CosmWasm Precompile

Address: 0x0000000000000000000000000000000000001002

Deprecation notice (Prop 115)Under governance Proposal 115, CosmWasm code uploads (MsgStoreCode) and contract instantiations (MsgInstantiateContract) are disabled chain-wide. The instantiate() function on this precompile reverts for all callers. Only calls to execute(), execute_batch(), and query() against pre-existing CosmWasm contracts still work. All CosmWasm functionality is deprecated in favor of EVM-only under SIP-3.The examples on this page attach only native SEI. Do not use the coins field to build IBC or tokenfactory integrations. IBC is disabled in both directions. Tokenfactory is not a supported development path.For new smart contract development, use the EVM directly. See Deploy a Smart Contract.

The Sei CosmWasm precompile lets EVM applications interact directly with pre-existing CosmWasm contracts through standard smart contract calls. You can call CosmWasm contracts directly from your dApps for execution, batch operations, and queries. You do not need a separate Cosmos SDK integration.

What is a precompile? A precompile is a special smart contract that the Sei protocol itself deploys at a fixed address. It exposes custom native chain logic to EVM-based applications. To the EVM, it behaves like a regular contract, but it executes privileged, low-level logic efficiently.

How does the CosmWasm precompile work?

The CosmWasm precompile at address 0x0000000000000000000000000000000000001002 exposes functions such as execute(), execute_batch(), and query().

EVM contracts and dApps can call CosmWasm functions directly, like any other smart contract method.
Operations run natively at the Cosmos SDK level for efficiency and security.
You do not need separate wallet integrations or complex cross-chain interactions.

What you’ll learn in this guide

After you finish this guide, you can:

Call CosmWasm contract functions and handle message formatting.
Run batch operations that execute multiple contract calls efficiently in a single transaction.
Query contract state to read CosmWasm contract data without gas costs.
Handle cross-runtime data by encoding and decoding messages between EVM and CosmWasm formats.

Functions

The CosmWasm precompile exposes these functions:

Transaction functions

Prop 115 disabled the instantiate() function, so calls to it revert. This reference omits it. The ABI in @sei-js/precompiles may still expose it for backward compatibility, but on-chain calls to it fail.

/// Executes some message on a CosmWasm contract.
/// @param contractAddress The Sei address of the contract to execute.
/// @param msg The msg to send for execution. The format is specified by the contract code.
/// @param coins A JSON-encoded coin list required by the legacy ABI.
/// @return response The execution response from the CosmWasm contract.
function execute(
    string memory contractAddress,
    bytes memory msg,
    bytes memory coins
) payable external returns (bytes memory response);

struct ExecuteMsg {
    string contractAddress;
    bytes msg;
    bytes coins;
}

/// Executes collection of messages on CosmWasm contracts.
/// @param executeMsgs Array of execution messages to process.
/// @return responses The execution responses collection from the CosmWasm contracts.
function execute_batch(
    ExecuteMsg[] memory executeMsgs
) payable external returns (bytes[] memory responses);

Query functions

/// Queries a CosmWasm contract.
/// @param contractAddress The Sei address of the contract to query.
/// @param req The query request object. The format is specified by the contract code.
/// @return response The response from the CosmWasm contract.
function query(
    string memory contractAddress,
    bytes memory req
) external view returns (bytes memory response);

Using the precompile

Setup

Prerequisites

Before you start, make sure that you have:

Node.js (v18 or higher)
The npm or yarn package manager
An EVM-compatible wallet
SEI tokens for gas and contract operations

Install dependencies

Install the required packages to interact with Sei precompiles:

# Install ethers.js for smart contract interactions
npm install ethers

# Install @sei-js/precompiles for precompile addresses and ABIs
npm install @sei-js/precompiles@^3

Import precompile components

// Import CosmWasm precompile address and ABI
// View the entire ABI here: https://github.com/sei-protocol/sei-chain/tree/main/precompiles/wasmd
import { WASM_PRECOMPILE_ABI, WASM_PRECOMPILE_ADDRESS } from '@sei-js/precompiles';
import { ethers } from 'ethers';

