@aifinpay/agent 2.3.0 → 2.5.0

package/PAYMENT_RECEIPTS.md

@@ -1,4 +1,121 @@
-# v1.4 payment authorization (2.3.0)
+# Solana payment authorization (2.5.0 source candidate)
+
+High-level execution still requires an accepted enabled canonical registry record.
+Both real Solana records remain disabled. This configuration describes the
+conditional source implementation; do not override availability in an application.
+
+```ts
+import { AiFinPayAgent, Aifp1FinalizedFailureError } from "@aifinpay/agent";
+
+const agent = await AiFinPayAgent.fromEnvironment({ solanaRpc: ownerSolanaRpc });
+agent.setBudget({ daily_usd: ownerDailyUsdLimit, per_call_usd: ownerBatchUsdLimit });
+await agent.fetchPaid(
+  url,
+  {},
+  {
+    gatewayOrigins: ["https://merchant.example"],
+    resourcePathMode: "direct",
+    maxAmountUsd: ownerBatchUsdLimit,
+    nativeUsdPrice: readFreshIndependentSolPrice,
+    solanaV14: {
+      environment: "prod",
+      network: "mainnet",
+      asset: "SOL", // USDC or USDT on mainnet; only reviewed USDC on devnet
+      maxFeeLamports: ownerFeeAndRentLimitLamports, // bigint, independently chosen
+      onPrepared: persistPrivatePaymentJournal,
+    },
+  }
+);
+```
+
+Use `environment:"dev",network:"devnet"` together for devnet; never infer a
+cluster from the payer's address. `nativeUsdPrice` is required even for SPL to
+value fee/rent costs, and must be independent and fresh within 60 seconds. Keys
+remain local. Quotes use request-bound Ed25519 ownership authorization before
+backend signing; the payer verifies the backend's secp256k1 quote signature
+against freshly read Config. This is separate from Ed25519 receipt authorization.
+
+Before the quote POST, the shared private ledger persists the exact owner-signed
+request, nonce, statement and RPC/limits/cluster/program/IDL context. A timeout or
+restart replays those same bytes, even after authorization expiry; the server may
+return only its already-issued original quote. The response is adopted durably,
+then its zero-debit phase converts atomically into the monetary reservation.
+Unknown, malformed, policy or preflight failures keep the original admission;
+changing owner context refuses replay. Custom Solana ledgers require the additive
+quote-admission hooks as well as the existing bound recovery hooks.
+
+Only an exact authenticated expired `410 not_admitted` from the owner API can
+close an absent zero-debit admission. An expired original quote can become a
+local nonbroadcast terminal only if no monetary reservation/signing occurred,
+its exact stored signed deadline and current Config signer are verified, and
+its original ID/time/evidence survive the atomic transition. That invocation
+returns failure and never asks for a replacement quote. A later explicit fetch
+may request a fresh admission; the backend still counts the old issued quote,
+so its policy allowance can remain constrained. This is no backend refund.
+Never clear state, rotate an unknown nonce, or downgrade while unresolved.
+
+`maxFeeLamports` bounds transaction fees plus missing payer-nonce/consumed-nonce
+PDA and destination ATA rent. Payer SPL ATA must already exist and be funded.
+Destination ATA creation is idempotent within the **same** settlement transaction,
+never a preparatory payment. Only classic Tokenkeg and independently pinned
+mint/decimal identities are accepted. Token-2022 and unreviewed mints refuse.
+
+The saved `Aifp1SolanaPaymentRecovery` includes `family:"solana"`, exact signature,
+base64 signed bytes, network/program/IDL, blockhash, nonce, owner-approved fee caps
+and independently sourced admission SOL/USD rate. The private ledger binds that
+context and the common factory wallet identity before the callback resolves.
+A failed fsync callback prevents broadcast. Never put journal bytes or JWTs in logs.
+
+```ts
+try {
+  const paid = await agent.recoverPaidPayment(savedRecovery, {
+    solanaEnvironment: "prod",
+    solanaNetwork: "mainnet",
+  });
+  // Store the verified receipt privately; no transaction was resent.
+} catch (error) {
+  if (error instanceof Aifp1FinalizedFailureError) {
+    // No paid access: original failure reconciled once to feeAmountUsd.
+    // actualFeeLamports and recovery identify the immutable original purchase.
+  }
+  throw error;
+}
+```
+
+Recovery validates the original signed transaction and owner-selected cluster;
+quote expiry, changed current admin profiles and expired recent blockhash never
+permit a second payment. A finalized failure requires the original raw bytes,
+valid error/slot, pinned genesis, canonical finalized block inclusion and safe
+actual fee within the original caps. The local fee-only transition is atomic and
+idempotent, survives restart/day rollover and cannot overwrite confirmed payment.
+An unavailable/malformed proof or local journal error keeps the original guard.
+The backend's outstanding signed-quote policy reservation remains separate.
+Older SDKs must not operate on unreconciled 2.5 journals; retain IDs while recovery
+is possible, and reconcile before downgrade. Never clear state to retry payment.
+
+Public reads need no passport binding or payer signature:
+
+```ts
+await agent.getPaymentHistory({ network: "solana", solanaNetwork: "mainnet", source: "transactions" });
+await agent.getQuota({ network: "solana", solanaNetwork: "mainnet" });
+```
+
+`balance({ solanaNetwork: "mainnet" })` independently verifies the owner RPC's
+genesis and uses that cluster's pinned USDC mint. Failed or malformed explicit
+cluster balance reads throw; they never become a verified zero balance.
+Devnet raw balances have test
+context, no SOL USD price and no contribution to the aggregate fiat value.
+Omitted legacy balance context is explicitly unverified owner RPC/mainnet mint;
+it does not establish payment availability. No devnet USDT pin is provided.
+
+These query independently pinned cluster/program and preserve base58 case. They
+return retained partial-history coverage and explicitly unallocated costs, validate
+exact wallet identity and conserved integer billing units, exclude arbitrary wallet transfers, may lag the
+chain and redact bearer JWTs.
+
+---
+
+# v1.4 payment authorization (2.4.0 source candidate)
 
 The existing v1.3 documentation below remains applicable to explicitly pinned
 v1.3 callers. The v1.4 path uses the original backend-signed quote:
