Skip to main content

​
Building Contracts

The xyz program build command compiles your Rust contract to optimized WebAssembly (Wasm).

​
Usage

xyz program build [options]
Run this command from your contract project directory (where Cargo.toml is located).

​
Build Methods

​
Docker Build (Default)

Uses the official CosmWasm optimizer for reproducible builds: 
xyz program build

Building contract with cosmwasm/optimizer:0.16.0...

Building crates for wasm target...
Creating intermediate artifacts...
Post-processing artifacts...
Optimizing artifacts...

Optimized:
  my_contract.wasm (185 KB)

Output: artifacts/my_contract.wasm
Advantages:
  • Reproducible builds (same output every time)
  • Optimized for size
  • Production-ready
Requirements:
  • Docker installed and running

​
Local Build

Uses your local Rust toolchain: 
xyz program build --local

Building with local cargo...

   Compiling my-contract v0.1.0 (/path/to/my-contract)
    Finished release [optimized] target(s) in 12.34s

Output: target/wasm32-unknown-unknown/release/my_contract.wasm (450 KB)
Advantages:
  • Faster iteration
  • No Docker required
Disadvantages:
  • Larger file size
  • Not reproducible
Requirements:
  • Rust with wasm32-unknown-unknown target: 
    rustup target add wasm32-unknown-unknown

​
Options

FlagDescriptionDefault
--localUse local cargo instead of Dockerfalse
--outputOutput directoryartifacts/

​
Output Location

​
Docker Build

artifacts/my_contract.wasm

​
Local Build

target/wasm32-unknown-unknown/release/my_contract.wasm

​
Size Comparison

Build MethodTypical Size
Docker (optimized)150-200 KB
Local (unoptimized)400-600 KB
XYZ Chain has a maximum contract size of 800 KB. Both methods typically produce contracts well under this limit.

​
Build Process

​
Docker Build Flow

┌─────────────────┐
│   Source Code   │
│   (src/*.rs)    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ cosmwasm/       │
│ optimizer:0.16.0│
│ (Docker)        │
└────────┬────────┘
         │
    ┌────┴────┐
    │         │
    ▼         ▼
┌───────┐ ┌───────┐
│ Build │ │Optimize│
│ Wasm  │ │ Size   │
└───┬───┘ └───┬───┘
    │         │
    └────┬────┘
         │
         ▼
┌─────────────────┐
│artifacts/       │
│my_contract.wasm │
│    (optimized)  │
└─────────────────┘

​
Local Build Flow

┌─────────────────┐
│   Source Code   │
│   (src/*.rs)    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ cargo build     │
│ --release       │
│ --target wasm32 │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│target/wasm32.../│
│my_contract.wasm │
│  (unoptimized)  │
└─────────────────┘

​
Development Workflow

​
Fast Iteration (Local)

For quick development cycles: 
# Build locally (faster)
xyz program build --local

# Deploy to local network
xyz program deploy target/wasm32-unknown-unknown/release/my_contract.wasm --from alice

​
Production (Docker)

For deployments: 
# Build with optimizer (reproducible)
xyz program build

# Deploy
xyz program deploy artifacts/my_contract.wasm --from alice

​
Troubleshooting

Install Docker from https://docker.com or use local build:
xyz program build --local
Run the command from your project root:
cd my-contract
xyz program build
Install the Wasm target:
rustup target add wasm32-unknown-unknown
Check your Rust code compiles:
cargo check
Fix any errors before building for Wasm.
  • Use Docker build (smaller output)
  • Remove unused dependencies
  • Optimize code for size

​
Verifying Builds

​
Check File Size

ls -lh artifacts/my_contract.wasm
# -rw-r--r-- 1 user staff 185K Jan 29 10:00 my_contract.wasm

​
Verify Wasm Format

file artifacts/my_contract.wasm
# artifacts/my_contract.wasm: WebAssembly (wasm) binary module version 0x1 (MVP)

​
Check Code Hash

For reproducible builds, verify the hash: 
sha256sum artifacts/my_contract.wasm
# abc123def456... artifacts/my_contract.wasm

​
CI/CD Integration

​
GitHub Actions

name: Build Contract
on: push

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Build with optimizer
        run: |
          docker run --rm -v "$(pwd)":/code \
            --mount type=volume,source="$(basename "$(pwd)")_cache",target=/code/target \
            --mount type=volume,source=registry_cache,target=/usr/local/cargo/registry \
            cosmwasm/optimizer:0.16.0

      - name: Upload artifact
        uses: actions/upload-artifact@v3
        with:
          name: contract
          path: artifacts/my_contract.wasm

​
Next Steps

After building: 
# Deploy to local network
xyz program deploy artifacts/my_contract.wasm --from alice --label "My Contract"