Precompile address: The CosmWasm precompile is deployed at 0x0000000000000000000000000000000000001002.

Contract initialization

Set up your provider, signer, and contract instance:

// Using EVM-compatible wallet as the signer and provider
const provider = new ethers.BrowserProvider(window.ethereum);
await provider.send('eth_requestAccounts', []);
const signer = await provider.getSigner();

// Create a contract instance for the CosmWasm precompile
const cosmwasm = new ethers.Contract(WASM_PRECOMPILE_ADDRESS, WASM_PRECOMPILE_ABI, signer);

Critical: Understanding message formats

CosmWasm message structure

The CosmWasm precompile requires JSON-encoded messages that match each contract’s own schema:

Function	Input/Output	Format type	Example
`execute()`	msg parameter (input)	JSON bytes	`ethers.toUtf8Bytes(jsonString)`
`query()`	req parameter (input)	JSON bytes	`ethers.toUtf8Bytes(jsonString)`
All functions	response (output)	JSON bytes	`JSON.parse(ethers.toUtf8String(response))`

How message encoding works

All CosmWasm functions require JSON-encoded byte arrays:

execute(): accepts the execution message as JSON bytes
query(): accepts the query message as JSON bytes

Native SEI handling:

Use msg.value for SEI amounts
Pass an empty JSON array for coins when the call does not require Bank Module funds

Best practice: Message encoding helpers

When you work with CosmWasm messages, use correct JSON encoding:

// Helper functions for message encoding
class CosmWasmMessageEncoder {
  // Encode execute message
  static encodeExecuteMsg(msg: object): Uint8Array {
    return ethers.toUtf8Bytes(JSON.stringify(msg));
  }

  // Encode query message
  static encodeQueryMsg(msg: object): Uint8Array {
    return ethers.toUtf8Bytes(JSON.stringify(msg));
  }

  // Decode response bytes to JSON
  static decodeResponse(responseBytes: Uint8Array): any {
    const jsonString = ethers.toUtf8String(responseBytes);
    return JSON.parse(jsonString);
  }
}

// Usage examples
const executeMsg = CosmWasmMessageEncoder.encodeExecuteMsg({
  transfer: {
    recipient: 'sei1...',
    amount: '1000000'
  }
});

const queryMsg = CosmWasmMessageEncoder.encodeQueryMsg({
  balance: { address: 'sei1...' }
});

Message format helpers

Use these helper functions to handle CosmWasm message formatting:

// Helper functions for CosmWasm message handling
class CosmWasmHelper {
  // Create execute message bytes
  static createExecuteMsg(msgObject: any): Uint8Array {
    return ethers.toUtf8Bytes(JSON.stringify(msgObject));
  }

  // Create query message bytes
  static createQueryMsg(msgObject: any): Uint8Array {
    return ethers.toUtf8Bytes(JSON.stringify(msgObject));
  }

  // Create the empty coin list used by these examples
  static emptyCoins(): Uint8Array {
    return ethers.toUtf8Bytes('[]');
  }

  // Parse response from CosmWasm contract
  static parseResponse(responseBytes: string | Uint8Array): any {
    try {
      const jsonString = typeof responseBytes === 'string' ? responseBytes : ethers.toUtf8String(responseBytes);
      return JSON.parse(jsonString);
    } catch (error) {
      console.error('Failed to parse CosmWasm response:', error);
      return null;
    }
  }
}

// Usage examples
const executeMsg = CosmWasmHelper.createExecuteMsg({
  mint: {
    recipient: 'sei1recipient...',
    amount: '1000000'
  }
});

const coins = CosmWasmHelper.emptyCoins();

Step-by-step guide: Using the CosmWasm precompile

Execute a CosmWasm contract

JavaScript
Solidity

// Execute a transfer on a CW20 token contract
const contractAddress = 'sei1contract...'; // Your CosmWasm contract address

