uvd-x402-sdk 2.108.0 → 2.110.0

package/README.md

@@ -10,7 +10,7 @@ Users sign a message or transaction, and the Ultravioleta facilitator handles on
 
 ## Features
 
-**Arras NEAR escrow (v2.108.0):** offline local-key NEP-366 authorization, canonical Rust payment IDs and pull lifecycle helpers through `uvd-x402-sdk/near`. [Guide and agent example](docs/near-escrow.md). As of 2026-11-02 the facilitator advertises escrow only on testnet, and the SDK's escrow contract registry has no mainnet row yet.
+**Arras NEAR escrow (v2.110.0):** offline local-key NEP-366 authorization, canonical Rust payment IDs and pull lifecycle helpers through `uvd-x402-sdk/near`. [Guide and agent example](docs/near-escrow.md). As of 2026-11-03 the production facilitator relays NEAR escrow only on testnet. Since 2.110.0 the registry allows mainnet escrow signing only for `v1.arras-escrow.near`; testnet keeps `arras-v1b-1101.testnet`.
 
 - **31 Networks**: EVM (19 including HashKey Chain, Arc, Scroll, SKALE Base, Robinhood Chain), Solana, Fogo, Stellar, NEAR, Algorand, Sui, XRP Ledger, Hedera (mainnet + testnet)
 - **Multi-Stablecoin**: USDC, EURC, AUSD, PYUSD, USDT, USDG (Robinhood Chain)

package/dist/providers/near/index.d.mts

