hamilton

CBDC

This is a pure JS node module which reads and writes the binary transaction and watchtower packet formats used in CBDC-universe0. It also contains utilities to calculate UHS and transaction hashes from output data.

The following is a breakdown of sections and classes for this cbdc-module:

Crypto

• Address

  • constructor(script_type, pubHex) - a new Address Object

    • script_type - {Number} representing the script type of the address
    • pubHex - {String} represents valid 32 byte hexadecimal string

  • getAddress() - returns {String} represented the bech32 encoding version of a publickey e.g.

  • decodeAddress() - returns {Object} with fields script_type (string representing) and pubHex (hex string of public key)

  • static decodeFromAddressString(address) - returns {Object} with fields script_type {Number} and pubHex {String} (hexdecimal string of public key)

• Publickey

  • constructor(secretKeyData) - returns a new Publickey object
    • secretKeyData - {String} a valid 32 byte hexadecimal string
  • static fromPrivateKeyData(secretKeyData)
    • secretKeyData - {String} a valid 32 byte hexadecimal string
  • toBuffer() - returns {Buffer} 32 byte buffer publickey

• Secretkey

  • contructor(randBytes) - returns new SecretKey with randBytes provided as random seed (if provided), otherwise it creates random key from random secrety bytes
    • randBytes - {Buffer} optional 32 bytes used to seed for privatekey, otherwise another random
  • toString() - returns {String} valid hexadecimal string of privatekey
  • toBuffer() - returns {Buffer} valid 32 byte Buffer for privatekey
  • static fromHex(secretKeyHex)- returns {SecretKey} from secretKeyHex
    • secretKeyHex - valid 32 byte hexadecimal string for privateKey
  • toHex() - returns hexadecimal representation of privateKey

Networking

• Networking
  • broadcastTx(port, host, signedTxHex) - broadcast a signedTxBuf to a sentinel server at host {host} and port {port} number
    • port - {number} port number of host
    • host - {string} hostname url to send signedTx
    • signedTxHex - {string} a valid hexadecimal encoded transaction that has been signed

Transaction

• Input
  • constructor(tx_hash, index, witnessProgramCommitment, value) returns new Input Object Type
    • tx_hash - {String} valid hexadecimal string for transaction hash this input references
    • index - {number} index position of the input for tx
    • witnessProgramCommitment {String} - witness commitment for this input
    • value {number} - the number of dollar units this input is worth
  • writeInputToBuffer() - returns Buffer representation as buffer type
  • getUHSHash() - returns {Buffer} Universal Hash Set hash of the input e.g. concatentation of [txid, index, witnessProgramCommitment, value] into bytes e.g.
  • toString() - returns {String} representing valid input

Utils

• Utility Methods CBDC module
  • sign(secretKey, message) - returns signature that signed message {message} with privateKey {privateKey}
    • secretKey - {String} - 32 byte hexadecimal string
    • message - {String} - message that is signed
  • verify(publicKey, message, signature) returns true or false whether the produced signature is validly signed publicKey
    • publicKey - 32 byte hexadecimal string
    • message - message to verify was signed
    • signature - {String} signature to verify validly signed message against public key message pair

Note: A Universal Hash Set Hash is used to identify a specfic (UTXO) within the cbdc-universe system it is a concatenation of a txid, a 64 bit encoded index of previous tx, a witnessProgramCommitment, and a 64 bit encoded value for that encoded output

• Output

  • constructor(witnessProgramCommitment, value) returns new Output Object type
    • witnessProgramCommitment - {String}
    • value - {Number}
  • writeOutputToBuffer() - returns a Buffer representation of this output in raw bytes
  • static fromOutputData(pubHex, value) - returns a new {Output} from publicKey and value provided
    • pubHex - {String}
    • value - {Number}
  • toString() - returns {String} string representation of Output

• Transaction

  • constructor(inputs, outputs, witnesses) - returns new {Transaction} object
    • inputs - Array{Input}
    • outputs - Array{Output}
    • witnesses - Array of witness object
  • toHex() - returns {String} hexadecimal string of the unsigned raw transaction
  • getTxid() - returns {String} returns hexadecimal string of transaction id (txid)
  • sign(secretKey) - returns {Buffer} signed tx in bytes
  • static txFromHex(rawHex) - returns {Transaction} object from the provided rawTx
    • rawHex - valid hexadecimal string represents a valid tx

Special Notes

BigInt is used everywhere throughout this module, that may pose problems in using toJson() methods or serializing for output

Example Usage

The following are example interactions.

• Address

      const addr = new Address('00', '3ad8f015f9212f8262248af4cf4cc39907d0215fdde14507f8bc09ad5836bbe9')
  
      console.log(addr.getAddress()); 
      usd1qqad3uq4lysjlqnzyj90fn6vcwvs05pptlw7z3g8lz7qnt2cx6a7jty6gr5
  
      console.log(addr.decodeAddress());
  
      { script_type: 0, pubHex: 3ad8f015f9212f8262248af4cf4cc39907d0215fdde14507f8bc09ad5836bbe9 }
  

• Publickey

      const pub = new Publickey('e00b5c3d80899217a22fea87e7337907203df8a1efebd4d2a8773c8f629fff36')
      console.log(pub.toBuffer());
  

• Secretkey

      const secKey = new SecretKey(Buffer.from(parseInt(Math.round(Math.random() * 10)), 'hex'));
      secKey.toString();
      secKey.toBuffer();
  