@@ -37,10 +154,10 @@ owner reconciliation; receipt recovery is not a replacement broadcast.
 
 The public MCP candidate implements this private journal/cache/lock integration.
 Applications using the SDK directly own persistence and process coordination.
-`fetchPaid` supports Polygon and explicitly selected Base in live mode, with
-native POL/ETH or a stablecoin pinned for that chain. It never falls back to a
-legacy route or changes assets after a refusal. The low-level executor retains
-Polygon/Amoy support and requires `expectedChain: "base"` to execute on Base.
+`fetchPaid` supports the current nine EVM mainnets in live mode, with the
+selected native currency or a stablecoin pinned for that chain. Every non-Polygon
+rail requires explicit owner selection. It never changes routes or assets after
+a refusal. Amoy remains a low-level test executor, separate from live receipts.
 
 A successful executor result requires a mined success receipt with the matching
 Payment event. Unknown broadcast/confirmation yields the original hash. Profile
@@ -54,18 +171,22 @@ SDK verifies its `eth_chainId` is 8453 before signing. `polygonRpc` remains the
 Polygon transport and is never reused for Base.
 
 ```ts
-await agent.fetchPaid(url, {}, {
-  gatewayOrigins: ["https://merchant.example"],
-  resourcePathMode: "direct",
-  maxAmountUsd: ownerLimitUsd,
-  nativeUsdPrice: readFreshIndependentEthPrice,
-  v14: {
-    chain: "base", // trusted caller choice, never copied from a quote
-    asset: "ETH", // or "USDC"; omit nativeUsdPrice for a USDC purchase
-    maxGasWei: ownerFeeBudgetWei,
-    onPrepared: persistPrivatePaymentJournal,
-  },
-});
+await agent.fetchPaid(
+  url,
+  {},
+  {
+    gatewayOrigins: ["https://merchant.example"],
+    resourcePathMode: "direct",
+    maxAmountUsd: ownerLimitUsd,
+    nativeUsdPrice: readFreshIndependentEthPrice,
+    v14: {
+      chain: "base", // trusted caller choice, never copied from a quote
+      asset: "ETH", // or "USDC"; omit nativeUsdPrice for a USDC purchase
+      maxGasWei: ownerFeeBudgetWei,
+      onPrepared: persistPrivatePaymentJournal,
+    },
+  }
+);
 ```
 
 `asset` defaults to ETH on Base and POL on Polygon. `nativeUsdPrice` must report
