@arkade-os/sdk 0.4.66 → 0.4.68

package/dist/{index-e7LYXk1d.d.cts → index-jouvy8FD.d.ts}

@@ -1,5 +1,5 @@
-import { bb as ContractHandler, q as RelativeTimelock, bn as Discoverable, V as VtxoScript, r as TapLeafScript, cS as TapscriptDeriving } from './index-uUE_uQPn.cjs';
-import { D as DefaultVtxo, a as DelegateVtxo } from './delegate-YXupcWWJ.cjs';
+import { bg as ContractHandler, s as RelativeTimelock, bs as Discoverable, V as VtxoScript, t as TapLeafScript, d5 as TapscriptDeriving } from './index-C7RZCfoY.js';
+import { D as DefaultVtxo, a as DelegateVtxo } from './delegate-AomVWxO_.js';
 import { Bytes } from '@scure/btc-signer/utils.js';
 
 /**
@@ -114,77 +114,79 @@ declare namespace VHTLC {
         unilateralRefundDelay: RelativeTimelock;
         unilateralRefundWithoutReceiverDelay: RelativeTimelock;
         /**
-         * Optional non-interactive claim leaf: `server` plus a covenant-tweaked
-         * emulator co-signer, pinned to `receiverPkScript`. Lets the receiver's
-         * claim be pushed by the emulator without the receiver being online.
+         * The emulator covenant leaves, ALL OR NOTHING. Present, this adds the
+         * three non-interactive leaves the emulator co-signs under a covenant
+         * pinning the payout to a pre-committed destination:
+         *
+         *  - `nonInteractiveClaim`: `server` + a covenant-tweaked emulator
+         *    co-signer, paying `receiverPkScript` — the receiver's claim can
+         *    be pushed without the receiver being online.
+         *  - `nonInteractiveRefund`: `server` + `receiver` + a covenant-tweaked
+         *    emulator co-signer, paying `senderPkScript`, no timelock — lets
+         *    server and receiver release the refund the moment they agree the
+         *    swap has failed, and recoverable even if the sender's own key is
+         *    lost, since no OTHER refund-side leaf survives that.
+         *  - `nonInteractiveRefundWithoutReceiver`: `server` + the SAME
+         *    covenant-tweaked co-signer as `nonInteractiveRefund`, paying
+         *    `senderPkScript` after `refundLocktime` — the only refund tier
+         *    needing no participant signature at all, so a sender who funded
+         *    a lockup and vanished is refundable through it alone.
+         *
+         * WHY ONE FLAG AND NOT A SWITCH PER LEAF. The three are one mechanism
+         * — the same emulator key, the same `enforcePayTo` covenant pointed
+         * at a per-role destination — and they protect opposite directions of
+         * the same swap, so no real configuration wants a subset. A subset
+         * would cost, not buy: every optional leaf multiplies the tree shapes
+         * a counterparty must derive to verify an address (nothing on the
+         * wire says which leaves a quote carries), so per-leaf toggling turns
+         * one address comparison into a combinatorial guess. All-or-nothing
+         * keeps the shape count at two: suite, or no suite.
+         *
+         * Leaf order fixes the taproot merkle root, so the suite is appended
+         * after the six signature leaves in a fixed order (claim, refund,
+         * timelocked refund) and a script built with this option NEVER
+         * collides with one built without it — which is what makes "did this
+         * quote opt in" a question an address comparison answers.
+         *
+         * STABLE PER RELEASE: what this option builds does not change within
+         * a published SDK version. A future covenant leaf joins the suite
+         * only behind a NEW option, so re-deriving a lockup with the SDK
+         * that quoted it reproduces its address byte-for-byte.
          */