// Create execute message for CW20 transfer
const executeMsg = CosmWasmHelper.createExecuteMsg({
  transfer: {
    recipient: 'sei1recipient...',
    amount: '1000000' // 1 token with 6 decimals
  }
});

// No additional coins needed for this execution
const coins = CosmWasmHelper.emptyCoins();

const tx = await cosmwasm.execute(contractAddress, executeMsg, coins);

const receipt = await tx.wait();
console.log('Transfer executed:', receipt);

// Parse the response if needed
const response = CosmWasmHelper.parseResponse(receipt.logs[0].data);
console.log('Execution response:', response);

contract CosmWasmExecutor {
    ICosmWasm constant COSMWASM = ICosmWasm(0x0000000000000000000000000000000000001002);

    event ContractExecuted(string contractAddress, bytes response);

    function executeContract(
        string memory contractAddress,
        bytes memory msg,
        bytes memory coins
    ) external payable {
        bytes memory response = COSMWASM.execute{value: msg.value}(
            contractAddress,
            msg,
            coins
        );

        emit ContractExecuted(contractAddress, response);
    }
}

Execute batch operations

JavaScript
Solidity

// Execute multiple operations in a single transaction
const contract1 = 'sei1contract1...';
const contract2 = 'sei1contract2...';

// Create multiple execute messages
const executeMsg1 = CosmWasmHelper.createExecuteMsg({
  transfer: {
    recipient: 'sei1recipient1...',
    amount: '500000'
  }
});

const executeMsg2 = CosmWasmHelper.createExecuteMsg({
  mint: {
    recipient: 'sei1recipient2...',
    amount: '1000000'
  }
});

// Create batch execution array
const executeMsgs = [
  {
    contractAddress: contract1,
    msg: executeMsg1,
    coins: CosmWasmHelper.emptyCoins()
  },
  {
    contractAddress: contract2,
    msg: executeMsg2,
    coins: CosmWasmHelper.emptyCoins()
  }
];

const tx = await cosmwasm.execute_batch(executeMsgs);
const receipt = await tx.wait();

console.log('Batch execution completed:', receipt);

contract BatchExecutor {
    ICosmWasm constant COSMWASM = ICosmWasm(0x0000000000000000000000000000000000001002);

    function executeBatch(
        ICosmWasm.ExecuteMsg[] memory executeMsgs
    ) external payable {
        bytes[] memory responses = COSMWASM.execute_batch{value: msg.value}(executeMsgs);

        // Process responses as needed
        for (uint i = 0; i < responses.length; i++) {
            // Handle each response
            emit BatchResponseReceived(i, responses[i]);
        }
    }

    event BatchResponseReceived(uint index, bytes response);
}

Query a CosmWasm contract

JavaScript
Solidity

// Query balance of a CW20 token
const contractAddress = 'sei1contract...';
const userAddress = 'sei1user...';

// Create query message
const queryMsg = CosmWasmHelper.createQueryMsg({
  balance: { address: userAddress }
});

try {
  const responseBytes = await cosmwasm.query(contractAddress, queryMsg);
  const response = CosmWasmHelper.parseResponse(responseBytes);

  console.log('User balance:', response.balance);

  // Query token info
  const tokenInfoMsg = CosmWasmHelper.createQueryMsg({ token_info: {} });
  const tokenInfoBytes = await cosmwasm.query(contractAddress, tokenInfoMsg);
  const tokenInfo = CosmWasmHelper.parseResponse(tokenInfoBytes);

  console.log('Token info:', {
    name: tokenInfo.name,
    symbol: tokenInfo.symbol,
    decimals: tokenInfo.decimals,
    total_supply: tokenInfo.total_supply
  });
} catch (error) {
  console.error('Query failed:', error);
}

