@0xgks/mandate-sdk

@0xgks/mandate-sdk

TypeScript SDK for generating and submitting MANDATE-compliant agent orders.

This package wraps the MANDATE protocol's proving and submission pipeline behind a single call:

import { MandateClient } from "@0xgks/mandate-sdk";

const client = new MandateClient({
  agentId: "0x...",              // Poseidon2(session pk, salt) — this agent's registry identity
  sequencerUrl: "http://127.0.0.1:8787",
  rpcUrl: "http://127.0.0.1:8545",
  auctionAddress: "0x...",       // BatchAuction
  registryAddress: "0x...",      // MandateRegistry
  sessionPrivateKey: "0x...",    // the session EOA's private key (zero authority over funds)
  circuitDir: "/path/to/circuits/policy_check",
  policy: {
    whitelistRoot: 123n,
    maxOrderNotional: 1_000_000n,
    maxPosition: 1_000n,
    maxDailyLoss: 500n,
    policySalt: 42n,
  },
});

const result = await client.proveAndSubmit({
  market: "1",        // circuit market id, decimal string
  side: "buy",
  amount: "3",
  limitPrice: "3120",
});
// { epoch, orderCommitment, proof, publicInputs, txHash }

What proveAndSubmit does

1. Normalizes the order (string amounts/prices -> the circuit's typed fields).
2. Reads the current epoch, commit/reveal phase, breaker bit, and this agent's anchored state root from the BatchAuction contract.
3. Checks the local plaintext policy still opens the commitment registered for this agent in MandateRegistry (refuses to prove with a stale or wrong mandate).
4. Fetches the anchored portfolio witness (Merkle path + encoded position/PnL) from the sequencer, and refuses to proceed if it disagrees with the on-chain root — the chain is always the trusted source, never the sequencer's say-so.
5. Generates the Poseidon2 order commitment and a Prover.toml, then runs nargo execute and bb prove against the Noir circuit. A mandate-violating order cannot be proven — this step throws MandateViolationError and nothing below it ever runs.
6. Re-checks the commit window hasn't closed while proving, then submits the proof-gated commitment to BatchAuction.submitOrder.
7. Hands the plaintext order envelope to the sequencer's /envelope endpoint for the reveal phase.

What this SDK is not

It does not decide what to trade — that's a strategy's job, and stays outside the SDK (see agents/src/strategies.ts in this monorepo for the demo's momentum/market-maker strategies). The SDK is the mechanical "prove this decided order and get it committed" primitive, safe to reuse from any agent runner or future MCP server.

Exports

Besides MandateClient, the package exports the lower-level primitives it's built from, for callers who want to compose their own flow:

• PolicyProver — the Prover.toml → nargo execute → bb prove wrapper.
• SparseMerkleTree — the ZeroTree sparse Merkle tree used for the whitelist and per-agent portfolio state.
• hash, policyCommitment, orderCommitment, whitelistLeaf, portfolioLeaf — Poseidon2 commitment functions with byte-for-byte Noir parity (see client.test.ts).
• toField, toHex32, encodeSigned, decodeSigned — field/encoding helpers matching the circuit exactly.
• MandateViolationError, PortfolioMismatchError, PolicyMismatchError, EpochClosedError — typed errors for each rejection path.

Requirements

Node.js ≥ 20, and on PATH (or via the nargoBin/bbBin config fields / NARGO_BIN/BB_BIN env vars): nargo (1.0.0-beta.22) and bb (5.0.0-nightly, matched to nargo).

Testing

npm test

Runs the sparse-Merkle-tree unit tests and an integration test that mocks the chain and sequencer but performs real proving (nargo execute + bb prove) against circuits/policy_check, covering the compliant-order, mandate-violation, portfolio-mismatch, policy-mismatch, and closed-window paths.