@opaquecash/stellar
Classes
| Class | Description |
|---|---|
| OpaqueClient | - |
| SchemaRegistry | - |
| AttestationEngine | - |
| StealthRegistry | - |
| StealthAnnouncer | - |
| PrivacyPool | - |
| RelayerRegistry | - |
| Groth16Verifier | - |
| ReputationVerifier | 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 Groth16Verifier). |
| SchemaParseError | - |
| AttestationDataError | - |
| OpaqueError | 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 ContractError with the decoded contract error code (and a name when the contract's error enum is known to the SDK). |
| ConfigError | Configuration is missing or invalid (e.g. mainnet without RPC URLs). |
| SignerError | A signer adapter failed to produce a signature. |
| RpcError | An RPC or Horizon request failed (network, timeout, or HTTP status). |
| SimulationError | A transaction failed during pre-flight simulation. |
| ContractError | A Soroban contract invocation reverted with a contract error code. |
| RootUnavailableError | The published reputation/pool root is unavailable or not yet indexed. |
| ArtifactError | A circuit artifact failed to resolve or failed its integrity check. |
| NotWiredError | 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. |
| PoolMerkleTree | Depth-20 Poseidon Merkle tree, byte-matching the contract / circuit / ASP. |
| RelayerGateway | - |
| RpcClient | - |
| PaymentsService | - |
| PoolService | - |
| RelayerService | - |
| ReputationService | - |
| SchemasService | - |
| MemoryNoteStore | In-memory NoteStore. Notes are keyed by commitment. |
| MemoryVaultStore | In-memory VaultStore. Ghost entries are keyed by stealth address. |
| MemoryScanStore | In-memory ScanStore. |
Interfaces
| Interface | Description |
|---|---|
| ArtifactResolver | - |
| OpaqueClientOptions | - |
| ContractAddresses | - |
| PoolWiring | - |
| RelayerWiring | - |
| NetworkDeployment | - |
| OpaqueConfig | - |
| ResolvedConfig | - |
| NetworkPreset | - |
| PoolWithdrawInputs | - |
| VerifyProofV2Inputs | - |
| VerifyReputationInputs | - |
| MemoRisk | - |
| MemoValidationResult | - |
| PaymentLinkParams | - |
| PaymentLink | - |
| PaymentLinkError | - |
| StealthAnnouncement | - |
| ScanMatch | - |
| FieldDef | - |
| Logger | Pluggable logger. The SDK logs nothing by default (no console.log noise in a library); a host app can pass consoleLogger or its own implementation. |
| PoolWithdrawProof | - |
| ReputationProveInput | - |
| ReputationWitnessV2 | - |
| ReputationProof | - |
| Groth16ProofLike | - |
| SerializedProof | - |
| RpcClientOptions | - |
| InvokeOptions | - |
| ReadOptions | - |
| ContractInvoker | The subset of 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. |
| ScannerModule | 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 ScannerLoader (browser instantiates via WebAssembly, Node reads the file); both resolve to this interface. |
| ContractBindings | - |
| OpaqueClientContext | - |
| StealthIdentity | - |
| SignerContext | - |
| OpaqueSigner | - |
| NoteStore | Persistence for privacy-pool notes (spending material). |
| VaultStore | Persistence for stealth "ghost" entries (ephemeral keys + metadata). |
| ScanStore | Persistence for the announcement-scan cursor (last processed ledger). |
| ContractCallEvent | 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. |
| ScannerSyncEvent | - |
| Telemetry | - |
Type Aliases
| Type Alias | Description |
|---|---|
| ArtifactId | - |
| ArtifactKind | - |
| OpaqueNetwork | Stellar network presets: passphrase and default RPC / Horizon endpoints per network. Mainnet ships with no default endpoints — callers must supply production providers explicitly. |
| GhostEntryLike | - |
| EncryptedGhostPayload | - |
| Hex | 0x-prefixed hex string. |
| DomainSeparationOpts | - |
| MemoType | Destination memo risk + validation. |
| PoolNote | - |
| DerivedDeposit | - |
| Network | Opaque payment-link format: opaque://v{version}/{network}/{metaAddress}?{params} with versioning, network binding, and optional SEP-compatible parameters. |
| FieldType | Schema field primitives shared by the schema codec and the schema service. |
| X25519Keypair | - |
| VerifiedBid | - |
| RelayerJobDraft | - |
| RelayerJobStatus | - |
| JobAdvert | - |
| RelayerBid | - |
| EncryptedPayload | - |
| RelayerMessage | - |
| PoolWithdrawPayload | - |
| SerializablePoolWithdrawPayload | - |
| ScannerLoader | Lazily load and instantiate the scanner module. |
| WithdrawProofBundle | A withdrawal proof bundle (everything except the public recipient/fee/relayer). |
| SignTxFn | Low-level callback form: sign a transaction XDR, return the signed XDR. |
Variables
| Variable | Description |
|---|---|
| DEFAULT_ARTIFACT_PATHS | Default relative paths, matching the published circuit release layout. |
| TESTNET_DEPLOYMENT | Generated from deployments/v1/testnet.json. |
| DEPLOYMENTS | Known deployments by network. Testnet is the only live deployment today. |
| NETWORK_PRESETS | - |
| SCHEME_ID_SECP256K1 | secp256k1 stealth scheme id, as registered on-chain. |
| formatXlm | Alias for formatStroopsToXlm. |
| LEGACY_SETUP_MESSAGE | - |
| POOL_TREE_DEPTH | Privacy-pool note model and cryptographic derivation. |
| BN254_R | - |
| MAX_FIELDS | - |
| MAX_FIELD_NAME_LEN | - |
| MAX_STRING_VALUE_LEN | - |
| MAX_ATTESTATION_DATA_LEN | - |
| CONTRACT_ERROR_NAMES | Known contract error enums, keyed by contract package name. Populated as the SDK binds each contract; an unknown code still surfaces as a numeric ContractError. Source of truth is each contract's #[contracterror]. |
| VERSION | The installed SDK version. |
| silentLogger | Default logger: discards everything. |
| consoleLogger | Logger that forwards to the global console. |
| RELAY_PAYLOAD_DOMAIN | - |
| RELAY_CHAIN_STELLAR | - |
| NEW_ACCOUNT_MIN_RESERVE_STROOPS | Minimum starting balance (stroops) to create a fresh Stellar account (1 XLM). |
| noopTelemetry | Default telemetry: records nothing. |
Functions
| Function | Description |
|---|---|
| urlArtifactResolver | Build a resolver that maps artifacts to URLs under a base URL. Pass paths to override individual artifact locations. |
| fileArtifactResolver | 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. |
| resolveConfig | Resolve user config into a complete, validated configuration: network preset + baked deployment + explicit overrides. Throws ConfigError when a required endpoint or contract address is missing (e.g. mainnet usage). |
| parseXlmToStroops | Parse an XLM string into stroops. Enforces at most 7 decimal places and rejects malformed input. |
| parseHorizonBalanceToStroops | Parse a Horizon balance string into stroops. Returns 0 for empty or malformed input (defensive against unexpected API responses). |
| formatStroopsToXlm | Format stroops as an XLM string with trailing zeros removed. |
| encryptGhostEntries | Encrypt ghost entries. Only ephemeralPrivKeyHex is encrypted; metadata (cluster, stealth address, timestamp) stays readable. |
| decryptGhostEntries | Decrypt ghost entries produced by encryptGhostEntries. |
| exportEncryptedBackup | Export ghost entries as an encrypted JSON string. |
| importEncryptedBackup | Import ghost entries from an encrypted backup string. |
| hexToBytes | Parse a hex string (with or without 0x) into bytes. |
| bytesToHex | Encode bytes as a lowercase hex string (no 0x prefix). |
| bytesToBigInt | Interpret bytes as a big-endian unsigned integer. |
| bigIntToBytes32 | Encode a bigint as a fixed 32-byte big-endian array. |
| toHex32 | bigint -> 0x-prefixed 32-byte big-endian hex. |
| concatBytes | Concatenate byte arrays into one. |
| buildDomainSeparatedMessage | Build the human-readable, domain-separated message a wallet signs to derive its Opaque stealth keys. Signing it is not a transaction and moves no funds. |
| deriveKeysFromSignature | Derive viewing key (v) and spending key (s) from a wallet signature used as entropy. Expands the signature into 64 bytes via HKDF-SHA256, then splits into two 32-byte private keys. Domain string is "opaque-cash-v1". |
| keysToStealthMetaAddress | Build the stealth meta-address from viewing and spending private keys. Meta-address = compressed(V) |
| stealthMetaAddressToHex | Encode the 66-byte stealth meta-address as 0x-prefixed hex. |
| parseStealthMetaAddress | Parse a recipient stealth meta-address into viewing and spending public keys. Format: first 33 bytes = compressed viewing key V, next 33 = compressed S. |
| computeStealthAddressAndViewTag | Sender-side: compute a one-time stealth address and view tag for a recipient meta-address. Generates a fresh ephemeral key per call. |
| buildGhostAnnouncementPayload | Rebuild announce() parameters for a manual ghost receive using a stored ephemeral private key (deterministic re-derivation of a prior send). |
| recipientSharedSecretHash | Recipient-side: recompute the DKSAP shared-secret hash and view tag from the sender's ephemeral public key and the recipient's viewing key. Mirrors the sender computation via ECDH symmetry (viewPriv·EphPub == ephPriv·ViewPub). |
| checkViewTagMatch | Cheap recipient-side prefilter: does this announcement's view tag match? Lets a recipient skip the expensive point math for non-matching transfers. |
| reconstructStealthPrivateKey | Recipient-side: reconstruct the one-time stealth private key for a transfer. stealthPriv = (spendingKey + sH) mod n, where sH = keccak(viewPriv·EphPub). The returned key controls the same secp256k1 point the sender derived, hence the same deterministic Stellar account. |
| deriveAnnouncerEphemeralKey | Deterministic ephemeral scalar for the "Announcer" stealth signer. |
| deriveStealthStellarKeypair | Derive the deterministic Ed25519 Stellar keypair from a stealth secp256k1 point. |
| deriveStealthStellarAddress | Derive the deterministic Stellar G-address from a stealth secp256k1 point. |
| stealthIdFromPrivateKey | Recompute the 20-byte EVM-style stealth id (0x + 40 hex) from a stealth private key. Used to confirm a view-tag match against an announcement. |
| deriveStealthStellarAddressFromStealthPrivKey | Derive the deterministic Stellar G-address from a stealth private key. |
| deriveStealthStellarKeypairFromStealthPrivKey | Derive the deterministic Stellar keypair from a stealth private key. |
| memoRiskFor | Look up the memo risk for a destination. Safe for any input. |
| validateMemo | Validate a memo value against the Stellar memo spec for the given type. |
| memoWarningCopy | Warning copy for the inline banner, or null when no warning is needed. |
| getPoseidon | Lazily build (and cache) the circomlibjs Poseidon instance. |
| hashFields | Hash a list of field elements with Poseidon, returning the field result. |
| randomFieldElement | Cryptographically-random field element < r (decimal string). |
| deriveDeposit | Derive the commitment material for one deposit from its secrets. |
| newNoteSecrets | Build a fresh note's secrets (commitment is filled once the leaf index is known). |
| unspentTotal | Unspent total across notes, in stroops. |
| isValidMetaAddress | Validate a DKSAP meta-address: 0x + 132 hex chars (66 bytes). |
| isValidNetwork | - |
| isValidStellarPublicKey | Validate a Stellar public key (G..., 56 chars, base32). |
| isValidAssetCode | - |
| isValidAmount | - |
| isValidIso8601 | - |
| isValidUrl | - |
| encodePaymentLink | Encode a payment link from components. Throws on invalid input. |
| decodePaymentLink | Decode a payment-link string into components, or a structured error. |
| createPaymentLink | Create a v1 payment link from a meta-address and network. |
| isOpaquePaymentLink | True when the string parses as a valid opaque payment link. |
| convertLegacyLink | Convert a legacy https://host/pay/{metaAddress} link into opaque format. |
| scanAnnouncements | Scan announcements for transfers to the recipient. Each candidate is view-tag prefiltered, then confirmed by reconstructing the one-time key and checking its stealth id equals the announced one (so a coincidental tag match is rejected). |
| parseFieldDefinitions | Parse and validate "type name" comma-separated field definitions. |
| fieldDefsToCanonicalString | - |
| encodeCanonicalFieldDefs | - |
| addressToAuthorityBytes | - |
| computeSchemaIdFromBytes | Compute a schema id (SHA-256 of authority |
| computeSchemaId | - |
| encodeAttestationData | Encode attestation payload bytes in schema field order. |
| decodeAttestationData | Decode canonical attestation bytes into a field-value map. |
| contractErrorName | Look up a contract error name for a code, if the SDK knows the enum. |
| computeWithdrawContext | Withdrawal context binding: keccak256(recipient_xdr ‖ withdrawn(16) ‖ fee(16) ‖ relayer_xdr ‖ scope(8)) mod r. |
| provePoolWithdraw | 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). |
| buildReputationWitnessV2 | Build the canonical V2 reputation witness for a holder's own attestation. |
| proveReputationV2 | Generate a V2 reputation proof and return a bundle ready for reputation.verifyOnChain / the reputation-verifier contract. |
| serializeGroth16Proof | - |
| generateX25519Keypair | - |
| sealBox | - |
| openBox | - |
| randomJobId | Cryptographically random 32-byte job id. |
| buildRelayedWithdrawPayload | 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. |
| buildRelayerJobDraft | - |
| pickStakeWeightedBid | Stake-weighted random choice among verified bids. |
| makeAdvert | - |
| bidSigningDigest | - |
| makeBid | - |
| verifyBid | - |
| validateAdvert | - |
| validateBid | - |
| poolWithdrawPayloadPreimage | - |
| hashPoolWithdrawPayload | - |
| hashPoolWithdrawPayloadHex | - |
| serializePoolWithdrawPayload | - |
| parsePoolWithdrawPayload | - |
| encodePoolWithdrawPayload | - |
| decodePoolWithdrawPayload | - |
| describeScError | Render an ScError into a short token like ContractError#4 or sceBudget. |
| decodeDiagnostics | Decode an array of diagnostic events (XDR) into a compact, de-duplicated string. Bounded to keep error messages readable. |
| extractContractErrorCode | Best-effort extraction of a contract error code from diagnostic events. Returns the first ContractError#N code found, or null. |
| addressToScVal | Stellar address (G/C-strkey) -> ScVal address. |
| bytesToScVal | Raw bytes -> ScVal bytes. |
| u32ToScVal | Number/bigint -> ScVal u32. |
| u64ToScVal | Number/bigint -> ScVal u64. |
| i128ToScVal | Bigint -> ScVal i128 (Soroban's signed amount type). |
| u128ToScVal | Bigint -> ScVal u128. |
| symbolToScVal | String -> ScVal symbol. |
| stringToScVal | String -> ScVal string. |
| boolToScVal | Boolean -> ScVal bool. |
| optionAddressToScVal | Optional address -> ScVal address, or a void ScVal when null/undefined. |
| fromScVal | Decode an ScVal into its native JS representation. |
| keypairSigner | Build a signer from a raw Ed25519 keypair (server / non-browser use). Accepts a Stellar secret seed (S...) or a Keypair instance. |
| callbackSigner | Build a signer from caller-supplied callbacks. Use this to adapt Freighter or any external signing service. |