tapass 0.0.0-stage → 0.2.0

package/src/tapd_requests/is_connection_failure.ts

@@ -0,0 +1,48 @@
+import grpc from '@grpc/grpc-js';
+
+const connectionFailureMessages = [
+  'channel is in state transient_failure',
+  'connect failed',
+  'connection dropped',
+  'econnrefused',
+  'econnreset',
+  'failed to connect to all addresses',
+  'no connection established',
+  'server is shutting down',
+];
+
+const isString = (n: unknown) => typeof n === 'string';
+const unavailableCode = grpc.status.UNAVAILABLE;
+
+type Err = {code?: number; details?: string; message?: string};
+
+/** Determine if an error represents a failure to connect to the daemon
+
+  {
+    [err]: {
+      [code]: <gRPC Status Code Number>
+      [details]: <gRPC Status Details String>
+      [message]: <Error Message String>
+    }
+  }
+
+  @returns
+  <Is Connection Failure Bool>
+*/
+export default ({err}: {err?: Err | null}) => {
+  // Exit early when there is no error
+  if (!err) {
+    return false;
+  }
+
+  // Exit early when the connection is reported as unavailable
+  if (err.code === unavailableCode) {
+    return true;
+  }
+
+  const text = [err.details, err.message].filter(isString).join(' ');
+
+  const normalized = text.toLowerCase();
+
+  return !!connectionFailureMessages.find(n => normalized.includes(n));
+};

package/src/tapd_requests/is_method_unsupported.ts

@@ -0,0 +1,33 @@
+import grpc from '@grpc/grpc-js';
+
+const unimplementedCode = grpc.status.UNIMPLEMENTED;
+const unknownRequestText = 'unknown request';
+
+type Err = {code?: number; details?: string};
+
+/** Determine if an error shows that the daemon does not have the RPC
+
+  A standalone tapd returns the unimplemented status. litd returns an unknown
+  request error for an RPC that is not in its permissions list.
+
+  {
+    [err]: {
+      [code]: <gRPC Status Code Number>
+      [details]: <gRPC Status Details String>
+    }
+  }
+
+  @returns
+  <Is Method Unsupported Bool>
+*/
+export default ({err}: {err?: Err | null}) => {
+  // Exit early when there is no error
+  if (!err) {
+    return false;
+  }
+
+  return (
+    err.code === unimplementedCode ||
+    String(err.details).includes(unknownRequestText)
+  );
+};

package/src/tapd_requests/is_permission_denied.ts

@@ -0,0 +1,18 @@
+const permissionDeniedText = 'permission denied';
+
+type Err = {details?: string};
+
+/** Determine if an error is a macaroon permission failure
+
+  {
+    [err]: {
+      [details]: <gRPC Status Details String>
+    }
+  }
+
+  @returns
+  <Is Permission Denied Bool>
+*/
+export default ({err}: {err?: Err | null}) => {
+  return String(err?.details).includes(permissionDeniedText);
+};

package/src/tapd_requests/is_tapd.ts

@@ -0,0 +1,22 @@
+type Args = {
+  method: string;
+  tapd?: unknown;
+  type: string;
+};
+
+/** Determine if object is an expected tapd Object
+
+  {
+    method: <Method Name String>
+    [tapd]: <tapd Object>
+    type: <Method Type String>
+  }
+
+  @returns
+  <Is Expected tapd Object Bool>
+*/
+export default ({method, tapd, type}: Args) => {
+  const service = (tapd as Record<string, Record<string, unknown>>)?.[type];
+
+  return !!service && typeof service[method] === 'function';
+};

package/src/tapd_requests/mint_funding_request.ts

