@atomicfinance/bitcoin-dlc-provider 3.6.0 → 4.0.0

package/.yalc/@node-dlc/messaging/lib/messages/OracleAttestation.ts

@@ -0,0 +1,292 @@
+import { BufferReader, BufferWriter } from '@node-dlc/bufio';
+import { math, verify } from 'bip-schnorr';
+
+import { MessageType } from '../MessageType';
+import { IDlcMessage } from './DlcMessage';
+import { OracleAnnouncement } from './OracleAnnouncement';
+
+/**
+ * Oracle attestation providing signatures over an outcome value.
+ * This represents the oracle's actual attestation to a specific outcome.
+ * Updated to match rust-dlc specification with 2-byte count prefixes.
+ *
+ * An attestation from an oracle providing signatures over an outcome value.
+ * This is what the oracle publishes when they want to attest to a specific outcome.
+ */
+export class OracleAttestation implements IDlcMessage {
+  public static type = MessageType.OracleAttestation;
+
+  /**
+   * Deserializes an oracle_attestation message
+   * @param buf
+   */
+  public static deserialize(buf: Buffer): OracleAttestation {
+    const instance = new OracleAttestation();
+    const reader = new BufferReader(buf);
+
+    reader.readBigSize(); // read type
+    instance.length = reader.readBigSize();
+
+    // Detect format: old rust-dlc 0.4.0 (no event_id) vs new rust-dlc (with event_id)
+    const currentPos = reader.position;
+
+    try {
+      // Try reading as new format (with event_id)
+      const eventIdLength = reader.readBigSize();
+
+      // If event ID length is reasonable (0-100 bytes), assume new format
+      if (eventIdLength >= BigInt('0') && eventIdLength <= BigInt('100')) {
+        if (eventIdLength === BigInt('0')) {
+          instance.eventId = '';
+        } else {
+          const eventIdBuf = reader.readBytes(Number(eventIdLength));
+          instance.eventId = eventIdBuf.toString();
+        }
+        instance.oraclePubkey = reader.readBytes(32);
+      } else {
+        // Event ID length is unreasonable, probably old format without event_id
+        reader.position = currentPos;
+        instance.eventId = ''; // Default empty event ID for old format
+        instance.oraclePubkey = reader.readBytes(32);
+      }
+    } catch (error) {
+      // If reading fails, assume old format without event_id
+      reader.position = currentPos;
+      instance.eventId = ''; // Default empty event ID for old format
+      instance.oraclePubkey = reader.readBytes(32);
+    }
+
+    const numSignatures = reader.readUInt16BE();
+
+    for (let i = 0; i < numSignatures; i++) {
+      const signature = reader.readBytes(64);
+      instance.signatures.push(signature);
+    }
+
+    // Handle both rust-dlc format (with u16 count prefix) and DLCSpecs format (no count prefix)
+    // Try to detect format by checking if next 2 bytes look like a reasonable outcome count
+    if (!reader.eof) {
+      const currentPos = reader.position;
+
+      try {
+        // Try reading as rust-dlc format (with u16 count prefix)
+        const numOutcomes = reader.readUInt16BE();
+
+        // Validate that this looks like a reasonable count
+        // If it's > 1000 or the remaining bytes can't accommodate this many outcomes,
+        // it's probably not a count prefix
+        const remainingBytes = reader.buffer.length - reader.position;
+
+        if (
+          numOutcomes > 0 &&
+          numOutcomes <= 1000 &&
+          remainingBytes >= numOutcomes * 2
+        ) {
+          // Looks like rust-dlc format with u16 count prefix
+          for (let i = 0; i < numOutcomes; i++) {
+            const outcomeLen = reader.readBigSize();
+            const outcomeBuf = reader.readBytes(Number(outcomeLen));
+            instance.outcomes.push(outcomeBuf.toString());
+          }
+        } else {
+          // Reset and try DLCSpecs format (no count prefix)
+          reader.position = currentPos;
+          while (!reader.eof) {
+            const outcomeLen = reader.readBigSize();
+            const outcomeBuf = reader.readBytes(Number(outcomeLen));
+            instance.outcomes.push(outcomeBuf.toString());
+          }
+        }
+      } catch (error) {
+        // If reading as rust-dlc format fails, reset and try DLCSpecs format
+        reader.position = currentPos;
+        while (!reader.eof) {
+          const outcomeLen = reader.readBigSize();
+          const outcomeBuf = reader.readBytes(Number(outcomeLen));
+          instance.outcomes.push(outcomeBuf.toString());
+        }
+      }
+    }
+
+    return instance;
+  }
+
+  /**
+   * The type for oracle_attestation message. oracle_attestation = 55400
+   */
+  public type = OracleAttestation.type;
+
+  public length: bigint;
+
+  /** The identifier of the announcement. */
+  public eventId: string;
+
+  /** The public key of the oracle (32 bytes, x-only). */
+  public oraclePubkey: Buffer;
+
+  /** The signatures over the event outcome (64 bytes each, Schnorr format). */
+  public signatures: Buffer[] = [];
+
+  /** The set of strings representing the outcome value. */
+  public outcomes: string[] = [];
+
+  /**
+   * Validates the oracle attestation according to rust-dlc specification.
+   * This includes validating signatures and ensuring consistency with announcement.
+   * @param announcement The corresponding oracle announcement for validation (optional)
+   * @throws Will throw an error if validation fails
+   */
+  public validate(announcement?: OracleAnnouncement): void {
+    // Basic structure validation
+    if (this.signatures.length !== this.outcomes.length) {
+      throw new Error('Number of signatures must match number of outcomes');
+    }
+
+    if (this.signatures.length === 0) {
+      throw new Error('Must have at least one signature and outcome');
+    }
+
+    // Validate event ID
+    if (!this.eventId || this.eventId.length === 0) {
+      throw new Error('Event ID cannot be empty');
+    }
+
+    // Validate oracle public key format
+    if (!this.oraclePubkey || this.oraclePubkey.length !== 32) {
+      throw new Error('Oracle public key must be 32 bytes (x-only format)');
+    }
+
+    // Validate signature formats
+    this.signatures.forEach((sig, index) => {
+      if (!sig || sig.length !== 64) {
+        throw new Error(
+          `Signature at index ${index} must be 64 bytes (Schnorr format)`,
+        );
+      }
+    });
+
+    // Validate outcomes are not empty
+    this.outcomes.forEach((outcome, index) => {
+      if (!outcome || outcome.length === 0) {
+        throw new Error(`Outcome at index ${index} cannot be empty`);
+      }
+    });
+
+    // Verify signatures over outcomes using tagged hash
+    this.signatures.forEach((sig, index) => {
+      const outcome = this.outcomes[index];
+      try {
+        const msg = math.taggedHash('DLC/oracle/attestation/v0', outcome);
+        verify(this.oraclePubkey, msg, sig);
+      } catch (error) {
+        throw new Error(
+          `Invalid signature for outcome "${outcome}" at index ${index}: ${error.message}`,
+        );
+      }
+    });
+
+    // If announcement is provided, validate consistency
+    if (announcement) {
+      this.validateAgainstAnnouncement(announcement);
+    }
+  }
+
+  /**
+   * Validates the attestation against the corresponding oracle announcement.
+   * This ensures the attestation is consistent with the original announcement.
+   * @param announcement The oracle announcement to validate against
+   * @throws Will throw an error if validation fails
+   */
+  private validateAgainstAnnouncement(announcement: OracleAnnouncement): void {
+    // Validate oracle public key matches announcement
+    if (!this.oraclePubkey.equals(announcement.oraclePubkey)) {
+      throw new Error('Oracle public key must match announcement');
+    }
+
+    // Validate event ID matches
+    if (this.eventId !== announcement.getEventId()) {
+      throw new Error('Event ID must match announcement');
+    }
+
+    // Validate that the number of signatures matches the number of nonces in announcement
+    const announcementNonces = announcement.getNonces();
+    if (this.signatures.length !== announcementNonces.length) {
+      throw new Error(
+        'Number of signatures must match number of nonces in announcement',
+      );
+    }
+
+    // Extract nonces from signatures (first 32 bytes) and compare with announcement nonces
+    // This validates that the signatures were created using the committed nonces
+    this.signatures.forEach((sig, index) => {
+      const nonceFromSig = sig.slice(0, 32);
+      const expectedNonce = announcementNonces[index];
+
+      if (!nonceFromSig.equals(expectedNonce)) {
+        throw new Error(
+          `Signature nonce mismatch at index ${index}: signature was not created with announced nonce`,
+        );
+      }
+    });
+  }
+
+  /**
+   * Returns the nonces used by the oracle to sign the event outcome.
+   * This is used for finding the matching oracle announcement.
+   * The nonce is extracted from the first 32 bytes of each signature.
+   */
+  public getNonces(): Buffer[] {
+    return this.signatures.map((sig) => sig.slice(0, 32));
+  }
+
+  /**
+   * Converts oracle_attestation to JSON
+   */
+  public toJSON(): OracleAttestationJSON {
+    return {
+      type: this.type,
+      eventId: this.eventId,
+      oraclePubkey: this.oraclePubkey.toString('hex'),
+      signatures: this.signatures.map((sig) => sig.toString('hex')),
+      outcomes: this.outcomes,
+    };
+  }
+
+  /**
+   * Serializes the oracle_attestation message into a Buffer
+   */
+  public serialize(): Buffer {
+    const writer = new BufferWriter();
+    writer.writeBigSize(this.type);
+
+    const dataWriter = new BufferWriter();
+    dataWriter.writeBigSize(this.eventId.length);
+    dataWriter.writeBytes(Buffer.from(this.eventId));
+    dataWriter.writeBytes(this.oraclePubkey);
+    dataWriter.writeUInt16BE(this.signatures.length);
+
+    for (const signature of this.signatures) {
+      dataWriter.writeBytes(signature);
+    }
+
+    // Write outcomes with u16 count prefix (matching rust-dlc format)
+    dataWriter.writeUInt16BE(this.outcomes.length);
+    for (const outcome of this.outcomes) {
+      dataWriter.writeBigSize(outcome.length);
+      dataWriter.writeBytes(Buffer.from(outcome));
+    }
+
+    writer.writeBigSize(dataWriter.size);
+    writer.writeBytes(dataWriter.toBuffer());
+
+    return writer.toBuffer();
+  }
+}
+
+export interface OracleAttestationJSON {
+  type: number;
+  eventId: string;
+  oraclePubkey: string;
+  signatures: string[];
+  outcomes: string[];
+}

