@atomicfinance/bitcoin-dlc-provider 4.2.8 → 4.3.0

package/.yalc/@node-dlc/core/lib/lightning/CommitmentNumber.ts

@@ -0,0 +1,94 @@
+import { LockTime, Sequence } from '@node-dlc/bitcoin';
+import { bigFromBufBE } from '@node-dlc/bufio';
+import { sha256 } from '@node-dlc/crypto';
+
+export class CommitmentNumber {
+  /**
+   * Using the obscured commitment number, creates a Sequence with
+   * the upper byte set to 0x80 and the lower three bytes set to the
+   * upper 3 bytes of the 48-bit commitment number.
+   *
+   * The upper most byte is set to 0x80 so that the relative lock time
+   * is disabled.
+   *
+   * @param commitment commitment number to obscure
+   */
+  public static getSequence(obscurred: bigint): Sequence {
+    return new Sequence(
+      Number((BigInt(0x80) << BigInt(24)) | (obscurred >> BigInt(24))),
+    );
+  }
+
+  /**
+   * Using the obscured commitment number, creates a LockTime with
+   * the upper byte set to 0x20 and the lower three bytes set to the
+   * lower 3 bytes of the 48-bit commitment number.
+   *
+   * The uppermost byte is set to 0x20 so the LockTime uses a time
+   * based absolute locktime that has already expired.
+   *
+   * @param obscurred obscurred commitment number
+   */
+  public static getLockTime(obscurred: bigint): LockTime {
+    return new LockTime(
+      Number((BigInt(0x20) << BigInt(24)) | (obscurred & BigInt(0xffffff))),
+    );
+  }
+
+  /**
+   * Reveals the commitment number provided by the nSequence and
+   * nLockTime values. This function reverses the obscurring using the
+   * known payment base points.
+   *
+   * @param locktime
+   * @param sequence
+   */
+  public static reveal(
+    locktime: LockTime,
+    sequence: Sequence,
+    openBasePoint: Buffer,
+    acceptBasePoint: Buffer,
+  ): number {
+    const hash = CommitmentNumber.getHash(openBasePoint, acceptBasePoint);
+    const upper = BigInt(sequence.value & 0xffffff) << BigInt(24);
+    const lower = BigInt(locktime.value & 0xffffff);
+    return Number(hash ^ (upper | lower));
+  }
+
+  /**
+   * Defined in BOLT3, the obscurred commitment number is attached to the
+   * commitment transaction. The 48-bit commitment number is broken into
+   * two pieces, the lower 3-bytes are obscured in nLocketime and the
+   * upper 3-bytes are obscured in the funding input's nSequence.
+   *
+   * The obscurred commitment number is calculated as the:
+   * sha256(open_channel payment_basepoint || accept_channel payment_basepoint) ^ commitment_number
+   * @param commitment
+   * @param openBasePoint
+   * @param acceptBasePoint
+   */
+  public static obscure(
+    commitment: number,
+    openBasePoint: Buffer,
+    acceptBasePoint: Buffer,
+  ): bigint {
+    return (
+      CommitmentNumber.getHash(openBasePoint, acceptBasePoint) ^
+      BigInt(commitment)
+    );
+  }
+
+  /**
+   * Obtains the lower 6-bytes from the sha256 of the open_channel
+   * basepoint and the accept_channel basepoint.
+   * @param openBasePoint
+   * @param acceptBasePoint
+   */
+  private static getHash(
+    openBasePoint: Buffer,
+    acceptBasePoint: Buffer,
+  ): bigint {
+    const hash = sha256(Buffer.concat([openBasePoint, acceptBasePoint]));
+    return bigFromBufBE(hash.slice(hash.length - 6));
+  }
+}

package/.yalc/@node-dlc/core/lib/lightning/CommitmentSecret.ts

@@ -0,0 +1,41 @@
+import { sha256 } from '@node-dlc/crypto';
+
+export class CommitmentSecret {
+  /**
+   * Generic version of commitment secret generator as defined in
+   * BOLT3.
+   *
+   * This function works by decrementing from bits to 0. If the index
+   * number has the corresponding bit set, it flips the bit in the
+   * secret and hashes it.
+   *
+   * The natural conclusion is the first secret flips every bit and
+   * the last secret flips zero (and is thus the seed).
+   *
+   * This function can be used for generate the local per-commitment
+   * secret based on the per-commitment seed and a commitment index
+   * (in this case it) generates all 48 bits.
+   *
+   * This function can also be used to generate prior commitment
+   * secrets from a newer secret, which acts as a prefix.
+   *
+   * @param base base secret that will be used to derive from
+   * @param i secret at index I to generate
+   * @param bits bits to evaluate, default is 48
+   */
+  public static derive(base: Buffer, i: bigint, bits = 48): Buffer {
+    // intii
+    let p = Buffer.from(base);
+
+    for (let b = bits - 1; b >= 0; b--) {
+      if (i & (BigInt(1) << BigInt(b))) {
+        // flip the specified bit in the specific byte
+        const byteIndex = Math.floor(b / 8);
+        const bitIndex = b % 8;
+        p[byteIndex] = p[byteIndex] ^ (1 << bitIndex);
+        p = sha256(p);
+      }
+    }
+    return p;
+  }
+}

