Documentation

Rendered from the repository's docs/ folder.

• ARCHITECTUREImprest turns a trader's onchain record into use-restricted trading credit. Three contracts
• SECURITYDesk code keeps pool credit inside the desk, the pool and Perpl, against a malicious trader,
• THREAT MODELAssume the trader, relayer and keeper are malicious, the UI is compromised, the indexer
• EVIDENCE STANDARDEvery externally visible number traces to a file in proof/.
• SETUP- Node.js 22+ (tested on 24.13.1) and pnpm 11
• DEMO RUNBOOKReal testnet activity only: no animations standing in for transactions, no hardcoded
• TESTNET DEPLOYMENT> Status (2026-10-09): already deployed on Monad testnet on 2026-10-07: ImprestPool
• KNOWN LIMITATIONSHonest list of what is not done, not proven, or depends on others. Updated 2026-10-09.
• FINAL STATUSUpdated 2026-10-08. This file summarizes; the evidence is in proof/ and the generated
• ACCOUNTINGOne canonical model, implemented three times and cross-checked:
• API| Function | Caller | Notes |
• AUDIT REPORTThis is an internal review by the build assistant, not an independent third-party audit.
• BUILD STATE> Historical snapshot (2026-10-08). Kept as a dated record. For the current state see [VERIFICATION.md](VERIFICATION.md), [ENVIRONMENTMATRIX.md](ENVIRONMENTMATR
• CLAIM LEDGERGenerated by scripts/src/gen-docs.ts from proof/claims/, which is itself generated from evidence by scripts/src/build-claims.ts and checked by scripts/src/valid
• COPY REVIEW| | Before | After |
• DECISIONSEach entry: old assumption, observed evidence, consequence, decision, affected files, tests.
• DEPENDENCY MATRIXVerified 2026-10-07. "Read on chain" means a read-only call against the live network,
• DEPLOY VERCELThe web app (web/) deploys as a normal Next.js project. Nothing secret goes to Vercel:
• DEPLOYMENTTestnet: follow [TESTNETDEPLOYMENT.md](TESTNETDEPLOYMENT.md). Mainnet uses the same script
• DEPLOYMENTS| Network | Contract | Address | Receipt |
• ENVIRONMENT MATRIXWhat runs where, and how each environment is labeled. Current as of 2026-10-13; the deployed web commit is whatever /api/version reports.
• FAILURE MODESHow each failure surfaces to the user, and what the system does.
• FINAL AUDIT> Historical snapshot (2026-10-08). This internal review is kept as recorded. It is not an external security audit. Later fixes and verification are in [VERIFIC
• FRONTENDAll colors, radii and type come from tokens in web/src/app/globals.css. The product is
• HACKATHON READINESSSource: "Metropolis Hackathon Rules & Guidelines", version 3.0, last updated 3 September 2026,
• HOSTINGThe live website runs on Vercel. Two optional services make it complete for visitors:
• INTEGRATIONSPer-sponsor status with evidence: [SPONSORMATRIX.md](SPONSORMATRIX.md). Versions and
• MOBILENative Expo (SDK 57, React Native 0.86) client in app/. It uses the same protocol, the same
• NETWORKSconfig/networks.json is the single source of truth; packages/core/src/networks.ts loads it
• OPERATIONS| Service | Start | Health | Logs |
• PROOFThe /proof page renders proof/claims/.json, which scripts/src/build-claims.ts
• RELEASE CHECKLISTRun before any release or submission. Every box needs evidence; unchecked boxes stay
• RISKEvery order is checked inside the desk contract before it reaches Perpl, and equity is
• SECURITY REVIEWThis is an internal automated security review, not an independent third-party audit.
• SPONSOR FINDINGSFormat: finding -> question sent -> sponsor response -> design change -> evidence -> status.
• SPONSOR MATRIX> Historical snapshot (2026-10-08). Statuses (for example the indexer and keeper) were recorded on that date. Current hosting status: [ENVIRONMENTMATRIX.md](ENV
• TEST MATRIXGenerated by scripts/src/gen-docs.ts from proof/local/forge-test-results.json (2026-10-07T15:27:11Z). Environment for every contract row: contracts (Perpl bytec
• TEST RESULTSRun 2026-10-08/09 on Windows 11 with Node 22, pnpm 11.5.0, Foundry 1.5.1 and Python 3.12,
• TESTNET> Contract addresses are current; run details are a historical record. Current desk state: [proof/local/desk-inventory.md](../proof/local/desk-inventory.md). Cu
• VERIFICATION> Historical snapshot. Sections 1–3 were recorded at commit 301157e