package/.yalc/@node-dlc/messaging/lib/messages/OracleEvent.ts

@@ -0,0 +1,250 @@
+import { BufferReader, BufferWriter } from '@node-dlc/bufio';
+
+import { MessageType } from '../MessageType';
+import { getTlv } from '../serialize/getTlv';
+import { IDlcMessage } from './DlcMessage';
+import {
+  DigitDecompositionEventDescriptor,
+  EnumEventDescriptor,
+  EventDescriptor,
+  IDigitDecompositionEventDescriptorJSON,
+  IEnumEventDescriptorJSON,
+} from './EventDescriptor';
+
+/**
+ * Oracle event containing information about an event and the way that the
+ * oracle will attest to it. Updated to be rust-dlc compliant.
+ *
+ * For users to be able to create DLCs based on a given event, they also
+ * need to obtain information about the oracle and the time at which it
+ * plans on releasing a signature over the event outcome. OracleEvent
+ * messages contain such information, which includes:
+ *   - the nonce(s) that will be used to sign the event outcome(s)
+ *   - the earliest time (UTC) at which it plans on releasing a signature
+ *     over the event outcome, in epoch seconds
+ *   - the event descriptor
+ *   - the event ID which can be a name or categorization associated with
+ *     the event by the oracle
+ */
+export class OracleEvent implements IDlcMessage {
+  public static type = MessageType.OracleEvent;
+
+  /**
+   * Creates an OracleEvent from JSON data
+   * @param json JSON object representing oracle event
+   */
+  // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types, @typescript-eslint/no-explicit-any
+  public static fromJSON(json: any): OracleEvent {
+    const instance = new OracleEvent();
+
+    // Parse oracle nonces array
+    const nonces = json.oracleNonces || json.oracle_nonces || [];
+    instance.oracleNonces = nonces.map((nonce: string) =>
+      Buffer.from(nonce, 'hex'),
+    );
+
+    instance.eventMaturityEpoch =
+      json.eventMaturityEpoch || json.event_maturity_epoch || 0;
+
+    // Parse event descriptor
+    instance.eventDescriptor = EventDescriptor.fromJSON(
+      json.eventDescriptor || json.event_descriptor,
+    );
+
+    instance.eventId = json.eventId || json.event_id || '';
+
+    return instance;
+  }
+
+  /**
+   * Deserializes an oracle_event message
+   * @param buf
+   */
+  public static deserialize(buf: Buffer): OracleEvent {
+    const instance = new OracleEvent();
+    const reader = new BufferReader(buf);
+
+    reader.readBigSize(); // read type
+    instance.length = reader.readBigSize();
+    const nonceCount = reader.readUInt16BE();
+
+    for (let i = 0; i < nonceCount; i++) {
+      instance.oracleNonces.push(reader.readBytes(32));
+    }
+
+    instance.eventMaturityEpoch = reader.readUInt32BE();
+    instance.eventDescriptor = EventDescriptor.deserialize(getTlv(reader));
+    const eventIdLength = reader.readBigSize();
+    const eventIdBuf = reader.readBytes(Number(eventIdLength));
+    instance.eventId = eventIdBuf.toString();
+
+    return instance;
+  }
+
+  /**
+   * The type for oracle_event message. oracle_event = 55330
+   */
+  public type = OracleEvent.type;
+
+  public length: bigint;
+
+  /** The nonces that the oracle will use to attest to the event outcome. */
+  public oracleNonces: Buffer[] = [];
+
+  /** The expected maturity of the contract (Unix timestamp). */
+  public eventMaturityEpoch: number;
+
+  /** The description of the event. */
+  public eventDescriptor: EventDescriptor;
+
+  /** The ID of the event. */
+  public eventId: string;
+
+  /**
+   * Validates correctness of all fields in the message according to rust-dlc specification.
+   * This includes validating that the number of nonces matches the expected count for the event type.
+   * https://github.com/discreetlogcontracts/dlcspecs/blob/master/Oracle.md
+   * @throws Will throw an error if validation fails
+   */
+  public validate(): void {
+    // Validate event maturity epoch
+    if (this.eventMaturityEpoch < 0) {
+      throw new Error('eventMaturityEpoch must be greater than or equal to 0');
+    }
+
+    // Validate event ID
+    if (!this.eventId || this.eventId.length === 0) {
+      throw new Error('eventId cannot be empty');
+    }
+
+    // Validate oracle nonces (must be 32 bytes each)
+    if (this.oracleNonces.length === 0) {
+      throw new Error('Must have at least one oracle nonce');
+    }
+
+    this.oracleNonces.forEach((nonce, index) => {
+      if (!nonce || nonce.length !== 32) {
+        throw new Error(`Oracle nonce at index ${index} must be 32 bytes`);
+      }
+    });
+
+    // Validate expected number of nonces based on event descriptor type
+    const expectedNbNonces = this.getExpectedNonceCount();
+
+    if (expectedNbNonces !== this.oracleNonces.length) {
+      throw new Error(
+        `OracleEvent nonce count mismatch: expected ${expectedNbNonces}, got ${this.oracleNonces.length}`,
+      );
+    }
+
+    // Validate the event descriptor itself
+    if (this.eventDescriptor instanceof DigitDecompositionEventDescriptor) {
+      this.eventDescriptor.validate();
+    }
+    // EnumEventDescriptorV0 doesn't have validation requirements beyond basic structure
+  }
+
+  /**
+   * Returns the expected number of nonces based on the event descriptor type.
+   * This matches the rust-dlc validation logic.
+   */
+  private getExpectedNonceCount(): number {
+    if (this.eventDescriptor instanceof EnumEventDescriptor) {
+      // Enum events require exactly 1 nonce
+      return 1;
+    } else if (
+      this.eventDescriptor instanceof DigitDecompositionEventDescriptor
+    ) {
+      // Digit decomposition events require nbDigits nonces, plus 1 if signed
+      const descriptor = this.eventDescriptor;
+      return descriptor.isSigned
+        ? descriptor.nbDigits + 1
+        : descriptor.nbDigits;
+    } else {
+      throw new Error('Unknown event descriptor type');
+    }
+  }
+
+  /**
+   * Returns whether this event is for enumerated outcomes.
+   */
+  public isEnumEvent(): boolean {
+    return this.eventDescriptor instanceof EnumEventDescriptor;
+  }
+
+  /**
+   * Returns whether this event is for numerical outcomes.
+   */
+  public isDigitDecompositionEvent(): boolean {
+    return this.eventDescriptor instanceof DigitDecompositionEventDescriptor;
+  }
+
+  /**
+   * Returns the event descriptor as EnumEventDescriptor if it's an enum event.
+   * @throws Error if not an enum event
+   */
+  public getEnumEventDescriptor(): EnumEventDescriptor {
+    if (!this.isEnumEvent()) {
+      throw new Error('Event is not an enum event');
+    }
+    return this.eventDescriptor as EnumEventDescriptor;
+  }
+
+  /**
+   * Returns the event descriptor as DigitDecompositionEventDescriptor if it's a numerical event.
+   * @throws Error if not a numerical event
+   */
+  public getDigitDecompositionEventDescriptor(): DigitDecompositionEventDescriptor {
+    if (!this.isDigitDecompositionEvent()) {
+      throw new Error('Event is not a digit decomposition event');
+    }
+    return this.eventDescriptor as DigitDecompositionEventDescriptor;
+  }
+
+  /**
+   * Converts oracle_event to JSON
+   */
+  public toJSON(): IOracleEventJSON {
+    return {
+      oracleNonces: this.oracleNonces.map((oracle) => oracle.toString('hex')),
+      eventMaturityEpoch: this.eventMaturityEpoch,
+      eventDescriptor: this.eventDescriptor.toJSON(),
+      eventId: this.eventId,
+    };
+  }
+
+  /**
+   * Serializes the oracle_event message into a Buffer
+   */
+  public serialize(): Buffer {
+    const writer = new BufferWriter();
+    writer.writeBigSize(this.type);
+
+    const dataWriter = new BufferWriter();
+    dataWriter.writeUInt16BE(this.oracleNonces.length);
+
+    for (const nonce of this.oracleNonces) {
+      dataWriter.writeBytes(nonce);
+    }
+
+    dataWriter.writeUInt32BE(this.eventMaturityEpoch);
+    dataWriter.writeBytes(this.eventDescriptor.serialize());
+    dataWriter.writeBigSize(this.eventId.length);
+    dataWriter.writeBytes(Buffer.from(this.eventId));
+
+    writer.writeBigSize(dataWriter.size);
+    writer.writeBytes(dataWriter.toBuffer());
+
+    return writer.toBuffer();
+  }
+}
+
+export interface IOracleEventJSON {
+  type?: number; // Made optional for rust-dlc compatibility
+  oracleNonces: string[];
+  eventMaturityEpoch: number;
+  eventDescriptor:
+    | IEnumEventDescriptorJSON
+    | IDigitDecompositionEventDescriptorJSON;
+  eventId: string;
+}

