tapass 0.1.0 → 0.2.0

package/src/tapd_methods/channels/open_asset_channel.ts

@@ -0,0 +1,193 @@
+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 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);
+const isNumeric = (n: unknown) => typeof n === 'string' && /^\d+$/.test(n);
+const isPositive = (n: string) => isNumeric(n) && BigInt(n) > BigInt(0);
+const isPublicKey = (n: string) => /^0[23][0-9A-F]{64}$/i.test(n);
+const {isSafeInteger} = Number;
+const isTransactionId = (n: unknown) => /^[0-9a-f]{64}$/i.test(String(n));
+const maxFeeRate = 4294967295;
+const method = 'fundChannel';
+const type = 'tapchannel';
+
+export type OpenAssetChannelArgs = AuthenticatedTapdArgs<{
+  /** Asset Units To Fund the Channel With Numeric String */
+  amount: string;
+  /** Asset Id Hex String */
+  asset_id?: string;
+  /** Chain Fee Tokens Per Virtual Byte Number */
+  chain_fee_tokens_per_vbyte: number;
+  /** Tokens To Give To the Peer Number */
+  give_tokens?: number;
+  /** Asset Group Key Hex String */
+  group_key?: string;
+  /** Connected Peer Public Key Hex String */
+  partner_public_key: string;
+}>;
+
+export type OpenAssetChannelResult = {
+  /** Funding Transaction Id Hex */
+  transaction_id: string;
+  /** Funding Transaction Output Index */
+  transaction_vout: number;
+};
+
+type Tasks = {
+  open: OpenAssetChannelResult;
+  validate: undefined;
+};
+
+/** Open a channel that is funded with an asset
+
+  The peer must be connected. tapd sets the satoshi amount of the channel.
+
+  tapd must run inside litd, with lnd and tapd in integrated mode
+
+  Requires `channels:write` permission
+
+  An `asset_id` or a `group_key` is required, but not both
+
+  `give_tokens` is a gift to the peer, in the same way as with openChannel
+
+  {
+    amount: <Asset Units To Fund the Channel With Numeric String>
+    [asset_id]: <Asset Id Hex String>
+    chain_fee_tokens_per_vbyte: <Chain Fee Tokens Per Virtual Byte Number>
+    [give_tokens]: <Tokens To Give To the Peer Number>
+    [group_key]: <Asset Group Key Hex String>
+    partner_public_key: <Connected Peer Public Key Hex String>
+    tapd: <Authenticated tapd API Object>
+  }
+
+  @returns via cbk or Promise
+  {
+    transaction_id: <Funding Transaction Id Hex String>
+    transaction_vout: <Funding Transaction Output Index Number>
+  }
+*/
+const openAssetChannel: TapdMethod<
+  OpenAssetChannelArgs,
+  OpenAssetChannelResult
+> = (
+  args: OpenAssetChannelArgs,
+  cbk?: TapdCallback<OpenAssetChannelResult>,
+) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto<Tasks, TapdError>(
+      {
+        // Check arguments
+        validate: cbk => {
+          if (!isPositive(args.amount)) {
+            return cbk([400, 'ExpectedAssetAmountToOpenAssetChannel']);
+          }
+
+          if (!args.asset_id && !args.group_key) {
+            return cbk([400, 'ExpectedAssetIdOrGroupKeyToOpenAssetChannel']);
+          }
+
+          if (!!args.asset_id && !!args.group_key) {
+            return cbk([400, 'UnexpectedAssetIdAndGroupKeyForAssetChannel']);
+          }
+
+          if (!!args.asset_id && !isAssetId(args.asset_id)) {
+            return cbk([400, 'ExpectedAssetIdHexToOpenAssetChannel']);
+          }
+
+          const feeRate = args.chain_fee_tokens_per_vbyte;
+
+          if (!isSafeInteger(feeRate) || feeRate < 1 || feeRate > maxFeeRate) {
+            return cbk([400, 'ExpectedChainFeeRateToOpenAssetChannel']);
+          }
+
+          const give = args.give_tokens;
+
+          if (give !== undefined && (!isSafeInteger(give) || give < 0)) {
+            return cbk([400, 'ExpectedGiveTokensToOpenAssetChannel']);
+          }
+
+          if (!!args.group_key && !isPublicKey(args.group_key)) {
+            return cbk([400, 'ExpectedGroupKeyHexToOpenAssetChannel']);
+          }
+
+          if (
+            !args.partner_public_key ||
+            !isPublicKey(args.partner_public_key)
+          ) {
+            return cbk([400, 'ExpectedPartnerPublicKeyToOpenAssetChannel']);
+          }
+
+          if (!isTapd({method, type, tapd: args.tapd})) {
+            return cbk([400, 'ExpectedAuthenticatedTapdToOpenAssetChannel']);
+          }
+
+          return cbk();
+        },
+
+        // Open the channel
+        open: [
+          'validate',
+          ({}, cbk) => {
+            const request = {
+              asset_amount: args.amount,
+              asset_id: from(args.asset_id || '', 'hex'),
+              fee_rate_sat_per_vbyte: args.chain_fee_tokens_per_vbyte,
+              group_key: from(args.group_key || '', 'hex'),
+              peer_pubkey: from(args.partner_public_key, 'hex'),
+              push_sat: args.give_tokens || 0,
+            };
+
+            return args.tapd[type][method](request, (err: any, res: any) => {
+              if (isConnectionFailure({err})) {
+                return cbk([503, 'FailedToConnectToTapdToOpenAssetChannel']);
+              }
+
+              if (isPermissionDenied({err})) {
+                return cbk([403, 'PermissionDeniedToOpenAssetChannel']);
+              }
+
+              const knownError = assetChannelRpcError({err});
+
+              if (!!knownError) {
+                return cbk(knownError);
+              }
+
+              if (!!err) {
+                return cbk([503, 'UnexpectedErrorOpeningAssetChannel', {err}]);
+              }
+
+              if (!res || !isTransactionId(res.txid)) {
+                return cbk([
+                  503,
+                  'ExpectedFundingTransactionIdForAssetChannel',
+                ]);
+              }
+
+              if (!isSafeInteger(res.output_index) || res.output_index < 0) {
+                return cbk([503, 'ExpectedFundingOutputIndexForAssetChannel']);
+              }
+
+              return cbk(null, {
+                transaction_id: res.txid,
+                transaction_vout: res.output_index,
+              });
+            });
+          },
+        ],
+      },
+      returnResult({reject, resolve, of: 'open'}, cbk),
+    );
+  });
+};
+
+export default openAssetChannel;

