@qntx/spark 0.0.0-stage → 0.1.1

package/dist/index-D1fBaHTa.d.mts

@@ -0,0 +1,55 @@
+//#region src/errors/index.d.ts
+/** Base class of every error raised by this package. */
+declare class SparkError extends Error {
+  constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * A failure reported by a {@link SparkCrypto} backend. `code` is the C ABI error code (see
+ * `qntx_spark.h`); the message never carries input bytes.
+ */
+declare class SparkCryptoError extends SparkError {
+  readonly code: number;
+  constructor(code: number, options?: ErrorOptions);
+}
+/**
+ * Malformed caller- or peer-supplied data: a Spark address, a BOLT-11 invoice, an encoding. The
+ * message names the offending field and rule; it never echoes the input, so no secret or invoice
+ * content leaks into logs through error messages.
+ */
+declare class SparkInputError extends SparkError {
+  constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * A request to a signing operator or the SSP failed. `code` uses one vocabulary: the gRPC canonical
+ * snake_case names for operator errors ("unauthenticated", "unavailable", "invalid_argument",
+ * "deadline_exceeded", … — Connect's PascalCase enum names are mapped down), `http_<status>` for
+ * SSP HTTP failures, `unexpected_response` for malformed SSP responses, and the SSP's GraphQL
+ * `extensions.code` lowercased. `operator` is the FROST identifier of the operator that failed,
+ * when the failure came from an operator. The message carries the server's own message — never
+ * request bodies.
+ */
+declare class SparkRequestError extends SparkError {
+  readonly code?: string | undefined;
+  readonly operator?: string | undefined;
+  constructor(message: string, options?: ErrorOptions & {
+    readonly code?: string;
+    readonly operator?: string;
+  });
+}
+/**
+ * A token broadcast's outcome is uncertain: the transaction may have committed server-side.
+ * `inputOutputIds` names the spent outputs — the caller passes it back to `tokens.transfer` or
+ * `tokens.consolidate` with the same receiver and amount, and that retry either returns the
+ * committed transaction's hash or broadcasts exactly those inputs once. Retrying without it would
+ * select different outputs and pay twice.
+ */
+declare class SparkTokenBroadcastError extends SparkRequestError {
+  readonly inputOutputIds: ReadonlyArray<string>;
+  constructor(message: string, options: ErrorOptions & {
+    readonly code?: string;
+    readonly operator?: string;
+    readonly inputOutputIds: ReadonlyArray<string>;
+  });
+}
+//#endregion
+export { SparkTokenBroadcastError as a, SparkRequestError as i, SparkError as n, SparkInputError as r, SparkCryptoError as t };

package/dist/index-DUSx3L3J.d.mts

@@ -0,0 +1,69 @@
+//#region src/crypto/index.d.ts
+/**
+ * C ABI version implemented by a {@link SparkCrypto} backend. Bumped only when `qntx_spark.h`
+ * changes incompatibly; the signer verifies it at construction.
+ */
+declare const SPARK_ABI_VERSION = 1;
+/**
+ * Curve-intensive Spark cryptography behind a bytes-only boundary. A backend maps 1:1 onto the C
+ * ABI in `qntx_spark.h` (`@qntx/spark-wasm` wraps the wasm32 build, `@qntx/spark-native` the native
+ * HybridObject); every method returns raw bytes and reports failure as a `SparkCryptoError` whose
+ * `code` is the ABI error code.
+ *
+ * Error codes: `0` success; `1` length error; `2` invalid scalar; `3` invalid point; `4` protobuf
+ * decode failure; `5` argument out of range (threshold, share count, job count cap 256); `6` FROST
+ * failure (invalid share, missing commitment); `7` decryption authentication failure; `8` internal
+ * error.
+ */
+type SparkCrypto = {
+  readonly abiVersion: number;
+  /**
+   * FROST signing nonces and commitments.
+   *
+   * `hedge` is a 32-byte signer-private hedge secret; `random` is `n`×32 bytes. Returns `n`×130
+   * bytes: per item `hiding‖binding` nonces (64) followed by the compressed `hiding‖binding`
+   * commitments (66). Each item runs frost `SigningNonces::new(hedge,
+   * ChaCha20Rng::from_seed(random_i))`. The hedge makes weak entropy safe, but nonce uniqueness
+   * still requires a fresh seed every call — the same seed under the same hedge reproduces the same
+   * nonces. The signer's `NonceStore` additionally rejects reuse of a commitment.
+   */
+  frostCommit: (hedge: Uint8Array, random: Uint8Array) => Uint8Array;
+  /**
+   * User-side FROST signature shares.
+   *
+   * `request` is a protobuf `ffi.FrostSignRequest`; returns `ffi.FrostSignResponse` — one 32-byte
+   * signature share per job, in job order. The backend signs the user role under the `SingleUser`
+   * scheme with `Identifier::derive("user")`; the user verifying share is computed from the secret
+   * key inside the backend and never accepted as input.
+   */
+  frostSign: (request: Uint8Array) => Uint8Array;
+  /**
+   * FROST aggregate signatures.
+   *
+   * `request` is a protobuf `ffi.FrostAggregateRequest`; returns `ffi.FrostAggregateResponse` — one
+   * 64-byte signature per job, in job order. When an adaptor public key is present the final
+   * verification is skipped per branch, matching upstream.
+   */
+  frostAggregate: (request: Uint8Array) => Uint8Array;
+  /**
+   * ECIES encryption, byte-compatible with `ecies` 0.2 defaults.
+   *
+   * `publicKey` is a 33- or 65-byte secp256k1 public key; `random` is 32 bytes. Returns
+   * `ephemeralPk(65)‖nonce(16)‖tag(16)‖ciphertext`: HKDF-SHA256 over `ephemeralPk‖sharedPoint`
+   * (both uncompressed) with AES-256-GCM and a 16-byte nonce; the ephemeral key and nonce are
+   * derived from `random`.
+   */
+  eciesEncrypt: (publicKey: Uint8Array, plaintext: Uint8Array, random: Uint8Array) => Uint8Array;
+  /** Inverse of {@link eciesEncrypt}: 32-byte private key and ciphertext yield the plaintext. */
+  eciesDecrypt: (privateKey: Uint8Array, ciphertext: Uint8Array) => Uint8Array;
+  /**
+   * Feldman VSS secret splitting, matching upstream `vss.rs` (`vsss-rs`) with seeded ChaCha20
+   * replacing its randomness source.
+   *
+   * `secret` is 32 bytes, `threshold` t ≥ 2, `shares` n ≥ t and `random` is 32 bytes. Returns
+   * `t`×33 proof bytes followed by `n`×32 share bytes; share indexes run 1..n.
+   */
+  splitSecretWithProofs: (secret: Uint8Array, threshold: number, shares: number, random: Uint8Array) => Uint8Array;
+};
+//#endregion
+export { SparkCrypto as n, SPARK_ABI_VERSION as t };

package/dist/index.d.mts

@@ -0,0 +1,115 @@
+import { a as SparkTokenBroadcastError, i as SparkRequestError, n as SparkError, r as SparkInputError, t as SparkCryptoError } from "./index-D1fBaHTa.mjs";
+import { a as sparkNetworkConfig, i as SparkOperatorConfig, n as SparkNetwork, r as SparkNetworkConfig } from "./lightning-address-CRULmi9v.mjs";
+import { i as isExpired, n as Bolt11Network, r as decodeBolt11, t as Bolt11Invoice } from "./bolt11-DsNTTS_O.mjs";
+import { A as CooperativeExitStatus, C as exitTransactions, D as CooperativeExitQuote, E as createMemorySparkStore, F as UnusedDepositAddress, I as SparkLeaf, L as SparkEvent, M as StaticDepositClaim, N as StaticDepositRefund, O as CooperativeExitResult, P as StaticDepositUtxo, S as ExitTransaction, T as SparkStore, _ as LightningSendStatus, a as createSparkClient, b as LightningInvoice, c as buildCpfpChild, d as SparkTokenBalance, f as SparkTokenOutput, g as LightningSendOutcome, h as LightningReceiveStatus, i as SparkInvoiceStatus, j as MIN_STATIC_REFUND_FEE_SATS, k as CooperativeExitSpeed, l as SparkTransfer, m as SparkWalletSettings, n as SparkClient, o as StaticDepositClaimResult, p as SparkTokenOutputStatus, r as SparkClientOptions, s as FundingInput, t as ClaimPendingResult, u as SparkTransferLeaf, v as LightningSendStatusRequest, w as SparkExitChain, x as WatchtowerExitedLeaf, y as LightningPayment } from "./index-B_g3vHnT.mjs";
+import { g as SparkSigner } from "./types-jBCznYd6.mjs";
+//#region src/core/invoice.d.ts
+/** Payment carried by a Spark invoice: satoshis or BTKN tokens. */
+type SparkPayment = {
+  readonly type: "sats";
+  readonly amount?: number | undefined;
+} | {
+  readonly type: "tokens";
+  /** 32-byte token identifier. */
+  readonly tokenIdentifier?: Uint8Array | undefined;
+  /** Big-endian uint128, at most 16 bytes. */
+  readonly amount?: Uint8Array | undefined;
+};
+/** Plain-TypeScript mirror of `spark.SparkInvoiceFields`; version is currently always 1. */
+type SparkInvoiceFields = {
+  readonly version: number;
+  /** UUID identifying the invoice (canonical lowercase form). */
+  readonly id: string;
+  readonly payment?: SparkPayment | undefined;
+  /** At most 120 UTF-8 bytes. */
+  readonly memo?: string | undefined;
+  /** 33-byte compressed secp256k1 public key. */
+  readonly senderPublicKey?: Uint8Array | undefined;
+  /** Unix milliseconds. */
+  readonly expiresAt?: number | undefined;
+};
+//#endregion
+//#region src/core/address.d.ts
+/**
+ * Plain-TypeScript mirror of `spark.SparkAddress`. `signature` is the 64-byte schnorr signature
+ * over the invoice fields; signing and verification are handled by the signer.
+ */
+type SparkAddress = {
+  readonly network: SparkNetwork;
+  readonly identityPublicKey: Uint8Array;
+  readonly invoice?: SparkInvoiceFields | undefined;
+  readonly signature?: Uint8Array | undefined;
+};
+/** Encodes a Spark address as `hrp1…` bech32m (the network's current prefix). */
+export declare function encodeSparkAddress(address: SparkAddress): string;
+/**
+ * Decodes a bech32m Spark address. Current (`spark`, `sparkrt`) and legacy (`sp`, `sprt`) prefixes
+ * are accepted; the prefix selects the network. Throws {@link SparkInputError} on malformed input.
+ */
+export declare function decodeSparkAddress(address: string): SparkAddress;
+/**
+ * Verifies the BIP-340 schnorr signature a Spark invoice carries: the signature covers
+ * `hashSparkInvoice(invoice, identityPublicKey, network)` under the x-only identity public key.
+ * Returns false for a missing invoice/signature or an invalid signature, matching upstream
+ * `validateSparkInvoiceSignature`'s verification step.
+ */
+export declare function verifySparkAddressSignature(address: SparkAddress): boolean;
+//#endregion
+//#region src/core/token-identifier.d.ts
+type SparkTokenIdentifierData = {
+  readonly tokenIdentifier: Uint8Array;
+  readonly network: SparkNetwork;
+};
+/** Encodes a raw 32-byte token identifier as `btkn1…`/`btknrt1…` bech32m. */
+export declare function encodeTokenIdentifier(tokenIdentifier: Uint8Array, network: SparkNetwork): string;
+/**
+ * Decodes a bech32m token identifier. Only the `btkn` (mainnet) and `btknrt` (regtest) prefixes are
+ * accepted; the prefix selects the network. Throws {@link SparkInputError} on malformed input.
+ */
+export declare function decodeTokenIdentifier(text: string): SparkTokenIdentifierData;
+//#endregion
+//#region src/invoice/create.d.ts
+type InvoiceOptions = {
+  readonly signer: SparkSigner;
+  readonly network: SparkNetwork;
+  readonly random: (length: number) => Uint8Array;
+  readonly now: () => number;
+  readonly memo?: string;
+  /** Restricts payment to this sender identity public key. */
+  readonly senderPublicKey?: Uint8Array;
+  /** Unix milliseconds; the invoice is rejected once expired. */
+  readonly expiresAtMs?: number;
+};
+/**
+ * Builds a signed sats invoice address for this identity. `amountSats` may be omitted for an
+ * open-amount invoice the payer fills in.
+ */
+export declare function createSatsInvoice(options: InvoiceOptions & {
+  readonly amountSats?: number;
+}): Promise<string>;
+/**
+ * Builds a signed tokens invoice address for this identity. `tokenIdentifier` (32 bytes raw) and
+ * `amount` may be omitted; payers then pick the token and amount.
+ */
+export declare function createTokensInvoice(options: InvoiceOptions & {
+  readonly tokenIdentifier?: Uint8Array;
+  readonly amount?: bigint;
+}): Promise<string>;
+//#endregion
+//#region src/invoice/parse.d.ts
+type ParsedSparkInvoice = {
+  readonly receiverIdentityPublicKey: Uint8Array;
+  readonly fields: SparkInvoiceFields;
+  /** True when the invoice carries a signature that verifies under the receiver's key. */
+  readonly signed: boolean;
+};
+/**
+ * Decodes and validates a signed invoice address: must be an invoice-carrying Spark address for
+ * `network`, any signature must verify, and the invoice must not be expired at `now`.
+ */
+export declare function parseSparkInvoice(text: string, options: {
+  readonly network: SparkNetwork;
+  readonly now: number;
+}): ParsedSparkInvoice;
+//#endregion
+export { type Bolt11Invoice, type Bolt11Network, type ClaimPendingResult, type CooperativeExitQuote, type CooperativeExitResult, type CooperativeExitSpeed, type CooperativeExitStatus, type ExitTransaction, type FundingInput, type LightningInvoice, type LightningPayment, type LightningReceiveStatus, type LightningSendOutcome, type LightningSendStatus, type LightningSendStatusRequest, MIN_STATIC_REFUND_FEE_SATS, type ParsedSparkInvoice, type SparkAddress, type SparkClient, type SparkClientOptions, SparkCryptoError, SparkError, type SparkEvent, type SparkExitChain, SparkInputError, type SparkInvoiceFields, type SparkInvoiceStatus, type SparkLeaf, type SparkNetwork, type SparkNetworkConfig, type SparkOperatorConfig, type SparkPayment, SparkRequestError, type SparkStore, type SparkTokenBalance, SparkTokenBroadcastError, type SparkTokenIdentifierData, type SparkTokenOutput, type SparkTokenOutputStatus, type SparkTransfer, type SparkTransferLeaf, type SparkWalletSettings, type StaticDepositClaim, type StaticDepositClaimResult, type StaticDepositRefund, type StaticDepositUtxo, type UnusedDepositAddress, type WatchtowerExitedLeaf, buildCpfpChild, createMemorySparkStore, createSparkClient, decodeBolt11, exitTransactions, isExpired, sparkNetworkConfig };