@@ -80,12 +201,41 @@ are rechecked before settlement. Missing or malformed oracle answers block payme
 The gas cap and balance checks use this total, but L1/operator fees may change
 before inclusion and are not capped by the signed EIP-1559 transaction.
 
-New recovery records include `chain`. A record without this field is treated as
-Polygon for compatibility and cannot recover a Base payment. The stored chain,
+New recovery records include `chain`. The low-level legacy default without it
+remains Polygon. MCP may migrate a missing-chain journal only from independent
+owner configuration after actual signed transaction bytes prove the chain ID,
+payer, pinned target, exact calldata/value and token/approval. Insufficient
+evidence requires owner reconciliation; no rail is guessed. The stored chain,
 asset and original quote must agree before the SDK signs a receipt claim.
 Recovery works after quote expiry when the existing transaction already settled;
 it never signs a replacement payment. Receipt JWT format is unchanged.
 
+## Durable USD reservations
+
+The built-in file ledger shares one daily cap across processes on one local
+filesystem. It reserves before approval/signing, reloads state under a private
+exclusive lock, and writes through a mode-600 temporary file with atomic rename
+and file/directory fsync. Corrupt or unreadable state refuses payment. A held lock
+times out without being stolen; after a crash the owner must stop all users and
+reconcile outstanding transactions before recovering that lock.
+
+Unknown broadcasts retain their debit reservation indefinitely. Confirmed debits
+count for 24 hours, while the unresolved purchase guard remains until a verified
+receipt completes reconciliation. API/issuer, payer, merchant/scope/resource/mode,
+chain/asset/token/gross/quote ID and signed-byte hash bind the reservation to the
+journal. Changing rails cannot repurchase unresolved access. A confirmed debit is
+never refunded for a receipt or HTTP failure. Recovery commits it once, and keeps
+its reconciliation identity after the budget window expires without counting
+that old debit. Bound history therefore grows; never truncate unresolved state.
+
+Old custom capped v1.4 adapters must implement `prepare`, `assertRecovery` and
+`complete`; absence fails before payment. The uncapped/legacy source API remains
+compatible. `MemorySpendLedger` coordinates one shared instance only. These are
+local filesystem guarantees, not a distributed cap across hosts. Do not downgrade
+to an older SDK while a 2.4 reservation is pending: old code can expire/reset it.
+Preserve the journal and reconcile first. Recovery never accepts a ledger path,
+USD valuation or increased cap from a quote or journal.
+
 ---
 
 # Authorize and recover payment receipts
@@ -202,3 +352,28 @@ compatibility changes do not activate a disabled deployment. v1.4 execution
 and legacy `call()` payment submission remain disabled in this RC. Current
 v1.4 quotes omit mutable fees/treasury from the signed commitment; a new
 contract/SDK release is required. There is no automatic version fallback.
+
+## Nine-network v1.4 source capability (2.4.0)
+
+`v14.chain` accepts polygon (default), base, optimism, arbitrum, avalanche, bnb,
+unichain, xrplevm and robinhood. Quotes cannot choose or expand that setting.
+`evmRpcUrls` keys use those canonical names (BNB uses bnb, not the legacy bridge
+bsc name). The backend must independently authorize the requested settlement_chain
+for the merchant. Native/USD prices must match POL/ETH/AVAX/BNB/XRP. Gas budgets
+are in the selected native asset's18-decimal wei; approval and settlement share
+the budget. OP models include oracle data/operator estimates, Nitro estimates
+include parent data already. Unknown or unavailable fee estimates refuse signing.
+
+The quote amount and existing settlement aliases still contain USD micro-units.
+`token_settlement` contains asset, token, decimals, total_units, merchant_units,
+protocol_fee_units, creator_units and settlement_semantics=gross-inclusive. Client
+address/decimal pins, signed gross and exact approval bind its total to USDmicro
+multiplied by10^(decimals-6). Legs split the token gross, not rounded USD legs.
+Metadata is checked whenever present;18dp requires it and old6dp can omit it.
+Signer/runtime/current-profile/TokenList checks are still performed before broadcast.
+Profiles remain administratively mutable under the accepted v1.4 trust model;
+these quote-time checks do not create immutable fee guarantees. Recovery never
+re-sends a payment and retains its original chain even after quote expiry.
+
+Source capability does not activate a production network. Per-chain deployment,
+backend/indexing and actual paid acceptance gates are recorded in the release evidence.