package/src/tapd_methods/channels/pay_asset_invoice.ts

@@ -0,0 +1,171 @@
+import {auto as asyncAuto} from 'async';
+import {returnResult} from 'asyncjs-util';
+
+import {isTapd} from '../../tapd_requests/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';
+import assetPaymentArgsError from './asset_payment_args_error.js';
+import assetPaymentRequest from './asset_payment_request.js';
+import type {AssetPaymentRequestArgs} from './asset_payment_request.js';
+import sendAssetPayment from './send_asset_payment.js';
+import type {SendAssetPaymentResult} from './send_asset_payment.js';
+
+const isRfqId = (n: string) => /^[0-9A-F]{64}$/i.test(n);
+const method = 'sendPayment';
+const name = 'PayAssetInvoice';
+const type = 'tapchannel';
+
+export type PayAssetInvoiceArgs = AuthenticatedTapdArgs<
+  AssetPaymentRequestArgs & {
+    /** BOLT 11 Payment Request String */
+    request: string;
+    /** Accepted Sell Quote Id Hex String */
+    rfq_id?: string;
+  }
+>;
+
+export type PayAssetInvoiceResult = SendAssetPaymentResult;
+
+type Tasks = {
+  pay: PayAssetInvoiceResult;
+  validate: undefined;
+};
+
+/** Pay a payment request with an asset, over an asset channel
+
+  The channel peer sells satoshis for the asset, at a rate in an RFQ quote
+
+  tapd must run inside litd, with lnd and tapd in integrated mode
+
+  Requires `channels:write` permission
+
+  An `asset_id` or a `group_key` is required, but not both
+
+  Use an `rfq_id` of an accepted sell quote to pay with that quote
+
+  Without `max_fee` or `max_fee_mtokens`, only routes with no fee are used,
+  the same as lnd
+
+  The default `pathfinding_timeout` is 25 seconds. The default `max_paths` is 1.
+
+  tapd rejects a payment that is too small to carry one asset unit, unless
+  `is_overpay_allowed` is set
+
+  {
+    [asset_id]: <Asset Id Hex String>
+    [group_key]: <Asset Group Key Hex String>
+    [is_overpay_allowed]: <Allow a Payment Above the Request Amount Bool>
+    [max_fee]: <Maximum Fee Tokens Number>
+    [max_fee_mtokens]: <Maximum Fee Millitokens String>
+    [max_paths]: <Maximum Payment Paths Number>
+    [pathfinding_timeout]: <Time To Spend Finding a Route Milliseconds Number>
+    [peer_public_key]: <RFQ Peer Public Key Hex String>
+    [price_oracle_metadata]: <Price Oracle Metadata String>
+    request: <BOLT 11 Payment Request String>
+    [rfq_id]: <Accepted Sell Quote Id Hex String>
+    tapd: <Authenticated tapd API Object>
+  }
+
+  @returns via cbk or Promise
+  {
+    confirmed_at: <Payment Confirmed At ISO 8601 Date String>
+    created_at: <Payment Created At ISO 8601 Date String>
+    destination: <Payment Destination Public Key Hex String>
+    fee: <Total Fee Tokens Paid Rounded Down Number>
+    fee_mtokens: <Total Fee Millitokens Paid String>
+    hops: [{
+      channel: <Standard Format Channel Id String>
+      channel_capacity: <Channel Capacity Tokens Number>
+      fee: <Fee Tokens Rounded Down Number>
+      fee_mtokens: <Fee Millitokens String>
+      forward: <Forward Tokens Number>
+      forward_mtokens: <Forward Millitokens String>
+      public_key: <Public Key Hex String>
+      timeout: <Timeout Block Height Number>
+    }]
+    id: <Payment Hash Hex String>
+    [index]: <Payment Index Number String>
+    mtokens: <Total Millitokens Paid String>
+    paths: [{
+      fee_mtokens: <Total Fee Millitokens Paid String>
+      hops: [<Hop Object>]
+      mtokens: <Total Millitokens Paid String>
+    }]
+    quotes: [{
+      [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>
+    }]
+    [request]: <BOLT 11 Payment Request String>
+    safe_fee: <Total Fee Tokens Paid Rounded Up Number>
+    safe_tokens: <Total Tokens Paid, Rounded Up Number>
+    secret: <Payment Preimage Hex String>
+    timeout: <Expiration Block Height Number>
+    tokens: <Total Tokens Paid Rounded Down Number>
+  }
+*/
+const payAssetInvoice: TapdMethod<
+  PayAssetInvoiceArgs,
+  PayAssetInvoiceResult
+> = (args: PayAssetInvoiceArgs, cbk?: TapdCallback<PayAssetInvoiceResult>) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto<Tasks, TapdError>(
+      {
+        // Check arguments
+        validate: cbk => {
+          const argsError = assetPaymentArgsError({args, name});
+
+          if (!!argsError) {
+            return cbk(argsError);
+          }
+
+          if (!args.request || typeof args.request !== 'string') {
+            return cbk([400, 'ExpectedPaymentRequestToPayAssetInvoice']);
+          }
+
+          if (!!args.rfq_id && !isRfqId(args.rfq_id)) {
+            return cbk([400, 'ExpectedRfqIdHexToPayAssetInvoice']);
+          }
+
+          if (!isTapd({method, type, tapd: args.tapd})) {
+            return cbk([400, 'ExpectedAuthenticatedTapdToPayAssetInvoice']);
+          }
+
+          return cbk();
+        },
+
+        // Pay the payment request
+        pay: [
+          'validate',
+          ({}, cbk) => {
+            const common = assetPaymentRequest(args);
+
+            const request = {
+              ...common,
+              payment_request: {
+                ...common.payment_request,
+                payment_request: args.request,
+              },
+              rfq_id: Buffer.from(args.rfq_id || '', 'hex'),
+            };
+
+            return sendAssetPayment({name, request, tapd: args.tapd}, cbk);
+          },
+        ],
+      },
+      returnResult({reject, resolve, of: 'pay'}, cbk),
+    );
+  });
+};
+
+export default payAssetInvoice;

