tapass 0.0.0-stage → 0.2.0

package/src/tapd_methods/channels/decode_asset_payment_request.ts

@@ -0,0 +1,192 @@
+import {auto as asyncAuto} from 'async';
+import {returnResult} from 'asyncjs-util';
+
+import {isConnectionFailure} from '../../tapd_requests/index.js';
+import {isPermissionDenied} from '../../tapd_requests/index.js';
+import {isTapd} from '../../tapd_requests/index.js';
+import {assetChannelRpcError} from '../../tapd_responses/index.js';
+import {rpcAssetPayReqAsRequest} from '../../tapd_responses/index.js';
+import type {AssetPaymentRequest} from '../../tapd_responses/index.js';
+import type {AuthenticatedTapdArgs} from '../../typescript/index.js';
+import type {TapdCallback} from '../../typescript/index.js';
+import type {TapdError} from '../../typescript/index.js';
+import type {TapdMethod} from '../../typescript/index.js';
+
+const {from} = Buffer;
+const isAssetId = (n: string) => /^[0-9A-F]{64}$/i.test(n);
+// tapd reads a 32 byte or a 33 byte group key here
+const isGroupKey = (n: string) => /^(0[23])?[0-9A-F]{64}$/i.test(n);
+const maxMetadataBytes = 32768;
+const method = 'decodeAssetPayReq';
+const type = 'tapchannel';
+
+export type DecodeAssetPaymentRequestArgs = AuthenticatedTapdArgs<{
+  /** Asset Id Hex String */
+  asset_id?: string;
+  /** Asset Group Key Hex String */
+  group_key?: string;
+  /** Price Oracle Metadata String */
+  price_oracle_metadata?: string;
+  /** BOLT 11 Payment Request String */
+  request: string;
+}>;
+
+export type DecodeAssetPaymentRequestResult = AssetPaymentRequest;
+
+type Tasks = {
+  decode: DecodeAssetPaymentRequestResult;
+  validate: undefined;
+};
+
+/** Decode a payment request and get its amount in units of an asset
+
+  tapd asks its price oracle for the asset rate
+
+  Requires `channels:read` permission
+
+  An `asset_id` or a `group_key` is required, but not both
+
+  {
+    [asset_id]: <Asset Id Hex String>
+    [group_key]: <Asset Group Key Hex String>
+    [price_oracle_metadata]: <Price Oracle Metadata String>
+    request: <BOLT 11 Payment Request String>
+    tapd: <Authenticated tapd API Object>
+  }
+
+  @returns via cbk or Promise
+  {
+    asset: {
+      amount: <Asset Units To Pay Numeric String>
+      [decimal_display]: <Decimal Places To Show Number>
+      [group_key]: <Asset Group Key Hex String>
+      id: <Asset Id Hex String>
+      is_collectible: <Asset Is Collectible Bool>
+      meta_hash: <Asset Metadata Hash Hex String>
+      name: <Asset Name String>
+    }
+    chain_address: <Fallback Chain Address String>
+    [cltv_delta]: <Final CLTV Delta Number>
+    created_at: <Payment Request Created At ISO 8601 Date String>
+    description: <Payment Description String>
+    description_hash: <Payment Longer Description Hash Hex String>
+    destination: <Public Key Hex String>
+    expires_at: <ISO 8601 Date String>
+    features: [{
+      bit: <BOLT 09 Feature Bit Number>
+      is_known: <Feature is Known Bool>
+      is_required: <Feature Support is Required To Pay Bool>
+      type: <Feature Type String>
+    }]
+    id: <Payment Hash Hex String>
+    is_expired: <Invoice is Expired Bool>
+    mtokens: <Requested Millitokens String>
+    [payment]: <Payment Identifier Hex Encoded String>
+    routes: [[{
+      [base_fee_mtokens]: <Base Routing Fee In Millitokens String>
+      [channel]: <Standard Format Channel Id String>
+      [cltv_delta]: <CLTV Blocks Delta Number>
+      [fee_rate]: <Fee Rate In Millitokens Per Million Number>
+      public_key: <Forward Edge Public Key Hex String>
+    }]]
+    safe_tokens: <Requested Tokens Rounded Up Number>
+    tokens: <Requested Tokens Rounded Down Number>
+  }
+*/
+const decodeAssetPaymentRequest: TapdMethod<
+  DecodeAssetPaymentRequestArgs,
+  DecodeAssetPaymentRequestResult
+> = (
+  args: DecodeAssetPaymentRequestArgs,
+  cbk?: TapdCallback<DecodeAssetPaymentRequestResult>,
+) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto<Tasks, TapdError>(
+      {
+        // Check arguments
+        validate: cbk => {
+          if (!args.asset_id && !args.group_key) {
+            return cbk([400, 'ExpectedAssetIdOrGroupKeyToDecodeAssetRequest']);
+          }
+
+          if (!!args.asset_id && !!args.group_key) {
+            return cbk([400, 'UnexpectedAssetIdAndGroupKeyToDecodeRequest']);
+          }
+
+          if (!!args.asset_id && !isAssetId(args.asset_id)) {
+            return cbk([400, 'ExpectedAssetIdHexToDecodeAssetRequest']);
+          }
+
+          if (!!args.group_key && !isGroupKey(args.group_key)) {
+            return cbk([400, 'ExpectedGroupKeyHexToDecodeAssetRequest']);
+          }
+
+          const metadata = args.price_oracle_metadata || '';
+
+          if (Buffer.byteLength(metadata) > maxMetadataBytes) {
+            return cbk([400, 'ExpectedShorterOracleMetadataToDecodeRequest']);
+          }
+
+          if (!args.request || typeof args.request !== 'string') {
+            return cbk([400, 'ExpectedPaymentRequestToDecodeAssetRequest']);
+          }
+
+          if (!isTapd({method, type, tapd: args.tapd})) {
+            return cbk([400, 'ExpectedAuthenticatedTapdToDecodeAssetRequest']);
+          }
+
+          return cbk();
+        },
+
+        // Decode the payment request
+        decode: [
+          'validate',
+          ({}, cbk) => {
+            const request = {
+              asset_id: from(args.asset_id || '', 'hex'),
+              group_key: from(args.group_key || '', 'hex'),
+              pay_req_string: args.request,
+              price_oracle_metadata: args.price_oracle_metadata || '',
+            };
+
+            return args.tapd[type][method](request, (err: any, res: any) => {
+              if (isConnectionFailure({err})) {
+                return cbk([503, 'FailedToConnectToTapdToDecodeAssetRequest']);
+              }
+
+              if (isPermissionDenied({err})) {
+                return cbk([
+                  403,
+                  'PermissionDeniedToDecodeAssetPaymentRequest',
+                ]);
+              }
+
+              const knownError = assetChannelRpcError({err});
+
+              if (!!knownError) {
+                return cbk(knownError);
+              }
+
+              if (!!err) {
+                return cbk([
+                  503,
+                  'UnexpectedErrorDecodingAssetPaymentRequest',
+                  {err},
+                ]);
+              }
+
+              try {
+                return cbk(null, rpcAssetPayReqAsRequest(res));
+              } catch (err: any) {
+                return cbk([503, err.message]);
+              }
+            });
+          },
+        ],
+      },
+      returnResult({reject, resolve, of: 'decode'}, cbk),
+    );
+  });
+};
+
+export default decodeAssetPaymentRequest;

