@naculus/connect-appkit-core 0.6.0 → 0.8.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { Namespace, UniversalWalletSession, WalletCapabilities, TokenConfig, WalletError, WalletErrorCode, SimulationResult, NameResolverConfig, NameResolver, NotificationSettings, InAppChannel, NotificationItem, SessionKeyManagerConfig, SessionKeyManager, Hex, UserOperationReceipt, Address, SmartAccountConfig, AtomicityRequirement, ExecutionPlan, SessionKeyInfo, SessionKeyTransaction, delegationTypedData, SessionKeyScope, ScopeCheckResult, SolanaSessionKeyInfo, SolanaSessionKeyScope, SolanaSessionKeyManager, SolanaPaymentRpc } from '@naculus/connect-core';
+import { Namespace, UniversalWalletSession, WalletCapabilities, TokenConfig, WalletError, WalletErrorCode, SimulationResult, NameResolverConfig, NameResolver, NotificationSettings, InAppChannel, NotificationItem, SessionKeyManagerConfig, SessionKeyManager, Hex, UserOperationReceipt, Address, SmartAccountConfig, AtomicityRequirement, ExecutionPlan, SessionKeyInfo, SessionKeyTransaction, delegationTypedData, SessionKeyScope, ScopeCheckResult, SpendRefusal, Authorization, ListedAuthorization, SpendRequest, SettlementVerification, SolanaSessionKeyInfo, SolanaSessionKeyScope, SolanaSessionKeyManager, SolanaPaymentRpc } from '@naculus/connect-core';
 
 /**
  * The types the framework-neutral half of appkit is built on.
@@ -43,7 +43,7 @@ interface Web3State {
 }
 
 /**
- * EIP-5792 capability answers, normalised once.
+ * EIP-5792 capability answers, normalized once.
  *
  * Deciding how to execute before sending is the whole point of
  * `wallet_getCapabilities`, and the reasoning that turns a raw answer into
@@ -82,7 +82,7 @@ declare function normalizeCapabilities(raw: Record<string, unknown> | null | und
 /**
  * Find the entry for a chain, by CAIP-2 or by the hex form.
  *
- * Connectors normalise keys to CAIP-2, but a wallet answering in raw hex
+ * Connectors normalize keys to CAIP-2, but a wallet answering in raw hex
  * through a custom connector should still be found rather than reported as
  * "unknown" next to an entry that is sitting right there.
  */
@@ -484,6 +484,15 @@ declare function createNotificationSettingsStorage(): NotificationSettingsStorag
 declare function loadNotificationSettings(storage: NotificationSettingsStorage): Promise<NotificationSettings | null>;
 declare function saveNotificationSettings(storage: NotificationSettingsStorage, settings: NotificationSettings): void;
 declare function updateNotificationSettings(current: NotificationSettings, update: Partial<NotificationSettings>): NotificationSettings;
+/** One settings change, computed from the settings it applies to. */
+type NotificationSettingsUpdate = (current: NotificationSettings) => Partial<NotificationSettings>;
+/**
+ * The settings once the persisted ones finish loading: every change made
+ * before the load resolved, replayed in order on top of what was persisted
+ * (or the defaults when nothing was). Without this the late load overwrote
+ * those changes, e.g. a chain muted during the first render came back.
+ */
+declare function replayNotificationSettings(persisted: NotificationSettings | null, updates: readonly NotificationSettingsUpdate[]): NotificationSettings;
 declare function channelsUpdate(channels: string[]): Partial<NotificationSettings>;
 declare function mutedChainSettings(settings: NotificationSettings, chainId: string, muted: boolean): Partial<NotificationSettings>;
 declare function createNotification(item: Omit<NotificationItem, "id" | "timestamp">): NotificationItem;
