/** * Where px402 runs: one preset per network, under the name x402 gives it, so * the drop-in surface (`dropin.ts`) needs no chain constants and no service * URLs. The default is Base (`"base"`, chain 8453). * * # What a preset carries * * The chain id, the USDC the reserve takes deposits in (on Base, Circle's * native USDC), a public JSON-RPC endpoint, PRXVT's hosted services, and the * reserve: its address, its `DOMAIN_SEPARATOR()` and the block it was * deployed in, copied from the deployment record the deploy writes. * * # Which network * * The `network` option, else the `PX402_NETWORK` environment variable (a * preset's name, `base`, or its CAIP-2 id, `eip155:8453`), else * {@link DEFAULT_NETWORK}. A deployment of your own is passed as a full * {@link Network} object. * * # The service URLs are resolved, never assumed * * A wallet needs an issuer and a registry, and a bridge facilitator to pay a * merchant that quotes only `exact`. Each is taken from, in order: * * 1. the caller's option (`issuerUrl`, `registryUrl`, `bridgeFacilitator`), * 2. the environment, under the names the examples already read * (`PX402_ISSUER_URL`, `PX402_REGISTRY_URL`, `PX402_BRIDGE_FACILITATOR`), * 3. the preset. * * Base's preset names PRXVT's hosted services, in one marked place * ({@link HOSTED_SERVICES}): `issuer.prxvt.com`, `registry.prxvt.com`, and * `facilitator.prxvt.com` as the bridge facilitator. They are the last * fallback, so an option or a variable always points a wallet elsewhere (your * own services, or a proxy in front of these). A network object of your own * carries its services in `services`; one that names no issuer or registry, * with nothing in the options or the environment either, is * {@link PX402MissingSettingError}, naming the option and the variable that * supply it. A bridge facilitator that resolves from none only leaves the * bridge off: a merchant that quotes only `exact` then gets its 402 back * unpaid, as with `wrapFetch` and no `bridge`. * * A preset's issuer is checked like any other: `px402.recover` refuses one * whose keyset the preset's reserve did not commit on chain (spec §4), so a * hostname that stopped being this deployment's cannot hand a wallet keys. * * The chain's RPC endpoint resolves the same way (`rpcUrl`, `PX402_RPC_URL`, * the preset's public endpoint), and is the one value every preset fills. A * preset may name a second public endpoint for the wallet's own transactions * (`txRpcUrl`: Base's reads go through publicnode, which serves no receipts, * and its deposits through `mainnet.base.org`); an endpoint the caller names * serves both. */ import { PX402ConfigError, type ChainConfig } from "./wallet.js"; /** The names x402 gives the networks px402 has presets for. */ export type NetworkName = "base" | "base-sepolia"; /** The px402 services a network's wallets use. Any of them may be unset. */ export interface NetworkServices { /** The issuer: `/keys`, `/withdraw`, the melt routes, `/log`. */ readonly issuerUrl?: string | undefined; /** The registry: `/melt-attempt` and `/spent`. */ readonly registryUrl?: string | undefined; /** A bridge facilitator, for merchants that quote only `exact` (v3 §26). */ readonly bridgeFacilitator?: string | undefined; } /** * A deployed px402 network: the chain, the reserve on it, and where its * services are. A preset is one of these; a deployment of your own is passed * as one. */ export interface Network { /** What errors and warnings call it, e.g. `"base"`. */ readonly name: string; /** EIP-155 chain id. */ readonly chainId: number; /** The `PX402Reserve` address, `0x`-prefixed. */ readonly reserveContract: string; /** The USDC the reserve takes deposits in, `0x`-prefixed. */ readonly usdc: string; /** The reserve's `DOMAIN_SEPARATOR()`, `0x`-prefixed 32-byte hex, as the deployment record writes it. */ readonly domainSeparator: string; /** The reserve's deployment block: where a recovery's log scan starts. */ readonly deployBlock: bigint; /** A public JSON-RPC endpoint for the chain. `rpcUrl` and `PX402_RPC_URL` override it. */ readonly rpcUrl: string; /** * A public JSON-RPC endpoint for the wallet's own transactions: the drop-in * sends its deposits through it and makes there every read that follows * them (nonce, fees, receipts, balances at the block it saw). Defaults to * {@link rpcUrl}. `rpcUrl` and `PX402_RPC_URL` override both: one endpoint * of your own serves everything. */ readonly txRpcUrl?: string; /** Blocks per `eth_getLogs` that endpoint serves. */ readonly logBlockRange?: bigint; readonly services?: NetworkServices; /** * The `PX402GaslessDepositor` beside the reserve, `0x`-prefixed: what a * wallet with USDC and no ETH signs its deposit authorization for * (`gasless.ts`). `gaslessDepositor` and `PX402_GASLESS_DEPOSITOR` * override it. */ readonly gaslessDepositor?: string | undefined; } /** * A network whose reserve is not configured: what a preset knows of the * chain, and no reserve a wallet could deposit into or pay from. Resolving * one is {@link PX402NetworkNotDeployedError}. */ export interface UndeployedNetwork { readonly name: string; readonly chainId: number; readonly deployed: false; /** The USDC the reserve will take deposits in, `0x`-prefixed. */ readonly usdc?: string; /** A public JSON-RPC endpoint for the chain. */ readonly rpcUrl?: string; /** A public JSON-RPC endpoint for the wallet's own transactions. */ readonly txRpcUrl?: string; /** Blocks per `eth_getLogs` that endpoint serves. */ readonly logBlockRange?: bigint; readonly services?: NetworkServices; } /** * A reserve, as its deployment record writes it. Every field is `undefined` * until the deploy fills it. */ export interface ReserveDeployment { /** The `PX402Reserve` address, `0x`-prefixed. */ readonly reserveContract: string | undefined; /** Its `DOMAIN_SEPARATOR()`, `0x`-prefixed 32-byte hex. */ readonly domainSeparator: string | undefined; /** The block it was deployed in. */ readonly deployBlock: bigint | undefined; } export declare const BASE_MAINNET_RESERVE: ReserveDeployment; export declare const BASE_MAINNET_GASLESS_DEPOSITOR: string | undefined; /** A preset's chain and services, with the reserve when all three of its values are set. */ export declare function presetWithReserve(chain: Omit, reserve: ReserveDeployment): Network | UndeployedNetwork; /** Every preset, by name. Pass a name to the drop-in surface, or a {@link Network} of your own. */ export declare const networks: { readonly base: Network | UndeployedNetwork; readonly "base-sepolia": Network; }; /** The network a wallet is on when neither the `network` option nor `PX402_NETWORK` names one: Base. */ export declare const DEFAULT_NETWORK: NetworkName; /** The environment variable that names the network when the `network` option does not. */ export declare const NETWORK_ENV_VAR = "PX402_NETWORK"; /** The environment variables the resolution reads: the names the examples already use. */ export declare const ENV_VARS: { readonly issuerUrl: "PX402_ISSUER_URL"; readonly registryUrl: "PX402_REGISTRY_URL"; readonly bridgeFacilitator: "PX402_BRIDGE_FACILITATOR"; readonly rpcUrl: "PX402_RPC_URL"; }; /** A value {@link resolveServices} resolves. */ export type NetworkSetting = keyof typeof ENV_VARS; /** * A value the wallet needs resolved from none of the places it is looked for. * The message names the option and the environment variable that supply it. */ export declare class PX402MissingSettingError extends PX402ConfigError { /** The option that supplies it, e.g. `issuerUrl`. */ readonly setting: NetworkSetting; /** The environment variable that supplies it, e.g. `PX402_ISSUER_URL`. */ readonly envVar: string; /** The network it was resolved for. */ readonly network: string; constructor(setting: NetworkSetting, network: string); } /** A network whose reserve is not configured: there is nothing to deposit into or pay from. */ export declare class PX402NetworkNotDeployedError extends PX402ConfigError { readonly network: string; readonly chainId: number; constructor(network: UndeployedNetwork); } /** * The network the `network` option names, else the one `PX402_NETWORK` * names; `undefined` when neither names one. * * @throws PX402NetworkNotDeployedError for a network whose reserve is not configured. * @throws PX402ConfigError for a name that is not a preset. */ export declare function namedNetwork(network?: NetworkName | Network | UndeployedNetwork, env?: Readonly>): Network | undefined; /** * The network a wallet runs on: the `network` option, else the preset * `PX402_NETWORK` names (read from `env`, `process.env` by default), else * {@link DEFAULT_NETWORK}. * * @throws PX402NetworkNotDeployedError for a network whose reserve is not configured. * @throws PX402ConfigError for a name that is not a preset. */ export declare function resolveNetwork(network?: NetworkName | Network | UndeployedNetwork, env?: Readonly>): Network; /** The preset for a chain id, when there is one with a reserve. */ export declare function networkForChain(chainId: number): Network | undefined; /** The environment variables gasless deposits are configured by (`gasless.ts`). */ export declare const GASLESS_ENV_VARS: { readonly gaslessDepositor: "PX402_GASLESS_DEPOSITOR"; readonly sponsorFacilitator: "PX402_SPONSOR_FACILITATOR"; }; /** Where a wallet on a network deposits gaslessly, resolved. */ export interface ResolvedGasless { /** The `PX402GaslessDepositor`, lowercase; `undefined` when none resolves (gasless deposits are off). */ readonly depositor: string | undefined; /** The facilitator whose `/deposit/sponsor` takes the authorization. */ readonly facilitator: string | undefined; } /** * The gasless depositor and the facilitator, in the order the module docs * give for every setting: the option, the environment variable * (`PX402_GASLESS_DEPOSITOR`, `PX402_SPONSOR_FACILITATOR`), the preset. The * facilitator falls back to the bridge facilitator: on Base both are * `facilitator.prxvt.com`. * * @throws PX402ConfigError for a depositor that is not a 20-byte address. */ export declare function resolveGasless(network: Network, bridgeFacilitator: string | undefined, overrides?: { readonly gaslessDepositor?: string; readonly sponsorFacilitator?: string; readonly env?: Readonly>; }): ResolvedGasless; /** What {@link resolveServices} reads before the preset. */ export interface ServiceOverrides { readonly issuerUrl?: string; readonly registryUrl?: string; readonly bridgeFacilitator?: string; readonly rpcUrl?: string; /** * Where the environment variables are read from. Defaults to * `process.env` where there is one (Node), and to nothing elsewhere. */ readonly env?: Readonly>; } /** Every service a wallet on a network uses, resolved. */ export interface ResolvedServices { readonly issuerUrl: string; readonly registryUrl: string; /** `undefined` when no bridge facilitator resolved: the bridge stays off. */ readonly bridgeFacilitator: string | undefined; /** Where the wallet reads the chain: recovery, the keyset commitment. */ readonly rpcUrl: string; /** * Where the drop-in sends its own transactions and reads what follows them: * the `rpcUrl` option or `PX402_RPC_URL` when either is set (one endpoint * of your own serves both), else the network's `txRpcUrl`, else its * `rpcUrl`. */ readonly txRpcUrl: string; } /** `process.env` where the runtime has one; an empty record elsewhere. */ export declare function processEnv(): Readonly>; /** * One value, in the order the module docs give: the option, the environment * variable, the preset (none when `network` is `undefined`). An empty string * counts as unset at every step. */ export declare function resolveSetting(setting: NetworkSetting, network: Network | undefined, overrides?: ServiceOverrides): string | undefined; /** * The issuer, the registry, the bridge facilitator and the RPC endpoint a * wallet on `network` uses. * * @throws PX402MissingSettingError for an issuer or registry (or, for a * network object without one, an RPC endpoint) that resolves from nothing. */ export declare function resolveServices(network: Network, overrides?: ServiceOverrides): ResolvedServices; /** * The {@link ChainConfig} a wallet on `network` is opened with: the reserve, * its domain separator as bytes, the RPC endpoint every chain read goes * through, and the deployment block recovery scans from. */ export declare function chainConfigOf(network: Network, rpcUrl: string, rpcFetch?: ChainConfig["rpcFetch"]): ChainConfig; /** What {@link chainConfig} reads besides the network. */ export interface ChainConfigOptions { /** The chain's JSON-RPC endpoint. Else `PX402_RPC_URL`, else the preset's public one. */ readonly rpcUrl?: string; /** The `fetch` the JSON-RPC calls go through. Defaults to the global `fetch`. */ readonly rpcFetch?: ChainConfig["rpcFetch"]; /** Where `PX402_NETWORK` and `PX402_RPC_URL` are read. Defaults to `process.env`. */ readonly env?: Readonly>; } /** * The `chain` the explicit path opens a wallet with, from a preset or a * network object of your own, in one call: * * ```ts * const wallet = await px402.recover({ seed, issuer, chain: chainConfig() }); * ``` * * The network resolves as {@link resolveNetwork} resolves it (the argument, * else `PX402_NETWORK`, else Base), and the RPC endpoint as the services do * (`options.rpcUrl`, else `PX402_RPC_URL`, else the preset's). The domain * separator comes back as the bytes `chain` takes. * * @throws PX402NetworkNotDeployedError for a network whose reserve is not configured. * @throws PX402ConfigError for a name that is not a preset, or a domain separator that is not 32 bytes. */ export declare function chainConfig(network?: NetworkName | Network | UndeployedNetwork, options?: ChainConfigOptions): ChainConfig;