Executing Contracts

Call contract methods that modify state

Executing Contracts

The xyz program execute command calls contract methods that modify state (like a transaction).

Usage

xyz program execute <contract> <message> --from <key> [options]

Arguments

Argument	Description
contract	Contract address
message	JSON message or @file.json

Basic Execution

xyz program execute xyz1contract... '{"increment":{}}' --from alice

Output:

Transaction Successful!

Contract: xyz1contract...
Method:   increment
TxHash:   ABC123DEF456...
Gas Used: 115678
Block:    12345

Message Formats

Inline JSON

xyz program execute xyz1contract... '{"increment":{}}' --from alice

With Parameters

xyz program execute xyz1contract... '{"reset":{"count":100}}' --from alice

From File

# Create message file
echo '{"transfer":{"recipient":"xyz1recipient...","amount":"1000"}}' > msg.json

# Execute from file
xyz program execute xyz1contract... @msg.json --from alice

Options

Flag	Description	Default
--from	Signing key	Required
--funds	Send funds with execution	None
--dry-run	Simulate only	false
--gas-buffer	Gas multiplier	1.3

Examples

Transfer Tokens (CW20)

xyz program execute xyz1tokencontract... \
  '{"transfer":{"recipient":"xyz1bob...","amount":"1000000"}}' \
  --from alice

Send with Funds

Some contracts require funds with execution:

xyz program execute xyz1escrowcontract... \
  '{"deposit":{}}' \
  --from alice \
  --funds 1000000uxyz

Batch Operations

xyz program execute xyz1contract... \
  '{"batch":{"operations":[{"increment":{}},{"increment":{}},{"increment":{}}]}}' \
  --from alice

Dry Run

Simulate without broadcasting:

xyz program execute xyz1contract... '{"increment":{}}' --from alice --dry-run

Output:

Dry run mode - transaction not broadcast

Estimated gas: 150,000
Estimated fee: 1,500 uxyz

Execute Details:
  Contract: xyz1contract...
  Message: {"increment":{}}
  Funds: 0

Message Examples

Simple Action

{"increment": {}}

With Parameters

{
  "transfer": {
    "recipient": "xyz1recipient...",
    "amount": "1000000"
  }
}

Nested Structure

{
  "create_order": {
    "order_type": "limit",
    "side": "buy",
    "price": "100",
    "quantity": "10"
  }
}

Multiple Actions (if supported)

{
  "batch": {
    "msgs": [
      {"increment": {}},
      {"set_owner": {"address": "xyz1new..."}}
    ]
  }
}

Authorization

Execute methods may have authorization requirements:

Public Methods

Anyone can call:

ExecuteMsg::Increment {} => { /* anyone */ }

Owner-Only Methods

ExecuteMsg::Reset { count } => {
    if info.sender != OWNER.load(deps.storage)? {
        return Err(ContractError::Unauthorized {});
    }
    // ...
}

Error when unauthorized:

Error: permission denied: only the contract owner can reset

Error Handling

The CLI provides user-friendly errors:

Chain Error	CLI Message
unauthorized	Permission denied: only the contract owner can…
insufficient funds	Insufficient balance to complete…
out of gas	Transaction requires more gas. Try increasing —gas

Complex JSON

For complex messages, use a file:

# Create complex message
cat > msg.json << 'EOF'
{
  "create_proposal": {
    "title": "Upgrade Protocol",
    "description": "This proposal upgrades the protocol to v2",
    "msgs": [
      {
        "wasm": {
          "execute": {
            "contract_addr": "xyz1other...",
            "msg": {"upgrade": {"version": "2.0.0"}},
            "funds": []
          }
        }
      }
    ]
  }
}
EOF

# Execute
xyz program execute xyz1governance... @msg.json --from alice

Scripting

Check Result

# Execute and capture tx hash
RESULT=$(xyz program execute xyz1contract... '{"increment":{}}' --from alice 2>&1)
TXHASH=$(echo "$RESULT" | grep "TxHash:" | awk '{print $2}')

echo "Transaction: $TXHASH"

Retry on Failure

#!/bin/bash
MAX_RETRIES=3
RETRY=0

while [ $RETRY -lt $MAX_RETRIES ]; do
  if xyz program execute xyz1contract... '{"increment":{}}' --from alice; then
    echo "Success!"
    exit 0
  fi
  RETRY=$((RETRY + 1))
  echo "Retry $RETRY/$MAX_RETRIES..."
  sleep 2
done

echo "Failed after $MAX_RETRIES retries"
exit 1

Troubleshooting

Invalid JSON

Validate your JSON:

echo '{"increment":{}}' | jq .

Contract not found

Verify contract exists:

xyz program info xyz1contract...

Unauthorized

Check method requirements:

• Are you the owner?
• Do you have the required role?

Out of gas

Increase gas buffer:

xyz program execute xyz1contract... '{"complex":{}}' \
  --from alice \
  --gas-buffer 2.0