tapass 0.0.0-stage → 0.2.0

package/src/tapd_responses/rpc_forward_as_asset_forward.ts

@@ -0,0 +1,164 @@
+import fixedPointAsDecimal from './fixed_point_as_decimal.js';
+import type {RpcFixedPoint} from './fixed_point_as_decimal.js';
+import type {RpcAssetSpec} from './rpc_buy_quote_as_quote.js';
+import shortChannelIdAsChannel from './short_channel_id_as_channel.js';
+
+const dateFrom = (n: string) => new Date(Number(n) * 1e3).toISOString();
+const hexOf = (n?: Buffer | null) =>
+  !n?.length ? undefined : n.toString('hex');
+const isBuffer = (n: unknown): n is Buffer => Buffer.isBuffer(n);
+const isNumeric = (n: unknown) => typeof n === 'string' && /^\d+$/.test(n);
+const policyTypes: Record<string, AssetForward['type']> = {
+  RFQ_POLICY_TYPE_PURCHASE: 'purchase',
+  RFQ_POLICY_TYPE_SALE: 'sale',
+};
+const zero = '0';
+
+export type RpcForwardingEvent = {
+  amt_in_msat: string;
+  amt_out_msat: string;
+  asset_amt: string;
+  asset_spec: RpcAssetSpec;
+  chan_id_in: string;
+  chan_id_out: string;
+  failed_at: string;
+  htlc_id: string;
+  opened_at: string;
+  peer: string;
+  policy_type: string;
+  rate: RpcFixedPoint | null;
+  rfq_id: Buffer;
+  settled_at: string;
+};
+
+export type AssetForward = {
+  /** Swapped Asset Units Numeric String */
+  amount: string;
+  /** Asset Id Hex */
+  asset_id?: string;
+  /** Forward Failed At ISO 8601 Date */
+  failed_at?: string;
+  /** Asset Group BIP340 Public Key Hex */
+  group_key?: string;
+  /** Incoming HTLC Index Numeric String */
+  htlc_index: string;
+  /** Incoming Standard Format Channel Id */
+  incoming_channel: string;
+  /** Received Millitokens String */
+  incoming_mtokens: string;
+  /** Forward Started At ISO 8601 Date */
+  opened_at: string;
+  /** Outgoing Standard Format Channel Id */
+  outgoing_channel: string;
+  /** Sent Millitokens String */
+  outgoing_mtokens: string;
+  /** Peer Public Key Hex */
+  peer_public_key?: string;
+  /** Rate Asset Units Per BTC Exact Decimal String */
+  rate?: string;
+  /** RFQ Session Id Hex */
+  rfq_id: string;
+  /** Forward Settled At ISO 8601 Date */
+  settled_at?: string;
+  /** Edge Node Policy Type */
+  type: 'purchase' | 'sale';
+};
+
+/** Asset forward from an RPC RFQ forwarding event
+
+  {
+    amt_in_msat: <Received Millisatoshis Numeric String>
+    amt_out_msat: <Sent Millisatoshis Numeric String>
+    asset_amt: <Swapped Asset Units Numeric String>
+    [asset_spec]: {
+      group_pub_key: <Asset Group BIP340 Public Key Buffer Object>
+      id: <Asset Id Buffer Object>
+    }
+    chan_id_in: <Incoming Short Channel Id Numeric String>
+    chan_id_out: <Outgoing Short Channel Id Numeric String>
+    failed_at: <Failed At Unix Seconds Numeric String> // 0 is not failed
+    htlc_id: <Incoming HTLC Index Numeric String>
+    opened_at: <Started At Unix Seconds Numeric String>
+    peer: <Peer Public Key Hex String>
+    policy_type: <Policy Type String>
+    [rate]: {
+      coefficient: <Scaled Integer Numeric String>
+      scale: <Decimal Places Number>
+    }
+    rfq_id: <RFQ Session Id Buffer Object>
+    settled_at: <Settled At Unix Seconds Numeric String> // 0 is not settled
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  {
+    amount: <Swapped Asset Units Numeric String>
+    [asset_id]: <Asset Id Hex String>
+    [failed_at]: <Forward Failed At ISO 8601 Date String>
+    [group_key]: <Asset Group BIP340 Public Key Hex String>
+    htlc_index: <Incoming HTLC Index Numeric String>
+    incoming_channel: <Incoming Standard Format Channel Id String>
+    incoming_mtokens: <Received Millitokens String>
+    opened_at: <Forward Started At ISO 8601 Date String>
+    outgoing_channel: <Outgoing Standard Format Channel Id String>
+    outgoing_mtokens: <Sent Millitokens String>
+    [peer_public_key]: <Peer Public Key Hex String>
+    [rate]: <Rate Asset Units Per BTC Exact Decimal String>
+    rfq_id: <RFQ Session Id Hex String>
+    [settled_at]: <Forward Settled At ISO 8601 Date String>
+    type: <Edge Node Policy Type String> // purchase, sale
+  }
+*/
+export default (forward?: RpcForwardingEvent | null): AssetForward => {
+  if (!forward) {
+    throw new Error('ExpectedRpcForwardingEvent');
+  }
+
+  if (!isNumeric(forward.amt_in_msat) || !isNumeric(forward.amt_out_msat)) {
+    throw new Error('ExpectedMsatAmountsInRpcForwardingEvent');
+  }
+
+  if (!isNumeric(forward.asset_amt)) {
+    throw new Error('ExpectedAssetAmountInRpcForwardingEvent');
+  }
+
+  if (!isNumeric(forward.htlc_id)) {
+    throw new Error('ExpectedHtlcIdInRpcForwardingEvent');
+  }
+
+  if (!isNumeric(forward.opened_at)) {
+    throw new Error('ExpectedOpenedAtInRpcForwardingEvent');
+  }
+
+  if (!policyTypes[forward.policy_type]) {
+    throw new Error('ExpectedKnownPolicyTypeInRpcForwardingEvent');
+  }
+
+  if (!isBuffer(forward.rfq_id) || !forward.rfq_id.length) {
+    throw new Error('ExpectedRfqIdInRpcForwardingEvent');
+  }
+
+  const failedAt = forward.failed_at;
+  const settledAt = forward.settled_at;
+
+  return {
+    amount: forward.asset_amt,
+    asset_id: hexOf(forward.asset_spec?.id),
+    failed_at: !!failedAt && failedAt !== zero ? dateFrom(failedAt) : undefined,
+    group_key: hexOf(forward.asset_spec?.group_pub_key),
+    htlc_index: forward.htlc_id,
+    incoming_channel: shortChannelIdAsChannel(forward.chan_id_in),
+    incoming_mtokens: forward.amt_in_msat,
+    opened_at: dateFrom(forward.opened_at),
+    outgoing_channel: shortChannelIdAsChannel(forward.chan_id_out),
+    outgoing_mtokens: forward.amt_out_msat,
+    peer_public_key: forward.peer || undefined,
+    rate: !forward.rate ? undefined : fixedPointAsDecimal(forward.rate),
+    rfq_id: forward.rfq_id.toString('hex'),
+    settled_at:
+      !!settledAt && settledAt !== zero ? dateFrom(settledAt) : undefined,
+    type: policyTypes[forward.policy_type],
+  };
+};

