{"_id":"@0xgks/mandate-sdk","name":"@0xgks/mandate-sdk","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@0xgks/mandate-sdk","version":"0.1.0","description":"TypeScript SDK for generating and submitting MANDATE-compliant agent orders: Poseidon2 commitments, sparse-Merkle portfolio membership, Noir/Barretenberg proving, and sequencer/contract submission.","type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"tsc","test":"tsx src/merkle.test.ts && tsx src/client.test.ts","prepublishOnly":"npm run build && npm test"},"dependencies":{"@zkpassport/poseidon2":"^0.6.0","viem":"^2.21.0"},"devDependencies":{"@types/node":"^20.11.0","tsx":"^4.19.0","typescript":"^5.6.0"},"engines":{"node":">=20"},"publishConfig":{"access":"public"},"_id":"@0xgks/mandate-sdk@0.1.0","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-2AmgnG51VsVinO9+3wbhUIbL5cFuFXS2aOxjfoyW3ivv5cDr6nXNtIA7DD6H/bCUpUbNnOMxk5T8c5N2mw1fsA==","shasum":"d4042e47b97f0ad2e46e205cb77d1e6400d2f1ec","tarball":"https://registry.npmjs.org/@0xgks/mandate-sdk/-/mandate-sdk-0.1.0.tgz","fileCount":26,"unpackedSize":40993,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCF2SmdjdYJOwnT1paLDZNxbDz0b8YWmn4HaYHPUG5aOAIgXv+k1Ta9AbqRgQaN/eUSV4PSeLUihPVJzG4lmA9tCpk="}]},"_npmUser":{"name":"0xgks","email":"goksualcinkaya@gmail.com"},"directories":{},"maintainers":[{"name":"0xgks","email":"goksualcinkaya@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mandate-sdk_0.1.0_1784757417034_0.48409316023208393"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-22T21:56:56.815Z","0.1.0":"2026-07-22T21:56:57.168Z","modified":"2026-07-22T21:56:57.431Z"},"maintainers":[{"name":"0xgks","email":"goksualcinkaya@gmail.com"}],"description":"TypeScript SDK for generating and submitting MANDATE-compliant agent orders: Poseidon2 commitments, sparse-Merkle portfolio membership, Noir/Barretenberg proving, and sequencer/contract submission.","readme":"# @0xgks/mandate-sdk\n\nTypeScript SDK for generating and submitting MANDATE-compliant agent orders.\n\nThis package wraps the MANDATE protocol's proving and submission pipeline\nbehind a single call:\n\n```ts\nimport { MandateClient } from \"@0xgks/mandate-sdk\";\n\nconst client = new MandateClient({\n  agentId: \"0x...\",              // Poseidon2(session pk, salt) — this agent's registry identity\n  sequencerUrl: \"http://127.0.0.1:8787\",\n  rpcUrl: \"http://127.0.0.1:8545\",\n  auctionAddress: \"0x...\",       // BatchAuction\n  registryAddress: \"0x...\",      // MandateRegistry\n  sessionPrivateKey: \"0x...\",    // the session EOA's private key (zero authority over funds)\n  circuitDir: \"/path/to/circuits/policy_check\",\n  policy: {\n    whitelistRoot: 123n,\n    maxOrderNotional: 1_000_000n,\n    maxPosition: 1_000n,\n    maxDailyLoss: 500n,\n    policySalt: 42n,\n  },\n});\n\nconst result = await client.proveAndSubmit({\n  market: \"1\",        // circuit market id, decimal string\n  side: \"buy\",\n  amount: \"3\",\n  limitPrice: \"3120\",\n});\n// { epoch, orderCommitment, proof, publicInputs, txHash }\n```\n\n## What `proveAndSubmit` does\n\n1. Normalizes the order (string amounts/prices -> the circuit's typed fields).\n2. Reads the current epoch, commit/reveal phase, breaker bit, and this\n   agent's anchored state root from the `BatchAuction` contract.\n3. Checks the local plaintext policy still opens the commitment registered\n   for this agent in `MandateRegistry` (refuses to prove with a stale or\n   wrong mandate).\n4. Fetches the anchored portfolio witness (Merkle path + encoded\n   position/PnL) from the sequencer, and refuses to proceed if it disagrees\n   with the on-chain root — the chain is always the trusted source, never\n   the sequencer's say-so.\n5. Generates the Poseidon2 order commitment and a `Prover.toml`, then runs\n   `nargo execute` and `bb prove` against the Noir circuit. **A\n   mandate-violating order cannot be proven** — this step throws\n   `MandateViolationError` and nothing below it ever runs.\n6. Re-checks the commit window hasn't closed while proving, then submits\n   the proof-gated commitment to `BatchAuction.submitOrder`.\n7. Hands the plaintext order envelope to the sequencer's `/envelope`\n   endpoint for the reveal phase.\n\n## What this SDK is not\n\nIt does not decide *what* to trade — that's a strategy's job, and stays\noutside the SDK (see `agents/src/strategies.ts` in this monorepo for the\ndemo's momentum/market-maker strategies). The SDK is the mechanical\n\"prove this decided order and get it committed\" primitive, safe to reuse\nfrom any agent runner or future MCP server.\n\n## Exports\n\nBesides `MandateClient`, the package exports the lower-level primitives it's\nbuilt from, for callers who want to compose their own flow:\n\n- `PolicyProver` — the `Prover.toml` → `nargo execute` → `bb prove` wrapper.\n- `SparseMerkleTree` — the ZeroTree sparse Merkle tree used for the\n  whitelist and per-agent portfolio state.\n- `hash`, `policyCommitment`, `orderCommitment`, `whitelistLeaf`,\n  `portfolioLeaf` — Poseidon2 commitment functions with byte-for-byte Noir\n  parity (see `client.test.ts`).\n- `toField`, `toHex32`, `encodeSigned`, `decodeSigned` — field/encoding\n  helpers matching the circuit exactly.\n- `MandateViolationError`, `PortfolioMismatchError`, `PolicyMismatchError`,\n  `EpochClosedError` — typed errors for each rejection path.\n\n## Requirements\n\nNode.js ≥ 20, and on `PATH` (or via the `nargoBin`/`bbBin` config fields /\n`NARGO_BIN`/`BB_BIN` env vars): `nargo` (1.0.0-beta.22) and `bb`\n(5.0.0-nightly, matched to nargo).\n\n## Testing\n\n```bash\nnpm test\n```\n\nRuns the sparse-Merkle-tree unit tests and an integration test that mocks\nthe chain and sequencer but performs **real** proving (`nargo execute` +\n`bb prove`) against `circuits/policy_check`, covering the compliant-order,\nmandate-violation, portfolio-mismatch, policy-mismatch, and closed-window\npaths.\n","readmeFilename":"README.md","_rev":"1-268c7b7f6dfa0c1f7301714b342ac33e"}