package/.yalc/@node-dlc/core/lib/lightning/CommitmentSecretStore.ts

@@ -0,0 +1,84 @@
+import { CommitmentSecret } from './CommitmentSecret';
+
+export type CommitmentSecretStoreItem = { index: bigint; secret: Buffer };
+
+/**
+ * Defined in BOLT3, this class compactly stored received commitment
+ * secrets from our counterparty. Without this mechanism we are required
+ * to store every commitment secret that we receive (2^48) which can be
+ * a huge amount of data at 32-bytes per secret.
+ *
+ * Instead we can use the fact that later commitment secrets act as
+ * prefixes for prior commitment secrets. We can then compactly store
+ * only the secrets we need to derive older commitment secrets.
+ */
+export class CommitmentSecretStore {
+  /**
+   * Returns the index of the least-significant bit. This is used to
+   * determine what the value at I is a prefix for.
+   * @param I commitment
+   */
+  public static calcIndex(I: bigint): number {
+    for (let i = BigInt(0); i < BigInt(48); i++) {
+      if (I & (BigInt(1) << i)) return Number(i);
+    }
+    return 48; // seed
+  }
+
+  private secrets: CommitmentSecretStoreItem[];
+
+  constructor() {
+    this.secrets = new Array(49) as CommitmentSecretStoreItem[];
+    for (let i = 0; i < this.secrets.length; i++) {
+      this.secrets[i] = { index: BigInt(0), secret: undefined };
+    }
+  }
+
+  /**
+   * Insert the commitment secret into the store and verify that the
+   * secret is able to derive all prior commitment secrets that we
+   * already know about.
+   *
+   * @param secret 32-byte secp256k1 secret
+   * @param i commitment number
+   */
+  public insert(secret: Buffer, i: bigint): void {
+    const B = CommitmentSecretStore.calcIndex(i);
+
+    // validate that the new secret allows derivation of known keys
+    // up to the new key
+    for (let b = 0; b < B; b++) {
+      const existing = this.secrets[b].secret;
+      const derived = CommitmentSecret.derive(secret, this.secrets[b].index, B);
+      if (!derived.equals(existing)) {
+        throw new Error('The secret for I is incorrect');
+      }
+    }
+
+    // update the position
+    this.secrets[Number(B)].index = i;
+    this.secrets[Number(B)].secret = secret;
+  }
+
+  /**
+   * Derives old commitment secrets from the from the compact store.
+   * Throws if we do not have the commitment secret for the specified
+   * commitment nmber.
+   * @param i derivation number starting at 2^48-1 down to zero.
+   */
+  public derive(i: bigint): Buffer {
+    for (let b = 0; b < this.secrets.length; b++) {
+      // construct a mask of the upper bits. Basically we lop off
+      // the lower b bits and then right-shift back into place
+      const mask = (BigInt(0xffffffffffff) >> BigInt(b)) << BigInt(b);
+
+      // Check if the prefix found using I & mask is one that we
+      // can use to derive our value. If not, we need to try
+      // another bit.
+      if ((i & mask) === this.secrets[b].index && this.secrets[b].secret) {
+        return CommitmentSecret.derive(this.secrets[b].secret, i, b);
+      }
+    }
+    throw new Error("Index I hasn't been received yet");
+  }
+}

package/.yalc/@node-dlc/core/lib/lightning/Htlc.ts