package/src/tapd_responses/rpc_grouped_assets_as_group.ts

@@ -0,0 +1,117 @@
+const assetVersions = ['ASSET_VERSION_V0', 'ASSET_VERSION_V1'];
+const {isArray} = Array;
+const isBuffer = (n: unknown): n is Buffer => Buffer.isBuffer(n);
+const isGroupKey = (n: string) => /^0[23][0-9a-f]{64}$/i.test(n);
+const isNumeric = (n: unknown) => typeof n === 'string' && /^\d+$/.test(n);
+
+export type RpcGroupedAssets = {
+  assets: {
+    amount: string;
+    id: Buffer;
+    lock_time: number;
+    meta_hash: Buffer;
+    relative_lock_time: number;
+    tag: string;
+    type: string;
+    version: string;
+  }[];
+};
+
+export type Group = {
+  assets: {
+    /** Asset Units Numeric String */
+    amount: string;
+    /** Asset Id Hex */
+    asset_id: string;
+    /** Asset Is Collectible */
+    is_collectible: boolean;
+    /** Lock Time */
+    lock_time?: number;
+    /** Asset Metadata Hash Hex */
+    meta_hash: string;
+    /** Asset Name */
+    name: string;
+    /** Relative Lock Time */
+    relative_lock_time?: number;
+    /** Asset Version */
+    version: number;
+  }[];
+  /** Tweaked Group Key Hex */
+  key: string;
+};
+
+/** Group from an RPC group key and its grouped assets
+
+  {
+    key: <Tweaked Group Key Hex String>
+    group: {
+      assets: [{
+        amount: <Asset Units Numeric String>
+        id: <Asset Id Buffer Object>
+        lock_time: <Lock Time Number>
+        meta_hash: <Asset Metadata Hash Buffer Object>
+        relative_lock_time: <Relative Lock Time Number>
+        tag: <Asset Name String>
+        type: <Asset Type String>
+        version: <Asset Version String>
+      }]
+    }
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  {
+    assets: [{
+      amount: <Asset Units Numeric String>
+      asset_id: <Asset Id Hex String>
+      is_collectible: <Asset Is Collectible Bool>
+      [lock_time]: <Lock Time Number>
+      meta_hash: <Asset Metadata Hash Hex String>
+      name: <Asset Name String>
+      [relative_lock_time]: <Relative Lock Time Number>
+      version: <Asset Version Number>
+    }]
+    key: <Tweaked Group Key Hex String>
+  }
+*/
+export default ({
+  group,
+  key,
+}: {
+  group?: RpcGroupedAssets | null;
+  key: string;
+}): Group => {
+  if (!isGroupKey(key)) {
+    throw new Error('ExpectedGroupKeyForRpcGroupedAssets');
+  }
+
+  if (!group || !isArray(group.assets)) {
+    throw new Error('ExpectedArrayOfAssetsInRpcGroupedAssets');
+  }
+
+  return {
+    key,
+    assets: group.assets.map(asset => {
+      if (!isNumeric(asset?.amount)) {
+        throw new Error('ExpectedAmountInRpcGroupedAsset');
+      }
+
+      if (!isBuffer(asset.id) || !isBuffer(asset.meta_hash)) {
+        throw new Error('ExpectedAssetIdAndMetaHashInRpcGroupedAsset');
+      }
+
+      return {
+        amount: asset.amount,
+        asset_id: asset.id.toString('hex'),
+        is_collectible: asset.type === 'COLLECTIBLE',
+        lock_time: asset.lock_time || undefined,
+        meta_hash: asset.meta_hash.toString('hex'),
+        name: asset.tag,
+        relative_lock_time: asset.relative_lock_time || undefined,
+        version: assetVersions.indexOf(asset.version),
+      };
+    }),
+  };
+};

