@opaquecash/stellar 0.1.0

package/dist/index-Dqr8RiOd.d.ts

@@ -0,0 +1,520 @@
+import { Keypair, xdr, rpc, Horizon } from '@stellar/stellar-sdk';
+import { h as hashFields, P as PoolNote } from './notes-CTR_oi8Y.js';
+
+/**
+ * Stellar network presets: passphrase and default RPC / Horizon endpoints per
+ * network. Mainnet ships with no default endpoints — callers must supply
+ * production providers explicitly.
+ */
+type OpaqueNetwork = "testnet" | "mainnet" | "futurenet" | "local";
+interface NetworkPreset {
+    passphrase: string;
+    rpcUrls: string[];
+    horizonUrls: string[];
+}
+declare const NETWORK_PRESETS: Record<OpaqueNetwork, NetworkPreset>;
+
+/**
+ * Per-network on-chain address book.
+ *
+ * These constants mirror `deployments/v1/<network>.json` in the repo and are the
+ * SDK's baked-in defaults. They are intended to be regenerated by a codegen step
+ * in CI so a redeploy updates the SDK with a single command. Callers may override
+ * any address through {@link OpaqueConfig}.
+ */
+
+interface ContractAddresses {
+    stealthRegistry: string;
+    stealthAnnouncer: string;
+    groth16Verifier: string;
+    reputationVerifier: string;
+    schemaRegistry: string;
+    attestationEngineV2: string;
+    poolVerifier: string;
+    privacyPool: string;
+    relayerRegistry: string;
+}
+interface PoolWiring {
+    /** Domain separator bound into pool commitments. */
+    scope: number;
+    /** Native XLM Stellar Asset Contract id backing the pool. */
+    nativeSac: string;
+}
+interface RelayerWiring {
+    minimumStake: bigint;
+    unstakeCooldownLedgers: number;
+    maxDeadlineLedgers: number;
+    gatewayUrls: string[];
+}
+interface NetworkDeployment {
+    contracts: ContractAddresses;
+    pool: PoolWiring;
+    relayer: RelayerWiring;
+    /** Ledger the contracts were deployed at; event scans start here. */
+    deploymentLedger: number;
+}
+/** Generated from deployments/v1/testnet.json. */
+declare const TESTNET_DEPLOYMENT: NetworkDeployment;
+/** Known deployments by network. Testnet is the only live deployment today. */
+declare const DEPLOYMENTS: Partial<Record<OpaqueNetwork, NetworkDeployment>>;
+
+interface OpaqueConfig {
+    /** Target Stellar network. */
+    network: OpaqueNetwork;
+    /** Override Soroban RPC endpoints (defaults to the network preset). */
+    rpcUrls?: string[];
+    /** Override Horizon endpoints (defaults to the network preset). */
+    horizonUrls?: string[];
+    /** Override individual contract addresses (defaults to the baked deployment). */
+    contracts?: Partial<ContractAddresses>;
+    /** Override relayer-market gateway endpoints. */
+    relayerGatewayUrls?: string[];
+    /** Base URL of a reputation-root publisher service, if used. */
+    reputationPublisherUrl?: string;
+    /** Override the ledger event scans start from (defaults to deployment ledger). */
+    startLedger?: number;
+}
+interface ResolvedConfig {
+    network: OpaqueNetwork;
+    passphrase: string;
+    rpcUrls: string[];
+    horizonUrls: string[];
+    contracts: ContractAddresses;
+    pool: PoolWiring;
+    relayer: RelayerWiring;
+    relayerGatewayUrls: string[];
+    reputationPublisherUrl?: string;
+    startLedger: number;
+}
+/**
+ * Resolve user config into a complete, validated configuration: network preset +
+ * baked deployment + explicit overrides. Throws {@link ConfigError} when a
+ * required endpoint or contract address is missing (e.g. mainnet usage).
+ */
+declare function resolveConfig(config: OpaqueConfig): ResolvedConfig;
+
+/**
+ * Signer abstraction. The SDK never holds or asks for a private key directly: it
+ * hands a transaction XDR to an {@link OpaqueSigner} and gets a signed XDR back.
+ * This unifies browser wallets (Freighter), raw server keypairs, and any custom
+ * signing backend behind one interface.
+ */
+
+interface SignerContext {
+    /** Network passphrase the transaction is bound to. */
+    networkPassphrase: string;
+}
+/** Low-level callback form: sign a transaction XDR, return the signed XDR. */
+type SignTxFn = (xdr: string) => Promise<string>;
+interface OpaqueSigner {
+    /** Stellar public key (G-address) this signer controls. */
+    publicKey(): string | Promise<string>;
+    /** Sign a base64 transaction XDR and return the signed base64 XDR. */
+    signTransaction(xdr: string, ctx: SignerContext): Promise<string>;
+    /** Optional: sign an arbitrary message (used for one-time key derivation). */
+    signMessage?(message: string): Promise<string>;
+}
+/**
+ * Build a signer from a raw Ed25519 keypair (server / non-browser use). Accepts a
+ * Stellar secret seed (`S...`) or a `Keypair` instance.
+ */
+declare function keypairSigner(secretOrKeypair: string | Keypair): OpaqueSigner;
+/**
+ * Build a signer from caller-supplied callbacks. Use this to adapt Freighter or
+ * any external signing service.
+ */
+declare function callbackSigner(opts: {
+    publicKey: string | (() => string | Promise<string>);
+    signTransaction: SignTxFn;
+    signMessage?: (message: string) => Promise<string>;
+}): OpaqueSigner;
+
+/**
+ * Pluggable logger. The SDK logs nothing by default (no `console.log` noise in a
+ * library); a host app can pass {@link consoleLogger} or its own implementation.
+ */
+interface Logger {
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+/** Default logger: discards everything. */
+declare const silentLogger: Logger;
+/** Logger that forwards to the global `console`. */
+declare const consoleLogger: Logger;
+
+/**
+ * Pluggable telemetry hooks. The SDK emits structured events at meaningful
+ * points (contract calls, scans) so a host app can wire its own metrics without
+ * the SDK depending on any monitoring library. All hooks are optional; the
+ * default is a no-op.
+ */
+interface ContractCallEvent {
+    contractId: string;
+    method: string;
+    success: boolean;
+    durationMs: number;
+    error?: string;
+}
+interface ScannerSyncEvent {
+    fromLedger: number;
+    toLedger: number;
+}
+interface Telemetry {
+    onContractCall?(event: ContractCallEvent): void;
+    onScannerSync?(event: ScannerSyncEvent): void;
+}
+/** Default telemetry: records nothing. */
+declare const noopTelemetry: Telemetry;
+
+/**
+ * Soroban RPC client. Holds resolved config, a signer, and observability hooks,
+ * and exposes contract `invoke` (write) and `read` (read-only simulate) with
+ * multi-endpoint read fallback, bounded polling, typed errors, and decoded
+ * diagnostics. No ambient globals: everything comes from {@link ResolvedConfig}.
+ */
+
+/** Minimum starting balance (stroops) to create a fresh Stellar account (1 XLM). */
+declare const NEW_ACCOUNT_MIN_RESERVE_STROOPS = 10000000n;
+interface RpcClientOptions {
+    config: ResolvedConfig;
+    logger?: Logger;
+    telemetry?: Telemetry;
+}
+interface InvokeOptions {
+    source: string;
+    contractId: string;
+    method: string;
+    args: xdr.ScVal[];
+    signer: OpaqueSigner;
+    /** Skip pre-flight simulation (default false). */
+    skipSimulation?: boolean;
+    /** Contract package name for error naming (e.g. "reputation-verifier"). */
+    contractPackage?: string;
+}
+interface ReadOptions {
+    source: string;
+    contractId: string;
+    method: string;
+    args: xdr.ScVal[];
+}
+/**
+ * The subset of {@link RpcClient} the contract bindings depend on. Bindings are
+ * written against this interface so they can be unit-tested with a stub invoker
+ * (no network) and dogfooded with the real client in production.
+ */
+interface ContractInvoker {
+    invoke(opts: InvokeOptions): Promise<string>;
+    readNative<T = unknown>(opts: ReadOptions): Promise<T>;
+    simulateRead(opts: ReadOptions): Promise<xdr.ScVal | undefined>;
+    getEvents(request: rpc.Server.GetEventsRequest): Promise<rpc.Api.GetEventsResponse>;
+    getLatestLedger(): Promise<number>;
+}
+declare class RpcClient {
+    readonly config: ResolvedConfig;
+    private readonly logger;
+    private readonly telemetry;
+    private readonly servers;
+    constructor(opts: RpcClientOptions);
+    /** Primary Soroban RPC server. */
+    get server(): rpc.Server;
+    /** Horizon server (first configured Horizon URL). */
+    horizon(): Horizon.Server;
+    /** Whether an account exists on-ledger. */
+    accountExists(publicKey: string): Promise<boolean>;
+    /**
+     * Send a native XLM transfer. Uses `createAccount` when the destination does
+     * not exist yet (stealth accounts), otherwise a `payment`. Signs via the
+     * provided signer and submits through Horizon.
+     */
+    sendNativeTransfer(opts: {
+        destination: string;
+        amountStroops: bigint;
+        signer: OpaqueSigner;
+    }): Promise<string>;
+    /** Run a read across providers with retry + timeout; throws RpcError on exhaustion. */
+    private read;
+    private poll;
+    /** Fetch contract events (paged) with read fallback. */
+    getEvents(request: rpc.Server.GetEventsRequest): Promise<rpc.Api.GetEventsResponse>;
+    /** Latest ledger sequence. */
+    getLatestLedger(): Promise<number>;
+    /** Read-only contract call via simulation. Returns the decoded return ScVal. */
+    simulateRead(opts: ReadOptions): Promise<xdr.ScVal | undefined>;
+    /** Read-only contract call returning the native-decoded value. */
+    readNative<T = unknown>(opts: ReadOptions): Promise<T>;
+    /** Invoke a contract method as a signed transaction. Returns the tx hash. */
+    invoke(opts: InvokeOptions): Promise<string>;
+    private toContractError;
+}
+
+type ArtifactId = "reputation-v2" | "pool-v3";
+type ArtifactKind = "wasm" | "zkey";
+interface ArtifactResolver {
+    /** Resolve an artifact to a URL string or its raw bytes. */
+    resolve(id: ArtifactId, kind: ArtifactKind): Promise<string | Uint8Array>;
+}
+/** Default relative paths, matching the published circuit release layout. */
+declare const DEFAULT_ARTIFACT_PATHS: Record<ArtifactId, Record<ArtifactKind, string>>;
+/**
+ * Build a resolver that maps artifacts to URLs under a base URL. Pass `paths` to
+ * override individual artifact locations.
+ */
+declare function urlArtifactResolver(opts: {
+    baseUrl: string;
+    paths?: Partial<Record<ArtifactId, Partial<Record<ArtifactKind, string>>>>;
+}): ArtifactResolver;
+/**
+ * Build a resolver that maps artifacts to local filesystem paths under a base
+ * directory. The returned path strings are consumed directly by snarkjs in Node.
+ */
+declare function fileArtifactResolver(opts: {
+    baseDir: string;
+    paths?: Partial<Record<ArtifactId, Partial<Record<ArtifactKind, string>>>>;
+}): ArtifactResolver;
+
+interface Groth16ProofLike {
+    pi_a: string[];
+    pi_b: string[][];
+    pi_c: string[];
+}
+interface SerializedProof {
+    a: Uint8Array;
+    b: Uint8Array;
+    c: Uint8Array;
+}
+declare function serializeGroth16Proof(proof: Groth16ProofLike): SerializedProof;
+
+type Poseidon = Parameters<typeof hashFields>[0];
+/** Depth-20 Poseidon Merkle tree, byte-matching the contract / circuit / ASP. */
+declare class PoolMerkleTree {
+    private readonly poseidon;
+    private readonly leaves;
+    private readonly depth;
+    private readonly zero;
+    constructor(poseidon: Poseidon, leaves: bigint[], depth?: number);
+    private rootFrom;
+    root(): bigint;
+    private node;
+    proof(index: number): {
+        siblings: bigint[];
+        indices: number[];
+    };
+}
+/**
+ * Withdrawal context binding:
+ * keccak256(recipient_xdr ‖ withdrawn(16) ‖ fee(16) ‖ relayer_xdr ‖ scope(8)) mod r.
+ */
+declare function computeWithdrawContext(opts: {
+    recipient: string;
+    withdrawn: bigint;
+    fee: bigint;
+    relayer: string;
+    scope: number;
+}): bigint;
+interface PoolWithdrawProof {
+    proofA: Uint8Array;
+    proofB: Uint8Array;
+    proofC: Uint8Array;
+    withdrawnValue: bigint;
+    stateRoot: Uint8Array;
+    aspRoot: Uint8Array;
+    nullifierHash: Uint8Array;
+    newCommitment: Uint8Array;
+}
+interface SnarkjsLike {
+    groth16: {
+        fullProve(input: Record<string, unknown>, wasm: string | Uint8Array, zkey: string | Uint8Array): Promise<{
+            proof: Groth16ProofLike;
+            publicSignals: string[];
+        }>;
+    };
+}
+/**
+ * Generate a full-withdrawal proof for `note`, paying `recipient` (minus `fee` to
+ * `relayer`). The caller supplies the reconstructed pool leaves: `stateLeaves`
+ * (commitment per state-tree index) and `depositIndices` (state index of each
+ * deposit, in ASP-tree order).
+ */
+declare function provePoolWithdraw(opts: {
+    note: PoolNote;
+    recipient: string;
+    relayer: string;
+    fee: bigint;
+    scope: number;
+    stateLeaves: bigint[];
+    depositIndices: number[];
+    artifacts: ArtifactResolver;
+    snarkjs?: SnarkjsLike;
+}): Promise<PoolWithdrawProof>;
+
+declare const RELAY_PAYLOAD_DOMAIN = "opaque-stellar-relay-v1";
+declare const RELAY_CHAIN_STELLAR = 3000;
+type PoolWithdrawPayload = {
+    poolId: string;
+    proofA: Uint8Array;
+    proofB: Uint8Array;
+    proofC: Uint8Array;
+    withdrawnValue: bigint;
+    stateRoot: Uint8Array;
+    aspRoot: Uint8Array;
+    nullifierHash: Uint8Array;
+    newCommitment: Uint8Array;
+    recipient: string;
+    poolFee: bigint;
+    poolRelayer: string;
+};
+type SerializablePoolWithdrawPayload = {
+    poolId: string;
+    proofA: string;
+    proofB: string;
+    proofC: string;
+    withdrawnValue: string;
+    stateRoot: string;
+    aspRoot: string;
+    nullifierHash: string;
+    newCommitment: string;
+    recipient: string;
+    poolFee: string;
+    poolRelayer: string;
+};
+declare function poolWithdrawPayloadPreimage(payload: PoolWithdrawPayload): Uint8Array;
+declare function hashPoolWithdrawPayload(payload: PoolWithdrawPayload): Uint8Array;
+declare function hashPoolWithdrawPayloadHex(payload: PoolWithdrawPayload): string;
+declare function serializePoolWithdrawPayload(payload: PoolWithdrawPayload): SerializablePoolWithdrawPayload;
+declare function parsePoolWithdrawPayload(payload: SerializablePoolWithdrawPayload): PoolWithdrawPayload;
+declare function encodePoolWithdrawPayload(payload: PoolWithdrawPayload): Uint8Array;
+declare function decodePoolWithdrawPayload(bytes: Uint8Array): PoolWithdrawPayload;
+
+type X25519Keypair = {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+};
+declare function generateX25519Keypair(seed?: Uint8Array): Promise<X25519Keypair>;
+declare function sealBox(plaintext: Uint8Array, recipientPublicKey: Uint8Array): Promise<string>;
+declare function openBox(box: string, recipientSecretKey: Uint8Array): Promise<Uint8Array>;
+
+/**
+ * `opaque/jobs/v1` wire messages: advert, bid, encrypted payload. Bids are
+ * Ed25519-signed by the relayer operator over a domain-separated digest so the
+ * SDK can verify them before trusting registry state.
+ */
+
+type JobAdvert = {
+    t: "advert";
+    v: 1;
+    jobId: string;
+    chain: number;
+    fee: string;
+    deadline: number;
+    payloadHash: string;
+};
+type RelayerBid = {
+    t: "bid";
+    v: 1;
+    jobId: string;
+    chain: number;
+    operator: string;
+    x25519Pk: string;
+    sig: string;
+    endpoint?: string;
+    freeStake?: string;
+};
+type EncryptedPayload = {
+    t: "payload";
+    v: 1;
+    jobId: string;
+    to: string;
+    box: string;
+};
+type RelayerMessage = JobAdvert | RelayerBid | EncryptedPayload;
+declare function makeAdvert(args: {
+    jobId: Uint8Array;
+    fee: bigint;
+    deadline: number;
+    payloadHash: Uint8Array;
+    chain?: number;
+}): JobAdvert;
+declare function bidSigningDigest(jobId: Uint8Array, x25519Pk: Uint8Array): Uint8Array;
+declare function makeBid(args: {
+    advert: JobAdvert;
+    operator: Keypair;
+    x25519Pk: Uint8Array;
+    endpoint?: string;
+    freeStake?: bigint;
+}): RelayerBid;
+declare function verifyBid(bid: RelayerBid): boolean;
+declare function validateAdvert(value: unknown): JobAdvert;
+declare function validateBid(value: unknown): RelayerBid;
+
+/**
+ * Relayer-market gateway client: build a blind withdrawal payload, advertise a
+ * job, collect and verify bids (signature + on-chain registry state), pick a
+ * relayer, and deliver the payload encrypted to its X25519 key. HTTP transport
+ * is the `opaque/jobs/v1` gateway API.
+ */
+
+type VerifiedBid = RelayerBid & {
+    freeStakeValue: bigint;
+};
+type RelayerJobDraft = {
+    jobId: Uint8Array;
+    jobIdHex: string;
+    payload: PoolWithdrawPayload;
+    payloadHash: Uint8Array;
+    payloadHashHex: string;
+    advert: JobAdvert;
+    deadlineLedger: number;
+    fee: bigint;
+};
+type RelayerJobStatus = "open" | "accepted" | "submitted" | "slashed" | "canceled" | "unknown";
+/** Cryptographically random 32-byte job id. */
+declare function randomJobId(): Uint8Array;
+/**
+ * Build the blind withdrawal payload. The pool fee is zero (the registry escrow
+ * pays the relayer) and the proof binds the registry as the pool relayer, so the
+ * payload hash is deterministic before a relayer is chosen.
+ */
+declare function buildRelayedWithdrawPayload(args: {
+    poolId: string;
+    registryId: string;
+    proof: PoolWithdrawProof;
+    recipient: string;
+}): PoolWithdrawPayload;
+declare function buildRelayerJobDraft(args: {
+    payload: PoolWithdrawPayload;
+    fee: bigint;
+    deadlineLedger: number;
+    jobId?: Uint8Array;
+}): RelayerJobDraft;
+/** Stake-weighted random choice among verified bids. */
+declare function pickStakeWeightedBid(bids: VerifiedBid[]): VerifiedBid | null;
+declare class RelayerGateway {
+    private readonly gatewayUrls;
+    private readonly registryId;
+    private readonly invoker;
+    constructor(opts: {
+        gatewayUrls: string[];
+        registryId: string;
+        invoker: ContractInvoker;
+    });
+    private url;
+    /** A deadline `ledgers` ahead of the current ledger. */
+    deadlineLedger(ledgers?: number): Promise<number>;
+    publishAdvert(advert: JobAdvert, gateway?: string): Promise<void>;
+    fetchBids(jobIdHex: string, gateway?: string): Promise<VerifiedBid[]>;
+    deliverPayload(args: {
+        draft: RelayerJobDraft;
+        bid: RelayerBid;
+        gateway?: string;
+    }): Promise<{
+        acceptedTx?: string;
+        submittedTx?: string;
+    } | null>;
+    jobStatus(jobIdHex: string, source: string): Promise<RelayerJobStatus>;
+    private verifyBidRegistryState;
+    private registryView;
+}
+
+export { fileArtifactResolver as $, type ArtifactResolver as A, type SignTxFn as B, type ContractInvoker as C, DEFAULT_ARTIFACT_PATHS as D, type EncryptedPayload as E, type SignerContext as F, type Groth16ProofLike as G, TESTNET_DEPLOYMENT as H, type InvokeOptions as I, type JobAdvert as J, bidSigningDigest as K, type Logger as L, buildRelayedWithdrawPayload as M, NETWORK_PRESETS as N, type OpaqueSigner as O, type PoolWithdrawProof as P, buildRelayerJobDraft as Q, type ResolvedConfig as R, type ScannerSyncEvent as S, type Telemetry as T, callbackSigner as U, type VerifiedBid as V, computeWithdrawContext as W, type X25519Keypair as X, consoleLogger as Y, decodePoolWithdrawPayload as Z, encodePoolWithdrawPayload as _, type RelayerJobDraft as a, generateX25519Keypair as a0, hashPoolWithdrawPayload as a1, hashPoolWithdrawPayloadHex as a2, keypairSigner as a3, makeAdvert as a4, makeBid as a5, noopTelemetry as a6, openBox as a7, parsePoolWithdrawPayload as a8, pickStakeWeightedBid as a9, poolWithdrawPayloadPreimage as aa, provePoolWithdraw as ab, randomJobId as ac, resolveConfig as ad, sealBox as ae, serializeGroth16Proof as af, serializePoolWithdrawPayload as ag, silentLogger as ah, urlArtifactResolver as ai, validateAdvert as aj, validateBid as ak, verifyBid as al, type PoolWithdrawPayload as b, type RelayerBid as c, type RelayerJobStatus as d, type OpaqueConfig as e, RpcClient as f, type ArtifactId as g, type ArtifactKind as h, type ContractAddresses as i, type ContractCallEvent as j, DEPLOYMENTS as k, NEW_ACCOUNT_MIN_RESERVE_STROOPS as l, type NetworkDeployment as m, type NetworkPreset as n, type OpaqueNetwork as o, PoolMerkleTree as p, type PoolWiring as q, RELAY_CHAIN_STELLAR as r, RELAY_PAYLOAD_DOMAIN as s, type ReadOptions as t, RelayerGateway as u, type RelayerMessage as v, type RelayerWiring as w, type RpcClientOptions as x, type SerializablePoolWithdrawPayload as y, type SerializedProof as z };