Quickstart

Run the SODA v0 demo end-to-end: a Solana program signs a real Sepolia transaction, or, with DEMO_CHAIN=sui-testnet, a Sui testnet transfer from the same wallet’s Sui address. The whole flow takes about 10 seconds once funds are in place.

Just want to use the SDK in your own project? You don’t need to clone this repo. Run pnpm add @soda-sdk/core and follow the Sign an Ethereum tx guide. This page is for the full local demo (validator + Anchor build + signer daemon).

v0 ships with a single dev signing key (no real t-of-n committee yet). That key persists across runs, so the derived ETH address is stable: fund it once on Sepolia, demo many times.

⚠️

Sepolia / devnet only. Don’t send real ETH (mainnet) or other valuable assets to a SODA-derived address while v0 is the deployed committee. A single-key signer means anyone with the keystore can move every derived balance — fine for a hackathon demo, not for production. See Concepts → Signing committee for the v1 design.

Prerequisites

WSL (Ubuntu) or Linux.
Rust 1.95+, Solana CLI 3.1+, Anchor 0.32.1, Node 24+, pnpm 10+.
A Solana keypair at ~/.config/solana/id.json.
A .env file at the repo root with SEPOLIA_RPC_URL=... (Alchemy / Infura). The Sui path needs no RPC key: it uses Mysten’s public GraphQL endpoint.

Setup

Clone and install

git clone https://github.com/JingYuan0926/frontier
cd frontier
pnpm install

Set up .env

cat > .env <<EOF
SEPOLIA_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/YOUR_KEY
SOLANA_DEVNET_RPC_URL=https://devnet.helius-rpc.com/?api-key=YOUR_KEY
# Optional sponsors that top the derived address up with gas just in time.
# 32-byte secp256k1 hex secrets holding testnet money only.
SEPOLIA_FUNDER_KEY=
SUI_FUNDER_KEY=
EOF

Fund the derived address

The first time you run the demo, it prints the derived Sepolia address (stable across runs as long as keyshare.dev.json exists). Send around 0.001 ETH of Sepolia testnet ETH to that address from a faucet.

For Sui, the derived address is different (the chain tag is a derivation input) and needs at least 0.02 SUI. The demo asks the public faucet itself, or sends from SUI_FUNDER_KEY if set; if both fail it prints the address and polls until you fund it from faucet.sui.io.

Run the demo

The CLI is the canonical demo path.

./demo.sh

Defaults to Solana devnet and an Aave V3 depositETH of 0.0001 ETH: the derived address ends up holding aWETH, a lending position owned by a Solana account. After a successful broadcast, demo.sh automatically runs pnpm verify <hash>, which prints the cryptographic audit trail (the checks tying the Solana SigRequest PDA to the broadcast EVM transaction).

DEMO_ACTION=borrow ./demo.sh             # Pool.borrow 0.1 USDC against the aWETH
DEMO_CHAIN=base-sepolia ./demo.sh        # destination chain: sepolia | base-sepolia
DEMO_CHAIN=sui-testnet ./demo.sh         # Sui: buy DEEP on DeepBook from the derived Sui address
DEMO_ACTION=sell DEMO_CHAIN=sui-testnet ./demo.sh    # sell that DEEP back for SUI
SODA_DRY_RUN=1 ./demo.sh                 # skip the foreign-chain broadcast, verify on-chain only
SOLANA_CLUSTER=local ./demo.sh           # against a local validator

The borrow is the proof of control: a deposit could be read as “sent ETH to a contract”, but only the position’s owner can borrow against it, and the derived address ends up holding USDC it never had. Both actions go through the same pipeline; only the calldata differs.

DEMO_CHAIN=sui-testnet (or sui-devnet) runs the same pipeline against a non-EVM chain: sui_demo BCS-encodes the Sui transaction on-chain, derives the sender itself, and commits sha256(blake2b(intent || tx)) instead of keccak(rlp). Sui accepts the committee’s secp256k1 signature natively, so soda and finalize_signature are untouched.

The Sui actions are DeepBook V3 trades, and they are the Sui counterpart of the Aave pair: swap buys DEEP with SUI off Sui’s on-chain central limit order book, sell spends that DEEP back. The sell is the proof of control — it moves coin objects the address acquired itself, not the SUI it was funded with. DEMO_ACTION=transfer is a plain transfer, kept as a fallback. demo.sh chains into pnpm verify:sui <digest> afterwards. See Sign a Sui tx.

pnpm --filter web dev
# open http://localhost:3000

