Skip to content

legacy-full.md

Latest commit

 

History

History
281 lines (204 loc) · 7.11 KB

legacy-full.md

File metadata and controls

281 lines (204 loc) · 7.11 KB
Raw
name cairo-toolchain-legacy-full
description Deployment and operational reference for Cairo contracts with sncast and Starknet Foundry.

Cairo Toolchain

Reference for deploying Cairo smart contracts to Starknet using sncast (Starknet Foundry).

When to Use

  • Deploying contracts to Starknet devnet, Sepolia, or mainnet
  • Declaring contract classes
  • Setting up deployer accounts
  • Configuring network endpoints
  • Verifying deployed contracts
  • Invoking/calling deployed contracts

When NOT to Use

Not for: Writing contracts (use cairo-contract-authoring), testing (use cairo-testing), optimization (use cairo-optimization)

Setup

Install Starknet Foundry

# Install via asdf (recommended for version pinning)
asdf plugin add starknet-foundry
asdf install starknet-foundry 0.57.0
asdf global starknet-foundry 0.57.0

.tool-versions

Pin versions for reproducible builds:

scarb 2.16.1
starknet-foundry 0.57.0

Note: Starknet Foundry 0.57.0 requires Scarb >= 2.14.0 (recommended: 2.16.x). Check github.com/foundry-rs/starknet-foundry/releases for the latest.

Build

# Build contracts (generates Sierra + CASM)
scarb build

Output goes to target/dev/:

  • myproject_MyContract.contract_class.json (Sierra)
  • myproject_MyContract.compiled_contract_class.json (CASM)

Account Setup

Create a New Account

# Generate account on Sepolia
sncast account create \
    --url https://starknet-sepolia.g.alchemy.com/v2/YOUR_KEY \
    --name my-deployer

# This outputs the account address — fund it with ETH/STRK before deploying

# Deploy the account contract
sncast account deploy \
    --url https://starknet-sepolia.g.alchemy.com/v2/YOUR_KEY \
    --name my-deployer

Import Existing Account

⚠️ Never hard-code a real private key in shell history or scripts. Use an environment variable or keystore-backed flow.

sncast account import \
    --url https://starknet-sepolia.g.alchemy.com/v2/YOUR_KEY \
    --name my-deployer \
    --address 0x123... \
    --private-key "$DEPLOYER_PRIVATE_KEY" \
    --type oz

Account types: oz (OpenZeppelin), argent, braavos

sncast.toml

Configure defaults to avoid repeating flags:

[default]
url = "https://starknet-sepolia.g.alchemy.com/v2/YOUR_KEY"
account = "my-deployer"
accounts-file = "~/.starknet_accounts/starknet_open_zeppelin_accounts.json"
wait = true

[mainnet]
url = "https://starknet-mainnet.g.alchemy.com/v2/YOUR_KEY"
account = "mainnet-deployer"

Use profiles: sncast --profile mainnet declare ...

Declare (Register Class)

Before deploying, declare the contract class on-chain:

# Declare contract
sncast declare \
    --contract-name MyContract

# Output:
# class_hash: 0x1234...
# transaction_hash: 0xabcd...

If the class is already declared, sncast will tell you — that's fine, use the existing class hash.

Deploy (Create Instance)

# Deploy with constructor args
sncast deploy \
    --class-hash 0x1234... \
    --constructor-calldata 0xOWNER_ADDRESS

# Multiple constructor args (space-separated)
sncast deploy \
    --class-hash 0x1234... \
    --constructor-calldata 0xOWNER 0xTOKEN_ADDRESS 1000

Constructor Calldata Encoding

Arguments are passed as felt252 values:

  • ContractAddress — pass as hex 0x123...
  • u256 — pass as TWO felts: low high (e.g., 1000 0 for 1000)
  • felt252 — pass directly
  • bool — 1 for true, 0 for false
  • ByteArray (strings) — use sncast's string encoding or pass raw

Invoke (Write)