package/.yalc/@node-dlc/messaging/lib/messages/OracleEventContainer.ts

@@ -0,0 +1,89 @@
+import { BufferReader, BufferWriter } from '@node-dlc/bufio';
+
+import { MessageType } from '../MessageType';
+import { getTlv } from '../serialize/getTlv';
+import { IDlcMessage } from './DlcMessage';
+import { OracleAnnouncement } from './OracleAnnouncement';
+import { OracleAttestation } from './OracleAttestation';
+
+/**
+ * OracleEventContainer contains information about the oracles to be used in
+ * executing a DLC.
+ */
+export class OracleEventContainer implements IDlcMessage {
+  public static type = MessageType.OracleEventContainer;
+
+  /**
+   * Deserializes an oracle_info_v0 message
+   * @param buf
+   */
+  public static deserialize(buf: Buffer): OracleEventContainer {
+    const instance = new OracleEventContainer();
+    const reader = new BufferReader(buf);
+
+    reader.readBigSize(); // read type
+    instance.length = reader.readBigSize();
+
+    const oracleNameLength = reader.readBigSize();
+    const oracleNameBuf = reader.readBytes(Number(oracleNameLength));
+    instance.oracleName = oracleNameBuf.toString();
+
+    const uriLength = reader.readBigSize();
+    const uriBuf = reader.readBytes(Number(uriLength));
+    instance.uri = uriBuf.toString();
+
+    instance.announcement = OracleAnnouncement.deserialize(getTlv(reader));
+
+    instance.attestation = OracleAttestation.deserialize(getTlv(reader));
+
+    const outcomeLength = reader.readBigSize();
+    const outcomeBuf = reader.readBytes(Number(outcomeLength));
+    instance.outcome = outcomeBuf.toString();
+
+    return instance;
+  }
+
+  /**
+   * The type for oracle_info_v0 message. oracle_info_v0 = 42770
+   */
+  public type = OracleEventContainer.type;
+
+  public length: bigint;
+
+  public oracleName: string;
+
+  public uri: string;
+
+  public announcement: OracleAnnouncement;
+
+  public attestation: OracleAttestation;
+
+  public outcome: string;
+
+  public validate(): void {
+    this.announcement.validate();
+  }
+
+  /**
+   * Serializes the oracle_info_v0 message into a Buffer
+   */
+  public serialize(): Buffer {
+    const writer = new BufferWriter();
+    writer.writeBigSize(this.type);
+
+    const dataWriter = new BufferWriter();
+    dataWriter.writeBigSize(this.oracleName.length);
+    dataWriter.writeBytes(Buffer.from(this.oracleName));
+    dataWriter.writeBigSize(this.uri.length);
+    dataWriter.writeBytes(Buffer.from(this.uri));
+    dataWriter.writeBytes(this.announcement.serialize());
+    dataWriter.writeBytes(this.attestation.serialize());
+    dataWriter.writeBigSize(this.outcome.length);
+    dataWriter.writeBytes(Buffer.from(this.outcome));
+
+    writer.writeBigSize(dataWriter.size);
+    writer.writeBytes(dataWriter.toBuffer());
+
+    return writer.toBuffer();
+  }
+}