• Networking

      let network = require('./networking/broadcast');
      const txBuf = new Transaction();
      Networking.broadcast(5555, '127.0.0.1', Buffer.from(tx.toHex(), 'hex'))
  

• Transaction

      const input = new Input('9f981e64afc0fc56a0d7b355cd9eba36f3d19507088713b1f73afc5bf301a44e', 0, '70cd87ebaaa0d2d059dccaceeb7f9f823a5791d60b00aef9d9573f1fbf91ca29', 200)
      const output = new Output('81b095a242974d9f4e98ca18b468b8e644e4168380a035b3d66bc279b36c6510', 200)
      const tx = new Transaction([input], [output], []);
      tx.sign('e00b5c3d80899217a22fea87e7337907203df8a1efebd4d2a8773c8f629fff36')
      console.log(tx.getTxid());
  
      12e01dfa90358fd203da3acbbe105b1ed2d249cd8e601ed919f4b8b2a99cbb02
  
      console.log(tx);
      01000000000000009f981e64afc0fc56a0d7b355cd9eba36f3d19507088713b1f73afc5bf301a44e000000000000000070cd87ebaaa0d2d059dccaceeb7f9f823a5791d60b00aef9d9573f1fbf91ca29c800000000000000010000000000000081b095a242974d9f4e98ca18b468b8e644e4168380a035b3d66bc279b36c6510c80000000000000001000000000000006100000000000000003ad8f015f9212f8262248af4cf4cc39907d0215fdde14507f8bc09ad5836bbe901986cc97272bdb7624a824afcef76936b8f945e55d6e8479b95c81298e77b42d5a255e8529fc2f0d90743e7f9997a7159b6121105c7ec9b9252da992f34611f
  
  

  • Constructing, signing and broacasting tx to sentinel

      const secretKey = 'e00b5c3d80899217a22fea87e7337907203df8a1efebd4d2a8773c8f629fff36';
  
      const input = new Input('9f981e64afc0fc56a0d7b355cd9eba36f3d19507088713b1f73afc5bf301a44e', 0, 70cd87ebaaa0d2d059dccaceeb7f9f823a5791d60b00aef9d9573f1fbf91ca29, 200)
      const output = new Output('81b095a242974d9f4e98ca18b468b8e644e4168380a035b3d66bc279b36c6510', 200)
      const tx = new Transaction([input], [output], []);
  
      tx.sign(secretKey);
  
      Networking.broadcast(5555, '127.0.0.1', Buffer.from(tx.toHex(), 'hex'))
  
  

  • Signing and Verifying

  const secretKey = "e00b5c3d80899217a22fea87e7337907203df8a1efebd4d2a8773c8f629fff36";
  const publicKey = "3ad8f015f9212f8262248af4cf4cc39907d0215fdde14507f8bc09ad5836bbe9";
  const sha256 = function () {...};
  const message = 'onomatopoeia';
  
  const sig = utils.sign(secretKey, message);
  utils.verify(publicKey, Buffer.from(sha256(message), 'hex'), sig);
  

Sample Data

Secret and Related Public Key

secret key: e00b5c3d80899217a22fea87e7337907203df8a1efebd4d2a8773c8f629fff36
public key: 3ad8f015f9212f8262248af4cf4cc39907d0215fdde14507f8bc09ad5836bbe9

Signed Transaction

01000000000000009f981e64afc0fc56a0d7b355cd9eba36f3d19507088713b1f73afc5bf301a44e000000000000000070cd87ebaaa0d2d059dccaceeb7f9f823a5791d60b00aef9d9573f1fbf91ca29c800000000000000010000000000000081b095a242974d9f4e98ca18b468b8e644e4168380a035b3d66bc279b36c6510c80000000000000001000000000000006100000000000000003ad8f015f9212f8262248af4cf4cc39907d0215fdde14507f8bc09ad5836bbe901986cc97272bdb7624a824afcef76936b8f945e55d6e8479b95c81298e77b42d5a255e8529fc2f0d90743e7f9997a7159b6121105c7ec9b9252da992f34611f

Signed Transaction Decoded

Tx {
  inputs: [
    {
      tx_hash: '9f981e64afc0fc56a0d7b355cd9eba36f3d19507088713b1f73afc5bf301a44e',
      index: 0n,
      witness_program_commitment: '70cd87ebaaa0d2d059dccaceeb7f9f823a5791d60b00aef9d9573f1fbf91ca29',
      value: 200n
    }
  ],
  outputs: [
    {
      witness_program_commitment: '81b095a242974d9f4e98ca18b468b8e644e4168380a035b3d66bc279b36c6510',
      value: 200n
    }
  ],
  witnesses: [
    {
      witness_length: 97n,
      script_type: 0,
      pubkey: '3ad8f015f9212f8262248af4cf4cc39907d0215fdde14507f8bc09ad5836bbe9',
      signature: '01986cc97272bdb7624a824afcef76936b8f945e55d6e8479b95c81298e77b42d5a255e8529fc2f0d90743e7f9997a7159b6121105c7ec9b9252da992f34611f'
    }
  ]
}

Testing

• Install mocha with npm install mocha or npm i -g mocha
• Run the command npm test from the root directory

Contributions

• Please submit a pull request with your reasoning so it will be discussed and reviewed