package/src/tapd_methods/channels/emit_asset_payment.ts

@@ -0,0 +1,78 @@
+import type {EventEmitter} from 'node:events';
+
+import {confirmedFromPayment} from 'lightning/lnd_responses/index.js';
+import {failureFromPayment} from 'lightning/lnd_responses/index.js';
+import {pendingFromPayment} from 'lightning/lnd_responses/index.js';
+
+import {rpcAssetAmountAsAmount} from '../../tapd_responses/index.js';
+
+const confirmedStatus = 'SUCCEEDED';
+const failedStatus = 'FAILED';
+const {isArray} = Array;
+const pendingStatus = 'IN_FLIGHT';
+
+type Args = {
+  /** RPC Asset Payment Object */
+  data: any;
+  /** Event Emitter Object */
+  emitter: EventEmitter;
+  /** Emit Error Function */
+  emitError: (err: unknown) => void;
+};
+
+/** Emit an asset payment update as a lightning payment event
+
+  The events are the same as in lightning subscribeToPastPayment, with the
+  asset amounts of the payment added as `assets`
+
+  {
+    data: {
+      asset_amounts: [<RPC Asset Amount Object>]
+      payment: <RPC lnd Payment Object>
+    }
+    emitter: <Event Emitter Object>
+    emitError: <Emit Error Function>
+  }
+
+  @event 'confirmed'
+  @event 'failed'
+  @event 'paying'
+*/
+export default ({data, emitter, emitError}: Args) => {
+  try {
+    if (!data || !isArray(data.asset_amounts) || !data.payment) {
+      throw new Error('ExpectedRpcAssetPaymentInPaymentUpdate');
+    }
+
+    const assets = data.asset_amounts.map(rpcAssetAmountAsAmount);
+    const {payment} = data;
+
+    switch (payment.status) {
+      case confirmedStatus:
+        return emitter.emit('confirmed', {
+          ...confirmedFromPayment(payment),
+          assets,
+        });
+
+      case failedStatus:
+        return emitter.emit('failed', {...failureFromPayment(payment), assets});
+
+      case pendingStatus:
+        // Exit early when no HTLC is in flight
+        if (!isArray(payment.htlcs)) {
+          return;
+        }
+
+        if (!payment.htlcs.some((n: any) => n.status === pendingStatus)) {
+          return;
+        }
+
+        return emitter.emit('paying', {...pendingFromPayment(payment), assets});
+
+      default:
+        return;
+    }
+  } catch (err: any) {
+    return emitError([503, err.message]);
+  }
+};

