@tabai/sdk 0.2.0

package/LICENSE

@@ -0,0 +1,23 @@
+SPDX-License-Identifier: MIT
+
+MIT License
+
+Copyright (c) 2026 Tab Project Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,401 @@
+# @tabai/sdk
+
+**Post-paid billing for autonomous agents on Monad.** Your agent calls a priced tool, gets the result immediately, and settles the bill later with its own keys. No prepayment, no held responses, no API key bought in advance.
+
+This package is three things in one: an **MCP server** exposing four tools to any MCP client, a **CLI**, and a **TypeScript library** for building on the rail directly.
+
+```bash
+npx -y @tabai/sdk connect
+```
+
+That is the whole setup step. It finds your MCP client's configuration file, backs it up, merges one entry, and prints the diff before it writes.
+
+---
+
+## What is behind it
+
+A Service meters your agent's usage into an **Open Tab** held in `TabBook` on Monad. Your agent settles that tab in USDC on the same chain, whenever it likes, signing with keys nobody else holds.
+
+Settlement is one transaction. `TabSettlement.settle` moves the Asset to the Service's collection address and applies the Settlement to the Open Tab in the same block, atomically. There is no facilitator, no oracle, no bridge and no waiting: the transfer and the credit are the same state change, so nobody has to be trusted to say the money arrived.
+
+That is why a credit limit here is a pure function of onchain history. It is computed from the Settlements the chain itself recorded and the Bonds the agent's counterparties have escrowed, and nothing an operator reports enters the figure.
+
+**Costs.** Gas is paid in MON. Tab itself adds no fee: each Service sets its own price per tool, in integer base units of one asset, and the amount charged is the amount transferred.
+
+---
+
+## Install
+
+Requires Node `>= 20.10.0`.
+
+```bash
+npx -y @tabai/sdk connect              # wire it into an MCP client
+npx -y @tabai/sdk doctor               # check the whole installation, keylessly
+```
+
+Or as a dependency:
+
+```bash
+npm install @tabai/sdk
+```
+
+`connect` supports `claude-code`, `claude-desktop`, `cursor`, `windsurf` and `vscode`, and takes `--client <id>`, `--config <path>` or `--dry-run`. Run it twice and the second run writes nothing: the merge is idempotent and leaves no second backup.
+
+**It never writes a private key.** Signing keys are read from the environment at the moment a Settlement is broadcast, and nothing about them is copied into a client configuration file.
+
+`doctor` reports what it could reach and warns rather than failing on what it could not. A missing agent address is a warning, not an error, because every read-only tool works without one.
+
+---
+
+## The four MCP tools
+
+Each tool declares a JSON Schema for its input and its output, and validates its own input against the schema it published.
+
+| Tool | What it does | Spends |
+| --- | --- | --- |
+| `tab_discover` | Lists Services, the assets each accepts, what each tool costs, and the Bond each has staked | nothing, and needs no key |
+| `tab_call` | Calls a metered tool. The charge lands on the Open Tab and is settled later. With an x402 signer configured, a refusal that carries an x402 offer is prepaid instead | nothing at call time, unless it prepays |
+| `tab_status` | Credit limit, Open Tab, prepaid credit and headroom, per asset, with recent Settlements | nothing, and needs no key |
+| `tab_settle` | Pays down an Open Tab by sending a Settlement with the agent's own key | real funds |
+
+Start with `tab_discover`, because `tab_call` needs a `serviceId` from its list.
+
+### Nothing throws
+
+Every fallible call returns `ok: false` with a `category`, a `code` and a `message`, so a model can decide what to do next rather than parse an exception.
+
+The one failure worth handling by name is an agent with no headroom:
+
+```json
+{
+  "ok": false,
+  "category": "LIMIT",
+  "code": "LIMIT_EXCEEDED",
+  "message": "the charge exceeds the Agent's headroom in this Asset",
+  "requiredBaseUnits": "10000",
+  "headroomBaseUnits": "2500"
+}
+```
+
+Both figures are present only on `LIMIT_EXCEEDED`, and they are there so the answer is actionable. **The correct response is to settle, not to retry**: retrying a call that exceeded a credit limit produces the same refusal at the same cost. A Settlement restores headroom in the block it lands.
+
+### A new agent has no credit, and that is the rule
+
+A credit limit is capped by the Bonds of counterparties the agent already has settlement history with. An agent with no history has no counterparties, so it has no limit and must settle before it can buy on credit. Its first Settlement banks prepaid credit and creates the history a limit is computed from.
+
+---
+
+## The CLI
+
+The same package is a CLI. Every command reads the chain; one of them writes to it, and it says so before it does.
+
+| Command | What it does | Spends |
+| --- | --- | --- |
+| `connect` | Writes the `tab` entry into your MCP client's configuration | nothing |
+| `mcp` | Serves the four tools over MCP. This is what a client launches | nothing |
+| `doctor` | Checks the installation against the live deployment | nothing, and needs no key |
+| `status` | What an agent owes, may still spend, and has settled | nothing, and needs no key |
+| `settle` | Pays down an Open Tab | real funds, and only with `--broadcast` |
+
+`settle` is a dry run unless you ask otherwise. It checks the Service accepts the Asset, quotes the amount, and stops:
+
+```bash
+npx -y @tabai/sdk settle \
+  --agent 0x1f6f…0542 \
+  --asset 10143:0x4802…4083 \
+  --service 0x7461…0000 \
+  --amount 47000
+```
+
+```
+Dry run. Nothing was broadcast.
+  chain id    10143
+  amount      47000
+
+Add --broadcast to send it. This spends real funds.
+```
+
+**Amounts are always base units.** USDC has six decimals, so `47000` is 0.047 USDC. Nothing in this system takes a decimal, holds a price, or consults a rate.
+
+`mcp` serves over stdio by default, and over streamable HTTP with `--http [--port <n>] [--host <h>] [--endpoint <p>]`.
+
+---
+
+## Configuration
+
+`doctor` warns when two things are missing, and both live in a config file rather than the environment, because neither is a secret: the agent whose Open Tab a call meters to, and where a Service can be reached.
+
+Put a `tab.config.mjs` beside your project, or in any parent directory:
+
+```js
+import { Wallet, JsonRpcProvider } from "ethers";
+import { createMonadStrategy } from "@tabai/sdk";
+
+export default {
+  // Whose Open Tab a metered call lands on.
+  agent: process.env.AGENT_ADDRESS,
+
+  registryUrl: process.env.NEXT_PUBLIC_REGISTRY_API_URL,
+
+  // The chain records no URL for a Service, deliberately, so the address lives here.
+  services: [
+    {
+      serviceId: "0x7461622e64656d6f000000000000000000000000000000000000000000000000",
+      name: "tab.demo",
+      endpoint: "http://localhost:8788",
+    },
+  ],
+
+  // The prepaid fallback, a factory for the same reason the strategies are.
+  // Called only when a Service has refused a call on credit and offered x402
+  // for it. Returning undefined declines, and the refusal stands as LIMIT_EXCEEDED.
+  x402: () =>
+    process.env.AGENT_PRIVATE_KEY === undefined
+      ? undefined
+      : new Wallet(process.env.AGENT_PRIVATE_KEY, new JsonRpcProvider(process.env.MONAD_RPC_URL)),
+
+  // A factory, not an object: the signer is built only if something settles,
+  // so every read stays keyless.
+  strategies: [
+    () => {
+      if (process.env.AGENT_PRIVATE_KEY === undefined) return undefined;
+      return createMonadStrategy({
+        signer: new Wallet(process.env.AGENT_PRIVATE_KEY, new JsonRpcProvider(process.env.MONAD_RPC_URL)),
+        tabSettlement: process.env.TAB_SETTLEMENT_ADDRESS,
+        assets: {
+          "10143:0x480209747417f5c830fda188a9b9acfa70bc4083": {
+            chainId: 10143n,
+            address: "0x480209747417f5c830fda188a9b9acfa70bc4083",
+            decimals: 6,
+            symbol: "mUSDC",
+          },
+        },
+      });
+    },
+  ],
+};
+```
+
+The key is read at the moment a Settlement is built, and never from this file. `tab_discover`, `tab_status` and `doctor` never call the factory, which is what keeps every read on this rail keyless.
+
+**A factory may decline.** Returning `undefined`, as the one above does when no key is set, means "not available here" rather than "this config is broken": the strategy is skipped and everything else in the file stands. That is the whole reason the entry is a factory rather than an object, and it lets one config file serve a read-only process and a settling one without branching.
+
+### Environment
+
+| Variable | Needed for |
+| --- | --- |
+| `MONAD_RPC_URL` | every read. The MCP server and `doctor` need only this |
+| `MONAD_CHAIN_ID` | `143` for Mainnet, `10143` for Testnet. Defaults to Testnet |
+| `TAB_BOOK_ADDRESS`, `TAB_SETTLEMENT_ADDRESS`, `SERVICE_REGISTRY_ADDRESS`, `BOND_ADDRESS` | resolving credit, Services and Bond |
+| `NEXT_PUBLIC_REGISTRY_API_URL` | the Service directory and an agent's history, if you use the read API rather than the chain |
+| `AGENT_PRIVATE_KEY` | broadcasting a Settlement, and nothing else. Never written to a configuration file |
+
+---
+
+## As a library
+
+Every export is typed, with the types shipped in the package. It carries no workspace dependency, so it installs and type-checks on its own.
+
+```ts
+import { createTabToolset, createTab402Client, createMonadStrategy } from "@tabai/sdk";
+```
+
+The main surfaces:
+
+| Import | What it is |
+| --- | --- |
+| `createTabToolset` | The four tools as plain functions, for embedding without MCP |
+| `createTabMcpServer` | The MCP server itself |
+| `createTab402Client` | An HTTP client that understands the post-paid `402` and its charge headers |
+| `tabPostPaid`, `honoTabPostPaid`, `expressTabPostPaid`, `withTabPostPaid` | Server plugins that meter a route after it has already responded |
+| `createTabProxy` | A reverse proxy that meters an upstream you do not control |
+| `createX402Client`, `signExactPayment` | The x402 side of the Agent: sign an EIP-3009 authorization for an `exact` requirement and repeat the request with it |
+| `handlePrepaidRequest`, `exactRequirementFor`, `createX402Facilitator` | The x402 side of a Service: offer a payment on a `402`, and take one through a facilitator |
+| `createX402FrontedProxy`, `createX402UpstreamPricing` | Buy now, pay later: front an x402 upstream, pay it, and meter the Agent |
+| `fetchHubManifest` | Monad's API Hub manifest, as tools of the Service fronting a provider |
+| `createMonadStrategy`, `createStrategyRegistry` | The Monad payment strategy, and the registry that resolves strategies |
+| `createKuruFundedStrategy`, `createKuruOnchainRouter` | Settle in any asset: swap the shortfall in through Kuru before the Monad strategy settles |
+| `revertMappingFor` | The single table mapping a contract revert to a category, code, disposition and remedy |
+
+### Running a metered Service
+
+Deliver first, charge after. The plugin adds exactly one status code to your surface, a `402` when a charge would exceed the caller's credit limit.
+
+```ts
+import { honoTabPostPaid } from "@tabai/sdk";
+
+app.use("/meter/*", honoTabPostPaid({ serviceId, priceOf, tabBook }));
+```
+
+Mount it under `/meter/`: `tab_call` sends a call to `<endpoint>/meter/<tool>`, so the endpoint in `tab.config` is the Service's root and `/hub/<prefix>` sits beside the tools.
+
+A gateway anyone can reach requires a signature on every metered call, and the Agent gives its own: put `headers: agentSignedMetering(agentSigner)` on the Service entry in `tab.config` and `tab_call` signs a digest of the method, path, Agent, tool, units and a timestamp with the Agent's key, sent as `Tab-Agent-Signature`. The key is built per call and never for a read, and it signs only when it is the Agent the call is metered against; for anyone else it adds nothing and the Service decides. A Service's own front can sign the same digest with the operator key instead.
+
+### Adding a strategy
+
+A strategy is how an agent pays. On Monad there is exactly one way, `TabSettlement.settle`, and the shipped strategy does that with an `ethers` signer. The seam still exists so that a different signer, a smart account, a session key, or a test double can stand behind the same call without the SDK caring which.
+
+```ts
+export interface PaymentStrategy {
+  readonly id: string;
+  readonly chainIds: readonly bigint[];
+  supports(asset: AssetRef): boolean;
+  quote(request: ChargeRequest): Promise<Result<ChargeQuote>>;
+  settle(request: SettleRequest): Promise<Result<SettlementReceipt>>;
+  settleBatch?(requests: readonly SettleRequest[]): Promise<Result<readonly SettlementReceipt[]>>;
+}
+```
+
+A receipt carries the transaction hash and, once the receipt is read, the `settlementId`, `applied` and `toPrepaid` figures straight off the `Settled` event. `settleBatch` maps onto `TabSettlement.settleBatch`, which settles several tabs in one transaction.
+
+---
+
+## x402: prepaid fallback and buy-now-pay-later
+
+x402 is the prepaid protocol: a server answers `402` with a `PAYMENT-REQUIRED` header naming what it accepts, the client signs a payment and repeats the request with `PAYMENT-SIGNATURE`, and the server returns the resource once a facilitator has settled the payment on chain. Tab is the opposite model, and this package makes the two meet in two places.
+
+**The offer on a credit refusal.** A Tab Service that refuses a call on `LimitExceeded` can put an x402 `exact` requirement for the same charge beside its `Tab-Charge-*` block. An Agent that would rather pay for that one call than settle its tab first takes the offer; one that would rather settle ignores it. When the offer is taken, the facilitator moves the Asset to the Service's Collection address, the work is delivered, and nothing lands on the Open Tab, because nothing is owed.
+
+```ts
+// A Service, on a Hono route
+const requirement = exactRequirementFor({ chainId: 10143n, asset, amount, payTo: collectionAddress });
+// On LimitExceeded: onLimitExceeded: (ctx) => jsonResponse(ctx.status, { ...ctx.headers, ...paymentRequiredHeaders(paymentRequiredFor({ resource, accepts: [requirement.value] })).value }, ctx.body)
+// On a request carrying PAYMENT-SIGNATURE:
+const outcome = await handlePrepaidRequest({ facilitator: createX402Facilitator(), payload, requirements: requirement.value, resource, deliver });
+```
+
+`handlePrepaidRequest` runs x402's default flow and no other: verify through the facilitator, deliver, settle through the facilitator, answer with `PAYMENT-RESPONSE`. A payment that does not verify is answered `402` with the reason and nothing is delivered; a delivery that failed is never settled, on the same rule the post-paid plugin meters no failed response. Monad's facilitator at `x402-facilitator.molandak.org` is the default and settles `exact` on Mainnet and Testnet.
+
+On the Agent's side, `createTab402Client` and `tab_call` take the offer when, and only when, an x402 signer is configured. The signer comes from `tab.config`'s `x402` entry, a factory called at the moment a refusal carries an offer and never before, so every read stays keyless. In the library client the repeat still happens first: a `402` is answered by one repeat, and only a `402` that stands after it and carries `PAYMENT-REQUIRED` is paid. `tab_call`, which never repeats, takes the offer on the first refusal, and reports the payment:
+
+```json
+{
+  "ok": true,
+  "result": { "quote": "42" },
+  "charge": { "amountBaseUnits": "10000", "asset": "10143:0x534b…43a3", "tool": "0x71…" },
+  "tab": { "openTabBaseUnits": "40000", "headroomBaseUnits": "500", "asset": "10143:0x534b…43a3" },
+  "x402": {
+    "txHash": "0xef…",
+    "network": "eip155:10143",
+    "amountBaseUnits": "10000",
+    "asset": "10143:0x534b…43a3",
+    "payTo": "0x9d3d…d837",
+    "payer": "0x19e7…ff2a",
+    "explorerUrl": "https://testnet.monadvision.com/tx/0xef…"
+  }
+}
+```
+
+`charge` and `tab` are the refusal the call was answered with; `x402` is what paid for it instead.
+
+**Buy now, pay later for x402 APIs.** The reverse direction is the one that changes what an Agent can do. A Tab Service can front any x402 upstream: the Agent calls the Service on credit, the Service pays the upstream with its operator's key, and the Service meters the Agent's Open Tab for the upstream's price plus a margin. The Agent never signs and never holds the upstream's currency.
+
+```ts
+const pricing = createX402UpstreamPricing({ tool, margin: { bps: 500n } });
+const metering = tabPostPaid({ serviceId, asset, tabBook, priceOf: pricing.priceOf });
+const proxy = createX402FrontedProxy({
+  upstream: "https://api.nansen.ai/api/v1",
+  stripPrefix: "/hub/nansen",
+  signer: operatorWallet,
+  asset,
+  pricing,
+  metering,
+  preflight: async ({ agent, amount }) => simulateDelivery(agent, amount),
+});
+app.all("/hub/nansen/*", (c) => proxy(c.req.raw));
+```
+
+The price is known only after the upstream's `402`, so `pricing` is a book the forward writes and `priceOf` reads, keyed by the request. **The amount rides in the unit count, not the unit price.** `TabBook.recordDelivery` refuses any unit price the applied price list does not hold, and a fronted price varies per call, so the Service publishes a small fixed unit for the fronted tool, one base unit by default, and a call consumes as many units as it cost. Without that published price every fronted delivery reverts `UnknownTool`, the plugin delivers anyway because a broken price list is the Service's fault, and the Service pays the upstream for work it bills nobody. `unitBaseUnits` sets a coarser unit, rounded up so the Service is never left short. `preflight` runs between the upstream's `402` and the operator's signature, with the quoted amount in hand: a Service simulates the delivery against `TabBook` there and refuses an Agent with no headroom before its own funds move. Only `exact` with EIP-3009 is signed, on the Service's own chain and Asset; an upstream that accepts nothing the Service can pay in is answered with why, and nothing is metered.
+
+`fetchHubManifest` reads Monad's API Hub, which fronts 74 pay-per-request providers behind one x402 endpoint, and `tab_discover` lists a fronted provider's endpoints under the Service as the tools they are, with the Hub's per-call price in base units:
+
+```js
+services: [{ serviceId, endpoint, hub: { provider: "defillama", prefix: "apihub" } }]
+```
+
+The reference metering gateway mounts both: `GATEWAY_HUB_UPSTREAMS` names the upstreams, `X402_ENABLED` and `X402_FACILITATOR_URL` govern the offer on a `402`, and `GATEWAY_COLLECTION_ADDRESS` is the `payTo` fallback when `ServiceRegistry.collectionOf` cannot be read.
+
+**What is official and what is not.** The types, the three header codecs and the facilitator HTTP client are `@x402/core`, the reference implementation. The EIP-3009 signing is this package's own, over ethers rather than the reference client's viem, and it is checked two ways: every test recovers the signer with `verifyTypedData`, and the reference client was run over the same authorization while this was written, producing the same signature byte for byte. The request handling is this package's own because the reference server middleware gates every request on payment, which is the model Tab exists to replace.
+
+### Settle in any asset through Kuru
+
+`TabSettlement.settle` moves the Asset the tab is denominated in. An Agent that holds MON, or a different stablecoin, can still settle: `createKuruFundedStrategy` wraps the Monad strategy, reads the Agent's balance of the Asset before every Settlement, and when it is short, swaps the shortfall in from a configured source token through Kuru, Monad's on-chain order book, then settles. The Settlement is still the inner strategy's transaction.
+
+```ts
+import { createKuruFundedStrategy, createKuruOnchainRouter, KURU_DEPLOYMENTS, KURU_NATIVE_TOKEN, kuruRouteKey } from "@tabai/sdk";
+
+const inner = createMonadStrategy({ signer, tabSettlement, assets });
+const strategy = createKuruFundedStrategy({
+  inner,
+  signer,
+  kuru: {
+    source: { address: KURU_NATIVE_TOKEN, decimals: 18, symbol: "MON" },
+    maxSourceAmount: 5n * 10n ** 18n,
+    router: createKuruOnchainRouter({
+      signer,
+      router: KURU_DEPLOYMENTS.mainnet.router,
+      routes: {
+        [kuruRouteKey(KURU_NATIVE_TOKEN, usdc.address)]: {
+          markets: [KURU_DEPLOYMENTS.mainnet.markets["MON-USDC"]],
+          isBuy: [false],
+          nativeSend: [true],
+        },
+      },
+      slippageBps: 100,
+    }),
+  },
+});
+```
+
+The swap runs through a `KuruRouter`, a two-method seam: `quote` says how much of the source token buys the shortfall, `swap` executes it. `createKuruOnchainRouter` is the shipped implementation over Kuru's `Router.anyToAnySwap`, quoting by simulation at the amount that will be sent and passing the shortfall as the swap's minimum out, so a Settlement is either fully funded or the swap reverts. A test hands in a fake router. The Router is deployed on Testnet and Mainnet; Kuru's aggregator is Mainnet only and is not used here, and neither is Kuru's own SDK, which pins ethers 5 and takes amounts as floating point.
+
+### Configuration keys
+
+| Key | Where | What it does |
+| --- | --- | --- |
+| `x402` | `tab.config` | A factory returning an x402 signer, or `undefined` to decline. Called only when a refusal carries an offer |
+| `services[].hub` | `tab.config` | `{ provider, prefix?, manifestUrl? }`: the API Hub provider a Service fronts, listed by `tab_discover` |
+| `x402` | `createTab402Client` | `{ signer, chainId?, asset?, maxAmount?, onPayment? }`: the same fallback, for the library client |
+| `upstreamPayment` | `createX402FrontedProxy` | `{ chainId, asset, signer? }`: where the upstream is paid when that is not the Service's own chain and Asset. The API Hub takes Mainnet USDC only, so a Testnet Service pays there and meters here, base unit for base unit |
+| `X402_ENABLED`, `X402_FACILITATOR_URL`, `GATEWAY_COLLECTION_ADDRESS`, `GATEWAY_HUB_UPSTREAMS`, `GATEWAY_X402_PRIVATE_KEY` | gateway environment | The offer on a `402`, the facilitator, the `payTo` fallback, the fronted upstreams (each with an optional `payOn: { chainId, asset }`), and an optional dedicated paying key |
+
+---
+
+## Network
+
+Tab is deployed on both Monad networks, and `MONAD_CHAIN_ID` picks which one this package talks to.
+
+| | Monad Mainnet | Monad Testnet |
+| --- | --- | --- |
+| Chain id | `143` | `10143` |
+| RPC | `https://rpc.monad.xyz` | `https://testnet-rpc.monad.xyz` |
+| Explorer | `https://monadvision.com` | `https://testnet.monadvision.com` |
+| Assets | USDC, AUSD | Circle's USDC, and `mUSDC`, a test token |
+
+| Contract | Mainnet | Testnet |
+| --- | --- | --- |
+| `ServiceRegistry` | `0x4F791F13F94944fCB2F884f8C7991cAa583884A6` | `0x3638DB35A76E5a22EA1E827636dA994be622c139` |
+| `Bond` | `0xbA86C0D053ba88afDECbED8aBa5b2eC3973fb230` | `0x29aDfD90Fc7c9026563Fc60651f696ab089080E7` |
+| `TabBook` | `0x0Dabf8E52280D0F128f546602a99b6DC4fbb80DC` | `0x87571030cCe27C84836bAfF85288eB1d85d908a4` |
+| `TabSettlement` | `0x32A96bfEABe766B4898b961B333B7B89f079a9a9` | `0x654Fac48185e4B71779eEc2457B1F24aEdf46717` |
+| `CurationMultisig` (2-of-3) | `0x123c19F46C38d5b4E922D1297250a71A03DFFD17` | |
+| `mUSDC` | | `0x480209747417f5c830fDA188a9b9AcFa70Bc4083` |
+
+Mainnet USDC is `0x754704Bc059F8C67012fEd69BC8A327a5aafb603` and AUSD is `0x00000000eFE302BEAA2b3e6e1b18d08D69a9012a`.
+Testnet USDC is `0x534b2f3A21130d7a60830c2Df862319e593943A3`, from Circle's faucet; MON for gas comes from `https://faucet.monad.xyz`.
+
+A Settlement is final when its block is. **Nothing in an agent's request path waits for anything**: a metered call completes immediately, and headroom is restored in the block the Settlement lands.
+
+---
+
+## Status
+
+The contracts are live on Mainnet and Testnet, and everything in this package runs against them today.
+A hosted read API, a public demo Service endpoint and a Dashboard are coming soon on Monad.
+Until then, `tab_discover` and `tab_status` need a Tab registry you point `registryUrl` at, and a Service's `endpoint` is wherever that Service runs.
+
+---
+
+## Built by
+
+Emad Qureshi. MIT licensed.