@@ -0,0 +1,57 @@
+import feeRateAsTokensPerKw from './fee_rate_as_tokens_per_kw.js';
+
+type Args = {
+  /** Fee Tokens Per Virtual Byte Number */
+  fee_tokens_per_vbyte?: number;
+  /** Tapscript Branch Hashes */
+  tapscript_branch?: {left: string; right: string};
+  /** Tapscript Leaf Scripts Hex Strings */
+  tapscript_leaves?: string[];
+};
+
+/** Fee rate and tapscript sibling fields of a fund or finalize request
+
+  The fee rate converts from tokens per vbyte to tokens per kiloweight, and it
+  is never below the fee rate floor of 253 tokens per kiloweight
+
+  {
+    [fee_tokens_per_vbyte]: <Fee Tokens Per Virtual Byte Number>
+    [tapscript_branch]: {
+      left: <Left Tap Branch Hash Hex String>
+      right: <Right Tap Branch Hash Hex String>
+    }
+    [tapscript_leaves]: [<Tapscript Leaf Script Hex String>]
+  }
+
+  @returns
+  {
+    [branch]: {
+      left_taphash: <Left Tap Branch Hash Buffer Object>
+      right_taphash: <Right Tap Branch Hash Buffer Object>
+    }
+    fee_rate: <Fee Tokens Per Kiloweight Number> // 0 is the tapd default
+    [full_tree]: {
+      all_leaves: [{
+        script: <Tapscript Leaf Script Buffer Object>
+      }]
+    }
+  }
+*/
+export default (args: Args) => {
+  return {
+    branch: !args.tapscript_branch
+      ? undefined
+      : {
+          left_taphash: Buffer.from(args.tapscript_branch.left, 'hex'),
+          right_taphash: Buffer.from(args.tapscript_branch.right, 'hex'),
+        },
+    fee_rate: feeRateAsTokensPerKw(args.fee_tokens_per_vbyte),
+    full_tree: !args.tapscript_leaves
+      ? undefined
+      : {
+          all_leaves: args.tapscript_leaves.map(script => ({
+            script: Buffer.from(script, 'hex'),
+          })),
+        },
+  };
+};

package/src/tapd_requests/script_key_type_query.ts

@@ -0,0 +1,44 @@
+const allTypes = 'all';
+const types: Record<string, string> = {
+  bip86: 'SCRIPT_KEY_BIP86',
+  burn: 'SCRIPT_KEY_BURN',
+  channel: 'SCRIPT_KEY_CHANNEL',
+  script_path_external: 'SCRIPT_KEY_SCRIPT_PATH_EXTERNAL',
+  tombstone: 'SCRIPT_KEY_TOMBSTONE',
+  unique_pedersen: 'SCRIPT_KEY_UNIQUE_PEDERSEN',
+};
+
+/** Script key type query from a script key type
+
+  When there is no type, tapd uses only BIP-86 script keys
+
+  <Script Key Type String> // all, bip86, burn, channel, script_path_external,
+                           // tombstone, unique_pedersen
+
+  @throws
+  <Error>
+
+  @returns
+  {
+    [all_types]: <All Script Key Types Bool>
+    [explicit_type]: <Script Key Type String>
+  }
+  or <Undefined> // when there is no type
+*/
+export default (type?: string) => {
+  // Exit early when there is no type, tapd then uses only BIP-86 keys
+  if (type === undefined) {
+    return undefined;
+  }
+
+  // Exit early when the query is for each type of script key
+  if (type === allTypes) {
+    return {all_types: true};
+  }
+
+  if (!types[type]) {
+    throw new Error('ExpectedKnownScriptKeyType');
+  }
+
+  return {explicit_type: types[type]};
+};

package/src/tapd_responses/asset_channel_rpc_error.ts

@@ -0,0 +1,73 @@
+import type {TapdError} from '../typescript/index.js';
+
+// Each text is from the tapd v0.8.5 tapchannel RPC server
+const knownErrors: {details: string; error: TapdError}[] = [
+  {
+    details: 'only available when running inside Lightning Terminal daemon',
+    error: [501, 'ExpectedTapdInsideLitdForAssetChannels'],
+  },
+  {
+    details: 'no asset channels available for quote negotiation',
+    error: [503, 'NoAssetChannelForQuoteNegotiation'],
+  },
+  {
+    details: 'error finding asset channel to use',
+    error: [503, 'NoAssetChannelToUse'],
+  },
+  {
+    details: 'does not support asset channels',
+    error: [503, 'PeerDoesNotSupportAssetChannels'],
+  },
+  {
+    details: 'unable to query peer feature bits: peer not found',
+    error: [503, 'ExpectedConnectedPeerForAssetChannel'],
+  },
+  {
+    details: 'error acquiring buy order for invoice',
+    error: [503, 'FailedToGetAssetBuyQuoteForInvoice'],
+  },
+  {
+    details: 'with sufficient expiry for the requested invoice expiry',
+    error: [503, 'NoAssetQuoteWithSufficientExpiryForInvoice'],
+  },
+  {
+    details: 'failed to acquire any quotes',
+    error: [503, 'FailedToGetAssetSellQuoteForPayment'],
+  },
+  {
+    details: 'quote ID did not match an accepted quote',
+    error: [404, 'AcceptedQuoteNotFoundForRfqId'],
+  },
+  {
+    details: 'rejecting payment of',
+    error: [400, 'ExpectedOverpayAllowedForSmallAssetPayment'],
+  },
+  {details: 'price oracle is not set', error: [503, 'PriceOracleIsNotSet']},
+  {
+    details: 'no genesis found for decoded asset',
+    error: [404, 'AssetNotFound'],
+  },
+  {details: 'error parsing group', error: [400, 'ExpectedValidGroupKey']},
+];
+
+/** Known error from a tapd asset channel RPC error
+
+  {
+    [err]: {
+      [details]: <gRPC Status Details String>
+    }
+  }
+
+  @returns
+  <Known Error Array> or <Undefined>
+*/
+export default ({err}: {err?: {details?: unknown} | null}) => {
+  // Exit early when there is no error
+  if (!err) {
+    return undefined;
+  }
+
+  const details = String(err.details);
+
+  return knownErrors.find(known => details.includes(known.details))?.error;
+};