-        nonInteractiveClaim?: {
-            receiverPkScript: Bytes;
+        nonInteractiveParameters?: {
+            /**
+             * The emulator service's public key, 32-byte x-only or 33-byte
+             * compressed. ONE key, tweaked per covenant destination, becomes
+             * the co-signer of every leaf in the suite — the leaves share it
+             * structurally, and BIP-341 tapscript sighashes committing to the
+             * tapleaf hash are what keep a signature for one leaf from
+             * replaying against another.
+             */
             emulatorPubkey: Bytes;
             /**
-             * OPT-IN: also require the claim to pay at least these amounts.
-             *
-             * The covenant's default bound is conservation (`out >= in`) — see
-             * {@link enforcePayTo} for why a quote is normally not the
-             * covenant's business. This is the escape hatch for a consumer that
-             * wants the quote enforced in script rather than at its own
-             * admission layer.
-             *
-             * ADDITIVE, NEVER A REPLACEMENT. The conservation bound stays. On
-             * its own, `out >= quoted` leaves everything ABOVE the quote
-             * unconstrained, so an overfunded lockup's surplus could be routed
-             * anywhere by whoever assembles the spend — trading an underfunding
-             * hole for a skimming one. Both bounds together admit neither.
-             *
-             * WHAT IT COSTS, and it is not only opcodes:
-             *
-             *  - THE ADDRESS BECOMES A FUNCTION OF THE QUOTE. These amounts
-             *    compile into the leaf, hence the emulator key, hence the
-             *    pkScript. A re-quote is a different address, and cannot be
-             *    applied to a lockup already funded.
-             *  - AN UNDERFUNDED LOCKUP BECOMES UNCLAIMABLE. Its only exit is the
-             *    refund path, which waits out the CLTV. That is the intended
-             *    incentive and it lands on whoever misfunded — but it converts
-             *    "claim the short amount now and settle up" into "wait for the
-             *    timelock".
-             *
-             * Omit for the default. Omitting leaves every script byte unchanged,
-             * so contracts already funded keep their addresses.
+             * Where the claim covenant pays: the receiver's own P2TR
+             * pkScript, 34 bytes.
+             */
+            receiverPkScript: Bytes;
+            /**
+             * Where BOTH refund covenants pay: the sender's own P2TR
+             * pkScript, 34 bytes. One destination shared by both refund
+             * leaves, so they cannot diverge on where a refund goes.
              */
-            strict?: {
-                /** Sats the claim must pay. Positive. */
-                amount: bigint;
-                /**
-                 * Asset base units the claim must pay.
-                 *
-                 * Required iff {@link VHTLC.Options.asset} is set, and refused
-                 * otherwise. Strict-on-sats-only against an asset-denominated
-                 * contract would pin the sat CARRIER and say nothing about the
-                 * asset that is the actual amount — half-enforcement that reads
-                 * like enforcement, which is the failure this option exists to
-                 * avoid rather than introduce.
-                 */
-                assetAmount?: bigint;
-            };
-        };
-        /**
-         * Optional non-interactive refund leaf: `server` + `receiver` + a
-         * covenant-tweaked emulator co-signer, pinned to `senderPkScript`, no
-         * timelock. Every OTHER refund-side leaf in this contract requires
-         * the sender's own signature — if the sender permanently loses that
-         * key, none of them are reachable. This leaf is the one exception:
-         * it needs neither the sender's presence nor their key, so funds
-         * remain recoverable to the sender's pre-committed address even
-         * then. It still needs the receiver (unlike `nonInteractiveClaim`,
-         * which needs only server + emulator) — deliberately: this is what
-         * lets server + receiver release the refund immediately, the moment
-         * they agree the swap has failed, rather than making the sender wait
-         * out `refundLocktime` the way {@link Script.refundWithoutReceiver}
-         * does.
-         */
-        nonInteractiveRefund?: {
             senderPkScript: Bytes;
-            emulatorPubkey: Bytes;
+            /**
+             * LEGACY REBUILD ONLY — never for a new lockup.
+             *
+             * `"preTimelockedRefund"` builds the suite WITHOUT its timelocked
+             * refund leaf: the shape every emulator-covenant lockup funded
+             * before that leaf shipped carries. Lockups already funded in that
+             * shape keep it permanently — a leaf cannot be retrofitted onto an
+             * address already committed — so re-deriving such a lockup (to
+             * spend it, or to verify an old quote's address) needs this. A new
+             * lockup that omits the leaf gives up the one refund tier needing
+             * nobody, for nothing.
+             */
+            legacy?: "preTimelockedRefund";
         };
         /**
          * Optional: denominate this contract in an Arkade ASSET rather than in
@@ -256,6 +258,8 @@ declare namespace VHTLC {
         readonly nonInteractiveClaimArkadeScript?: Bytes;
         readonly nonInteractiveRefundScript?: string;
         readonly nonInteractiveRefundArkadeScript?: Bytes;
+        readonly nonInteractiveRefundWithoutReceiverScript?: string;
+        readonly nonInteractiveRefundWithoutReceiverArkadeScript?: Bytes;
         protected constructor(options: Options, preimageCondition: (hash: Bytes) => Bytes);
         /** Return the collaborative claim tapleaf script. */
         claim(): TapLeafScript;
@@ -273,6 +277,59 @@ declare namespace VHTLC {
         nonInteractiveClaim(): [TapLeafScript, Bytes];
         /** Return the non-interactive refund tapleaf script as well as the ArkadeScript. */
         nonInteractiveRefund(): [TapLeafScript, Bytes];
+        /**
+         * Return the timelocked non-interactive refund tapleaf and its ArkadeScript.
+         *
+         * SPENDING THIS LEAF, CONCRETELY — confirmed from this SDK's own
+         * emulator client and covenant-spend builder ({@link
+         * EmulatorProvider} in `src/providers/emulator.ts`, and {@link
+         * ArkadeTransactionBuilder} in `src/arkade/contract.ts`), which is
+         * the general machinery every covenant leaf in this file goes
+         * through:
+         *
+         *  1. Build the ark tx spending this leaf (this method's {@link
+         *     TapLeafScript} as `tapLeafScript`, this script's {@link
+         *     VtxoScript.encode} as `tapTree`), plus its checkpoint tx.
+         *  2. Attach the ArkadeScript this method returns to the spent
+         *     input via an `EmulatorPacket` (type 1) — `{ vin, script:
+         *     <this ArkadeScript>, witness: <empty> }`, empty because the
+         *     script pushes its own input/output index with
+         *     `PUSHCURRENTINPUTINDEX` rather than reading one from the
+         *     witness — wrapped in an `Extension` OP_RETURN output on the
+         *     ark tx.
+         *  3. Attach the spent input's OWN creating ark tx as `PrevArkTx` on
+         *     input 0 — required so the emulator can resolve that input's
+         *     prevout pkScript/value; it does not otherwise have them.
+         *  4. POST the (base64-PSBT) ark tx and checkpoint(s) as `{ arkTx,
+         *     checkpointTxs }` to the emulator's `POST /v1/tx`.
+         *
+         * THE COVENANT CHECK the emulator runs against that ArkadeScript —
+         * `enforcePayTo(senderPkScript)`, see that function above — is: the
+         * output at this SAME input's index is a v1 P2TR output paying
+         * `senderPkScript`, with a value at least the input's. Only on that
+         * check passing does the emulator sign for `nirCosigner` (the
+         * `emulatorPubkey` tweaked by this ArkadeScript's hash); the
+         * response carries the fully co-signed `signedArkTx` and
+         * `signedCheckpointTxs` — `ArkadeTransactionBuilder.send()`'s own
+         * comment on this path: "the emulator executes the arkade script
+         * and finalizes with arkd" — no separate call to arkd is made by
+         * this SDK for a covenant spend.
+         * Neither `server` nor `receiver` play any part in that check: this
+         * leaf's tapscript still requires `server`'s own signature
+         * alongside `nirCosigner`'s (see the class doc above), but that is
+         * consensus-level multisig, not something the covenant enforces.
+         *
+         * NOT SPENDABLE UNTIL `refundLocktime` MATURES — the tapscript's
+         * `OP_CHECKLOCKTIMEVERIFY` is arkd's concern, not the emulator's;
+         * the emulator will happily co-sign an immature spend and arkd will
+         * then refuse it. A block-height-typed `refundLocktime` (below the
+         * standard height/timestamp boundary this SDK names
+         * `CLTV_HEIGHT_THRESHOLD`, 500,000,000, in
+         * `src/contracts/handlers/helpers.ts`) is refused by arkd for a
+         * forfeit-eligible leaf independent of maturity — use a
+         * seconds-typed (absolute Unix timestamp) value.
+         */
+        nonInteractiveRefundWithoutReceiver(): [TapLeafScript, Bytes];
     }
     /**
      * Virtual Hash Time Lock Contract (VHTLC) script implementation.
@@ -286,17 +343,34 @@ declare namespace VHTLC {
      * - **unilateralClaim**: Receiver can claim unilaterally after delay
      * - **unilateralRefund**: Sender and receiver can refund unilaterally after delay
      * - **unilateralRefundWithoutReceiver**: Sender can refund unilaterally after delay
-     * - **nonInteractiveClaim** (optional): server + emulator can push the
-     *   receiver's claim, pinned to a pre-committed destination
-     * - **nonInteractiveRefund** (optional): server + receiver + emulator
-     *   can push the sender's refund immediately, no timelock, pinned to a
-     *   pre-committed destination — recoverable even if the sender's own key
-     *   is lost
+     * - **nonInteractiveClaim** (with `nonInteractiveParameters`): server + emulator
+     *   can push the receiver's claim, pinned to a pre-committed destination
+     * - **nonInteractiveRefund** (with `nonInteractiveParameters`): server + receiver
+     *   + emulator can push the sender's refund immediately, no timelock,
+     *   pinned to a pre-committed destination — recoverable even if the
+     *   sender's own key is lost
+     * - **nonInteractiveRefundWithoutReceiver** (with `nonInteractiveParameters`):
+     *   server + emulator can push the sender's refund after `refundLocktime`,
+     *   pinned to a pre-committed destination — the only refund tier needing
+     *   no participant signature at all
      *
      * See {@link ScriptV2} for the current recommended construction — same
      * leaf ladder, same options shape, an added length check on the claim
      * preimage. This class is unchanged and stays available as-is.
      *
+     * **Pre-existing limitation: the `vhtlc` contract handler registers none
+     * of the covenant leaves.** `nonInteractiveParameters` builds on this class
+     * exactly as it does on {@link ScriptV2} — both extend the same
+     * `BaseScript` where those leaves are constructed. But the `vhtlc`
+     * contract handler (`src/contracts/handlers/vhtlc.ts`) round-trips none
+     * of them: its params type carries no covenant fields, and
+     * `createScript` only ever builds the six signature-only leaves. A V1
+     * script built with the covenant suite therefore compiles and can
+     * be funded, but cannot be registered as a `vhtlc` contract — the
+     * handler would derive a different (six-leaf) script for the same
+     * params and `ContractManager` refuses the mismatch. Register through
+     * the `vhtlc-v2` handler instead, which round-trips the suite.
+     *
      * @example
      * ```typescript
      * const vhtlc = new VHTLC.Script({
@@ -367,9 +441,9 @@ declare const VHTLCContractHandler: ContractHandler<VHTLCContractParams, VHTLC.S
  * The eight mandatory fields are `VHTLCContractParams` verbatim — the two
  * script versions take the same {@link VHTLC.Options}, so a divergent shape
  * here would be a difference with no cause. What V1's handler has no field for
- * is the two optional covenant leaves, and those are exactly what the swap
- * corridor's lockup carries, so leaving them out would make this handler unable
- * to round-trip the contract it exists to serve.
+ * is the emulator covenant suite, and that is exactly what the swap corridor's
+ * lockup carries, so leaving it out would make this handler unable to
+ * round-trip the contract it exists to serve.
  */
 interface VHTLCV2ContractParams {
     sender: Uint8Array;
@@ -391,20 +465,18 @@ interface VHTLCV2ContractParams {
         /** The asset group index within that genesis transaction. */
         groupIndex: number;
     };
-    /** @see VHTLC.Options.nonInteractiveClaim */
-    nonInteractiveClaim?: {
+    /**
+     * The emulator covenant suite, all or nothing — mirrors {@link
+     * VHTLC.Options.nonInteractiveParameters} exactly, including the legacy selector:
+     * a row funded before the timelocked refund leaf shipped round-trips with
+     * `legacy: "preTimelockedRefund"` and re-derives its eight-leaf shape.
+     */
+    nonInteractiveParameters?: {
         receiverPkScript: Uint8Array;
         emulatorPubkey: Uint8Array;
-        /** @see VHTLC.Options.nonInteractiveClaim.strict */
-        strict?: {
-            amount: bigint;
-            assetAmount?: bigint;
-        };
-    };
-    /** @see VHTLC.Options.nonInteractiveRefund */
-    nonInteractiveRefund?: {
         senderPkScript: Uint8Array;
-        emulatorPubkey: Uint8Array;
+        /** @see VHTLC.Options.nonInteractiveParameters.legacy */
+        legacy?: "preTimelockedRefund";
     };
 }
 /**
@@ -426,21 +498,22 @@ interface VHTLCV2ContractParams {
  * the same ScriptV2 the two uses would fight over one row.
  *
  * **Which leaves this offers, and why the set is smaller than the ladder.**
- * ScriptV2 has eight leaves; a wallet holding ONE of the two participant keys
+ * ScriptV2 has nine leaves; a wallet holding ONE of the two participant keys
  * can satisfy four of them, and offering a leaf whose signature the caller
  * cannot produce is worse than offering fewer — it turns a refusal into a
  * transaction that gets built and then rejected.
  *
- * | leaf                              | needs                          | offered |
- * |-----------------------------------|--------------------------------|---------|
- * | `claim`                           | receiver + server, preimage    | yes, to the receiver |
- * | `refund`                          | sender + receiver + server     | no — needs the counterparty live |
- * | `refundWithoutReceiver`           | sender + server, CLTV          | yes, to the sender |
- * | `unilateralClaim`                 | receiver, CSV                  | yes, to the receiver |
- * | `unilateralRefund`                | sender + receiver, CSV         | no — needs the counterparty live |
- * | `unilateralRefundWithoutReceiver` | sender, CSV                    | yes, to the sender |
- * | `nonInteractiveClaim`             | server + emulator              | no — the wallet holds neither key |
- * | `nonInteractiveRefund`            | server + receiver + emulator   | no — the wallet holds neither key |
+ * | leaf                                  | needs                          | offered |
+ * |---------------------------------------|--------------------------------|---------|
+ * | `claim`                               | receiver + server, preimage    | yes, to the receiver |
+ * | `refund`                              | sender + receiver + server     | no — needs the counterparty live |
+ * | `refundWithoutReceiver`               | sender + server, CLTV          | yes, to the sender |
+ * | `unilateralClaim`                     | receiver, CSV                  | yes, to the receiver |
+ * | `unilateralRefund`                    | sender + receiver, CSV         | no — needs the counterparty live |
+ * | `unilateralRefundWithoutReceiver`     | sender, CSV                    | yes, to the sender |
+ * | `nonInteractiveClaim`                 | server + emulator              | no — the wallet holds neither key |
+ * | `nonInteractiveRefund`                | server + receiver + emulator   | no — the wallet holds neither key |
+ * | `nonInteractiveRefundWithoutReceiver` | server + emulator, CLTV        | no — the wallet holds neither key |
  *
  * The two omitted interactive leaves are the same two the `vhtlc` handler
  * omits, for the same reason: `refund` and `unilateralRefund` both need the