Open Source — Aleo Layer-3 Framework

Ship your own
L3 network
on Aleo.

WooSDK bundles everything you need to launch a fully working Layer 3 chain: genesis contract, sequencer node, ZK prover, CLI, and wallet — anchored to Aleo, proved with zero-knowledge.

Get started View on GitHub
5 Core components
L1→L3 Bridge built-in
ZK Native proofs
Docker One command
ALEO Layer 1 Genesis Contract (L1) Sequencer L3 Node ZK Prover Zero-Knowledge CLI Deploy & Manage Woo Wallet DEX · RPC · Transfers bridge
Genesis Contract L3 Sequencer ZK Prover CLI Tooling Woo Wallet L1→L3 Bridge Aleo Testnet Docker Deploy Custom Chain-ID Wrapped Aleo DeFi DEX Open Source Genesis Contract L3 Sequencer ZK Prover CLI Tooling Woo Wallet L1→L3 Bridge Aleo Testnet Docker Deploy Custom Chain-ID Wrapped Aleo DeFi DEX Open Source
SDK Components

Everything your L3 needs,
assembled and ready.

Five tightly-integrated layers that handle the full lifecycle from chain genesis to end-user wallet interactions.

Genesis Contract

The on-chain anchor on Aleo L1. Manages batch anchoring, staking administration, and the vault bridge. Deployed once per network.

L3 Sequencer Node

Maintains the local Layer 3 state. Acts as the network sequencer, ordering transactions and batching them for submission to L1.

ZK Prover

A Rust-powered prover that generates and verifies Zero-Knowledge Proofs for every transaction on your L3, inheriting Aleo's privacy guarantees.

CLI

Deploy a new network, mint the initial gas token, activate the chain, and trigger L1→L3 bridge deposits — all from a single command-line tool.

Woo Wallet

A browser-based interface built for your L3. Supports custom RPC endpoints, token transfers, a built-in DEX, and contract deployment.

L1 → L3 Bridge

Move Aleo Testnet funds from L1 directly into your L3, minting Wrapped Aleo. Both CLI and the Leo contract templates are included.

Architecture

Five layers. One transaction path.

From the moment a user submits a transaction in the wallet to the moment proof lands on Aleo L1, every component hands off cleanly to the next.

01
CLI sets up the chain

Run cli.mjs full with your chain ID and gas token. The CLI deploys the genesis contract to Aleo L1 and mints the initial supply.

02
Sequencer accepts txs

Your L3 node receives transactions from the wallet or RPC, orders them, and maintains the local chain state.

03
ZK Prover generates proofs

The Rust prover creates a Zero-Knowledge Proof for each batch of transactions, ensuring validity without revealing private data.

04
Batch anchors on L1

The genesis contract on Aleo L1 receives the proof and anchors the batch, securing L3 finality on the base layer.

05
Wallet closes the loop

Users query the RPC from the wallet, see confirmed balances, and can bridge back from L3 to L1 whenever needed.

Woo Wallet User & RPC Sequencer L3 Node Orders txs ZK Prover Rust · Proof Generation Genesis Contract (L1) Anchor & Bridge ALEO Layer 1 Finality L1 → L3 bridge deposit CLI Deploys chain
Why WooSDK

Build chains,
not infrastructure.

Launching a custom L3 on Aleo from scratch means months of work: writing the anchor contract, setting up a sequencer, integrating a ZK backend, and building a wallet. WooSDK collapses that into a git clone and one command.

  • Instant genesis Deploy your network's anchor contract to Aleo L1 and mint your gas token in one CLI call.
  • ZK proofs included The Rust prover is pre-integrated. No cryptography expertise required to ship a privacy-preserving chain.
  • Bridge on day one L1-to-L3 deposits work out of the box. Your users can fund L3 wallets directly from Aleo Testnet.
  • Full wallet UI Woo Wallet ships with DEX, custom RPC, and contract deployment — ready for your end users.
  • Docker or manual Run the entire stack with docker compose up or configure each service manually for production.
~1 min
From clone to running L3 node with Docker
5
Pre-built components
ZK
Native zero-knowledge proofs
MIT
Open source license
Quick Start

Up and running in minutes.

Two paths: Docker gets you a full working environment instantly. Manual setup gives you control over each service for production deployments.

Terminal 
# Clone the repository
git clone https://github.com/riquelima805/woosdk.git
cd woosdk

# Start all services
docker compose up --build

# Deploy a new network (replace 1988 with your chain ID)
docker compose --profile cli run --rm cli \
  node cli.mjs full \
  --chain-id 1988 \
  --gas-token-id 1

# View logs
docker compose logs -f node1

# Check service status
docker compose ps
⚠ Always update the chain-id and sequencer address before launching. The sequencer address is also used as the bridge Vault address.
01

Install dependencies

Requires Node.js v18+, Rust v1.70+, and Leo v2.0.0+. Add the Leo executable to your PATH.

bash
git clone https://github.com/riquelima805/woosdk.git
cd woosdk
npm install
02