package/src/tapd_responses/batch_states.ts

@@ -0,0 +1,12 @@
+/** Mint batch state names for the tapd batch states */
+export default {
+  BATCH_STATE_BROADCAST: 'broadcast',
+  BATCH_STATE_COMMITTED: 'committed',
+  BATCH_STATE_CONFIRMED: 'confirmed',
+  BATCH_STATE_FINALIZED: 'finalized',
+  BATCH_STATE_FROZEN: 'frozen',
+  BATCH_STATE_PENDING: 'pending',
+  BATCH_STATE_SEEDLING_CANCELLED: 'seedling_cancelled',
+  BATCH_STATE_SPROUT_CANCELLED: 'sprout_cancelled',
+  BATCH_STATE_UNKNOWN: 'unknown',
+} as Record<string, string>;

package/src/tapd_responses/fixed_point_as_decimal.ts

@@ -0,0 +1,51 @@
+const isDigits = (n: unknown): n is string =>
+  typeof n === 'string' && /^\d+$/.test(n);
+const {isSafeInteger} = Number;
+
+export type RpcFixedPoint = {
+  coefficient: string;
+  scale: number;
+};
+
+/** Exact decimal string from an RPC fixed point number
+
+  The value is the coefficient divided by 10 to the power of the scale. The
+  decimal string has exactly `scale` decimal places, so it keeps the scale.
+
+  For example, coefficient 12345 with scale 2 is "123.45"
+
+  {
+    coefficient: <Scaled Integer Numeric String>
+    scale: <Decimal Places Number>
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  <Exact Decimal String>
+*/
+export default (fixedPoint?: RpcFixedPoint | null) => {
+  if (!fixedPoint) {
+    throw new Error('ExpectedRpcFixedPointNumber');
+  }
+
+  if (!isDigits(fixedPoint.coefficient)) {
+    throw new Error('ExpectedNumericCoefficientInRpcFixedPoint');
+  }
+
+  if (!isSafeInteger(fixedPoint.scale) || fixedPoint.scale < 0) {
+    throw new Error('ExpectedScaleInRpcFixedPoint');
+  }
+
+  const {scale} = fixedPoint;
+
+  // Exit early when there are no decimal places
+  if (!scale) {
+    return fixedPoint.coefficient;
+  }
+
+  const digits = fixedPoint.coefficient.padStart(scale + 1, '0');
+
+  return `${digits.slice(0, -scale)}.${digits.slice(-scale)}`;
+};

package/src/tapd_responses/index.ts

