feat(sdk-coin-ada): add CIP-8 message builder

TICKET: COIN-4724

Author: bhavidhingra

.gitcommitscopes

@@ -1,4 +1,5 @@
 account-lib
+sdk-coin-ada
 sdk-coin-rune
 sdk-coin-sui
 sdk-core

modules/abstract-eth/test/unit/messages/eip191/eip191Message.ts

@@ -143,7 +143,7 @@ describe('EIP191 Message', () => {
       broadcastFormat.serializedSignatures.should.deepEqual(expectedSerializedSignatures);
       broadcastFormat.signers.should.deepEqual([fixtures.eip191.signer]);
       broadcastFormat.metadata!.should.deepEqual(fixtures.eip191.metadata);
-      broadcastFormat.signablePayload!.should.equal('test-signable-payload');
+      broadcastFormat.signablePayload!.should.equal('dGVzdC1zaWduYWJsZS1wYXlsb2Fk');
     });
 
     it('should throw error when broadcasting without signatures', async () => {

modules/sdk-coin-ada/src/lib/index.ts

@@ -12,3 +12,4 @@ export { StakingWithdrawBuilder } from './stakingWithdrawBuilder';
 export { StakingPledgeBuilder } from './stakingPledgeBuilder';
 export { VoteDelegationBuilder } from './voteDelegationBuilder';
 export { Utils };
+export * from './messages';

modules/sdk-coin-ada/src/lib/messages/cip8/cip8Message.ts

@@ -0,0 +1,91 @@
+import { BaseMessage, MessageOptions, MessageStandardType, Signature } from '@bitgo/sdk-core';
+import * as CardanoSL from '@emurgo/cardano-serialization-lib-nodejs';
+import { constructCSLCoseObjects, coseObjectsOutputToBuffer, createCSLSigStructure } from './utils';
+
+/**
+ * Implementation of Message for CIP8 standard
+ */
+export class Cip8Message extends BaseMessage {
+  constructor(options: MessageOptions) {
+    super({
+      ...options,
+      type: MessageStandardType.CIP8,
+    });
+  }
+
+  /**
+   * Validates required fields and returns common setup objects
+   * @private
+   */
+  private validateAndGetCommonSetup() {
+    if (!this.payload) {
+      throw new Error('Payload is required to build a CIP8 message');
+    }
+    if (!this.signers || this.signers.length === 0) {
+      throw new Error('A signer address is required to build a CIP8 message');
+    }
+
+    let cslAddress: CardanoSL.Address;
+    try {
+      cslAddress = CardanoSL.Address.from_bech32(this.signers[0]);
+    } catch (error) {
+      // Convert string errors to proper Error objects
+      if (typeof error === 'string') {
+        throw new Error(`Invalid signer address: ${error}`);
+      }
+      throw error;
+    }
+
+    const addressCborBytes = cslAddress.to_bytes();
+
+    return { addressCborBytes };
+  }
+
+  /**
+   * Returns the hash of the CIP-8 prefixed message
+   */
+  async getSignablePayload(): Promise<string | Buffer> {
+    if (!this.signablePayload) {
+      this.signablePayload = this.buildSignablePayload();
+    }
+    return this.signablePayload;
+  }
+
+  /**
+   * Builds the signable payload for a CIP8 message
+   * @returns The signable payload as a Buffer
+   */
+  buildSignablePayload(): string | Buffer {
+    const { addressCborBytes } = this.validateAndGetCommonSetup();
+    const { sigStructureCborBytes } = createCSLSigStructure(addressCborBytes, this.payload);
+    return Buffer.from(sigStructureCborBytes);
+  }
+
+  getBroadcastableSignatures(): Signature[] {
+    if (!this.signatures.length) {
+      return [];
+    }
+
+    const signature = this.signatures[0].signature;
+    const publicKeyHex = this.signatures[0].publicKey.pub;
+
+    const { addressCborBytes } = this.validateAndGetCommonSetup();
+    const { protectedHeaderCborBytes, payloadBytes } = createCSLSigStructure(addressCborBytes, this.payload);
+
+    const coseObjectsOutput = constructCSLCoseObjects(
+      protectedHeaderCborBytes,
+      payloadBytes,
+      signature,
+      CardanoSL.PublicKey.from_bytes(Buffer.from(publicKeyHex, 'hex'))
+    );
+    const coseObjectsBuffer = coseObjectsOutputToBuffer(coseObjectsOutput);
+    return [
+      {
+        signature: coseObjectsBuffer,
+        publicKey: {
+          pub: publicKeyHex,
+        },
+      },
+    ];
+  }
+}

modules/sdk-coin-ada/src/lib/messages/cip8/cip8MessageBuilder.ts

@@ -0,0 +1,72 @@
+import { Cip8Message } from './cip8Message';
+import { BaseCoin as CoinConfig } from '@bitgo/statics';
+import {
+  BaseMessageBuilder,
+  BroadcastableMessage,
+  deserializeSignatures,
+  IMessage,
+  MessageStandardType,
+} from '@bitgo/sdk-core';
+
+/**
+ * Builder for CIP-8 messages
+ */
+export class Cip8MessageBuilder extends BaseMessageBuilder {
+  /**
+   * Base constructor.
+   * @param _coinConfig BaseCoin from statics library
+   */
+  public constructor(_coinConfig: Readonly<CoinConfig>) {
+    super(_coinConfig, MessageStandardType.CIP8);
+  }
+
+  /**
+   * Build a signable message using the CIP-8 standard
+   * with previously set input and metadata
+   * @returns A signable message
+   */
+  public async build(): Promise<IMessage> {
+    try {
+      if (!this.payload) {
+        throw new Error('Message payload must be set before building the message');
+      }
+      return new Cip8Message({
+        coinConfig: this.coinConfig,
+        payload: this.payload,
+        signatures: this.signatures,
+        signers: this.signers,
+        metadata: {
+          ...this.metadata,
+          encoding: 'utf8',
+        },
+      });
+    } catch (err) {
+      if (err instanceof Error) {
+        throw err;
+      }
+      throw new Error('Failed to build CIP-8 message');
+    }
+  }
+
+  /**
+   * Parse a broadcastable message back into a message
+   * @param broadcastMessage The broadcastable message to parse
+   * @returns The parsed message
+   */
+  public async fromBroadcastFormat(broadcastMessage: BroadcastableMessage): Promise<IMessage> {
+    const { type, payload, serializedSignatures, signers, metadata } = broadcastMessage;
+    if (type !== MessageStandardType.CIP8) {
+      throw new Error(`Invalid message type, expected ${MessageStandardType.CIP8}`);
+    }
+    return new Cip8Message({
+      coinConfig: this.coinConfig,
+      payload,
+      signatures: deserializeSignatures(serializedSignatures),
+      signers,
+      metadata: {
+        ...metadata,
+        encoding: 'utf8',
+      },
+    });
+  }
+}

modules/sdk-coin-ada/src/lib/messages/cip8/index.ts

@@ -0,0 +1,2 @@
+export * from './cip8Message';
+export * from './cip8MessageBuilder';

modules/sdk-coin-ada/src/lib/messages/cip8/utils.ts

@@ -0,0 +1,92 @@
+import { Buffer } from 'buffer';
+import * as CSL from '@emurgo/cardano-serialization-lib-nodejs';
+import { Decoder, Encoder } from 'cbor';
+
+// Helper function to convert a Uint8Array or Buffer to a hex string
+export function bytesToHex(bytes: Uint8Array | Buffer): string {
+  return Buffer.from(bytes).toString('hex');
+}
+
+export interface CSLSigStructureOutput {
+  sigStructureCborBytes: Uint8Array;
+  protectedHeaderCborBytes: Uint8Array;
+  payloadBytes: Buffer;
+}
+
+export interface CSLCoseObjectsOutput {
+  manualCoseSign1Hex: string;
+  manualCoseKeyHex: string;
+}
+
+/**
+ * Creates the CSL signature structure for off-chain message signing.
+ *
+ * @param addressCborBytes - The CBOR bytes of the CSL address.
+ * @param message - The message to be signed.
+ * @returns An object containing the signature structure CBOR bytes, protected header CBOR bytes, and payload bytes.
+ */
+export function createCSLSigStructure(addressCborBytes: Uint8Array, message: string): CSLSigStructureOutput {
+  // Payload
+  const payloadBytes = Buffer.from(message, 'utf-8');
+
+  // Protected Header
+  const protectedHeaderMap = new Map<number | string, any>();
+  protectedHeaderMap.set(1, -8); // Algorithm ID: EdDSA
+  protectedHeaderMap.set('address', Buffer.from(addressCborBytes));
+  const protectedHeaderCborBytes = Encoder.encode(protectedHeaderMap);
+
+  // Sig_structure
+  const sigStructureArray: any[] = [
+    'Signature1',
+    Buffer.from(protectedHeaderCborBytes),
+    Buffer.from([]), // Empty external_aad
+    Buffer.from(payloadBytes),
+  ];
+  const sigStructureCborBytes = Encoder.encode(sigStructureArray);
+
+  return { sigStructureCborBytes, protectedHeaderCborBytes, payloadBytes };
+}
+
+// COSE objects construction function
+export function constructCSLCoseObjects(
+  protectedHeaderCborBytes: Uint8Array,
+  payloadBytes: Buffer,
+  cslSignatureBytes: Uint8Array,
+  paymentPubKey: CSL.PublicKey
+): CSLCoseObjectsOutput {
+  // COSE_Sign1 Construction
+  const unprotectedHeadersMap = new Map<string, any>();
+  unprotectedHeadersMap.set('hashed', false);
+  const coseSign1Array: any[] = [
+    Buffer.from(protectedHeaderCborBytes),
+    unprotectedHeadersMap,
+    Buffer.from(payloadBytes),
+    Buffer.from(cslSignatureBytes),
+  ];
+  const finalCoseSign1CborBytes = Encoder.encode(coseSign1Array);
+  /* // directly encoding the coseSign1Array without prepending the 0xD2 tag.
+   * const coseSign1PayloadBytes = Encoder.encode(coseSign1Array);
+   * const coseSign1Tag = Buffer.from([0xD2]); // Tag 18 for COSE_Sign1
+   * const finalCoseSign1CborBytes = Buffer.concat([coseSign1Tag, coseSign1PayloadBytes]);
+   */
+  const manualCoseSign1Hex = bytesToHex(finalCoseSign1CborBytes);
+
+  // COSE_Key Construction
+  const coseKeyMap = new Map<number, any>();
+  coseKeyMap.set(1, 1); // kty: OKP (Octet Key Pair)
+  coseKeyMap.set(3, -8); // alg: EdDSA
+  coseKeyMap.set(-1, 6); // crv: Ed25519
+  coseKeyMap.set(-2, Buffer.from(paymentPubKey.as_bytes())); // x: public_key_bytes (Ed25519 public key)
+  const finalCoseKeyCborBytes = Encoder.encode(coseKeyMap);
+  const manualCoseKeyHex = bytesToHex(finalCoseKeyCborBytes);
+
+  return { manualCoseSign1Hex, manualCoseKeyHex };
+}
+
+export function coseObjectsOutputToBuffer(output: CSLCoseObjectsOutput): Buffer {
+  return Buffer.from(Encoder.encode(output));
+}
+
+export async function bufferToCoseObjectsOutput(buffer: Buffer): Promise<CSLCoseObjectsOutput> {
+  return await Decoder.decodeFirst(buffer);
+}

modules/sdk-coin-ada/src/lib/messages/index.ts

@@ -0,0 +1,2 @@
+export * from './messageBuilderFactory';
+export * from './cip8';

modules/sdk-coin-ada/src/lib/messages/messageBuilderFactory.ts

@@ -0,0 +1,18 @@
+import { Cip8MessageBuilder } from './cip8';
+import { BaseCoin as CoinConfig } from '@bitgo/statics';
+import { BaseMessageBuilderFactory, IMessageBuilder, MessageStandardType } from '@bitgo/sdk-core';
+
+export class MessageBuilderFactory extends BaseMessageBuilderFactory {
+  constructor(coinConfig: Readonly<CoinConfig>) {
+    super(coinConfig);
+  }
+
+  public getMessageBuilder(type: MessageStandardType): IMessageBuilder {
+    switch (type) {
+      case MessageStandardType.CIP8:
+        return new Cip8MessageBuilder(this.coinConfig);
+      default:
+        throw new Error(`Invalid message standard ${type}`);
+    }
+  }
+}

modules/sdk-coin-ada/test/resources/cip8Resources.ts

@@ -0,0 +1,48 @@
+import * as CardanoSL from '@emurgo/cardano-serialization-lib-nodejs';
+import { Buffer } from 'buffer';
+
+export const cip8TestResources = {
+  // Test address and key pair
+  address: {
+    bech32:
+      'addr_test1qpxecfjurjtcnalwy6gxcqzp09je55gvfv79hghqst8p7p6dnsn9c8yh38m7uf5sdsqyz7t9nfgscjeutw3wpqkwrursutfm7h',
+    paymentKeyHash: '5a0bf45a9f8214d9d44e20f806116bda59e10e706574b877501391b14',
+  },
+  keyPair: {
+    prv: '38e3bf2573ebbc35b65b5bc91275e0ef05cc3ebd5bb913ede29c19fe0edacc8a',
+    pub: 'c082eb504ec79dbdaecbf9c69745f88bb7973b02db8c4c73e4faeef349e21447',
+  },
+
+  // Test messages
+  messages: {
+    simple: 'Hello, Cardano!',
+    utf8: 'こんにちは, Cardano!', // Test UTF-8 characters
+    longer:
+      'This is a longer message for testing the CIP8 message implementation. It contains multiple sentences and is intended to test how the implementation handles messages of varying lengths.',
+  },
+
+  // Pre-computed signatures for tests
+  signatures: {
+    simpleMessageSignature:
+      '8458208458208a582000000000000000000000000000000000000000000000000000000000000000001a40158205a0bf45a9f8214d9d44e20f806116bda59e10e706574b877501391b14a1686866616c7365584073884144eb54ddc9a92cc5a5fff4bb38536c0489e75e84244c454419ebc5e636528d6c68e939a9c15d7f6d57e4da5ba68bca9b94f17ac0652d25470fac1207',
+  },
+
+  // Helper function to create a test signature
+  createTestSignature: function (payload: string): Uint8Array {
+    // This is a dummy function that returns a fixed signature
+    // In real tests, we'd use actual cryptographic libraries to sign
+    const buffer = Buffer.alloc(64, 0);
+    buffer.write(payload.slice(0, 64), 'utf8');
+    return buffer;
+  },
+
+  // Helper function to create a CSL public key from the test key pair
+  createTestPublicKey: function (): CardanoSL.PublicKey {
+    return CardanoSL.PublicKey.from_bytes(Buffer.from(this.keyPair.pub, 'hex'));
+  },
+
+  // Pre-computed signable payloads for verification
+  signablePayloads: {
+    simple: 'a0', // Example CBOR hex for simple message (will be replaced with actual values)
+  },
+};