tapass 0.0.0-stage → 0.2.0

package/src/tapd_responses/rpc_sell_quote_as_quote.ts

@@ -0,0 +1,136 @@
+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 isPublicKey = (n: unknown) => /^0[23][0-9a-f]{64}$/i.test(String(n));
+const zero = '0';
+
+export type RpcSellQuote = {
+  accepted_max_amount: string;
+  asset_amount: string;
+  asset_spec: RpcAssetSpec;
+  bid_asset_rate: RpcFixedPoint | null;
+  expiry: string;
+  id: Buffer;
+  min_transportable_msat: string;
+  peer: string;
+  price_oracle_metadata: string;
+  scid: string;
+};
+
+export type SellQuote = {
+  /** Accepted Maximum Payment Millitokens String */
+  accepted_max_mtokens?: string;
+  /** Asset Units Numeric String */
+  amount: string;
+  /** Asset Id Hex */
+  asset_id?: string;
+  /** Channel To Pay Over Standard Format Channel Id */
+  channel: string;
+  /** Quote Expires At ISO 8601 Date */
+  expires_at: string;
+  /** Asset Group BIP340 Public Key Hex */
+  group_key?: string;
+  /** Quote Request Id Hex */
+  id: string;
+  /** Minimum Millitokens To Send One Asset Unit String */
+  min_transportable_mtokens: string;
+  /** Peer Public Key Hex */
+  peer_public_key: string;
+  /** Price Oracle Metadata */
+  price_oracle_metadata?: string;
+  /** Bid Rate Asset Units Per BTC Exact Decimal String */
+  rate: string;
+};
+
+/** Sell quote from an RPC peer accepted sell quote
+
+  {
+    accepted_max_amount: <Accepted Maximum Payment Millisatoshis String>
+    asset_amount: <Asset Units Numeric String>
+    [asset_spec]: {
+      group_pub_key: <Asset Group BIP340 Public Key Buffer Object>
+      id: <Asset Id Buffer Object>
+    }
+    bid_asset_rate: {
+      coefficient: <Scaled Integer Numeric String>
+      scale: <Decimal Places Number>
+    }
+    expiry: <Expires At Unix Seconds Numeric String>
+    id: <Quote Request Id Buffer Object>
+    min_transportable_msat: <Minimum Millisatoshis For One Unit String>
+    peer: <Peer Public Key Hex String>
+    price_oracle_metadata: <Price Oracle Metadata String>
+    scid: <Short Channel Id Numeric String>
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  {
+    [accepted_max_mtokens]: <Accepted Maximum Payment Millitokens String>
+    amount: <Asset Units Numeric String>
+    [asset_id]: <Asset Id Hex String>
+    channel: <Channel To Pay Over Standard Format Channel Id String>
+    expires_at: <Quote Expires At ISO 8601 Date String>
+    [group_key]: <Asset Group BIP340 Public Key Hex String>
+    id: <Quote Request Id Hex String>
+    min_transportable_mtokens: <Minimum Millitokens To Send One Unit String>
+    peer_public_key: <Peer Public Key Hex String>
+    [price_oracle_metadata]: <Price Oracle Metadata String>
+    rate: <Bid Rate Asset Units Per BTC Exact Decimal String>
+  }
+*/
+export default (quote?: RpcSellQuote | null): SellQuote => {
+  if (!quote) {
+    throw new Error('ExpectedRpcPeerAcceptedSellQuote');
+  }
+
+  if (!isNumeric(quote.asset_amount)) {
+    throw new Error('ExpectedAssetAmountInRpcSellQuote');
+  }
+
+  if (!isNumeric(quote.expiry)) {
+    throw new Error('ExpectedExpiryInRpcSellQuote');
+  }
+
+  if (!isBuffer(quote.id) || !quote.id.length) {
+    throw new Error('ExpectedQuoteIdInRpcSellQuote');
+  }
+
+  if (!isNumeric(quote.min_transportable_msat)) {
+    throw new Error('ExpectedMinTransportableMsatInRpcSellQuote');
+  }
+
+  if (!isPublicKey(quote.peer)) {
+    throw new Error('ExpectedPeerPublicKeyInRpcSellQuote');
+  }
+
+  if (!quote.bid_asset_rate) {
+    throw new Error('ExpectedBidAssetRateInRpcSellQuote');
+  }
+
+  const accepted = quote.accepted_max_amount;
+
+  return {
+    accepted_max_mtokens:
+      !!accepted && accepted !== zero ? accepted : undefined,
+    amount: quote.asset_amount,
+    asset_id: hexOf(quote.asset_spec?.id),
+    channel: shortChannelIdAsChannel(quote.scid),
+    expires_at: dateFrom(quote.expiry),
+    group_key: hexOf(quote.asset_spec?.group_pub_key),
+    id: quote.id.toString('hex'),
+    min_transportable_mtokens: quote.min_transportable_msat,
+    peer_public_key: quote.peer,
+    price_oracle_metadata: quote.price_oracle_metadata || undefined,
+    rate: fixedPointAsDecimal(quote.bid_asset_rate),
+  };
+};

