algosdk 3.7.0-beta.1 → 3.8.0

package/src/encoding/address.ts

@@ -204,9 +204,16 @@ export function getApplicationAddress(appID: number | bigint): Address {
  * Derive a post-quantum (PQ) account address together with the canonical salt
  * used to derive it.
  *
+ * @remarks
+ * The salt is found by rejection sampling: it is the lowest value whose
+ * preimage hashes to something that could not also be an Ed25519 public key, so
+ * that a PQ account can never collide with an Ed25519 one.
+ *
  * @param schemeBytes - The 2-byte ASCII PQ scheme identifier (e.g. "f1" for Falcon-1024).
  * @param key - The scheme's canonical public key.
  * @returns The derived Address and the canonical 1-byte salt.
+ * @throws If `schemeBytes` is not exactly {@link PQ_SCHEME_SIZE} bytes, or in
+ *   the ~2^-256 case where no salt in range yields a valid address.
  */
 export function addressFromPQKey(
   schemeBytes: Uint8Array,
@@ -248,6 +255,8 @@ export function addressFromPQKey(
  *
  * @param pqsig - The post-quantum signature to derive the address from.
  * @returns The address of the account the signature authorizes.
+ * @throws If the signature's scheme is malformed, or if its salt is not the
+ *   canonical one for its scheme and public key.
  */
 export function addressFromPQSig(pqsig: EncodedPQSig): Address {
   const { address, salt } = addressFromPQKey(pqsig.sch, pqsig.pk);

package/src/falcon-signer.ts

@@ -1,6 +1,7 @@
 import { Address } from './encoding/address.js';
 import {
   AddressWithDelegatedLsigSigner,
+  AddressWithEmptyTransactionSigner,
   AddressWithTransactionSigner,
 } from './signer.js';
 import { addressWithSignersFromRawPQSigner } from './pq-signer.js';
@@ -10,15 +11,44 @@ import { addressWithSignersFromRawPQSigner } from './pq-signer.js';
  */
 export const FALCON_1024_SCHEME = new TextEncoder().encode('f1');
 
+/**
+ * A Falcon-1024 public key paired with a function that signs raw bytes with the
+ * corresponding secret key.
+ *
+ * @remarks
+ * `falcon1024Signer` receives the exact bytes to sign, with every
+ * domain-separation prefix already applied, so it can be backed by a key that
+ * never leaves a wallet, HSM or hardware device.
+ */
 export interface Falcon1024SigningKey {
+  /** The Falcon-1024 public key. */
   falcon1024PublicKey: Uint8Array;
+  /** Signs the given bytes verbatim with the corresponding secret key. */
   falcon1024Signer: (bytesToSign: Uint8Array) => Promise<Uint8Array>;
 }
 
+/**
+ * Build the full set of signers for a Falcon-1024 key from a function that
+ * signs raw bytes with it.
+ *
+ * @remarks
+ * A thin wrapper around {@link addressWithSignersFromRawPQSigner} that supplies
+ * the {@link FALCON_1024_SCHEME} identifier, so see that function for the
+ * details and limitations of post-quantum signing.
+ *
+ * @param falconSigningKey - The public key and raw signing function to build the signers from
+ * @param sendingAddress - The address transactions are sent from. Defaults to
+ *   the derived Falcon-1024 address; supply it when this key is the auth
+ *   address of a rekeyed account.
+ * @returns An address bundled with transaction, empty transaction and delegated
+ *   LogicSig signers
+ */
 export function addressWithSignersFromRawFalcon1024Signer(
   falconSigningKey: Falcon1024SigningKey,
   sendingAddress?: Address
-): AddressWithTransactionSigner & AddressWithDelegatedLsigSigner {
+): AddressWithTransactionSigner &
+  AddressWithDelegatedLsigSigner &
+  AddressWithEmptyTransactionSigner {
   return addressWithSignersFromRawPQSigner(
     {
       pqScheme: FALCON_1024_SCHEME,

package/src/heartbeat.ts

@@ -2,6 +2,7 @@ import { Address } from './encoding/address.js';
 import { Encodable, Schema } from './encoding/encoding.js';
 import {
   AddressSchema,
+  BooleanSchema,
   Uint64Schema,
   ByteArraySchema,
   FixedLengthByteArraySchema,
@@ -111,6 +112,10 @@ export class Heartbeat implements Encodable {
         key: 'kd', // HbKeyDilution
         valueSchema: new Uint64Schema(),
       },
+      {
+        key: 'c', // HbChallengeDiscount
+        valueSchema: new BooleanSchema(),
+      },
     ])
   );
 
@@ -124,18 +129,22 @@ export class Heartbeat implements Encodable {
 
   public keyDilution: bigint;
 
+  public challengeDiscount: boolean;
+
   public constructor(params: {
     address: Address;
     proof: HeartbeatProof;
     seed: Uint8Array;
     voteID: Uint8Array;
     keyDilution: bigint;
+    challengeDiscount?: boolean;
   }) {
     this.address = params.address;
     this.proof = params.proof;
     this.seed = params.seed;
     this.voteID = params.voteID;
     this.keyDilution = params.keyDilution;
+    this.challengeDiscount = params.challengeDiscount ?? false;
   }
 
   // eslint-disable-next-line class-methods-use-this
@@ -150,6 +159,7 @@ export class Heartbeat implements Encodable {
       ['sd', this.seed],
       ['vid', this.voteID],
       ['kd', this.keyDilution],
+      ['c', this.challengeDiscount],
     ]);
   }
 
@@ -163,6 +173,7 @@ export class Heartbeat implements Encodable {
       seed: data.get('sd'),
       voteID: data.get('vid'),
       keyDilution: data.get('kd'),
+      challengeDiscount: data.get('c'),
     });
   }
 }

package/src/logicsig.ts

@@ -68,8 +68,22 @@ export function sanityCheckProgram(program: Uint8Array) {
   }
 }
 