# Call a write function
sncast invoke \
    --contract-address 0xCONTRACT \
    --function "transfer" \
    --calldata 0xRECIPIENT 1000 0

Call (Read)

# Call a view function (free, no tx)
sncast call \
    --contract-address 0xCONTRACT \
    --function "get_balance" \
    --calldata 0xACCOUNT

Multicall

Execute multiple calls in a single transaction:

# Create a multicall file
cat > multicall.toml << 'EOF'
[[call]]
call_type = "deploy"
class_hash = "0x1234..."
inputs = ["0xOWNER"]

[[call]]
call_type = "invoke"
contract_address = "0xTOKEN"
function = "approve"
inputs = ["0xSPENDER", "1000", "0"]
EOF

sncast multicall run --path multicall.toml

Deploy Script Pattern

For complex deployments, use a script:

#!/bin/bash
set -euo pipefail

RPC_URL="https://starknet-sepolia.g.alchemy.com/v2/YOUR_KEY"
ACCOUNT="my-deployer"

echo "Building..."
scarb build

echo "Declaring MyToken..."
TOKEN_CLASS=$(sncast --json declare --contract-name MyToken --url "$RPC_URL" --account "$ACCOUNT" | jq -r '.class_hash')
echo "Token class: $TOKEN_CLASS"

echo "Deploying MyToken..."
TOKEN_ADDR=$(sncast --json deploy --class-hash "$TOKEN_CLASS" --constructor-calldata 0xOWNER --url "$RPC_URL" --account "$ACCOUNT" | jq -r '.contract_address')
echo "Token deployed at: $TOKEN_ADDR"

echo "Declaring AMM..."
AMM_CLASS=$(sncast --json declare --contract-name AMM --url "$RPC_URL" --account "$ACCOUNT" | jq -r '.class_hash')

echo "Deploying AMM..."
AMM_ADDR=$(sncast --json deploy --class-hash "$AMM_CLASS" --constructor-calldata "$TOKEN_ADDR" --url "$RPC_URL" --account "$ACCOUNT" | jq -r '.contract_address')
echo "AMM deployed at: $AMM_ADDR"

echo "Done. Addresses:"
echo "  Token: $TOKEN_ADDR"
echo "  AMM:   $AMM_ADDR"

Note: Script above assumes jq is installed for JSON parsing.

Network Endpoints

Network RPC URL
Devnet (local) http://localhost:5050
Sepolia (testnet) https://starknet-sepolia.g.alchemy.com/v2/KEY
Mainnet https://starknet-mainnet.g.alchemy.com/v2/KEY

Alternative providers: Infura, Blast, Nethermind (free tier available).

Local Devnet

# Install and run starknet-devnet-rs
cargo install starknet-devnet
starknet-devnet --seed 42

# Devnet provides pre-funded accounts — use them for testing

Contract Verification

Verify source code on Voyager or Starkscan:

# Verify on Voyager (manual: upload Sierra JSON via web UI)
# https://sepolia.voyager.online/contract/0xADDRESS#code

# Or use Walnut for programmatic verification
# https://app.walnut.dev

Note: In Starknet Foundry 0.57.0+, sncast verify supports both Walnut and Voyager backends (for example, sncast verify --verifier voyager). Starkscan verification still uses its web UI.

Upgradeable Contracts

For contracts using OZ UpgradeableComponent:

# 1. Declare new class
sncast declare --contract-name MyContractV2

# 2. Call upgrade on existing contract
sncast invoke \
    --contract-address 0xEXISTING_CONTRACT \
    --function "upgrade" \
    --calldata 0xNEW_CLASS_HASH

Common Errors

Error Cause Fix
Contract not found Account not deployed Run sncast account deploy
Insufficient max fee Not enough ETH/STRK for gas Fund the deployer account
Class already declared Same class hash exists Use the existing class hash for deploy
Entry point not found Wrong function name Check the contract ABI
Invalid calldata Wrong number/type of args Check constructor signature, remember u256 = 2 felts