docs(root): refactor omni_example to index and debugging.ts

BTC-1864

TICKET: BTC-0

Author: ericli-bitgo

examples/ts/btc/omni/config.ts

@@ -23,4 +23,6 @@ export const omniConfig = {
   walletPassphrase,
   walletId,
   otp,
+  MEMPOOL_PREFIX: env === 'test' ? 'testnet4/' : '',
+  OMNI_PREFIX: Buffer.from('6f6d6e69', 'hex'),
 };

examples/ts/btc/omni/debugging.ts

@@ -0,0 +1,63 @@
+import { Wallet } from '@bitgo/sdk-core';
+import * as superagent from 'superagent';
+import * as utxolib from '@bitgo/utxo-lib';
+import { omniConfig } from './config';
+
+export async function mintOmniAsset(wallet: Wallet, address: string, feeRate = 20_000): Promise<void> {
+  const transactionVersion = Buffer.alloc(2);
+  const transactionType = Buffer.alloc(2);
+  transactionType.writeUint16BE(50);
+  const ecoSystem = Buffer.alloc(1);
+  ecoSystem.writeInt8(2);
+  const propertyType = Buffer.alloc(2);
+  propertyType.writeUint16BE(2);
+  const previousPropertyID = Buffer.alloc(4);
+
+  const category = Buffer.from('Other\0');
+  const subCategory = Buffer.from('Other\0');
+  const propertyTitle = Buffer.from('Testcoin\0');
+  const propertyURL = Buffer.from('https://example.com\0');
+  const propertyData = Buffer.from('\0');
+
+  const amount = Buffer.alloc(8);
+  amount.writeBigUint64BE(BigInt(100000 * 10 ** 8));
+
+  const res = await superagent.get(`https://mempool.space/${omniConfig.MEMPOOL_PREFIX}api/address/${address}/utxo`);
+  const unspent = res.body[0];
+  const unspent_id = unspent.txid + ':' + unspent.vout;
+
+  const omniScript = Buffer.concat([
+    omniConfig.OMNI_PREFIX, // omni
+    transactionVersion,
+    transactionType,
+    ecoSystem,
+    propertyType,
+    previousPropertyID,
+    category,
+    subCategory,
+    propertyTitle,
+    propertyURL,
+    propertyData,
+    amount,
+  ]);
+
+  const output = utxolib.payments.embed({ data: [omniScript], network: utxolib.networks.bitcoin }).output;
+  if (!output) {
+    throw new Error('Invalid output');
+  }
+  const script = output.toString('hex');
+  const tx = await wallet.sendMany({
+    recipients: [
+      {
+        amount: '0',
+        address: `scriptPubkey:${script}`,
+      },
+    ],
+    isReplaceableByFee: true,
+    feeRate,
+    walletPassphrase: omniConfig.walletPassphrase,
+    changeAddress: address,
+    unspents: [unspent_id],
+  });
+  console.log('Omni asset created: ', tx);
+}

examples/ts/btc/omni/index.ts

@@ -10,75 +10,13 @@ import * as utxolib from '@bitgo/utxo-lib';
 
 const RECEIVE_ADDRESS = '';
 const SEND_ADDRESS = '';
-const MEMPOOL_PREFIX = omniConfig.coin === 'tbtc4' ? 'testnet4/' : '';
 const AMOUNT = 729100000n;
 const ASSET_ID = 31;