Install wallet dependencies

bash
cd woo-wallet
npm install
03

Build the ZK Prover

bash
cd ../zk-prover
cargo build
04

Configure environment

Return to the root folder and add your Aleo private key to the .env file. You need Testnet credits from faucet.aleo.org.

05

Deploy the network

This command deploys the system, mints the initial gas token, and activates the network.

bash
node cli.mjs full \
  --chain-id 888 \
  --gas-token-id 1 \
  --sequencer <SEQUENCER_ADDRESS>
06

Start all services

Run each in a separate terminal.

RPC server — run from /woosdk
npx tsx src/rpc.ts
ZK Prover — run from /woosdk/zk-prover
cargo run --release
Wallet — run from /woo-wallet
npm run dev
ℹ Required contracts: You must deploy the DeFi contract and wanpedleo for the wallet to work correctly. Both are located in /aleo programs.
L1 to L3 deposit — via CLI (Docker) 
# Bridge Aleo Testnet funds into your L3
docker compose --profile cli run --rm cli \
  node cli.mjs bridge-in \
  --chain-id 1988 \
  --token-id 0 \
  --amount 1000 \
  --receiver aleo1YOUR_ADDRESS_HERE

Or use the Leo contract directly from the genesis contract's templates folder:

leo execute (direct L1 call) 
leo execute bridge_in \
  2011u64 1u64 5000000u64 \
  <L1_RECEIVER_ADDRESS> \
  <VAULT_ADDRESS> \
  --broadcast \
  --network testnet \
  --endpoint "https://api.explorer.aleo.org/v1/testnet3" \
  --private-key "YOUR_PRIVATE_KEY"
ℹ Bridged funds arrive as Wrapped Aleo on your L3. The bridge vault address and sequencer address are the same for now.
Overview

What is WooSDK?

WooSDK is an open-source framework for developers who want to launch Layer 3 networks on top of Aleo. It removes the infrastructure heavy-lifting by packaging five tightly integrated components into a single repository that can be bootstrapped with Docker or configured manually for production.

A WooSDK chain is anchored to Aleo L1 via a genesis contract, sequences transactions locally, proves them with Zero-Knowledge Proofs, and exposes an EVM-style RPC for wallet and dApp integrations.

SDK Component Map

Component Language Role
Genesis ContractLeoAnchors batches, staking, bridge on Aleo L1
L3 NodeNode.js / TypeScriptSequencer, local L3 state, RPC
ZK ProverRustZero-Knowledge Proof generation & verification
CLINode.jsDeploy chains, mint tokens, bridge
Woo WalletNode.js / WebUser interface: transfers, DEX, RPC, deploy

Requirements

Before installing WooSDK, make sure the following runtimes are available in your environment:

ℹ After installing Leo, make sure the leo executable is on your system PATH so the CLI can call it during deployment.

For Docker-based setup, only Docker and Docker Compose are required — all runtimes are bundled in the container images.

Genesis Contract (L1)

The Genesis Contract is a Leo smart contract deployed to Aleo L1. It is the on-chain anchor for your entire L3 network and handles three main responsibilities:

Batch anchoring

After the ZK Prover generates a proof for a batch of L3 transactions, the genesis contract receives and records that proof on L1, establishing finality.

Staking management

The genesis contract holds the logic for sequencer staking, allowing you to add economic security to your L3 over time.

Bridge vault

The contract acts as the vault for the L1→L3 bridge. When users call bridge_in, funds are locked in the vault on L1 and minted as Wrapped Aleo on L3. The sequencer address and vault address are the same entity for now — this will be decoupled in a future update.

L3 Node (Sequencer)

The L3 Node is the local chain runtime. Written in TypeScript, it does the following:

  • Receives transactions from the wallet or any RPC-compatible client
  • Orders transactions into batches
  • Maintains the current L3 state (account balances, contract storage)
  • Hands batches off to the ZK Prover
  • Exposes an RPC endpoint for wallet and dApp integration

Start the RPC server from the root directory:

bash
npx tsx src/rpc.ts

ZK Prover

The ZK Prover is a Rust binary that generates and verifies Zero-Knowledge Proofs for L3 transaction batches. It runs as a sidecar to the L3 node.

Build

bash — inside /woosdk/zk-prover
cargo build

Run in production

bash — inside /woosdk/zk-prover
cargo run --release
⚠ If you encounter a hyphen error in the Dockerfile, run:
sed -i 's|CMD \["./zk-prover"\]|CMD ["./zk_prover"]|g' ~/woosdk/zk-prover/Dockerfile
Then force a rebuild: docker compose build zk_prover --no-cache && docker compose up -d --force-recreate

CLI

The CLI (cli.mjs) is the primary tool for network operations. It wraps Leo contract deployment, token minting, and bridge calls into ergonomic subcommands.

full — deploy a new network

bash
node cli.mjs full \
  --chain-id 888 \
  --gas-token-id 1 \
  --sequencer <SEQUENCER_ADDRESS>