package/README.md

@@ -1,21 +1,41 @@
 # @aifinpay/agent (Node / TypeScript)
 
-Version **2.3.0** adds Base ETH and USDC to the AIFP-1 `fetchPaid` flow.
-Polygon remains the default. Select Base independently with `v14.chain: "base"`;
-a merchant quote cannot change that choice. Runtime, signer, token, RPC chain and
-current profile checks remain mandatory, along with a durable pre-broadcast
-journal and an explicit gas budget. Legacy `call()` remains unavailable.
-
-Native payments require a fresh independent `nativeUsdPrice`: POL/USD on Polygon,
-ETH/USD on Base. The SDK does not infer or fetch this price from a payment quote.
-Stablecoin payments use the selected deployment's pinned token and exact USD minor
-units. No native price is needed for stablecoin settlement.
-
-On Base, `maxGasWei` covers the estimated L2 execution fee plus buffered L1 data and
-operator fees, including approval when needed. This preflight estimate can change
-before inclusion; the transaction cannot enforce a hard cap on L1/operator fees.
-An unavailable fee oracle blocks signing. See the [Base configuration and recovery
-guide](./PAYMENT_RECEIPTS.md).
+Version **2.5.0** (source candidate) extends the existing signed AIFP-1 `fetchPaid`
+flow to Polygon, Base, Optimism, Arbitrum, Avalanche, BNB, Unichain, XRPL EVM and
+Robinhood. Polygon remains the default; select another network explicitly with
+`v14.chain`. A descriptor is client capability, not production readiness: the
+merchant must authorize the chain and the backend must serve/verifiably settle it.
+Runtime, signer, token, RPC-chain and current profile checks remain mandatory,
+along with a durable pre-broadcast journal and explicit native gas budget.
+
+Native purchases require a fresh independent `nativeUsdPrice` for POL, ETH, AVAX,
+BNB or XRP on the selected chain. Stablecoins use an independently pinned token
+address and decimals. USD micro-units remain unchanged; `token_settlement` binds
+exact6/18-decimal token units and every gross-inclusive leg to the signed gross
+and exact approval.18-decimal tokens require this metadata; legacy6-decimal
+quotes remain accepted. XRPL EVM currently has no pinned stablecoin.
+
+`maxGasWei` covers approval plus settlement. OP chains (Base/Optimism/Unichain)
+include buffered L1/operator estimates; Nitro (Arbitrum/Robinhood) already includes
+parent-data gas in the RPC estimate, so it is counted once. Unavailable OP fees
+block signing. These are preflight estimates, not inclusion-time guarantees.
+Current admin profiles remain mutable; receipt and recovery policy is unchanged.
+See [payment configuration and recovery](./PAYMENT_RECEIPTS.md).
+
+The 2.5 candidate also adds owner-selected `solanaV14` paid access for SOL9 and
+classic SPL6 USDC/USDT. Network and environment, local Ed25519 payer,
+independently sourced SOL/USD and `maxFeeLamports` (transaction fees **plus all
+nonce/ATA rent**) are separate from EVM options. `v14` and `solanaV14` together
+are rejected. Canonical Solana flags remain disabled: this source is conditional,
+not a production activation or published 2.5 claim.
+
+The exact 216-byte quote and 297-byte instruction follow the packaged pinned IDL.
+Fresh genesis/config/profile/mint/nonce/account evidence and unsigned final-message
+simulation precede budget reservation and local signing. Signed bytes are saved
+before the single send. Unknown signature outcomes never expire or authorize a
+replacement transaction. A canonical finalized failure retains only its proven
+fee debit; missing proof retains the full reservation. Public history/quota
+select Solana cluster explicitly and never expose bearer receipts.
 
 ### Link the agent to its owner's dashboard
 