package/src/tapd_responses/rpc_send_event_as_send_event.ts

@@ -0,0 +1,245 @@
+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';
+import rpcTransferAsTransfer from './rpc_transfer_as_transfer.js';
+import type {RpcTransfer} from './rpc_transfer_as_transfer.js';
+import type {Transfer} from './rpc_transfer_as_transfer.js';
+
+const hexOf = (n?: Buffer | null) =>
+  !n?.length ? undefined : n.toString('hex');
+const {isArray} = Array;
+const isBuffer = (n: unknown): n is Buffer => Buffer.isBuffer(n);
+const isNumeric = (n: unknown) => typeof n === 'string' && /^-?\d+$/.test(n);
+const microsPerMs = 1e3;
+const noChange = -1;
+const parcelTypes: Record<string, SendEvent['parcel_type']> = {
+  PARCEL_TYPE_ADDRESS: 'address',
+  PARCEL_TYPE_PENDING: 'pending',
+  PARCEL_TYPE_PRE_ANCHORED: 'pre_anchored',
+  PARCEL_TYPE_PRE_SIGNED: 'pre_signed',
+};
+const reversedHex = (n: Buffer) => Buffer.from(n).reverse().toString('hex');
+const sendStatePrefix = 'SendState';
+const weightUnitsPerVbyte = 4;
+const weightUnitsPerKw = 1e3;
+
+export type RpcSendEvent = {
+  addresses: RpcAddr[];
+  anchor_transaction: {
+    anchor_psbt: Buffer;
+    chain_fees_sats: string;
+    change_output_index: number;
+    final_tx: Buffer;
+    lnd_locked_utxos: {output_index: number; txid: Buffer}[];
+    target_fee_rate_sat_kw: number;
+  } | null;
+  error: string;
+  next_send_state: string;
+  parcel_type: string;
+  passive_virtual_packets: Buffer[];
+  send_state: string;
+  timestamp: string;
+  transfer: RpcTransfer | null;
+  transfer_label: string;
+  virtual_packets: Buffer[];
+};
+
+export type SendEvent = {
+  /** Recipient Addresses */
+  addresses: Address[];
+  anchor?: {
+    /** Change Output Index */
+    change_output_index?: number;
+    /** Chain Fee Tokens */
+    fee: number;
+    /** Target Fee Tokens Per Virtual Byte */
+    fee_tokens_per_vbyte: number;
+    locked_utxos: {
+      /** Locked Transaction Id Hex */
+      transaction_id: string;
+      /** Locked Transaction Output Index */
+      transaction_vout: number;
+    }[];
+    /** Anchor Transaction PSBT Hex */
+    psbt: string;
+    /** Signed Anchor Transaction Hex */
+    transaction?: string;
+  };
+  /** Event At ISO 8601 Date */
+  at: string;
+  /** Send State Error */
+  error?: string;
+  /** Transfer Label */
+  label?: string;
+  /** Next Send State */
+  next_state?: string;
+  /** Parcel Type */
+  parcel_type: 'address' | 'pending' | 'pre_anchored' | 'pre_signed';
+  /** Passive Virtual Packets Hex */
+  passive_virtual_packets: string[];
+  /** Executed Send State */
+  state: string;
+  /** Transfer */
+  transfer?: Transfer;
+  /** Virtual Packets Hex */
+  virtual_packets: string[];
+};
+
+/** Send state name from a tapd send state
+
+  For example SendStateAnchorSign becomes anchor_sign
+
+  <tapd Send State String>
+
+  @returns
+  <Send State Name String>
+*/
+const stateFrom = (state: string) => {
+  // Exit early when the state does not have the known format
+  if (!state.startsWith(sendStatePrefix)) {
+    return state;
+  }
+
+  return state
+    .slice(sendStatePrefix.length)
+    .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+    .toLowerCase();
+};
+
+/** Send event from an RPC send event
+
+  {
+    addresses: [<RPC Address Object>]
+    [anchor_transaction]: {
+      anchor_psbt: <Anchor Transaction PSBT Buffer Object>
+      chain_fees_sats: <Chain Fee Satoshis Numeric String>
+      change_output_index: <Change Output Index Number> // -1 is no change
+      final_tx: <Signed Anchor Transaction Buffer Object>
+      lnd_locked_utxos: [{
+        output_index: <Output Index Number>
+        txid: <Transaction Id Internal Order Buffer Object>
+      }]
+      target_fee_rate_sat_kw: <Target Fee Rate Satoshis Per Kw Number>
+    }
+    error: <Send State Error String>
+    next_send_state: <Next Send State String>
+    parcel_type: <Parcel Type String>
+    passive_virtual_packets: [<Passive Virtual Packet Buffer Object>]
+    send_state: <Executed Send State String>
+    timestamp: <Event At Unix Microseconds Numeric String>
+    [transfer]: <RPC Transfer Object>
+    transfer_label: <Transfer Label String>
+    virtual_packets: [<Virtual Packet Buffer Object>]
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  {
+    addresses: [<Address Object>]
+    [anchor]: {
+      [change_output_index]: <Change Output Index Number>
+      fee: <Chain Fee Tokens Number>
+      fee_tokens_per_vbyte: <Target Fee Tokens Per Virtual Byte Number>
+      locked_utxos: [{
+        transaction_id: <Locked Transaction Id Hex String>
+        transaction_vout: <Locked Transaction Output Index Number>
+      }]
+      psbt: <Anchor Transaction PSBT Hex String>
+      [transaction]: <Signed Anchor Transaction Hex String>
+    }
+    at: <Event At ISO 8601 Date String>
+    [error]: <Send State Error String>
+    [label]: <Transfer Label String>
+    [next_state]: <Next Send State String>
+    parcel_type: <Parcel Type String> // address, pending, pre_anchored, ...
+    passive_virtual_packets: [<Passive Virtual Packet Hex String>]
+    state: <Executed Send State String>
+    [transfer]: <Transfer Object>
+    virtual_packets: [<Virtual Packet Hex String>]
+  }
+*/
+export default (event?: RpcSendEvent | null): SendEvent => {
+  if (!event) {
+    throw new Error('ExpectedRpcSendEventDetails');
+  }
+
+  if (!isArray(event.addresses)) {
+    throw new Error('ExpectedArrayOfAddressesInRpcSendEvent');
+  }
+
+  if (!parcelTypes[event.parcel_type]) {
+    throw new Error('ExpectedKnownParcelTypeInRpcSendEvent');
+  }
+
+  if (!event.send_state) {
+    throw new Error('ExpectedSendStateInRpcSendEvent');
+  }
+
+  if (!isNumeric(event.timestamp)) {
+    throw new Error('ExpectedTimestampInRpcSendEvent');
+  }
+
+  if (!isArray(event.virtual_packets)) {
+    throw new Error('ExpectedArrayOfVirtualPacketsInRpcSendEvent');
+  }
+
+  if (!isArray(event.passive_virtual_packets)) {
+    throw new Error('ExpectedArrayOfPassivePacketsInRpcSendEvent');
+  }
+
+  const anchor = event.anchor_transaction;
+
+  if (!!anchor && !isBuffer(anchor.anchor_psbt)) {
+    throw new Error('ExpectedAnchorPsbtInRpcSendEvent');
+  }
+
+  if (!!anchor && !isNumeric(anchor.chain_fees_sats)) {
+    throw new Error('ExpectedChainFeesInRpcSendEvent');
+  }
+
+  if (!!anchor && !isArray(anchor.lnd_locked_utxos)) {
+    throw new Error('ExpectedArrayOfLockedUtxosInRpcSendEvent');
+  }
+
+  const at = new Date(Math.floor(Number(event.timestamp) / microsPerMs));
+  const feeRate = anchor?.target_fee_rate_sat_kw || 0;
+
+  return {
+    addresses: event.addresses.map(rpcAddrAsAddress),
+    anchor: !anchor
+      ? undefined
+      : {
+          change_output_index:
+            anchor.change_output_index === noChange
+              ? undefined
+              : anchor.change_output_index,
+          fee: Number(anchor.chain_fees_sats),
+          fee_tokens_per_vbyte:
+            (feeRate * weightUnitsPerVbyte) / weightUnitsPerKw,
+          // tapd sends the locked transaction ids in internal byte order
+          locked_utxos: anchor.lnd_locked_utxos.map(utxo => ({
+            transaction_id: reversedHex(utxo.txid),
+            transaction_vout: utxo.output_index,
+          })),
+          psbt: anchor.anchor_psbt.toString('hex'),
+          transaction: hexOf(anchor.final_tx),
+        },
+    at: at.toISOString(),
+    error: event.error || undefined,
+    label: event.transfer_label || undefined,
+    next_state: !event.next_send_state
+      ? undefined
+      : stateFrom(event.next_send_state),
+    parcel_type: parcelTypes[event.parcel_type],
+    passive_virtual_packets: event.passive_virtual_packets.map(n => {
+      return n.toString('hex');
+    }),
+    state: stateFrom(event.send_state),
+    transfer: !event.transfer
+      ? undefined
+      : rpcTransferAsTransfer(event.transfer),
+    virtual_packets: event.virtual_packets.map(n => n.toString('hex')),
+  };
+};