A TypeScript interface for Aleo, inspired by viem. Wraps existing Aleo wallets and SDKs behind a unified, familiar API — for human developers and AI agents alike.
Documentation · Package guide · LLM documentation index
Aleo allows users privacy in their assets and data and allows developers to build privacy into their Dapps.
Veil provides semantics familiar to what EVM developers and agents expect. If you've built on Ethereum with viem, you already know how to use veil — same patterns, same method names, applied to Aleo.
import { createPublicClient, createWalletClient, http } from '@provablehq/veil-core'
import { fromWalletAdapter } from '@provablehq/veil-aleo-wallet-adapter'
// A read-only client — point a transport at an Aleo node (viem's createPublicClient).
const client = createPublicClient({
transport: http('https://edge.provable.com/api/v2'),
})
// Similar method names as in viem, now reading Aleo state.
const height = await client.getBlockNumber() // current chain height
const balance = await client.getBalance({ address: 'aleo1...' }) // public credits
// readContract reads a program mapping: mapping[key] in `credits.aleo`.
const value = await client.readContract({
programId: 'credits.aleo',
mapping: 'account',
key: 'aleo1...',
})
// For writes, a wallet client pairs a transport with an account — same as viem.
// A connected wallet supplies both; a local key path uses @provablehq/veil-aleo-sdk.
const { account, transport } = fromWalletAdapter(walletAdapter)
const wallet = createWalletClient({ account, transport })
// writeContract mirrors viem: name the program + function, pass typed inputs.
const txId = await wallet.writeContract({
program: 'my_program.aleo',
function: 'transfer',
inputs: ['aleo1...', '100u64'],
})| Use case | What it enables |
|---|---|
| 👛 Private Browser and Mobile dApps | browser apps where a user's wallet (Shield, Leo, Puzzle, Fox) holds the keys and proves. (@provablehq/veil-aleo-react-hooks) |
| 💸 Private Token Bridging & Shielding | Shield public assets from Ethereum and Solana. Privately hold and transfer them |
| 📈 Private DeFi | Private swaps of Ethereum and Solana assets, private market making, private lending (@provablehq/shield-swap-sdk) |
| 🤖 AI agents that use Aleo | expose Aleo as MCP tools or drop tool schemas into any agent framework; agents can also write viem-style code directly. (@provablehq/veil-core/agent, @provablehq/veil-core/mcp) |
| Aleo Program Development & Testing | build, deploy, and test Aleo programs and dapps against a local Aleo node (@provablehq/veil-leo, @provablehq/veil-aleo-devnode) |
@provablehq/veil-core is the base — every other package builds on its client, action,
and transport interfaces.
| Package | What it's for | When to use it |
|---|---|---|
🧩 @provablehq/veil-core |
Clients, actions, transports, types — the base SDK. Also ships LLM agent (/agent) and MCP (/mcp) bindings. |
Every Veil project — reading or writing Aleo, or as the base you extend. |
🔑 @provablehq/veil-aleo-sdk |
Local accounts, signing, and proving via @provablehq/sdk. Build a client from a private key. |
Developing scripts, clis, server-side apps, or AI Agents using a locally custodied keys or server wallets |
🌐 @provablehq/veil-aleo-wallet-adapter |
Bridge any Provable-standard wallet (Shield, Leo, Puzzle, Fox) into a Veil client. | Building Aleo browser or mobile dapps and integrations |
⚛️ @provablehq/veil-aleo-react-hooks |
VeilProvider + useVeilWallet() — wallet connection and clients for React apps. |
Building Aleo dapps with React |
📈 @provablehq/shield-swap-sdk |
Client for the shield_swap AMM/DEX — private swaps, liquidity, and the DEX API. |
Integrating with Shield Swap for private token swaps |
🖥️ @provablehq/shield-swap-cli |
The shield-swap command — setup, pools, balances, swaps, and liquidity from a terminal. |
CLI for for private swaps on Shield Swap for humans or Agents |
📜 @provablehq/veil-codegen |
Generate typed bindings from an Aleo program ABI (library + veil-codegen CLI). |
Generating JS/TS contracts from Aleo smart contract ABIs |
🧪 @provablehq/veil-aleo-devnode |
Run and drive a local Aleo devnode for tests. | Testing and local development with a local Aleo node |
🦁 @provablehq/veil-leo |
Typed wrapper around the leo CLI (build, deploy, …). |
Compiling or deploying Leo programs — including during testing with Aleo Devnode (@provablehq/veil-aleo-devnode) |
💸 @provablehq/aleo-bridge-sdk |
Cross-chain bridge client (preview). Versions in lockstep with the Veil packages; expect breaking changes between minor releases. | Bridging tokens to and from Aleo via EVM Chains (Circle ARC, Base, Arbitrum, etc.) or Solana |
import { createPublicClient, http } from '@provablehq/veil-core'
const client = createPublicClient({
transport: http('https://edge.provable.com/api/v2'),
})
// Familiar viem-style actions
const height = await client.getBlockNumber()
const block = await client.getBlock({ height: 1000 })
const tx = await client.getTransaction({ id: 'at1...' })
const balance = await client.getBalance({ address: 'aleo1...' })
const source = await client.getCode({ programId: 'credits.aleo' })
const value = await client.readContract({
programId: 'credits.aleo',
mapping: 'account',
key: 'aleo1...',
})import { createWalletClient } from '@provablehq/veil-core'
import { fromWalletAdapter } from '@provablehq/veil-aleo-wallet-adapter'
const { account, transport } = fromWalletAdapter(walletAdapter)
const client = createWalletClient({ account, transport })
// writeContract or its alias executeTransaction
await client.writeContract({
program: 'my_program.aleo',
function: 'transfer',
inputs: ['aleo1...', '100u64'],
fee: 1000n,
})
await client.deployContract({
program: myProgramSource,
fee: 5000n,
})
await client.transfer({
to: 'aleo1...',
amount: 1_000_000n,
})import { loadNetwork } from '@provablehq/veil-aleo-sdk'
// loadNetwork builds the account, proving, and clients from a private key.
const aleo = await loadNetwork('testnet')
const { publicClient, walletClient } = aleo.createAleoClient({
privateKey: 'APrivateKey1...',
networkUrl: 'https://edge.provable.com/api/v2',
provingMode: 'delegated', // or 'local' to prove in-process
proverUrl: 'https://edge.provable.com/api/prove/testnet',
})import { getContract } from '@provablehq/veil-core'
const contract = getContract({
programSource: tokenProgramSource,
client: { public: publicClient, wallet: walletClient },
})
// Typed read/write from parsed program source
const balance = await contract.read.balances({ key: 'aleo1...' })
const txId = await contract.write.transfer({
inputs: ['aleo1...', '100u64'],
fee: 1000n,
})import { createPublicClient, http, viewOnlyAccount } from '@provablehq/veil-core'
const client = createPublicClient({
transport: http('https://edge.provable.com/api/v2'),
})
const account = viewOnlyAccount({
address: 'aleo1...',
viewKey: 'AViewKey1...',
})
// Use the view key to decrypt records without signing authority@provablehq/aleo-bridge-sdk supports cross-chain transfers through Circle
xReserve, Circle CCTP, and Hyperlane. It connects Aleo assets to Ethereum and
Solana, and moves native USDC between Arc and Ethereum, Base, or Arbitrum.
The package is in preview; supported operations depend on the route's reviewed
deployment metadata. See the bridge package guide
for supported routes, wallet integrations, execution, and recovery.
import { createBridgeClient } from '@provablehq/aleo-bridge-sdk'
const bridge = createBridgeClient({ environment: 'mainnet' })
const [route] = bridge.registry.getRoutes({
environment: bridge.environment,
protocol: 'xreserve',
sourceChainId: 'ethereum',
destinationChainId: 'aleo',
})
const quote = await bridge.quote({
source: { chain: 'ethereum', asset: 'usdc' },
destination: { chain: 'aleo', asset: 'usdcx' },
bridgeProtocol: route.protocol,
amount: '25',
recipient: aleoAddress,
})
quote.plan.steps // approve → deposit → wait-attestation → mintquote validates the route, amount precision, and recipient, reads current
fees where the provider exposes them, and returns the plan used for execution.
Quoting does not sign, submit, or move funds. Execution and recovery are separate
operations documented in the bridge package guide.
veil is designed for two audiences equally: human developers who write code against the TypeScript library, and AI agents that either write code using viem patterns or call tools directly.
Run the MCP server to expose all veil actions as tools:
import { createMcpServer } from '@provablehq/veil-core/mcp'
import { createPublicClient, http } from '@provablehq/veil-core'
const client = createPublicClient({
transport: http('https://edge.provable.com/api/v2'),
})
await createMcpServer({ client })Agents can then call tools like aleo_get_balance, aleo_read_mapping, aleo_execute, aleo_describe_program, etc. All tools return structured JSON with parsed Aleo values.
Use agent tool schemas and handlers directly in any agent framework:
import { aleoAgentTools } from '@provablehq/veil-core/agent'
const tools = aleoAgentTools({
client: publicClient,
walletClient: walletClient,
})
// Each tool has { schema, handler } — plug into LangChain, Vercel AI SDK, etc.Core reads records from a scanner and joins or splits them to prepare an
ARC20, ARC22, native credits, or compatible custom balance for spending. An asset
needs only its program; optional recordName and amountField select a custom
balance. Joins of more than two records prefer available batch helper programs.
Shield Swap applies these operations to each DEX token's underlying program.
shield-swap inventory runs background
maintenance and stores recovery data in SQLite.
Record reservations and recovery are off by default. Follow the record management guide to enable them, configure storage, select private fee records, and recover interrupted work. The concurrent swaps walkthrough shows how to prepare records, share both stores, and claim successful swaps when another trade fails.
MIT