package/.yalc/@node-dlc/messaging/lib/messages/OracleIdentifier.ts

@@ -0,0 +1,78 @@
+import { BufferReader, BufferWriter } from '@node-dlc/bufio';
+
+import { MessageType } from '../MessageType';
+import { IDlcMessage } from './DlcMessage';
+
+export class OracleIdentifier implements IDlcMessage {
+  public static type = MessageType.OracleIdentifier;
+
+  /**
+   * Deserializes an oracle_event message
+   * @param buf
+   */
+  public static deserialize(buf: Buffer): OracleIdentifier {
+    const instance = new OracleIdentifier();
+    const reader = new BufferReader(buf);
+
+    reader.readBigSize(); // read type
+    instance.length = reader.readBigSize();
+
+    const oracleNameLength = reader.readBigSize();
+    const oracleNameBuf = reader.readBytes(Number(oracleNameLength));
+    instance.oracleName = oracleNameBuf.toString();
+    instance.oraclePubkey = reader.readBytes(32);
+
+    return instance;
+  }
+
+  /**
+   * The type for oracle_identifier message. oracle_identifier = 61472
+   */
+  public type = OracleIdentifier.type;
+
+  public length: bigint;
+
+  public oracleName: string;
+
+  public oraclePubkey: Buffer;
+
+  public validate(): void {
+    return;
+  }
+
+  /**
+   * Converts oracle_event to JSON
+   */
+  public toJSON(): IOracleIdentifierJSON {
+    return {
+      type: this.type,
+      oracleName: this.oracleName,
+      oraclePubkey: this.oraclePubkey.toString('hex'),
+    };
+  }
+
+  /**
+   * Serializes the oracle_event message into a Buffer
+   */
+  public serialize(): Buffer {
+    const writer = new BufferWriter();
+    writer.writeBigSize(this.type);
+
+    const dataWriter = new BufferWriter();
+    dataWriter.writeBigSize(this.oracleName.length);
+    dataWriter.writeBytes(Buffer.from(this.oracleName));
+
+    dataWriter.writeBytes(this.oraclePubkey);
+
+    writer.writeBigSize(dataWriter.size);
+    writer.writeBytes(dataWriter.toBuffer());
+
+    return writer.toBuffer();
+  }
+}
+
+export interface IOracleIdentifierJSON {
+  type: number;
+  oracleName: string;
+  oraclePubkey: string;
+}