astra-lightning 1.0.0

package/lnd_methods/signer/sign_transaction.js

@@ -0,0 +1,140 @@
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+
+const inputSigningMethod = require('./input_signing_method');
+const {isLnd} = require('./../../lnd_requests');
+
+const bufferAsHex = buffer => buffer.toString('hex');
+const hexAsBuffer = hex => Buffer.from(hex || '', 'hex');
+const {isArray} = Array;
+const isV1 = scriptHex => scriptHex.length === 68 && /5120/.test(scriptHex);
+const method = 'signOutputRaw';
+const notFound = -1;
+const type = 'signer';
+const unimplementedError = '12 UNIMPLEMENTED: unknown service signrpc.Signer';
+
+/** Sign transaction
+
+  `spending` is required for non-internal inputs for a Taproot signature
+
+  Requires LND built with `signrpc` build tag
+
+  Requires `signer:generate` permission
+
+  `root_hash` is not supported in LND 0.14.5 and below
+  `spending` is not supported in LND 0.14.5 and below
+
+  {
+    inputs: [{
+      key_family: <Key Family Number>
+      key_index: <Key Index Number>
+      output_script: <Output Script Hex String>
+      output_tokens: <Output Tokens Number>
+      [root_hash]: <Taproot Root Hash Hex String>
+      sighash: <Sighash Type Number>
+      vin: <Input Index To Sign Number>
+      [witness_script]: <Witness Script Hex String>
+    }]
+    lnd: <Authenticated LND API Object>
+    [spending]: [{
+      output_script: <Non-Internal Spend Output Script Hex String>
+      output_tokens: <Non-Internal Spend Output Tokens Number>
+    }]
+    transaction: <Unsigned Transaction Hex String>
+  }
+
+  @returns via cbk or Promise
+  {
+    signatures: [<Signature Hex String>]
+  }
+*/
+module.exports = ({inputs, lnd, spending, transaction}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!isArray(inputs) || !inputs.length) {
+          return cbk([400, 'ExpectedInputsToSignTransaction']);
+        }
+
+        if (!isLnd({lnd, method, type})) {
+          return cbk([400, 'ExpectedAuthenticatedLndToSignTransaction']);
+        }
+
+        if (!transaction) {
+          return cbk([400, 'ExpectedUnsignedTransactionToSign']);
+        }
+
+        return cbk();
+      },
+
+      // Derive the previous outputs set for Taproot spends
+      outputs: ['validate', ({}, cbk) => {
+        const outputs = [].concat(inputs).concat(spending || []).map(utxo => ({
+          pk_script: hexAsBuffer(utxo.output_script),
+          value: utxo.output_tokens,
+        }));
+
+        const v1Spends = outputs.filter(n => isV1(bufferAsHex(n.pk_script)));
+
+        // Exit early when there is no need to provide prev outs, non-taproot
+        if (!v1Spends.length) {
+          return cbk();
+        }
+
+        return cbk(null, outputs);
+      }],
+
+      // Get signatures
+      signTransaction: ['outputs', ({outputs}, cbk) => {
+        return lnd[type][method]({
+          prev_outputs: outputs,
+          raw_tx_bytes: hexAsBuffer(transaction),
+          sign_descs: inputs.map(input => {
+            return {
+              input_index: input.vin,
+              key_desc: {
+                key_loc: {
+                  key_family: input.key_family,
+                  key_index: input.key_index,
+                },
+              },
+              output: {
+                pk_script: hexAsBuffer(input.output_script),
+                value: input.output_tokens,
+              },
+              sighash: input.sighash,
+              sign_method: inputSigningMethod({input, outputs}).method,
+              tap_tweak: hexAsBuffer(input.root_hash),
+              witness_script: hexAsBuffer(input.witness_script),
+            };
+          }),
+        },
+        (err, res) => {
+          if (!!err && err.message === unimplementedError) {
+            return cbk([400, 'ExpectedLndBuiltWithSignerRpcBuildTag']);
+          }
+
+          if (!!err) {
+            return cbk([503, 'UnexpectedErrorWhenSigning', {err}]);
+          }
+
+          if (!res) {
+            return cbk([503, 'UnexpectedEmptyResponseWhenSigning']);
+          }
+
+          if (!isArray(res.raw_sigs) || !res.raw_sigs.length) {
+            return cbk([503, 'ExpectedSignaturesInSignatureResponse']);
+          }
+
+          if (res.raw_sigs.findIndex(n => !Buffer.isBuffer(n)) !== notFound) {
+            return cbk([503, 'ExpectedSignatureBuffersInSignResponse']);
+          }
+
+          return cbk(null, {signatures: res.raw_sigs.map(bufferAsHex)});
+        });
+      }],
+    },
+    returnResult({reject, resolve, of: 'signTransaction'}, cbk));
+  });
+};

