@opaquecash/stellar 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,822 @@
+import { GhostEntryLike, Hex, StealthAnnouncement, ScanMatch } from './crypto/index.cjs';
+export { AttestationDataError, DomainSeparationOpts, EncryptedGhostPayload, FieldDef, FieldType, LEGACY_SETUP_MESSAGE, MAX_ATTESTATION_DATA_LEN, MAX_FIELDS, MAX_FIELD_NAME_LEN, MAX_STRING_VALUE_LEN, MemoRisk, MemoType, MemoValidationResult, Network, PaymentLink, PaymentLinkError, PaymentLinkParams, SchemaParseError, addressToAuthorityBytes, bigIntToBytes32, buildDomainSeparatedMessage, buildGhostAnnouncementPayload, bytesToBigInt, bytesToHex, checkViewTagMatch, computeSchemaId, computeSchemaIdFromBytes, computeStealthAddressAndViewTag, concatBytes, convertLegacyLink, createPaymentLink, decodeAttestationData, decodePaymentLink, decryptGhostEntries, deriveAnnouncerEphemeralKey, deriveKeysFromSignature, deriveStealthStellarAddress, deriveStealthStellarAddressFromStealthPrivKey, deriveStealthStellarKeypair, deriveStealthStellarKeypairFromStealthPrivKey, encodeAttestationData, encodeCanonicalFieldDefs, encodePaymentLink, encryptGhostEntries, exportEncryptedBackup, fieldDefsToCanonicalString, formatStroopsToXlm, formatXlm, hexToBytes, importEncryptedBackup, isOpaquePaymentLink, isValidAmount, isValidAssetCode, isValidIso8601, isValidMetaAddress, isValidNetwork, isValidStellarPublicKey, isValidUrl, keysToStealthMetaAddress, memoRiskFor, memoWarningCopy, parseFieldDefinitions, parseHorizonBalanceToStroops, parseStealthMetaAddress, parseXlmToStroops, recipientSharedSecretHash, reconstructStealthPrivateKey, scanAnnouncements, stealthIdFromPrivateKey, stealthMetaAddressToHex, toHex32, validateMemo } from './crypto/index.cjs';
+import { P as PoolNote } from './notes-CTR_oi8Y.cjs';
+export { B as BN254_R, D as DerivedDeposit, a as POOL_TREE_DEPTH, d as deriveDeposit, g as getPoseidon, h as hashFields, n as newNoteSecrets, r as randomFieldElement, u as unspentTotal } from './notes-CTR_oi8Y.cjs';
+import { C as ContractInvoker, O as OpaqueSigner, A as ArtifactResolver, G as Groth16ProofLike, R as ResolvedConfig, P as PoolWithdrawProof, a as RelayerJobDraft, b as PoolWithdrawPayload, V as VerifiedBid, c as RelayerBid, d as RelayerJobStatus, e as OpaqueConfig, L as Logger, T as Telemetry, f as RpcClient } from './index-Cy3ABCai.cjs';
+export { g as ArtifactId, h as ArtifactKind, i as ContractAddresses, j as ContractCallEvent, D as DEFAULT_ARTIFACT_PATHS, k as DEPLOYMENTS, E as EncryptedPayload, I as InvokeOptions, J as JobAdvert, N as NETWORK_PRESETS, l as NEW_ACCOUNT_MIN_RESERVE_STROOPS, m as NetworkDeployment, n as NetworkPreset, o as OpaqueNetwork, p as PoolMerkleTree, q as PoolWiring, r as RELAY_CHAIN_STELLAR, s as RELAY_PAYLOAD_DOMAIN, t as ReadOptions, u as RelayerGateway, v as RelayerMessage, w as RelayerWiring, x as RpcClientOptions, S as ScannerSyncEvent, y as SerializablePoolWithdrawPayload, z as SerializedProof, B as SignTxFn, F as SignerContext, H as TESTNET_DEPLOYMENT, X as X25519Keypair, K as bidSigningDigest, M as buildRelayedWithdrawPayload, Q as buildRelayerJobDraft, U as callbackSigner, W as computeWithdrawContext, Y as consoleLogger, Z as decodePoolWithdrawPayload, _ as encodePoolWithdrawPayload, $ as fileArtifactResolver, a0 as generateX25519Keypair, a1 as hashPoolWithdrawPayload, a2 as hashPoolWithdrawPayloadHex, a3 as keypairSigner, a4 as makeAdvert, a5 as makeBid, a6 as noopTelemetry, a7 as openBox, a8 as parsePoolWithdrawPayload, a9 as pickStakeWeightedBid, aa as poolWithdrawPayloadPreimage, ab as provePoolWithdraw, ac as randomJobId, ad as resolveConfig, ae as sealBox, af as serializeGroth16Proof, ag as serializePoolWithdrawPayload, ah as silentLogger, ai as urlArtifactResolver, aj as validateAdvert, ak as validateBid, al as verifyBid } from './index-Cy3ABCai.cjs';
+import { xdr } from '@stellar/stellar-sdk';
+
+/**
+ * Typed error hierarchy for the SDK. Every thrown error carries a stable,
+ * machine-readable `code` so callers can branch without string-matching
+ * messages. Soroban contract failures map to {@link ContractError} with the
+ * decoded contract error code (and a name when the contract's error enum is
+ * known to the SDK).
+ */
+declare class OpaqueError extends Error {
+    /** Stable, machine-readable error code (e.g. "CONFIG", "CONTRACT"). */
+    readonly code: string;
+    constructor(message: string, code: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Configuration is missing or invalid (e.g. mainnet without RPC URLs). */
+declare class ConfigError extends OpaqueError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** A signer adapter failed to produce a signature. */
+declare class SignerError extends OpaqueError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** An RPC or Horizon request failed (network, timeout, or HTTP status). */
+declare class RpcError extends OpaqueError {
+    readonly httpStatus?: number;
+    constructor(message: string, options?: {
+        httpStatus?: number;
+        cause?: unknown;
+    });
+}
+/** A transaction failed during pre-flight simulation. */
+declare class SimulationError extends OpaqueError {
+    readonly diagnostics?: string;
+    constructor(message: string, options?: {
+        diagnostics?: string;
+        cause?: unknown;
+    });
+}
+/** A Soroban contract invocation reverted with a contract error code. */
+declare class ContractError extends OpaqueError {
+    readonly contract: string;
+    readonly contractCode: number;
+    /** Human-readable name when the contract's error enum is known. */
+    readonly errorName?: string;
+    constructor(opts: {
+        contract: string;
+        contractCode: number;
+        errorName?: string;
+        message?: string;
+        cause?: unknown;
+    });
+}
+/** The published reputation/pool root is unavailable or not yet indexed. */
+declare class RootUnavailableError extends OpaqueError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** A circuit artifact failed to resolve or failed its integrity check. */
+declare class ArtifactError extends OpaqueError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * A capability that depends on a layer not yet wired in this build (e.g. the
+ * proving layer, the WASM scanner, or the relayer gateway client). Thrown so the
+ * surface is discoverable and the failure is explicit rather than silent.
+ */
+declare class NotWiredError extends OpaqueError {
+    constructor(capability: string, hint?: string);
+}
+/**
+ * Known contract error enums, keyed by contract package name. Populated as the
+ * SDK binds each contract; an unknown code still surfaces as a numeric
+ * {@link ContractError}. Source of truth is each contract's `#[contracterror]`.
+ */
+declare const CONTRACT_ERROR_NAMES: Record<string, Record<number, string>>;
+/** Look up a contract error name for a code, if the SDK knows the enum. */
+declare function contractErrorName(contractPackage: string, code: number): string | undefined;
+
+/**
+ * ScVal conversion helpers for building Soroban contract-call arguments.
+ * Thin, typed wrappers over `@stellar/stellar-sdk` so callers never hand-roll
+ * `nativeToScVal` type tags.
+ */
+
+/** Stellar address (G/C-strkey) -> ScVal address. */
+declare function addressToScVal(addr: string): xdr.ScVal;
+/** Raw bytes -> ScVal bytes. */
+declare function bytesToScVal(bytes: Uint8Array): xdr.ScVal;
+/** Number/bigint -> ScVal u32. */
+declare function u32ToScVal(n: number): xdr.ScVal;
+/** Number/bigint -> ScVal u64. */
+declare function u64ToScVal(n: bigint | number): xdr.ScVal;
+/** Bigint -> ScVal i128 (Soroban's signed amount type). */
+declare function i128ToScVal(n: bigint): xdr.ScVal;
+/** Bigint -> ScVal u128. */
+declare function u128ToScVal(n: bigint): xdr.ScVal;
+/** String -> ScVal symbol. */
+declare function symbolToScVal(s: string): xdr.ScVal;
+/** String -> ScVal string. */
+declare function stringToScVal(s: string): xdr.ScVal;
+/** Boolean -> ScVal bool. */
+declare function boolToScVal(b: boolean): xdr.ScVal;
+/** Optional address -> ScVal address, or a void ScVal when null/undefined. */
+declare function optionAddressToScVal(addr: string | null | undefined): xdr.ScVal;
+/** Decode an ScVal into its native JS representation. */
+declare function fromScVal(v: xdr.ScVal): unknown;
+
+/**
+ * Decode Soroban diagnostic events and ScErrors from a failed transaction into
+ * short, human-readable strings, and extract a contract error code when present.
+ */
+
+/** Render an ScError into a short token like `ContractError#4` or `sceBudget`. */
+declare function describeScError(e: xdr.ScError): string;
+/**
+ * Decode an array of diagnostic events (XDR) into a compact, de-duplicated
+ * string. Bounded to keep error messages readable.
+ */
+declare function decodeDiagnostics(events: unknown[]): string;
+/**
+ * Best-effort extraction of a contract error code from diagnostic events.
+ * Returns the first `ContractError#N` code found, or null.
+ */
+declare function extractContractErrorCode(events: unknown[]): number | null;
+
+/**
+ * Bindings for the stealth-registry and stealth-announcer contracts: publish a
+ * meta-address and announce a one-time stealth transfer.
+ */
+
+/** secp256k1 stealth scheme id, as registered on-chain. */
+declare const SCHEME_ID_SECP256K1 = 1n;
+declare class StealthRegistry {
+    private readonly rpc;
+    readonly contractId: string;
+    constructor(rpc: ContractInvoker, contractId: string);
+    /** Register a stealth meta-address for the signer's account. */
+    registerKeys(opts: {
+        stealthMetaAddress: Uint8Array;
+        schemeId?: bigint;
+        signer: OpaqueSigner;
+    }): Promise<string>;
+}
+declare class StealthAnnouncer {
+    private readonly rpc;
+    readonly contractId: string;
+    constructor(rpc: ContractInvoker, contractId: string);
+    /** Announce a one-time stealth transfer (stealth id + ephemeral key + view tag). */
+    announce(opts: {
+        stealthAddress: Uint8Array;
+        ephemeralPubKey: Uint8Array;
+        metadata: Uint8Array;
+        schemeId?: bigint;
+        signer: OpaqueSigner;
+    }): Promise<string>;
+}
+
+declare class SchemaRegistry {
+    private readonly rpc;
+    readonly contractId: string;
+    constructor(rpc: ContractInvoker, contractId: string);
+    /** Register a schema. The signer is the schema authority. */
+    registerSchema(opts: {
+        schemaId: Uint8Array;
+        name: string;
+        fieldDefinitions: string;
+        revocable: boolean;
+        version?: number;
+        resolver?: string | null;
+        schemaExpiryLedger: number;
+        signer: OpaqueSigner;
+    }): Promise<string>;
+    deprecateSchema(opts: {
+        schemaId: Uint8Array;
+        signer: OpaqueSigner;
+    }): Promise<string>;
+    addDelegate(opts: {
+        schemaId: Uint8Array;
+        delegate: string;
+        signer: OpaqueSigner;
+    }): Promise<string>;
+    removeDelegate(opts: {
+        schemaId: Uint8Array;
+        delegate: string;
+        signer: OpaqueSigner;
+    }): Promise<string>;
+    private assertDelegate;
+}
+declare class AttestationEngine {
+    private readonly rpc;
+    readonly contractId: string;
+    constructor(rpc: ContractInvoker, contractId: string);
+    /** Attest to a stealth identity under a schema. The signer is the issuer. */
+    attest(opts: {
+        schemaId: Uint8Array;
+        stealthAddressHash: Uint8Array;
+        data: Uint8Array;
+        expirationLedger: number;
+        refUid: Uint8Array;
+        signer: OpaqueSigner;
+    }): Promise<string>;
+    revokeAttestation(opts: {
+        uid: Uint8Array;
+        signer: OpaqueSigner;
+    }): Promise<string>;
+}
+
+interface VerifyProofV2Inputs {
+    proofA: Uint8Array;
+    proofB: Uint8Array;
+    proofC: Uint8Array;
+    merkleRoot: Uint8Array;
+    attestationId: Uint8Array;
+    externalNullifier: Uint8Array;
+    nullifierHash: Uint8Array;
+}
+declare class Groth16Verifier {
+    private readonly rpc;
+    readonly contractId: string;
+    constructor(rpc: ContractInvoker, contractId: string);
+    /** Submit a Groth16 V2 proof. The public signals are passed as an ScMap. */
+    verifyProofV2(opts: VerifyProofV2Inputs & {
+        signer: OpaqueSigner;
+    }): Promise<string>;
+}
+interface VerifyReputationInputs {
+    proofA: Uint8Array;
+    proofB: Uint8Array;
+    proofC: Uint8Array;
+    merkleRoot: Uint8Array;
+    attestationId: Uint8Array;
+    externalNullifier: bigint;
+    nullifierHash: Uint8Array;
+    expirationLedger?: number;
+}
+/**
+ * High-level reputation-verifier binding. `verify_reputation` enforces root
+ * validity + nullifier-replay protection and calls the groth16-verifier; this is
+ * the on-chain entry point for proving reputation (vs. the lower-level
+ * {@link Groth16Verifier}).
+ */
+declare class ReputationVerifier {
+    private readonly rpc;
+    readonly contractId: string;
+    constructor(rpc: ContractInvoker, contractId: string);
+    /** Submit a V2 reputation proof for on-chain verification. */
+    verifyReputation(opts: VerifyReputationInputs & {
+        groth16VerifierId: string;
+        signer: OpaqueSigner;
+    }): Promise<string>;
+    /** Read the latest published reputation Merkle root (bytes), or null if none. */
+    getLatestRoot(source: string): Promise<Uint8Array | null>;
+}
+
+interface PoolWithdrawInputs {
+    proofA: Uint8Array;
+    proofB: Uint8Array;
+    proofC: Uint8Array;
+    withdrawnValue: bigint;
+    stateRoot: Uint8Array;
+    aspRoot: Uint8Array;
+    nullifierHash: Uint8Array;
+    newCommitment: Uint8Array;
+    recipient: string;
+    fee: bigint;
+    relayer: string;
+}
+declare class PrivacyPool {
+    private readonly rpc;
+    readonly contractId: string;
+    constructor(rpc: ContractInvoker, contractId: string);
+    /** Deposit `value` stroops under a precomputed commitment at `expectedIndex`. */
+    deposit(opts: {
+        value: bigint;
+        commitment: Uint8Array;
+        expectedIndex: number;
+        signer: OpaqueSigner;
+    }): Promise<string>;
+    /** Withdraw to `recipient` (minus `fee` to `relayer`) with a v3 proof. */
+    withdraw(opts: PoolWithdrawInputs & {
+        signer: OpaqueSigner;
+    }): Promise<string>;
+    /** Publish a tree root (admin only). `kind` selects the state vs ASP root. */
+    updateRoot(opts: {
+        kind: "state" | "asp";
+        root: Uint8Array;
+        datasetHash: Uint8Array;
+        signer: OpaqueSigner;
+    }): Promise<string>;
+    /** Read the next deposit leaf index (the value `deposit` will assign). */
+    getDepositCount(source: string): Promise<number>;
+    /** Read the latest published state (or ASP) root, or null if none. */
+    getLatestRoot(opts: {
+        source: string;
+        kind: "state" | "asp";
+    }): Promise<Uint8Array | null>;
+    /**
+     * Reconstruct the pool's commitment leaves from on-chain events. Returns the
+     * commitment at each state-tree index (`stateLeaves`, deposits + withdrawal
+     * remainders) and the state index of each deposit in event order
+     * (`depositIndices`, == ASP-tree order). Feed these into the withdrawal prover.
+     */
+    reconstructState(opts?: {
+        startLedger?: number;
+    }): Promise<{
+        stateLeaves: bigint[];
+        depositIndices: number[];
+    }>;
+}
+
+/**
+ * Binding for the relayer-registry contract job lifecycle the wallet drives:
+ * create a blind withdrawal job (escrow fee), cancel it, or slash an
+ * accepted-but-unsubmitted job after the deadline. Relayer-side methods
+ * (register, accept, submit) live in the relayer node.
+ */
+
+declare class RelayerRegistry {
+    private readonly rpc;
+    readonly contractId: string;
+    constructor(rpc: ContractInvoker, contractId: string);
+    /** Create a blind job with an escrowed fee and a payload hash + deadline. */
+    createJob(opts: {
+        jobId: Uint8Array;
+        payloadHash: Uint8Array;
+        deadlineLedger: number;
+        fee: bigint;
+        signer: OpaqueSigner;
+    }): Promise<string>;
+    /** Cancel a never-accepted job after its deadline; refunds the escrow fee. */
+    cancelJob(opts: {
+        jobId: Uint8Array;
+        signer: OpaqueSigner;
+    }): Promise<string>;
+    /** Slash an accepted-but-unsubmitted job after its deadline. */
+    slashJob(opts: {
+        jobId: Uint8Array;
+        signer: OpaqueSigner;
+    }): Promise<string>;
+    private jobAction;
+}
+
+/**
+ * Storage abstractions. The SDK never imports a state container (no zustand, no
+ * IndexedDB): pool notes, ghost entries, and scan cursors persist through these
+ * interfaces. In-memory defaults are provided; a host app plugs its own
+ * (zustand/IndexedDB in the browser, fs/sqlite on a server).
+ */
+
+/** Persistence for privacy-pool notes (spending material). */
+interface NoteStore {
+    list(): Promise<PoolNote[]>;
+    add(note: PoolNote): Promise<void>;
+    /** Mark the note with this commitment as spent. */
+    markSpent(commitment: string): Promise<void>;
+}
+/** Persistence for stealth "ghost" entries (ephemeral keys + metadata). */
+interface VaultStore {
+    listGhosts(): Promise<GhostEntryLike[]>;
+    saveGhost(entry: GhostEntryLike): Promise<void>;
+}
+/** Persistence for the announcement-scan cursor (last processed ledger). */
+interface ScanStore {
+    getCursor(): Promise<number | null>;
+    setCursor(ledger: number): Promise<void>;
+}
+/** In-memory {@link NoteStore}. Notes are keyed by commitment. */
+declare class MemoryNoteStore implements NoteStore {
+    private notes;
+    list(): Promise<PoolNote[]>;
+    add(note: PoolNote): Promise<void>;
+    markSpent(commitment: string): Promise<void>;
+}
+/** In-memory {@link VaultStore}. Ghost entries are keyed by stealth address. */
+declare class MemoryVaultStore implements VaultStore {
+    private entries;
+    listGhosts(): Promise<GhostEntryLike[]>;
+    saveGhost(entry: GhostEntryLike): Promise<void>;
+}
+/** In-memory {@link ScanStore}. */
+declare class MemoryScanStore implements ScanStore {
+    private cursor;
+    getCursor(): Promise<number | null>;
+    setCursor(ledger: number): Promise<void>;
+}
+
+/**
+ * Typed interface to the Rust/WASM DKSAP scanner. The scanner does the
+ * performance-critical view-tag filtering, stealth-key reconstruction, and
+ * reputation-witness generation. The binary ships with the package and is loaded
+ * lazily by an environment-specific {@link ScannerLoader} (browser instantiates
+ * via `WebAssembly`, Node reads the file); both resolve to this interface.
+ *
+ * Pure-TS equivalents for the simplest operations live in `crypto/dksap`
+ * (`checkViewTagMatch`, `reconstructStealthPrivateKey`) for environments that
+ * cannot load WASM.
+ */
+interface ScannerModule {
+    derive_stealth_address_wasm(viewPrivkeyBytes: Uint8Array, spendPubkeyBytes: Uint8Array, ephemeralPubkeyBytes: Uint8Array): {
+        stealthAddress: string;
+        viewTag: number;
+    };
+    check_announcement_view_tag_wasm(viewTag: number, viewPrivkeyBytes: Uint8Array, ephemeralPubkeyBytes: Uint8Array): string;
+    reconstruct_signing_key_wasm(masterSpendPrivBytes: Uint8Array, masterViewPrivBytes: Uint8Array, ephemeralPubkeyBytes: Uint8Array): Uint8Array;
+    scan_attestations_wasm(announcementsJson: string, viewPrivkeyBytes: Uint8Array, spendPubkeyBytes: Uint8Array): string;
+    scan_attestations_v2_wasm(announcementsJson: string, schemasJson: string, viewPrivkeyBytes: Uint8Array, spendPubkeyBytes: Uint8Array, currentSlot: bigint, trustedIssuersJson: string): string;
+    generate_reputation_witness(attestationsJson: string, targetTraitId: string, stealthPrivkeyBytes: Uint8Array, externalNullifier: string): string;
+    encode_attestation_metadata_wasm(viewTag: number, attestationId: bigint): string;
+}
+/** Lazily load and instantiate the scanner module. */
+type ScannerLoader = () => Promise<ScannerModule>;
+
+interface ReputationProveInput {
+    /** Attestation id (== schema id) of the trait being proven. */
+    attestationId: number;
+    /** The holder's stealth private key bytes. */
+    stealthPrivKey: Uint8Array;
+    /** Application-chosen external nullifier (must fit in u64 for the contract). */
+    externalNullifier: bigint;
+}
+interface ReputationWitnessV2 {
+    stealth_pk: string;
+    schema_id: string;
+    issuer_pk_x: string;
+    trait_data_hash: string;
+    nonce: string;
+    merkle_path: string[];
+    merkle_path_indices: number[];
+    merkle_root: string;
+    attestation_id: string;
+    external_nullifier: string;
+    nullifier_hash: string;
+}
+/** Build the canonical V2 reputation witness for a holder's own attestation. */
+declare function buildReputationWitnessV2(input: ReputationProveInput): Promise<ReputationWitnessV2>;
+interface SnarkjsLike {
+    groth16: {
+        fullProve(input: Record<string, unknown>, wasm: string | Uint8Array, zkey: string | Uint8Array): Promise<{
+            proof: Groth16ProofLike;
+            publicSignals: string[];
+        }>;
+    };
+}
+interface ReputationProof extends VerifyReputationInputs {
+    publicSignals: string[];
+}
+/**
+ * Generate a V2 reputation proof and return a bundle ready for
+ * `reputation.verifyOnChain` / the reputation-verifier contract.
+ */
+declare function proveReputationV2(opts: {
+    input: ReputationProveInput;
+    artifacts: ArtifactResolver;
+    snarkjs?: SnarkjsLike;
+}): Promise<ReputationProof>;
+
+/**
+ * The capability surface the services depend on. {@link OpaqueClient} implements
+ * it; services depend on this interface (not the client class) so they stay
+ * decoupled and unit-testable with a lightweight stub context.
+ */
+
+interface ContractBindings {
+    stealthRegistry: StealthRegistry;
+    stealthAnnouncer: StealthAnnouncer;
+    schemaRegistry: SchemaRegistry;
+    attestationEngine: AttestationEngine;
+    groth16Verifier: Groth16Verifier;
+    reputationVerifier: ReputationVerifier;
+    privacyPool: PrivacyPool;
+    relayerRegistry: RelayerRegistry;
+}
+interface OpaqueClientContext {
+    readonly config: ResolvedConfig;
+    readonly rpc: ContractInvoker;
+    readonly contracts: ContractBindings;
+    readonly notes: NoteStore;
+    readonly vault: VaultStore;
+    readonly scanStore: ScanStore;
+    readonly signer?: OpaqueSigner;
+    /** Circuit artifact resolver, when proof generation is enabled. */
+    readonly artifacts?: ArtifactResolver;
+    /** Returns the configured signer or throws if none is set. */
+    requireSigner(): OpaqueSigner;
+    /** Send a native XLM transfer (create-account or payment) via Horizon. */
+    sendNativeTransfer(opts: {
+        destination: string;
+        amountStroops: bigint;
+        signer: OpaqueSigner;
+    }): Promise<string>;
+}
+
+declare class SchemasService {
+    private readonly ctx;
+    constructor(ctx: OpaqueClientContext);
+    /** Register a schema. The signer is the authority; returns the schema id. */
+    register(opts: {
+        name: string;
+        fieldDefinitions: string;
+        revocable: boolean;
+        version?: number;
+        resolver?: string | null;
+        schemaExpiryLedger: number;
+    }): Promise<{
+        schemaId: Uint8Array;
+        txHash: string;
+    }>;
+    /** Attest to a stealth identity under a schema. The signer is the issuer. */
+    attest(opts: {
+        schemaId: Uint8Array;
+        stealthAddressHash: Uint8Array;
+        fieldValues: Record<string, string>;
+        fieldDefinitions: string;
+        expirationLedger: number;
+        refUid?: Uint8Array;
+    }): Promise<string>;
+    revoke(opts: {
+        uid: Uint8Array;
+    }): Promise<string>;
+    deprecate(opts: {
+        schemaId: Uint8Array;
+    }): Promise<string>;
+    addDelegate(opts: {
+        schemaId: Uint8Array;
+        delegate: string;
+    }): Promise<string>;
+    removeDelegate(opts: {
+        schemaId: Uint8Array;
+        delegate: string;
+    }): Promise<string>;
+}
+
+/**
+ * Stealth private payments. Derive an identity and meta-address, register it,
+ * send a stealth XLM payment (one-time account + announcement), and sweep a
+ * detected stealth account. Announcement scanning needs the WASM scanner and is
+ * surfaced as a not-wired capability in this build (use the crypto primitives
+ * `checkViewTagMatch` / `reconstructStealthPrivateKey` with your own event feed).
+ */
+
+interface StealthIdentity {
+    viewingKey: Uint8Array;
+    spendingKey: Uint8Array;
+    metaAddress: Uint8Array;
+    metaHex: Hex;
+}
+declare class PaymentsService {
+    private readonly ctx;
+    constructor(ctx: OpaqueClientContext);
+    /** Derive viewing/spending keys + meta-address from a wallet signature. */
+    deriveIdentity(signatureHex: string): StealthIdentity;
+    /** Register a stealth meta-address for the signer's account. */
+    register(opts: {
+        metaAddress: Uint8Array;
+    }): Promise<string>;
+    /** Pure: compute a one-time stealth address + announcement params for a recipient. */
+    prepareTransfer(recipientMetaHex: string): {
+        ephemeralPriv: Uint8Array;
+        ephemeralPubKey: Uint8Array;
+        stealthAddress: string;
+        stealthStellarAddress: string;
+        viewTag: number;
+        metadata: Uint8Array;
+    };
+    /**
+     * Send a stealth XLM payment: pay the one-time stealth Stellar account, then
+     * publish the announcement so the recipient can detect and sweep it.
+     */
+    send(opts: {
+        to: string;
+        amountXlm: string;
+    }): Promise<{
+        stealthStellarAddress: string;
+        ephemeralPubKey: Uint8Array;
+        paymentTxHash: string;
+        announceTxHash: string;
+    }>;
+    /**
+     * Sweep a detected stealth account to a destination. The stealth account signs
+     * itself (derived from the one-time key), so the connected wallet is never the
+     * source. `amountStroops` is the exact amount to move (compute the spendable
+     * balance from Horizon, reserving fee + minimum balance).
+     */
+    sweep(opts: {
+        stealthPrivKey: Uint8Array;
+        destination: string;
+        amountStroops: bigint;
+    }): Promise<string>;
+    /**
+     * Scan announcements for transfers addressed to `identity`, returning each
+     * match with its reconstructed one-time key and Stellar account. The caller
+     * supplies the announcements (read from the stealth-announcer contract events).
+     */
+    scan(opts: {
+        announcements: StealthAnnouncement[];
+        identity: Pick<StealthIdentity, "viewingKey" | "spendingKey">;
+    }): ScanMatch[];
+}
+
+declare class ReputationService {
+    private readonly ctx;
+    private readonly schemas;
+    constructor(ctx: OpaqueClientContext, schemas: SchemasService);
+    /** Attest a reputation trait to a stealth identity (delegates to schemas). */
+    attest(opts: Parameters<SchemasService["attest"]>[0]): Promise<string>;
+    /** Submit a precomputed V2 reputation proof for on-chain verification. */
+    verifyOnChain(opts: VerifyReputationInputs): Promise<string>;
+    /** Read the latest published reputation Merkle root, or null if none. */
+    getLatestRoot(opts?: {
+        source?: string;
+    }): Promise<Uint8Array | null>;
+    /**
+     * Generate a V2 reputation proof. Requires an artifact resolver
+     * (`new OpaqueClient({ artifacts })`); otherwise throws {@link NotWiredError}.
+     */
+    prove(input: ReputationProveInput): Promise<ReputationProof>;
+    /** Generate a proof and submit it on-chain in one call. Returns the tx hash. */
+    proveAndVerify(input: ReputationProveInput): Promise<string>;
+}
+
+/**
+ * Privacy pool. Deposit (derive a note's commitment and persist the note),
+ * withdraw with a precomputed proof, and read pool state (deposit count, roots).
+ * Withdrawal proof *generation* needs the proving layer (snarkjs + circuit
+ * artifacts) and is surfaced as a not-wired capability in this build: bring a
+ * precomputed proof bundle to withdraw().
+ */
+
+/** A withdrawal proof bundle (everything except the public recipient/fee/relayer). */
+type WithdrawProofBundle = PoolWithdrawProof;
+declare class PoolService {
+    private readonly ctx;
+    constructor(ctx: OpaqueClientContext);
+    private source;
+    /**
+     * Deposit `amountXlm` into the pool. Reads the next leaf index, derives the
+     * commitment from fresh (or provided) secrets, submits, and persists the note.
+     */
+    deposit(opts: {
+        amountXlm: string;
+        secrets?: {
+            nullifier: string;
+            secret: string;
+        };
+        createdAt?: number;
+    }): Promise<{
+        note: PoolNote;
+        txHash: string;
+    }>;
+    /** Withdraw using a precomputed proof bundle. Marks the note spent on success. */
+    withdraw(opts: {
+        proof: WithdrawProofBundle;
+        recipient: string;
+        fee?: bigint;
+        relayer?: string;
+        /** Note commitment to mark spent once the withdrawal lands. */
+        noteCommitment?: string;
+    }): Promise<string>;
+    /** Read the next deposit leaf index. */
+    getDepositCount(opts?: {
+        source?: string;
+    }): Promise<number>;
+    /** Read the latest published state and ASP roots (or null when unpublished). */
+    getRoots(opts?: {
+        source?: string;
+    }): Promise<{
+        state: Uint8Array | null;
+        asp: Uint8Array | null;
+    }>;
+    /**
+     * Generate a full-withdrawal proof for a note. Requires an artifact resolver
+     * (`new OpaqueClient({ artifacts })`). The pool leaves are reconstructed from
+     * on-chain Deposit/Withdraw events automatically; pass `stateLeaves` +
+     * `depositIndices` to skip the on-chain read (e.g. in tests).
+     */
+    proveWithdraw(opts: {
+        note: PoolNote;
+        recipient: string;
+        relayer?: string;
+        fee?: bigint;
+        scope?: number;
+        stateLeaves?: bigint[];
+        depositIndices?: number[];
+    }): Promise<PoolWithdrawProof>;
+}
+
+/**
+ * Relayer market: the wallet-side withdrawal flow. Build a blind withdrawal
+ * payload from a pool proof, create the on-chain escrow job, advertise it,
+ * collect and verify bids, pick a relayer, and deliver the encrypted payload.
+ */
+
+declare class RelayerService {
+    private readonly ctx;
+    constructor(ctx: OpaqueClientContext);
+    private gateway;
+    /** Create a blind withdrawal job (escrows the fee on-chain). */
+    createJob(opts: {
+        jobId: Uint8Array;
+        payloadHash: Uint8Array;
+        deadlineLedger: number;
+        fee: bigint;
+    }): Promise<string>;
+    /** Create the on-chain job for a built draft. */
+    createJobForDraft(draft: RelayerJobDraft): Promise<string>;
+    /** Cancel a never-accepted job after its deadline (refunds the escrow fee). */
+    cancelJob(opts: {
+        jobId: Uint8Array;
+    }): Promise<string>;
+    /** Slash an accepted-but-unsubmitted job after its deadline. */
+    slashJob(opts: {
+        jobId: Uint8Array;
+    }): Promise<string>;
+    /** Build the blind withdrawal payload from a pool proof. */
+    buildWithdrawPayload(opts: {
+        proof: PoolWithdrawProof;
+        recipient: string;
+    }): PoolWithdrawPayload;
+    /** Build a job draft (job id, payload hash, advert) from a payload. */
+    buildJobDraft(opts: {
+        payload: PoolWithdrawPayload;
+        fee: bigint;
+        deadlineLedger: number;
+        jobId?: Uint8Array;
+    }): RelayerJobDraft;
+    /** A deadline `ledgers` ahead of the current ledger. */
+    deadlineLedger(ledgers?: number): Promise<number>;
+    /** Advertise a job to the gateway. */
+    advertise(draft: RelayerJobDraft): Promise<void>;
+    /** Fetch and verify bids for a job (signature + on-chain registry state). */
+    fetchBids(jobIdHex: string): Promise<VerifiedBid[]>;
+    /** Stake-weighted random choice among verified bids. */
+    pickBid(bids: VerifiedBid[]): VerifiedBid | null;
+    /** Encrypt the payload to the chosen relayer and deliver it to the gateway. */
+    deliverPayload(args: {
+        draft: RelayerJobDraft;
+        bid: RelayerBid;
+    }): Promise<{
+        acceptedTx?: string;
+        submittedTx?: string;
+    } | null>;
+    /** Read a job's on-chain status. */
+    jobStatus(jobIdHex: string, source?: string): Promise<RelayerJobStatus>;
+}
+
+/**
+ * The high-level entry point. One config + one signer wires the resolved network,
+ * RPC client, contract bindings, storage, and the domain services
+ * (`payments`, `pool`, `reputation`, `schemas`, `relayer`). Low-level escape
+ * hatches (`rpc`, `contracts`, `soroban`) are exposed for advanced use.
+ */
+
+interface OpaqueClientOptions extends OpaqueConfig {
+    signer?: OpaqueSigner;
+    storage?: {
+        notes?: NoteStore;
+        vault?: VaultStore;
+        scan?: ScanStore;
+    };
+    logger?: Logger;
+    telemetry?: Telemetry;
+    /** Circuit artifact resolver; enables proof generation when provided. */
+    artifacts?: ArtifactResolver;
+    /** Advanced / testing: inject a custom invoker instead of the built-in RpcClient. */
+    invoker?: ContractInvoker;
+}
+declare class OpaqueClient implements OpaqueClientContext {
+    readonly config: ResolvedConfig;
+    readonly rpc: ContractInvoker;
+    readonly contracts: ContractBindings;
+    readonly notes: NoteStore;
+    readonly vault: VaultStore;
+    readonly scanStore: ScanStore;
+    readonly signer?: OpaqueSigner;
+    readonly artifacts?: ArtifactResolver;
+    readonly payments: PaymentsService;
+    readonly pool: PoolService;
+    readonly reputation: ReputationService;
+    readonly schemas: SchemasService;
+    readonly relayer: RelayerService;
+    private readonly rpcClient?;
+    constructor(opts: OpaqueClientOptions);
+    /** The built-in Soroban/Horizon client, or undefined when a custom invoker was injected. */
+    get soroban(): RpcClient | undefined;
+    /** Returns the configured signer or throws if none was set. */
+    requireSigner(): OpaqueSigner;
+    /** Send a native XLM transfer through the built-in RpcClient. */
+    sendNativeTransfer(opts: {
+        destination: string;
+        amountStroops: bigint;
+        signer: OpaqueSigner;
+    }): Promise<string>;
+}
+
+/**
+ * `@opaquecash/stellar` — stealth private payments, privacy pools, relayer-market
+ * submission, and on-chain ZK reputation for Stellar / Soroban.
+ *
+ * The high-level `OpaqueClient` and chain services are layered on top of the
+ * isomorphic crypto primitives re-exported here. Until the chain layer lands,
+ * the crypto surface is the stable, published entry point. Import a narrower
+ * surface via subpaths (e.g. `@opaquecash/stellar/crypto`) for the smallest
+ * bundle.
+ */
+declare const VERSION = "0.1.0";
+
+export { ArtifactError, ArtifactResolver, AttestationEngine, CONTRACT_ERROR_NAMES, ConfigError, type ContractBindings, ContractError, ContractInvoker, GhostEntryLike, Groth16ProofLike, Groth16Verifier, Hex, Logger, MemoryNoteStore, MemoryScanStore, MemoryVaultStore, NotWiredError, type NoteStore, OpaqueClient, type OpaqueClientContext, type OpaqueClientOptions, OpaqueConfig, OpaqueError, OpaqueSigner, PaymentsService, PoolNote, PoolService, type PoolWithdrawInputs, PoolWithdrawPayload, PoolWithdrawProof, PrivacyPool, RelayerBid, RelayerJobDraft, RelayerJobStatus, RelayerRegistry, RelayerService, type ReputationProof, type ReputationProveInput, ReputationService, ReputationVerifier, type ReputationWitnessV2, ResolvedConfig, RootUnavailableError, RpcClient, RpcError, SCHEME_ID_SECP256K1, ScanMatch, type ScanStore, type ScannerLoader, type ScannerModule, SchemaRegistry, SchemasService, SignerError, SimulationError, StealthAnnouncement, StealthAnnouncer, type StealthIdentity, StealthRegistry, Telemetry, VERSION, type VaultStore, VerifiedBid, type VerifyProofV2Inputs, type VerifyReputationInputs, type WithdrawProofBundle, addressToScVal, boolToScVal, buildReputationWitnessV2, bytesToScVal, contractErrorName, decodeDiagnostics, describeScError, extractContractErrorCode, fromScVal, i128ToScVal, optionAddressToScVal, proveReputationV2, stringToScVal, symbolToScVal, u128ToScVal, u32ToScVal, u64ToScVal };