package/src/tapd_responses/rpc_managed_utxo_as_utxo.ts

@@ -0,0 +1,105 @@
+import outpointAsTransaction from './outpoint_as_transaction.js';
+import rpcAssetAsAsset from './rpc_asset_as_asset.js';
+import type {Asset} from './rpc_asset_as_asset.js';
+import type {RpcAsset} from './rpc_asset_as_asset.js';
+
+const dateFrom = (n: string) => new Date(Number(n) * 1e3).toISOString();
+const {isArray} = Array;
+const isBuffer = (n: unknown): n is Buffer => Buffer.isBuffer(n);
+const isInteger = (n: unknown) => typeof n === 'string' && /^-?\d+$/.test(n);
+
+export type RpcManagedUtxo = {
+  amt_sat: string;
+  assets: RpcAsset[];
+  internal_key: Buffer;
+  lease_expiry_unix: string;
+  lease_owner: Buffer;
+  merkle_root: Buffer;
+  out_point: string;
+  taproot_asset_root: Buffer;
+};
+
+export type Utxo = {
+  assets: Asset[];
+  /** Internal Key Hex */
+  internal_key: string;
+  /** Lease Expires At ISO 8601 Date */
+  lease_expires_at?: string;
+  /** Lease Owner Id Hex */
+  lease_owner?: string;
+  /** Taproot Merkle Root Hex */
+  merkle_root: string;
+  /** Taproot Asset Root Commitment Hash Hex */
+  taproot_asset_root: string;
+  /** Output Value Tokens */
+  tokens: number;
+  /** Transaction Id Hex */
+  transaction_id: string;
+  /** Transaction Output Index */
+  transaction_vout: number;
+};
+
+/** UTXO from an RPC managed UTXO
+
+  {
+    amt_sat: <Output Value Satoshis Numeric String>
+    assets: [<RPC Asset Object>]
+    internal_key: <Internal Key Buffer Object>
+    lease_expiry_unix: <Lease Expires At Unix Seconds Numeric String>
+    lease_owner: <Lease Owner Id Buffer Object>
+    merkle_root: <Taproot Merkle Root Buffer Object>
+    out_point: <Outpoint String>
+    taproot_asset_root: <Taproot Asset Root Commitment Hash Buffer Object>
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  {
+    assets: [<Asset Object>]
+    internal_key: <Internal Key Hex String>
+    [lease_expires_at]: <Lease Expires At ISO 8601 Date String>
+    [lease_owner]: <Lease Owner Id Hex String>
+    merkle_root: <Taproot Merkle Root Hex String>
+    taproot_asset_root: <Taproot Asset Root Commitment Hash Hex String>
+    tokens: <Output Value Tokens Number>
+    transaction_id: <Transaction Id Hex String>
+    transaction_vout: <Transaction Output Index Number>
+  }
+*/
+export default (utxo?: RpcManagedUtxo | null): Utxo => {
+  if (!utxo) {
+    throw new Error('ExpectedRpcManagedUtxoDetails');
+  }
+
+  if (!isInteger(utxo.amt_sat)) {
+    throw new Error('ExpectedOutputValueInRpcManagedUtxo');
+  }
+
+  if (!isArray(utxo.assets)) {
+    throw new Error('ExpectedArrayOfAssetsInRpcManagedUtxo');
+  }
+
+  if (!isBuffer(utxo.internal_key) || !isBuffer(utxo.merkle_root)) {
+    throw new Error('ExpectedKeysInRpcManagedUtxo');
+  }
+
+  if (!isBuffer(utxo.taproot_asset_root)) {
+    throw new Error('ExpectedTaprootAssetRootInRpcManagedUtxo');
+  }
+
+  // tapd sends the zero time as the expiry when there is no lease
+  const hasLease = !!utxo.lease_owner?.length;
+
+  return {
+    assets: utxo.assets.map(rpcAssetAsAsset),
+    internal_key: utxo.internal_key.toString('hex'),
+    lease_expires_at: hasLease ? dateFrom(utxo.lease_expiry_unix) : undefined,
+    lease_owner: hasLease ? utxo.lease_owner.toString('hex') : undefined,
+    merkle_root: utxo.merkle_root.toString('hex'),
+    taproot_asset_root: utxo.taproot_asset_root.toString('hex'),
+    tokens: Number(utxo.amt_sat),
+    ...outpointAsTransaction(utxo.out_point),
+  };
+};