This deploys the genesis contract, mints the initial gas supply, and activates the network. The sequencer address becomes the bridge vault.

bridge-in — deposit from L1

bash
node cli.mjs bridge-in \
  --chain-id 888 \
  --token-id 0 \
  --amount 1000 \
  --receiver aleo1YOUR_ADDRESS_HERE

Woo Wallet

A web-based wallet built for L3 interactions. It connects to your L3 node's RPC endpoint and supports:

  • Custom RPC — point it at any WooSDK L3 node
  • Token transfers — send any L3 token between addresses
  • DEX — add liquidity pools (X/Y token pairs) and execute swaps
  • Contract deployment — deploy and interact with L3 contracts from the browser
  • Test token minting — deploy test tokens and call mint during development

Start the wallet

bash — inside /woo-wallet
npm run dev
ℹ The DeFi contract and wanpedleo must be deployed before the wallet's DEX and bridge features function correctly. Both contracts are in the /aleo programs folder.

Installation

Option A — Docker (fastest)

bash
git clone https://github.com/riquelima805/woosdk.git
cd woosdk
docker compose up --build

Option B — Manual

bash — root dependencies
git clone https://github.com/riquelima805/woosdk.git
cd woosdk
npm install
bash — wallet dependencies
cd woo-wallet
npm install
bash — ZK prover (Rust)
cd ../zk-prover
cargo build

Deploy a Network

Add your Aleo private key to the .env file in the root folder. You need Testnet credits — get them at faucet.aleo.org.

bash
node cli.mjs full \
  --chain-id 888 \
  --gas-token-id 1 \
  --sequencer <SEQUENCER_ADDRESS>

Then start all three services in separate terminals as described in the Quick Start — RPC, ZK Prover, and Wallet.

⚠ If using Docker, update the sequencer address in .env.test before deploying. The chain-id in the CLI command must match the one in your environment config.

Bridge (L1 to L3)

WooSDK supports depositing Aleo Testnet credits from L1 into your L3, producing Wrapped Aleo on L3.

Via CLI

bash
node cli.mjs bridge-in \
  --chain-id 1988 \
  --token-id 0 \
  --amount 1000 \
  --receiver aleo1YOUR_ADDRESS_HERE

Via Leo execute

Run directly from the templates folder inside your genesis contract:

bash
leo execute bridge_in \
  2011u64 1u64 5000000u64 \
  <L1_RECEIVER_ADDRESS> \
  <VAULT_ADDRESS> \
  --broadcast \
  --network testnet \
  --endpoint "https://api.explorer.aleo.org/v1/testnet3" \
  --private-key "YOUR_PRIVATE_KEY"

Testing Features

Tokens and DeFi

In the Woo Wallet, you can deploy test tokens and call their mint function to create supply. In the DeFi section, add two tokens (X and Y), deposit them, and call the liquidity function to create a pool. The current vault supports up to two tokens at a time.

Running services (quick reference)

docker — start background services
docker compose up -d
docker — tail node logs
docker compose logs -f node1
docker — check status
docker compose ps

Troubleshooting

ZK Prover fails with a hyphen error in Docker ▶

The Dockerfile references ./zk-prover (hyphen) but the binary is built as ./zk_prover (underscore). Fix with:

bash
sed -i 's|CMD \["./zk-prover"\]|CMD ["./zk_prover"]|g' ~/woosdk/zk-prover/Dockerfile
docker compose build zk_prover --no-cache
docker compose up -d --force-recreate
Wallet DEX or bridge features are not working ▶

The DeFi contract and wanpedleo must be deployed before the wallet can interact with those features. Both contracts are in /aleo programs. Deploy them with Leo and ensure the addresses are correctly referenced in the wallet config.

Bridge deposits are not arriving on L3 ▶

Verify that the vault address in your bridge command matches the sequencer address set during network deployment. Also confirm the RPC node is running and connected to the correct chain ID.

CLI deploy fails with a Leo error ▶

Check that the leo binary is on your PATH (which leo should return a result). You need Leo v2.0.0 or later. Also confirm your private key in .env has Testnet credits from faucet.aleo.org.

Docker Compose services restart immediately after starting ▶

Run docker compose logs -f node1 immediately after starting to capture the exit reason. The most common causes are a missing or invalid private key in .env.test, or a chain-id mismatch between the deploy command and the environment config.

Development Notes

WooSDK is under active development. The following known limitations will be addressed in future releases:

  • The bridge currently accepts any address as a vault. This will be restricted in a future update so only the registered sequencer can act as vault.
  • The RPC currently counts balances only for data provided by the owner as Vault. Multi-source accounting is planned.
  • L3 authentication (Auth layer) is still under development. Authorization checks on L3 are not yet enforced.

Contributions are welcome. See the GitHub repository for open issues and the roadmap.

Open Source

Ready to launch your L3?

Clone the repo, configure your chain ID, and run one command. Your Layer 3 network on Aleo is waiting.

View on GitHub Quick Start Guide