contract CosmWasmQuery {
    ICosmWasm constant COSMWASM = ICosmWasm(0x0000000000000000000000000000000000001002);

    function queryContract(
        string memory contractAddress,
        bytes memory queryMsg
    ) external view returns (bytes memory) {
        return COSMWASM.query(contractAddress, queryMsg);
    }

    // Helper to query and decode in one call (requires additional parsing logic)
    function queryBalance(
        string memory contractAddress,
        string memory userAddress
    ) external view returns (bytes memory) {
        // This would require JSON parsing in Solidity, which is complex
        // Better to handle parsing off-chain
        bytes memory queryMsg = abi.encode('{"balance":{"address":"', userAddress, '"}}');
        return COSMWASM.query(contractAddress, queryMsg);
    }
}

Query limitations: Consider parsing responses off-chain. CosmWasm queries are read-only operations and do not consume gas. However, parsing JSON responses in Solidity is complex.

Advanced usage examples

Cross-runtime DeFi integration

async function crossRuntimeDeFiOperation(cosmwasmDexContract: string, evmTokenContract: string, amount: string) {
  try {
    // 1. Execute swap on CosmWasm DEX
    const swapMsg = CosmWasmHelper.createExecuteMsg({
      swap: {
        offer_asset: {
          info: { native_token: { denom: 'usei' } },
          amount: amount
        },
        belief_price: '1.0'
      }
    });

    const swapTx = await cosmwasm.execute(cosmwasmDexContract, swapMsg, CosmWasmHelper.emptyCoins(), { value: ethers.parseEther(amount) });

    await swapTx.wait();
    console.log('CosmWasm swap completed');

    // 2. Query swap result
    const balanceMsg = CosmWasmHelper.createQueryMsg({
      balance: { address: await signer.getAddress() }
    });

    const balanceResponse = await cosmwasm.query(cosmwasmDexContract, balanceMsg);
    const balance = CosmWasmHelper.parseResponse(balanceResponse);

    console.log('New balance after swap:', balance);

    return balance;
  } catch (error) {
    console.error('Cross-runtime operation failed:', error);
    throw error;
  }
}

Complete integration example

JavaScript
Solidity

async function cosmwasmExample() {
  // Setup
  const provider = new ethers.BrowserProvider(window.ethereum);
  await provider.send('eth_requestAccounts', []);
  const signer = await provider.getSigner();
  const cosmwasm = new ethers.Contract(WASM_PRECOMPILE_ADDRESS, WASM_PRECOMPILE_ABI, signer);

  const userAddress = await signer.getAddress();

  // Replace with the address of an existing CosmWasm contract you want to interact with.
  const contractAddress = 'sei1contract...';

  try {
    // 1. Execute mint operation against an existing contract
    console.log('=== Minting Tokens ===');
    const mintMsg = CosmWasmHelper.createExecuteMsg({
      mint: {
        recipient: 'sei1recipient...',
        amount: '1000000000' // 1000 tokens
      }
    });

    const mintTx = await cosmwasm.execute(contractAddress, mintMsg, CosmWasmHelper.emptyCoins());
    await mintTx.wait();
    console.log('Tokens minted successfully');

    // 2. Query token information
    console.log('=== Querying Token Info ===');
    const tokenInfoMsg = CosmWasmHelper.createQueryMsg({ token_info: {} });
    const tokenInfoBytes = await cosmwasm.query(contractAddress, tokenInfoMsg);
    const tokenInfo = CosmWasmHelper.parseResponse(tokenInfoBytes);

    console.log('Token Info:', {
      name: tokenInfo.name,
      symbol: tokenInfo.symbol,
      decimals: tokenInfo.decimals,
      total_supply: tokenInfo.total_supply
    });

    // 3. Query user balance
    const balanceMsg = CosmWasmHelper.createQueryMsg({
      balance: { address: 'sei1recipient...' }
    });
    const balanceBytes = await cosmwasm.query(contractAddress, balanceMsg);
    const balance = CosmWasmHelper.parseResponse(balanceBytes);

    console.log('User balance:', balance.balance);

    // 4. Execute batch transfer
    console.log('=== Batch Transfer ===');
    const batchMsgs = [
      {
        contractAddress: contractAddress,
        msg: CosmWasmHelper.createExecuteMsg({
          transfer: {
            recipient: 'sei1addr1...',
            amount: '100000000' // 100 tokens
          }
        }),
        coins: CosmWasmHelper.emptyCoins()
      },
      {
        contractAddress: contractAddress,
        msg: CosmWasmHelper.createExecuteMsg({
          transfer: {
            recipient: 'sei1addr2...',
            amount: '200000000' // 200 tokens
          }
        }),
        coins: CosmWasmHelper.emptyCoins()
      }
    ];

    const batchTx = await cosmwasm.execute_batch(batchMsgs);
    await batchTx.wait();
    console.log('Batch transfer completed');
  } catch (error) {
    console.error('CosmWasm operation failed:', error);
  }
}