@@ -69,7 +89,7 @@ npm pack
 Install the resulting tarball in your application:
 
 ```bash
-npm install /absolute/path/to/sdk/node/aifinpay-agent-2.3.0.tgz
+npm install /absolute/path/to/sdk/node/aifinpay-agent-<version>.tgz
 ```
 
 ## Quick start
@@ -104,7 +124,8 @@ inputs and wallet files out of chats, logs and version control.
 The same configured inputs restore the same addresses after a process restart.
 An explicit `evmPrivateKey` option overrides the derived EVM identity; retain
 that separate key as well to recover the imported wallet. Loading a wallet
-does not enable the RC's gated settlement routes.
+does not by itself pay for anything; paid execution goes through `fetchPaid`
+and its checks.
 
 `AiFinPayAgent.new()` and `Agent.new()` intentionally create a fresh ephemeral
 wallet each time. They do not load existing environment variables or keystores
@@ -126,24 +147,34 @@ const agent2 = Agent.fromSecretB58("3RvZm7Gw...");
 
 ## How x402 auth works under the hood
 
-For every gated request the SDK:
-
-1. `GET /nonce` → receives a one-time UUID with 60s TTL.
-2. computes `SHA-256("AiFinPay-x402:{nonce}:{pubkey}")`.
-3. signs with Ed25519, base58-encodes the signature.
+`Agent.pay(url)` (and `get`/`post`/`request`) handles an AiFinPay-native 402
+with request-bound auth (version 2). For a gated request the SDK:
+
+1. sends the request without credentials; the 402 body carries a one-time
+   `x-nonce`, its expiry `x-nonce-expires-at`, `x-aifinpay-auth-version: 2`
+   and the SHA-256 of the request body it was issued for;
+2. refuses to sign unless the request went to the origin configured as the
+   agent's `baseUrl`, the response came from that origin, and the body digest
+   matches the body it sent;
+3. signs, with Ed25519, the SHA-256 of
+   `JSON.stringify(["AiFinPay-x402", "v2", nonce, pubkey, origin, METHOD, path+query, bodySha256, expiresAt])`
+   and base58-encodes the signature;
 4. retries the original request with headers:
    - `x-agent-pubkey: <base58 pubkey>`
-   - `x-nonce: <uuid>`
+   - `x-nonce: <nonce>`
    - `x-signature: <base58 sig>`
+   - `x-aifinpay-auth-version: 2`
 
-The server verifies the signature, checks the agent has a live Seat PDA
-on-chain, and serves the resource.
+The server verifies the signature, consumes the nonce, checks the agent has a
+live Seat PDA on-chain, and serves the resource. The retired v1 format
+(`GET /nonce`, `SHA-256("AiFinPay-x402:{nonce}:{pubkey}")`) is refused, and
+`Agent.authHeaders()` throws.
 
 ## Privacy
 
 - **The server never sees your private key.** Period.
 - Nonces are consumed on use; replay-resistant.
-- All transactions are public and on-chain — Solana + Polygon mainnet.
+- Payments settle on public chains — the explicitly selected EVM network — and are visible on-chain.
 
 ## License
 

package/dist/agentHistory.d.ts

@@ -1,9 +1,12 @@
 import { type AgentPassportNetwork } from "./agentPassport.js";