package/src/tapd_responses/rpc_receive_event_as_receive_update.ts

@@ -0,0 +1,84 @@
+import outpointAsTransaction from './outpoint_as_transaction.js';
+import receiveStatuses from './receive_statuses.js';
+import rpcAddrAsAddress from './rpc_addr_as_address.js';
+import type {Address} from './rpc_addr_as_address.js';
+import type {RpcAddr} from './rpc_addr_as_address.js';
+
+const isInteger = (n: unknown) => typeof n === 'string' && /^-?\d+$/.test(n);
+const microsPerMilli = 1e3;
+
+export type RpcReceiveEvent = {
+  address: RpcAddr | null;
+  confirmation_height: number;
+  error: string;
+  outpoint: string;
+  status: string;
+  timestamp: string;
+};
+
+export type ReceiveUpdate = {
+  address: Address;
+  /** Confirmation Block Height */
+  confirmation_height?: number;
+  /** Receive Error */
+  error?: string;
+  /** Receive Status */
+  status: string;
+  /** Anchor Transaction Id Hex */
+  transaction_id?: string;
+  /** Anchor Transaction Output Index */
+  transaction_vout?: number;
+  /** Updated At ISO 8601 Date */
+  updated_at: string;
+};
+
+/** Receive update from an RPC receive event
+
+  {
+    address: <RPC Address Object>
+    confirmation_height: <Confirmation Block Height Number>
+    error: <Receive Error String>
+    outpoint: <Anchor Outpoint String>
+    status: <Address Event Status String>
+    timestamp: <Event Unix Microseconds Numeric String>
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  {
+    address: <Address Object>
+    [confirmation_height]: <Confirmation Block Height Number>
+    [error]: <Receive Error String>
+    status: <Receive Status String>
+    [transaction_id]: <Anchor Transaction Id Hex String>
+    [transaction_vout]: <Anchor Transaction Output Index Number>
+    updated_at: <Updated At ISO 8601 Date String>
+  }
+*/
+export default (event?: RpcReceiveEvent | null): ReceiveUpdate => {
+  if (!event) {
+    throw new Error('ExpectedRpcReceiveEventDetails');
+  }
+
+  if (!receiveStatuses[event.status]) {
+    throw new Error('ExpectedKnownStatusInRpcReceiveEvent');
+  }
+
+  if (!isInteger(event.timestamp)) {
+    throw new Error('ExpectedTimestampInRpcReceiveEvent');
+  }
+
+  // tapd sends the time of the event in microseconds
+  const millis = Number(event.timestamp) / microsPerMilli;
+
+  return {
+    address: rpcAddrAsAddress(event.address),
+    confirmation_height: event.confirmation_height || undefined,
+    error: event.error || undefined,
+    status: receiveStatuses[event.status],
+    updated_at: new Date(millis).toISOString(),
+    ...(!event.outpoint ? {} : outpointAsTransaction(event.outpoint)),
+  };
+};

