Contract Tools

Contract Tools

These tools enable comprehensive interaction with smart contracts on the Somnia blockchain, including reading data, writing to contracts, deploying new contracts, and analyzing contract behavior.

read_contract

Reads data from a smart contract by calling view/pure functions.

Parameters:

• network (optional): Network name or chain ID (defaults to Somnia testnet)
• contractAddress: The smart contract address to interact with
• abi: The contract ABI as a JSON array
• functionName: The function to call (e.g., ‘balanceOf’)
• args (optional): Arguments for the function call as an array

Example:

{
  "network": "Somnia Testnet",
  "contractAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
  "abi": [
    {
      "inputs": [{"name": "owner", "type": "address"}],
      "name": "balanceOf",
      "outputs": [{"name": "", "type": "uint256"}],
      "stateMutability": "view",
      "type": "function"
    }
  ],
  "functionName": "balanceOf",
  "args": ["0x1234567890123456789012345678901234567890"]
}

Response: Returns the result of the contract function call.

Example Prompt:

Read the balanceOf function from contract 0xabcdef1234567890abcdef1234567890abcdef12 for address 0x1234567890123456789012345678901234567890.

write_contract

Executes a state-changing function on a smart contract. This will modify the blockchain state and requires gas fees and transaction signing.

Parameters:

• network (optional): Network name or chain ID (defaults to Somnia testnet)
• contractAddress: The smart contract address to interact with
• abi: The contract ABI as a JSON array
• functionName: The function to call (e.g., ‘transfer’)
• args (optional): Arguments for the function call as an array

Example:

{
  "network": "Somnia Testnet",
  "contractAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
  "abi": [
    {
      "inputs": [
        {"name": "to", "type": "address"},
        {"name": "amount", "type": "uint256"}
      ],
      "name": "transfer",
      "stateMutability": "nonpayable",
      "type": "function"
    }
  ],
  "functionName": "transfer",
  "args": ["0x1234567890123456789012345678901234567890", "1000000000000000000"]
}

Response: Returns success status and transaction hash.

Example Prompt:

Call the transfer function on contract 0xabcdef1234567890abcdef1234567890abcdef12 to send 1 token to 0x1234567890123456789012345678901234567890.

deploy_contract

Deploys a new smart contract to the blockchain. Requires compiled bytecode and constructor arguments.

Parameters:

• network (optional): Network name or chain ID (defaults to Somnia testnet)
• bytecode: The compiled contract bytecode as hex string
• abi: The contract ABI as a JSON array
• args (optional): Constructor arguments as an array

Example:

{
  "network": "Somnia Testnet",
  "bytecode": "0x608060405234801561001057600080fd5b50d3801561001d57600080fd5b50d2801561002a57600080fd5b5060c0806100386000396000f3fe6080604052348015600f57600080fd5b506004361060285760003560e01c8063771602f714602d575b600080fd5b60336035565b005b600080905090565b9091019056fe",
  "abi": [
    {
      "inputs": [],
      "stateMutability": "nonpayable",
      "type": "constructor"
    }
  ],
  "args": []
}

Response: Returns contract address and transaction hash.

Example Prompt:

Deploy a new contract with bytecode 0x608060405234801561001057600080fd5b50d3801561001d57600080fd5b50d2801561002a57600080fd5b5060c0806100386000396000f3fe6080604052348015600f57600080fd5b506004361060285760003560e01c8063771602f714602d575b600080fd5b60336035565b005b600080905090565b9091019056fe.

simulate_contract_call

Simulates a contract function call without executing it on the blockchain. Useful for testing and debugging.

Parameters:

• network (optional): Network name or chain ID (defaults to Somnia testnet)
• contractAddress: The contract address to simulate call on
• abi: The contract ABI as a JSON array
• functionName: The function to simulate
• args (optional): Function arguments as an array

Example:

{
  "network": "Somnia Testnet",
  "contractAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
  "abi": [
    {
      "inputs": [{"name": "owner", "type": "address"}],
      "name": "balanceOf",
      "outputs": [{"name": "", "type": "uint256"}],
      "stateMutability": "view",
      "type": "function"
    }
  ],
  "functionName": "balanceOf",
  "args": ["0x1234567890123456789012345678901234567890"]
}

Response: Returns the simulated result.

Example Prompt:

Simulate calling balanceOf on contract 0xabcdef1234567890abcdef1234567890abcdef12.

estimate_contract_gas

Estimates the gas required for a contract function call.

Parameters:

• network (optional): Network name or chain ID (defaults to Somnia testnet)
• contractAddress: The contract address
• abi: The contract ABI as a JSON array
• functionName: The function to estimate gas for
• args (optional): Arguments for the function call as an array
• from (optional): The sender address
• value (optional): The value to send with the call in wei

Example:

{
  "network": "Somnia Testnet",
  "contractAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
  "abi": [
    {
      "inputs": [
        {"name": "to", "type": "address"},
        {"name": "amount", "type": "uint256"}
      ],
      "name": "transfer",
      "stateMutability": "nonpayable",
      "type": "function"
    }
  ],
  "functionName": "transfer",
  "args": ["0x1234567890123456789012345678901234567890", "1000000000000000000"]
}

Response: Returns the estimated gas amount.

Example Prompt:

Estimate gas for calling transfer on contract 0xabcdef1234567890abcdef1234567890abcdef12.

get_contract_events

Gets historical events/logs from a smart contract within specified block range.

Parameters:

• network (optional): Network name or chain ID (defaults to Somnia testnet)
• contractAddress: The contract address to get events from
• abi (optional): The contract ABI as a JSON array
• eventName (optional): Specific event name to filter
• fromBlock (optional): Starting block number for event search
• toBlock (optional): Ending block number for event search

Example:

{
  "network": "Somnia Testnet",
  "contractAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
  "eventName": "Transfer",
  "fromBlock": 1000000,
  "toBlock": 1001000
}

Response: Returns array of event logs with simplified format.

Example Prompt:

Get Transfer events from contract 0xabcdef1234567890abcdef1234567890abcdef12 between blocks 1000000 and 1001000.

multicall_contract

Executes multiple contract calls in a single transaction using multicall.

Parameters:

• network (optional): Network name or chain ID (defaults to Somnia testnet)
• calls: Array of contract calls to execute

Example:

{
  "network": "Somnia Testnet",
  "calls": [
    {
      "target": "0xabcdef1234567890abcdef1234567890abcdef12",
      "callData": "0x70a082310000000000000000000000001234567890123456789012345678901234567890"
    },
    {
      "target": "0xabcdef1234567890abcdef1234567890abcdef12",
      "callData": "0x70a082310000000000000000000000009876543210987654321098765432109876543210"
    }
  ]
}

Response: Returns multicall results with block number and return data.

Example Prompt:

Execute multiple calls on contract 0xabcdef1234567890abcdef1234567890abcdef12.

multicall_contract_3

Executes multiple contract calls with individual success/failure status using multicall3.

Parameters:

• network (optional): Network name or chain ID (defaults to Somnia testnet)
• calls: Array of contract calls with optional value

Example:

{
  "network": "Somnia Testnet",
  "calls": [
    {
      "target": "0xabcdef1234567890abcdef1234567890abcdef12",
      "callData": "0x70a082310000000000000000000000001234567890123456789012345678901234567890",
      "value": "0"
    }
  ]
}

Response: Returns results with individual success/failure status.

Example Prompt:

Execute multiple calls with multicall3 on contract 0xabcdef1234567890abcdef1234567890abcdef12.

verify_contract

Checks contract verification status or submits contract for verification on the blockchain explorer.

Parameters:

• network (optional): Network name or chain ID (defaults to Somnia testnet)
• contractAddress: Contract address to verify
• action: Action to perform (‘check’ or ‘verify’)
• sourceCode (required for verify): Contract source code
• contractName (required for verify): Contract name
• compilerVersion (required for verify): Compiler version
• optimization (optional): Whether optimization was used
• constructorArguments (optional): Constructor arguments as hex
• license (optional): Contract license type