Three steps: connect Phantom, derive the EVM address, then act on Aave — deposit ETH or borrow USDC. Phantom signs sign_eth_transfer; the server signs the payload, submits finalize_signature, and broadcasts. A live card shows Aave’s own view of the derived address (supplied, borrowed, collateral, health factor, rates), read from the Pool with eth_call. The deployed instance needs the environment variables listed in Deploy the web demo to Vercel.

The same three steps for Sui are at http://localhost:3000/sui: connect, derive the Sui address, then trade on DeepBook — buy DEEP with SUI or sell it back, with a live card showing DeepBook’s own view of the address (balances, mid price, what the demo size would buy). Phantom signs sign_sui_tx; /api/sui/fund tops the address up (SUI_FUNDER_KEY, else the public faucet) and /api/sui/finalize signs, finalizes and submits over GraphQL. Set NEXT_PUBLIC_SUI_CHAIN and SUI_CHAIN to the same value (sui-testnet | sui-devnet) in apps/web/.env; see apps/web/.env.example.

To show the full production-shape architecture (each piece communicating via on-chain events only, no shared in-process state), open three terminals:

# Terminal 1 — Rust signer daemon (Tokio + k256)
pnpm signer
 
# Terminal 2 — Node relayer (events → broadcast)
pnpm relayer:dev
 
# Terminal 3 — kick it off
./demo.sh

Each process logs its own work; all three independently arrive at the same on-chain finalize_signature and the same Sepolia transaction hash.

Replaces the v0 single-key Rust signer with a real Lindell ‘17 2-of-2 MPC committee. The on-chain program doesn’t change — only the off-chain signer.

# 1. Once: distributed key generation (writes shares to apps/mpc-node/shares/)
pnpm mpc:dkg
 
# 2. Boot the MPC stack (3 containers: p1, p2, coordinator)
pnpm mpc:up
 
# 3. Once: migrate the on-chain group_pk from v0 → v0.5 joint key
#    Requires `anchor build && anchor deploy` first so the new
#    update_committee ix is on devnet.
pnpm mpc:update-committee
 
# 4. Run the subscriber that wires SigRequested → MPC sign → finalize
pnpm mpc:subscribe
 
# 5. Run the demo as usual; signing now goes through MPC
./demo.sh

For the full deploy walkthrough (two EC2 hosts in different regions plus a coordinator), see Deploy → AWS MPC.

What you should see

The CLI prints the derived ETH address and waits for funding (skipped if already funded).
A SigRequested event fires on Solana devnet. Visible on Solscan.
The signer signs the payload off-chain with k256.
A finalize_signature instruction runs secp256k1_recover on-chain and stores the signature.
The signed RLP is broadcast to Sepolia. Etherscan link is printed.
pnpm verify <hash> runs automatically and prints the six audit checks.

Verifying any past run

pnpm verify 0x<sepolia_tx_hash>
DEMO_CHAIN=sui-testnet pnpm verify:sui <sui_tx_digest>

Reads only public state. Re-derives the ETH (or Sui) address from the on-chain SigRequest PDA and confirms the broadcast from / sender address matches. Both tools look the SigRequest up under your CLI wallet; set VERIFY_REQUESTER=<pubkey> to audit a run signed by another account.

Troubleshooting

Symptom	Fix
`insufficient funds`	Fund the derived address from a Sepolia faucet.
`AlreadyCompleted` (custom error 0x1770)	Idempotent: another process (relayer / daemon) already signed. Safe to ignore.
Anchor build fails on BPF stack	You enabled on-chain `ProjectivePoint` ops. v0 keeps derivation off-chain.
Web UI shows blank balance	Set `SEPOLIA_RPC_URL` in `apps/web/.env.local` (mirrors repo-root `.env`).
Sui faucet `429 Wait for Ns`	The public faucet rate-limits per IP. Use faucet.sui.io, the Sui Discord, or set `SUI_FUNDER_KEY`; the demo keeps polling the balance.
`no SUI coin objects at 0x…`	Unfunded, or the GraphQL indexer has not seen the faucet transfer yet. Check Suiscan and rerun in a few seconds.
Sui dry-run `FAILURE` after a top-up	A gas coin’s version changed between reading it and building the tx. Rerun; the demo refetches coins and the payload is new.
`DEMO_CHAIN=sui-testnet` still runs the EVM demo	An older `demo.sh` let `.env` override the environment. Current `demo.sh` keeps what you set on the command line.

Introduction Use with AI