@qntx/spark 0.0.0-stage → 0.1.0

package/dist/types-jBCznYd6.d.mts

@@ -0,0 +1,322 @@
+import { n as SparkNetwork, t as LightningAddressStatement } from "./lightning-address-CRULmi9v.mjs";
+import { Transaction } from "@scure/btc-signer";
+//#region src/core/bitcoin/sighash.d.ts
+/** A transaction to sign: raw bytes plus every input's prevout script and amount. */
+type SigningTarget = {
+  readonly transaction: Uint8Array;
+  readonly inputIndex: number;
+  readonly prevouts: ReadonlyArray<{
+    script: Uint8Array;
+    amount: number;
+  }>;
+};
+//#endregion
+//#region src/signer/types.d.ts
+/**
+ * A private key the local signer can resolve, addressed by how upstream derives it. The key
+ * material never leaves the signer; callers pass only these descriptors.
+ *
+ * - `leaf`: `LEAF{leafId}` path — hardened child `u32be(sha256(utf8(leafId))[0..4]) mod 2^31` of the
+ *   signing root (`m/8797555'/a'/1'`).
+ * - `static-deposit`: hardened child `index` of the static-deposit root (`m/8797555'/a'/3'`).
+ *   (`m/8797555'/a'/2'` is upstream's deposit key; single-use deposits bind leaf keys, so it is
+ *   unused.)
+ */
+type SparkLeafKey = {
+  readonly type: "leaf";
+  readonly leafId: string;
+} | {
+  readonly type: "static-deposit";
+  readonly index: number;
+};
+/**
+ * Any private key a FROST or key-spend job can use. `received` decrypts `ciphertext` with the
+ * identity key (ECIES) to recover the 32-byte key the sender sealed for this identity.
+ */
+type SparkKey = SparkLeafKey | {
+  readonly type: "received";
+  readonly ciphertext: Uint8Array;
+};
+/** The user's FROST signing commitment pair: 33-byte compressed `hiding` and `binding` points. */
+type SigningCommitment = {
+  readonly hiding: Uint8Array;
+  readonly binding: Uint8Array;
+};
+/** An operator's FROST identifier and its commitment for one signing session. */
+type OperatorCommitment = {
+  /** 64 lowercase hex characters; the operator's FROST identifier scalar. */
+  readonly identifier: string;
+  readonly commitment: SigningCommitment;
+};
+/**
+ * A user-side FROST signing job. `commitment` must come from {@link SparkSigner.newCommitments}; it
+ * is consumed by the call — signing once removes it, so a second job carrying the same commitment
+ * fails even if the first signing attempt itself failed.
+ */
+type FrostSignJob = {
+  readonly key: SparkKey;
+  readonly target: SigningTarget;
+  /** 33-byte compressed combined (aggregate) verifying key for this session. */
+  readonly verifyingKey: Uint8Array;
+  readonly commitment: SigningCommitment;
+  readonly operatorCommitments: ReadonlyArray<OperatorCommitment>;
+  /** Optional 33-byte adaptor point; omit or leave empty for plain signatures. */
+  readonly adaptorPublicKey?: Uint8Array;
+};
+/** Aggregation of the user's share (obtained from {@link SparkSigner.signFrost}) with the SOs'. */
+type FrostAggregateJob = {
+  readonly key: SparkKey;
+  readonly target: SigningTarget;
+  readonly verifyingKey: Uint8Array;
+  readonly commitment: SigningCommitment;
+  /** The user's 32-byte signature share produced by `signFrost` for this session. */
+  readonly signatureShare: Uint8Array;
+  readonly operators: ReadonlyArray<{
+    /** 64 lowercase hex characters. */
+    readonly identifier: string;
+    readonly commitment: SigningCommitment;
+    /** The operator's 32-byte signature share. */
+    readonly signatureShare: Uint8Array;
+    /** The operator's 33-byte verifying share. */
+    readonly publicKey: Uint8Array;
+  }>;
+  readonly adaptorPublicKey?: Uint8Array;
+};
+/**
+ * A statement the signer signs with the identity key. The signer computes every digest itself from
+ * the full statement content — there is no sign-arbitrary-hash method.
+ *
+ * - `so-challenge`: `challenge` is a serialized `spark_authn.Challenge`; decoded strictly (no unknown
+ *   fields), its `publicKey` must equal the identity public key as a curve point.
+ * - `ssp-challenge`: `protectedChallenge` is the base64 SSP session challenge; decoded bytes must be
+ *   an `ssp_authn.ProtectedChallenge` (unknown fields tolerated) whose `challenge.public_key` is
+ *   the identity public key in either encoding.
+ * - `transfer-package` / `claim-package`: `package` is the serialized `spark.TransferPackage` /
+ *   `spark.ClaimPackage`; the digest is computed from the decoded message fields.
+ * - `static-deposit-claim`: the fixed-quote claim statement (`txid` in display byte order,
+ *   `sspSignature` is the SSP quote signature's decoded bytes).
+ * - `static-deposit-refund`: the refund statement; `txid`/`vout`/`amount` describe the deposit output
+ *   and `target` is the refund transaction whose sighash becomes the payload.
+ * - `watchtower-recovery`: `target` is the recovery transaction; its sighash enters the digest.
+ * - `spark-invoice`: `invoice` is a serialized `spark.SparkInvoiceFields`; signed with BIP-340.
+ * - `token-transaction`: `partialTransaction` is a serialized `spark_token.PartialTokenTransaction`;
+ *   the digest is its V3 protoreflecthash, signed with BIP-340 (upstream tokenSignatures:
+ *   SCHNORR).
+ * - `lightning-address`: a Breez LNURL-server v2 message authorizing a Lightning Address
+ *   register/unregister on `domain`; the digest is `sha256` of the canonical LF-joined message,
+ *   signed with DER ECDSA.
+ */
+type IdentityStatement = {
+  readonly kind: "so-challenge";
+  readonly challenge: Uint8Array;
+} | {
+  readonly kind: "ssp-challenge";
+  readonly protectedChallenge: string;
+} | {
+  readonly kind: "transfer-package";
+  readonly transferId: string;
+  readonly package: Uint8Array;
+} | {
+  readonly kind: "claim-package";
+  readonly transferId: string;
+  readonly package: Uint8Array;
+} | {
+  readonly kind: "static-deposit-claim";
+  readonly network: SparkNetwork;
+  /** The deposit transaction id in display (big-endian) byte order. */
+  readonly txid: Uint8Array;
+  readonly vout: number;
+  readonly creditAmountSats: number;
+  /** The SSP's quote signature bytes — the payload the statement hashes. */
+  readonly sspSignature: Uint8Array;
+} | {
+  readonly kind: "static-deposit-refund";
+  readonly network: SparkNetwork;
+  /** The deposit transaction id in display (big-endian) byte order. */
+  readonly txid: Uint8Array;
+  readonly vout: number;
+  readonly amount: number;
+  readonly target: SigningTarget;
+} | {
+  readonly kind: "watchtower-recovery";
+  readonly network: SparkNetwork;
+  readonly leafId: string;
+  readonly target: SigningTarget;
+} | {
+  readonly kind: "spark-invoice";
+  readonly invoice: Uint8Array;
+} | {
+  readonly kind: "token-transaction";
+  /** Serialized `spark_token.PartialTokenTransaction`. */
+  readonly partialTransaction: Uint8Array;
+} | LightningAddressStatement;
+/** A signing operator the signer builds per-operator packages for. */
+type SparkOperator = {
+  readonly id: number;
+  /** 64 lowercase hex characters; the FROST identifier scalar. */
+  readonly identifier: string;
+  /** 33-byte compressed secp256k1 public key the packages are ECIES-encrypted to. */
+  readonly identityPublicKey: Uint8Array;
+};
+/**
+ * PrepareTransfer input: every leaf gets a fresh random recipient key; the operator-visible tweak
+ * is `old − new` (mod n) split by VSS and encrypted per operator. Each leaf's `secret_cipher` is
+ * sealed to that leaf's own receiver identity key, so one transfer can pay several receivers. The
+ * operator set and threshold are the signer's construction-time values — a call cannot retarget the
+ * tweak shares to other keys.
+ */
+type PrepareTransferRequest = {
+  readonly transferId: string;
+  readonly leaves: ReadonlyArray<{
+    readonly leafId: string;
+    readonly key: SparkLeafKey;
+    /** 33-byte compressed identity public key the leaf's `secret_cipher` is encrypted to. */
+    readonly receiverIdentityPublicKey: Uint8Array;
+  }>;
+};
+/** One leaf's transfer output, mirroring the per-leaf fields of `spark.SendLeafKeyTweak`. */
+type PreparedTransferLeaf = {
+  readonly leafId: string;
+  /** The fresh 33-byte leaf key the receiver will claim with. */
+  readonly newPublicKey: Uint8Array;
+  /** ECIES(receiverIdentityPublicKey) ciphertext sealing the new 32-byte leaf key. */
+  readonly secretCipher: Uint8Array;
+  /** 64-byte compact ECDSA signature over `sha256(leafId ‖ transferId ‖ secretCipher)`. */
+  readonly signature: Uint8Array;
+};
+/**
+ * Sender transfer preparation. `operatorPackages` maps each operator's 64-hex identifier to the
+ * ECIES-encrypted `spark.SendLeafKeyTweaks` it can open.
+ */
+type PreparedTransfer = {
+  /** SO identifier → ECIES(identityPublicKey) of the serialized `spark.SendLeafKeyTweaks`. */
+  readonly operatorPackages: Record<string, Uint8Array>;
+  readonly leaves: ReadonlyArray<PreparedTransferLeaf>;
+};
+/**
+ * PrepareClaim input: each leaf's `secretCipher` is the sender's ECIES-encrypted leaf key. The
+ * tweak shares are split across and sealed to the signer's construction-time operator set.
+ */
+type PrepareClaimRequest = {
+  readonly transferId: string;
+  readonly leaves: ReadonlyArray<{
+    readonly leafId: string;
+    readonly secretCipher: Uint8Array;
+  }>;
+};
+/**
+ * Receiver claim preparation. `operatorPackages` maps each operator's identifier to the
+ * ECIES-encrypted `spark.ClaimLeafKeyTweaks` it can open.
+ */
+type PreparedClaim = {
+  /** SO identifier → ECIES(identityPublicKey) of the serialized `spark.ClaimLeafKeyTweaks`. */
+  readonly operatorPackages: Record<string, Uint8Array>;
+};
+/**
+ * Lightning receive preparation. The preimage is generated inside the signer and never leaves;
+ * `paymentHash` is `sha256(preimage)` and `operatorPackages` maps each operator's identifier to the
+ * ECIES-encrypted `spark.SecretShare` it can open (the V2 store-preimage-share payload).
+ */
+type PreparedLightningReceive = {
+  readonly paymentHash: Uint8Array;
+  /** SO identifier → ECIES(identityPublicKey) of the serialized `spark.SecretShare`. */
+  readonly operatorPackages: Record<string, Uint8Array>;
+};
+/**
+ * A Lightning HTLC timeout spend: the sequence-lock-leaf path the sender takes once the refund
+ * transaction's HTLC output has confirmed for `LIGHTNING_HTLC_SEQUENCE` blocks. `transaction` is
+ * the unsigned single-input sweep (`constructHtlcSenderSpend`'s `txBytes`); the signer rebuilds the
+ * HTLC output script from `paymentHash`, `hashLockPublicKey` and its own identity key, checks the
+ * input's sequence satisfies the CSV, sighashes the sequence-lock leaf and BIP-340-signs.
+ */
+type HtlcTimeoutSignRequest = {
+  readonly transaction: Uint8Array;
+  /** Index of the input spending the HTLC output — 0 for the single-input sweep shape. */
+  readonly inputIndex: number;
+  /** The HTLC output's amount in sats. */
+  readonly prevoutAmountSats: number;
+  /** 32-byte payment hash locking the HTLC's hash-lock leaf. */
+  readonly paymentHash: Uint8Array;
+  /** 33-byte compressed public key on the hash-lock leaf (the SSP identity for sends). */
+  readonly hashLockPublicKey: Uint8Array;
+};
+/**
+ * The static-deposit claim request: which key index and the statement the SSP expects signed. The
+ * deposit secret is sealed to the SSP identity bound at signer construction — a call cannot
+ * redirect it to another key.
+ */
+type StaticDepositClaimRequest = {
+  /** Static-deposit child index (upstream uses 0 for the current deposit address). */
+  readonly index: number;
+  readonly statement: Extract<IdentityStatement, {
+    readonly kind: "static-deposit-claim";
+  }>;
+};
+/**
+ * The signer's identity surface. Private keys never leave the signer; every method returns protocol
+ * values only (Uint8Array, strings, safe integers, plain objects) so an implementation may live
+ * behind a binding boundary.
+ */
+type SparkSigner = {
+  /** The 33-byte compressed secp256k1 identity public key. */
+  readonly identityPublicKey: () => Promise<Uint8Array>;
+  /** Compressed public keys for the given private-key descriptors, in order. */
+  readonly publicKeys: (keys: ReadonlyArray<SparkLeafKey>) => Promise<ReadonlyArray<Uint8Array>>;
+  /**
+   * Public keys of ECIES-sealed ("received") keys: each ciphertext is decrypted with the identity
+   * key (must yield 32 bytes) and its compressed public key returned.
+   */
+  readonly receivedPublicKeys: (ciphertexts: ReadonlyArray<Uint8Array>) => Promise<ReadonlyArray<Uint8Array>>;
+  /**
+   * Generates `count` FROST commitment pairs (at most 256). The secret nonces are stored inside the
+   * signer keyed by the commitment pair and consumed by {@link signFrost}.
+   */
+  readonly newCommitments: (count: number) => Promise<ReadonlyArray<SigningCommitment>>;
+  /**
+   * User-side FROST signature shares, one 32-byte share per job in order (at most 256 jobs). Each
+   * job's commitment is consumed — removed before signing, so reuse fails even after an error.
+   */
+  readonly signFrost: (jobs: ReadonlyArray<FrostSignJob>) => Promise<ReadonlyArray<Uint8Array>>;
+  /**
+   * Aggregated 64-byte FROST (Schnorr) signatures, one per job in order. The user verifying share
+   * is derived from the resolved private key inside the signer.
+   */
+  readonly aggregateFrost: (jobs: ReadonlyArray<FrostAggregateJob>) => Promise<ReadonlyArray<Uint8Array>>;
+  /**
+   * Signs a protocol statement with the identity key. DER ECDSA for protocol statements, BIP-340
+   * for `spark-invoice`.
+   */
+  readonly signIdentity: (statement: IdentityStatement) => Promise<Uint8Array>;
+  /**
+   * BIP-341 key-path signature over the target's sighash: the resolved key is tweaked with
+   * `TapTweak` (empty merkle root) and BIP-340-signed with fresh aux randomness. Returns 64 bytes.
+   */
+  readonly signKeySpend: (key: SparkKey, target: SigningTarget) => Promise<Uint8Array>;
+  /**
+   * BIP-342 script-path signature over the sequence-lock leaf of a Lightning HTLC output — the
+   * sender's timeout path. The signer rebuilds the leaf and the prevout's HTLC output script from
+   * `paymentHash`, `hashLockPublicKey` and its own identity key, requires the input's sequence to
+   * satisfy the `LIGHTNING_HTLC_SEQUENCE` CSV, then BIP-340-signs with the identity key. Accepts
+   * only the single-input sweep shape; returns 64 bytes.
+   */
+  readonly signHtlcTimeout: (request: HtlcTimeoutSignRequest) => Promise<Uint8Array>;
+  /** Builds the sender transfer package: per-leaf fresh keys, VSS tweaks, per-SO ECIES packages. */
+  readonly prepareTransfer: (request: PrepareTransferRequest) => Promise<PreparedTransfer>;
+  /** Builds the receiver claim package: VSS `received − LEAF{leafId}` tweaks, per-SO ECIES packages. */
+  readonly prepareClaim: (request: PrepareClaimRequest) => Promise<PreparedClaim>;
+  /** Generates a preimage, splits it by VSS and encrypts one `SecretShare` per operator. */
+  readonly prepareLightningReceive: () => Promise<PreparedLightningReceive>;
+  /**
+   * The static-deposit claim: the child secret key ECIES-sealed to the SSP identity bound at signer
+   * construction (the same scheme as transfer leaf secret ciphers) plus the identity-key DER
+   * signature over the claim statement. The plaintext key never leaves the signer.
+   */
+  readonly claimStaticDeposit: (request: StaticDepositClaimRequest) => Promise<{
+    readonly encryptedSecretKey: Uint8Array;
+    readonly signature: Uint8Array;
+  }>;
+  /** Wipes every private key, cached secret and unused nonce, then rejects all further calls. */
+  readonly dispose: () => void;
+};
+//#endregion
+export { StaticDepositClaimRequest as _, OperatorCommitment as a, PreparedClaim as c, PreparedTransferLeaf as d, SigningCommitment as f, SparkSigner as g, SparkOperator as h, IdentityStatement as i, PreparedLightningReceive as l, SparkLeafKey as m, FrostSignJob as n, PrepareClaimRequest as o, SparkKey as p, HtlcTimeoutSignRequest as r, PrepareTransferRequest as s, FrostAggregateJob as t, PreparedTransfer as u, SigningTarget as v };