Example:

{
  "network": "Somnia Testnet",
  "contractAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
  "action": "check"
}

Response: Returns verification status and contract information.

Example Prompt:

Check if contract 0xabcdef1234567890abcdef1234567890abcdef12 is verified.

get_contract_source

Gets the source code of a smart contract from the blockchain explorer.

Parameters:

• network (optional): Network name or chain ID (defaults to Somnia testnet)
• contractAddress: Contract address to get source code for

Example:

{
  "network": "Somnia Testnet",
  "contractAddress": "0xabcdef1234567890abcdef1234567890abcdef12"
}

Response: Returns contract source code and metadata if verified.

Example Prompt:

Get the source code of contract 0xabcdef1234567890abcdef1234567890abcdef12.

get_contract_bytecode

Gets the deployed bytecode of a smart contract using Viem.

Parameters:

• network (optional): Network name or chain ID (defaults to Somnia testnet)
• contractAddress: Contract address to get bytecode for

Example:

{
  "network": "Somnia Testnet",
  "contractAddress": "0xabcdef1234567890abcdef1234567890abcdef12"
}

Response: Returns bytecode and contract information.

Example Prompt:

Get the bytecode of contract 0xabcdef1234567890abcdef1234567890abcdef12.

batch_write_contract

Executes multiple contract write operations in batch.

Parameters:

• network (optional): Network name or chain ID (defaults to Somnia testnet)
• operations: Array of contract operations to execute in batch
• continueOnError (optional): Whether to continue with remaining operations if one fails

Example:

{
  "network": "Somnia Testnet",
  "operations": [
    {
      "contractAddress": "0xabcdef1234567890abcdef1234567890abcdef12",
      "abi": [...],
      "functionName": "transfer",
      "args": ["0x1234567890123456789012345678901234567890", "1000000000000000000"]
    }
  ],
  "continueOnError": true
}

Response: Returns batch execution results with success/failure status for each operation.

Example Prompt:

Execute multiple write operations on contracts.

get_contract_abi

Gets the ABI (Application Binary Interface) of a smart contract.

Parameters:

• network (optional): Network name or chain ID (defaults to Somnia testnet)
• contractAddress: Contract address to get ABI for

Example:

{
  "network": "Somnia Testnet",
  "contractAddress": "0xabcdef1234567890abcdef1234567890abcdef12"
}

Response: Returns ABI and contract metadata.

Example Prompt:

Get the ABI of contract 0xabcdef1234567890abcdef1234567890abcdef12.

is_contract

Checks if an address is a smart contract.

Parameters:

• network (optional): Network name or chain ID (defaults to Somnia testnet)
• address: The address to check

Example:

{
  "network": "Somnia Testnet",
  "address": "0xabcdef1234567890abcdef1234567890abcdef12"
}

Response: Returns whether the address is a contract and a descriptive message.

Example Prompt:

Is address 0xabcdef1234567890abcdef1234567890abcdef12 a smart contract?

Usage Notes

Reading Contracts

• Only view/pure functions can be called (no state changes)
• ABI must be provided in valid JSON format
• Arguments must match the function signature
• Returns raw blockchain data (may need formatting)

Writing Contracts

• Requires private key in environment variables
• Modifies blockchain state and costs gas
• Transaction will be signed and broadcasted

Contract Deployment

• Requires compiled bytecode
• Constructor arguments must match contract constructor
• Returns contract address after successful deployment

Multicall Operations

• Executes multiple calls in single transaction
• More gas efficient than individual calls
• Multicall3 provides individual success/failure status

Contract Verification

• Check if contract is already verified
• Submit for verification with source code
• Requires all compilation parameters

Error Handling

Contract tools may return errors if:

• Contract address is invalid
• ABI format is incorrect
• Function name doesn’t exist in the contract
• Arguments don’t match function signature
• Contract call reverts or fails
• Network connection issues
• Insufficient funds for write operations
• Private key not configured for write operations