package/lnd_methods/signer/update_group_signing_session.d.ts

@@ -0,0 +1,23 @@
+import {
+  AuthenticatedLightningArgs,
+  AuthenticatedLightningMethod,
+} from '../../typescript/shared';
+
+export type UpdateGroupSigningSessionArgs = AuthenticatedLightningArgs<{
+  /** Hash to Sign Hex String */
+  hash: string;
+  /** MuSig2 Session Id Hex String */
+  id: string;
+  /** Nonce Hex Strings */
+  nonces: string[];
+}>;
+
+export type UpdateGroupSigningSessionResult = {
+  /** Partial Signature Hex String */
+  signature: string;
+};
+
+export const updateGroupSigningSession: AuthenticatedLightningMethod<
+  UpdateGroupSigningSessionArgs,
+  UpdateGroupSigningSessionResult
+>;

package/lnd_methods/signer/update_group_signing_session.js

@@ -0,0 +1,110 @@
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+
+const {isLnd} = require('./../../lnd_requests');
+
+const bufferAsHex = buffer => buffer.toString('hex');
+const hexAsBuffer = hex => Buffer.from(hex, 'hex');
+const {isArray} = Array;
+const {isBuffer} = Buffer;
+const isHash = n => !!n && /^[0-9A-F]{64}$/i.test(n);
+const method = 'muSig2RegisterNonces';
+const type = 'signer';
+
+/** Update a MuSig2 signing session with nonces and generate a partial sig
+
+  All remote nonces are expected to be passed
+
+  Requires LND built with `signrpc` build tag
+
+  Requires `signer:generate` permission
+
+  This method is not supported in LND 0.14.5 and below
+
+  {
+    hash: <Hash to Sign Hex String>
+    id: <MuSig2 Session Id Hex String>
+    lnd: <Authenticated LND API Object>
+    nonces: [<Nonce Hex String>]
+  }
+
+  @returns via cbk or Promise
+  {
+    signature: <Partial Signature Hex String>
+  }
+*/
+module.exports = ({hash, id, lnd, nonces}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!isHash(hash)) {
+          return cbk([400, 'ExpectedHashToSignToUpdateMuSig2Session']);
+        }
+
+        if (!id) {
+          return cbk([400, 'ExpectedSessionIdToUpdateMuSig2Session']);
+        }
+
+        if (!isLnd({lnd, method, type})) {
+          return cbk([400, 'ExpectedAuthenticatedLndToUpdateMuSig2Session']);
+        }
+
+        if (!isArray(nonces)) {
+          return cbk([400, 'ExpectedArrayOfNoncesToUpdateMuSig2Session']);
+        }
+
+        return cbk();
+      },
+
+      // Update the session with the nonces
+      updateNonces: ['validate', ({}, cbk) => {
+        return lnd[type][method]({
+          other_signer_public_nonces: nonces.map(hexAsBuffer),
+          session_id: hexAsBuffer(id),
+        },
+        (err, res) => {
+          if (!!err) {
+            return cbk([503, 'UnexpectedErrorUpdatingMuSig2Session', {err}]);
+          }
+
+          if (!res) {
+            return cbk([503, 'ExpectedResultOfRegisterNoncesRequest']);
+          }
+
+          if (res.have_all_nonces !== true) {
+            return cbk([400, 'ExpectedAllNoncesForRegisterNoncesRequest']);
+          }
+
+          return cbk();
+        });
+      }],
+
+      // Partially sign the digest hash
+      sign: ['updateNonces', ({}, cbk) => {
+        return lnd[type].muSig2Sign({
+          message_digest: hexAsBuffer(hash),
+          session_id: hexAsBuffer(id),
+        },
+        (err, res) => {
+          if (!!err) {
+            return cbk([503, 'UnexpectedErrorSigningMuSig2Session', {err}]);
+          }
+
+          if (!res) {
+            return cbk([503, 'ExpectedResultForMuSig2SignRequest']);
+          }
+
+          if (!isBuffer(res.local_partial_signature)) {
+            return cbk([503, 'ExpectedPartialSignatureForMuSig2SignRequest']);
+          }
+
+          return cbk(null, {
+            signature: bufferAsHex(res.local_partial_signature),
+          });
+        });
+      }],
+    },
+    returnResult({reject, resolve, of: 'sign'}, cbk));
+  });
+};