+/**
+ * The domain-separation prefix prepended to a program before it is hashed into
+ * an escrow address, or signed for delegation by a single ed25519 account.
+ */
 export const PROGRAM_TAG = new TextEncoder().encode('Program');
+
+/**
+ * The domain-separation prefix prepended to a post-quantum delegating account's
+ * address and a program before the program is signed for delegation.
+ */
 export const PQ_PROGRAM_TAG = new TextEncoder().encode('PQProgram');
+
+/**
+ * The domain-separation prefix prepended to a delegating multisig account's
+ * address and a program before the program is signed for delegation.
+ */
 export const MSIG_PROGRAM_TAG = new TextEncoder().encode('MsigProgram');
 
 /**
@@ -112,6 +126,11 @@ export class LogicSig implements encoding.Encodable {
   sig?: Uint8Array;
   msig?: EncodedMultisig;
   lmsig?: EncodedMultisig;
+  /**
+   * The post-quantum delegation signature, if the delegating account is a
+   * post-quantum account. At most one of `sig`, `msig`, `lmsig` and `pqsig` may
+   * be set.
+   */
   pqsig?: EncodedPQSig;
 
   constructor(program: Uint8Array, programArgs?: Array<Uint8Array> | null) {
@@ -276,6 +295,11 @@ export class LogicSig implements encoding.Encodable {
   /**
    * Signs this LogicSig for delegation using the given signer.
    *
+   * @remarks
+   * Re-signing an already-signed LogicSig is allowed, and replaces the previous
+   * delegation signature. At most one of `sig`, `msig`, `lmsig` and `pqsig` may
+   * be set, so any signature left over from an earlier call is cleared.
+   *
    * @param signer - The signer to delegate to
    * @param msig - Optional multisig account the signer is a subsigner of
    * @returns The address the signer signed as. When `msig` is omitted this is
@@ -283,10 +307,9 @@ export class LogicSig implements encoding.Encodable {
    *   subsigner, not the multisig, so the delegating account is
    *   `multisigAddress(msig)`. Either way it is an authorizing address, which
    *   is not necessarily the address a signer sends transactions from.
-   *
-   * Re-signing an already-signed LogicSig is allowed, and replaces the previous
-   * delegation signature. At most one of `sig`, `msig`, `lmsig` and `pqsig` may
-   * be set, so any signature left over from an earlier call is cleared.
+   * @throws If the signer returns a signature of the wrong kind for the
+   *   requested delegation, or an `lmsig` whose version, threshold or public
+   *   keys do not match `msig`
    */
   async signWithSigner(
     signer: DelegatedLsigSigner,
@@ -360,6 +383,24 @@ export class LogicSig implements encoding.Encodable {
     this.lmsig.subsig[index].s = sig;
   }
 
+  /**
+   * Appends an additional subsignature to this LogicSig's existing multisig
+   * delegation.
+   *
+   * @remarks
+   * The multisig preimage is taken from the `lmsig` already on this LogicSig,
+   * so {@link signWithSigner} must have been called with an `msig` argument
+   * first. The signer must hold a key belonging to that multisig.
+   *
+   * A signature already collected from another member is never silently
+   * replaced: if the signer returns a different signature for a subsig that is
+   * already filled in, this throws instead.
+   *
+   * @param signer - The signer to append a subsignature from
+   * @throws If there is no multisig on this LogicSig, if the signer returns no
+   *   signature, a signature for a key outside the multisig, or one that
+   *   conflicts with a signature already collected
+   */
   async appendToMultisigWithSigner(signer: DelegatedLsigSigner) {
     if (this.lmsig === undefined) {
       throw new Error('no multisig present');
@@ -475,8 +516,15 @@ export class LogicSig implements encoding.Encodable {
    * Signs arbitrary data for use with the `ed25519verify` opcode from within
    * this LogicSig's program.
    *
+   * @remarks
+   * This does not modify the LogicSig or delegate it; the LogicSig is only used
+   * for the address that domain-separates the signature. The program is
+   * responsible for verifying the returned signature against the signer's
+   * public key.
+   *
    * @param signer - The signer to sign the data with
    * @param data - The data to sign
+   * @returns A promise which resolves to the raw signature over the data
    */
   async signDataWithSigner(signer: ProgramDataSigner, data: Uint8Array) {
     return signer(data, this);
@@ -656,6 +704,22 @@ export class LogicSigAccount implements encoding.Encodable {
     this.lsig.sign(secretKey, msig);
   }
 
+  /**
+   * Turns this LogicSigAccount into a delegated LogicSig, signed by one member
+   * of a delegating multisig account.
+   *
+   * @remarks
+   * This produces a LogicSig with a single subsignature filled in. Unless the
+   * multisig's threshold is 1, call {@link LogicSigAccount.appendToMultisigWithSigner}
+   * with the remaining members' signers before the LogicSig can authorize
+   * transactions.
+   *
+   * If the delegating account is not a multisig, use
+   * {@link LogicSigAccount.signWithSigner} instead.
+   *
+   * @param msig - The multisig delegating to this LogicSig
+   * @param signer - The signer of one member of `msig`
+   */
   async signMultisigWithSigner(
     msig: MultisigMetadata,
     signer: DelegatedLsigSigner
@@ -676,6 +740,16 @@ export class LogicSigAccount implements encoding.Encodable {
     this.lsig.appendToMultisig(secretKey);
   }
 
+  /**
+   * Adds an additional signature from a member of the delegating multisig
+   * account.
+   *
+   * @remarks
+   * {@link LogicSigAccount.signMultisigWithSigner} must have been called first
+   * to establish the multisig this signature belongs to.
+   *
+   * @param signer - The signer of another member of the delegating multisig account
+   */
   async appendToMultisigWithSigner(signer: DelegatedLsigSigner) {
     await this.lsig.appendToMultisigWithSigner(signer);
   }
@@ -697,8 +771,17 @@ export class LogicSigAccount implements encoding.Encodable {
 
   /**
    * Turns this LogicSigAccount into a delegated LogicSig, signed by the given
-   * signer. If the delegating account is a multisig account, use
-   * `signMultisigWithSigner` instead.
+   * signer. This type of LogicSig has the authority to sign transactions on
+   * behalf of another account, called the delegating account.
+   *
+   * @remarks
+   * If the delegating account is a multisig account, use
+   * {@link LogicSigAccount.signMultisigWithSigner} instead.
+   *
+   * The delegating account is taken to be the address the signer reports having
+   * signed as, not any sending address the signer advertises: for a rekeyed
+   * account the latter is the address it sends transactions from, which is not
+   * the account authorizing this delegation.
    *
    * @param signer - The signer of the delegating account.
    */
@@ -720,6 +803,10 @@ export function logicSigFromByte(encoded: Uint8Array): LogicSig {
   return encoding.decodeMsgpack(encoded, LogicSig);
 }
 
+/**
+ * The domain-separation prefix prepended, along with the program's address, to
+ * data signed for verification by the `ed25519verify` opcode.
+ */
 export const SIGN_PROGRAM_DATA_PREFIX = new TextEncoder().encode('ProgData');
 
 /**

package/src/makeTxn.ts

@@ -539,7 +539,13 @@ export function makeApplicationCreateTxnFromObject({
 }
 
 /**
- * Make a transaction that changes an application's approval and clear programs
+ * Make a transaction that changes an application's approval and clear programs.
+ *
+ * The application's global state schema and extra program pages may also be changed during an
+ * update by providing numGlobalInts, numGlobalByteSlices, and/or extraPages. The local state schema
+ * cannot be changed after application creation. If the pages or global schema increases in size, the entire
+ * MBR for the application will move to the sender of the update and that account will become the `sizeSponsor`
+ * in the application's parameters. A decrease in schema or pages does not affect MBR or `sizeSponsor`.
  *
  * @param options - Application update transaction parameters
  */
@@ -557,6 +563,9 @@ export function makeApplicationUpdateTxnFromObject({
   access,
   approvalProgram,
   clearProgram,
+  numGlobalInts,
+  numGlobalByteSlices,
+  extraPages,
   note,
   lease,
   rekeyTo,
@@ -566,9 +575,6 @@ export function makeApplicationUpdateTxnFromObject({
   | 'onComplete'
   | 'numLocalInts'
   | 'numLocalByteSlices'
-  | 'numGlobalInts'
-  | 'numGlobalByteSlices'
-  | 'extraPages'
   | 'approvalProgram'
   | 'clearProgram'
 > &
@@ -598,6 +604,9 @@ export function makeApplicationUpdateTxnFromObject({
     access,
     approvalProgram,
     clearProgram,
+    numGlobalInts,
+    numGlobalByteSlices,
+    extraPages,
     note,
     lease,
     rekeyTo,

package/src/mnemonic/mnemonic.ts

@@ -198,6 +198,8 @@ const PQ_KEY_PREFIX = new TextEncoder().encode('PQK');
  * @param mn - A 25-word Algorand mnemonic
  * @param scheme - The 2-byte ASCII PQ scheme identifier (e.g. "f1" for Falcon-1024)
  * @returns The 32-byte seed to hand to the scheme's key generator
+ * @throws If `mn` is not a valid 25-word mnemonic, or if `scheme` is not
+ *   exactly {@link PQ_SCHEME_SIZE} bytes
  */
 export function pq25WordMnemonicToSeed(
   mn: string,

package/src/pq-signer.ts

@@ -5,6 +5,7 @@ import { MultisigMetadata } from './multisig.js';
 import { SignedTransaction } from './signedTransaction.js';
 import {
   AddressWithDelegatedLsigSigner,
+  AddressWithEmptyTransactionSigner,
   AddressWithTransactionSigner,
   DelegatedLsigSigner,
   TransactionSigner,
@@ -13,16 +14,55 @@ import { Transaction } from './transaction.js';
 import { EncodedPQSig } from './types/transactions/encoded.js';
 import { concatArrays } from './utils/utils.js';
 
+/**
+ * A post-quantum public key, its scheme identifier, and a function that signs
+ * raw bytes with the corresponding secret key.
+ *
+ * @remarks
+ * `pqSigner` receives the exact bytes to sign, with every domain-separation
+ * prefix already applied, so it can be backed by a key that never leaves a
+ * wallet, HSM or hardware device.
+ */
 export interface PQSigningKey {
+  /** The 2-byte ASCII PQ scheme identifier (e.g. "f1" for Falcon-1024). */
   pqScheme: Uint8Array;
+  /** The scheme's canonical public key. */
   pqPublicKey: Uint8Array;
+  /** Signs the given bytes verbatim with the corresponding secret key. */
   pqSigner: (bytesToSign: Uint8Array) => Promise<Uint8Array>;
 }
 
+/**
+ * Build the full set of signers for a post-quantum key from a function that
+ * signs raw bytes with it.
+ *
+ * @remarks
+ * The account address is derived from the scheme and public key via
+ * {@link addressFromPQKey}, so it does not have to be supplied. Every signature
+ * produced carries the scheme, canonical salt and public key alongside the
+ * signature bytes, which is what lets the network recover the authorizing
+ * address from the signature alone.
+ *
+ * PQ schemes cannot participate in multisig, so `delegatedLsigSigner` throws if
+ * given an `msig` argument, and no `mxBytesSigner` or `programDataSigner` is
+ * returned — signing arbitrary bytes and program data are ed25519-only
+ * operations.
+ *
+ * @param signingKey - The scheme, public key and raw signing function to build the signers from
+ * @param sendingAddress - The address transactions are sent from. Defaults to
+ *   the derived PQ address; supply it when the PQ key is the auth address of a
+ *   rekeyed account, in which case the produced transactions carry the derived
+ *   address in their `sgnr` field.
+ * @returns An address bundled with transaction, empty transaction and delegated
+ *   LogicSig signers
+ * @throws If `pqScheme` is not exactly 2 bytes
+ */
 export function addressWithSignersFromRawPQSigner(
   signingKey: PQSigningKey,
   sendingAddress?: Address
-): AddressWithTransactionSigner & AddressWithDelegatedLsigSigner {
+): AddressWithTransactionSigner &
+  AddressWithDelegatedLsigSigner &
+  AddressWithEmptyTransactionSigner {
   const { pqPublicKey, pqSigner: rawSigner, pqScheme } = signingKey;
   const { address: authAddress, salt } = addressFromPQKey(
     pqScheme,
@@ -56,6 +96,35 @@ export function addressWithSignersFromRawPQSigner(
     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
@@ -85,6 +154,7 @@ export function addressWithSignersFromRawPQSigner(
   return {
     address: sendingAddress ?? authAddress,
     txnSigner,
+    emptyTxnSigner,
     delegatedLsigSigner,
   };
 }

package/src/signer.ts

@@ -36,15 +36,54 @@ export type TransactionSigner = (
   indexesToSign: number[]
 ) => Promise<Uint8Array[]>;
 
+/**
+ * An address paired with a signer able to sign transactions on its behalf.
+ *
+ * @remarks
+ * `address` is the address transactions are sent from, which is not necessarily
+ * the address that authorizes them: for a rekeyed account the two differ, and
+ * `txnSigner` sets the transaction's `sgnr` field accordingly.
+ */
 export interface AddressWithTransactionSigner extends Addressable {
   txnSigner: 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
- * */
+/**
+ * An address paired with a signer that produces placeholder signatures for it.
+ *
+ * @remarks
+ * Useful for post-quantum accounts, whose real signatures are large and slow to
+ * produce, when only a simulation of the group is needed.
+ */
+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;
+}
+
+/**
+ * This type represents a function which can sign a LogicSig for delegation.
+ *
+ * @remarks
+ * Exactly one of `sig`, `lmsig` and `pqsig` is returned, according to the kind
+ * of key the signer holds and whether `msig` was supplied:
+ *
+ * - `sig` - an ed25519 signature from a single delegating account
+ * - `lmsig` - a multisig containing this signer's subsignature, returned when
+ *   `msig` is supplied
+ * - `pqsig` - a post-quantum signature from a single delegating account
+ *
+ * @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 A promise which resolves to the signature and the address that
+ *   produced it. When `msig` is omitted this is the delegating account; when
+ *   `msig` is supplied it is the individual subsigner rather than the multisig.
+ *   Either way it is an authorizing address, which is not necessarily the
+ *   address the signer sends transactions from.
+ */
 export type DelegatedLsigSigner = (
   lsig: LogicSig,
   msig?: MultisigMetadata
@@ -56,21 +95,54 @@ export type DelegatedLsigSigner = (
   )
 >;
 
+/**
+ * An address paired with a signer able to delegate a LogicSig to it.
+ */
 export interface AddressWithDelegatedLsigSigner extends Addressable {
   delegatedLsigSigner: DelegatedLsigSigner;
 }
 
+/**
+ * This type represents a function which can sign arbitrary bytes, for use with
+ * {@link verifyBytes}.
+ *
+ * @remarks
+ * The implementation is responsible for prepending the "MX" domain-separation
+ * prefix ({@link SIGN_BYTES_PREFIX}) before signing, so `bytesToSign` is the
+ * caller's bytes alone.
+ *
+ * @param bytesToSign - The bytes to sign, without any domain-separation prefix
+ * @returns A promise which resolves to the raw signature
+ */
 export type MxBytesSigner = (bytesToSign: Uint8Array) => Promise<Uint8Array>;
 
+/**
+ * An address paired with a signer able to sign arbitrary bytes on its behalf.
+ */
 export interface AddressWithMxBytesSigner extends Addressable {
   mxBytesSigner: MxBytesSigner;
 }
 
+/**
+ * This type represents a function which can sign data for use with the
+ * `ed25519verify` opcode from within a LogicSig's program.
+ *
+ * @remarks
+ * The implementation is responsible for prepending the "ProgData" prefix
+ * ({@link SIGN_PROGRAM_DATA_PREFIX}) and the LogicSig's address before signing.
+ *
+ * @param data - The data to sign, without any prefix
+ * @param lsig - The LogicSig whose program will verify the signature
+ * @returns A promise which resolves to the raw signature
+ */
 export type ProgramDataSigner = (
   data: Uint8Array,
   lsig: LogicSig
 ) => Promise<Uint8Array>;
 
+/**
+ * An address paired with a signer able to sign program data on its behalf.
+ */
 export interface AddressWithProgramDataSigner extends Addressable {
   programDataSigner: ProgramDataSigner;
 }

package/src/signing.ts

@@ -8,6 +8,11 @@ import { LogicSig, LogicSigAccount, sanityCheckProgram } from './logicsig.js';
 import { addressFromMultisigPreImg } from './multisig.js';
 import type { TransactionSigner } from './signer.js';
 
+/**
+ * The domain-separation prefix prepended to arbitrary bytes before signing them
+ * with {@link signBytes}, so that such a signature can never be mistaken for a
+ * signature over a transaction or a program.
+ */
 export const SIGN_BYTES_PREFIX = Uint8Array.from([77, 88]); // "MX"
 
 /**
@@ -34,6 +39,23 @@ export function signTransaction(txn: Transaction, sk: Uint8Array) {
   };
 }
 
+/**
+ * signTransactionWithSigner signs a single transaction with the given signer.
+ *
+ * @remarks
+ * This is the replacement for the deprecated {@link signTransaction}, which can
+ * only sign with a raw ed25519 secret key. Because a `TransactionSigner` signs
+ * a group, the transaction is passed as a one-element group and the single
+ * result is returned.
+ *
+ * The decoded `stxn` is returned alongside the blob so callers can read what
+ * the signer produced — its `sig`, `pqsig` or `msig` field, and the `sgnr` field
+ * naming the key that signed when it is not the transaction sender.
+ *
+ * @param txn - the transaction to sign
+ * @param signer - the signer to sign with
+ * @returns an object with blob, txID and stxn properties
+ */
 export async function signTransactionWithSigner(
   txn: Transaction,
   signer: TransactionSigner

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 {