+import type { SolanaNetwork } from "./generated/solanaV14Deployments.generated.js";
 export interface AgentHistoryOptions {
     address?: string;
     /** Public @username, AIFP number or aifp_agent_* identifier; never a secret. */
     passport?: string;
     network?: AgentPassportNetwork;
+    /** Required with network="solana"; never infer a cluster from an address. */
+    solanaNetwork?: SolanaNetwork;
     source?: "transactions" | "receipts";
     limit?: number;
     offset?: number;
@@ -18,6 +21,8 @@ export declare const AGENT_TRANSACTION_FIELDS: string[];
 export declare function getAgentHistory(options: AgentHistoryOptions): Promise<Record<string, unknown>>;
 export interface QuotaOptions {
     address: string;
+    network?: AgentPassportNetwork;
+    solanaNetwork?: SolanaNetwork;
     /** Optional mrch_… filter — only batches bought from this service. */
     merchantId?: string;
     /** Also list batches with 0 remaining (still retained, not yet expired). */
@@ -36,6 +41,10 @@ export interface QuotaBatch {
     paid?: string;
     expires?: string;
     receipt_id?: string;
+    chain?: string;
+    network?: SolanaNetwork;
+    program?: string;
+    asset?: string;
 }
 export interface QuotaSummary {
     agent: string;

package/dist/agentHistory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agentHistory.d.ts","sourceRoot":"","sources":["../src/agentHistory.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6C,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAG1G,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAC/B,MAAM,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,wGAAwG;AACxG,eAAO,MAAM,oBAAoB,UAoBhC,CAAC;AAEF,4GAA4G;AAC5G,eAAO,MAAM,wBAAwB,UAcpC,CAAC;AAEF,uFAAuF;AACvF,wBAAsB,eAAe,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CA8DpG;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,MAAM,WAAW,UAAU;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/D,OAAO,EAAE,UAAU,EAAE,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAsC3E"}
+{"version":3,"file":"agentHistory.d.ts","sourceRoot":"","sources":["../src/agentHistory.ts"],"names":[],"mappings":"AAAA,OAAO,EAA6C,KAAK,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAI1G,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+CAA+C,CAAC;AAEnF,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAC/B,6EAA6E;IAC7E,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,MAAM,CAAC,EAAE,cAAc,GAAG,UAAU,CAAC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,wGAAwG;AACxG,eAAO,MAAM,oBAAoB,UAuBhC,CAAC;AAEF,4GAA4G;AAC5G,eAAO,MAAM,wBAAwB,UAyBpC,CAAC;AAgDF,uFAAuF;AACvF,wBAAsB,eAAe,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAyEpG;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAC/B,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,MAAM,WAAW,UAAU;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/D,OAAO,EAAE,UAAU,EAAE,CAAC;CACvB;AAED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAkE3E"}

package/dist/agentHistory.js

@@ -1,5 +1,7 @@
 import { resolveAgentPassport, agentPassportWallet } from "./agentPassport.js";
 import { aifinpayApiUrl } from "./apiUrl.js";
+import { PublicKey } from "@solana/web3.js";
+import { solanaV14Inventory } from "./settlementSolanaV14.js";
 /** Public fields returned for source="receipts". Single source of truth — MCP must import, not copy. */
 export const AGENT_RECEIPT_FIELDS = [
     "receipt_id",
@@ -21,6 +23,9 @@ export const AGENT_RECEIPT_FIELDS = [
     "expires_at",
     "unit_quota",
     "metering_version",
+    "asset",
+    "network",
+    "program",
 ];
 /** Public fields returned for source="transactions". Single source of truth — MCP must import, not copy. */
 export const AGENT_TRANSACTION_FIELDS = [
@@ -37,7 +42,58 @@ export const AGENT_TRANSACTION_FIELDS = [
     "merchant_amount",
     "treasury_fee",
     "ip_creator_fee",
+    "network",
+    "program",
+    "block_hash",
+    "nonce",
+    "treasury_address",
+    "fee_lamports",
+    "nonce_rent_lamports",
+    "ata_rent_lamports",
+    "cost_allocation",
+    "order_id_hash",
+    "route_id",
 ];
+function historyIdentity(address, network, cluster) {
+    if (network === "solana") {
+        if (!cluster)
+            throw new Error("Solana history requires an explicit solanaNetwork");
+        const d = solanaV14Inventory(cluster === "mainnet" ? "prod" : "dev", cluster);
+        try {
+            if (!address || new PublicKey(address).toBase58() !== address)
+                throw new Error();
+        }
+        catch {
+            throw new Error("History requires a canonical case-preserved Solana address");
+        }
+        return { address: address, network: cluster, program: d.programId };
+    }
+    if (cluster !== undefined)
+        throw new Error("solanaNetwork requires network=solana");
+    if (!address || !/^0x[0-9a-fA-F]{40}$/.test(address))
+        throw new Error("History requires an EVM address");
+    return { address: address.toLowerCase() };
+}
+function assertHistoryContext(body, selected, identityField = "address") {
+    if (selected.network &&
+        (!body ||
+            typeof body !== "object" ||
+            body.chain !== "solana" ||
+            body.network !== selected.network ||
+            body.program !== selected.program ||
+            body[identityField] !== selected.address))
+        throw new Error("History response changed the selected Solana payer/network/program");
+}
+function solanaCoverage(value) {
+    const v = value;
+    if (!v ||
+        typeof v !== "object" ||
+        v.coverage_kind !== "retained_rpc_inventory" ||
+        v.archive_complete !== false ||
+        !(v.coverage_start === null || (Number.isSafeInteger(v.coverage_start) && Number(v.coverage_start) > 0)))
+        throw new Error("Invalid retained Solana history coverage");
+    return { coverage_kind: v.coverage_kind, coverage_start: v.coverage_start, archive_complete: false };
+}
 /** Read public payment metadata. A passport is resolved to a verified wallet first. */
 export async function getAgentHistory(options) {
     const base = options.baseUrl || "https://aifinpay.io";
@@ -58,41 +114,55 @@ export async function getAgentHistory(options) {
     let address = options.address;
     if (options.passport) {
         const identity = await resolveAgentPassport(options.passport, base, fetchImpl);
-        identity.wallets = identity.wallets.filter((wallet) => wallet.chain_family === "evm" && Number(wallet.verified_at) > 0);
+        identity.wallets = identity.wallets.filter((wallet) => wallet.chain_family === (network === "solana" ? "solana" : "evm") && Number(wallet.verified_at) > 0);
         const wallet = agentPassportWallet(identity, network);
-        if (address && address.toLowerCase() !== wallet.address.toLowerCase()) {
+        if (address &&
+            (network === "solana" ? address !== wallet.address : address.toLowerCase() !== wallet.address.toLowerCase())) {
             throw new Error("Address does not match this passport's verified wallet on the requested network");
         }
         address = wallet.address;
     }
-    if (!address || !/^0x[0-9a-fA-F]{40}$/.test(address))
-        throw new Error("History requires an EVM address or a passport with an EVM wallet binding");
+    const selected = historyIdentity(address, network, options.solanaNetwork);
     const query = new URLSearchParams({ limit: String(limit), offset: String(offset) });
-    if (source === "transactions")
+    if (source === "transactions" || network === "solana")
         query.set("chain", network);
-    const response = await fetchImpl(aifinpayApiUrl(base, `/v1/agents/${address.toLowerCase()}/${source}?${query}`), {
+    if (selected.network) {
+        query.set("network", selected.network);
+        query.set("program", selected.program);
+    }
+    const response = await fetchImpl(aifinpayApiUrl(base, `/v1/agents/${selected.address}/${source}?${query}`), {
         headers: { accept: "application/json" },
     });
     if (!response.ok)
-        throw new Error(`Payment history unavailable: HTTP ${response.status}; source=${source}. Use receipts for retained prepaid batches; indexed transactions currently cover Polygon only.`);
+        throw new Error(`Payment history unavailable: HTTP ${response.status}; source=${source}; chain=${network}.`);
     const body = (await response.json());
     if (!body || typeof body !== "object" || !Array.isArray(body[source]))
         throw new Error("Invalid history response");
+    assertHistoryContext(body, selected);
     // Defense in depth: even a misconfigured/older backend must not send bearer
     // tokens to a caller of this metadata-only API.
     const fields = source === "receipts" ? AGENT_RECEIPT_FIELDS : AGENT_TRANSACTION_FIELDS;
-    const items = body[source].map((item) => Object.fromEntries(fields.filter((field) => item[field] !== undefined).map((field) => [field, item[field]])));
+    const items = body[source].map((item) => {
+        if (!item || typeof item !== "object")
+            throw new Error("Invalid history row");
+        assertHistoryContext(item, selected, source === "receipts" ? "payer" : "agent_address");
+        return Object.fromEntries(fields.filter((field) => item[field] !== undefined).map((field) => [field, item[field]]));
+    });
     return {
-        address: address.toLowerCase(),
+        address: selected.address,
+        ...(selected.network ? { chain: "solana", network: selected.network, program: selected.program } : {}),
         ...(options.passport ? { passport: options.passport } : {}),
         source,
         items,
         limit,
         offset,
         next_offset: typeof body.next_offset === "number" ? body.next_offset : null,
+        ...(selected.network && body.indexing !== undefined ? { indexing: solanaCoverage(body.indexing) } : {}),
         coverage: source === "receipts"
             ? "Retained AiFinPay receipts only; external merchant quota may lag"
-            : "Indexed AiFinPay Polygon settlements only; excludes arbitrary wallet transfers and may lag the chain",
+            : selected.network
+                ? "Verified AiFinPay settlements from retained RPC inventory only; partial history, no archive/full-wallet attestation. Shared transaction costs may be unallocated."
+                : `Indexed AiFinPay ${network} settlements only; excludes arbitrary wallet transfers and may lag the chain`,
     };
 }
 /**
@@ -104,15 +174,34 @@ export async function getAgentHistory(options) {
 export async function getQuota(options) {
     const base = (options.baseUrl || "https://aifinpay.io").replace(/\/+$/, "");
     const fetchImpl = options.fetchImpl || fetch;
-    const address = options.address.toLowerCase();
-    if (!/^0x[0-9a-fA-F]{40}$/.test(address))
-        throw new Error("Quota requires an EVM address");
-    const response = await fetchImpl(aifinpayApiUrl(base, `/v1/agents/${address}/receipts`), {
+    const selected = historyIdentity(options.address, options.network ?? "polygon", options.solanaNetwork);
+    const query = new URLSearchParams();
+    if (options.network)
+        query.set("chain", options.network);
+    if (selected.network) {
+        query.set("network", selected.network);
+        query.set("program", selected.program);
+    }
+    const response = await fetchImpl(aifinpayApiUrl(base, `/v1/agents/${selected.address}/receipts${query.size ? `?${query}` : ""}`), {
         headers: { accept: "application/json" },
     });
     if (!response.ok)
         throw new Error(`Quota lookup failed: HTTP ${response.status}`);
     const body = (await response.json());
+    if (!body || !Array.isArray(body.receipts))
+        throw new Error("Invalid quota response");
+    assertHistoryContext(body, selected);
+    body.receipts.forEach((row) => {
+        assertHistoryContext(row, selected, "payer");
+        if (selected.network &&
+            (![row.used, row.remaining, row.unit_quota].every((v) => Number.isSafeInteger(v) && Number(v) >= 0) ||
+                !Number.isSafeInteger(Number(row.used) + Number(row.remaining)) ||
+                Number(row.used) + Number(row.remaining) !== row.unit_quota ||
+                (row.exp !== undefined &&
+                    row.exp !== null &&
+                    (!Number.isSafeInteger(row.exp) || Number(row.exp) <= 0 || Number(row.exp) > 8640000000000))))
+            throw new Error("Malformed Solana unit quota, usage or expiry");
+    });
     const now = Math.floor(Date.now() / 1000);
     const num = (v, dflt) => (typeof v === "number" && Number.isFinite(v) ? v : dflt);
     const batches = (body.receipts ?? [])
@@ -126,10 +215,13 @@ export async function getQuota(options) {
         tier: typeof r.tier === "string" ? r.tier : undefined,
         used: num(r.used, 0),
         remaining: num(r.remaining, 0),
-        quota: num(r.quota, 1),
+        quota: selected.network ? Number(r.unit_quota) : num(r.quota, 1),
         paid: r.amount != null ? `${r.amount} ${typeof r.currency === "string" ? r.currency : "USD"}` : undefined,
         expires: typeof r.exp === "number" ? new Date(r.exp * 1000).toISOString() : undefined,
         receipt_id: typeof r.receipt_id === "string" ? r.receipt_id : undefined,
+        chain: typeof r.chain === "string" ? r.chain : undefined,
+        ...(selected.network ? { network: selected.network, program: selected.program } : {}),
+        asset: typeof r.asset === "string" ? r.asset : undefined,
     }))
         .sort((a, b) => b.remaining - a.remaining);
     const totals = {};
@@ -138,8 +230,10 @@ export async function getQuota(options) {
         const cur = totals[key] ?? { remaining: 0, batches: 0 };
         cur.remaining += b.remaining;
         cur.batches += 1;
+        if (selected.network && (!Number.isSafeInteger(cur.remaining) || !Number.isSafeInteger(cur.batches)))
+            throw new Error("Solana quota totals exceed safe integer bounds");
         totals[key] = cur;
     }
-    return { agent: address, totals, batches };
+    return { agent: selected.address, totals, batches };
 }
 //# sourceMappingURL=agentHistory.js.map