package/lnd_methods/signer/verify_bytes_signature.d.ts

@@ -0,0 +1,30 @@
+import {
+  AuthenticatedLightningArgs,
+  AuthenticatedLightningMethod,
+} from '../../typescript';
+
+export type VerifyBytesSignatureArgs = AuthenticatedLightningArgs<{
+  /** Message Preimage Bytes Hex Encoded String */
+  preimage: string;
+  /** Signature Valid For Public Key Hex String */
+  public_key: string;
+  /** Signature Hex */
+  signature: string;
+}>;
+
+export type VerifyBytesSignatureResult = {
+  /** Signature is Valid */
+  is_valid: boolean;
+};
+
+/**
+ * Verify signature of arbitrary bytes
+ *
+ * Requires LND built with `signrpc` build tag
+ *
+ * Requires `signer:read` permission
+ */
+export const verifyBytesSignature: AuthenticatedLightningMethod<
+  VerifyBytesSignatureArgs,
+  VerifyBytesSignatureResult
+>;

package/lnd_methods/signer/verify_bytes_signature.js

@@ -0,0 +1,87 @@
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+
+const {isLnd} = require('./../../lnd_requests');
+
+const isHex = n => !(n.length % 2) && /^[0-9A-F]*$/i.test(n);
+const isSchnorrSignatureLength = signature => signature.length === 128;
+const unimplementedError = '12 UNIMPLEMENTED: unknown service signrpc.Signer';
+
+/** Verify signature of arbitrary bytes
+
+  When passing a schnorr signature, a BIP-340 x-only public key should be given
+
+  Requires LND built with `signrpc` build tag
+
+  Requires `signer:read` permission
+
+  Validating `schnorr` signatures is unsupported in LND 0.15.0 and below
+
+  {
+    lnd: <Authenticated LND API Object>
+    preimage: <Message Preimage Bytes Hex Encoded String>
+    public_key: <Signature Valid For Public Key Hex String>
+    signature: <Signature Hex String>
+  }
+
+  @returns via cbk or Promise
+  {
+    is_valid: <Signature is Valid Bool>
+  }
+*/
+module.exports = (args, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!isLnd({lnd: args.lnd, method: 'verifyMessage', type: 'signer'})) {
+          return cbk([400, 'ExpectedLndToVerifyBytesSignature']);
+        }
+
+        if (!args.preimage || !isHex(args.preimage)) {
+          return cbk([400, 'ExpectedPreimageToVerifyBytesSignature'])
+        }
+
+        if (!args.public_key || !isHex(args.public_key)) {
+          return cbk([400, 'ExpectedPublicKeyToVerifyBytesSignature']);
+        }
+
+        if (!args.signature || !isHex(args.signature)) {
+          return cbk([400, 'ExpectedSignatureToVerifyBytesSignature']);
+        }
+
+        return cbk();
+      },
+
+      // Verify signature
+      verify: ['validate', ({}, cbk) => {
+        return args.lnd.signer.verifyMessage({
+          is_schnorr_sig: isSchnorrSignatureLength(args.signature),
+          msg: Buffer.from(args.preimage, 'hex'),
+          pubkey: Buffer.from(args.public_key, 'hex'),
+          signature: Buffer.from(args.signature, 'hex'),
+        },
+        (err, res) => {
+          if (!!err && err.message === unimplementedError) {
+            return cbk([400, 'ExpectedSignerRpcLndBuildTagToVerifySignBytes']);
+          }
+
+          if (!!err) {
+            return cbk([503, 'UnexpectedErrWhenVerifyingSignedBytes', {err}]);
+          }
+
+          if (!res) {
+            return cbk([503, 'UnexpectedEmptyResponseWhenVerifyingBytesSig']);
+          }
+
+          if (res.valid === undefined) {
+            return cbk([503, 'ExpectedValidStateOfSignatureOverBytes']);
+          }
+
+          return cbk(null, {is_valid: res.valid});
+        });
+      }],
+    },
+    returnResult({reject, resolve, of: 'verify'}, cbk));
+  });
+};

