Reader

nablaz-sdk

An open-source reader for agent payment permissions. It rebuilds, from public chain data, what an address was allowed to spend, what it spent, and under which terms, and keeps every fact next to the command that reproduces it. It reads the NablaZ record and grantee vaults, Coinbase spend permissions, MetaMask delegations and Agent Credit Lines.

It holds no keys, needs no account or API key, and runs anywhere you have an RPC endpoint.

What it reads

Arbitrum One and Base are both enabled. The NablaZ contracts are live on Arbitrum One only, so on Base the reader indexes the third-party sources alone.

Third-party sources, on both chains:

• Coinbase SpendPermissionManager: SpendPermissionApproved, SpendPermissionUsed, SpendPermissionRevoked.
• MetaMask DelegationManager (delegation framework v1.3.0): RedeemedDelegation, with every caveat decoded. For each redemption the reader reads the transaction receipt and keeps the ERC-20 Transfers sent by the delegator. A redemption alone is not a payment; only such a Transfer is.
• Agent Credit Lines (Borrowed, Repaid, Defaulted) at a configured lender. No lender is known on either chain today, so no lender is registered. The decoder ships with tests, and a read with nothing indexed says "nothing indexed" with its block range.
• ERC-8004: NewFeedback from the "Reputation Registry" (who rated which agentId, and where; never the feedback's value, decimals, tags, endpoint or URIs), and the agentWallet and owner histories from the Identity Registry's MetadataSet and ERC-721 Transfer. Addresses from src/generated/erc8004.json (vendor commit pinned there).

NablaZ sources, where deployed:

• RecordEntry from NablaRecord, every field.
• AccountCreated from NablaAccountFactoryPermanent and AccountRegistryV6, to discover accounts.
• ERC-1967 Upgraded on every discovered account proxy.
• USDC AuthorizationUsed and Transfer where the authorizer or sender is a grantee vault. Vaults are discovered from logs alone: the PAY_AUTHORIZED entry names the vault, and the funding Transfer in the same transaction confirms it.

What it writes

Rows hold facts and counts. The reader states facts and passes no judgement on any subject.

In vault_payments, the party that submitted the settlement transaction (tx.from) is recorded as submitter. It is never treated as the counterparty; the counterparty is the Transfer recipient.

A settlement writes no NablaRecord entry. A payment's record is two parts, paired by the reader: the PAY_AUTHORIZED entry the account wrote when it reserved funds into the grantee vault (the reservation, in record_entries), and USDC's own AuthorizationUsed and Transfer events (the settlement, one vault_payments row). A citation of a payment cites both: the PAY_AUTHORIZED log (block, transaction hash, log index) and the USDC settlement transaction and its block.

Citation rule

The logs are the ground truth; this reader is a convenience over them. Every row carries the chain id, block number, transaction hash and log index of its evidence, plus a cast logs command and the equivalent raw eth_getLogs request that return that log from any RPC. A row you cannot reproduce from its command is a bug.

One field is a state read, not a log: the envelope expiry in vault_payments. It is labelled "state read — needs archive RPC". The reader calls envelopeOf(account, granteeKey, token) on the account's mandate at block N−1 and at the settlement block N, and stores both calls as cast call --block commands. If the two reads agree, the value is stored. If they differ, the envelope changed within block N, and the field is stored as "not determinable" with both reads cited. On 2026-10-23, the same historical eth_call at 50,000 blocks below head answered 6 of 10 times through https://arb1.arbitrum.io/rpc, and the other 4 returned "historical state … is not available", so a public endpoint cannot be relied on for this field. Everything else rebuilds from logs on any RPC.

Read

GET /read/:chainId/:address returns every indexed fact about an address. No key is needed: the endpoint is a read over public logs.

{ "subject": "0x…", "chainId": 8453, "asOfBlock": "53160200",

"facts": [ { "source": "metamask:delegation_payment", "label": "(b) exact execution, once", "shape": "b", "terms": { "payer": "0x…", "payee": "0x…", "token": "0x…", "amount": "…" }, "cite": { "chainId": 8453, "block": "…", "tx": "0x…", "logIndex": 0 }, "reproduce": "cast receipt 0x… --rpc-url \"$BASE_RPC_URL\" --json | jq …" } ], "selfDealing": null, "exposure": null, "cShare": { "chainId": 8453, "asOfBlock": "53160200", "byToken": { "0x…": { "count": { "c": 0, "total": 1 }, "value": { "c": "0", "total": "…" } } } }, "notes": [ "no Agent Credit Lines lender registered on this chain", "SpendPermissionManager permissions and spends for this address: nothing indexed (blocks 53160000..53160200)" ] }

• facts: one per record entry, vault payment, spend permission, delegation, payment, redemption and credit-line event. Each names its source and carries a permission label, the block, transaction and log index, and the one-line command that returns the same log from any RPC.
• selfDealing (NablaZ accounts only): distinct counterparties paid, share of value paid to accounts under the same controller, share paid to counterparties with no record, and the sentence "A payee controlled by the same person under another key cannot be detected from chain data."
• exposure (NablaZ accounts only): per grant and token, the least remaining allowance across windows plus the vault balance, with the limit that outstanding authorizations are not observable onchain.
• cShare: per token, the count and value of this read's payment facts labelled (c), over all of them; never summed across tokens.
• notes: every source that returned nothing ("nothing indexed (blocks X..Y)", or "indexed up to X; source starts at Y" while the indexer is below the source's start), and every fact that is not determinable, stated as text.

Every permission label has one of five shapes:

The MetaMask enforcer table is generated from the vendor's Deployments.md at a pinned commit (scripts/gen-enforcers.ts, src/generated/enforcers.json). A test fails when the vendor's main branch lists an enforcer the table lacks.

One-liners are the ground truth. The reader is a convenience over the logs. Each reproduce field is a cast command you can run yourself with an RPC URL in $ARB_ONE_RPC_URL or $BASE_RPC_URL.

Feedback grounding

When the subject has been the agentWallet or the owner of an ERC-8004 agentId, every NewFeedback about that agentId becomes an erc8004:feedback_grounding fact (R-D2B-2). A feedback is grounded when an ERC-20 Transfer from the rater to the identity's payment address settled before it (by block, then by log index within a block), whatever the token or route (R-S191-11). The payment address is resolved at the transfer's block, never later: getAgentWallet there, else ownerOf there, and the fact says which binding applied (R-S191-16). A transfer made before the identity existed does not ground ("identity did not exist at the payment block"). The wallet at the feedback block is reported beside the grounding ("wallet at feedback: " or "wallet at feedback: cleared") and is never the test (R-S191-12).

Plain transfers are not indexed. At read time the reader calls eth_getLogs with topic0 = Transfer and topic1 = the rater, any token address, from the Identity Registry's start block (or the instance's start) to the feedback block, and states that range in the fact. Candidates are the addresses in the identity's agentWallet history (MetadataSet) and owner history (ERC-721 Transfer), each confirmed at the transfer's block. A settlement from the rater's own grantee vault is a payment from the rater (R-S191-17). Native-token transfers are not read ("native-token transfers not read", R-S191-18). A transfer that is one of the reader's payment facts keeps its permission label; any other is labelled (c) with reason "direct transfer, no permission object". The fact also says whether the rater is the subject, and whether the two share a controller when both are NablaZ accounts. It carries no value, decimals, tags or URIs, and the feedback file is not fetched ("feedbackURI not read").

test/fork/afg.fork.test.ts runs this grounding on the 816 grounded feedback entries in Agentic Finance Graph's Base fixture (CC BY 4.0, see NOTICE) and writes the comparison to docs/reader/afg-agreement-2026-10-20.csv. docs/reader/retroactive-binding-2026-10.md describes the remaining disagreements.

Hosted read

https://read.nablaz.io runs the reader and the MCP server below as one instance, on both home chains (chain IDs 42161 and 8453), with every source indexed from its deployment block. It is keyless and reads only. It has two doors:

• GET https://read.nablaz.io/read/:chainId/:address: the JSON a local GET /read returns.
• POST https://read.nablaz.io/mcp: the MCP server's Streamable HTTP transport, with its one tool, read_subject. For an MCP client that takes a URL: { "type": "http", "url": "https://read.nablaz.io/mcp" }.

Both doors are rate-limited per client IP; a request over the limit gets 429 with a plain-text body. Beside them, GET /live (the process is up) answers with a status code and a short text, and GET /ready (the index has caught up) answers HTTP 200 with an empty body when ready, and 503 with {"ready":false} when not; nothing else is s