@@ -19,7 +19,7 @@ interface PaymentIdParams extends EscrowMsgParams {
 }
 interface NearLocalSigner {
     readonly publicKey: Uint8Array;
-    /** Sign the NEP-366 SHA-256 digest directly, without a NEP-413 envelope. */
+    /** Sign the supplied SHA-256 digest directly. The calling helper supplies its domain prefix. */
     sign(digest: Uint8Array): Uint8Array | Promise<Uint8Array>;
 }
 interface NearEscrowDelegateOptions {
@@ -65,7 +65,7 @@ declare const NEAR_ESCROW_TOKENS: Readonly<Record<NearEscrowNetwork, string>>;
 /**
  * The Arras escrow deployments this SDK signs for, per network. Any other escrowContract is refused before the
  * signer is called, for authorization and lifecycle alike: a signed delegate can be relayed by anyone, so a 402
- * server must not be able to point it at its own account. Mainnet stays empty until its contract ships in a release.
+ * server must not be able to point it at its own account. Only deployed Arras v1 contracts are registered.
  */
 declare const NEAR_ESCROW_CONTRACTS: Readonly<Record<NearEscrowNetwork, readonly string[]>>;
 /** Canonical Arras JSON: field order, decimal-string timestamps, lowercase hex, no spaces. */
@@ -95,6 +95,154 @@ declare const withdrawFor: (o: NearEscrowDelegateOptions, account: string) => Pr
 interface AuthorizeFromBudget {
     authorizeFromBudget(request: unknown): Promise<NearEscrowPayment>;
 }
+/** Local-key exact NEP-366 payment; uses the escrow serializer and raw digest signer. */
+interface NearExactDelegateOptions extends Omit<NearEscrowDelegateOptions, 'escrowContract'> {
+    token: string;
+    payTo: string;
+    amount: NearUnsigned;
+}
+interface NearExactPayment extends Omit<NearEscrowPayment, 'scheme'> {
+    scheme: 'exact';
+}
+declare function signExactNearDelegate(options: NearExactDelegateOptions): Promise<NearExactPayment>;
+
+interface Nep413Message {
+    message: string;
+    nonce: Uint8Array;
+    recipient: string;
+    callbackUrl?: string;
+}
+interface SignNep413Options extends Nep413Message {
+    signer: NearLocalSigner;
+    accountId: string;
+}
+interface Nep413SignedMessage {
+    accountId: string;
+    publicKey: string;
+    signature: string;
+}
+/** Prefix 2^31+413 followed by message, fixed nonce, recipient and Option<String> callback. */
+declare function nep413Preimage(options: Nep413Message): Uint8Array;
+declare function signNep413(options: SignNep413Options): Promise<Nep413SignedMessage>;
+
+/** Payer-funded NEP-145 calls. These are unsigned normal transactions, never facilitator delegates. */
+
+interface NearStorageTransaction {
+    signerId: string;
+    receiverId: string;
+    actions: [
+        {
+            type: 'FunctionCall';
+            params: {
+                methodName: 'storage_deposit';
+                args: {
+                    account_id: string;
+                    registration_only: boolean;
+                };
+                gas: string;
+                deposit: string;
+            };
+        }
+    ];
+}
+interface NearStorageOptions {
+    network: NearEscrowNetwork;
+    /** Account that signs the normal transaction and pays its deposit and gas. */
+    payerId: string;
+    /** Account to register or fund; defaults to payerId. */
+    accountId?: string;
+    /** YoctoNEAR, not NEAR. Query storage_balance_bounds for the live contract minimum. */
+    deposit?: NearUnsigned;
+}
+/** Explicit deployment from NEAR_ESCROW_CONTRACTS for the selected network. */
+interface ArrasStorageOptions extends NearStorageOptions {
+    escrowContract: string;
+}
+declare const NEAR_ARRAS_STORAGE_DEPOSIT = "50000000000000000000000";
+declare const NEAR_USDC_STORAGE_DEPOSIT = "1250000000000000000000";
+/** Keep surplus available for payment storage; registration_only must be false for Arras. */
+declare function buildArrasStorageDeposit(options: ArrasStorageOptions): NearStorageTransaction;
+/** Register in native USDC; refund any surplus rather than topping up an FT registration. */
+declare function buildUsdcStorageDeposit(options: NearStorageOptions): NearStorageTransaction;
+
+interface ArrasAuthorizedData {
+    payment_id: string;
+    operator_id: string;
+    token: string;
+    payer: string;
+    receiver: string;
+    amount: string;
+    fee_bps: number;
+    fee_recipient: string;
+    terms_hash: string;
+}
+interface ArrasReleasedData {
+    payment_id: string;
+    amount: string;
+    net: string;
+    fee: string;
+}
+interface ArrasPaymentAmountData {
+    payment_id: string;
+    amount: string;
+}
+interface ArrasWithdrawnData {
+    account: string;
+    token: string;
+    amount: string;
+    ok: boolean;
+}
+interface ArrasCompactedData {
+    payment_id: string;
+}
+interface ArrasOperatorData {
+    operator_id: string;
+    owner?: string;
+    capturers?: string[];
+    fee_bps?: number;
+    fee_recipient?: string;
+    min_amount?: string;
+    tope_tvl_operador?: string;
+    tope_tvl_por_payer?: string;
+    sponsor_max_por_payer?: string;
+}
+interface ArrasCapsSetData {
+    by: string;
+    tope_por_pago: string;
+    tope_tvl_global: string;
+}
+interface ArrasPauseData {
+    by: string;
+    paused: boolean;
+    at: string;
+}
+interface ArrasEventData {
+    authorized: ArrasAuthorizedData;
+    released: ArrasReleasedData;
+    refunded: ArrasPaymentAmountData;
+    reclaimed: ArrasPaymentAmountData;
+    withdrawn: ArrasWithdrawnData;
+    compacted: ArrasCompactedData;
+    operator_registered: ArrasOperatorData;
+    operator_updated: ArrasOperatorData;
+    caps_set: ArrasCapsSetData;
+    paused: ArrasPauseData;
+    unpaused: ArrasPauseData;
+}
+type ArrasEvent = {
+    [K in keyof ArrasEventData]: {
+        standard: 'arras';
+        version: '1.0.0';
+        event: K;
+        data: ArrasEventData[K][];
+    };
+}[keyof ArrasEventData];
+/**
+ * Pass flattened receipt outcome logs. Foreign logs, malformed envelopes/data and unknown
+ * standards, versions or events are skipped. Preserve each batch and decimal integer bytes.
+ * Logs alone do not authenticate the emitter: the caller must check the receipt executor/status.
+ */
+declare function parseArrasEvents(logs: readonly unknown[]): ArrasEvent[];
 
 /**
  * uvd-x402-sdk - NEAR Provider
@@ -234,4 +382,4 @@ declare class NEARProvider implements WalletAdapter {
     private base58Encode;
 }
 
-export { type AuthorizeFromBudget, type EscrowAuthorizationOptions, type EscrowMsgParams, NEARProvider, NEAR_ESCROW_CONTRACTS, NEAR_ESCROW_MAX_GAS, NEAR_ESCROW_MIN_GAS, NEAR_ESCROW_TOKENS, type NearEscrowDelegate, type NearEscrowDelegateOptions, type NearEscrowFunctionCall, type NearEscrowLifecycleMethod, type NearEscrowNetwork, type NearEscrowPayment, type NearLocalSigner, type NearUnsigned, type PaymentIdParams, type WalletSelectorOptions, buildEscrowAuthorizationDelegate, buildEscrowMsg, computePaymentId, createNearLocalSigner, NEARProvider as default, paymentIdPreimage, reclaim, refund, release, signEscrowAuthorization, signEscrowLifecycle, validateEscrowAuthorizationDelegate, withdraw, withdrawFor };
+export { type ArrasAuthorizedData, type ArrasCapsSetData, type ArrasCompactedData, type ArrasEvent, type ArrasEventData, type ArrasOperatorData, type ArrasPauseData, type ArrasPaymentAmountData, type ArrasReleasedData, type ArrasStorageOptions, type ArrasWithdrawnData, type AuthorizeFromBudget, type EscrowAuthorizationOptions, type EscrowMsgParams, NEARProvider, NEAR_ARRAS_STORAGE_DEPOSIT, NEAR_ESCROW_CONTRACTS, NEAR_ESCROW_MAX_GAS, NEAR_ESCROW_MIN_GAS, NEAR_ESCROW_TOKENS, NEAR_USDC_STORAGE_DEPOSIT, type NearEscrowDelegate, type NearEscrowDelegateOptions, type NearEscrowFunctionCall, type NearEscrowLifecycleMethod, type NearEscrowNetwork, type NearEscrowPayment, type NearExactDelegateOptions, type NearExactPayment, type NearLocalSigner, type NearStorageOptions, type NearStorageTransaction, type NearUnsigned, type Nep413Message, type Nep413SignedMessage, type PaymentIdParams, type SignNep413Options, type WalletSelectorOptions, buildArrasStorageDeposit, buildEscrowAuthorizationDelegate, buildEscrowMsg, buildUsdcStorageDeposit, computePaymentId, createNearLocalSigner, NEARProvider as default, nep413Preimage, parseArrasEvents, paymentIdPreimage, reclaim, refund, release, signEscrowAuthorization, signEscrowLifecycle, signExactNearDelegate, signNep413, validateEscrowAuthorizationDelegate, withdraw, withdrawFor };

package/dist/providers/near/index.d.ts

@@ -19,7 +19,7 @@ interface PaymentIdParams extends EscrowMsgParams {
 }
 interface NearLocalSigner {
     readonly publicKey: Uint8Array;
-    /** Sign the NEP-366 SHA-256 digest directly, without a NEP-413 envelope. */
+    /** Sign the supplied SHA-256 digest directly. The calling helper supplies its domain prefix. */
     sign(digest: Uint8Array): Uint8Array | Promise<Uint8Array>;
 }
 interface NearEscrowDelegateOptions {
@@ -65,7 +65,7 @@ declare const NEAR_ESCROW_TOKENS: Readonly<Record<NearEscrowNetwork, string>>;
 /**
  * The Arras escrow deployments this SDK signs for, per network. Any other escrowContract is refused before the
  * signer is called, for authorization and lifecycle alike: a signed delegate can be relayed by anyone, so a 402
- * server must not be able to point it at its own account. Mainnet stays empty until its contract ships in a release.
+ * server must not be able to point it at its own account. Only deployed Arras v1 contracts are registered.
  */
 declare const NEAR_ESCROW_CONTRACTS: Readonly<Record<NearEscrowNetwork, readonly string[]>>;
 /** Canonical Arras JSON: field order, decimal-string timestamps, lowercase hex, no spaces. */
@@ -95,6 +95,154 @@ declare const withdrawFor: (o: NearEscrowDelegateOptions, account: string) => Pr
 interface AuthorizeFromBudget {
     authorizeFromBudget(request: unknown): Promise<NearEscrowPayment>;
 }
+/** Local-key exact NEP-366 payment; uses the escrow serializer and raw digest signer. */
+interface NearExactDelegateOptions extends Omit<NearEscrowDelegateOptions, 'escrowContract'> {
+    token: string;
+    payTo: string;
+    amount: NearUnsigned;
+}
+interface NearExactPayment extends Omit<NearEscrowPayment, 'scheme'> {
+    scheme: 'exact';
+}
+declare function signExactNearDelegate(options: NearExactDelegateOptions): Promise<NearExactPayment>;
+
+interface Nep413Message {
+    message: string;
+    nonce: Uint8Array;
+    recipient: string;
+    callbackUrl?: string;
+}
+interface SignNep413Options extends Nep413Message {
+    signer: NearLocalSigner;
+    accountId: string;
+}
+interface Nep413SignedMessage {
+    accountId: string;
+    publicKey: string;
+    signature: string;
+}
+/** Prefix 2^31+413 followed by message, fixed nonce, recipient and Option<String> callback. */
+declare function nep413Preimage(options: Nep413Message): Uint8Array;
+declare function signNep413(options: SignNep413Options): Promise<Nep413SignedMessage>;
+
+/** Payer-funded NEP-145 calls. These are unsigned normal transactions, never facilitator delegates. */
+
+interface NearStorageTransaction {
+    signerId: string;
+    receiverId: string;
+    actions: [
+        {
+            type: 'FunctionCall';
+            params: {
+                methodName: 'storage_deposit';
+                args: {
+                    account_id: string;
+                    registration_only: boolean;
+                };
+                gas: string;
+                deposit: string;
+            };
+        }
+    ];
+}
+interface NearStorageOptions {
+    network: NearEscrowNetwork;
+    /** Account that signs the normal transaction and pays its deposit and gas. */
+    payerId: string;
+    /** Account to register or fund; defaults to payerId. */
+    accountId?: string;
+    /** YoctoNEAR, not NEAR. Query storage_balance_bounds for the live contract minimum. */
+    deposit?: NearUnsigned;
+}
+/** Explicit deployment from NEAR_ESCROW_CONTRACTS for the selected network. */
+interface ArrasStorageOptions extends NearStorageOptions {
+    escrowContract: string;
+}
+declare const NEAR_ARRAS_STORAGE_DEPOSIT = "50000000000000000000000";
+declare const NEAR_USDC_STORAGE_DEPOSIT = "1250000000000000000000";
+/** Keep surplus available for payment storage; registration_only must be false for Arras. */
+declare function buildArrasStorageDeposit(options: ArrasStorageOptions): NearStorageTransaction;
+/** Register in native USDC; refund any surplus rather than topping up an FT registration. */
+declare function buildUsdcStorageDeposit(options: NearStorageOptions): NearStorageTransaction;
+
+interface ArrasAuthorizedData {
+    payment_id: string;
+    operator_id: string;
+    token: string;
+    payer: string;
+    receiver: string;
+    amount: string;
+    fee_bps: number;
+    fee_recipient: string;
+    terms_hash: string;
+}
+interface ArrasReleasedData {
+    payment_id: string;
+    amount: string;
+    net: string;
+    fee: string;
+}
+interface ArrasPaymentAmountData {
+    payment_id: string;
+    amount: string;
+}
+interface ArrasWithdrawnData {
+    account: string;
+    token: string;
+    amount: string;
+    ok: boolean;
+}
+interface ArrasCompactedData {
+    payment_id: string;
+}
+interface ArrasOperatorData {
+    operator_id: string;
+    owner?: string;
+    capturers?: string[];
+    fee_bps?: number;
+    fee_recipient?: string;
+    min_amount?: string;
+    tope_tvl_operador?: string;
+    tope_tvl_por_payer?: string;
+    sponsor_max_por_payer?: string;
+}
+interface ArrasCapsSetData {
+    by: string;
+    tope_por_pago: string;
+    tope_tvl_global: string;
+}
+interface ArrasPauseData {
+    by: string;
+    paused: boolean;
+    at: string;
+}
+interface ArrasEventData {
+    authorized: ArrasAuthorizedData;
+    released: ArrasReleasedData;
+    refunded: ArrasPaymentAmountData;
+    reclaimed: ArrasPaymentAmountData;
+    withdrawn: ArrasWithdrawnData;
+    compacted: ArrasCompactedData;
+    operator_registered: ArrasOperatorData;
+    operator_updated: ArrasOperatorData;
+    caps_set: ArrasCapsSetData;
+    paused: ArrasPauseData;
+    unpaused: ArrasPauseData;
+}
+type ArrasEvent = {
+    [K in keyof ArrasEventData]: {
+        standard: 'arras';
+        version: '1.0.0';
+        event: K;
+        data: ArrasEventData[K][];
+    };
+}[keyof ArrasEventData];
+/**
+ * Pass flattened receipt outcome logs. Foreign logs, malformed envelopes/data and unknown
+ * standards, versions or events are skipped. Preserve each batch and decimal integer bytes.
+ * Logs alone do not authenticate the emitter: the caller must check the receipt executor/status.
+ */
+declare function parseArrasEvents(logs: readonly unknown[]): ArrasEvent[];
 
 /**
  * uvd-x402-sdk - NEAR Provider
@@ -234,4 +382,4 @@ declare class NEARProvider implements WalletAdapter {
     private base58Encode;
 }
 
-export { type AuthorizeFromBudget, type EscrowAuthorizationOptions, type EscrowMsgParams, NEARProvider, NEAR_ESCROW_CONTRACTS, NEAR_ESCROW_MAX_GAS, NEAR_ESCROW_MIN_GAS, NEAR_ESCROW_TOKENS, type NearEscrowDelegate, type NearEscrowDelegateOptions, type NearEscrowFunctionCall, type NearEscrowLifecycleMethod, type NearEscrowNetwork, type NearEscrowPayment, type NearLocalSigner, type NearUnsigned, type PaymentIdParams, type WalletSelectorOptions, buildEscrowAuthorizationDelegate, buildEscrowMsg, computePaymentId, createNearLocalSigner, NEARProvider as default, paymentIdPreimage, reclaim, refund, release, signEscrowAuthorization, signEscrowLifecycle, validateEscrowAuthorizationDelegate, withdraw, withdrawFor };
+export { type ArrasAuthorizedData, type ArrasCapsSetData, type ArrasCompactedData, type ArrasEvent, type ArrasEventData, type ArrasOperatorData, type ArrasPauseData, type ArrasPaymentAmountData, type ArrasReleasedData, type ArrasStorageOptions, type ArrasWithdrawnData, type AuthorizeFromBudget, type EscrowAuthorizationOptions, type EscrowMsgParams, NEARProvider, NEAR_ARRAS_STORAGE_DEPOSIT, NEAR_ESCROW_CONTRACTS, NEAR_ESCROW_MAX_GAS, NEAR_ESCROW_MIN_GAS, NEAR_ESCROW_TOKENS, NEAR_USDC_STORAGE_DEPOSIT, type NearEscrowDelegate, type NearEscrowDelegateOptions, type NearEscrowFunctionCall, type NearEscrowLifecycleMethod, type NearEscrowNetwork, type NearEscrowPayment, type NearExactDelegateOptions, type NearExactPayment, type NearLocalSigner, type NearStorageOptions, type NearStorageTransaction, type NearUnsigned, type Nep413Message, type Nep413SignedMessage, type PaymentIdParams, type SignNep413Options, type WalletSelectorOptions, buildArrasStorageDeposit, buildEscrowAuthorizationDelegate, buildEscrowMsg, buildUsdcStorageDeposit, computePaymentId, createNearLocalSigner, NEARProvider as default, nep413Preimage, parseArrasEvents, paymentIdPreimage, reclaim, refund, release, signEscrowAuthorization, signEscrowLifecycle, signExactNearDelegate, signNep413, validateEscrowAuthorizationDelegate, withdraw, withdrawFor };