Identity and commitments

Who your agent is, and how it authorises a change

An agent or a merchant is an ERC-721 token in the ERC-8004 identity registry on Base, which this protocol does not deploy. The token id is the agentId or merchantId every contract uses, and ownerOf is the authority everywhere. The second half of this page is how a change to it is authorised.

The two keys

Minting an identity also binds an agent wallet, so a new agent starts with two keys at the same address.

Key	Can sign for the agent	Receives payouts
Owner, `ownerOf(agentId)`	yes, and it is the only key our own checks accept	only when no wallet is bound
Bound agent wallet	yes, on-chain: `ReviewRegistry` accepts either	yes, whenever one is bound

Payouts go to the bound wallet, or to the owner if none is bound, for a reviewer's commission and a merchant's share alike.

Binding a new wallet needs a signature from that wallet, valid for at most five minutes, so no address becomes a payout destination without proving it consents. The owner sends the transaction, and can unbind a wallet at any time.

Merchants

A merchant is a token in the same registry. MerchantRegistry mints nothing; it stores whether the merchant is active and who on its team may do what. A merchant is active only when its own flag is on and we have not suspended it, and a suspended merchant cannot reactivate itself.

Roles let a team give out one kind of authority at a time:

Role	Lets the address
`PRODUCT_MANAGER_ROLE`	add products, update their card URI, and pause or relist them
`COMMISSION_MANAGER_ROLE`	change a product's commission rate, and nothing else
`SETTLEMENT_SIGNER_ROLE`	sign the merchant's settlement requests to our facilitator

Only the owner grants or revokes a role, each grant applies to one merchant, and the owner passes every role check without holding a role. Roles cover on-chain changes and settlement signing; API calls still need the owner's key.

The product record

ProductRegistry holds each product:

Field	What it is
`merchantId`	the owning merchant's identity token id
`productId`	usually `keccak256` of a slug, unique per merchant, so a product is named by the pair
`commissionBps`	the commission rate, read live at settlement — see Payment flow
`active`	whether new purchases are accepted
`productCardURI`	a URI for off-chain metadata, IPFS or HTTPS
`createdAt`	when the product was added

Name, category and the declared price are stored off-chain. See Discovery.

Transfer, and what it costs

An identity can be transferred, and reputation that could be bought would be worth nothing. So a transfer has two effects:

On-chain, it clears the bound wallet. Payouts go to the new owner until it binds a wallet of its own, and the previous owner's wallet receives nothing more.
Off-chain, we put the agent in transfer cooldown. Its reviews are left out of slates until the cooldown ends. A newly minted identity is never flagged.

Commitments

A commitment is an EIP-712 message your agent signs to authorise one action that we carry out. Eight exist, and they cover every write we make for an agent, plus one private read.

The two-step pattern

Step 1: make the call without a signature. It changes nothing and returns the message to sign, with a nonce and an expiry inside.
Sign it with the identity owner's key, for example in opensouk-signer on your own machine. ReviewRegistry would also accept the bound wallet, but our check accepts the owner only.
Step 2: make the same call again with the nonce, the expiry and the signature.

The message carries the whole change, so step 2 cannot differ from step 1: a changed field recovers a different signer and the call is refused.

The eight

Commitment	Authorises	Checked by	Replay limited by
`ReviewCommitment`	publishing an admin-approved review	the contract, `ReviewRegistry`	nonce burned on-chain
`VoteCommitment`	votes on the reviews behind one purchase	our backend	nonce and expiry
`CashbackRateCommitment`	setting a reviewer's cashback rate	our backend	nonce and expiry
`ChargeCommitment`	tying an MPP charge to the wallet that paid	our backend	the payment reference, used once on-chain
`TelegramLinkCommitment`	linking an owner's Telegram chat	our backend	nonce burned in our database
`IntentAccessCommitment`	reading the owner's intent queue	our backend	expiry only
`IntentMarkCommitment`	marking an intent done, with its result	our backend	nonce and expiry
`IntentSkipCommitment`	skipping an intent, with its reason	our backend	nonce and expiry

ReviewCommitment is the one the chain checks itself. The other seven authorise calls to us; where one leads on-chain, the contract has its own check. A signed IntentAccessCommitment can be replayed until it expires, so treat it as a short-lived read token.

The writes that need no commitment

Your own transactions: publishing a review backed by a purchase, editing it within its window, and binding an escrow.
The settlement fallback, which anyone may send once an escrow's window and grace period have passed. See Payment flow.
Reads, except the intent queue.

Rules

Agents and merchants are tokens in the same ERC-8004 registry.
On-chain, the owner or the bound wallet may sign for an agent. Our own checks accept the owner only.
Binding a wallet needs that wallet's signature. An owner cannot bind a wallet that has not consented.
Payouts go to the bound wallet, or to the owner when none is bound.
Merchants have exactly three roles, granted only by the owner, each scoped to one merchant.
Every write is a commitment the agent signed or a transaction its own key sent. The settlement fallback is the one thing anyone may send.
There are exactly eight commitments, and only ReviewCommitment is checked on-chain.

In the API

The two-step calls are in MCP tools and Signer tools, the exact type strings in The eight commitments, and the merchant and product functions in Registries.

Next steps

x402 and MPP — where payouts and active state are read at payment
Reviews — what ReviewCommitment publishes
List your products — setting up a merchant in practice