fix(utxo-coredao): clarifications from the coredao team

TICKET: BTC-1578

Author: davidkaplanbitgo

modules/utxo-coredao/src/transaction.ts

@@ -1,7 +1,66 @@
 // Source: https://docs.coredao.org/docs/Learn/products/btc-staking/design
-export const CORE_DAO_TESTNET_CHAIN_ID = Buffer.alloc(2, 0x1115);
-export const CORE_DAO_MAINNET_CHAIN_ID = Buffer.alloc(2, 0x1116);
-export const CORE_DAO_SATOSHI_PLUS_IDENTIFIER = Buffer.alloc(4, 0x5341542b);
+export const CORE_DAO_TESTNET_CHAIN_ID = Buffer.from('045b', 'hex');
+export const CORE_DAO_MAINNET_CHAIN_ID = Buffer.from('045c', 'hex');
+export const CORE_DAO_SATOSHI_PLUS_IDENTIFIER = Buffer.from('5341542b', 'hex');
+// https://github.com/bitcoin/bitcoin/blob/5961b23898ee7c0af2626c46d5d70e80136578d3/src/script/script.h#L47
+const OP_RETURN_IDENTIFIER = Buffer.from('6a', 'hex');
+const OP_PUSHDATA1_IDENTIFIER = Buffer.from('4c', 'hex');
+const OP_PUSHDATA2_IDENTIFIER = Buffer.from('4d', 'hex');
+const OP_PUSHDATA4_IDENTIFIER = Buffer.from('4e', 'hex');
+
+export function encodeTimelock(timelock: number): Buffer {
+  const buff = Buffer.alloc(4);
+  buff.writeUInt32LE(timelock);
+  return buff;
+}
+
+export function decodeTimelock(buffer: Buffer): number {
+  if (buffer.length !== 4) {
+    throw new Error('Invalid timelock buffer length');
+  }
+  return buffer.readUInt32LE();
+}
+
+export function encodeOpReturnLength(length: number): Buffer {
+  /**
+   * Any bytes with lengths smaller than 0x4c (76) is pushed with 1 byte equal to the size (byte[10] -> 10 + byte[10]; byte[70] -> 70 + byte[70])
+   * Any bytes bigger than or equal to 0x4c is pushed by using 0x4c (ie. OP_PUSHDATA) followed by the length followed by the data (byte[80] -> OP_PUSHDATA + 80 + byte[80])
+   * Any bytes with length bigger than 255 uses 0x4d (OP_PUSHDATA2)
+   * Any bytes with length bigger than 65535 (0xffff) uses 0x4e (OP_PUSHDATA4)
+   */
+  if (length < 76) {
+    return Buffer.alloc(1, length);
+  } else if (length < 255) {
+    return Buffer.concat([OP_PUSHDATA1_IDENTIFIER, Buffer.alloc(1, length)]);
+  } else if (length < 65535) {
+    const buff = Buffer.alloc(2);
+    buff.writeUInt16BE(length);
+    return Buffer.concat([OP_PUSHDATA2_IDENTIFIER, buff]);
+  } else {
+    const buff = Buffer.alloc(4);
+    buff.writeUInt32BE(length);
+    return Buffer.concat([OP_PUSHDATA4_IDENTIFIER, buff]);
+  }
+}
+
+/**
+ * Decode the length of an OP_RETURN output script
+ * @param buffer
+ * @returns { length: number, offset: number } Length of the OP_RETURN output script and the offset
+ */
+export function decodeOpReturnLength(buffer: Buffer): { length: number; offset: number } {
+  if (buffer[0] < 0x4c) {
+    return { length: buffer[0], offset: 1 };
+  } else if (buffer[0] === 0x4c) {
+    return { length: buffer[1], offset: 2 };
+  } else if (buffer[0] === 0x4d) {
+    return { length: buffer.readUInt16BE(1), offset: 3 };
+  } else if (buffer[0] === 0x4e) {
+    return { length: buffer.readUInt32BE(1), offset: 5 };
+  } else {
+    throw new Error('Invalid length');
+  }
+}
 
 type BaseParams = {
   version: number;
@@ -43,7 +102,7 @@ export function createCoreDaoOpReturnOutputScript({
    * LENGTH: which represents the total byte length after the OP_RETURN opcode. Note that all data has to be pushed with its appropriate size byte(s). [1]
    * Satoshi Plus Identifier: (SAT+) 4 bytes
    * Version: (0x01) 1 byte
-   * Chain ID: (0x1115 for Core Testnet and 0x1116 for Core Mainnet) 2 bytes
+   * Chain ID: (0x045b (1115) for Core Testnet and 0x045c (1116) for Core Mainnet) 2 bytes
    * Delegator: The Core address to receive rewards, 20 bytes
    * Validator: The Core validator address to stake to, 20 bytes
    * Fee: Fee for relayer, 1 byte, range [0,255], measured in CORE
@@ -88,36 +147,25 @@ export function createCoreDaoOpReturnOutputScript({
   if ('timelock' in rest && (rest.timelock < 0 || rest.timelock > 4294967295)) {
     throw new Error('Invalid timelock - out of range');
   }
-  const timelockBuffer = 'timelock' in rest ? Buffer.alloc(4, rest.timelock).reverse() : Buffer.from([]);
 
-  const totalLength =
+  // encode the number into a 4-byte buffer
+  // if timelock is provided, write it into 32-bit little-endian
+  const timelockBuffer = 'timelock' in rest ? encodeTimelock(rest.timelock) : Buffer.from([]);
+
+  const lengthBuffer = encodeOpReturnLength(
     CORE_DAO_SATOSHI_PLUS_IDENTIFIER.length +
-    versionBuffer.length +
-    chainId.length +
-    delegator.length +
-    validator.length +
-    feeBuffer.length +
-    redeemScriptBuffer.length +
-    timelockBuffer.length +
-    // This is to account for the LENGTH byte
-    1;
-
-  // If the length is  >= 0x4c (76), we need to use the OP_PUSHDATA (0x4c) opcode and then the length
-  const totalLengthBuffer =
-    totalLength >= 76
-      ? Buffer.concat([
-          Buffer.from([0x4c]),
-          Buffer.alloc(
-            1,
-            // This is to account for the extra OP_PUSHDATA byte
-            totalLength + 1
-          ),
-        ])
-      : Buffer.alloc(1, totalLength);
+      versionBuffer.length +
+      chainId.length +
+      delegator.length +
+      validator.length +
+      feeBuffer.length +
+      redeemScriptBuffer.length +
+      timelockBuffer.length
+  );
 
   return Buffer.concat([
-    Buffer.from([0x6a]),
-    totalLengthBuffer,
+    OP_RETURN_IDENTIFIER,
+    lengthBuffer,
     CORE_DAO_SATOSHI_PLUS_IDENTIFIER,
     versionBuffer,
     chainId,

modules/utxo-coredao/test/unit/transaction.ts

@@ -3,6 +3,8 @@ import {
   CORE_DAO_MAINNET_CHAIN_ID,
   CORE_DAO_SATOSHI_PLUS_IDENTIFIER,
   createCoreDaoOpReturnOutputScript,
+  decodeTimelock,
+  encodeTimelock,
 } from '../../src';
 import { testutil } from '@bitgo/utxo-lib';
 
@@ -19,6 +21,9 @@ describe('OP_RETURN', function () {
     'hex'
   );
   const validTimelock = 800800;
+  // https://docs.coredao.org/docs/Learn/products/btc-staking/design#op_return-output-1
+  const defaultScript =
+    '6a4c505341542b01045bde60b7d0e6b758ca5dd8c61d377a2c5f1af51ec1a9e209f5ea0036c8c2f41078a3cebee57d8a47d501041f5e0e66b17576a914c4b8ae927ff2b9ce218e20bf06d425d6b68424fd88ac';
 
   describe('createCoreDaoOpReturnOutputScript', function () {
     it('should throw if invalid parameters are passed', function () {
@@ -97,8 +102,8 @@ describe('OP_RETURN', function () {
       assert.strictEqual(script[0], 0x6a);
       // Make sure that the length of the script matches what is in the buffer
       assert.strictEqual(
-        // We do not count the OP_RETURN opcode
-        script.length - 1,
+        // We do not count the OP_RETURN opcode or the bytes for the length
+        script.length - 2,
         script[1]
       );
     });
@@ -118,8 +123,8 @@ describe('OP_RETURN', function () {
       // Make sure that the length of the script matches what is in the buffer
       assert.strictEqual(script[1], 0x4c);
       assert.strictEqual(
-        // We do not count the OP_RETURN opcode
-        script.length - 1,
+        // We do not count the OP_RETURN opcode or the length + pushbytes
+        script.length - 3,
         script[2]
       );
       // Satoshi plus identifier
@@ -155,8 +160,8 @@ describe('OP_RETURN', function () {
       assert.strictEqual(script[0], 0x6a);
       // Make sure that the length of the script matches what is in the buffer
       assert.strictEqual(
-        // We do not count the OP_RETURN opcode
-        script.length - 1,
+        // We do not count the OP_RETURN opcode or the length
+        script.length - 2,
         script[1]
       );
       // Satoshi plus identifier
@@ -172,10 +177,59 @@ describe('OP_RETURN', function () {
       // Make sure that the fee is correct
       assert.strictEqual(script[49], validFee);
       // Make sure that the redeemScript is correct
+      assert.deepStrictEqual(script.subarray(50, 54).toString('hex'), encodeTimelock(validTimelock).toString('hex'));
+      assert.deepStrictEqual(decodeTimelock(script.subarray(50, 54)), validTimelock);
+    });
+
+    it('should recreate the example OP_RETURN correctly', function () {
       assert.deepStrictEqual(
-        script.subarray(50, 54).reverse().toString('hex'),
-        Buffer.alloc(4, validTimelock).toString('hex')
+        createCoreDaoOpReturnOutputScript({
+          version: 1,
+          chainId: Buffer.from('045b', 'hex'),
+          delegator: Buffer.from('de60b7d0e6b758ca5dd8c61d377a2c5f1af51ec1', 'hex'),
+          validator: Buffer.from('a9e209f5ea0036c8c2f41078a3cebee57d8a47d5', 'hex'),
+          fee: 1,
+          redeemScript: Buffer.from('041f5e0e66b17576a914c4b8ae927ff2b9ce218e20bf06d425d6b68424fd88ac', 'hex'),
+        }).toString('hex'),
+        // Source: https://docs.coredao.org/docs/Learn/products/btc-staking/design#op_return-output-1
+        defaultScript
       );
     });
+
+    it('should create a OP_RETURN with the extra long length identifier', function () {
+      const redeemScriptPushdata2 = Buffer.alloc(265, 0);
+      const scriptPushdata2 = createCoreDaoOpReturnOutputScript({
+        version: validVersion,
+        chainId: validChainId,
+        delegator: validDelegator,
+        validator: validValidator,
+        fee: validFee,
+        redeemScript: redeemScriptPushdata2,
+      });
+
+      // Make sure that the first byte is the OP_RETURN opcode
+      assert.strictEqual(scriptPushdata2[0], 0x6a);
+      // Make sure that there is the OP_PUSHDATA2 identifier
+      assert.strictEqual(scriptPushdata2[1], 0x4d);
+      // We do not count the OP_RETURN opcode or the bytes for the length
+      assert.strictEqual(scriptPushdata2.readInt16BE(2), scriptPushdata2.length - 4);
+
+      const redeemScriptPushdata4 = Buffer.alloc(65540, 0);
+      const scriptPushdata4 = createCoreDaoOpReturnOutputScript({
+        version: validVersion,
+        chainId: validChainId,
+        delegator: validDelegator,
+        validator: validValidator,
+        fee: validFee,
+        redeemScript: redeemScriptPushdata4,
+      });
+
+      // Make sure that the first byte is the OP_RETURN opcode
+      assert.strictEqual(scriptPushdata4[0], 0x6a);
+      // Make sure that there is the OP_PUSHDATA4 identifier
+      assert.strictEqual(scriptPushdata4[1], 0x4e);
+      // We do not count the OP_RETURN opcode or the bytes for the length
+      assert.strictEqual(scriptPushdata4.readInt32BE(2), scriptPushdata4.length - 6);
+    });
   });
 });