package/src/tapd_responses/rpc_rfq_event_as_event.ts

@@ -0,0 +1,123 @@
+import rpcBuyQuoteAsQuote from './rpc_buy_quote_as_quote.js';
+import type {BuyQuote} from './rpc_buy_quote_as_quote.js';
+import type {RpcBuyQuote} from './rpc_buy_quote_as_quote.js';
+import rpcSellQuoteAsQuote from './rpc_sell_quote_as_quote.js';
+import type {RpcSellQuote} from './rpc_sell_quote_as_quote.js';
+import type {SellQuote} from './rpc_sell_quote_as_quote.js';
+import shortChannelIdAsChannel from './short_channel_id_as_channel.js';
+
+const isNumeric = (n: unknown) => typeof n === 'string' && /^\d+$/.test(n);
+const microsecondsPerMs = BigInt(1e3);
+
+/** ISO 8601 date from a unix timestamp in microseconds */
+const dateFromMicros = (n: string) => {
+  return new Date(Number(BigInt(n) / microsecondsPerMs)).toISOString();
+};
+
+export type RpcRfqEvent = {
+  accept_htlc?: {scid: string; timestamp: string} | null;
+  event?: string;
+  peer_accepted_buy_quote?: {
+    peer_accepted_buy_quote: RpcBuyQuote | null;
+    timestamp: string;
+  } | null;
+  peer_accepted_sell_quote?: {
+    peer_accepted_sell_quote: RpcSellQuote | null;
+    timestamp: string;
+  } | null;
+};
+
+export type RfqEvent =
+  | {data: BuyQuote & {at: string}; event: 'accepted_buy_quote'}
+  | {data: SellQuote & {at: string}; event: 'accepted_sell_quote'}
+  | {data: {at: string; channel: string}; event: 'accepted_htlc'};
+
+/** Event from an RPC RFQ event
+
+  {
+    [accept_htlc]: {
+      scid: <Short Channel Id Numeric String>
+      timestamp: <Unix Microseconds Numeric String>
+    }
+    event: <Set Event Name String>
+    [peer_accepted_buy_quote]: {
+      peer_accepted_buy_quote: <RPC Peer Accepted Buy Quote Object>
+      timestamp: <Unix Microseconds Numeric String>
+    }
+    [peer_accepted_sell_quote]: {
+      peer_accepted_sell_quote: <RPC Peer Accepted Sell Quote Object>
+      timestamp: <Unix Microseconds Numeric String>
+    }
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  {
+    data: {
+      at: <Event At ISO 8601 Date String>
+      ...<Buy Quote, Sell Quote, or Channel Object>
+    }
+    event: <Event Name String> // accepted_buy_quote, accepted_sell_quote,
+                               // accepted_htlc
+  }
+*/
+export default (event?: RpcRfqEvent | null): RfqEvent => {
+  if (!event) {
+    throw new Error('ExpectedRpcRfqEvent');
+  }
+
+  switch (event.event) {
+    case 'accept_htlc': {
+      const htlc = event.accept_htlc;
+
+      if (!htlc || !isNumeric(htlc.timestamp)) {
+        throw new Error('ExpectedTimestampInRpcAcceptHtlcEvent');
+      }
+
+      return {
+        data: {
+          at: dateFromMicros(htlc.timestamp),
+          channel: shortChannelIdAsChannel(htlc.scid),
+        },
+        event: 'accepted_htlc',
+      };
+    }
+
+    case 'peer_accepted_buy_quote': {
+      const accepted = event.peer_accepted_buy_quote;
+
+      if (!accepted || !isNumeric(accepted.timestamp)) {
+        throw new Error('ExpectedTimestampInRpcAcceptedBuyQuoteEvent');
+      }
+
+      return {
+        data: {
+          at: dateFromMicros(accepted.timestamp),
+          ...rpcBuyQuoteAsQuote(accepted.peer_accepted_buy_quote),
+        },
+        event: 'accepted_buy_quote',
+      };
+    }
+
+    case 'peer_accepted_sell_quote': {
+      const accepted = event.peer_accepted_sell_quote;
+
+      if (!accepted || !isNumeric(accepted.timestamp)) {
+        throw new Error('ExpectedTimestampInRpcAcceptedSellQuoteEvent');
+      }
+
+      return {
+        data: {
+          at: dateFromMicros(accepted.timestamp),
+          ...rpcSellQuoteAsQuote(accepted.peer_accepted_sell_quote),
+        },
+        event: 'accepted_sell_quote',
+      };
+    }
+
+    default:
+      throw new Error('ExpectedKnownEventTypeInRpcRfqEvent');
+  }
+};