@@ -0,0 +1,52 @@
+import { Value } from '@node-dlc/bitcoin';
+
+import { HtlcDirection } from './HtlcDirection';
+
+/**
+ * An HTLC (hashed time-locked contract) is part of the transfer
+ * layer of the Lightning network. HTLCs are used to trustlessly offer
+ * a payment to a counterparty if they are able to provide a preimage
+ * of the hash. The offeror can claw back funds after an expiration
+ * period (absolute lock time) if the recipient is unable to provide
+ * the preimage for the contract. HTLCs are used in Lightning for both
+ * initiating payments to a peer directly and as part of forwarding
+ * payments.
+ */
+export class Htlc {
+  /**
+   * The preimage of the payment hash using SHA256.
+   */
+  public paymentPreimage: Buffer;
+
+  /**
+   * Constructs an HTLC with associated information
+   * @param htlcId Identifier for the HTLC is a counter maintained
+   * per-channel, per-peer. It starts at zero and is incremented when
+   * an HTLC is offered. This value is used when sending channel
+   * related messages to disambiguate HTLCs that may share the same
+   * preimage.
+   *
+   * @param direction Direction, from your node's perspective, that
+   * indicates if the HTLC was offered or received.
+   *
+   * @param value The value of the HTLC in millisatoshi.
+   *
+   * @param cltvExpiry The absolutely blocktime expiry of the HTLC.
+   * The value must be under 500,000,000 to ensure it is a block-based
+   * locktime. After this timeout has expired, the offeror can perform
+   * a forced resolution on-chain.
+   *
+   * @param paymentHash The 32-byte hash of the preimage. Knowledge of
+   * the preimage is irrevocable and considers payment complete.
+   */
+  constructor(
+    readonly htlcId: bigint,
+    readonly direction: HtlcDirection,
+    readonly value: Value,
+    readonly cltvExpiry: number,
+    readonly paymentHash: Buffer,
+    paymentPreimage?: Buffer,
+  ) {
+    this.paymentPreimage = paymentPreimage;
+  }
+}

package/.yalc/@node-dlc/core/lib/lightning/HtlcDirection.ts

@@ -0,0 +1,17 @@
+/**
+ * Direction, from our node's perspective, of an HTLC.
+ */
+export enum HtlcDirection {
+  /**
+   * We have offered this HTLC to pay a node directly or on behalf
+   * of a forward request.
+   */
+  Offered = 0,
+
+  /**
+   * We have accepted this HTLC from the counterparty. We may be the
+   * final hop in a chain (and would posssess) the preimage or we may
+   * be a processing hop in a sequence of payments.
+   */
+  Accepted = 1,
+}

package/.yalc/@node-dlc/core/lib/lightning/ScriptFactory.ts