package/lnd_methods/unauthenticated/change_password.d.ts

@@ -0,0 +1,18 @@
+import {
+  UnauthenticatedLightningArgs,
+  UnauthenticatedLightningMethod,
+} from '../../typescript';
+
+export type ChangePasswordArgs = UnauthenticatedLightningArgs<{
+  /** Current Password String */
+  current_password: string;
+  /** New Password String */
+  new_password: string;
+}>;
+
+/**
+ * Change wallet password
+ *
+ * Requires locked LND and unauthenticated LND connection
+ */
+export const changePassword: UnauthenticatedLightningMethod<ChangePasswordArgs>;

package/lnd_methods/unauthenticated/change_password.js

@@ -0,0 +1,59 @@
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+
+const {isLnd} = require('./../../lnd_requests');
+
+const method = 'changePassword';
+const type = 'unlocker';
+const utf8AsBuffer = utf8 => Buffer.from(utf8, 'utf8');
+
+/** Change wallet password
+
+  Requires locked LND and unauthenticated LND connection
+
+  {
+    current_password: <Current Password String>
+    lnd: <Unauthenticated LND API Object>
+    new_password: <New Password String>
+  }
+
+  @returns via cbk or Promise
+*/
+module.exports = (args, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!args.current_password) {
+          return cbk([400, 'ExpectedCurrentPasswordToChangePassword']);
+        }
+
+        if (!isLnd({method, type, lnd: args.lnd})) {
+          return cbk([400, 'ExpectedUnauthenticatedLndToChangePassword']);
+        }
+
+        if (!args.new_password) {
+          return cbk([400, 'ExpectedNewPasswordForChangePasswordRequest']);
+        }
+
+        return cbk();
+      },
+
+      // Use the old password to change to the new password
+      changePassword: ['validate', ({}, cbk) => {
+        return args.lnd[type][method]({
+          current_password: utf8AsBuffer(args.current_password),
+          new_password: utf8AsBuffer(args.new_password),
+        },
+        err => {
+          if (!!err) {
+            return cbk([503, 'FailedToChangeLndPassword', {err}]);
+          }
+
+          return cbk();
+        });
+      }],
+    },
+    returnResult({reject, resolve}, cbk));
+  });
+};

package/lnd_methods/unauthenticated/create_seed.d.ts

@@ -0,0 +1,24 @@
+import {
+  UnauthenticatedLightningArgs,
+  UnauthenticatedLightningMethod,
+} from '../../typescript';
+
+export type CreateSeedArgs = UnauthenticatedLightningArgs<{
+  /** Seed Passphrase String */
+  passphrase?: string;
+}>;
+
+export type CreateSeedResult = {
+  /** Cipher Seed Mnemonic String */
+  seed: string;
+};
+
+/**
+ * Create a wallet seed
+ *
+ * Requires unlocked lnd and unauthenticated LND
+ */
+export const createSeed: UnauthenticatedLightningMethod<
+  CreateSeedArgs,
+  CreateSeedResult
+>;

package/lnd_methods/unauthenticated/create_seed.js

@@ -0,0 +1,70 @@
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+
+const {isLnd} = require('./../../lnd_requests');
+
+const connectionFailure = '14 UNAVAILABLE: Connect Failed';
+const expectedMnemonicLength = 24;
+const {isArray} = Array;
+const method = 'genSeed';
+const type = 'unlocker';
+const utf8AsBuffer = utf8 => Buffer.from(utf8, 'utf8');
+
+/** Create a wallet seed
+
+  Requires unlocked lnd and unauthenticated LND API Object
+
+  {
+    lnd: <Unauthenticated LND API Object>
+    [passphrase]: <Seed Passphrase String>
+  }
+
+  @returns via cbk or Promise
+  {
+    seed: <Cipher Seed Mnemonic String>
+  }
+*/
+module.exports = ({lnd, passphrase}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!isLnd({lnd, method, type})) {
+          return cbk([400, 'ExpectedNonAuthenticatedLndForSeedCreation']);
+        }
+
+        return cbk();
+      },
+
+      // Create seed
+      createSeed: ['validate', ({}, cbk) => {
+        const pass = !passphrase ? undefined : utf8AsBuffer(passphrase);
+
+        return lnd[type][method]({aezeed_passphrase: pass}, (err, res) => {
+          if (!!err && err.message === connectionFailure) {
+            return cbk([503, 'UnexpectedConnectionFailure']);
+          }
+
+          if (!!err) {
+            return cbk([503, 'UnexpectedCreateSeedError', {err}]);
+          }
+
+          if (!res) {
+            return cbk([503, 'ExpectedResponseForSeedCreation']);
+          }
+
+          if (!isArray(res.cipher_seed_mnemonic)) {
+            return cbk([503, 'ExpectedCipherSeedMnemonic']);
+          }
+
+          if (res.cipher_seed_mnemonic.length !== expectedMnemonicLength) {
+            return cbk([503, 'UnexpectedCipherSeedMnemonicLength']);
+          }
+
+          return cbk(null, {seed: res.cipher_seed_mnemonic.join(' ')});
+        });
+      }],
+    },
+    returnResult({reject, resolve, of: 'createSeed'}, cbk));
+  });
+};