@@ -0,0 +1,75 @@
+export {default as assetChannelRpcError} from './asset_channel_rpc_error.js';
+export {default as batchStates} from './batch_states.js';
+export {default as fixedPointAsDecimal} from './fixed_point_as_decimal.js';
+export type {RpcFixedPoint} from './fixed_point_as_decimal.js';
+export {default as longKeyAsNumber} from './long_key_as_number.js';
+export {default as mintRpcError} from './mint_rpc_error.js';
+export {default as outpointAsTransaction} from './outpoint_as_transaction.js';
+export {default as receiveStatuses} from './receive_statuses.js';
+export {default as rpcAddrAsAddress} from './rpc_addr_as_address.js';
+export type {Address} from './rpc_addr_as_address.js';
+export type {RpcAddr} from './rpc_addr_as_address.js';
+export {default as rpcAddrEventAsReceive} from './rpc_addr_event_as_receive.js';
+export type {Receive} from './rpc_addr_event_as_receive.js';
+export type {RpcAddrEvent} from './rpc_addr_event_as_receive.js';
+export {default as rpcAssetAmountAsAmount} from './rpc_asset_amount_as_amount.js';
+export type {AssetAmount} from './rpc_asset_amount_as_amount.js';
+export type {RpcAssetAmount} from './rpc_asset_amount_as_amount.js';
+export {default as rpcAssetAsAsset} from './rpc_asset_as_asset.js';
+export type {Asset} from './rpc_asset_as_asset.js';
+export type {RpcAsset} from './rpc_asset_as_asset.js';
+export {default as rpcAssetBalanceAsBalance} from './rpc_asset_balance_as_balance.js';
+export type {Balance} from './rpc_asset_balance_as_balance.js';
+export type {RpcAssetBalance} from './rpc_asset_balance_as_balance.js';
+export {default as rpcAssetBurnAsBurn} from './rpc_asset_burn_as_burn.js';
+export type {Burn} from './rpc_asset_burn_as_burn.js';
+export type {RpcAssetBurn} from './rpc_asset_burn_as_burn.js';
+export {default as rpcAssetInvoiceAsInvoice} from './rpc_asset_invoice_as_invoice.js';
+export type {AssetInvoice} from './rpc_asset_invoice_as_invoice.js';
+export type {RpcAssetInvoice} from './rpc_asset_invoice_as_invoice.js';
+export {default as rpcAssetMetaAsMetadata} from './rpc_asset_meta_as_metadata.js';
+export type {Metadata} from './rpc_asset_meta_as_metadata.js';
+export type {RpcAssetMeta} from './rpc_asset_meta_as_metadata.js';
+export {default as rpcAssetPayReqAsRequest} from './rpc_asset_pay_req_as_request.js';
+export type {AssetPaymentRequest} from './rpc_asset_pay_req_as_request.js';
+export type {RpcAssetPayReq} from './rpc_asset_pay_req_as_request.js';
+export {default as rpcAssetPaymentAsPayment} from './rpc_asset_payment_as_payment.js';
+export type {AssetPayment} from './rpc_asset_payment_as_payment.js';
+export type {RpcAssetPayment} from './rpc_asset_payment_as_payment.js';
+export {default as rpcBatchAsBatch} from './rpc_batch_as_batch.js';
+export type {Batch} from './rpc_batch_as_batch.js';
+export type {PendingAsset} from './rpc_batch_as_batch.js';
+export type {RpcMintingBatch} from './rpc_batch_as_batch.js';
+export type {RpcVerboseBatch} from './rpc_batch_as_batch.js';
+export {default as rpcBuyQuoteAsQuote} from './rpc_buy_quote_as_quote.js';
+export type {BuyQuote} from './rpc_buy_quote_as_quote.js';
+export type {RpcAssetSpec} from './rpc_buy_quote_as_quote.js';
+export type {RpcBuyQuote} from './rpc_buy_quote_as_quote.js';
+export {default as rpcDecodedProofAsProof} from './rpc_decoded_proof_as_proof.js';
+export type {Proof} from './rpc_decoded_proof_as_proof.js';
+export type {RpcDecodedProof} from './rpc_decoded_proof_as_proof.js';
+export {default as rpcForwardAsAssetForward} from './rpc_forward_as_asset_forward.js';
+export type {AssetForward} from './rpc_forward_as_asset_forward.js';
+export type {RpcForwardingEvent} from './rpc_forward_as_asset_forward.js';
+export {default as rpcGroupedAssetsAsGroup} from './rpc_grouped_assets_as_group.js';
+export type {Group} from './rpc_grouped_assets_as_group.js';
+export type {RpcGroupedAssets} from './rpc_grouped_assets_as_group.js';
+export {default as rpcManagedUtxoAsUtxo} from './rpc_managed_utxo_as_utxo.js';
+export type {RpcManagedUtxo} from './rpc_managed_utxo_as_utxo.js';
+export type {Utxo} from './rpc_managed_utxo_as_utxo.js';
+export {default as rpcReceiveEventAsReceiveUpdate} from './rpc_receive_event_as_receive_update.js';
+export type {ReceiveUpdate} from './rpc_receive_event_as_receive_update.js';
+export type {RpcReceiveEvent} from './rpc_receive_event_as_receive_update.js';
+export {default as rpcRfqEventAsEvent} from './rpc_rfq_event_as_event.js';
+export type {RfqEvent} from './rpc_rfq_event_as_event.js';
+export type {RpcRfqEvent} from './rpc_rfq_event_as_event.js';
+export {default as rpcSellQuoteAsQuote} from './rpc_sell_quote_as_quote.js';
+export type {RpcSellQuote} from './rpc_sell_quote_as_quote.js';
+export type {SellQuote} from './rpc_sell_quote_as_quote.js';
+export {default as rpcSendEventAsSendEvent} from './rpc_send_event_as_send_event.js';
+export type {RpcSendEvent} from './rpc_send_event_as_send_event.js';
+export type {SendEvent} from './rpc_send_event_as_send_event.js';
+export {default as rpcTransferAsTransfer} from './rpc_transfer_as_transfer.js';
+export type {RpcTransfer} from './rpc_transfer_as_transfer.js';
+export type {Transfer} from './rpc_transfer_as_transfer.js';
+export {default as shortChannelIdAsChannel} from './short_channel_id_as_channel.js';

