algosdk 2.9.0 → 3.0.0-beta.1

package/src/multisigSigning.ts

@@ -0,0 +1,359 @@
+import * as nacl from './nacl/naclWrappers.js';
+import { Address } from './encoding/address.js';
+import * as encoding from './encoding/encoding.js';
+import { Transaction } from './transaction.js';
+import * as utils from './utils/utils.js';
+import { EncodedMultisig } from './types/transactions/encoded.js';
+import { SignedTransaction } from './signedTransaction.js';
+import {
+  MultisigMetadata,
+  addressFromMultisigPreImg,
+  pksFromAddresses,
+} from './multisig.js';
+
+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.';
+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.';
+const MULTISIG_KEY_NOT_EXIST_ERROR_MSG = 'Key does not exist';
+
+/**
+ * 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: Transaction,
+  { version, threshold, addrs }: MultisigMetadata
+) {
+  // construct the appendable multisigned transaction format
+  const pks = pksFromAddresses(addrs);
+  const subsigs = pks.map((pk) => ({ pk }));
+
+  const msig: EncodedMultisig = {
+    v: version,
+    thr: threshold,
+    subsig: subsigs,
+  };
+
+  // if the address of this multisig is different from the transaction sender,
+  // we need to add the auth-addr field
+  const msigAddr = addressFromMultisigPreImg({
+    version,
+    threshold,
+    pks,
+  });
+  let sgnr: Address | undefined;
+  if (!txn.sender.equals(msigAddr)) {
+    sgnr = msigAddr;
+  }
+
+  const signedTxn = new SignedTransaction({
+    txn,
+    msig,
+    sgnr,
+  });
+
+  return encoding.encodeMsgpack(signedTxn);
+}
+
+interface MultisigOptions {
+  rawSig: Uint8Array;
+  myPk: Uint8Array;
+}
+
+interface MultisigMetadataWithPks extends Omit<MultisigMetadata, 'addrs'> {
+  pks: Uint8Array[];
+}
+
+/**
+ * createMultisigTransactionWithSignature creates a multisig transaction blob with an included signature.
+ * @param txn - the actual transaction to sign.
+ * @param rawSig - a Uint8Array 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: Transaction,
+  { rawSig, myPk }: MultisigOptions,
+  { version, threshold, pks }: MultisigMetadataWithPks
+): Uint8Array {
+  // Create an empty encoded multisig transaction
+  const encodedMsig = createMultisigTransaction(txn, {
+    version,
+    threshold,
+    addrs: pks.map((pk) => new Address(pk)),
+  });
+  // note: this is not signed yet, but will be shortly
+  const signedTxn = encoding.decodeMsgpack(encodedMsig, SignedTransaction);
+
+  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) {
+    throw new Error(MULTISIG_KEY_NOT_EXIST_ERROR_MSG);
+  }
+
+  return encoding.encodeMsgpack(signedTxn);
+}
+
+/**
+ * partialSignTxn partially signs this transaction and returns a partially-signed multisig transaction,
+ * encoded with msgpack as a typed array.
+ * @param transaction - The transaction to sign
+ * @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.
+ */
+function partialSignTxn(
+  transaction: Transaction,
+  { version, threshold, pks }: MultisigMetadataWithPks,
+  sk: Uint8Array
+) {
+  // get signature verifier
+  const myPk = nacl.keyPairFromSecretKey(sk).publicKey;
+  return createMultisigTransactionWithSignature(
+    transaction,
+    { rawSig: transaction.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 transaction - The transaction to sign
+ * @param metadata - multisig metadata
+ * @param signerAddr - address of the signer
+ * @param signature - raw multisig signature
+ * @returns an encoded, partially signed multisig transaction.
+ */
+function partialSignWithMultisigSignature(
+  transaction: Transaction,
+  metadata: MultisigMetadataWithPks,
+  signerAddr: string | Address,
+  signature: Uint8Array
+) {
+  if (!nacl.isValidSignatureLength(signature.length)) {
+    throw new Error(MULTISIG_SIGNATURE_LENGTH_ERROR_MSG);
+  }
+  const signerAddressObj =
+    typeof signerAddr === 'string'
+      ? Address.fromString(signerAddr)
+      : signerAddr;
+  return createMultisigTransactionWithSignature(
+    transaction,
+    {
+      rawSig: signature,
+      myPk: signerAddressObj.publicKey,
+    },
+    metadata
+  );
+}
+
+/**
+ * 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.decodeMsgpack(
+    multisigTxnBlobs[0],
+    SignedTransaction
+  );
+  if (!refSigTx.msig) {
+    throw new Error(
+      'Invalid multisig transaction, multisig structure missing at index 0'
+    );
+  }
+  const refTxID = refSigTx.txn.txID();
+  const refAuthAddr = refSigTx.sgnr ? refSigTx.sgnr.toString() : undefined;
+  const refPreImage = {
+    version: refSigTx.msig.v,
+    threshold: refSigTx.msig.thr,
+    pks: refSigTx.msig.subsig.map((subsig) => subsig.pk),
+  };
+  const refMsigAddr = addressFromMultisigPreImg(refPreImage);
+
+  const newSubsigs = refSigTx.msig.subsig.map((sig) => ({ ...sig }));
+  for (let i = 1; i < multisigTxnBlobs.length; i++) {
+    const unisig = encoding.decodeMsgpack(
+      multisigTxnBlobs[i],
+      SignedTransaction
+    );
+    if (!unisig.msig) {
+      throw new Error(
+        `Invalid multisig transaction, multisig structure missing at index ${i}`
+      );
+    }
+
+    if (unisig.txn.txID() !== refTxID) {
+      throw new Error(MULTISIG_MERGE_MISMATCH_ERROR_MSG);
+    }
+
+    const authAddr = unisig.sgnr ? unisig.sgnr.toString() : 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 = addressFromMultisigPreImg(preimg);
+    if (!refMsigAddr.equals(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];
+      if (current.s && !utils.arrayEqual(uniSubsig.s, current.s)) {
+        // 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 refSgnr =
+    typeof refAuthAddr !== 'undefined' ? refSigTx.sgnr : undefined;
+  const signedTxn = new SignedTransaction({
+    msig,
+    txn: refSigTx.txn,
+    sgnr: refSgnr,
+  });
+  return encoding.encodeMsgpack(signedTxn);
+}
+
+/**
+ * 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: Transaction,
+  { version, threshold, addrs }: MultisigMetadata,
+  sk: Uint8Array
+) {
+  // build pks for partialSign
+  const pks = pksFromAddresses(addrs);
+  const blob = partialSignTxn(txn, { version, threshold, pks }, sk);
+  return {
+    txID: txn.txID(),
+    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 = pksFromAddresses(addrs);
+  // obtain underlying txn, sign it, and merge it
+  const multisigTxObj = encoding.decodeMsgpack(
+    multisigTxnBlob,
+    SignedTransaction
+  );
+  const partialSignedBlob = partialSignTxn(
+    multisigTxObj.txn,
+    { version, threshold, pks },
+    sk
+  );
+  return {
+    txID: multisigTxObj.txn.txID(),
+    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 | Address,
+  signature: Uint8Array
+) {
+  const pks = pksFromAddresses(addrs);
+  // obtain underlying txn, sign it, and merge it
+  const multisigTxObj = encoding.decodeMsgpack(
+    multisigTxnBlob,
+    SignedTransaction
+  );
+  const partialSignedBlob = partialSignWithMultisigSignature(
+    multisigTxObj.txn,
+    { version, threshold, pks },
+    signerAddr,
+    signature
+  );
+  return {
+    txID: multisigTxObj.txn.txID(),
+    blob: mergeMultisigTransactions([multisigTxnBlob, partialSignedBlob]),
+  };
+}

package/src/nacl/naclWrappers.ts

@@ -1,6 +1,6 @@
 import nacl from 'tweetnacl';
 import sha512 from 'js-sha512';
-import { isReactNative } from '../utils/utils';
+import { isReactNative } from '../utils/utils.js';
 
 export function genericHash(arr: sha512.Message) {
   return sha512.sha512_256.array(arr);

package/src/signedTransaction.ts

@@ -0,0 +1,163 @@
+import {
+  Encodable,
+  encodeMsgpack,
+  decodeMsgpack,
+} from './encoding/encoding.js';
+import { Address } from './encoding/address.js';
+import { Transaction } from './transaction.js';
+import { LogicSig } from './logicsig.js';
+import {
+  EncodedMultisig,
+  encodedMultiSigToEncodingData,
+  encodedMultiSigFromEncodingData,
+  ENCODED_MULTISIG_SCHEMA,
+} from './types/transactions/index.js';
+import {
+  AddressSchema,
+  FixedLengthByteArraySchema,
+  OptionalSchema,
+  NamedMapSchema,
+  allOmitEmpty,
+} from './encoding/schema/index.js';
+
+export class SignedTransaction implements Encodable {
+  static readonly encodingSchema = new NamedMapSchema(
+    allOmitEmpty([
+      {
+        key: 'txn',
+        valueSchema: Transaction.encodingSchema,
+      },
+      {
+        key: 'sig',
+        valueSchema: new OptionalSchema(new FixedLengthByteArraySchema(64)),
+      },
+      {
+        key: 'msig',
+        valueSchema: new OptionalSchema(ENCODED_MULTISIG_SCHEMA),
+      },
+      {
+        key: 'lsig',
+        valueSchema: new OptionalSchema(LogicSig.encodingSchema),
+      },
+      {
+        key: 'sgnr',
+        valueSchema: new OptionalSchema(new AddressSchema()),
+      },
+    ])
+  );
+
+  /**
+   * The transaction that was signed
+   */
+  public readonly txn: Transaction;
+
+  /**
+   * Transaction signature
+   */
+  public readonly sig?: Uint8Array;
+
+  /**
+   * Multisig structure
+   */
+  public readonly msig?: EncodedMultisig;
+
+  /**
+   * Logic signature
+   */
+  public readonly lsig?: LogicSig;
+
+  /**
+   * The signer, if signing with a different key than the Transaction type `sender` property indicates
+   */
+  public readonly sgnr?: Address;
+
+  constructor({
+    txn,
+    sig,
+    msig,
+    lsig,
+    sgnr,
+  }: {
+    txn: Transaction;
+    sig?: Uint8Array;
+    msig?: EncodedMultisig;
+    lsig?: LogicSig;
+    sgnr?: Address;
+  }) {
+    this.txn = txn;
+    this.sig = sig;
+    this.msig = msig;
+    this.lsig = lsig;
+    this.sgnr = sgnr;
+
+    let numberOfSigs = 0;
+    if (sig) numberOfSigs += 1;
+    if (msig) numberOfSigs += 1;
+    if (lsig) numberOfSigs += 1;
+    if (numberOfSigs > 1) {
+      throw new Error(
+        `SignedTransaction must not have more than 1 signature. Got ${numberOfSigs}`
+      );
+    }
+  }
+
+  // eslint-disable-next-line class-methods-use-this
+  public getEncodingSchema() {
+    return SignedTransaction.encodingSchema;
+  }
+
+  public toEncodingData(): Map<string, unknown> {
+    return new Map<string, unknown>([
+      ['txn', this.txn.toEncodingData()],
+      ['sig', this.sig],
+      [
+        'msig',
+        this.msig ? encodedMultiSigToEncodingData(this.msig) : undefined,
+      ],
+      ['lsig', this.lsig ? this.lsig.toEncodingData() : undefined],
+      ['sgnr', this.sgnr],
+    ]);
+  }
+
+  public static fromEncodingData(data: unknown): SignedTransaction {
+    if (!(data instanceof Map)) {
+      throw new Error(`Invalid decoded SignedTransaction: ${data}`);
+    }
+    return new SignedTransaction({
+      txn: Transaction.fromEncodingData(data.get('txn')),
+      sig: data.get('sig'),
+      msig: data.get('msig')
+        ? encodedMultiSigFromEncodingData(data.get('msig'))
+        : undefined,
+      lsig: data.get('lsig')
+        ? LogicSig.fromEncodingData(data.get('lsig'))
+        : undefined,
+      sgnr: data.get('sgnr'),
+    });
+  }
+}
+
+/**
+ * decodeSignedTransaction takes a Uint8Array (from transaction.signTxn) and converts it to an object
+ * containing the Transaction (txn), the signature (sig), and the auth-addr field if applicable (sgnr)
+ * @param transactionBuffer - the Uint8Array containing a transaction
+ * @returns containing a Transaction, the signature, and possibly an auth-addr field
+ */
+export function decodeSignedTransaction(
+  transactionBuffer: Uint8Array
+): SignedTransaction {
+  return decodeMsgpack(transactionBuffer, SignedTransaction);
+}
+
+/**
+ * encodeUnsignedSimulateTransaction takes a txnBuilder.Transaction object,
+ * converts it into a SignedTransaction-like object, and converts it to a Buffer.
+ *
+ * Note: this function should only be used to simulate unsigned transactions.
+ *
+ * @param txn - Transaction object to simulate.
+ */
+export function encodeUnsignedSimulateTransaction(txn: Transaction) {
+  const stxn = new SignedTransaction({ txn });
+  return encodeMsgpack(stxn);
+}

package/src/signer.ts

@@ -1,8 +1,13 @@
-import { encodeUnsignedSimulateTransaction, Transaction } from './transaction';
-import Account from './types/account';
-import { LogicSigAccount, signLogicSigTransactionObject } from './logicsig';
-import { MultisigMetadata } from './types/multisig';
-import { signMultisigTransaction, mergeMultisigTransactions } from './multisig';
+import Account from './types/account.js';
+import { Transaction } from './transaction.js';
+import { encodeUnsignedSimulateTransaction } from './signedTransaction.js';
+import { LogicSigAccount } from './logicsig.js';
+import { signLogicSigTransactionObject } from './signing.js';
+import { MultisigMetadata } from './multisig.js';
+import {
+  signMultisigTransaction,
+  mergeMultisigTransactions,
+} from './multisigSigning.js';
 
 /**
  * This type represents a function which can sign transactions from an atomic transaction group.

package/src/signing.ts

@@ -0,0 +1,95 @@
+import * as nacl from './nacl/naclWrappers.js';
+import { Address } from './encoding/address.js';
+import * as encoding from './encoding/encoding.js';
+import { SignedTransaction } from './signedTransaction.js';
+import { Transaction } from './transaction.js';
+import { LogicSig, LogicSigAccount } from './logicsig.js';
+import { addressFromMultisigPreImg } from './multisig.js';
+
+function signLogicSigTransactionWithAddress(
+  txn: Transaction,
+  lsig: LogicSig,
+  lsigAddress: Address
+) {
+  if (!lsig.verify(lsigAddress.publicKey)) {
+    throw new Error(
+      'Logic signature verification failed. Ensure the program and signature are valid.'
+    );
+  }
+
+  let sgnr: Address | undefined;
+  if (!nacl.bytesEqual(lsigAddress.publicKey, txn.sender.publicKey)) {
+    sgnr = lsigAddress;
+  }
+
+  const signedTxn = new SignedTransaction({
+    lsig,
+    txn,
+    sgnr,
+  });
+
+  return {
+    txID: txn.txID(),
+    blob: encoding.encodeMsgpack(signedTxn),
+  };
+}
+
+/**
+ * signLogicSigTransactionObject takes a transaction and a LogicSig object and
+ * returns a signed transaction.
+ *
+ * @param txn - The transaction to sign.
+ * @param lsigObject - The LogicSig object that will sign the transaction.
+ *
+ * @returns Object containing txID and blob representing signed transaction.
+ */
+export function signLogicSigTransactionObject(
+  txn: Transaction,
+  lsigObject: LogicSig | LogicSigAccount
+) {
+  let lsig: LogicSig;
+  let lsigAddress: Address;
+
+  if (lsigObject instanceof LogicSigAccount) {
+    lsig = lsigObject.lsig;
+    lsigAddress = lsigObject.address();
+  } else {
+    lsig = lsigObject;
+
+    if (lsig.sig) {
+      // For a LogicSig with a non-multisig delegating account, we cannot derive
+      // the address of that account from only its signature, so assume the
+      // delegating account is the sender. If that's not the case, the signing
+      // will fail.
+      lsigAddress = new Address(txn.sender.publicKey);
+    } else if (lsig.msig) {
+      const msigMetadata = {
+        version: lsig.msig.v,
+        threshold: lsig.msig.thr,
+        pks: lsig.msig.subsig.map((subsig) => subsig.pk),
+      };
+      lsigAddress = addressFromMultisigPreImg(msigMetadata);
+    } else {
+      lsigAddress = lsig.address();
+    }
+  }
+
+  return signLogicSigTransactionWithAddress(txn, lsig, lsigAddress);
+}
+
+/**
+ * signLogicSigTransaction takes a transaction and a LogicSig object and returns
+ * a signed transaction.
+ *
+ * @param txn - The transaction to sign.
+ * @param lsigObject - The LogicSig object that will sign the transaction.
+ *
+ * @returns Object containing txID and blob representing signed transaction.
+ * @throws error on failure
+ */
+export function signLogicSigTransaction(
+  txn: Transaction,
+  lsigObject: LogicSig | LogicSigAccount
+) {
+  return signLogicSigTransactionObject(txn, lsigObject);
+}