package/lnd_methods/unauthenticated/create_wallet.d.ts

@@ -0,0 +1,28 @@
+import {
+  UnauthenticatedLightningArgs,
+  UnauthenticatedLightningMethod,
+} from '../../typescript';
+
+export type CreateWalletArgs = UnauthenticatedLightningArgs<{
+  /** AEZSeed Encryption Passphrase String */
+  passphrase?: string;
+  /** Wallet Password String */
+  password: string;
+  /** Seed Mnemonic String */
+  seed: string;
+}>;
+
+export type CreateWalletResult = {
+  /** Base64 Encoded Admin Macaroon String */
+  macaroon: string;
+};
+
+/**
+ * Create a wallet
+ *
+ * Requires unlocked lnd and unauthenticated LND
+ */
+export const createWallet: UnauthenticatedLightningMethod<
+  CreateWalletArgs,
+  CreateWalletResult
+>;

package/lnd_methods/unauthenticated/create_wallet.js

@@ -0,0 +1,74 @@
+const asyncAuto = require('async/auto');
+const {returnResult} = require('asyncjs-util');
+
+const {isLnd} = require('./../../lnd_requests');
+
+const bufferAsBase64 = buffer => buffer.toString('base64');
+const {isBuffer} = Buffer;
+const method = 'initWallet';
+const type = 'unlocker';
+const utf8AsBuf = utf8 => Buffer.from(utf8, 'utf8');
+
+/** Create a wallet
+
+  Requires unlocked lnd and unauthenticated LND API Object
+
+  {
+    lnd: <Unauthenticated LND API Object>
+    [passphrase]: <AEZSeed Encryption Passphrase String>
+    password: <Wallet Password String>
+    seed: <Seed Mnemonic String>
+  }
+
+  @returns via cbk or Promise
+  {
+    macaroon: <Base64 Encoded Admin Macaroon String>
+  }
+*/
+module.exports = ({lnd, passphrase, password, seed}, cbk) => {
+  return new Promise((resolve, reject) => {
+    return asyncAuto({
+      // Check arguments
+      validate: cbk => {
+        if (!isLnd({lnd, method, type})) {
+          return cbk([400, 'ExpectedLndForWalletCreation']);
+        }
+
+        if (!password) {
+          return cbk([400, 'ExpectedWalletPasswordForWalletCreation']);
+        }
+
+        if (!seed) {
+          return cbk([400, 'ExpectedSeedMnemonicForWalletCreation']);
+        }
+
+        return cbk();
+      },
+
+      // Create wallet
+      createWallet: ['validate', ({}, cbk) => {
+        return lnd[type][method]({
+          aezeed_passphrase: !!passphrase ? utf8AsBuf(passphrase) : undefined,
+          cipher_seed_mnemonic: seed.split(' '),
+          wallet_password: utf8AsBuf(password),
+        },
+        (err, res) => {
+          if (!!err) {
+            return cbk([503, 'UnexpectedInitWalletError', {err}]);
+          }
+
+          if (!res) {
+            return cbk([503, 'ExpectedResponseForInitWallet']);
+          }
+
+          if (!isBuffer(res.admin_macaroon)) {
+            return cbk([503, 'ExpectedAdminMacaroonToCrateWallet']);
+          }
+
+          return cbk(null, bufferAsBase64(res.admin_macaroon));
+        });
+      }],
+    },
+    returnResult({reject, resolve}, cbk));
+  });
+};