Contract example

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

interface ICosmWasmPrecompile {
    struct ExecuteMsg {
        string contractAddress;
        bytes msg;
        bytes coins;
    }

    function execute(
        string memory contractAddress,
        bytes memory msg,
        bytes memory coins
    ) payable external returns (bytes memory response);

    function execute_batch(
        ExecuteMsg[] memory executeMsgs
    ) payable external returns (bytes[] memory responses);

    function query(
        string memory contractAddress,
        bytes memory req
    ) external view returns (bytes memory response);
}

contract CosmWasmBridge {
    ICosmWasmPrecompile constant COSMWASM = ICosmWasmPrecompile(0x0000000000000000000000000000000000001002);

    event ContractExecuted(string contractAddress, bytes response);
    event BatchExecuted(uint256 msgCount);
    event QueryExecuted(string contractAddress, bytes response);

    // Execute a message on a CosmWasm contract
    function executeContract(
        string memory contractAddress,
        bytes memory executeMsg,
        bytes memory coins
    ) external payable returns (bytes memory) {
        bytes memory response = COSMWASM.execute{value: msg.value}(
            contractAddress,
            executeMsg,
            coins
        );

        emit ContractExecuted(contractAddress, response);
        return response;
    }

    // Execute multiple messages in batch
    function executeBatch(
        ICosmWasmPrecompile.ExecuteMsg[] memory executeMsgs
    ) external payable returns (bytes[] memory) {
        bytes[] memory responses = COSMWASM.execute_batch{value: msg.value}(executeMsgs);

        emit BatchExecuted(executeMsgs.length);
        return responses;
    }

    // Query a CosmWasm contract
    function queryContract(
        string memory contractAddress,
        bytes memory queryMsg
    ) external view returns (bytes memory) {
        bytes memory response = COSMWASM.query(contractAddress, queryMsg);

        // Note: Cannot emit events in view functions
        return response;
    }

    // Helper function to create execute message struct
    function createExecuteMsg(
        string memory contractAddress,
        bytes memory msg,
        bytes memory coins
    ) public pure returns (ICosmWasmPrecompile.ExecuteMsg memory) {
        return ICosmWasmPrecompile.ExecuteMsg({
            contractAddress: contractAddress,
            msg: msg,
            coins: coins
        });
    }
}

This contract is a bridge between the EVM and existing CosmWasm contracts. For complex operations, handle message encoding and decoding client-side.

Client integration example

import { network } from 'hardhat';

// Hardhat 3 exposes ethers through a network connection rather than a global import
const { ethers } = await network.create();