@@ -609,7 +618,7 @@ type ExecuteRoute = (quote: ExecutableQuote, recipient: string, options?: Execut
  * a valid non-EVM address on a guess.
  */
 declare function validateRouteRecipient(quote: ExecutableQuote | null | undefined, recipient: string): ExecuteRouteError | null;
-/** Normalise whatever an executor threw into the hook's error shape. */
+/** Normalize whatever an executor threw into the hook's error shape. */
 declare function toExecuteRouteError(cause: unknown): ExecuteRouteError;
 
 /** The subset of the config that changes what a key may spend or how it is sealed. */
@@ -845,6 +854,62 @@ interface DelegationFrameworkAdapterOptions {
 }
 declare function createDelegationFrameworkAdapter(options: DelegationFrameworkAdapterOptions): PolicyExecutionAdapter;
 
+type AssetId = string;
+interface AuthorizationAssetMetadata {
+    symbol: string;
+    decimals: number;
+}
+interface DescribeAuthorizationOptions {
+    assets?: Record<AssetId, AuthorizationAssetMetadata>;
+    locale?: string;
+    /** Unix timestamp in seconds. */
+    now?: number;
+}
+interface AuthorizationRecipientView {
+    shortened: string;
+    full: string;
+}
+interface AuthorizationAmountView {
+    formatted: string;
+}
+interface AuthorizationGrantView {
+    asset: AssetId;
+    assetLabel: string;
+    recipients: AuthorizationRecipientView[];
+    perPayment: AuthorizationAmountView;
+    total: AuthorizationAmountView;
+    count: number | null;
+    rails: string[];
+}
+interface AuthorizationExpiryView {
+    timestamp: number;
+    absolute: string;
+    relative: string;
+}
+interface AuthorizationDescription {
+    label: string | null;
+    principal: string | null;
+    grants: AuthorizationGrantView[];
+    expiry: AuthorizationExpiryView;
+    warnings: string[];
+}
+declare function formatAuthorizationAmount(amount: bigint, metadata: AuthorizationAssetMetadata | undefined): AuthorizationAmountView;
+/** Build a network-free consent/listing view of an authorization. */
+declare function describeAuthorization(input: Authorization | ListedAuthorization, options?: DescribeAuthorizationOptions): AuthorizationDescription;
+type SpendExplanation = {
+    allowed: true;
+    grant: number;
+    remainingTotal: bigint;
+    remainingTotalFormatted: AuthorizationAmountView;
+    sentence: string;
+} | {
+    allowed: false;
+    reason: SpendRefusal;
+    sentence: string;
+};
+/** Explain the shared evaluator's exact allow/refuse result for a UI. */
+declare function explainSpend(authorization: Authorization, request: SpendRequest, options?: DescribeAuthorizationOptions): SpendExplanation;
+
 /**
  * Agentic payments (x402 / MPP) for the appkit shells.
  *
@@ -852,7 +917,7 @@ declare function createDelegationFrameworkAdapter(options: DelegationFrameworkAd
  * `@naculus/payments-x402` or `createMppFetch` from `@naculus/payments-mpp`,
  * with the session key and limits it chooses — and the hooks only track its
  * state. So appkit takes no dependency on either package: their results are
- * read here by shape, and a shape this does not recognise is reported as
+ * read here by shape, and a shape this does not recognize is reported as
  * `protocol: "unknown"` rather than guessed at.
  */
 /** What `createX402Fetch` and `createMppFetch` return, structurally. */
@@ -866,6 +931,11 @@ interface PaymentFetchResult {
     receipt?: unknown;
 }
 type PaymentFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<PaymentFetchResult>;
+type PaymentVerificationStatus = "unverified" | "pending" | "verified" | "mismatch" | "failed" | "unavailable";
+interface PaymentVerification {
+    status: PaymentVerificationStatus;
+    reason?: string;
+}
 /** One payment, in the terms a UI shows. Amounts are token base units. */
 interface PaymentRecord {
     protocol: "x402" | "mpp" | "unknown";
@@ -882,7 +952,19 @@ interface PaymentRecord {
      * other fields are what the client signed.
      */
     reference: string | null;
+    /** A server-reported reference remains unverified until this is verified. */
+    verification: PaymentVerification;
+}
+declare const DEFAULT_VERIFY_RETRY: {
+    readonly attempts: 5;
+    readonly delayMs: 4000;
+};
+interface VerifyRetryOptions {
+    attempts: number;
+    delayMs: number;
 }
+/** Apply a verifier result without mutating the payment record. */
+declare function applySettlementVerification(payment: PaymentRecord, result: SettlementVerification): PaymentRecord;
 /**
  * The payment a paying fetch made, or null when it paid nothing. Reads the
  * x402 requirement / settlement (EVM or Solana) or the MPP `evm` / `solana`
@@ -890,6 +972,60 @@ interface PaymentRecord {
  */
 declare function describePayment(input: RequestInfo | URL, result: PaymentFetchResult): PaymentRecord | null;
 
+/** Request options accepted by a caller-built MPP session fetch. */
+interface MppSessionRequestInit extends RequestInit {
+    units?: bigint;
+}
+/** An open MPP payment channel, represented without depending on payments-mpp. */
+interface MppSessionChannel {
+    channelId: string;
+    payer: string;
+    payee: string;
+    mint: string;
+    channelProgram: string;
+    deposit: bigint;
+    gracePeriodSeconds: number;
+    openSlot: bigint;
+    salt: bigint;
+}
+/** A successful MPP receipt, represented structurally. */
+interface MppSessionReceipt {
+    status: "success";
+    method: string;
+    timestamp: string;
+    reference: string;
+    [field: string]: unknown;
+}
+interface MppSessionFetchResult {
+    response: Response;
+    receipt: unknown;
+    channel: unknown;
+}
+type MppSessionRequest = (input: RequestInfo | URL, init?: MppSessionRequestInit) => Promise<MppSessionFetchResult>;
+interface MppSessionForceCloseResult {
+    requestCloseTxHash: string;
+    withdrawPayer(): Promise<string>;
+}
+interface MppSessionMeter {
+    add(units: bigint): void;
+    readonly pending: bigint;
+}
+/** The caller-owned session surface consumed by the React and Vue shells. */
+interface MppSessionFetch extends MppSessionRequest {
+    readonly meter: MppSessionMeter;
+    readonly channels: readonly unknown[];
+    close(): Promise<MppSessionFetchResult>;
+    forceClose(): Promise<MppSessionForceCloseResult>;
+}
+/** Return a channel only when all public fields have the expected shape. */
+declare function readMppSessionChannel(value: unknown): MppSessionChannel | null;
+/** Return the newest structurally valid channel currently held by a session. */
+declare function readCurrentMppSessionChannel(session: Pick<MppSessionFetch, "channels">): MppSessionChannel | null;
+/** Return a receipt only when it has the public success-receipt shape. */
+declare function readMppSessionReceipt(value: unknown): MppSessionReceipt | null;
+/** A post-send channel-open failure carries the channel that can be recovered. */
+declare function readMppRecoveryChannelId(error: unknown): string | null;
+
 /**
  * Solana session keys for the appkit shells (connect-lib STATE thread 18).
  *
@@ -1016,4 +1152,4 @@ declare function siwxResultToSession<M extends SiwxMessageLike>(result: SiwxResu
     refreshedAt: null;
 };
 
-export { type AddressValidationLevel, type AtomicSupport, type ChainCapabilities, type ChainInfo, type CompareCosts, type CompareCostsInput, type ConnectionStatus, type CostComparison, type CostComparisonOperation, type CostComparisonOptions, DEFAULT_NOTIFICATION_SETTINGS, type DecimalsCache, type DelegationFrameworkAdapterOptions, type DelegationPolicyDeps, type DelegationPolicyFlow, type DelegationPolicyPreview, type DelegationTypedData, type DestinationIssue, type DestinationValidation, type ExecutableQuote, type ExecuteRoute, type ExecuteRouteError, type ExecuteRouteOptions, type ExecuteRouteResult, type GetRouteQuotes, InvalidUserOperationReceiptError, NOTIFICATION_SETTINGS_KEY, type NotificationSettingsStorage, type PaymentFetch, type PaymentFetchResult, type PaymentRecord, type PolicyExecutionAdapter, type PolicyExecutionCheck, type PolicyExecutionPreview, type PolicyExecutionRoute, type PolicyExecutionSubmission, type PolicySignatureVerifier, type PreparedPolicyExecution, type RedemptionCodec, type RedemptionRpc, type RedemptionTransaction, type RetryOptions, type RouteQuote, type RouteQuoteInput, type RouteQuoteOptions, type SimulationCallClient, type SimulationTransaction, type SiwxLocation, type SiwxMessageLike, type SiwxResultLike, type SmartAccountOptionsLike, type SmartAccountType, type SolanaIdentity, type SolanaOwnerSigner, type SolanaPayer, type SolanaRoles, type SolanaRolesAbsence, type SolanaRolesSource, type SolanaRolesState, type SolanaSessionKeyFlow, type SolanaSessionKeyFlowDeps, type SolanaSigner, type SolanaWalletFeatures, type TokenIdentity, type TransactionSimulationContext, type ViemChainShape, type WalletChain, type Web3Action, type Web3State, __resetResolverForTests, addInAppNotification, assertHexSignature, atomicSupportFor, bareEvmAddress, buildDelegationPolicyMessage, buildSmartAccountConfig, chainNamespace, chainNumber, chainsForNamespace, channelsUpdate, clearOneInAppNotification, compareCostsKey, createDecimalsCache, createDelegationFrameworkAdapter, createDelegationPolicyFlow, createNotification, createNotificationSettingsStorage, createSolanaSessionKeyFlow, decodeRevertReason, defaultSiwxDomain, defaultSiwxUri, describeChain, describePayment, eip155ChainIdToNumber, encodeErc20Approve, encodeErc20Transfer, encodeErc20TransferFrom, fetchUserOperationReceipt, getResolver, getSharedSessionKeyManager, initialWeb3State, isBurnDestination, isEvmChainId, isPositiveIntegerAmount, isQuotableInput, isSiwxExpired, isSiwxNotBeforeValid, isVerifiablePolicy, loadNotificationSettings, mutedChainSettings, normalizeCapabilities, normalizeEip155ChainId, parseUserOperationReceipt, readDecimals, readSolanaRoles, resetSharedSessionKeyManager, resolveChain, resolveContextSimulationEndpoint, resolveEvmChainId, resolveRevertReason, resolveSimulationEndpoint, resolveUserOpChain, sameExecutionIntent, saveNotificationSettings, selectChainCapabilities, sessionKeyConfigFingerprint, simulateTransactionPreview, siwxResultToSession, toChainSwitchError, toEip155Accounts, toExecuteRouteError, toViemChain, tokenChainMismatch, tokenKey, updateNotificationSettings, validateDestination, validateRouteRecipient, web3Reducer, withRetry, withTimeout, writeDecimals };
+export { type AddressValidationLevel, type AssetId, type AtomicSupport, type AuthorizationAmountView, type AuthorizationAssetMetadata, type AuthorizationDescription, type AuthorizationExpiryView, type AuthorizationGrantView, type AuthorizationRecipientView, type ChainCapabilities, type ChainInfo, type CompareCosts, type CompareCostsInput, type ConnectionStatus, type CostComparison, type CostComparisonOperation, type CostComparisonOptions, DEFAULT_NOTIFICATION_SETTINGS, DEFAULT_VERIFY_RETRY, type DecimalsCache, type DelegationFrameworkAdapterOptions, type DelegationPolicyDeps, type DelegationPolicyFlow, type DelegationPolicyPreview, type DelegationTypedData, type DescribeAuthorizationOptions, type DestinationIssue, type DestinationValidation, type ExecutableQuote, type ExecuteRoute, type ExecuteRouteError, type ExecuteRouteOptions, type ExecuteRouteResult, type GetRouteQuotes, InvalidUserOperationReceiptError, type MppSessionChannel, type MppSessionFetch, type MppSessionFetchResult, type MppSessionForceCloseResult, type MppSessionMeter, type MppSessionReceipt, type MppSessionRequest, type MppSessionRequestInit, NOTIFICATION_SETTINGS_KEY, type NotificationSettingsStorage, type NotificationSettingsUpdate, type PaymentFetch, type PaymentFetchResult, type PaymentRecord, type PaymentVerification, type PaymentVerificationStatus, type PolicyExecutionAdapter, type PolicyExecutionCheck, type PolicyExecutionPreview, type PolicyExecutionRoute, type PolicyExecutionSubmission, type PolicySignatureVerifier, type PreparedPolicyExecution, type RedemptionCodec, type RedemptionRpc, type RedemptionTransaction, type RetryOptions, type RouteQuote, type RouteQuoteInput, type RouteQuoteOptions, type SimulationCallClient, type SimulationTransaction, type SiwxLocation, type SiwxMessageLike, type SiwxResultLike, type SmartAccountOptionsLike, type SmartAccountType, type SolanaIdentity, type SolanaOwnerSigner, type SolanaPayer, type SolanaRoles, type SolanaRolesAbsence, type SolanaRolesSource, type SolanaRolesState, type SolanaSessionKeyFlow, type SolanaSessionKeyFlowDeps, type SolanaSigner, type SolanaWalletFeatures, type SpendExplanation, type TokenIdentity, type TransactionSimulationContext, type VerifyRetryOptions, type ViemChainShape, type WalletChain, type Web3Action, type Web3State, __resetResolverForTests, addInAppNotification, applySettlementVerification, assertHexSignature, atomicSupportFor, bareEvmAddress, buildDelegationPolicyMessage, buildSmartAccountConfig, chainNamespace, chainNumber, chainsForNamespace, channelsUpdate, clearOneInAppNotification, compareCostsKey, createDecimalsCache, createDelegationFrameworkAdapter, createDelegationPolicyFlow, createNotification, createNotificationSettingsStorage, createSolanaSessionKeyFlow, decodeRevertReason, defaultSiwxDomain, defaultSiwxUri, describeAuthorization, describeChain, describePayment, eip155ChainIdToNumber, encodeErc20Approve, encodeErc20Transfer, encodeErc20TransferFrom, explainSpend, fetchUserOperationReceipt, formatAuthorizationAmount, getResolver, getSharedSessionKeyManager, initialWeb3State, isBurnDestination, isEvmChainId, isPositiveIntegerAmount, isQuotableInput, isSiwxExpired, isSiwxNotBeforeValid, isVerifiablePolicy, loadNotificationSettings, mutedChainSettings, normalizeCapabilities, normalizeEip155ChainId, parseUserOperationReceipt, readCurrentMppSessionChannel, readDecimals, readMppRecoveryChannelId, readMppSessionChannel, readMppSessionReceipt, readSolanaRoles, replayNotificationSettings, resetSharedSessionKeyManager, resolveChain, resolveContextSimulationEndpoint, resolveEvmChainId, resolveRevertReason, resolveSimulationEndpoint, resolveUserOpChain, sameExecutionIntent, saveNotificationSettings, selectChainCapabilities, sessionKeyConfigFingerprint, simulateTransactionPreview, siwxResultToSession, toChainSwitchError, toEip155Accounts, toExecuteRouteError, toViemChain, tokenChainMismatch, tokenKey, updateNotificationSettings, validateDestination, validateRouteRecipient, web3Reducer, withRetry, withTimeout, writeDecimals };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Namespace, UniversalWalletSession, WalletCapabilities, TokenConfig, WalletError, WalletErrorCode, SimulationResult, NameResolverConfig, NameResolver, NotificationSettings, InAppChannel, NotificationItem, SessionKeyManagerConfig, SessionKeyManager, Hex, UserOperationReceipt, Address, SmartAccountConfig, AtomicityRequirement, ExecutionPlan, SessionKeyInfo, SessionKeyTransaction, delegationTypedData, SessionKeyScope, ScopeCheckResult, SolanaSessionKeyInfo, SolanaSessionKeyScope, SolanaSessionKeyManager, SolanaPaymentRpc } from '@naculus/connect-core';
+import { Namespace, UniversalWalletSession, WalletCapabilities, TokenConfig, WalletError, WalletErrorCode, SimulationResult, NameResolverConfig, NameResolver, NotificationSettings, InAppChannel, NotificationItem, SessionKeyManagerConfig, SessionKeyManager, Hex, UserOperationReceipt, Address, SmartAccountConfig, AtomicityRequirement, ExecutionPlan, SessionKeyInfo, SessionKeyTransaction, delegationTypedData, SessionKeyScope, ScopeCheckResult, SpendRefusal, Authorization, ListedAuthorization, SpendRequest, SettlementVerification, SolanaSessionKeyInfo, SolanaSessionKeyScope, SolanaSessionKeyManager, SolanaPaymentRpc } from '@naculus/connect-core';
 
 /**
  * The types the framework-neutral half of appkit is built on.
@@ -43,7 +43,7 @@ interface Web3State {
 }
 
 /**
- * EIP-5792 capability answers, normalised once.
+ * EIP-5792 capability answers, normalized once.
  *
  * Deciding how to execute before sending is the whole point of
  * `wallet_getCapabilities`, and the reasoning that turns a raw answer into
@@ -82,7 +82,7 @@ declare function normalizeCapabilities(raw: Record<string, unknown> | null | und
 /**
  * Find the entry for a chain, by CAIP-2 or by the hex form.
  *
- * Connectors normalise keys to CAIP-2, but a wallet answering in raw hex
+ * Connectors normalize keys to CAIP-2, but a wallet answering in raw hex
  * through a custom connector should still be found rather than reported as
  * "unknown" next to an entry that is sitting right there.
  */
@@ -484,6 +484,15 @@ declare function createNotificationSettingsStorage(): NotificationSettingsStorag
 declare function loadNotificationSettings(storage: NotificationSettingsStorage): Promise<NotificationSettings | null>;
 declare function saveNotificationSettings(storage: NotificationSettingsStorage, settings: NotificationSettings): void;
 declare function updateNotificationSettings(current: NotificationSettings, update: Partial<NotificationSettings>): NotificationSettings;
+/** One settings change, computed from the settings it applies to. */
+type NotificationSettingsUpdate = (current: NotificationSettings) => Partial<NotificationSettings>;
+/**
+ * The settings once the persisted ones finish loading: every change made
+ * before the load resolved, replayed in order on top of what was persisted
+ * (or the defaults when nothing was). Without this the late load overwrote
+ * those changes, e.g. a chain muted during the first render came back.
+ */
+declare function replayNotificationSettings(persisted: NotificationSettings | null, updates: readonly NotificationSettingsUpdate[]): NotificationSettings;
 declare function channelsUpdate(channels: string[]): Partial<NotificationSettings>;
 declare function mutedChainSettings(settings: NotificationSettings, chainId: string, muted: boolean): Partial<NotificationSettings>;
 declare function createNotification(item: Omit<NotificationItem, "id" | "timestamp">): NotificationItem;
@@ -609,7 +618,7 @@ type ExecuteRoute = (quote: ExecutableQuote, recipient: string, options?: Execut
  * a valid non-EVM address on a guess.
  */
 declare function validateRouteRecipient(quote: ExecutableQuote | null | undefined, recipient: string): ExecuteRouteError | null;
-/** Normalise whatever an executor threw into the hook's error shape. */
+/** Normalize whatever an executor threw into the hook's error shape. */
 declare function toExecuteRouteError(cause: unknown): ExecuteRouteError;
 
 /** The subset of the config that changes what a key may spend or how it is sealed. */
@@ -845,6 +854,62 @@ interface DelegationFrameworkAdapterOptions {
 }
 declare function createDelegationFrameworkAdapter(options: DelegationFrameworkAdapterOptions): PolicyExecutionAdapter;
 
+type AssetId = string;
+interface AuthorizationAssetMetadata {
+    symbol: string;
+    decimals: number;
+}
+interface DescribeAuthorizationOptions {
+    assets?: Record<AssetId, AuthorizationAssetMetadata>;
+    locale?: string;
+    /** Unix timestamp in seconds. */
+    now?: number;
+}
+interface AuthorizationRecipientView {
+    shortened: string;
+    full: string;
+}
+interface AuthorizationAmountView {
+    formatted: string;
+}
+interface AuthorizationGrantView {
+    asset: AssetId;
+    assetLabel: string;
+    recipients: AuthorizationRecipientView[];
+    perPayment: AuthorizationAmountView;
+    total: AuthorizationAmountView;
+    count: number | null;
+    rails: string[];
+}
+interface AuthorizationExpiryView {
+    timestamp: number;
+    absolute: string;
+    relative: string;
+}
+interface AuthorizationDescription {
+    label: string | null;
+    principal: string | null;
+    grants: AuthorizationGrantView[];
+    expiry: AuthorizationExpiryView;
+    warnings: string[];
+}
+declare function formatAuthorizationAmount(amount: bigint, metadata: AuthorizationAssetMetadata | undefined): AuthorizationAmountView;
+/** Build a network-free consent/listing view of an authorization. */
+declare function describeAuthorization(input: Authorization | ListedAuthorization, options?: DescribeAuthorizationOptions): AuthorizationDescription;
+type SpendExplanation = {
+    allowed: true;
+    grant: number;
+    remainingTotal: bigint;
+    remainingTotalFormatted: AuthorizationAmountView;
+    sentence: string;
+} | {
+    allowed: false;
+    reason: SpendRefusal;
+    sentence: string;
+};
+/** Explain the shared evaluator's exact allow/refuse result for a UI. */
+declare function explainSpend(authorization: Authorization, request: SpendRequest, options?: DescribeAuthorizationOptions): SpendExplanation;
+
 /**
  * Agentic payments (x402 / MPP) for the appkit shells.
  *
@@ -852,7 +917,7 @@ declare function createDelegationFrameworkAdapter(options: DelegationFrameworkAd
  * `@naculus/payments-x402` or `createMppFetch` from `@naculus/payments-mpp`,
  * with the session key and limits it chooses — and the hooks only track its
  * state. So appkit takes no dependency on either package: their results are
- * read here by shape, and a shape this does not recognise is reported as
+ * read here by shape, and a shape this does not recognize is reported as
  * `protocol: "unknown"` rather than guessed at.
  */
 /** What `createX402Fetch` and `createMppFetch` return, structurally. */
@@ -866,6 +931,11 @@ interface PaymentFetchResult {
     receipt?: unknown;
 }
 type PaymentFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<PaymentFetchResult>;
+type PaymentVerificationStatus = "unverified" | "pending" | "verified" | "mismatch" | "failed" | "unavailable";
+interface PaymentVerification {
+    status: PaymentVerificationStatus;
+    reason?: string;
+}
 /** One payment, in the terms a UI shows. Amounts are token base units. */
 interface PaymentRecord {
     protocol: "x402" | "mpp" | "unknown";
@@ -882,7 +952,19 @@ interface PaymentRecord {
      * other fields are what the client signed.
      */
     reference: string | null;
+    /** A server-reported reference remains unverified until this is verified. */
+    verification: PaymentVerification;
+}
+declare const DEFAULT_VERIFY_RETRY: {
+    readonly attempts: 5;
+    readonly delayMs: 4000;
+};
+interface VerifyRetryOptions {
+    attempts: number;
+    delayMs: number;
 }
+/** Apply a verifier result without mutating the payment record. */
+declare function applySettlementVerification(payment: PaymentRecord, result: SettlementVerification): PaymentRecord;
 /**
  * The payment a paying fetch made, or null when it paid nothing. Reads the
  * x402 requirement / settlement (EVM or Solana) or the MPP `evm` / `solana`
@@ -890,6 +972,60 @@ interface PaymentRecord {
  */
 declare function describePayment(input: RequestInfo | URL, result: PaymentFetchResult): PaymentRecord | null;
 
+/** Request options accepted by a caller-built MPP session fetch. */
+interface MppSessionRequestInit extends RequestInit {
+    units?: bigint;
+}
+/** An open MPP payment channel, represented without depending on payments-mpp. */
+interface MppSessionChannel {
+    channelId: string;
+    payer: string;
+    payee: string;
+    mint: string;
+    channelProgram: string;
+    deposit: bigint;
+    gracePeriodSeconds: number;
+    openSlot: bigint;
+    salt: bigint;
+}
+/** A successful MPP receipt, represented structurally. */
+interface MppSessionReceipt {
+    status: "success";
+    method: string;
+    timestamp: string;
+    reference: string;
+    [field: string]: unknown;
+}
+interface MppSessionFetchResult {
+    response: Response;
+    receipt: unknown;
+    channel: unknown;
+}
+type MppSessionRequest = (input: RequestInfo | URL, init?: MppSessionRequestInit) => Promise<MppSessionFetchResult>;
+interface MppSessionForceCloseResult {
+    requestCloseTxHash: string;
+    withdrawPayer(): Promise<string>;
+}
+interface MppSessionMeter {
+    add(units: bigint): void;
+    readonly pending: bigint;
+}
+/** The caller-owned session surface consumed by the React and Vue shells. */
+interface MppSessionFetch extends MppSessionRequest {
+    readonly meter: MppSessionMeter;
+    readonly channels: readonly unknown[];
+    close(): Promise<MppSessionFetchResult>;
+    forceClose(): Promise<MppSessionForceCloseResult>;
+}
+/** Return a channel only when all public fields have the expected shape. */
+declare function readMppSessionChannel(value: unknown): MppSessionChannel | null;
+/** Return the newest structurally valid channel currently held by a session. */
+declare function readCurrentMppSessionChannel(session: Pick<MppSessionFetch, "channels">): MppSessionChannel | null;
+/** Return a receipt only when it has the public success-receipt shape. */
+declare function readMppSessionReceipt(value: unknown): MppSessionReceipt | null;
+/** A post-send channel-open failure carries the channel that can be recovered. */
+declare function readMppRecoveryChannelId(error: unknown): string | null;
+
 /**
  * Solana session keys for the appkit shells (connect-lib STATE thread 18).
  *
@@ -1016,4 +1152,4 @@ declare function siwxResultToSession<M extends SiwxMessageLike>(result: SiwxResu
     refreshedAt: null;
 };
 
-export { type AddressValidationLevel, type AtomicSupport, type ChainCapabilities, type ChainInfo, type CompareCosts, type CompareCostsInput, type ConnectionStatus, type CostComparison, type CostComparisonOperation, type CostComparisonOptions, DEFAULT_NOTIFICATION_SETTINGS, type DecimalsCache, type DelegationFrameworkAdapterOptions, type DelegationPolicyDeps, type DelegationPolicyFlow, type DelegationPolicyPreview, type DelegationTypedData, type DestinationIssue, type DestinationValidation, type ExecutableQuote, type ExecuteRoute, type ExecuteRouteError, type ExecuteRouteOptions, type ExecuteRouteResult, type GetRouteQuotes, InvalidUserOperationReceiptError, NOTIFICATION_SETTINGS_KEY, type NotificationSettingsStorage, type PaymentFetch, type PaymentFetchResult, type PaymentRecord, type PolicyExecutionAdapter, type PolicyExecutionCheck, type PolicyExecutionPreview, type PolicyExecutionRoute, type PolicyExecutionSubmission, type PolicySignatureVerifier, type PreparedPolicyExecution, type RedemptionCodec, type RedemptionRpc, type RedemptionTransaction, type RetryOptions, type RouteQuote, type RouteQuoteInput, type RouteQuoteOptions, type SimulationCallClient, type SimulationTransaction, type SiwxLocation, type SiwxMessageLike, type SiwxResultLike, type SmartAccountOptionsLike, type SmartAccountType, type SolanaIdentity, type SolanaOwnerSigner, type SolanaPayer, type SolanaRoles, type SolanaRolesAbsence, type SolanaRolesSource, type SolanaRolesState, type SolanaSessionKeyFlow, type SolanaSessionKeyFlowDeps, type SolanaSigner, type SolanaWalletFeatures, type TokenIdentity, type TransactionSimulationContext, type ViemChainShape, type WalletChain, type Web3Action, type Web3State, __resetResolverForTests, addInAppNotification, assertHexSignature, atomicSupportFor, bareEvmAddress, buildDelegationPolicyMessage, buildSmartAccountConfig, chainNamespace, chainNumber, chainsForNamespace, channelsUpdate, clearOneInAppNotification, compareCostsKey, createDecimalsCache, createDelegationFrameworkAdapter, createDelegationPolicyFlow, createNotification, createNotificationSettingsStorage, createSolanaSessionKeyFlow, decodeRevertReason, defaultSiwxDomain, defaultSiwxUri, describeChain, describePayment, eip155ChainIdToNumber, encodeErc20Approve, encodeErc20Transfer, encodeErc20TransferFrom, fetchUserOperationReceipt, getResolver, getSharedSessionKeyManager, initialWeb3State, isBurnDestination, isEvmChainId, isPositiveIntegerAmount, isQuotableInput, isSiwxExpired, isSiwxNotBeforeValid, isVerifiablePolicy, loadNotificationSettings, mutedChainSettings, normalizeCapabilities, normalizeEip155ChainId, parseUserOperationReceipt, readDecimals, readSolanaRoles, resetSharedSessionKeyManager, resolveChain, resolveContextSimulationEndpoint, resolveEvmChainId, resolveRevertReason, resolveSimulationEndpoint, resolveUserOpChain, sameExecutionIntent, saveNotificationSettings, selectChainCapabilities, sessionKeyConfigFingerprint, simulateTransactionPreview, siwxResultToSession, toChainSwitchError, toEip155Accounts, toExecuteRouteError, toViemChain, tokenChainMismatch, tokenKey, updateNotificationSettings, validateDestination, validateRouteRecipient, web3Reducer, withRetry, withTimeout, writeDecimals };
+export { type AddressValidationLevel, type AssetId, type AtomicSupport, type AuthorizationAmountView, type AuthorizationAssetMetadata, type AuthorizationDescription, type AuthorizationExpiryView, type AuthorizationGrantView, type AuthorizationRecipientView, type ChainCapabilities, type ChainInfo, type CompareCosts, type CompareCostsInput, type ConnectionStatus, type CostComparison, type CostComparisonOperation, type CostComparisonOptions, DEFAULT_NOTIFICATION_SETTINGS, DEFAULT_VERIFY_RETRY, type DecimalsCache, type DelegationFrameworkAdapterOptions, type DelegationPolicyDeps, type DelegationPolicyFlow, type DelegationPolicyPreview, type DelegationTypedData, type DescribeAuthorizationOptions, type DestinationIssue, type DestinationValidation, type ExecutableQuote, type ExecuteRoute, type ExecuteRouteError, type ExecuteRouteOptions, type ExecuteRouteResult, type GetRouteQuotes, InvalidUserOperationReceiptError, type MppSessionChannel, type MppSessionFetch, type MppSessionFetchResult, type MppSessionForceCloseResult, type MppSessionMeter, type MppSessionReceipt, type MppSessionRequest, type MppSessionRequestInit, NOTIFICATION_SETTINGS_KEY, type NotificationSettingsStorage, type NotificationSettingsUpdate, type PaymentFetch, type PaymentFetchResult, type PaymentRecord, type PaymentVerification, type PaymentVerificationStatus, type PolicyExecutionAdapter, type PolicyExecutionCheck, type PolicyExecutionPreview, type PolicyExecutionRoute, type PolicyExecutionSubmission, type PolicySignatureVerifier, type PreparedPolicyExecution, type RedemptionCodec, type RedemptionRpc, type RedemptionTransaction, type RetryOptions, type RouteQuote, type RouteQuoteInput, type RouteQuoteOptions, type SimulationCallClient, type SimulationTransaction, type SiwxLocation, type SiwxMessageLike, type SiwxResultLike, type SmartAccountOptionsLike, type SmartAccountType, type SolanaIdentity, type SolanaOwnerSigner, type SolanaPayer, type SolanaRoles, type SolanaRolesAbsence, type SolanaRolesSource, type SolanaRolesState, type SolanaSessionKeyFlow, type SolanaSessionKeyFlowDeps, type SolanaSigner, type SolanaWalletFeatures, type SpendExplanation, type TokenIdentity, type TransactionSimulationContext, type VerifyRetryOptions, type ViemChainShape, type WalletChain, type Web3Action, type Web3State, __resetResolverForTests, addInAppNotification, applySettlementVerification, assertHexSignature, atomicSupportFor, bareEvmAddress, buildDelegationPolicyMessage, buildSmartAccountConfig, chainNamespace, chainNumber, chainsForNamespace, channelsUpdate, clearOneInAppNotification, compareCostsKey, createDecimalsCache, createDelegationFrameworkAdapter, createDelegationPolicyFlow, createNotification, createNotificationSettingsStorage, createSolanaSessionKeyFlow, decodeRevertReason, defaultSiwxDomain, defaultSiwxUri, describeAuthorization, describeChain, describePayment, eip155ChainIdToNumber, encodeErc20Approve, encodeErc20Transfer, encodeErc20TransferFrom, explainSpend, fetchUserOperationReceipt, formatAuthorizationAmount, getResolver, getSharedSessionKeyManager, initialWeb3State, isBurnDestination, isEvmChainId, isPositiveIntegerAmount, isQuotableInput, isSiwxExpired, isSiwxNotBeforeValid, isVerifiablePolicy, loadNotificationSettings, mutedChainSettings, normalizeCapabilities, normalizeEip155ChainId, parseUserOperationReceipt, readCurrentMppSessionChannel, readDecimals, readMppRecoveryChannelId, readMppSessionChannel, readMppSessionReceipt, readSolanaRoles, replayNotificationSettings, resetSharedSessionKeyManager, resolveChain, resolveContextSimulationEndpoint, resolveEvmChainId, resolveRevertReason, resolveSimulationEndpoint, resolveUserOpChain, sameExecutionIntent, saveNotificationSettings, selectChainCapabilities, sessionKeyConfigFingerprint, simulateTransactionPreview, siwxResultToSession, toChainSwitchError, toEip155Accounts, toExecuteRouteError, toViemChain, tokenChainMismatch, tokenKey, updateNotificationSettings, validateDestination, validateRouteRecipient, web3Reducer, withRetry, withTimeout, writeDecimals };