package/src/tapd_methods/channels/send_asset_keysend.ts

@@ -0,0 +1,196 @@
+import {createHash} from 'node:crypto';
+import {randomBytes} from 'node:crypto';
+
+import {auto as asyncAuto} from 'async';
+import {returnResult} from 'asyncjs-util';
+
+import {isTapd} from '../../tapd_requests/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';
+import assetPaymentArgsError from './asset_payment_args_error.js';
+import assetPaymentRequest from './asset_payment_request.js';
+import type {AssetPaymentRequestArgs} from './asset_payment_request.js';
+import sendAssetPayment from './send_asset_payment.js';
+import type {SendAssetPaymentResult} from './send_asset_payment.js';
+
+const isHash = (n: string) => /^[0-9A-F]{64}$/i.test(n);
+const isNumeric = (n: unknown) => typeof n === 'string' && /^\d+$/.test(n);
+const isPositive = (n: string) => isNumeric(n) && BigInt(n) > BigInt(0);
+const isPublicKey = (n: string) => /^0[23][0-9A-F]{64}$/i.test(n);
+const {isSafeInteger} = Number;
+const keySendRecordType = '5482373484';
+const method = 'sendPayment';
+// tapd needs at least the HTLC dust limit, litcli also sends this amount
+const minTokens = 354;
+const name = 'SendAssetKeysend';
+const preimageByteLength = 32;
+const sha256 = (n: Buffer) => createHash('sha256').update(n).digest();
+const type = 'tapchannel';
+
+export type SendAssetKeysendArgs = AuthenticatedTapdArgs<
+  Omit<AssetPaymentRequestArgs, 'is_overpay_allowed'> & {
+    /** Asset Units To Send Numeric String */
+    amount: string;
+    /** Destination Peer Public Key Hex String */
+    destination: string;
+    /** Payment Preimage Hex String */
+    secret?: string;
+    /** Tokens That Carry the Asset Units Number */
+    tokens?: number;
+  }
+>;
+
+export type SendAssetKeysendResult = SendAssetPaymentResult;
+
+type Tasks = {
+  send: SendAssetKeysendResult;
+  validate: undefined;
+};
+
+/** Send an asset to a channel peer with a keysend payment
+
+  tapd only sends an asset keysend payment to a direct asset channel peer
+
+  tapd must run inside litd, with lnd and tapd in integrated mode
+
+  Requires `channels:write` permission
+
+  An `asset_id` or a `group_key` is required, but not both
+
+  The default `tokens` is 354, the smallest amount that tapd accepts
+
+  A random `secret` is used when there is no `secret`
+
+  Without `max_fee` or `max_fee_mtokens`, only routes with no fee are used,
+  the same as lnd
+
+  {
+    amount: <Asset Units To Send Numeric String>
+    [asset_id]: <Asset Id Hex String>
+    destination: <Destination Peer Public Key Hex String>
+    [group_key]: <Asset Group Key Hex String>
+    [max_fee]: <Maximum Fee Tokens Number>
+    [max_fee_mtokens]: <Maximum Fee Millitokens String>
+    [max_paths]: <Maximum Payment Paths Number>
+    [pathfinding_timeout]: <Time To Spend Finding a Route Milliseconds Number>
+    [peer_public_key]: <RFQ Peer Public Key Hex String>
+    [price_oracle_metadata]: <Price Oracle Metadata String>
+    [secret]: <Payment Preimage Hex String>
+    tapd: <Authenticated tapd API Object>
+    [tokens]: <Tokens That Carry the Asset Units Number>
+  }
+
+  @returns via cbk or Promise
+  {
+    confirmed_at: <Payment Confirmed At ISO 8601 Date String>
+    created_at: <Payment Created At ISO 8601 Date String>
+    destination: <Payment Destination Public Key Hex String>
+    fee: <Total Fee Tokens Paid Rounded Down Number>
+    fee_mtokens: <Total Fee Millitokens Paid String>
+    hops: [{
+      channel: <Standard Format Channel Id String>
+      channel_capacity: <Channel Capacity Tokens Number>
+      fee: <Fee Tokens Rounded Down Number>
+      fee_mtokens: <Fee Millitokens String>
+      forward: <Forward Tokens Number>
+      forward_mtokens: <Forward Millitokens String>
+      public_key: <Public Key Hex String>
+      timeout: <Timeout Block Height Number>
+    }]
+    id: <Payment Hash Hex String>
+    [index]: <Payment Index Number String>
+    mtokens: <Total Millitokens Paid String>
+    paths: [{
+      fee_mtokens: <Total Fee Millitokens Paid String>
+      hops: [<Hop Object>]
+      mtokens: <Total Millitokens Paid String>
+    }]
+    quotes: [<Accepted Sell Quote Object>]
+    safe_fee: <Total Fee Tokens Paid Rounded Up Number>
+    safe_tokens: <Total Tokens Paid, Rounded Up Number>
+    secret: <Payment Preimage Hex String>
+    timeout: <Expiration Block Height Number>
+    tokens: <Total Tokens Paid Rounded Down Number>
+  }
+*/
+const sendAssetKeysend: TapdMethod<
+  SendAssetKeysendArgs,
+  SendAssetKeysendResult
+> = (
+  args: SendAssetKeysendArgs,
+  cbk?: TapdCallback<SendAssetKeysendResult>,
+) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto<Tasks, TapdError>(
+      {
+        // Check arguments
+        validate: cbk => {
+          if (!isPositive(args.amount)) {
+            return cbk([400, 'ExpectedAssetAmountToSendAssetKeysend']);
+          }
+
+          const argsError = assetPaymentArgsError({args, name});
+
+          if (!!argsError) {
+            return cbk(argsError);
+          }
+
+          if (!args.destination || !isPublicKey(args.destination)) {
+            return cbk([400, 'ExpectedDestinationToSendAssetKeysend']);
+          }
+
+          if (!!args.secret && !isHash(args.secret)) {
+            return cbk([400, 'ExpectedPreimageHexToSendAssetKeysend']);
+          }
+
+          if (!isTapd({method, type, tapd: args.tapd})) {
+            return cbk([400, 'ExpectedAuthenticatedTapdToSendAssetKeysend']);
+          }
+
+          const tokens = args.tokens;
+
+          if (tokens !== undefined && !isSafeInteger(tokens)) {
+            return cbk([400, 'ExpectedIntegerTokensToSendAssetKeysend']);
+          }
+
+          if (tokens !== undefined && tokens < minTokens) {
+            return cbk([400, 'ExpectedAtLeast354TokensToSendAssetKeysend']);
+          }
+
+          return cbk();
+        },
+
+        // Send the keysend payment
+        send: [
+          'validate',
+          ({}, cbk) => {
+            const common = assetPaymentRequest(args);
+
+            const preimage = !!args.secret
+              ? Buffer.from(args.secret, 'hex')
+              : randomBytes(preimageByteLength);
+
+            const request = {
+              ...common,
+              asset_amount: args.amount,
+              payment_request: {
+                ...common.payment_request,
+                amt: args.tokens || minTokens,
+                dest: Buffer.from(args.destination, 'hex'),
+                dest_custom_records: {[keySendRecordType]: preimage},
+                payment_hash: sha256(preimage),
+              },
+            };
+
+            return sendAssetPayment({name, request, tapd: args.tapd}, cbk);
+          },
+        ],
+      },
+      returnResult({reject, resolve, of: 'send'}, cbk),
+    );
+  });
+};
+
+export default sendAssetKeysend;