package/package.json

@@ -1,6 +1,100 @@
 {
   "name": "@qntx/spark",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Spark Bitcoin L2 protocol for TypeScript: platform-neutral client, signer and crypto-backend interfaces.",
+  "keywords": [
+    "bitcoin",
+    "l2",
+    "lightning",
+    "spark"
+  ],
+  "homepage": "https://github.com/qntx/spark#readme",
+  "bugs": {
+    "url": "https://github.com/qntx/spark/issues"
+  },
+  "license": "Apache-2.0",
+  "author": "QuantX <x@qntx.org>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/qntx/spark.git",
+    "directory": "packages/spark"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./crypto": {
+      "types": "./dist/crypto.d.mts",
+      "import": "./dist/crypto.mjs",
+      "default": "./dist/crypto.mjs"
+    },
+    "./lnurl": {
+      "types": "./dist/lnurl.d.mts",
+      "import": "./dist/lnurl.mjs",
+      "default": "./dist/lnurl.mjs"
+    },
+    "./server": {
+      "types": "./dist/server.d.mts",
+      "import": "./dist/server.mjs",
+      "default": "./dist/server.mjs"
+    },
+    "./signer": {
+      "types": "./dist/signer.d.mts",
+      "import": "./dist/signer.mjs",
+      "default": "./dist/signer.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "dev": "vp pack --watch",
+    "test": "vp test",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.src.json",
+    "check:pkg": "vp pack && publint && attw --pack . --profile esm-only",
+    "smoke:hermes": "bun run build && bun scripts/hermes-smoke.ts",
+    "prepublishOnly": "vp run build"
+  },
+  "dependencies": {
+    "@bufbuild/protobuf": "^2.16.0",
+    "@connectrpc/connect": "^2.2.0",
+    "@connectrpc/connect-web": "^2.2.0",
+    "@noble/ciphers": "2.4.0",
+    "@noble/curves": "^2.4.0",
+    "@noble/hashes": "^2.4.0",
+    "@scure/base": "^2.4.0",
+    "@scure/bip32": "^2.4.0",
+    "@scure/btc-signer": "^2.4.1"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "0.18.5",
+    "@qntx/spark-wasm": "0.1.0",
+    "@qntx/tsconfig": "1.0.1",
+    "@types/node": "26.6.5",
+    "publint": "0.3.25",
+    "typescript": "7.0.2",
+    "undici": "8.12.2",
+    "vite-plus": "1.2.0"
+  },
+  "devEngines": {
+    "packageManager": {
+      "name": "bun",
+      "version": "1.4.0",
+      "onFail": "ignore"
+    }
+  },
+  "engines": {
+    "node": ">=20.19.0"
+  }
+}