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

Output

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

Output

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

Flag	Description	Default
`--local`	Use local cargo instead of Docker	false
`--output`	Output directory	`artifacts/`

Output Location

Docker Build

artifacts/my_contract.wasm

Local Build

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

Size Comparison

Build Method	Typical 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

Docker not found

Install Docker from https://docker.com or use local build:

xyz program build --local

Cargo.toml not found

Run the command from your project root:

cd my-contract
xyz program build

wasm32 target not installed

Install the Wasm target:

rustup target add wasm32-unknown-unknown

Build fails with errors

Check your Rust code compiles:

cargo check

Fix any errors before building for Wasm.

Contract too large

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"

Getting Started

Chain

Products

Developer Tools

Token Operations

Smart Contracts

Local Development

Chain API

Launchpad API

Building Contracts

Building Contracts

Usage

Build Methods

Docker Build (Default)

Local Build

Options

Output Location

Docker Build

Local Build

Size Comparison

Build Process

Docker Build Flow

Local Build Flow

Development Workflow

Fast Iteration (Local)

Production (Docker)

Troubleshooting

Verifying Builds

Check File Size

Verify Wasm Format

Check Code Hash

CI/CD Integration

GitHub Actions

Next Steps

​Building Contracts

​Usage

​Build Methods

​Docker Build (Default)

​Local Build

​Options

​Output Location

​Docker Build

​Local Build

​Size Comparison

​Build Process

​Docker Build Flow

​Local Build Flow

​Development Workflow

​Fast Iteration (Local)

​Production (Docker)

​Troubleshooting

​Verifying Builds

​Check File Size

​Verify Wasm Format

​Check Code Hash

​CI/CD Integration

​GitHub Actions

​Next Steps

Building Contracts

Usage

Build Methods

Docker Build (Default)

Local Build

Options

Output Location

Docker Build

Local Build

Size Comparison

Build Process

Docker Build Flow

Local Build Flow

Development Workflow

Fast Iteration (Local)

Production (Docker)

Troubleshooting

Verifying Builds

Check File Size

Verify Wasm Format

Check Code Hash

CI/CD Integration

GitHub Actions

Next Steps