package/src/tapd_methods/channels/encode_asset_custom_records.ts

@@ -0,0 +1,187 @@
+import {auto as asyncAuto} from 'async';
+import {returnResult} from 'asyncjs-util';
+
+import {isConnectionFailure} from '../../tapd_requests/index.js';
+import {isPermissionDenied} from '../../tapd_requests/index.js';
+import {isTapd} from '../../tapd_requests/index.js';
+import {longKeyAsNumber} from '../../tapd_responses/index.js';
+import type {AuthenticatedTapdArgs} from '../../typescript/index.js';
+import type {TapdCallback} from '../../typescript/index.js';
+import type {TapdError} from '../../typescript/index.js';
+import type {TapdMethod} from '../../typescript/index.js';
+
+const {entries} = Object;
+const {fromEntries} = Object;
+const {isArray} = Array;
+const isAssetId = (n: unknown) => /^[0-9A-F]{64}$/i.test(String(n));
+const isBuffer = (n: unknown): n is Buffer => Buffer.isBuffer(n);
+const isNumeric = (n: unknown) => typeof n === 'string' && /^\d+$/.test(n);
+const isPositive = (n: unknown) => isNumeric(n) && BigInt(n as string) > 0;
+const isRfqId = (n: string) => /^[0-9A-F]{64}$/i.test(n);
+const method = 'encodeCustomRecords';
+const type = 'tapchannel';
+
+export type EncodeAssetCustomRecordsArgs = AuthenticatedTapdArgs<{
+  assets?: {
+    /** Asset Units Numeric String */
+    amount: string;
+    /** Asset Id Hex String */
+    asset_id: string;
+  }[];
+  /** RFQ Quote Id Hex String */
+  rfq_id?: string;
+}>;
+
+export type EncodeAssetCustomRecordsResult = {
+  records: {
+    /** Record Type Number String */
+    type: string;
+    /** Record Value Hex */
+    value: string;
+  }[];
+};
+
+type Tasks = {
+  encode: EncodeAssetCustomRecordsResult;
+  validate: undefined;
+};
+
+/** Encode the first hop custom records of an asset payment
+
+  Use the records as the first hop custom records of an lnd payment, to pay
+  with assets over an asset channel
+
+  This method does not need a permission
+
+  An `rfq_id` is for a payment that uses an accepted RFQ quote
+
+  `assets` or an `rfq_id` is required
+
+  {
+    [assets]: [{
+      amount: <Asset Units Numeric String>
+      asset_id: <Asset Id Hex String>
+    }]
+    [rfq_id]: <RFQ Quote Id Hex String>
+    tapd: <Authenticated tapd API Object>
+  }
+
+  @returns via cbk or Promise
+  {
+    records: [{
+      type: <Record Type Number String>
+      value: <Record Value Hex String>
+    }]
+  }
+*/
+const encodeAssetCustomRecords: TapdMethod<
+  EncodeAssetCustomRecordsArgs,
+  EncodeAssetCustomRecordsResult
+> = (
+  args: EncodeAssetCustomRecordsArgs,
+  cbk?: TapdCallback<EncodeAssetCustomRecordsResult>,
+) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto<Tasks, TapdError>(
+      {
+        // Check arguments
+        validate: cbk => {
+          if (!!args.assets && !isArray(args.assets)) {
+            return cbk([400, 'ExpectedArrayOfAssetsToEncodeCustomRecords']);
+          }
+
+          if (!args.assets?.length && !args.rfq_id) {
+            return cbk([400, 'ExpectedAssetsOrRfqIdToEncodeCustomRecords']);
+          }
+
+          const assets = args.assets || [];
+
+          if (assets.some(n => !isAssetId(n?.asset_id))) {
+            return cbk([400, 'ExpectedAssetIdHexToEncodeCustomRecords']);
+          }
+
+          if (assets.some(n => !isPositive(n.amount))) {
+            return cbk([400, 'ExpectedAssetAmountToEncodeCustomRecords']);
+          }
+
+          const ids = assets.map(n => n.asset_id.toLowerCase());
+
+          if (new Set(ids).size !== ids.length) {
+            return cbk([400, 'ExpectedUniqueAssetsToEncodeCustomRecords']);
+          }
+
+          if (!!args.rfq_id && !isRfqId(args.rfq_id)) {
+            return cbk([400, 'ExpectedRfqIdHexToEncodeCustomRecords']);
+          }
+
+          if (!isTapd({method, type, tapd: args.tapd})) {
+            return cbk([400, 'ExpectedAuthenticatedTapdToEncodeRecords']);
+          }
+
+          return cbk();
+        },
+
+        // Encode the records
+        encode: [
+          'validate',
+          ({}, cbk) => {
+            const assets = args.assets || [];
+
+            const request = {
+              router_send_payment: {
+                asset_amounts: fromEntries(
+                  assets.map(n => [n.asset_id.toLowerCase(), n.amount]),
+                ),
+                rfq_id: Buffer.from(args.rfq_id || '', 'hex'),
+              },
+            };
+
+            return args.tapd[type][method](request, (err: any, res: any) => {
+              if (isConnectionFailure({err})) {
+                return cbk([503, 'FailedToConnectToTapdToEncodeRecords']);
+              }
+
+              if (isPermissionDenied({err})) {
+                return cbk([403, 'PermissionDeniedToEncodeAssetCustomRecords']);
+              }
+
+              if (!!err) {
+                return cbk([
+                  503,
+                  'UnexpectedErrorEncodingAssetCustomRecords',
+                  {err},
+                ]);
+              }
+
+              if (!res || !res.custom_records) {
+                return cbk([503, 'ExpectedCustomRecordsInEncodeResponse']);
+              }
+
+              const records = entries(res.custom_records as object);
+
+              if (records.some(([, value]) => !isBuffer(value))) {
+                return cbk([503, 'ExpectedRecordValuesInEncodeResponse']);
+              }
+
+              try {
+                return cbk(null, {
+                  records: records
+                    .map(([recordType, value]) => ({
+                      type: longKeyAsNumber(recordType),
+                      value: (value as Buffer).toString('hex'),
+                    }))
+                    .sort((a, b) => (BigInt(a.type) < BigInt(b.type) ? -1 : 1)),
+                });
+              } catch (err: any) {
+                return cbk([503, err.message]);
+              }
+            });
+          },
+        ],
+      },
+      returnResult({reject, resolve, of: 'encode'}, cbk),
+    );
+  });
+};
+
+export default encodeAssetCustomRecords;