import { type MessagePartialSigner } from '@solana/kit'; import type { Challenge as MppxChallenge } from 'mppx'; import { Method, z } from 'mppx'; /** * Default voucher expiry timestamp, matching the Rust SDK and program tests. */ export declare const DEFAULT_SESSION_EXPIRES_AT = 4102444800; /** * Numeric input accepted by the session helpers. */ export type AmountLike = bigint | number | string; /** * Funding mode used to open a Solana payment session. */ export type SessionMode = 'pull' | 'push'; /** * Voucher authority used when a challenge advertises pull-mode sessions. * * `clientVoucher` does not require multi-delegate setup; `operatedVoucher` * is the operator-signed path that uses delegated token movement. */ export type SessionPullVoucherStrategy = 'clientVoucher' | 'operatedVoucher'; /** * Signer capable of Ed25519-signing exact voucher message bytes. */ export type SessionSigner = MessagePartialSigner; /** * Basis-point split distributed when a session settles. */ export interface SessionSplit { /** Share of the settled amount, in basis points (100 = 1%). */ readonly bps: number; /** Base58 address receiving this share. */ readonly recipient: string; } /** * Request embedded in a Solana `session` challenge. */ export interface SessionRequest extends Record { /** Maximum the session may spend, in base units. */ readonly cap: string; /** Currency identifier: a symbol like `'USDC'` or an SPL mint address. */ readonly currency: string; /** Token decimals (6 for the supported stablecoins). */ readonly decimals?: number | undefined; /** Human-readable description of what the session pays for. */ readonly description?: string | undefined; /** Merchant correlation id echoed in receipts. */ readonly externalId?: string | undefined; /** Smallest voucher increment the server accepts, in base units. */ readonly minVoucherDelta?: string | undefined; /** Funding modes the server supports. Omitted or empty means push only. */ readonly modes?: SessionMode[] | undefined; /** Solana network slug (`mainnet`, `devnet`, `localnet`). */ readonly network?: string | undefined; /** Operator public key vouchers are addressed to (base58). */ readonly operator: string; /** Payment-channels program id override (base58). */ readonly programId?: string | undefined; /** Voucher authority for pull-mode sessions. */ readonly pullVoucherStrategy?: SessionPullVoucherStrategy | undefined; /** Server-provided recent blockhash, saving the client an RPC round-trip. */ readonly recentBlockhash?: string | undefined; /** Server-provided current slot, used as the channel `openSlot` PDA seed (u64 as string). */ readonly recentSlot?: number | string | undefined; /** Primary recipient of the settled amount (base58). */ readonly recipient: string; /** Basis-point splits distributed at close. */ readonly splits?: SessionSplit[] | undefined; } /** * Parsed MPP challenge for the Solana session method. */ export type SessionChallenge = MppxChallenge.Challenge; /** * Voucher content signed by the client session key. */ export interface VoucherData { /** Channel / session id the voucher is bound to (base58). */ readonly channelId: string; /** Cumulative amount authorized so far, in base units. */ readonly cumulativeAmount: string; /** Unix timestamp (seconds) at which the voucher expires. */ readonly expiresAt: number; /** Optional client-side voucher counter. Not part of the signed bytes. */ readonly nonce?: number | undefined; } /** * Voucher-like input accepted by low-level serialization helpers. */ export interface VoucherDataInput { /** Channel / session id the voucher is bound to (base58). */ readonly channelId: string; /** Legacy wire alias for `cumulativeAmount`. */ readonly cumulative?: AmountLike | undefined; /** Cumulative amount authorized so far, in base units. */ readonly cumulativeAmount?: AmountLike | undefined; /** Unix timestamp (seconds) at which the voucher expires. */ readonly expiresAt: AmountLike; /** Optional client-side voucher counter. Not part of the signed bytes. */ readonly nonce?: number | undefined; } /** * Signed cumulative voucher. */ export interface SignedVoucher { /** The signed voucher fields. */ readonly data: VoucherData; /** Base58 Ed25519 signature over the canonical voucher bytes. */ readonly signature: string; } /** * Open action payload for payment channels or delegated-token pull sessions. */ export interface OpenPayload { /** Pull mode: delegated amount approved by the wallet, in base units. */ readonly approvedAmount?: string | undefined; /** Public key authorized to sign vouchers for this session (base58). */ readonly authorizedSigner: string; /** Channel address (push) or delegated token account (pull), base58. */ readonly channelId?: string | undefined; /** Push mode: deposit locked in the payment channel, in base units. */ readonly deposit?: string | undefined; /** Push mode: close grace period in seconds. */ readonly gracePeriod?: number | undefined; /** Pull mode: pre-signed multi-delegate init transaction (base64), when the PDA may not exist yet. */ readonly initMultiDelegateTx?: string | undefined; /** SPL mint of the funding asset (base58). */ readonly mint?: string | undefined; /** Funding mode this open uses. */ readonly mode: SessionMode; /** Pull mode: wallet that owns the delegated token account (base58). */ readonly owner?: string | undefined; /** Push mode: channel payee (base58). */ readonly payee?: string | undefined; /** Push mode: channel payer (base58). */ readonly payer?: string | undefined; /** Push mode: slot the open was built against (decimal string); the channel `openSlot` PDA seed. */ readonly recentSlot?: number | string | undefined; /** Push mode: channel-derivation salt (decimal string). */ readonly salt?: string | undefined; /** Open transaction signature, or {@link PENDING_SERVER_SIGNATURE} when the server broadcasts. */ readonly signature: string; /** Pull mode: delegated token account vouchers draw from (base58). */ readonly tokenAccount?: string | undefined; /** Push mode: base64 signed open transaction for server-side submission. */ readonly transaction?: string | undefined; /** Pull mode: pre-signed delegation update transaction (base64). */ readonly updateDelegationTx?: string | undefined; } /** * Client action sent as a Solana session credential payload. */ export type SessionAction = { readonly action: 'close'; readonly channelId: string; readonly voucher?: SignedVoucher | undefined; } | { readonly action: 'commit'; readonly deliveryId: string; readonly voucher: SignedVoucher; } | { readonly action: 'topUp'; readonly channelId: string; readonly newDeposit: string; readonly signature: string; } | { readonly action: 'voucher'; readonly voucher: SignedVoucher; } | (OpenPayload & { readonly action: 'open'; }); /** * Payload body posted to a commit endpoint by the consumer helpers. */ export interface CommitPayload { /** Delivery being committed. */ readonly deliveryId: string; /** Signed cumulative voucher covering the delivery. */ readonly voucher: SignedVoucher; } /** * Server-issued metering directive attached to a delivered message. */ export interface MeteringDirective { /** Price of this delivery, in base units. */ readonly amount: string; /** Endpoint the commit should be POSTed to. Falls back to the transport default. */ readonly commitUrl?: string | undefined; /** Currency identifier the amount is denominated in. */ readonly currency: string; /** Unique id of the reserved delivery. */ readonly deliveryId: string; /** Unix timestamp (seconds) after which the reservation lapses. */ readonly expiresAt: number; /** Opaque server token echoed back on commit. Clients must not modify it. */ readonly proof?: string | undefined; /** Server-side delivery sequence number, monotonic per session. */ readonly sequence: number; /** Session / channel the delivery is billed against. */ readonly sessionId: string; } /** * Final usage for a metered stream. */ export interface MeteringUsage { /** Total metered amount, in base units. */ readonly amount: string; /** Delivery the usage belongs to. */ readonly deliveryId: string; } /** * Payload paired with the directive needed to acknowledge it. */ export interface MeteredEnvelope { /** Directive to commit once the payload is processed. */ readonly metering: MeteringDirective; /** The delivered application payload. */ readonly payload: Payload; } /** * Commit status returned by the server. */ export type CommitStatus = 'committed' | 'replayed'; /** * Receipt returned after a commit is accepted. */ export interface CommitReceipt { /** Amount this commit added, in base units. */ readonly amount: string; /** Session cumulative after the commit, in base units. */ readonly cumulative: string; /** Delivery the commit settled. */ readonly deliveryId: string; /** Session / channel the commit was applied to. */ readonly sessionId: string; /** `committed` on first acceptance, `replayed` on idempotent retries. */ readonly status: CommitStatus; } /** * Context accepted by the `session()` MPP client method. */ export interface SessionContext { /** Session action to perform. Defaults to `open` until a session is active, then `voucher`. */ readonly action?: 'close' | 'commit' | 'open' | 'topUp' | 'voucher' | undefined; /** Incremental amount for `voucher` / `commit`, in base units. */ readonly amount?: AmountLike | undefined; /** Pull opens: delegated amount approved by the wallet, in base units. */ readonly approvedAmount?: AmountLike | undefined; /** Absolute cumulative amount for `voucher`, in base units. */ readonly cumulativeAmount?: AmountLike | undefined; /** Delivery to commit. Defaults to `directive.deliveryId`. */ readonly deliveryId?: string | undefined; /** Push opens: channel deposit, in base units. Defaults to the challenge cap. */ readonly deposit?: AmountLike | undefined; /** Metering directive being committed. */ readonly directive?: MeteringDirective | undefined; /** Close: last unsettled increment to sign into the closing voucher, in base units. */ readonly finalIncrement?: AmountLike | undefined; /** Push opens: channel close grace period in seconds. */ readonly gracePeriod?: number | undefined; /** Pull opens: pre-signed multi-delegate init transaction (base64). */ readonly initMultiDelegateTx?: string | undefined; /** Push opens: SPL mint of the deposit (base58). */ readonly mint?: string | undefined; /** Funding mode for `open`. Defaults to the first server-advertised mode. */ readonly mode?: SessionMode | undefined; /** TopUp: new total deposit, in base units. */ readonly newDeposit?: AmountLike | undefined; /** Push opens: slot the open is built against (a channel PDA seed). Defaults to the challenge `recentSlot`. */ readonly openSlot?: AmountLike | undefined; /** Pull opens: wallet that owns the delegated token account (base58). */ readonly owner?: string | undefined; /** Push opens: channel payee (base58). */ readonly payee?: string | undefined; /** Push opens: channel payer (base58). */ readonly payer?: string | undefined; /** Push opens: channel-derivation salt. */ readonly salt?: AmountLike | undefined; /** Active session to act on, overriding the method-level session. */ readonly session?: ActiveSession | undefined; /** Open / topUp transaction signature (base58). */ readonly signature?: string | undefined; /** Optional client identifier serialized into the credential. */ readonly source?: string | undefined; /** Pull opens: delegated token account vouchers draw from (base58). */ readonly tokenAccount?: string | undefined; /** Push opens: base64 signed open transaction for server-side submission. */ readonly transaction?: string | undefined; /** Pull opens: pre-signed delegation update transaction (base64). */ readonly updateDelegationTx?: string | undefined; /** Pre-signed voucher for `voucher` / `close`, bypassing local signing. */ readonly voucher?: SignedVoucher | undefined; } /** * Runtime context schema for mppx routing. Detailed validation happens in the SDK helper. */ export declare const sessionContextSchema: z.ZodMiniCustom; /** * Returns the funding modes advertised by a session request; an omitted or * empty `modes` list means the server only supports push. */ export declare function sessionRequestModes(request: Pick): readonly SessionMode[]; /** * Builds canonical payment-channel voucher bytes: * `magic (0x56, 0x01) || channel_id || cumulative_amount_le_u64 || expires_at_le_i64`. * * Delegates to the shared encoder so client and server agree on the bytes * they sign / verify. */ export declare function voucherMessageBytes(data: VoucherDataInput): Uint8Array; /** * Serializes a Solana session action as an MPP `Authorization` header value. */ export declare function serializeSessionCredential(parameters: serializeSessionCredential.Parameters): string; export declare namespace serializeSessionCredential { interface Parameters { /** Challenge the credential answers (echoed for stateless verification). */ readonly challenge: SessionChallenge; /** Session action to authorize. */ readonly payload: SessionAction; /** Optional client identifier serialized into the credential. */ readonly source?: string | undefined; } } /** * Tracks local voucher state for an open Solana payment session. */ export declare class ActiveSession { #private; constructor(channelId: string, signer: SessionSigner, options?: ActiveSession.Options); constructor(parameters: ActiveSession.Parameters); /** Channel/session identifier used by all vouchers. */ get channelId(): string; /** Current local cumulative watermark. */ get cumulative(): bigint; /** Current local cumulative watermark as a decimal string. */ get cumulativeAmount(): string; /** Expiry timestamp used for newly signed vouchers. */ get expiresAt(): number; /** Current local voucher nonce. */ get nonce(): number; /** Session key authorized to sign vouchers. */ get signer(): SessionSigner; /** Public key authorized to sign vouchers. */ get authorizedSigner(): string; /** Updates the expiry timestamp used for subsequent vouchers. */ setExpiresAt(expiresAt: AmountLike): void; /** * Signs an absolute cumulative voucher without advancing local state. */ prepareVoucher(cumulative: AmountLike): Promise; /** * Signs an increment from the current watermark without advancing local state. */ prepareIncrement(amount: AmountLike): Promise; /** * Records a prepared voucher as accepted by the server. */ recordVoucher(voucher: SignedVoucher): void; /** * Signs an absolute cumulative voucher and advances local state. */ signVoucher(cumulative: AmountLike): Promise; /** * Signs an increment from the current watermark and advances local state. */ signIncrement(amount: AmountLike): Promise; /** * Builds a `voucher` action for a freshly signed increment. */ voucherAction(amount: AmountLike): Promise; /** * Builds a `commit` action for a delivery and freshly signed increment. */ commitAction(delivery: MeteringDirective | string, amount?: AmountLike): Promise; /** * Builds a payment-channel `open` action. */ openAction(deposit: AmountLike, signature: string, options?: ActiveSession.OpenOptions): OpenPayload & { readonly action: 'open'; }; /** * Builds a detailed payment-channel `open` action. */ openPaymentChannelAction(parameters: ActiveSession.PaymentChannelOpenParameters): OpenPayload & { readonly action: 'open'; }; /** * Builds a pull-mode `open` action after delegation is confirmed. */ openPullAction(parameters: ActiveSession.PullOpenParameters): OpenPayload & { readonly action: 'open'; }; /** * Builds a `topUp` action after the top-up transaction is confirmed. */ topUpAction(newDeposit: AmountLike, signature: string): SessionAction; /** * Builds a cooperative `close` action, optionally signing a final increment. */ closeAction(finalIncrement?: AmountLike): Promise; } export declare namespace ActiveSession { interface Options { /** Cumulative already authorized when resuming a session, in base units. Defaults to 0. */ readonly cumulative?: AmountLike | undefined; /** Voucher expiry as a unix timestamp (seconds). Defaults to {@link DEFAULT_SESSION_EXPIRES_AT}. */ readonly expiresAt?: AmountLike | undefined; /** Starting voucher counter when resuming a session. */ readonly nonce?: AmountLike | undefined; } interface Parameters extends Options { /** Channel address (push) or delegated token account (pull), base58. */ readonly channelId: string; /** Key that signs vouchers for this session. */ readonly signer: SessionSigner; } interface OpenOptions { /** Funding mode. Defaults to `push`. */ readonly mode?: SessionMode | undefined; /** Base64 signed open transaction for server-side submission. */ readonly transaction?: string | undefined; } interface PaymentChannelOpenParameters extends OpenOptions { /** Deposit locked in the channel, in base units. */ readonly deposit: AmountLike; /** Close grace period in seconds. */ readonly gracePeriod: number; /** SPL mint of the deposit (base58). */ readonly mint: string; /** Slot the open transaction was built against (a channel PDA seed). */ readonly openSlot: AmountLike; /** Channel payee (base58). */ readonly payee: string; /** Channel payer (base58). */ readonly payer: string; /** Channel-derivation salt. */ readonly salt: AmountLike; /** Open transaction signature (base58). */ readonly signature: string; } interface PullOpenParameters { /** Delegated amount approved by the wallet, in base units. */ readonly approvedAmount: AmountLike; /** Pre-signed multi-delegate init transaction (base64), when the PDA may not exist yet. */ readonly initMultiDelegateTx?: string | undefined; /** Wallet that owns the delegated token account (base58). */ readonly owner: string; /** Delegation transaction signature, or {@link PENDING_SERVER_SIGNATURE}. */ readonly signature: string; /** Delegated token account vouchers draw from (base58). Defaults to the derived account. */ readonly tokenAccount?: string | undefined; /** Pre-signed delegation update transaction (base64). */ readonly updateDelegationTx?: string | undefined; } } /** * Creates the Solana `session` MPP client method. */ export declare function session(parameters?: session.Parameters): Method.Client<{ readonly intent: "session"; readonly name: "solana"; readonly schema: { readonly credential: { readonly payload: z.ZodMiniDiscriminatedUnion<[z.ZodMiniObject<{ action: z.ZodMiniLiteral<"open">; approvedAmount: z.ZodMiniOptional>; authorizedSigner: z.ZodMiniString; channelId: z.ZodMiniOptional>; deposit: z.ZodMiniOptional>; gracePeriod: z.ZodMiniOptional>; initMultiDelegateTx: z.ZodMiniOptional>; mint: z.ZodMiniOptional>; mode: z.ZodMiniEnum<{ push: "push"; pull: "pull"; }>; owner: z.ZodMiniOptional>; payee: z.ZodMiniOptional>; payer: z.ZodMiniOptional>; recentSlot: z.ZodMiniOptional, z.ZodMiniNumber]>>; salt: z.ZodMiniOptional, z.ZodMiniNumber]>>; signature: z.ZodMiniString; tokenAccount: z.ZodMiniOptional>; transaction: z.ZodMiniOptional>; updateDelegationTx: z.ZodMiniOptional>; }, z.core.$strip>, z.ZodMiniObject<{ action: z.ZodMiniLiteral<"voucher">; voucher: z.ZodMiniObject<{ data: z.ZodMiniObject<{ channelId: z.ZodMiniString; cumulative: z.ZodMiniOptional>; cumulativeAmount: z.ZodMiniOptional>; expiresAt: z.ZodMiniNumber; nonce: z.ZodMiniOptional>; }, z.core.$strip>; signature: z.ZodMiniString; }, z.core.$strip>; }, z.core.$strip>, z.ZodMiniObject<{ action: z.ZodMiniLiteral<"commit">; deliveryId: z.ZodMiniString; voucher: z.ZodMiniObject<{ data: z.ZodMiniObject<{ channelId: z.ZodMiniString; cumulative: z.ZodMiniOptional>; cumulativeAmount: z.ZodMiniOptional>; expiresAt: z.ZodMiniNumber; nonce: z.ZodMiniOptional>; }, z.core.$strip>; signature: z.ZodMiniString; }, z.core.$strip>; }, z.core.$strip>, z.ZodMiniObject<{ action: z.ZodMiniLiteral<"topUp">; channelId: z.ZodMiniString; newDeposit: z.ZodMiniString; signature: z.ZodMiniString; }, z.core.$strip>, z.ZodMiniObject<{ action: z.ZodMiniLiteral<"close">; channelId: z.ZodMiniString; voucher: z.ZodMiniOptional; cumulative: z.ZodMiniOptional>; cumulativeAmount: z.ZodMiniOptional>; expiresAt: z.ZodMiniNumber; nonce: z.ZodMiniOptional>; }, z.core.$strip>; signature: z.ZodMiniString; }, z.core.$strip>>; }, z.core.$strip>], "action">; }; readonly request: z.ZodMiniObject<{ cap: z.ZodMiniString; currency: z.ZodMiniString; decimals: z.ZodMiniOptional>; description: z.ZodMiniOptional>; externalId: z.ZodMiniOptional>; minVoucherDelta: z.ZodMiniOptional>; modes: z.ZodMiniOptional>>; network: z.ZodMiniOptional>; operator: z.ZodMiniString; programId: z.ZodMiniOptional>; pullVoucherStrategy: z.ZodMiniOptional>; recentBlockhash: z.ZodMiniOptional>; recentSlot: z.ZodMiniOptional, z.ZodMiniNumber]>>; recipient: z.ZodMiniString; splits: z.ZodMiniOptional; recipient: z.ZodMiniString; }, z.core.$strip>>>; }, z.core.$strip>; }; }, z.ZodMiniCustom>; export declare namespace session { interface CreateActionParameters { /** Challenge being answered. */ readonly challenge: SessionChallenge; /** Per-request context passed to the method handler. */ readonly context?: SessionContext | undefined; /** Active session, when one has already been opened. */ readonly session?: ActiveSession | undefined; } interface Parameters { /** Channel id to resume. Requires `signer`; ignored when `session` is given. */ readonly channelId?: string | undefined; /** Override that builds the session action for each challenge (custom wallet flows). */ readonly createAction?: ((parameters: CreateActionParameters) => Promise | SessionAction) | undefined; /** Voucher expiry for a resumed session, unix seconds. */ readonly expiresAt?: AmountLike | undefined; /** Existing session to drive instead of creating one. */ readonly session?: ActiveSession | undefined; /** Voucher signer for a resumed session. */ readonly signer?: SessionSigner | undefined; /** Optional client identifier serialized into credentials. */ readonly source?: string | undefined; } } //# sourceMappingURL=Session.d.ts.map