package/src/tapd_responses/long_key_as_number.ts

@@ -0,0 +1,31 @@
+const isDecimal = (n: string) => /^\d+$/.test(n);
+const longBitsHashLength = 8;
+const maxByte = 255;
+
+/** Decimal number string from a 64 bit map key of a decoded protobuf message
+
+  protobufjs decodes a uint64 map key as an 8 character hash string. Each
+  character is a byte, in little-endian order.
+
+  <Map Key String>
+
+  @throws
+  <Error>
+
+  @returns
+  <Decimal Number String>
+*/
+export default (key: string) => {
+  // Exit early when the key is already a decimal number
+  if (isDecimal(key)) {
+    return key;
+  }
+
+  const bytes = Array.from({length: key.length}, (_, i) => key.charCodeAt(i));
+
+  if (bytes.length !== longBitsHashLength || bytes.some(n => n > maxByte)) {
+    throw new Error('ExpectedLongBitsHashMapKey');
+  }
+
+  return Buffer.from(bytes).readBigUInt64LE().toString();
+};

package/src/tapd_responses/mint_rpc_error.ts

@@ -0,0 +1,39 @@
+import type {TapdError} from '../typescript/index.js';
+
+const knownErrors: {details: string; error: TapdError}[] = [
+  {details: 'no pending batch', error: [404, 'PendingMintBatchNotFound']},
+  {details: 'batch already funded', error: [400, 'MintBatchIsAlreadyFunded']},
+  {details: 'batch is not funded', error: [400, 'ExpectedFundedMintBatch']},
+  {details: 'no seedlings in batch', error: [400, 'ExpectedAssetsInMintBatch']},
+  {
+    details: 'manual fee rate below floor',
+    error: [400, 'ExpectedHigherFeeRateForMintBatch'],
+  },
+  {
+    details: 'feerate does not meet minrelayfee',
+    error: [400, 'ExpectedHigherFeeRateForMintBatch'],
+  },
+  {details: 'invalid asset name', error: [400, 'ExpectedValidAssetName']},
+];
+
+/** Known error from a mint RPC error
+
+  {
+    [err]: {
+      [details]: <gRPC Status Details String>
+    }
+  }
+
+  @returns
+  <Known Error Array> or <Undefined>
+*/
+export default ({err}: {err?: {details?: unknown} | null}) => {
+  // Exit early when there is no error
+  if (!err) {
+    return undefined;
+  }
+
+  const details = String(err.details);
+
+  return knownErrors.find(known => details.includes(known.details))?.error;
+};

package/src/tapd_responses/outpoint_as_transaction.ts

@@ -0,0 +1,25 @@
+const isTransactionId = (n: string) => /^[0-9a-f]{64}$/i.test(n);
+const isVout = (n: string) => /^\d+$/.test(n);
+
+/** Transaction id and output index from an outpoint string
+
+  <Outpoint String> // txid:vout
+
+  @throws
+  <Error>
+
+  @returns
+  {
+    transaction_id: <Transaction Id Hex String>
+    transaction_vout: <Transaction Output Index Number>
+  }
+*/
+export default (outpoint: string) => {
+  const [id, vout, ...extra] = outpoint.split(':');
+
+  if (!id || !isTransactionId(id) || !vout || !isVout(vout) || !!extra.length) {
+    throw new Error('ExpectedOutpointWithTransactionIdAndOutputIndex');
+  }
+
+  return {transaction_id: id, transaction_vout: Number(vout)};
+};

package/src/tapd_responses/receive_statuses.ts

@@ -0,0 +1,8 @@
+/** Receive status types by tapd address event status */
+export default {
+  ADDR_EVENT_STATUS_COMPLETED: 'completed',
+  ADDR_EVENT_STATUS_PROOF_RECEIVED: 'proof_received',
+  ADDR_EVENT_STATUS_TRANSACTION_CONFIRMED: 'transaction_confirmed',
+  ADDR_EVENT_STATUS_TRANSACTION_DETECTED: 'transaction_detected',
+  ADDR_EVENT_STATUS_UNKNOWN: 'unknown',
+} as Record<string, string>;