{/* GENERATED at build time from the repo's CHANGELOG.md — do not edit. */}
Changelog
Notable changes to @altananetwork/sdk, @altananetwork/mcp,
@altananetwork/x402-server and @altananetwork/hypersigner-keystore-mcp.
Format based on Keep a Changelog.
Versions below are the @altananetwork/sdk version; the matching
@altananetwork/mcp version is noted where it differs.
From 1.0.0 the sdk and mcp packages follow semantic versioning: a breaking
change is a major version. @altananetwork/x402-server and
@altananetwork/hypersigner-keystore-mcp are still 0.x, where a minor
version may contain breaking changes.
This changelog starts at 0.7.0. Entries for earlier versions were reconstructed from commit history after the fact, so they summarize what shipped rather than itemizing every change.
[1.1.0] - 2026-11-18
@altananetwork/mcp 1.1.0, @altananetwork/x402-server 0.4.0
Added
-
A new wallet gets its agent identity (ERC-8004) by itself. After a wallet's first admin action has confirmed, the SDK registers the wallet in the chain's agent registry, in a transaction of its own. On by default, on BNB Chain, Celo and their testnets, after
executeorgrantSession, whichever is the wallet's first action.- The record is stored onchain: "Altana Agent", the Altana icon, and a link
to the wallet's page on the Altana explorer.
agentIdentity: { name, description, image, endpoint }oncreateClient, or on a single call, replaces any of them.agentIdentity: falseturns it off. - A KeyStore registration never depends on it. The agent registration never
shares a transaction with one: it is sent only after the wallet's action
has confirmed, and a failure is reported on the result and never thrown.
ExecuteResult.agentIdentityandGrantSessionResult.agentIdentitiescarryregistered(with the agent's number and transaction),skippedorfailed. - Only a wallet that is new on the chain is registered, once. A wallet that
owns an agent already is left as it is. A passkey wallet approves each
transaction, so it is not sent a second one:
client.registerAgentIdentityregisters it when the app chooses to ask. - Every registration carries the onchain tag
createdWith = altana(ALTANA_AGENT_TAG).agentPageUrl(chainId, agentId)is the agent's page on 8004scan, anderc8004AgentCountreads how many agents a wallet owns. @altananetwork/mcp: tool answers carry the agent's number and page,erc8004_registeron a wallet that has its agent updates that agent instead of creating a second one, andALTANA_AGENT_IDENTITY=offturns the automatic registration off.
- The record is stored onchain: "Altana Agent", the Altana icon, and a link
to the wallet's page on the Altana explorer.
-
@altananetwork/x402-server:USAT_CELO, USA₮ on Celo mainnet. Tether America USD at0xD2ab3C9A02DBBAB236BfEC45D1d755DF4267F771, 6 decimals, EIP-712 domainTether America USD/1, on the eip3009 and permit2-exact rails. The name, version and decimals were read from the token, and a unit test recomputes the domain separator of every Celo mainnet token config against the value the token reports. -
@altananetwork/mcp:grant_sessioncan set a session up to pay x402 requests. The newx402Tokensinput (one token address or a list) makes the approvals an x402 payment needs in the same transaction as the grant: each token approved to Permit2, and the token and Permit2 approved as signature checkers for the session key. Before this,x402_requestneeded approvals that no MCP tool could make. x402 payments are signed rather than sent by the session, so its daily spend caps do not bound them. -
fetchWithX402discovers canonical x402 v2 header challenges. A presentPAYMENT-REQUIREDheader supplies the complete version, resource and payment options, even with an empty or non-JSON response body. Malformed or unsupported header challenges fail before signing instead of falling back to conflicting body instructions. When the header is absent, legacy v1, v2 and B402 body challenges keep working. Each call still signs and retries at most once.
Fixed
-
A wallet short of the chain's currency for a registration is told so, on every chain and whatever token it pays the relay in. A KeyStore registration is paid in the chain's own currency, as value the request sends. A wallet that named a stablecoin as its fee token and held too little CELO for the registration was told "This could not be carried out, and the relay gave no reason", because it held plenty of the token it named. The error is now
insufficient_funds: "Not enough CELO for the registration: needs about 9.2 CELO, you have 3 CELO. Add CELO on Celo." The same request paid in the chain's own currency said "Not enough BNB to pay for this"; it now says "Not enough BNB for the registration" too, on BNB Smart Chain, Ethereum and Celo.FundingShortfallgains an optionalpurpose: "registration"for an app that lays the sentence out itself. A shortfall that is not a registration keeps its wording. -
@altananetwork/mcp:grant_sessionstores the session key before it sends the grant. The key was stored after the grant confirmed, so a keychain write that failed left a paid, authorized key that nobody held. The key is now stored first and removed again if the grant fails. -
@altananetwork/x402-server: several tokens on the eip3009 rail each settle on their own contract. A merchant listing more than one eip3009 token verified a payment against the right token and then settled it on the first eip3009 rail, so a USD₮ payment on a merchant that also listed USDC was sent to the USDC contract and refused with "invalid signature". Settlement now resolves the rail from the payment's token, the same way verification does. A merchant with one eip3009 token is unaffected. -
USD₮ on Celo and Celo Sepolia serves the eip3009 rail. The token configs and docs said it was permit2-exact only. Both tokens accept
transferWithAuthorization, and a Celo mainnet fork test now settles USDC, USD₮ and USA₮ on that rail.
[1.0.0] - 2026-11-17
@altananetwork/mcp 1.0.0, @altananetwork/x402-server 0.3.0,
@altananetwork/hypersigner-keystore-mcp 0.3.0
Upgrading from 0.9.0
Code written for 0.9.0 compiles and runs against 1.0.0; CI installs the packed packages and compiles such a script on every pull request. What behaves differently:
- Revoke.
client.revokeSessionrevokes on every chain of the client that holds the key, throws aSessionRevokeErrorwhen it failed on the chain the call answers for, and reportsstatus: "revoked", not"CONFIRMED". - Grant result.
GrantSessionResultgainsstatus,legs,registrationandcacheSync. On BNB Chain and Ethereum nothing else changes. On a network that mirrors another chain's Keystore (Base Sepolia) the call returns once the account authorized the key; the Keystore write and the cache proof finish in the background. - Errors. A relay failure is thrown as an
AltanaErrorwith acodeand one plain sentence; the relay's own words are onrelayMessageandcause. Branch oncode, not on message text. execute. A bundle the relay refused with no receipt throws instead of returningFAILED.- Fee token. With no
feeTokenthe relay charges whichever accepted token the wallet holds. On BNB Chain and Ethereum that is still the native token; on Celo it can be CELO, USDC or USDT. The Keystore registration fee is always paid in the chain's native token. - x402.
signX402Paymentsigns a v2 envelope when the requirement names no version.fetchWithX402reads the session's approvals first and refuses when one is missing (checkApprovals: falseskips the reads). @altananetwork/x402-server. A payment that was broadcast but whose receipt could not be read is answered200withsettlement: "pending", not402. Deliver on"confirmed"if delivery must wait for the chain.fundNativealways throws; fund wallets from a faucet or your own wallet.- MCP.
deadlineMinutesmust be positive,revoke_sessionrevokes on every chain of the environment that holds the key, and a failed grant is not saved as a session. - Licence.
@altananetwork/x402-serverand@altananetwork/hypersigner-keystore-mcpare Apache-2.0, as the sdk and mcp packages already were.
Breaking
- Session grant and revoke report per chain; a grant still goes to one
chain.
client.grantSessiongrants on one chain,chainIdor the client's default chain, as in 0.9.0: it returnstransactionHashand throws when the account on that chain did not authorize the key (the original error, orSession grant did not confirm: status=<STATUS>). PasschainIds: number[]instead to grant on several chains in one call; that form does not throw for a failed chain. Calls written for 0.9.0 keep working unchanged. New inGrantSessionResult:keyId,keyHash,status: "granted" | "failed",legs(one per step per chain),registrationandcacheSync; on an L2 a result withstatus: "failed"is a live key whose Keystore write or cache proof is left.client.revokeSessionrevokes on every chain of the client that holds the key. It still acceptschainId(deprecated: it names the chain the call answers for, default the client's default chain, and does not narrow the revoke), returnstransactionHashfor that chain, and throws aSessionRevokeErrorwhen the revoke failed there instead of returningstatus: "FAILED". Its result is now{ keyId, status: "revoked" | "failed", legs, cacheSync }rather than anExecuteResult:statusno longer reads"CONFIRMED", so code that waits for that value must compare against"revoked". The low-levelgrantSession/revokeSessionfunctions take{ networks }instead of{ network }and never throw for a failed leg.onStatusreceives the chain as a second argument.
Added
-
Celo and Celo Sepolia, each with its own KeyStore.
CELO(chain 42220) andCELO_SEPOLIA(chain 11142220) are execution networks whose KeyStore is on the chain itself, as on BNB Chain: a grant registers the key and authorizes it in one relay transaction, a revoke undoes both in one, and the registration fee is paid in CELO. The relay on Celo takes its own fee in CELO, USDC or USDT. A wallet created for Celo is also set up on Ethereum (Sepolia on testnet), through the newNetworkConfig.provisionAlso, so a passkey wallet can act there later. A wallet that lacks the CELO for a registration is told what it needs and has, and asked for CELO only.@altananetwork/mcp(ALTANA_CHAIN=celo,celo-sepolia) and@altananetwork/hypersigner-keystore-mcpread and encode against Celo's KeyStore. Covered by unit tests, thefork:celo-keystorefork test against the deployed contracts and thesmoke:celo-sepolialive test. -
proofRpcUrlsonNetworkConfig. A cache proof is built at the block the L2 anchors, about 100 blocks behind the registry chain's head, and Ethereum's default public RPC does not serveeth_getProofthere.ETHEREUM.proofRpcUrlslists endpoints that do;syncSessionToCache,grantSession,revokeSessionand the session quotes try them in order and thenpublicRpcUrl. Set your own list on the registry network, or keep passingl1Client. Networks without the field read frompublicRpcUrlas before. -
quoteExecute.client.quoteExecute(and the standalonequoteExecute) takes the same options asexecuteand returns the relay's quote for those exact calls without sending them: the maximum fee, the token it is charged in, the native value the calls carry and any shortfall. Size a "send everything" call as balance minus the quoted fee instead of guessing. -
ERC-8004 agent identity on Celo. The identity registry is now its own address record,
ERC8004_ADDRESSES, read witherc8004Registry(chainId), and it carries Celo (42220,0x8004A169…) and Celo Sepolia (11142220,0x8004A818…) alongside BNB Chain and BNB testnet. Every entry point and the MCP tools built on them therefore work on Celo:registerErc8004Agent,setErc8004AgentUri,getErc8004Agent,erc8004RegisterPermissionsand the two call builders. The registry moved out ofERC8183_ADDRESSESbecause Celo has the registry and none of the ERC-8183 job-escrow stack;Erc8183Addresses.registrystill names the same contract and now reads it from the new record, so the two cannot drift. -
@altananetwork/x402-server: settle through a hosted facilitator.facilitatorServicepoints a merchant at one, which broadcasts the payment and pays the gas, so a merchant can take payments without an RPC or a funded key. Celo runs the one its own documentation points at:CELO_FACILITATOR_URL(42220) andCELO_SEPOLIA_FACILITATOR_URL(11142220);facilitatorSupportedreads its openGET /supportedandsupportsExactOnanswers whether it serves a chain. The choice is per rail:facilitatorService.railsdecides what goes there and everything else settles from the merchant's key, so one route covers both paths.facilitatorRailsandfacilitatorAssetsread what a facilitator claims per asset fromGET /supported— Celo's mainnet facilitator listseip3009for USDC, USDT and USAT andpermit2for wARS, wBRL and wCOP — and the new receipt fieldsettledVia("facilitator"or"merchant") reports which route settled a payment, so a seller states the route instead of inferring it from the rail. Verification stays local either way, since the merchant's own is ERC-1271-aware and a facilitator's need not be.POST /settleneeds anX-API-Key, and a 401 says so rather than looking like a rejected payment. -
@altananetwork/hypersigner-keystore-mcp: an L1 key, readable on an L2. The server encoded L1 KeyStore calls only, so an authorize, a timebox or a revoke it produced was invisible to anything on the L2: an L2 rooted in the KeyStore reads authority through aKeyStoreCache, and the cache knows only what someone has proven into it.keystore_cache_statusreads that cache and separates the three states a caller otherwise conflates: never proven, proven at the block the L2 anchors, and proven at another one. The third matters becauseisValidKeyanswers only for the anchored block, so one anchor update makes a correct entry read as not valid until a fresh proof lands. Andkeystore_encode_cache_proofreturns the unsignedpopulateKeycall that carries the key's current L1 state across. Relaying is permissionless, so any funded L2 account can send it for any user, and the server still signs nothing. An L2 alias now also names its mirror:ALTANA_CHAIN=base-sepoliaresolves to the Sepolia registry and Base Sepolia's cache, whileALTANA_CHAIN=sepoliaresolves to the same registry with no L2, because more than one L2 can be rooted in it.L2_RPC_URLoverrides the L2 read RPC. -
A session key can pay x402 straight after it is granted. A payment from a smart account is an ERC-1271 signature, and
IthacaAccount.isValidSignatureaccepts a session key's only from a contract the account has approved as a signature checker for that key; the permit2 rails additionally need the token approved to Permit2, which moves it with an ordinarytransferFrom. Neither was part of granting a session, and missing either failed at settlement rather than at signing, reverting with no reason naming an approval, so a merchant reportedsettlement failed: Execution reverted for an unknown reason.grantSessionnow takesx402Tokens: for each token, the same intent that authorizes the session approves the token to Permit2 and approves both Permit2 and the token as checkers for that key, per chain, in one transaction.checkX402Approvals(session, requirement)reads the same two things and says which is missing and the call that sets it;approvedSignatureCheckersandx402SignatureCheckerare exported alongside it, as are thebuildSetCheckerApprovalCallandbuildApproveTokenForPermit2Callbuilders. -
Keystore writes paid from the wallet's own chain. On a network that mirrors another chain's Keystore (Base Sepolia),
grantSession,revokeSessionandregisterSessionKeyneed no ETH on the Keystore chain: the SDK asks the relay to pay the Sepolia write, registration fee and relay fee, from the wallet's balance on the L2 it acts on under the same single signature, always. ETH the wallet holds on Sepolia is not used. Registry legs and quote lines carryfundedFromChainIdandsourceTransactionHash; quotes charge the line to the L2 balance. -
Relay fees in the token the wallet holds. The SDK no longer names the native token on every call. With no
feeToken, a wallet (admin) key sends none and the relay charges whichever of its accepted tokens the wallet holds (on Celo: CELO, USDC, USDT, USDm, EURm or KESm, priced from Celo's own oracle), so a wallet funded with a stablecoin transacts without CELO. A session key pays from its spend caps: the SDK keeps the capped tokens the relay accepts on the chain and names the one the wallet holds the most of, failing before anything is sent when the wallet holds none of them.feeTokennow also takes a list: pay with the first listed token the relay accepts and the wallet holds.grantSessionwithfeeToken(one address or a list) adds a daily spend cap for each (default one whole token,feeSpendLimitoverrides) so the session can pay fees in it.ExecuteResultgainsfeeToken, the token the relay charged, read from the intent it quoted. Newclient.feeCurrencies()(andfeeCurrencies({ network })) lists what a chain's relay accepts with each token's rate and the relay'srateTtl;formatFeeAmountprints an amount with its symbol;NATIVE_TOKENis exported. A "fee token not supported" rejection now names the tokens the relay accepts on that chain, read live. MCP:create_walletnames the accepted fee tokens in its funding steps; the newlist_fee_currenciestool lists them (with the wallet's balance of each when a wallet is named);wallet_execute,session_executeandgrant_sessionandrevoke_sessiontakefeeTokenas one address or a list, and the two execute tools report the token charged.Behaviour change: on Celo a wallet holding both CELO and a stablecoin used to pay every fee in CELO and now pays in whichever of the two the relay values higher. Pass
feeToken: NATIVE_TOKENto keep paying in CELO. On every other chain the relay accepts native only, so nothing changes. -
Grant on several chains in one call, and revoke wherever the key is.
grantSessiontakeschainIdsto act on a set of networks, andrevokeSessionalways does. Revoke discovers, in parallel, which chains' accounts hold the key and which Keystores list it, then revokes on each: one account leg per chain holding the key, one registry leg per Keystore chain (shared by the L2s behind it, bundled into the account intent when the Keystore chain is itself one of the chains), and one post-revocation cache proof per L2. Grant writes the Keystore once per registry chain, then authorizes the session on each chain and proves it into each L2 cache. Both return a per-chain report (legs, each withchainId,kind,status,transactionHash,reason) and a binarystatus(granted/revokedorfailed), never throw for a failed leg, and are safe to call again: a retry only acts on what is still pending. Passkey sessions are now revocable (the revoke used a secp256k1 descriptor for every key). Newclient.quoteGrantSession/client.quoteRevokeSession(andquoteGrantSession,quoteRevokeSession,quoteCalls) price each leg through the relay'sprepareCallswithout signing, with the payers' balances; each line and balance reportsneeded, the native amount including the fee, not only the registration fee (the relay's own figure when it reports the wallet short). New account readsgetKeys,getKey,accountHasKey,keyHashForSessionOrKey,keyIdForSessionOrKey. New configsBASE_SEPOLIA(chain 84532, L1 Sepolia, KeyStoreCacheOPStack0x37ebf8F17c3705568a03fB3A1629AcE7B3D95FFf).SEPOLIAnow carries the testnet relay URL, so Sepolia KeyStore writes are relayed wallet calls (passkey wallets can register there) instead of direct transactions from the admin key. NewNETWORKS(mainnet: BNB, Ethereum, Celo;testnet: BNB testnet, Celo Sepolia, Base Sepolia) andnetworkByChainId. The MCPrevoke_sessiontool revokes across the whole mainnet or testnet group of its chain. -
L2 execution networks with a mirrored KeyStore (Base Sepolia). A network can keep its KeyStore on its L1 and mirror it into a KeyStoreCache on the L2:
NetworkConfiggains an optionalregistryfield naming the L1 and the cache (absent means the KeyStore is on the chain itself, so existing configs are untouched), plusregistryNetwork(network),isCachedRegistry,keyStoreCacheOfandprovisioningNetworks. On an L2grantSessionruns three steps (L1 KeyStore write, account authorization through the L2 relay, proof into the L2 cache through the OP-stackL1Blockpredeploy) and reports the first and last on the result (registry,cache);revokeSessionruns them in reverse and returns the same reports (RevokeSessionResult);registerSessionKeyandrecoverFromPasskeyread and write the L1. Newclient.syncSessionToCache(andsyncSessionToCache) submits the proof as a wallet call through the L2 relay, waiting for the anchor and retrying when it moves;GrantSessionOptionsgainspopulateCacheandonStatus. The proof building blocks are exported:buildPopulateKeyCall,waitForL1Anchor,readL1Anchor,computeKeyPackedSlot. New configsBASE_SEPOLIA(chain 84532, L1 Sepolia) andSEPOLIA(chain 11155111). Per-chain faucet map (FAUCET_URLS,faucetHint,CELO_SEPOLIA_FAUCET_URL), x402 aliasescelo/celo-sepolia, and docs (own and mirrored Keystore in Keystore, grant, revoke, sync and errors). Covered by unit tests, two anvil fork tests (fork-celo-cache: KeyStoreCacheOPStack 1.1.1 accepts a real Sepolia proof built by the SDK;fork-celo-x402-server) and two live smoke scripts. -
@altananetwork/mcp:ALTANA_CHAIN=celo-sepolia/celo. Chain selection moved tonetwork.ts. Every selectable chain keeps its own KeyStore, whichwallet_verificationandverify_authorizationread andgrant_sessionandrevoke_sessionwrite in the account's own transaction;create_walletnames what to fund, including the native token the registration fee is paid in. -
@altananetwork/x402-server: Celo tokens.USDC_CELO,USDC_CELO_SEPOLIA(Circle USDC, EIP-712 domainUSDC/2, 6 decimals, both rails) andUSDT_CELO,USDT_CELO_SEPOLIA(6 decimals, permit2-exact only). Settlement through viem's Celo chains is a standard EIP-1559 transaction, pinned by a unit test and the Celo Sepolia fork test. -
@altananetwork/hypersigner-keystore-mcp:sepolia,celoandcelo-sepoliachains, and thebase-sepoliaalias.ALTANA_CHAIN=sepoliais the registry behind Base Sepolia, withbase-sepolia/84532resolving to it;celo/42220andcelo-sepolia/11142220are chains with their own KeyStore. -
client.holdings()discovers which tokens a wallet holds.balancesneeds an explicit token list;holdingsasks the Altana relay for the wallet's assets on the chain (wallet_getAssets) and then reads every ERC-20 it names live, so the entries are the sameTokenBalanceshape asbalances, BEP-677 display scaling included. Zero balances are dropped unlessincludeZero: true; tokens whose reads fail stay in the list asok: false. No configuration: the relay already attached to the chain is used, so there is no indexer key and no token list to maintain. The MCPwallet_balancetool gainsdiscover: true, which returns the discovered list flaggeddiscovered: true, and thewallet-balanceslash command now shows every token the wallet holds. Token reads are also chunked (40 tokens per multicall, at most 3 in flight) so a wallet with hundreds of tokens does not burst-fire calls at a public RPC. (#78)
Changed
-
Relay failures are
AltanaErrors. Every failure the relay reports is thrown as anAltanaError:codeto branch on (insufficient_funds,quote_expired,session_expired,spend_limit_exceeded,call_not_permitted,relay_unreachable,chain_not_served,wallet_unknown_to_relay,price_unavailable,prices_stale,unknown),messageas one sentence a person can act on,statementandactionas its two halves,detailfor a log, and the relay's own words onrelayMessageandcause.isAltanaErrorrecognises one across package copies.classifyRelayFailure,explainRelayFailureandwithFailureContextare exported for apps that map failures themselves, andsdkBuildnames the commit a build came from. -
A session that has run out says when. A session used after its expiry is refused before anything is sent: "This session expired at 12:28 UTC. Grant a new session to continue." The relay's "key hash is unknown" for the same case reads the same.
-
A wallet the relay has no record of says what to do. "Invalid authorization item. Create a new wallet to continue." (
wallet_unknown_to_relay). -
grantSessionandrevokeSessionreturn as soon as the Keystore write and the account legs are confirmed, which is when the session is usable (or stopped). The L2 cache proofs, which wait for the L2 to anchor the Keystore block (15 to 30 minutes on Celo Sepolia), keep running in the background: their legs readPENDINGand the newcacheSyncpromise resolves with them once they are in.populateCache: "await"restores the blocking behaviour.SessionLeg.statusgainsPENDING. -
fetchWithX402reads a session's x402 approvals before paying and refuses when one is missing, naming it, rather than settling into a revert. It fails open: only a read that succeeds and shows a gap stops the payment, so an unreachable RPC or a chain the SDK has no config for leaves the call exactly as it was. Twoeth_calls, no gas.checkApprovals: falseskips them — worth setting if you count requests in tests, since the reads add two. -
Relay rejections for an account the relay has not registered now say to create the wallet with
client.createWalletfirst. -
When the relay's simulation reverts without a reason, the SDK reads the wallet's balances through the relay and says which chain cannot pay for the call, and which chains it could not be funded from. Session quotes label such legs "could not be quoted" instead of "fee unknown".
-
Relay rejections carrying an
Error(string)orPanicrevert show the message ("Cache: bad storage proof") instead of the hex data. -
Session quotes price the cache-proof legs with a key the wallet already has in the Keystore instead of asking the relay to simulate a proof that does not exist yet. On a first grant the leg is marked
deferred(priced once the registry write lands), no longer reported as a failure. -
Hire expiry is documented and pinned, and the MCP deadline option is described.
hireErc8183AgentsetsexpiredAt = now + disputeWindow + deadlineSeconds; the formula is now the exportederc8183ExpiredAt, covered by a unit test, and the ERC-8183 docs gain a "Deadline and expiry" section: what the seller window means, the per-chain dispute windows (900 s testnet, 7 days mainnet), whenclaimRefundopens, and an interop warning that providers on bnbagent < 0.4.6 read a 24 h testnet window and silently skip shorter jobs (passdeadlineSeconds: 86400 + <window>or have them upgrade; upstream bnbagent-sdk #83). The MCP tool'sdeadlineMinutesnow carries a description, must be positive, and is rounded to whole seconds (a fractional value used to throw aBigIntRangeError).deadlineSecondsmust be a positive integer. The default padding is unchanged on purpose: baking another SDK's stale 24 h constant into ours would make testnet jobs diverge from the policy they bind. (#82)
Fixed
-
A slow relay no longer leaves a paid registration half done. A Keystore write funded from an L2 locks the payment on the L2 first and runs on the L1 after. When the relay was slow on the L1, the SDK stopped waiting at four minutes, reported the write as failed with "nothing was mined on any chain" while the payment sat in the escrow, and never sent the session key's write or the cache proof, even though the relay went on to register the wallet's first key (Celo mainnet, 2026-11-14). The SDK now keeps waiting while the payment is held, for up to 65 minutes, reports the new
onStatuseventregistry-write-pendingonce, and then goes on with the session key and the proof. If the wait ends first, the reason says where the payment is: "The KeyStore update on Ethereum has not completed yet. The payment for it is held on Celo and comes back if the update does not complete." A timed-outPENDINGfromwaitForCallsnow carries the receipts the relay had reported. Grants on BNB Chain and Ethereum, where the write is part of the same transaction, are unchanged. -
A Keystore registration the relay reports as not done is checked in the Keystore. A signed request can be delivered by a sender other than the relay, and on Ethereum one was: the session key's registration landed, delivered by another sender earlier in the same block, the relay's own transaction then failed and it reported status 500, and the SDK sent no cache proof for a key that was registered (Celo mainnet, 2026-11-16). When the relay reports a registration as not done, the SDK now reads the Keystore; if the key is there, the registry leg is
CONFIRMEDwith the transaction that registered it, and the session key's write and the cache proof go ahead. If the Keystore cannot be read, the failure stands and its reason says the check was not made. -
The price preview of a first registration counts the root key once, and prices a wallet that holds only a stablecoin.
quoteGrantSessionquoted the session key's write with the root key's registration added to it, then added the root key's write again. On mainnet that combined request does not fit one intent's gas, so the relay could not price it, and a wallet holding only USDC on Celo was told it needed CELO. A first registration is now priced as the two writes the grant sends, one key each. -
A wallet that holds a stablecoin and none of its chain's currency is told its real balance. A failure the SDK words as a shortfall on a funded write named the chain's own currency even when the wallet held only USDC there ("you have 0 CELO"). It now names the token the wallet holds, with its balance.
-
A price that is too old is reported as one. The relay converts a request paid in one asset and carried out in another at a Chainlink price, and refuses when that price is older than its limit. It answers the refusal with a revert that carries no reason, the same answer it gives when a wallet cannot pay, so a wallet that could pay was told to add funds. The SDK now reads the feeds the conversion depends on after such a refusal, and when one is older than the relay accepts the error is
prices_stale: "Prices are temporarily unavailable, try again shortly." The feed and its age are ondetail. Any other refusal keeps the sentence it had. The feeds and the limit are onNetworkConfig.nativePriceFeed. -
A quote reads a cross-chain cost per leg and per token. A registry write the relay funds from an L2 is paid on that L2, and the relay prices it in whatever token it accepts there: the native one, or a stablecoin with 6 decimals. The SDK used to reduce a two-leg quote to one number by adding the legs' fees together and charging the total to the payer's native balance on the funding chain. That only worked while one unit of the source asset repaid one unit of the destination asset, which is what the testnet relay's own config arranged; it is not true at real prices, and it is not true at all when the source leg is priced in a stablecoin. Worse, both legs report the same zero address for "native", so the old sum was adding CELO wei to ETH wei without anything looking wrong.
A
QuoteLinenow carriesneeds: what the payer must hold, per chain and per token, andcharges: what each of the relay's legs charges in its own token.quote.balanceshas one row per token with its owntoken,symbolanddecimals, read as an ERC-20 balance when the token is one (and reportingsufficient: falsewith areasonwhen that read fails, never a short answer dressed as a safe one).formatQuoteLinesays "pays 2.845288560627534961 CELO on Celo Sepolia" instead of labelling a CELO amount with the registry chain's symbol. For a multichain quote only the funding chain is charged: the relay's funder pays on the destination and the escrow repays it, so counting the destination leg as well charged the payer twice.fee,feeTokenandneededstay, as the figures for the chain the payer pays from, andneededis the native part ofneeds— so a leg charged in a stablecoin reportsneeded: 0nand the real amount inneeds. A quote whose legs the relay does not tag with chains behaves exactly as before. -
A wallet's first session key registers reliably again. That first registry write is two KeyStore calls,
initialRegisterKeythenregisterKey, and they were bundled into one relayed intent.initialRegisterKeyalone costs about 1.08M gas on a cold account, which leftregisterKeytoo little of the intent's budget: it ran out of gas and the Orchestrator returnedCallError(), surfacing as a failedgrantSessionwith nothing naming gas. The two calls now go as two sequential intents, each quoted for its own gas. They do not need to be atomic — the direct (no-relay) registry path has always sent one transaction per call — and if the first lands and the second fails, a retry ofgrantSessionreads KeyStore, finds the admin key, and sends onlyregisterKey.SessionLeggains an optionalrootRegistrationcarrying the first intent's outcome; the leg's owntransactionHashandblockNumberstill describe the session key's write, so cache proofs anchor where they did before.onStatus("registry-write", detail)now carriesdetail.stepof"root"or"session"on a first write; the event name is unchanged, so a consumer ignoringstepsimply sees it twice.quoteSessionprices both intents and sums them, and a registry line gainsrootRegistrationwith the first intent's own share. -
A failed registry write says what went wrong. The leg's
reasonwasregistry write status FAILED, which named neither the chain's revert nor the relay's message, both of which were available one layer down. It now carries the write's own words. -
A registration fee quoted a moment ago is no longer refused at inclusion.
KeyStoreController.getRegistrationFeeInWei()is oracle-priced — a USD fee converted through Chainlink's ETH/USD feed — so the wei amount moves with every oracle round, while the controller requiresmsg.value >= feeat inclusion. A registration call now carries the quoted fee plus 10%, via the exportedregistrationValueFor, andrequiredFundsand the quote line follow it because both sum the calls' ownvalue. Overpaying costs nothing: the controller refunds the excess tomsg.senderwith a full-gascall, which an EIP-7702 delegated account can receive, and the refund isrequired so a failure reverts loudly rather than keeping the change. 10% is sized against the measurement rather than the symptom: Chainlink ETH/USD steps at most ~1.4% per round on Sepolia, so this is about six times the worst step. It is deliberately not large enough to absorb a stale payload, because that is a lifecycle problem rather than a pricing one —keystore_encode_register_keynow returnsquotedFeeWeiandquotedAtBlockwith it, so a caller can compare againstkeystore_registration_quoteand re-encode rather than send a payload built in an earlier oracle round. -
Mirror proofs work again after Glamsterdam. Ethereum Sepolia's block headers gained
blockAccessListHashandslotNumberat block 11856337, so the SDK's header RLP encoder no longer reproduced the block hash andbuildPopulateKeyCallrefused to build any proof against a post-fork anchor ("RLP header encoding does not hash to block hash; block schema likely changed"). That guard was right and is why this was a readable diagnosis rather than an on-chain revert. Both fields are now encoded, appended in that order and only when present, so pre-fork headers and anything already in a cache keep verifying — three of the four chains the SDK reads do not carry them yet. The deployedKeyStoreCacheOPStackneeded no change: it hashes the header's raw bytes and readsstateRootat index 3 with no field-count check, confirmed by static call against the live contract. Existing cache entries,isValidKeyand session registration were never affected; only building a new proof was. -
Sepolia works again after EIP-7708. Ethereum Sepolia activated Glamsterdam at block 11856337, and every ETH transfer now also emits a real ERC-20
Transferlog from the system address0xfffffffffffffffffffffffffffffffffffffffe. The relay buildsassetDiffsfrom simulation logs, so that log arrived as{"address":"0xff..fe","type":"erc20"}with nosymbol— the address has no code, so the relay'sdecimals()/symbol()/name()multicall reverts and those fields stay absent. Every variant of porto's asset-diff schema requires asymbol, so porto rejected the whole response and everygrantSessionregistry leg on Sepolia failed. The SDK's relay transport now removes those entries before porto validates, on every response that carriesassetDiffs(wallet_prepareCallsandwallet_getCallsHistory), dropping an account's entry when the system address was its only diff. They are dropped rather than relabelled because the relay synthesises its own native diff from0xee..ee: the two logs describe one movement, so mapping the system address onto the native asset would double every ETH balance change. A response carrying no such entry is returned unchanged, by identity. -
A passkey wallet can be created on a cached-registry network.
createWallet({ signer: passkey })refused on Celo Sepolia and Base Sepolia with "signer produced a different address on chain 11155111". Those networks provision two chains, the network and the KeyStore chain behind it, andcreateWalletasked each chain for a wallet address separately. A passkey has no EOA, so the throwaway secp256k1 that stands in for one was generated per chain, giving the wallet a different address on each. The address and the key that signs the EIP-7702 authorization over it are now decided once per wallet (planAccountProvisioning) and used on every chain (provisionAccount);createPasskeyWalletshares the same step. A passkey wallet therefore has one address, with the passkey as admin, on the network and on its registry chain, where its registry writes go through the relay from its own account. -
A wallet's second operation no longer fails on the nonce. The relay chooses an intent's nonce by reading the account's nonce on chain at
latestand remembers nothing between requests, so an operation prepared before the wallet's previous one is visible to the relay was given a nonce the account rejected, andgrantSession,revokeSessionandexecutecame back withInvalidNonce(InvalidNonce). Waiting for the previous operation was not enough: the relay's own read lags the receipts it hands out. A prepare rejected for its nonce is now retried, up to three times over twelve seconds, with nothing signed or sent in between; live on Celo Sepolia four back-to-back operations on one wallet each succeeded on the attempt after the rejection. Any other rejection is still the caller's answer immediately. The SDK does not supply the nonce itself, although the relay would honour it: a counterfactual wallet's first intent gets a random sequence key and every intent after the delegation lands uses key 0, so counting up from the previous nonce is wrong exactly when it matters. -
signX402Paymentsigns a v2 envelope when the requirement names no version. A v2PaymentRequirementscarries nox402Versionof its own (it lives on the 402 body), so a caller handingsignX402Paymentanaccepts[]entry straight from a challenge had nothing to copy down and got a v1 envelope, which real v2 facilitators refuse for its format before looking at the signature. Celo's answersinvalid_format, "data did not match any variant of untagged enum FacilitatorVerifyRequest", which points nowhere near the version. The default is now 2; the requirement's own version still wins, and the newopts.x402Versionoverrides both for a v1 merchant that does not say so.fetchWithX402already stamped the body's version and is unchanged. -
Cache proofs no longer start before the L2 has anchored the registry write. A relayed KeyStore write took its block number from a public RPC receipt lookup; when that lookup failed (the node had not indexed the transaction yet) the error was swallowed and the cache proof was built right away against an older L1 block, where the key did not exist, so the cache rejected it. The block number now comes from the relay's own call status receipt (
waitForCallsreturns it), with a retried RPC lookup only as a fallback. If it stays unknown, the cache step ofgrantSession,revokeSessionandregisterSessionKeyfails with "registry block unknown, proof not attempted" instead of proving.syncSessionToCache(as used by those three) also refuses to submit a proof whose storage value shows the key absent: it waits for the next anchor and rebuilds it. -
An empty revert from the relay no longer reads as a balance shortfall it is not. When the relay's simulation reverted with no reason bytes (a bare
0x), the SDK read the wallet's native balances and worded the rejection as a shortfall either way, so a wallet holding 1 ETH while the call sent 0.000376 ETH was told its balance "does not cover" the call. A bare0xnow gets its own message: it says the simulation reverted with no reason, names the chain and the calls it simulated with what they send, and adds the balance only as what it is. A balance below the value the calls send still reads as a shortfall, with the chain's faucet where there is one; a balance above it says the balance is not the cause.shortfallMessageis replaced byemptyRevertMessageandbalanceClause. -
NoSpendPermissionsandExceededSpendLimitexplain themselves. Both reached callers as a bare contract error, and on the fee path as a raw 32-byte selector.NoSpendPermissionsnow says the session has no spend limit for a token the transaction spends, that relay fees need a native limit with headroom even for a session that only sends tokens, and that permissions cannot be widened on an existing session.ExceededSpendLimitnames the token whose cap is exhausted and points at the decimals trap. Both match the decoded name and the raw selector. (#83) -
fundNativeis deprecated and always throws. The relay's faucet only mints ERC-20 fee tokens; a native request sent a zero-value transaction to0x0and the helper returned its hash as if the wallet had been funded. It now throws, naming the address to fund and the chain's public faucet where there is one.waitForBalanceis unchanged. Removal in a later release. (#83) -
Relay rejections now lead with the relay's actual reason. A rejected request (for example an unaccepted
feeToken) used to surface only viem's genericInvalid parameters were provided to the RPC method, while the relay's real explanation sat several.causelevels deep where nobody found it. The submit path now extracts that reason and throws with it up front — e.g.The relay rejected the request to prepare the call: fee token not supported: 0x…— keeping the original error on.cause. Fee-token requests get an extra hint that relay fees are paid in the native currency (BNB), not$U. The execute and errors docs document the fee model. No behavior change to successful calls. (#72) -
@altananetwork/x402-server: a payment whose receipt could not be read is no longer reported as failed. When the settlement transaction was broadcast but the RPC failed to return its receipt (error or timeout), the merchant answered 402 "settlement failed" with a fresh challenge and forgot the authorization. Every x402 buyer answers a fresh challenge by signing a new authorization, so the buyer paid twice for one request, and the first transaction hash was discarded. Settlement now returnssettlement: "pending"with the hash once a transaction is out, and the merchant answers 200 with that receipt; the same authorization sent again while pending is re-checked and answered with the same settlement instead of a replay rejection. The same classification applies when the broadcast response itself is lost and the node reports the transaction as already known. Receipt waits are bounded by the newsettleTimeoutMsoption (default 60s),clientslets a merchant inject its own viem clients, and settlement error text no longer embeds the facilitator's RPC URL. Reproduced and covered on a BNB-mainnet fork infork-x402-server, which now runs in CI. Reported in #76.
0.9.0 - 2026-09-02
@altananetwork/mcp 0.9.0
Added
-
serializeSession/deserializeSession— the safe way to persist a session.serializeSession(session)returns a JSON-safe object with NO key material in it (spend limits as decimal strings);deserializeSession(stored, signer)rebuilds a signing session from the stored half plus the key the caller kept, and refuses a signer that doesn't match the session's registered public key — a mixed-up key now fails loudly at restore instead of opaquely at execute. The MCP server's three hand-rolled session restores now go throughdeserializeSession.grantSessionalso warns (once per process) when called without asessionSigner: the SDK-generated key exists only in process memory, and losing it strands the on-chain authorization it backs. (#58) -
ERC-8183 seller support — an Altana agent can now get paid, not just pay.
submitErc8183Deliverablesubmits a hired job's finished work (wallet or session path; pre-flight reads turn the kernel's opaque reverts into clear errors),buildSubmitCallis the low-level builder, anderc8183SubmitPermissions(chainId)scopes a seller session to exactlysubmit()on the commerce kernel. The deliverable-manifest codec ships too:encodeErc8183Manifest/erc8183ManifestHashproduce the canonical form byte-identical to the Python reference — including the\uXXXXescaping of non-ASCII content that a plainJSON.stringifygets wrong and that breaks cross-language hash verification — andverifyErc8183ManifestTextis the buyer-side raw-bytes integrity check. Exposed in the MCP server aserc8183_submit, which returns the exact canonical text the agent must serve at its deliverable URL. The fork e2e now drives the full two-sided lifecycle (hire → submit → verify → settle → seller paid) against real kernel bytecode. (#59)
Changed
-
SignerTypeno longer advertises"injected". The union member promised browser-wallet (MetaMask) signing that was never implemented and is blocked by the wallets themselves: extension wallets withhold the EIP-7702 delegation authorization and refuse to sign the raw relay digests, so the runtime has rejected"injected"since day one. The type now matches reality ("privateKey" | "passkey"; compile-time-only change — no working code used it), the helpful runtime message stays, and a new guide, Onboard users from browser wallets, documents the flow that works: connect MetaMask/Trust Wallet/Rabby as usual, create the account withcreatePasskeyWallet, and fund it in one click through the connected wallet's own provider. (#56) -
A signer's private key can no longer be captured by JSON. The docs used to say "persist the
Sessionobject verbatim" — advice that threw on bigint spend limits, silently wrote the raw session key into storage, and dropped the signing function. The internal key field is now non-enumerable, soJSON.stringify/Object.keysnever see it. Anyone who relied on the leak for persistence must migrate toserializeSession/deserializeSessionplus their own key storage; the docs' session-persistence guidance is rewritten everywhere it appeared. (#58) -
Documented the EIP-7702 native-payout limitation. Contracts that pay the wallet native coin via
.transfer()/.send()revert: the 2300-gas stipend cannot run the wallet's delegated account code. Known case: Venus core-pool vBNBredeemon BNB Chain. ERC-20 payouts and full-gascall{value:}payouts are unaffected. The errors and execute pages now cover the symptom and the workarounds (wrapped-token path, gateway contracts, plain-EOA receiver), and a fork test pins the behavior against the real mainnet account bytecode. Root cause is in the paying contract, so there is no SDK-side fix. (#55)
Fixed
-
The SDK's last Node-only API is gone.
getErc8183DeliverableUrldecoded event bytes withBuffer, which does not exist in browsers or React Native without a polyfill; it now uses viem's runtime-neutralhexToString(behavior-parity verified, including NUL padding and invalid UTF-8). The passkey guard messages also stopped blaming only "Node or other server runtimes" — they now name React Native and point at thewebAuthnoption. (#65) -
Relay rejections no longer hang for four minutes as
PENDING. The status poller only understood relay codes 200 and 500; a bundle the relay rejected before inclusion (code 300 — most commonly a session spend cap too small to also cover the relay fee, which the cap must) fell through the loop for the full 240-second deadline and then came back asPENDING, for a bundle that was already dead on the first poll. Statuses are now classified by the EIP-5792 bands (1xx in flight, 2xx confirmed, 300–699 failed; unknown codes keep polling rather than risking a duplicate resubmission), so a rejection returnsFAILEDwithin seconds. Results gain an optionalstatusCodewith the relay's raw code — onFAILEDit separates "rejected before the chain" from "reverted on-chain", and on a timed-outPENDINGit separates "genuinely still in flight" from "the relay never answered". The docs now carry the status code table and a grantSession warning that the native spend cap also pays relay fees. Note the behavior change: flows that used to seePENDINGafter 240 s for rejected bundles now seeFAILEDfast. (#57) -
BSC testnet (chain 97) hire flow no longer reverts. The bundled
ERC8183_ADDRESSES[97].policypointed at an address that is not whitelisted on the testnet EvaluatorRouter, so everyhireErc8183Agent()/buildHireCalls()run on BSC testnet reverted atregisterJobwithPolicyNotWhitelisted(). The entry now uses the deployed OptimisticPolicy (0xd6a4217588F6B1F5657a92A3e94E6422aD771cEA), verified against the operator's deployment manifest and live router whitelist state. Mainnet was unaffected. (#53)
Added
- Passkeys on native mobile: WebAuthn function injection.
createPasskey,createPasskeyWallet,recoverFromPasskey, andsignerFromPasskeyaccept awebAuthn: { createFn, getFn }option for JavaScript runtimes without the browser WebAuthn API — React Native, Expo, Capacitor. The app passes its native passkey library's functions (which bridge to Apple's and Google's platform passkey APIs) and the SDK forwards them into porto everywhere WebAuthn is touched: credential creation, recovery, and every signature (each execute performs a fresh assertion ceremony). Outside a browser,rpIdis required with a clear error (porto/ox would otherwise crash on the missingwindowmid-flow), and the option types avoid DOM globals so React Native tsconfigs typecheck. Browser behavior is unchanged when the option is absent. CI proves the forwarding with the same mock-function pattern porto's own tests use; real-device verification is invited from the field. (#65)
0.8.0 - 2026-08-18
Added
-
ERC-8004 agent identity. An agent on an Altana wallet can now mint and maintain its own on-chain identity, so buyers and other agents can discover it.
registerErc8004Agentmints and returns the assignedagentId,setErc8004AgentUripublishes the registration record, andgetErc8004Agentreads both back.buildErc8004RegisterCall/buildErc8004SetAgentUriCallare the underlying call builders, andencodeErc8004AgentUri/decodeErc8004AgentUri/withErc8004Registrationhandle the registration file — canonical JSON, byte-identical to@bnbagent's TypeScript and Python SDKs, so records hash the same across ecosystems. Registry addresses come from the existingERC8183_ADDRESSES[chainId].registry; there is no second address table.This closes the gap that forced BNB Agent Studio agents on Altana wallets to deploy with
--skip-register. -
erc8004RegisterPermissions(chainId)— the bounded capability for the above: two{ to, signature }rules that let a session key call exactlyregisterandsetAgentURIon the registry. Deliberately not a{ to: registry }grant: a session executes as the wallet, which owns the identity token, so a registry-wide grant would also authorizetransferFrom,setApprovalForAll(an operator approval that outlives the session's revocation), andsetAgentWallet. -
erc8004_register,erc8004_set_agent_urianderc8004_showin the MCP server.erc8004_registerdrives both registration phases; if the mint lands but the write-back fails it returns theagentIdwith repair instructions rather than stranding a minted identity that has no reverse lookup. All three check the session's permissions client-side before spending gas.
Fixed
hireErc8183Agentno longer throws a false "job is not ours" error whenopts.noWaitis set. WithnoWait,execute()returns{ status: "PENDING" }as soon as the relay accepts the intent — before the batch is mined — but the post-funding ownership check read chain state unconditionally, so it saw pre-inclusion state and failed on everynoWaitcall. Worse, obeying the error's "retry" advice re-ran the hire batch and escrowed $U a second time for an already-funded job. The check now runs only once the result isCONFIRMED;noWaitcallers verify viagetErc8183Jobafter theircallsIdconfirms (the docstring documents this). First external contribution — thanks @web3xDev! (#42)
0.7.1 - 2026-08-12
@altananetwork/mcp 0.7.1
Added
grantSessionreturns the grant's transaction hash. The result is nowGrantSessionResult, aSessionplus an optionaltransactionHash. Granting is the one call that charges the user a Keystore registration fee (twice on a wallet's first admin action), and it was the only entry point that discarded the hash instead of forwarding it.execute,revokeSessionandregisterSessionKeywere already returning it.grant_sessionreports the transaction hash in the MCP server, alongside the session details andkeyId, matching every other write tool.
Not a breaking change: GrantSessionResult is assignable everywhere a Session
is expected. One thing to watch as a consumer, an explicit annotation narrows
the type back down and hides the new field:
const session: Session = await client.grantSession({ ... });
session.transactionHash; // does not typecheckLet the type be inferred, or annotate with GrantSessionResult.
0.7.0 - 2026-08-04
@altananetwork/mcp 0.7.0
Added
- Skills registry discovery in the MCP server.
search_skillssearches the registry by name, description, and tags;get_skillfetches a skill's full playbook. Playbook content is integrity checked against the registry'ssha256before it is returned, so a tampered playbook is rejected rather than followed.
Fixed
- B402 envelope compatibility. The x402 client and server now speak the B402 envelope dialect on both sides, fixing payments against BNB-chain sellers that expect it.
0.6.0 - 2026-07-16
@altananetwork/mcp 0.5.0
Added
- ERC-8183 buyer support. Hire BNB Agent Studio seller agents from an
Altana wallet: escrow, job status, and settlement as one atomic relay
intent. Exposed through the SDK and as
erc8183_create_job,erc8183_job_status, anderc8183_settlein the MCP server. @altananetwork/x402-server. Seller-side x402/B402 package: payment challenges, verification, and on-chain settlement.
0.5.0 - 2026-07-14
@altananetwork/mcp 0.4.0
Added
- BNB testnet support (chain 97), routed through
testnet-relay.altana.network. - Optional session-key Keystore registration.
grantSessiontakes aregisterflag, on by default;registerSessionKeyregisters a key later. - ERC-20 balances with BEP-677 support.
client.balancesdetects scaled-UI-amount tokens via ERC-165 and scales their display value, leaving the raw on-chain amount untouched.
0.4.0 - 2026-07-14
@altananetwork/mcp 0.3.0
Added
- x402 payments. Pay HTTP payment challenges with a session key over Permit2 or EIP-3009, including the B402 permit2-exact witness rail.
- ERC-1271 signature verification for smart-account wallets.
0.3.3 - 2026-07-08
First public release: agentic wallets, session keys, the Keystore registry, the MCP servers, and the documentation site.
This page is generated from
CHANGELOG.md, the canonical file in the SDK repo.