algosdk 3.6.0 → 3.7.0

package/src/multisigSigning.ts

@@ -10,6 +10,8 @@ import {
   addressFromMultisigPreImg,
   pksFromAddresses,
 } from './multisig.js';
+import type { TransactionSigner } from './signer.js';
+import { signTransactionWithSigner } from './signing.js';
 
 export const MULTISIG_MERGE_LESSTHANTWO_ERROR_MSG =
   'Not enough multisig transactions to merge. Need at least two';
@@ -144,6 +146,36 @@ function partialSignTxn(
   );
 }
 
+async function partialSignTxnWithSigner(
+  transaction: Transaction,
+  { version, threshold, pks }: MultisigMetadataWithPks,
+  txnSigner: TransactionSigner
+) {
+  const { stxn } = await signTransactionWithSigner(transaction, txnSigner);
+  const rawSig = stxn.sig;
+
+  if (rawSig === undefined) {
+    throw Error(
+      `Expected TransactionSigner to return a signed transaction with a sig, but sig was empty`
+    );
+  }
+
+  // A signer reports which key it signed with in `sgnr`, but omits it when that
+  // key is the transaction sender, so fall back to the sender. If neither is a
+  // member of the multisig, createMultisigTransactionWithSignature rejects it
+  // rather than attaching the signature to the wrong subsig.
+  const myPk = (stxn.sgnr ?? transaction.sender).publicKey;
+
+  return createMultisigTransactionWithSignature(
+    transaction,
+    {
+      rawSig,
+      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.
@@ -265,6 +297,8 @@ export function mergeMultisigTransactions(multisigTxnBlobs: Uint8Array[]) {
 }
 
 /**
+ * @deprecated Use {@link signMultisigTransactionWithSigner} instead
+ *
  * 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.
@@ -291,6 +325,44 @@ export function signMultisigTransaction(
 }
 
 /**
+ * signMultisigTransactionWithSigner takes a raw transaction, a multisig preimage and a signer, and
+ * returns a multisig transaction: a blob representing a transaction and multisignature account
+ * preimage. The returned multisig txn can accumulate additional signatures through
+ * mergeMultisigTransactions or appendSignMultisigTransactionWithSigner.
+ *
+ * The signer must hold a key belonging to the multisig. That key is taken from the `sgnr` field of
+ * the transaction the signer returns, falling back to the transaction sender when `sgnr` is absent
+ * — which is the same convention signers use when writing it. Every signer this SDK provides
+ * follows it. Note that `AddressWithTransactionSigner.address` cannot be used for this: it is the
+ * address the signer sends transactions from, which for a rekeyed account is not the signing key.
+ *
+ * @param txn - the transaction to sign
+ * @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 txnSigner - the signer to sign with
+ * @returns an object with txID and blob properties
+ */
+export async function signMultisigTransactionWithSigner(
+  txn: Transaction,
+  { version, threshold, addrs }: MultisigMetadata,
+  txnSigner: TransactionSigner
+) {
+  const pks = pksFromAddresses(addrs);
+  const blob = await partialSignTxnWithSigner(
+    txn,
+    { version, threshold, pks },
+    txnSigner
+  );
+  return {
+    txID: txn.txID(),
+    blob,
+  };
+}
+
+/**
+ * @deprecated Use {@link appendSignMultisigTransactionWithSigner} instead
+ *
  * 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.
@@ -323,6 +395,45 @@ export function appendSignMultisigTransaction(
   };
 }
 
+/**
+ * appendSignMultisigTransactionWithSigner takes a multisig transaction blob, and appends the given
+ * signer's 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.
+ *
+ * As with {@link signMultisigTransactionWithSigner}, the signer's key is taken from the `sgnr`
+ * field of the transaction it returns, falling back to the transaction sender when `sgnr` is
+ * absent.
+ *
+ * @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 txnSigner - the signer to sign with
+ * @returns an object with txID and blob properties
+ */
+export async function appendSignMultisigTransactionWithSigner(
+  multisigTxnBlob: Uint8Array,
+  { version, threshold, addrs }: MultisigMetadata,
+  txnSigner: TransactionSigner
+) {
+  const pks = pksFromAddresses(addrs);
+  // obtain underlying txn, sign it, and merge it
+  const multisigTxObj = encoding.decodeMsgpack(
+    multisigTxnBlob,
+    SignedTransaction
+  );
+  const partialSignedBlob = await partialSignTxnWithSigner(
+    multisigTxObj.txn,
+    { version, threshold, pks },
+    txnSigner
+  );
+  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.

package/src/pq-signer.ts

@@ -0,0 +1,123 @@
+import { Address, addressFromPQKey } from './encoding/address.js';
+import { encodeMsgpack } from './encoding/encoding.js';
+import { LogicSig, PQ_PROGRAM_TAG } from './logicsig.js';
+import { MultisigMetadata } from './multisig.js';
+import { SignedTransaction } from './signedTransaction.js';
+import {
+  AddressWithDelegatedLsigSigner,
+  AddressWithEmptyTransactionSigner,
+  AddressWithTransactionSigner,
+  DelegatedLsigSigner,
+  TransactionSigner,
+} from './signer.js';
+import { Transaction } from './transaction.js';
+import { EncodedPQSig } from './types/transactions/encoded.js';
+import { concatArrays } from './utils/utils.js';
+
+export interface PQSigningKey {
+  pqScheme: Uint8Array;
+  pqPublicKey: Uint8Array;
+  pqSigner: (bytesToSign: Uint8Array) => Promise<Uint8Array>;
+}
+
+export function addressWithSignersFromRawPQSigner(
+  signingKey: PQSigningKey,
+  sendingAddress?: Address
+): AddressWithTransactionSigner &
+  AddressWithDelegatedLsigSigner &
+  AddressWithEmptyTransactionSigner {
+  const { pqPublicKey, pqSigner: rawSigner, pqScheme } = signingKey;
+  const { address: authAddress, salt } = addressFromPQKey(
+    pqScheme,
+    pqPublicKey
+  );
+
+  const txnSigner: TransactionSigner = async (
+    txnGroup: Transaction[],
+    indexesToSign: number[]
+  ) => {
+    const stxns: SignedTransaction[] = [];
+    for (const index of indexesToSign) {
+      const txn = txnGroup[index];
+      // eslint-disable-next-line no-await-in-loop
+      const sig = await rawSigner(txn.bytesToSign());
+      const pqsig: EncodedPQSig = {
+        sch: pqScheme,
+        slt: salt,
+        pk: pqPublicKey,
+        sig,
+      };
+      const stxn = new SignedTransaction({
+        txn,
+        pqsig,
+        sgnr: txn.sender.equals(authAddress) ? undefined : authAddress,
+      });
+
+      stxns.push(stxn);
+    }
+
+    return stxns.map((stxn) => encodeMsgpack(stxn));
+  };
+
+  // A TransactionSigner that attaches a placeholder PQ envelope rather than a
+  // real signature. The scheme, salt, and public key are populated but the
+  // signature bytes are left empty. When simulated with `allowEmptySignatures`,
+  // algod derives the authorizer from this envelope and charges the post-quantum
+  // fee surcharge, so the reported fee usage matches a genuinely signed group -
+  // all without paying the cost of producing a (large, slow) Falcon signature.
+  const emptyTxnSigner: TransactionSigner = (
+    txnGroup: Transaction[],
+    indexesToSign: number[]
+  ) => {
+    const stxns: Uint8Array[] = [];
+    for (const index of indexesToSign) {
+      const txn = txnGroup[index];
+      const pqsig: EncodedPQSig = {
+        sch: pqScheme,
+        slt: salt,
+        pk: pqPublicKey,
+        sig: new Uint8Array(),
+      };
+      const stxn = new SignedTransaction({
+        txn,
+        pqsig,
+        sgnr: txn.sender.equals(authAddress) ? undefined : authAddress,
+      });
+      stxns.push(encodeMsgpack(stxn));
+    }
+    return Promise.resolve(stxns);
+  };
+
+  const delegatedLsigSigner: DelegatedLsigSigner = async (
+    lsig: LogicSig,
+    msig?: MultisigMetadata
+  ) => {
+    if (msig) {
+      throw Error(
+        `post-quantum scheme ${new TextDecoder().decode(pqScheme)} does not support multisig signing`
+      );
+    }
+
+    const toBeSigned = new Uint8Array(
+      concatArrays(PQ_PROGRAM_TAG, authAddress.publicKey, lsig.logic)
+    );
+
+    const sig = await rawSigner(toBeSigned);
+
+    const pqsig: EncodedPQSig = {
+      sch: pqScheme,
+      slt: salt,
+      pk: pqPublicKey,
+      sig,
+    };
+
+    return { address: authAddress, pqsig };
+  };
+
+  return {
+    address: sendingAddress ?? authAddress,
+    txnSigner,
+    emptyTxnSigner,
+    delegatedLsigSigner,
+  };
+}

package/src/signedTransaction.ts

@@ -11,6 +11,10 @@ import {
   encodedMultiSigToEncodingData,
   encodedMultiSigFromEncodingData,
   ENCODED_MULTISIG_SCHEMA,
+  EncodedPQSig,
+  encodedPQSigToEncodingData,
+  encodedPQSigFromEncodingData,
+  ENCODED_PQSIG_SCHEMA,
 } from './types/transactions/index.js';
 import {
   AddressSchema,
@@ -39,6 +43,10 @@ export class SignedTransaction implements Encodable {
         key: 'lsig',
         valueSchema: new OptionalSchema(LogicSig.encodingSchema),
       },
+      {
+        key: 'pqsig',
+        valueSchema: new OptionalSchema(ENCODED_PQSIG_SCHEMA),
+      },
       {
         key: 'sgnr',
         valueSchema: new OptionalSchema(new AddressSchema()),
@@ -66,6 +74,11 @@ export class SignedTransaction implements Encodable {
    */
   public readonly lsig?: LogicSig;
 
+  /**
+   * Post-quantum signature
+   */
+  public readonly pqsig?: EncodedPQSig;
+
   /**
    * The signer, if signing with a different key than the Transaction type `sender` property indicates
    */
@@ -76,24 +89,28 @@ export class SignedTransaction implements Encodable {
     sig,
     msig,
     lsig,
+    pqsig,
     sgnr,
   }: {
     txn: Transaction;
     sig?: Uint8Array;
     msig?: EncodedMultisig;
     lsig?: LogicSig;
+    pqsig?: EncodedPQSig;
     sgnr?: Address;
   }) {
     this.txn = txn;
     this.sig = sig;
     this.msig = msig;
     this.lsig = lsig;
+    this.pqsig = pqsig;
     this.sgnr = sgnr;
 
     let numberOfSigs = 0;
     if (sig) numberOfSigs += 1;
     if (msig) numberOfSigs += 1;
     if (lsig) numberOfSigs += 1;
+    if (pqsig) numberOfSigs += 1;
     if (numberOfSigs > 1) {
       throw new Error(
         `SignedTransaction must not have more than 1 signature. Got ${numberOfSigs}`
@@ -115,6 +132,10 @@ export class SignedTransaction implements Encodable {
         this.msig ? encodedMultiSigToEncodingData(this.msig) : undefined,
       ],
       ['lsig', this.lsig ? this.lsig.toEncodingData() : undefined],
+      [
+        'pqsig',
+        this.pqsig ? encodedPQSigToEncodingData(this.pqsig) : undefined,
+      ],
       ['sgnr', this.sgnr],
     ]);
   }
@@ -132,6 +153,9 @@ export class SignedTransaction implements Encodable {
       lsig: data.get('lsig')
         ? LogicSig.fromEncodingData(data.get('lsig'))
         : undefined,
+      pqsig: data.get('pqsig')
+        ? encodedPQSigFromEncodingData(data.get('pqsig'))
+        : undefined,
       sgnr: data.get('sgnr'),
     });
   }

package/src/signer.ts

@@ -8,6 +8,20 @@ import {
   signMultisigTransaction,
   mergeMultisigTransactions,
 } from './multisigSigning.js';
+import type { Address } from './encoding/address.js';
+import type {
+  EncodedMultisig,
+  EncodedPQSig,
+} from './types/transactions/encoded.js';
+import type { LogicSig } from './logicsig.js';
+
+/**
+ * Something that has an Algorand address associated with it.
+ * It could be logic sig, single-signer account, multisig, app, etc.
+ */
+export interface Addressable {
+  address: Address;
+}
 
 /**
  * This type represents a function which can sign transactions from an atomic transaction group.
@@ -22,6 +36,54 @@ export type TransactionSigner = (
   indexesToSign: number[]
 ) => Promise<Uint8Array[]>;
 
+export interface AddressWithTransactionSigner extends Addressable {
+  txnSigner: TransactionSigner;
+}
+
+export interface AddressWithEmptyTransactionSigner extends Addressable {
+  /**
+   * A TransactionSigner that produces unsigned (or placeholder-signed)
+   * transactions. This must only be used to simulate transactions with the
+   * `allowEmptySignatures` option enabled.
+   */
+  emptyTxnSigner: TransactionSigner;
+}
+
+/** Function for signing logic signatures for delegation
+ *  @param lsig - The logic signature that is being signed for delegation
+ *  @param msig - Optional multisig account that should be set when a public key is signing as a subsigner of a multisig
+ *  @returns The address of the delegator
+ * */
+export type DelegatedLsigSigner = (
+  lsig: LogicSig,
+  msig?: MultisigMetadata
+) => Promise<
+  { address: Address } & (
+    | { sig: Uint8Array }
+    | { lmsig: EncodedMultisig }
+    | { pqsig: EncodedPQSig }
+  )
+>;
+
+export interface AddressWithDelegatedLsigSigner extends Addressable {
+  delegatedLsigSigner: DelegatedLsigSigner;
+}
+
+export type MxBytesSigner = (bytesToSign: Uint8Array) => Promise<Uint8Array>;
+
+export interface AddressWithMxBytesSigner extends Addressable {
+  mxBytesSigner: MxBytesSigner;
+}
+
+export type ProgramDataSigner = (
+  data: Uint8Array,
+  lsig: LogicSig
+) => Promise<Uint8Array>;
+
+export interface AddressWithProgramDataSigner extends Addressable {
+  programDataSigner: ProgramDataSigner;
+}
+
 /**
  * Create a TransactionSigner that can sign transactions for the provided basic Account.
  */

package/src/signing.ts

@@ -1,17 +1,112 @@
 import * as nacl from './nacl/naclWrappers.js';
-import { Address } from './encoding/address.js';
+import { Address, addressFromPQSig } from './encoding/address.js';
 import * as encoding from './encoding/encoding.js';
+import * as utils from './utils/utils.js';
 import { SignedTransaction } from './signedTransaction.js';
 import { Transaction } from './transaction.js';
-import { LogicSig, LogicSigAccount } from './logicsig.js';
+import { LogicSig, LogicSigAccount, sanityCheckProgram } from './logicsig.js';
 import { addressFromMultisigPreImg } from './multisig.js';
+import type { TransactionSigner } from './signer.js';
+
+export const SIGN_BYTES_PREFIX = Uint8Array.from([77, 88]); // "MX"
+
+/**
+ * @deprecated Use signTransactionWithSigner
+ *
+ * signTransaction takes an object with either payment or key registration fields and
+ * a secret key and returns a signed blob.
+ *
+ * Payment transaction fields: from, to, amount, fee, firstValid, lastValid, genesisHash,
+ * note(optional), GenesisID(optional), closeRemainderTo(optional)
+ *
+ * Key registration fields: fee, firstValid, lastValid, voteKey, selectionKey, voteFirst,
+ * voteLast, voteKeyDilution, genesisHash, note(optional), GenesisID(optional)
+ *
+ * If flatFee is not set and the final calculated fee is lower than the protocol minimum fee, the fee will be increased to match the minimum.
+ * @param txn - object with either payment or key registration fields
+ * @param sk - Algorand Secret Key
+ * @returns object contains the binary signed transaction and its txID
+ */
+export function signTransaction(txn: Transaction, sk: Uint8Array) {
+  return {
+    txID: txn.txID(),
+    blob: txn.signTxn(sk),
+  };
+}
+
+export async function signTransactionWithSigner(
+  txn: Transaction,
+  signer: TransactionSigner
+): Promise<ReturnType<typeof signTransaction> & { stxn: SignedTransaction }> {
+  const [blob] = await signer([txn], [0]);
+
+  return {
+    blob,
+    txID: txn.txID(),
+    stxn: encoding.decodeMsgpack(blob, SignedTransaction),
+  };
+}
+
+/**
+ * signBytes takes arbitrary bytes and a secret key, prepends the bytes with "MX" for domain separation, signs the bytes
+ * with the private key, and returns the signature.
+ * @param bytes - Uint8array
+ * @param sk - Algorand secret key
+ * @returns binary signature
+ */
+export function signBytes(bytes: Uint8Array, sk: Uint8Array) {
+  const toBeSigned = utils.concatArrays(SIGN_BYTES_PREFIX, bytes);
+  const sig = nacl.sign(toBeSigned, sk);
+  return sig;
+}
+
+/**
+ * verifyBytes takes array of bytes, an address, and a signature and verifies if the signature is correct for the public
+ * key and the bytes (the bytes should have been signed with "MX" prepended for domain separation).
+ * @param bytes - Uint8Array
+ * @param signature - binary signature
+ * @param addr - string address
+ * @returns bool
+ */
+export function verifyBytes(
+  bytes: Uint8Array,
+  signature: Uint8Array,
+  addr: string | Address
+) {
+  const toBeVerified = utils.concatArrays(SIGN_BYTES_PREFIX, bytes);
+  const addrObj = typeof addr === 'string' ? Address.fromString(addr) : addr;
+  return nacl.verify(toBeVerified, signature, addrObj.publicKey);
+}
 
 function signLogicSigTransactionWithAddress(
   txn: Transaction,
   lsig: LogicSig,
   lsigAddress: Address
 ) {
-  if (!lsig.verify(lsigAddress.publicKey)) {
+  // `lsig.verify` enforces this for the non-PQ paths, but the PQ path below
+  // skips it, so check it up front for every path.
+  const sigCount = [lsig.sig, lsig.msig, lsig.lmsig, lsig.pqsig].filter(
+    Boolean
+  ).length;
+  if (sigCount > 1) {
+    throw new Error(
+      'LogicSig has too many signatures. At most one of sig, msig, lmsig, or pqsig may be present'
+    );
+  }
+
+  if (lsig.pqsig) {
+    // This SDK cannot validate the post-quantum signature itself, so it checks
+    // what it can and leaves the signature to the network: the program must be
+    // well-formed, and the signature's scheme, salt and public key must derive
+    // the delegating address.
+    try {
+      sanityCheckProgram(lsig.logic);
+    } catch (e) {
+      throw new Error(
+        `Logic signature verification failed. Ensure the program is valid: ${(e as Error).message}`
+      );
+    }
+  } else if (!lsig.verify(lsigAddress.publicKey)) {
     throw new Error(
       'Logic signature verification failed. Ensure the program and signature are valid.'
     );
@@ -56,11 +151,17 @@ export function signLogicSigTransactionObject(
   } 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.
+    if (lsig.pqsig) {
+      // A PQ signature carries the scheme, salt and public key of the
+      // delegating account, so its address is derivable. This is what lets a
+      // bare PQ-delegated LogicSig authorize a transaction whose sender was
+      // rekeyed to the delegating account.
+      lsigAddress = addressFromPQSig(lsig.pqsig);
+    } else if (lsig.sig) {
+      // For an ed25519 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.lmsig) {
       const msigMetadata = {

package/src/transaction.ts

@@ -247,6 +247,12 @@ function ensureResourceReference(input: unknown): TransactionResourceReference {
     if (box !== undefined) {
       return { box: ensureBoxReference(box) };
     }
+
+    // An empty resource reference is meaningful: it asks for a box I/O quota
+    // bump without naming a resource.
+    if (utils.isEmptyObject(input)) {
+      return {};
+    }
   }
   throw new Error(`Not a resource reference: ${input}`);
 }
@@ -329,6 +335,7 @@ export interface HeartbeatTransactionFields {
   readonly seed: Uint8Array;
   readonly voteID: Uint8Array;
   readonly keyDilution: bigint;
+  readonly challengeDiscount: boolean;
 }
 
 /**
@@ -876,6 +883,7 @@ export class Transaction implements encoding.Encodable {
         seed: params.heartbeatParams.seed,
         voteID: params.heartbeatParams.voteID,
         keyDilution: params.heartbeatParams.keyDilution,
+        challengeDiscount: params.heartbeatParams.challengeDiscount,
       });
     }
 
@@ -1035,6 +1043,7 @@ export class Transaction implements encoding.Encodable {
         seed: this.heartbeat.seed,
         voteID: this.heartbeat.voteID,
         keyDilution: this.heartbeat.keyDilution,
+        challengeDiscount: this.heartbeat.challengeDiscount,
       });
       data.set('hb', heartbeat.toEncodingData());
       return data;
@@ -1219,6 +1228,7 @@ export class Transaction implements encoding.Encodable {
         seed: heartbeat.seed,
         voteID: heartbeat.voteID,
         keyDilution: heartbeat.keyDilution,
+        challengeDiscount: heartbeat.challengeDiscount,
       };
       params.heartbeatParams = heartbeatParams;
     } else {
@@ -1252,13 +1262,21 @@ export class Transaction implements encoding.Encodable {
     return encoding.encodeMsgpack(this);
   }
 
-  // returns the raw signature
+  /**
+   * @deprecated Use `(await signTransactionWithSigner(txn, signer)).stxn.sig` instead
+   *
+   * returns the raw signature
+   *
+   */
   rawSignTxn(sk: Uint8Array): Uint8Array {
     const toBeSigned = this.bytesToSign();
     const sig = nacl.sign(toBeSigned, sk);
     return sig;
   }
 
+  /**
+   * @deprecated Use `await signTransactionWithSigner(txn, signer)`
+   */
   signTxn(sk: Uint8Array): Uint8Array {
     // TODO: deprecate in favor of SignedTransaction class
     const keypair = nacl.keyPairFromSecretKey(sk);