algosdk 1.24.0 → 2.0.0

package/src/multisig.ts

@@ -0,0 +1,495 @@
+import * as nacl from './nacl/naclWrappers';
+import * as address from './encoding/address';
+import * as encoding from './encoding/encoding';
+import * as txnBuilder from './transaction';
+import * as utils from './utils/utils';
+import AnyTransaction, { EncodedTransaction } from './types/transactions';
+import { MultisigMetadata } from './types/multisig';
+import {
+  EncodedMultisig,
+  EncodedSignedTransaction,
+} from './types/transactions/encoded';
+
+/**
+ Utilities for manipulating multisig transaction blobs.
+ */
+
+export const MULTISIG_MERGE_LESSTHANTWO_ERROR_MSG =
+  'Not enough multisig transactions to merge. Need at least two';
+export const MULTISIG_MERGE_MISMATCH_ERROR_MSG =
+  'Cannot merge txs. txIDs differ';
+export const MULTISIG_MERGE_MISMATCH_AUTH_ADDR_MSG =
+  'Cannot merge txs. Auth addrs differ';
+export const MULTISIG_MERGE_WRONG_PREIMAGE_ERROR_MSG =
+  'Cannot merge txs. Multisig preimages differ';
+export const MULTISIG_MERGE_SIG_MISMATCH_ERROR_MSG =
+  'Cannot merge txs. subsigs are mismatched.';
+const MULTISIG_KEY_NOT_EXIST_ERROR_MSG = 'Key does not exist';
+export const MULTISIG_NO_MUTATE_ERROR_MSG =
+  'Cannot mutate a multisig field as it would invalidate all existing signatures.';
+export const MULTISIG_USE_PARTIAL_SIGN_ERROR_MSG =
+  'Cannot sign a multisig transaction using `signTxn`. Use `partialSignTxn` instead.';
+export const MULTISIG_SIGNATURE_LENGTH_ERROR_MSG =
+  'Cannot add multisig signature. Signature is not of the correct length.';
+
+interface MultisigOptions {
+  rawSig: Uint8Array;
+  myPk: Uint8Array;
+}
+
+interface MultisigMetadataWithPks extends Omit<MultisigMetadata, 'addrs'> {
+  pks: Uint8Array[];
+}
+
+/**
+ * createMultisigTransaction creates a raw, unsigned multisig transaction blob.
+ * @param txn - the actual transaction.
+ * @param version - multisig version
+ * @param threshold - multisig threshold
+ * @param pks - ordered list of public keys in this multisig
+ * @returns encoded multisig blob
+ */
+export function createMultisigTransaction(
+  txn: txnBuilder.Transaction,
+  { version, threshold, addrs }: MultisigMetadata
+) {
+  // construct the appendable multisigned transaction format
+  const pks = addrs.map((addr) => address.decodeAddress(addr).publicKey);
+  const subsigs = pks.map((pk) => ({ pk: Buffer.from(pk) }));
+
+  const msig: EncodedMultisig = {
+    v: version,
+    thr: threshold,
+    subsig: subsigs,
+  };
+  const txnForEncoding = txn.get_obj_for_encoding();
+  const signedTxn: EncodedSignedTransaction = {
+    msig,
+    txn: txnForEncoding,
+  };
+
+  // if the address of this multisig is different from the transaction sender,
+  // we need to add the auth-addr field
+  const msigAddr = address.fromMultisigPreImg({
+    version,
+    threshold,
+    pks,
+  });
+  if (
+    address.encodeAddress(txnForEncoding.snd) !==
+    address.encodeAddress(msigAddr)
+  ) {
+    signedTxn.sgnr = Buffer.from(msigAddr);
+  }
+
+  return new Uint8Array(encoding.encode(signedTxn));
+}
+
+/**
+ * createMultisigTransactionWithSignature creates a multisig transaction blob with an included signature.
+ * @param txn - the actual transaction to sign.
+ * @param rawSig - a Buffer raw signature of that transaction
+ * @param myPk - a public key that corresponds with rawSig
+ * @param version - multisig version
+ * @param threshold - multisig threshold
+ * @param pks - ordered list of public keys in this multisig
+ * @returns encoded multisig blob
+ */
+function createMultisigTransactionWithSignature(
+  txn: txnBuilder.Transaction,
+  { rawSig, myPk }: MultisigOptions,
+  { version, threshold, pks }: MultisigMetadataWithPks
+) {
+  // Create an empty encoded multisig transaction
+  const encodedMsig = createMultisigTransaction(txn, {
+    version,
+    threshold,
+    addrs: pks.map((pk) => address.encodeAddress(pk)),
+  });
+  // note: this is not signed yet, but will be shortly
+  const signedTxn = encoding.decode(encodedMsig) as EncodedSignedTransaction;
+
+  let keyExist = false;
+  // append the multisig signature to the corresponding public key in the multisig blob
+  signedTxn.msig.subsig.forEach((subsig, i) => {
+    if (nacl.bytesEqual(subsig.pk, myPk)) {
+      keyExist = true;
+      signedTxn.msig.subsig[i].s = rawSig;
+    }
+  });
+  if (keyExist === false) {
+    throw new Error(MULTISIG_KEY_NOT_EXIST_ERROR_MSG);
+  }
+
+  // if the address of this multisig is different from the transaction sender,
+  // we need to add the auth-addr field
+  const msigAddr = address.fromMultisigPreImg({
+    version,
+    threshold,
+    pks,
+  });
+  if (
+    address.encodeAddress(signedTxn.txn.snd) !== address.encodeAddress(msigAddr)
+  ) {
+    signedTxn.sgnr = Buffer.from(msigAddr);
+  }
+
+  return new Uint8Array(encoding.encode(signedTxn));
+}
+
+/**
+ * MultisigTransaction is a Transaction that also supports creating partially-signed multisig transactions.
+ */
+export class MultisigTransaction extends txnBuilder.Transaction {
+  /* eslint-disable class-methods-use-this,@typescript-eslint/no-unused-vars,no-dupe-class-members */
+  /**
+   * Override inherited method to throw an error, as mutating transactions are prohibited in this context
+   */
+  addLease() {
+    throw new Error(MULTISIG_NO_MUTATE_ERROR_MSG);
+  }
+
+  /**
+   * Override inherited method to throw an error, as mutating transactions are prohibited in this context
+   */
+  addRekey() {
+    throw new Error(MULTISIG_NO_MUTATE_ERROR_MSG);
+  }
+
+  /**
+   * Override inherited method to throw an error, as traditional signing is not allowed
+   */
+  signTxn(sk: Uint8Array): Uint8Array; // This overload ensures that the override has a compatible type definition with the parent method
+  signTxn(sk: any): any {
+    throw new Error(MULTISIG_USE_PARTIAL_SIGN_ERROR_MSG);
+  }
+  /* eslint-enable class-methods-use-this,@typescript-eslint/no-unused-vars,no-dupe-class-members */
+
+  /**
+   * partialSignTxn partially signs this transaction and returns a partially-signed multisig transaction,
+   * encoded with msgpack as a typed array.
+   * @param version - multisig version
+   * @param threshold - multisig threshold
+   * @param pks - multisig public key list, order is important.
+   * @param sk - an Algorand secret key to sign with.
+   * @returns an encoded, partially signed multisig transaction.
+   */
+  partialSignTxn(
+    { version, threshold, pks }: MultisigMetadataWithPks,
+    sk: Uint8Array
+  ) {
+    // get signature verifier
+    const myPk = nacl.keyPairFromSecretKey(sk).publicKey;
+    return createMultisigTransactionWithSignature(
+      this,
+      { rawSig: this.rawSignTxn(sk), myPk },
+      { version, threshold, pks }
+    );
+  }
+
+  /**
+   * partialSignWithMultisigSignature partially signs this transaction with an external raw multisig signature and returns
+   * a partially-signed multisig transaction, encoded with msgpack as a typed array.
+   * @param metadata - multisig metadata
+   * @param signerAddr - address of the signer
+   * @param signature - raw multisig signature
+   * @returns an encoded, partially signed multisig transaction.
+   */
+  partialSignWithMultisigSignature(
+    metadata: MultisigMetadataWithPks,
+    signerAddr: string,
+    signature: Uint8Array
+  ) {
+    if (!nacl.isValidSignatureLength(signature.length)) {
+      throw new Error(MULTISIG_SIGNATURE_LENGTH_ERROR_MSG);
+    }
+    return createMultisigTransactionWithSignature(
+      this,
+      {
+        rawSig: signature,
+        myPk: address.decodeAddress(signerAddr).publicKey,
+      },
+      metadata
+    );
+  }
+
+  // eslint-disable-next-line camelcase
+  static from_obj_for_encoding(
+    txnForEnc: EncodedTransaction
+  ): MultisigTransaction {
+    return super.from_obj_for_encoding(txnForEnc) as MultisigTransaction;
+  }
+}
+
+/**
+ * mergeMultisigTransactions takes a list of multisig transaction blobs, and merges them.
+ * @param multisigTxnBlobs - a list of blobs representing encoded multisig txns
+ * @returns typed array msg-pack encoded multisig txn
+ */
+export function mergeMultisigTransactions(multisigTxnBlobs: Uint8Array[]) {
+  if (multisigTxnBlobs.length < 2) {
+    throw new Error(MULTISIG_MERGE_LESSTHANTWO_ERROR_MSG);
+  }
+  const refSigTx = encoding.decode(
+    multisigTxnBlobs[0]
+  ) as EncodedSignedTransaction;
+  const refTxID = MultisigTransaction.from_obj_for_encoding(
+    refSigTx.txn
+  ).txID();
+  const refAuthAddr = refSigTx.sgnr
+    ? address.encodeAddress(refSigTx.sgnr)
+    : undefined;
+  const refPreImage = {
+    version: refSigTx.msig.v,
+    threshold: refSigTx.msig.thr,
+    pks: refSigTx.msig.subsig.map((subsig) => subsig.pk),
+  };
+  const refMsigAddr = address.encodeAddress(
+    address.fromMultisigPreImg(refPreImage)
+  );
+
+  const newSubsigs = refSigTx.msig.subsig.map((sig) => ({ ...sig }));
+  for (let i = 1; i < multisigTxnBlobs.length; i++) {
+    const unisig = encoding.decode(
+      multisigTxnBlobs[i]
+    ) as EncodedSignedTransaction;
+
+    const unisigAlgoTxn = MultisigTransaction.from_obj_for_encoding(unisig.txn);
+    if (unisigAlgoTxn.txID() !== refTxID) {
+      throw new Error(MULTISIG_MERGE_MISMATCH_ERROR_MSG);
+    }
+
+    const authAddr = unisig.sgnr
+      ? address.encodeAddress(unisig.sgnr)
+      : undefined;
+    if (refAuthAddr !== authAddr) {
+      throw new Error(MULTISIG_MERGE_MISMATCH_AUTH_ADDR_MSG);
+    }
+
+    // check multisig has same preimage as reference
+    if (unisig.msig.subsig.length !== refSigTx.msig.subsig.length) {
+      throw new Error(MULTISIG_MERGE_WRONG_PREIMAGE_ERROR_MSG);
+    }
+    const preimg: MultisigMetadataWithPks = {
+      version: unisig.msig.v,
+      threshold: unisig.msig.thr,
+      pks: unisig.msig.subsig.map((subsig) => subsig.pk),
+    };
+    const msgigAddr = address.encodeAddress(address.fromMultisigPreImg(preimg));
+    if (refMsigAddr !== msgigAddr) {
+      throw new Error(MULTISIG_MERGE_WRONG_PREIMAGE_ERROR_MSG);
+    }
+
+    // now, we can merge
+    unisig.msig.subsig.forEach((uniSubsig, index) => {
+      if (!uniSubsig.s) return;
+      const current = newSubsigs[index];
+      // we convert the Uint8Arrays uniSubsig.s and current.s to Buffers here because (as
+      // of Dec 2020) React overrides the buffer package with an older version that does
+      // not support Uint8Arrays in the comparison function. See this thread for more
+      // info: https://github.com/algorand/js-algorand-sdk/issues/252
+      if (
+        current.s &&
+        Buffer.compare(Buffer.from(uniSubsig.s), Buffer.from(current.s)) !== 0
+      ) {
+        // mismatch
+        throw new Error(MULTISIG_MERGE_SIG_MISMATCH_ERROR_MSG);
+      }
+      current.s = uniSubsig.s;
+    });
+  }
+  const msig: EncodedMultisig = {
+    v: refSigTx.msig.v,
+    thr: refSigTx.msig.thr,
+    subsig: newSubsigs,
+  };
+  const signedTxn: EncodedSignedTransaction = {
+    msig,
+    txn: refSigTx.txn,
+  };
+  if (typeof refAuthAddr !== 'undefined') {
+    signedTxn.sgnr = Buffer.from(address.decodeAddress(refAuthAddr).publicKey);
+  }
+  return new Uint8Array(encoding.encode(signedTxn));
+}
+
+export function verifyMultisig(
+  toBeVerified: Uint8Array,
+  msig: EncodedMultisig,
+  publicKey: Uint8Array
+) {
+  const version = msig.v;
+  const threshold = msig.thr;
+  const subsigs = msig.subsig;
+
+  const pks = subsigs.map((subsig) => subsig.pk);
+  if (msig.subsig.length < threshold) {
+    return false;
+  }
+
+  let pk: Uint8Array;
+  try {
+    pk = address.fromMultisigPreImg({ version, threshold, pks });
+  } catch (e) {
+    return false;
+  }
+
+  if (!utils.arrayEqual(pk, publicKey)) {
+    return false;
+  }
+
+  let counter = 0;
+  for (const subsig of subsigs) {
+    if (subsig.s !== undefined) {
+      counter += 1;
+    }
+  }
+  if (counter < threshold) {
+    return false;
+  }
+
+  let verifiedCounter = 0;
+  for (const subsig of subsigs) {
+    if (subsig.s !== undefined) {
+      if (nacl.verify(toBeVerified, subsig.s, subsig.pk)) {
+        verifiedCounter += 1;
+      }
+    }
+  }
+
+  if (verifiedCounter < threshold) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * signMultisigTransaction takes a raw transaction (see signTransaction), a multisig preimage, a secret key, and returns
+ * a multisig transaction, which is a blob representing a transaction and multisignature account preimage. The returned
+ * multisig txn can accumulate additional signatures through mergeMultisigTransactions or appendSignMultisigTransaction.
+ * @param txn - object with either payment or key registration fields
+ * @param version - multisig version
+ * @param threshold - multisig threshold
+ * @param addrs - a list of Algorand addresses representing possible signers for this multisig. Order is important.
+ * @param sk - Algorand secret key. The corresponding pk should be in the pre image.
+ * @returns object containing txID, and blob of partially signed multisig transaction (with multisig preimage information)
+ * If the final calculated fee is lower than the protocol minimum fee, the fee will be increased to match the minimum.
+ */
+export function signMultisigTransaction(
+  txn: txnBuilder.TransactionLike,
+  { version, threshold, addrs }: MultisigMetadata,
+  sk: Uint8Array
+) {
+  // check that the from field matches the mSigPreImage. If from field is not populated, fill it in.
+  const expectedFromRaw = address.fromMultisigPreImgAddrs({
+    version,
+    threshold,
+    addrs,
+  });
+  if (!Object.prototype.hasOwnProperty.call(txn, 'from')) {
+    // eslint-disable-next-line no-param-reassign
+    txn.from = expectedFromRaw;
+  }
+  // build pks for partialSign
+  const pks = addrs.map((addr) => address.decodeAddress(addr).publicKey);
+  // `txn` needs to be handled differently if it's a constructed `Transaction` vs a dict of constructor args
+  const txnAlreadyBuilt = txn instanceof txnBuilder.Transaction;
+  let algoTxn: MultisigTransaction;
+  let blob: Uint8Array;
+  if (txnAlreadyBuilt) {
+    algoTxn = (txn as unknown) as MultisigTransaction;
+    blob = MultisigTransaction.prototype.partialSignTxn.call(
+      algoTxn,
+      { version, threshold, pks },
+      sk
+    );
+  } else {
+    algoTxn = new MultisigTransaction(txn as AnyTransaction);
+    blob = algoTxn.partialSignTxn({ version, threshold, pks }, sk);
+  }
+  return {
+    txID: algoTxn.txID().toString(),
+    blob,
+  };
+}
+
+/**
+ * appendSignMultisigTransaction takes a multisig transaction blob, and appends our signature to it.
+ * While we could derive public key preimagery from the partially-signed multisig transaction,
+ * we ask the caller to pass it back in, to ensure they know what they are signing.
+ * @param multisigTxnBlob - an encoded multisig txn. Supports non-payment txn types.
+ * @param version - multisig version
+ * @param threshold - multisig threshold
+ * @param addrs - a list of Algorand addresses representing possible signers for this multisig. Order is important.
+ * @param sk - Algorand secret key
+ * @returns object containing txID, and blob representing encoded multisig txn
+ */
+export function appendSignMultisigTransaction(
+  multisigTxnBlob: Uint8Array,
+  { version, threshold, addrs }: MultisigMetadata,
+  sk: Uint8Array
+) {
+  const pks = addrs.map((addr) => address.decodeAddress(addr).publicKey);
+  // obtain underlying txn, sign it, and merge it
+  const multisigTxObj = encoding.decode(
+    multisigTxnBlob
+  ) as EncodedSignedTransaction;
+  const msigTxn = MultisigTransaction.from_obj_for_encoding(multisigTxObj.txn);
+  const partialSignedBlob = msigTxn.partialSignTxn(
+    { version, threshold, pks },
+    sk
+  );
+  return {
+    txID: msigTxn.txID().toString(),
+    blob: mergeMultisigTransactions([multisigTxnBlob, partialSignedBlob]),
+  };
+}
+
+/**
+ * appendMultisigTransactionSignature takes a multisig transaction blob, and appends a given raw signature to it.
+ * This makes it possible to compile a multisig signature using only raw signatures from external methods.
+ * @param multisigTxnBlob - an encoded multisig txn. Supports non-payment txn types.
+ * @param version - multisig version
+ * @param threshold - multisig threshold
+ * @param addrs - a list of Algorand addresses representing possible signers for this multisig. Order is important.
+ * @param signerAddr - address of the signer
+ * @param signature - raw multisig signature
+ * @returns object containing txID, and blob representing encoded multisig txn
+ */
+export function appendSignRawMultisigSignature(
+  multisigTxnBlob: Uint8Array,
+  { version, threshold, addrs }: MultisigMetadata,
+  signerAddr: string,
+  signature: Uint8Array
+) {
+  const pks = addrs.map((addr) => address.decodeAddress(addr).publicKey);
+  // obtain underlying txn, sign it, and merge it
+  const multisigTxObj = encoding.decode(
+    multisigTxnBlob
+  ) as EncodedSignedTransaction;
+  const msigTxn = MultisigTransaction.from_obj_for_encoding(multisigTxObj.txn);
+  const partialSignedBlob = msigTxn.partialSignWithMultisigSignature(
+    { version, threshold, pks },
+    signerAddr,
+    signature
+  );
+  return {
+    txID: msigTxn.txID().toString(),
+    blob: mergeMultisigTransactions([multisigTxnBlob, partialSignedBlob]),
+  };
+}
+
+/**
+ * multisigAddress takes multisig metadata (preimage) and returns the corresponding human readable Algorand address.
+ * @param version - multisig version
+ * @param threshold - multisig threshold
+ * @param addrs - list of Algorand addresses
+ */
+export function multisigAddress({
+  version,
+  threshold,
+  addrs,
+}: MultisigMetadata) {
+  return address.fromMultisigPreImgAddrs({ version, threshold, addrs });
+}

package/src/nacl/naclWrappers.ts

@@ -0,0 +1,49 @@
+import nacl from 'tweetnacl';
+import sha512 from 'js-sha512';
+
+export function genericHash(arr: sha512.Message) {
+  return sha512.sha512_256.array(arr);
+}
+
+export function randomBytes(length: number) {
+  return nacl.randomBytes(length);
+}
+
+export function keyPairFromSeed(seed: Uint8Array) {
+  return nacl.sign.keyPair.fromSeed(seed);
+}
+
+export function keyPair() {
+  const seed = randomBytes(nacl.box.secretKeyLength);
+  return keyPairFromSeed(seed);
+}
+
+export function isValidSignatureLength(len: number) {
+  return len === nacl.sign.signatureLength;
+}
+
+export function keyPairFromSecretKey(sk: Uint8Array) {
+  return nacl.sign.keyPair.fromSecretKey(sk);
+}
+
+export function sign(msg: Uint8Array, secretKey: Uint8Array) {
+  return nacl.sign.detached(msg, secretKey);
+}
+
+export function bytesEqual(a: Uint8Array, b: Uint8Array) {
+  return nacl.verify(a, b);
+}
+
+export function verify(
+  message: Uint8Array,
+  signature: Uint8Array,
+  verifyKey: Uint8Array
+) {
+  return nacl.sign.detached.verify(message, signature, verifyKey);
+}
+
+// constants
+export const PUBLIC_KEY_LENGTH = nacl.sign.publicKeyLength;
+export const SECRET_KEY_LENGTH = nacl.sign.secretKeyLength;
+export const HASH_BYTES_LENGTH = 32;
+export const SEED_BTYES_LENGTH = 32;

package/src/signer.ts

@@ -0,0 +1,105 @@
+import { Transaction } from './transaction';
+import Account from './types/account';
+import { LogicSigAccount, signLogicSigTransactionObject } from './logicsig';
+import { MultisigMetadata } from './types/multisig';
+import { signMultisigTransaction, mergeMultisigTransactions } from './multisig';
+
+/**
+ * This type represents a function which can sign transactions from an atomic transaction group.
+ * @param txnGroup - The atomic group containing transactions to be signed
+ * @param indexesToSign - An array of indexes in the atomic transaction group that should be signed
+ * @returns A promise which resolves an array of encoded signed transactions. The length of the
+ *   array will be the same as the length of indexesToSign, and each index i in the array
+ *   corresponds to the signed transaction from txnGroup[indexesToSign[i]]
+ */
+export type TransactionSigner = (
+  txnGroup: Transaction[],
+  indexesToSign: number[]
+) => Promise<Uint8Array[]>;
+
+/**
+ * Create a TransactionSigner that can sign transactions for the provided basic Account.
+ */
+export function makeBasicAccountTransactionSigner(
+  account: Account
+): TransactionSigner {
+  return (txnGroup: Transaction[], indexesToSign: number[]) => {
+    const signed: Uint8Array[] = [];
+
+    for (const index of indexesToSign) {
+      signed.push(txnGroup[index].signTxn(account.sk));
+    }
+
+    return Promise.resolve(signed);
+  };
+}
+
+/**
+ * Create a TransactionSigner that can sign transactions for the provided LogicSigAccount.
+ */
+export function makeLogicSigAccountTransactionSigner(
+  account: LogicSigAccount
+): TransactionSigner {
+  return (txnGroup: Transaction[], indexesToSign: number[]) => {
+    const signed: Uint8Array[] = [];
+
+    for (const index of indexesToSign) {
+      const { blob } = signLogicSigTransactionObject(txnGroup[index], account);
+      signed.push(blob);
+    }
+
+    return Promise.resolve(signed);
+  };
+}
+
+/**
+ * Create a TransactionSigner that can sign transactions for the provided Multisig account.
+ * @param msig - The Multisig account metadata
+ * @param sks - An array of private keys belonging to the msig which should sign the transactions.
+ */
+export function makeMultiSigAccountTransactionSigner(
+  msig: MultisigMetadata,
+  sks: Uint8Array[]
+): TransactionSigner {
+  return (txnGroup: Transaction[], indexesToSign: number[]) => {
+    const signed: Uint8Array[] = [];
+
+    for (const index of indexesToSign) {
+      const txn = txnGroup[index];
+      const partialSigs: Uint8Array[] = [];
+
+      for (const sk of sks) {
+        const { blob } = signMultisigTransaction(txn, msig, sk);
+        partialSigs.push(blob);
+      }
+
+      signed.push(mergeMultisigTransactions(partialSigs));
+    }
+
+    return Promise.resolve(signed);
+  };
+}
+
+/** Represents an unsigned transactions and a signer that can authorize that transaction. */
+export interface TransactionWithSigner {
+  /** An unsigned transaction */
+  txn: Transaction;
+  /** A transaction signer that can authorize txn */
+  signer: TransactionSigner;
+}
+
+/**
+ * Check if a value conforms to the TransactionWithSigner structure.
+ * @param value - The value to check.
+ * @returns True if an only if the value has the structure of a TransactionWithSigner.
+ */
+export function isTransactionWithSigner(
+  value: any
+): value is TransactionWithSigner {
+  return (
+    typeof value === 'object' &&
+    Object.keys(value).length === 2 &&
+    typeof value.txn === 'object' &&
+    typeof value.signer === 'function'
+  );
+}