async function main() {
  const [deployer] = await ethers.getSigners();
  console.log('Deploying contracts with the account:', deployer.address);

  const CosmWasmBridge = await ethers.getContractFactory('CosmWasmBridge');
  console.log('Deploying CosmWasmBridge...');
  const bridge = await CosmWasmBridge.deploy();

  await bridge.waitForDeployment();
  console.log('CosmWasmBridge deployed to:', await bridge.getAddress());

  // Address of an existing CosmWasm contract you want to interact with
  const contractAddress = 'sei1contract...';

  // Encode an execute message (e.g., a CW20 transfer)
  const executeMsg = ethers.toUtf8Bytes(
    JSON.stringify({
      transfer: {
        recipient: 'sei1recipient...',
        amount: '1000000'
      }
    })
  );

  const coins = ethers.toUtf8Bytes('[]');

  const tx = await bridge.executeContract(contractAddress, executeMsg, coins);
  const receipt = await tx.wait();

  console.log('Execute transaction hash:', tx.hash);

  const event = receipt.logs.find((log) => log.topics[0] === ethers.id('ContractExecuted(string,bytes)'));

  if (event) {
    console.log('CosmWasm execute call confirmed');
  }
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Troubleshooting

Common issues and solutions

Message encoding issues

// Ensure proper JSON encoding for messages
const msg = {
  transfer: {
    recipient: 'sei1...',
    amount: '1000000' // Use strings for large numbers
  }
};

// Correct encoding
const encodedMsg = ethers.toUtf8Bytes(JSON.stringify(msg));

// Incorrect - will cause parsing errors
const incorrectMsg = ethers.toUtf8Bytes('invalid json');

Error code reference

Error	Cause	Solution
`invalid json`	Malformed JSON message	Validate the JSON before encoding
`contract not found`	Invalid contract address	Verify the contract address format
`insufficient funds`	Not enough tokens for the operation	Check the balance and reduce the amount
`execution failed`	Contract execution error	Check the contract state and parameters
`unauthorized`	Insufficient permissions	Check admin/owner permissions
`query parsing failed`	Invalid query message format	Match the contract’s query schema

Important notes

All CosmWasm messages must be correctly JSON-encoded as bytes. Contract schemas vary by implementation.

Message format requirements

JSON encoding: All messages must be valid JSON, encoded as UTF-8 bytes. Invalid JSON causes transaction failures.
Schema compliance: Messages must match the contract’s expected format.
Type safety: Use the data types that the contract expects.

Contract address format

Use valid Sei contract addresses with the sei1... prefix.
These are Cosmos-format addresses, not EVM addresses.
Contract existence: Verify that contracts exist before you call them.

Cross-runtime considerations

State isolation: CosmWasm and EVM contracts have separate state.
Gas estimation: CosmWasm operations may require different gas calculations.
Error handling: Failed CosmWasm operations revert the entire EVM transaction.
Native SEI handling: Use msg.value for SEI and leave the coins list empty.
Batch limitations: Large batches may reach gas limits.

Best practices

Always validate JSON messages before you send them.
Parse responses carefully, especially for complex data structures.
Use batch operations for multiple related calls to save gas.
When possible, query contracts to verify their state before you execute calls on them.

View the CosmWasm precompile source code and contract ABI.

​How does the CosmWasm precompile work?

​What you’ll learn in this guide

​Functions

​Transaction functions

​Query functions

​Using the precompile

​Setup

​Prerequisites

​Install dependencies

​Import precompile components

​Contract initialization

​Critical: Understanding message formats

​CosmWasm message structure

​How message encoding works

​Best practice: Message encoding helpers

​Message format helpers

​Step-by-step guide: Using the CosmWasm precompile

​Execute a CosmWasm contract

​Execute batch operations

​Query a CosmWasm contract

​Advanced usage examples

​Cross-runtime DeFi integration

​Complete integration example

​Troubleshooting

​Common issues and solutions

​Message encoding issues

​Error code reference

​Important notes

​Message format requirements

​Contract address format

​Cross-runtime considerations

​Best practices

How does the CosmWasm precompile work?

What you’ll learn in this guide

Functions

Transaction functions

Query functions

Using the precompile

Setup

Prerequisites

Install dependencies

Import precompile components

Contract initialization

Critical: Understanding message formats

CosmWasm message structure

How message encoding works

Best practice: Message encoding helpers

Message format helpers

Step-by-step guide: Using the CosmWasm precompile

Execute a CosmWasm contract

Execute batch operations

Query a CosmWasm contract

Advanced usage examples

Cross-runtime DeFi integration

Complete integration example

Troubleshooting

Common issues and solutions

Message encoding issues

Error code reference

Important notes

Message format requirements

Contract address format

Cross-runtime considerations

Best practices