@@ -0,0 +1,150 @@
+import { OpCode, Script } from '@node-dlc/bitcoin';
+import { hash160, ripemd160 } from '@node-dlc/crypto';
+
+export class ScriptFactory {
+  /**
+   * Constructs the P2MS commit script used in in the funding transaction
+   * as defined in BOLT3. The pubkeys must be sorted in lexicographical
+   * order.
+   *
+   * @param openPubKey funding_pubkey sent in open_channel
+   * @param acceptPubKey funding_pubkey sent in accept_channel
+   */
+  public static fundingScript(
+    openPubKey: Buffer,
+    acceptPubKey: Buffer,
+  ): Script {
+    const pubkeys = [openPubKey, acceptPubKey].sort((a, b) => a.compare(b));
+    return Script.p2msLock(2, ...pubkeys);
+  }
+
+  /**
+   * Constructs an revocable sequence maturing contract using the
+   * provided keys and delay. This script is used in the `to_local`
+   * output of the commmitment transaction as well as the secondary
+   * HTLC-Success and HTLC-Timeout transactions.
+   *
+   * @param revocationPubKey the revocation pubkey that has the ability
+   * to perform a penalty transaction should a revoked version of this
+   * output be spend.
+   * @param delayedPubKey the delayed pubkey spendable after the
+   * sequence delay
+   * @param toSelfDelay the sequence delay in blocks
+   */
+  public static toLocalScript(
+    revocationPubKey: Buffer,
+    delayedPubKey: Buffer,
+    toSelfDelay: number,
+  ): Script {
+    return new Script(
+            OpCode.OP_IF,
+                revocationPubKey,
+            OpCode.OP_ELSE,
+                Script.number(toSelfDelay),
+                OpCode.OP_CHECKSEQUENCEVERIFY,
+                OpCode.OP_DROP,
+                delayedPubKey,
+            OpCode.OP_ENDIF,
+            OpCode.OP_CHECKSIG,
+        ); // prettier-ignore
+  }
+
+  /**
+   * Constructs the script for an offered HTLC output of a  commitment
+   * transaction as defined in BOLT3. This enables on-chain resolution
+   * of an HTLC to the local node via the secondary HTLC-Timeout
+   * transaction. This secondary transaction is both sequence delayed
+   * and timelocked and requires signatures by both parties to prevent
+   * premature spending. The remote node can immediately resolve the
+   * transaction wit knowledge of the preimage.
+   *
+   * Revocable with witness:
+   * [revocationSig, revocationPubKey]
+   *
+   * Pay to local via the HTLC-Timeout transaction by using witness
+   * [0, remoteHtlcSig, localHtlcSig, <>]
+   *
+   * Pay to remote counterparty without delay using witness
+   * [remoteHtlcSig, preimage]
+   *
+   * @param paymentHash
+   * @param revocationPubKey
+   * @param localHtlcPubKey
+   * @param remoteHtlcPubKey
+   */
+  public static offeredHtlcScript(
+    paymentHash: Buffer,
+    revocationPubKey: Buffer,
+    localHtlcPubKey: Buffer,
+    remoteHtlcPubKey: Buffer,
+  ): Script {
+    return new Script(
+            // to remote with revocation key
+            OpCode.OP_DUP, OpCode.OP_HASH160, hash160(revocationPubKey), OpCode.OP_EQUAL,
+            OpCode.OP_IF,
+                OpCode.OP_CHECKSIG,
+            OpCode.OP_ELSE,
+                remoteHtlcPubKey, OpCode.OP_SWAP, OpCode.OP_SIZE, Script.number(32), OpCode.OP_EQUAL,
+                OpCode.OP_NOTIF,
+                    // to local via HTLC-Timeout transaction (timelocked)
+                    OpCode.OP_DROP, OpCode.OP_2, OpCode.OP_SWAP, localHtlcPubKey, OpCode.OP_2, OpCode.OP_CHECKMULTISIG,
+                OpCode.OP_ELSE,
+                    // to remote with preimage and signature
+                    OpCode.OP_HASH160, ripemd160(paymentHash), OpCode.OP_EQUALVERIFY,
+                    OpCode.OP_CHECKSIG,
+                OpCode.OP_ENDIF,
+            OpCode.OP_ENDIF,
+        ); // prettier-ignore
+  }
+
+  /**
+   * Constructs the script for a received HTLC output of a commitment
+   * transaction as defined in BOLT3. This enables on-chain resolution
+   * of an HTLC to the local node via the secondary HTLC-Success
+   * transaction. This secondary transaction is sequence delayed and
+   * thus local spends require both parties signatures. The remote
+   * node can perform a timeout of this output after the timelock
+   * expires.
+   *
+   * Revocable with witness:
+   * [revocationSig, revocationPubKey]
+   *
+   * Pay to local via the HTLC-Success transaction by using witness
+   * [0, remoteHtlcSig, localHtlcSig, preimage]
+   *
+   * Pay to remote counterparty after the CLTV expiry using witness
+   * [remoteHtlcSig, <>]
+   *
+   * @param paymentHash
+   * @param cltvExpiry
+   * @param revocationPubKey
+   * @param localHtlcPubKey
+   * @param remoteHtlcPubKey
+   */
+  public static receivedHtlcScript(
+    paymentHash: Buffer,
+    cltvExpiry: number,
+    revocationPubKey: Buffer,
+    localHtlcPubKey: Buffer,
+    remoteHtlcPubKey: Buffer,
+  ): Script {
+    return new Script(
+            // to remote with revocation key
+            OpCode.OP_DUP, OpCode.OP_HASH160, hash160(revocationPubKey), OpCode.OP_EQUAL,
+            OpCode.OP_IF,
+                OpCode.OP_CHECKSIG,
+            OpCode.OP_ELSE,
+                remoteHtlcPubKey, OpCode.OP_SWAP, OpCode.OP_SIZE, Script.number(32), OpCode.OP_EQUAL,
+                OpCode.OP_IF,
+                    // to local via HTLC-Success transaction
+                    OpCode.OP_HASH160, ripemd160(paymentHash), OpCode.OP_EQUALVERIFY,
+                    OpCode.OP_2, OpCode.OP_SWAP, localHtlcPubKey, OpCode.OP_2, OpCode.OP_CHECKMULTISIG,
+                OpCode.OP_ELSE,
+                    // to remote after cltv expiry with signature
+                    OpCode.OP_DROP, Script.number(cltvExpiry), OpCode.OP_CHECKLOCKTIMEVERIFY, OpCode.OP_DROP,
+                    OpCode.OP_CHECKSIG,
+                OpCode.OP_ENDIF,
+            OpCode.OP_ENDIF,
+        ); // prettier-ignore
+  }
+}