-const OMNI_PREFIX = Buffer.from('6f6d6e69', 'hex');
 
 async function getWallet() {
   return await omniConfig.sdk.coin(omniConfig.coin).wallets().get({ id: omniConfig.walletId });
 }
 
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-async function mintOmniAsset(wallet: Wallet, address: string, feeRate = 20_000) {
-  const transactionVersion = Buffer.alloc(2);
-  const transactionType = Buffer.alloc(2);
-  transactionType.writeUint16BE(50);
-  const ecoSystem = Buffer.alloc(1);
-  ecoSystem.writeInt8(2);
-  const propertyType = Buffer.alloc(2);
-  propertyType.writeUint16BE(2);
-  const previousPropertyID = Buffer.alloc(4);
-
-  const category = Buffer.from('Other\0');
-  const subCategory = Buffer.from('Other\0');
-  const propertyTitle = Buffer.from('Testcoin\0');
-  const propertyURL = Buffer.from('https://example.com\0');
-  const propertyData = Buffer.from('\0');
-
-  const amount = Buffer.alloc(8);
-  amount.writeBigUint64BE(BigInt(100000 * 10 ** 8));
-
-  const res = await superagent.get(`https://mempool.space/${MEMPOOL_PREFIX}api/address/${address}/utxo`);
-  const unspent = res.body[0];
-  const unspent_id = unspent.txid + ':' + unspent.vout;
-
-  const omniScript = Buffer.concat([
-    OMNI_PREFIX, // omni
-    transactionVersion,
-    transactionType,
-    ecoSystem,
-    propertyType,
-    previousPropertyID,
-    category,
-    subCategory,
-    propertyTitle,
-    propertyURL,
-    propertyData,
-    amount,
-  ]);
-
-  const output = utxolib.payments.embed({ data: [omniScript], network: utxolib.networks.bitcoin }).output;
-  if (!output) {
-    throw new Error('Invalid output');
-  }
-  const script = output.toString('hex');
-  const tx = await wallet.sendMany({
-    recipients: [
-      {
-        amount: '0',
-        address: `scriptPubkey:${script}`,
-      },
-    ],
-    isReplaceableByFee: true,
-    feeRate,
-    walletPassphrase: omniConfig.walletPassphrase,
-    changeAddress: address,
-    unspents: [unspent_id],
-  });
-  console.log('Omni asset created: ', tx);
-}
-
 async function sendOmniAsset(
   wallet: Wallet,
   receiver: string,
@@ -87,7 +25,13 @@ async function sendOmniAsset(
   assetId = 31,
   feeRate = 20_000
 ) {
-  const res = await superagent.get(`https://mempool.space/${MEMPOOL_PREFIX}/api/address/${sender}/utxo`);
+  if (!['1', 'n', 'm'].includes(receiver.slice(0, 1))) {
+    throw new Error(
+      'Omni has only been verified to work with legacy addresses - use other address formats at your own risk'
+    );
+  }
+
+  const res = await superagent.get(`https://mempool.space/${omniConfig.MEMPOOL_PREFIX}api/address/${sender}/utxo`);
   const unspent = res.body[0];
   const unspent_id = unspent.txid + ':' + unspent.vout;
 
@@ -97,18 +41,22 @@ async function sendOmniAsset(
   assetHex.writeUInt32BE(assetId);
   const amountHex = Buffer.alloc(8);
   amountHex.writeBigUInt64BE(amountMicroCents);
-  const omniScript = Buffer.concat([OMNI_PREFIX, transactionType, assetHex, amountHex]);
+  const omniScript = Buffer.concat([omniConfig.OMNI_PREFIX, transactionType, assetHex, amountHex]);
   const output = utxolib.payments.embed({ data: [omniScript], network: omniConfig.network }).output;
   if (!output) {
     throw new Error('Invalid output');
   }
   const script = output.toString('hex');
   const tx = await wallet.sendMany({
     recipients: [
+      // this signals the receiver of the omni asset
+      // we are not actually trying to send BTC to the receiver
+      // so we send the minimum amount above the dust limit
       {
         amount: '546',
         address: receiver,
       },
+      // this is the actual script that the omni layer reads for the send
       {
         amount: '0',
         address: `scriptPubkey:${script}`,
@@ -117,6 +65,8 @@ async function sendOmniAsset(
     isReplaceableByFee: true,
     feeRate,
     walletPassphrase: omniConfig.walletPassphrase,
+    // we must send change to our input address to ensure that omni won't
+    // accidentally send our asset to the change address instead of the recipient
     changeAddress: sender,
     unspents: [unspent_id],
   });
@@ -129,7 +79,7 @@ async function sendOmniAsset(
 async function main() {
   console.log('Starting...');
 
-  const feeRateRes = await superagent.get(`https://mempool.space/${MEMPOOL_PREFIX}api/v1/fees/recommended`);
+  const feeRateRes = await superagent.get(`https://mempool.space/${omniConfig.MEMPOOL_PREFIX}api/v1/fees/recommended`);
   const feeRate = feeRateRes.body.fastestFee;
 
   const wallet = await getWallet();