package/bin/tab.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * The `tab` executable.
+ *
+ * A thin shim over `runCli`, and thin on purpose: the CLI is ordinary library
+ * code in `src/cli/`, which is what lets the tests drive every command in
+ * process with an injected environment and injected input and output, instead of
+ * spawning a shell and parsing what comes back.
+ *
+ * The shim owns three things the library deliberately does not: reading
+ * `process.argv`, setting the exit code, and the last-resort handler. Nothing in
+ * `runCli` throws, so the `catch` is a backstop for a bug in this file or a
+ * failure to load the build at all.
+ */
+
+import { runCli } from "../dist/cli/main.js";
+
+try {
+  process.exitCode = await runCli(process.argv.slice(2));
+} catch (error) {
+  process.stderr.write(`tab: ${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+}

package/dist/_shared/abi.d.ts

@@ -0,0 +1,150 @@
+import type { Bytes32 } from "./hex.js";
+/**
+ * Canonical event signatures, the exact strings the topic hash is taken over.
+ * No spaces, no parameter names, canonical types.
+ */
+export declare const EVENT_SIGNATURES: {
+    /** `TabBook.SettlementApplied`: a Settlement lowered an Open Tab. `topics[1]` is the settlement id. */
+    readonly SettlementApplied: "SettlementApplied(bytes32,address,bytes32,address,uint256,uint256,uint128)";
+    /** `TabBook.DeliveryRecorded`: a Service metered usage into an Open Tab. `topics[1]` is the Agent. */
+    readonly DeliveryRecorded: "DeliveryRecorded(address,bytes32,address,bytes32,uint32,uint256,uint64)";
+    /** `TabBook.HistoryExtended`: the Agent's history commitment advanced by one record. */
+    readonly HistoryExtended: "HistoryExtended(address,address,bytes32,uint32,(bytes32,address,uint128,uint64,uint64,bool,bool))";
+    /** `TabBook.TabDelinquent`: a Settlement Window closed with the tab still open. */
+    readonly TabDelinquent: "TabDelinquent(bytes32,address,bytes32,address,uint128,uint64)";
+    /** `TabBook.TabDelinquencyCleared`: the delinquent tab settled to zero. */
+    readonly TabDelinquencyCleared: "TabDelinquencyCleared(bytes32,address,address)";
+    /** `TabSettlement.Settled`: the Asset moved from the Agent to the Service's Collection address. */
+    readonly Settled: "Settled(bytes32,address,bytes32,address,uint128,uint128,uint128,address)";
+    /**
+     * `TabSettlement.SettledGasless`: the Settlement arrived on the Agent's Permit2 signature and
+     * `topics[2]` is the relayer that paid for it. Always follows a `Settled` with the same id.
+     */
+    readonly SettledGasless: "SettledGasless(bytes32,address)";
+    /** `Bond.BondFunded`: stake entered the escrow. */
+    readonly BondFunded: "BondFunded(bytes32,address,uint128,address)";
+    /** `Bond.BondWithdrawn`: stake left the escrow. */
+    readonly BondWithdrawn: "BondWithdrawn(bytes32,address,uint128,address)";
+    /** ERC-20 `Transfer`, for reading balances and payouts off the Asset contract. */
+    readonly Transfer: "Transfer(address,address,uint256)";
+};
+/** Name of an event whose signature this module pins. */
+export type EventName = keyof typeof EVENT_SIGNATURES;
+/**
+ * `topics[0]` for each pinned event: the Keccak-256 hash of its canonical
+ * signature. Derived rather than transcribed, so a signature edit cannot leave a
+ * stale hash behind.
+ */
+export declare const EVENT_TOPIC0: Readonly<Record<EventName, Bytes32>>;
+/** `topics[0]` for a pinned event. */
+export declare const eventTopic0: (name: EventName) => Bytes32;
+/**
+ * The witness struct, exactly as `TabSettlement.WITNESS_TYPE` declares it.
+ * `surface` is the `TabSettlement` address and `chainId` the chain it lives on.
+ */
+export declare const TAB_SETTLEMENT_WITNESS_TYPE: "TabSettlement(bytes32 serviceId,address asset,uint128 amount,address surface,uint256 chainId)";
+/** `keccak256(TAB_SETTLEMENT_WITNESS_TYPE)`, the same value as `TabSettlement.WITNESS_TYPEHASH`. */
+export declare const TAB_SETTLEMENT_WITNESS_TYPEHASH: Bytes32;
+/**
+ * What the contract passes Permit2 as `witnessTypeString`, exactly as
+ * `TabSettlement.WITNESS_TYPE_STRING` declares it. Permit2 appends it to
+ * `PERMIT2_WITNESS_TRANSFER_FROM_STUB`.
+ */
+export declare const PERMIT2_WITNESS_TYPE_STRING: "TabSettlement witness)TabSettlement(bytes32 serviceId,address asset,uint128 amount,address surface,uint256 chainId)TokenPermissions(address token,uint256 amount)";
+/** Permit2's own `_PERMIT_TRANSFER_FROM_WITNESS_TYPEHASH_STUB`. */
+export declare const PERMIT2_WITNESS_TRANSFER_FROM_STUB: "PermitWitnessTransferFrom(TokenPermissions permitted,address spender,uint256 nonce,uint256 deadline,";
+/** The full primary type Permit2 hashes, and its typehash. */
+export declare const PERMIT2_WITNESS_TRANSFER_FROM_TYPE: "PermitWitnessTransferFrom(TokenPermissions permitted,address spender,uint256 nonce,uint256 deadline,TabSettlement witness)TabSettlement(bytes32 serviceId,address asset,uint128 amount,address surface,uint256 chainId)TokenPermissions(address token,uint256 amount)";
+export declare const PERMIT2_WITNESS_TRANSFER_FROM_TYPEHASH: Bytes32;
+/** Permit2's EIP-712 domain name. Its domain has no `version`. */
+export declare const PERMIT2_DOMAIN_NAME: "Permit2";
+/**
+ * The EIP-712 domain an Agent signs a gasless Settlement under: Permit2's, on
+ * the chain the Settlement happens on.
+ */
+export declare function permit2Domain(chainId: number | bigint, permit2: `0x${string}`): {
+    readonly name: "Permit2";
+    readonly chainId: bigint;
+    readonly verifyingContract: `0x${string}`;
+};
+/**
+ * The typed-data types for `signTypedData`, primary type
+ * `PermitWitnessTransferFrom`. Field order matches Permit2's stub and the
+ * witness type above; the referenced structs are what the type string names.
+ */
+export declare const PERMIT2_WITNESS_TRANSFER_FROM_TYPES: {
+    readonly PermitWitnessTransferFrom: readonly [{
+        readonly name: "permitted";
+        readonly type: "TokenPermissions";
+    }, {
+        readonly name: "spender";
+        readonly type: "address";
+    }, {
+        readonly name: "nonce";
+        readonly type: "uint256";
+    }, {
+        readonly name: "deadline";
+        readonly type: "uint256";
+    }, {
+        readonly name: "witness";
+        readonly type: "TabSettlement";
+    }];
+    readonly TokenPermissions: readonly [{
+        readonly name: "token";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly TabSettlement: readonly [{
+        readonly name: "serviceId";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "asset";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint128";
+    }, {
+        readonly name: "surface";
+        readonly type: "address";
+    }, {
+        readonly name: "chainId";
+        readonly type: "uint256";
+    }];
+};
+export declare const PERMIT2_WITNESS_TRANSFER_FROM_PRIMARY_TYPE: "PermitWitnessTransferFrom";
+/**
+ * The gasless entry point on `TabSettlement`, as a human-readable ABI fragment.
+ * `spender` in the signed message is the `TabSettlement` address and `witness`
+ * is `TabSettlement.witnessHash(serviceId, asset, amount)`.
+ */
+export declare const TAB_SETTLEMENT_PERMIT2_ABI: readonly ["function settleWithPermit2(address agent, bytes32 serviceId, address asset, uint128 amount, uint256 nonce, uint256 deadline, bytes signature) returns (bytes32 settlementId, uint128 applied, uint128 toPrepaid)", "function witnessHash(bytes32 serviceId, address asset, uint128 amount) view returns (bytes32)", "function WITNESS_TYPE_STRING() view returns (string)", "function WITNESS_TYPEHASH() view returns (bytes32)", "function PERMIT2() view returns (address)", "event SettledGasless(bytes32 indexed settlementId, address indexed relayer)"];
+/** The slice of Permit2 a signer or relayer touches, as human-readable ABI. */
+export declare const PERMIT2_ABI: readonly ["function DOMAIN_SEPARATOR() view returns (bytes32)", "function nonceBitmap(address owner, uint256 wordPosition) view returns (uint256)", "function invalidateUnorderedNonces(uint256 wordPos, uint256 mask)", "event UnorderedNonceInvalidation(address indexed owner, uint256 word, uint256 mask)"];
+/**
+ * The Identity Registry: an ERC-721 whose token id is the agentId, whose
+ * `tokenURI` is the agent's registration file, and whose `agentWallet`
+ * metadata is the account acting for the agent. `register` mints to the
+ * caller and records it as the wallet; ids are sequential from zero.
+ */
+export declare const ERC8004_IDENTITY_REGISTRY_ABI: readonly ["function register() returns (uint256 agentId)", "function register(string agentURI) returns (uint256 agentId)", "function register(string agentURI, (string metadataKey, bytes metadataValue)[] metadata) returns (uint256 agentId)", "function setAgentURI(uint256 agentId, string newURI)", "function tokenURI(uint256 tokenId) view returns (string)", "function ownerOf(uint256 tokenId) view returns (address)", "function balanceOf(address owner) view returns (uint256)", "function getAgentWallet(uint256 agentId) view returns (address)", "function getMetadata(uint256 agentId, string metadataKey) view returns (bytes)", "function setMetadata(uint256 agentId, string metadataKey, bytes metadataValue)", "function isAuthorizedOrOwner(address spender, uint256 agentId) view returns (bool)", "function getVersion() pure returns (string)", "event Registered(uint256 indexed agentId, string agentURI, address indexed owner)", "event URIUpdated(uint256 indexed agentId, string newURI, address indexed updatedBy)", "event MetadataSet(uint256 indexed agentId, string indexed indexedMetadataKey, string metadataKey, bytes metadataValue)", "event Transfer(address indexed from, address indexed to, uint256 indexed tokenId)"];
+/**
+ * The Reputation Registry: feedback about an agent, keyed by agentId and the
+ * client that gave it, 1-indexed per client. An agent's owner or operator
+ * cannot give feedback about it.
+ */
+export declare const ERC8004_REPUTATION_REGISTRY_ABI: readonly ["function giveFeedback(uint256 agentId, int128 value, uint8 valueDecimals, string tag1, string tag2, string endpoint, string feedbackURI, bytes32 feedbackHash)", "function revokeFeedback(uint256 agentId, uint64 feedbackIndex)", "function appendResponse(uint256 agentId, address clientAddress, uint64 feedbackIndex, string responseURI, bytes32 responseHash)", "function getSummary(uint256 agentId, address[] clientAddresses, string tag1, string tag2) view returns (uint64 count, int128 summaryValue, uint8 summaryValueDecimals)", "function readFeedback(uint256 agentId, address clientAddress, uint64 feedbackIndex) view returns (int128 value, uint8 valueDecimals, string tag1, string tag2, bool isRevoked)", "function readAllFeedback(uint256 agentId, address[] clientAddresses, string tag1, string tag2, bool includeRevoked) view returns (address[] clients, uint64[] feedbackIndexes, int128[] values, uint8[] valueDecimals, string[] tag1s, string[] tag2s, bool[] revokedStatuses)", "function getLastIndex(uint256 agentId, address clientAddress) view returns (uint64)", "function getClients(uint256 agentId) view returns (address[])", "function getIdentityRegistry() view returns (address)", "function getVersion() pure returns (string)", "event NewFeedback(uint256 indexed agentId, address indexed clientAddress, uint64 feedbackIndex, int128 value, uint8 valueDecimals, string indexed indexedTag1, string tag1, string tag2, string endpoint, string feedbackURI, bytes32 feedbackHash)", "event FeedbackRevoked(uint256 indexed agentId, address indexed clientAddress, uint64 indexed feedbackIndex)", "event ResponseAppended(uint256 indexed agentId, address indexed clientAddress, uint64 feedbackIndex, address indexed responder, string responseURI, bytes32 responseHash)"];
+/** Canonical ERC-8004 event signatures, for topic filters. */
+export declare const ERC8004_EVENT_SIGNATURES: {
+    readonly Registered: "Registered(uint256,string,address)";
+    readonly URIUpdated: "URIUpdated(uint256,string,address)";
+    readonly MetadataSet: "MetadataSet(uint256,string,string,bytes)";
+    readonly NewFeedback: "NewFeedback(uint256,address,uint64,int128,uint8,string,string,string,string,string,bytes32)";
+    readonly FeedbackRevoked: "FeedbackRevoked(uint256,address,uint64)";
+    readonly ResponseAppended: "ResponseAppended(uint256,address,uint64,address,string,bytes32)";
+};
+export type Erc8004EventName = keyof typeof ERC8004_EVENT_SIGNATURES;
+/** `topics[0]` for each ERC-8004 event, derived from its canonical signature. */
+export declare const ERC8004_EVENT_TOPIC0: Readonly<Record<Erc8004EventName, Bytes32>>;
+//# sourceMappingURL=abi.d.ts.map

package/dist/_shared/abi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abi.d.ts","sourceRoot":"","sources":["../src/abi.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAExC;;;GAGG;AACH,eAAO,MAAM,gBAAgB;IAC3B,uGAAuG;;IAEvG,sGAAsG;;IAEtG,wFAAwF;;IAGxF,mFAAmF;;IAEnF,2EAA2E;;IAE3E,mGAAmG;;IAEnG;;;OAGG;;IAEH,mDAAmD;;IAEnD,mDAAmD;;IAEnD,kFAAkF;;CAE1E,CAAC;AAEX,yDAAyD;AACzD,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,gBAAgB,CAAC;AAEtD;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,CAE/B,CAAC;AAEhC,sCAAsC;AACtC,eAAO,MAAM,WAAW,GAAI,MAAM,SAAS,KAAG,OAA6B,CAAC;AAY5E;;;GAGG;AACH,eAAO,MAAM,2BAA2B,EACtC,+FAAwG,CAAC;AAE3G,oGAAoG;AACpG,eAAO,MAAM,+BAA+B,EAAE,OAAqD,CAAC;AAEpG;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,qKACuE,CAAC;AAEhH,mEAAmE;AACnE,eAAO,MAAM,kCAAkC,EAC7C,sGAA+G,CAAC;AAElH,8DAA8D;AAC9D,eAAO,MAAM,kCAAkC,yQACiC,CAAC;AACjF,eAAO,MAAM,sCAAsC,EAAE,OAEpD,CAAC;AAEF,kEAAkE;AAClE,eAAO,MAAM,mBAAmB,EAAG,SAAkB,CAAC;AAEtD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,EAAE,KAAK,MAAM,EAAE;;;;EAM7E;AAED;;;;GAIG;AACH,eAAO,MAAM,mCAAmC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmBtC,CAAC;AAEX,eAAO,MAAM,0CAA0C,EAAG,2BAAoC,CAAC;AAE/F;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,0iBAO7B,CAAC;AAEX,+EAA+E;AAC/E,eAAO,MAAM,WAAW,iTAKd,CAAC;AAWX;;;;;GAKG;AACH,eAAO,MAAM,6BAA6B,qsCAiBhC,CAAC;AAEX;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,mvDAclC,CAAC;AAEX,8DAA8D;AAC9D,eAAO,MAAM,wBAAwB;;;;;;;CAO3B,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,wBAAwB,CAAC;AAErE,iFAAiF;AACjF,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAEvC,CAAC"}