algosdk 3.7.0-beta.1 → 3.8.0

package/dist/types/client/v2/indexer/models/types.d.ts

@@ -154,6 +154,7 @@ export declare class Account implements Encodable {
      * * sig
      * * msig
      * * lsig
+     * * pqsig
      * * or null if unknown
      */
     sigType?: string;
@@ -213,6 +214,7 @@ export declare class Account implements Encodable {
      * * sig
      * * msig
      * * lsig
+     * * pqsig
      * * or null if unknown
      */
     constructor({ address, amount, amountWithoutPendingRewards, minBalance, pendingRewards, rewards, round, status, totalAppsOptedIn, totalAssetsOptedIn, totalBoxBytes, totalBoxes, totalCreatedApps, totalCreatedAssets, appsLocalState, appsTotalExtraPages, appsTotalSchema, assets, authAddr, closedAtRound, createdApps, createdAssets, createdAtRound, deleted, incentiveEligible, lastHeartbeat, lastProposed, participation, rewardBase, sigType, }: {
@@ -1145,10 +1147,21 @@ export declare class Block implements Encodable {
      * the potential bonus payout for this block.
      */
     bonus?: number;
+    /**
+     * the fee required, beyond the minimum fee, for "normal" transactions in this
+     * block.
+     */
+    congestionTax?: number;
     /**
      * the sum of all fees paid by transactions in this block.
      */
     feesCollected?: number;
+    /**
+     * the degree to which this block is full, based on the number of bytes in the
+     * final block compared to the maximum allowed. Expressed as a fixed-point integer
+     * with 6 digits of precision, so 1,000,000 is a completely full block.
+     */
+    load?: number;
     /**
      * Participation account data that needs to be checked/acted on by the network.
      */
@@ -1218,7 +1231,12 @@ export declare class Block implements Encodable {
      * the default SHA512_256. This commitment can be used on environments where only
      * the SHA256 function exists.
      * @param bonus - the potential bonus payout for this block.
+     * @param congestionTax - the fee required, beyond the minimum fee, for "normal" transactions in this
+     * block.
      * @param feesCollected - the sum of all fees paid by transactions in this block.
+     * @param load - the degree to which this block is full, based on the number of bytes in the
+     * final block compared to the maximum allowed. Expressed as a fixed-point integer
+     * with 6 digits of precision, so 1,000,000 is a completely full block.
      * @param participationUpdates - Participation account data that needs to be checked/acted on by the network.
      * @param previousBlockHash512 - (prev512) Previous block hash, using SHA-512.
      * @param proposer - the proposer of this block.
@@ -1237,7 +1255,7 @@ export declare class Block implements Encodable {
      * @param upgradeState - Fields relating to a protocol upgrade.
      * @param upgradeVote - Fields relating to voting for a protocol upgrade.
      */
-    constructor({ genesisHash, genesisId, previousBlockHash, round, seed, timestamp, transactionsRoot, transactionsRootSha256, bonus, feesCollected, participationUpdates, previousBlockHash512, proposer, proposerPayout, rewards, stateProofTracking, transactions, transactionsRootSha512, txnCounter, upgradeState, upgradeVote, }: {
+    constructor({ genesisHash, genesisId, previousBlockHash, round, seed, timestamp, transactionsRoot, transactionsRootSha256, bonus, congestionTax, feesCollected, load, participationUpdates, previousBlockHash512, proposer, proposerPayout, rewards, stateProofTracking, transactions, transactionsRootSha512, txnCounter, upgradeState, upgradeVote, }: {
         genesisHash: string | Uint8Array;
         genesisId: string;
         previousBlockHash: string | Uint8Array;
@@ -1247,7 +1265,9 @@ export declare class Block implements Encodable {
         transactionsRoot: string | Uint8Array;
         transactionsRootSha256: string | Uint8Array;
         bonus?: number | bigint;
+        congestionTax?: number | bigint;
         feesCollected?: number | bigint;
+        load?: number | bigint;
         participationUpdates?: ParticipationUpdates;
         previousBlockHash512?: string | Uint8Array;
         proposer?: Address | string;
@@ -1471,7 +1491,7 @@ export declare class Box implements Encodable {
     static fromEncodingData(data: unknown): Box;
 }
 /**
- * Box descriptor describes an app box without a value.
+ * Box descriptor describes an app box.
  */
 export declare class BoxDescriptor implements Encodable {
     private static encodingSchemaValue;
@@ -1480,12 +1500,20 @@ export declare class BoxDescriptor implements Encodable {
      * Base64 encoded box name
      */
     name: Uint8Array;
+    /**
+     * Base64 encoded box value. Present only when the `values` query parameter is set
+     * to true.
+     */
+    value?: Uint8Array;
     /**
      * Creates a new `BoxDescriptor` object.
      * @param name - Base64 encoded box name
+     * @param value - Base64 encoded box value. Present only when the `values` query parameter is set
+     * to true.
      */
-    constructor({ name }: {
+    constructor({ name, value, }: {
         name: string | Uint8Array;
+        value?: string | Uint8Array;
     });
     getEncodingSchema(): Schema;
     toEncodingData(): Map<string, unknown>;
@@ -1536,17 +1564,23 @@ export declare class BoxesResponse implements Encodable {
      * next parameter.
      */
     nextToken?: string;
+    /**
+     * The round for which this information is relevant.
+     */
+    round?: number;
     /**
      * Creates a new `BoxesResponse` object.
      * @param applicationId - (appidx) application index.
      * @param boxes -
      * @param nextToken - Used for pagination, when making another request provide this token with the
      * next parameter.
+     * @param round - The round for which this information is relevant.
      */
-    constructor({ applicationId, boxes, nextToken, }: {
+    constructor({ applicationId, boxes, nextToken, round, }: {
         applicationId: number | bigint;
         boxes: BoxDescriptor[];
         nextToken?: string;
+        round?: number | bigint;
     });
     getEncodingSchema(): Schema;
     toEncodingData(): Map<string, unknown>;
@@ -2943,6 +2977,12 @@ export declare class TransactionHeartbeat implements Encodable {
      * (hbvid) HbVoteID must match the HbAddress account's current VoteID.
      */
     hbVoteId: Uint8Array;
+    /**
+     * (hbc) HbChallengeDiscount requests the challenge fee discount, reducing the
+     * required fee by one min fee. It is a request, not an assertion: it is granted
+     * only if HbAddress is actually under challenge.
+     */
+    hbChallengeDiscount?: boolean;
     /**
      * Creates a new `TransactionHeartbeat` object.
      * @param hbAddress - (hbad) HbAddress is the account this txn is proving onlineness for.
@@ -2952,13 +2992,17 @@ export declare class TransactionHeartbeat implements Encodable {
      * @param hbSeed - (hbsd) HbSeed must be the block seed for the this transaction's firstValid
      * block.
      * @param hbVoteId - (hbvid) HbVoteID must match the HbAddress account's current VoteID.
+     * @param hbChallengeDiscount - (hbc) HbChallengeDiscount requests the challenge fee discount, reducing the
+     * required fee by one min fee. It is a request, not an assertion: it is granted
+     * only if HbAddress is actually under challenge.
      */
-    constructor({ hbAddress, hbKeyDilution, hbProof, hbSeed, hbVoteId, }: {
+    constructor({ hbAddress, hbKeyDilution, hbProof, hbSeed, hbVoteId, hbChallengeDiscount, }: {
         hbAddress: string;
         hbKeyDilution: number | bigint;
         hbProof: HbProofFields;
         hbSeed: string | Uint8Array;
         hbVoteId: string | Uint8Array;
+        hbChallengeDiscount?: boolean;
     });
     getEncodingSchema(): Schema;
     toEncodingData(): Map<string, unknown>;
@@ -3124,6 +3168,12 @@ export declare class TransactionSignature implements Encodable {
      * crypto/multisig.go : MultisigSig
      */
     multisig?: TransactionSignatureMultisig;
+    /**
+     * structure holding a post-quantum signature.
+     * Definition:
+     * data/transactions/pqsig.go : PQSig
+     */
+    pqsig?: TransactionSignaturePQsig;
     /**
      * (sig) Standard ed25519 signature.
      */
@@ -3136,11 +3186,15 @@ export declare class TransactionSignature implements Encodable {
      * @param multisig - structure holding multiple subsignatures.
      * Definition:
      * crypto/multisig.go : MultisigSig
+     * @param pqsig - structure holding a post-quantum signature.
+     * Definition:
+     * data/transactions/pqsig.go : PQSig
      * @param sig - (sig) Standard ed25519 signature.
      */
-    constructor({ logicsig, multisig, sig, }: {
+    constructor({ logicsig, multisig, pqsig, sig, }: {
         logicsig?: TransactionSignatureLogicsig;
         multisig?: TransactionSignatureMultisig;
+        pqsig?: TransactionSignaturePQsig;
         sig?: string | Uint8Array;
     });
     getEncodingSchema(): Schema;
@@ -3176,6 +3230,12 @@ export declare class TransactionSignatureLogicsig implements Encodable {
      * crypto/multisig.go : MultisigSig
      */
     multisigSignature?: TransactionSignatureMultisig;
+    /**
+     * structure holding a post-quantum signature.
+     * Definition:
+     * data/transactions/pqsig.go : PQSig
+     */
+    pqsig?: TransactionSignaturePQsig;
     /**
      * (sig) ed25519 signature.
      */
@@ -3191,13 +3251,17 @@ export declare class TransactionSignatureLogicsig implements Encodable {
      * @param multisigSignature - structure holding multiple subsignatures.
      * Definition:
      * crypto/multisig.go : MultisigSig
+     * @param pqsig - structure holding a post-quantum signature.
+     * Definition:
+     * data/transactions/pqsig.go : PQSig
      * @param signature - (sig) ed25519 signature.
      */
-    constructor({ logic, args, logicMultisigSignature, multisigSignature, signature, }: {
+    constructor({ logic, args, logicMultisigSignature, multisigSignature, pqsig, signature, }: {
         logic: string | Uint8Array;
         args?: Uint8Array[];
         logicMultisigSignature?: TransactionSignatureMultisig;
         multisigSignature?: TransactionSignatureMultisig;
+        pqsig?: TransactionSignaturePQsig;
         signature?: string | Uint8Array;
     });
     getEncodingSchema(): Schema;
@@ -3263,6 +3327,49 @@ export declare class TransactionSignatureMultisigSubsignature implements Encodab
     toEncodingData(): Map<string, unknown>;
     static fromEncodingData(data: unknown): TransactionSignatureMultisigSubsignature;
 }
+/**
+ * structure holding a post-quantum signature.
+ * Definition:
+ * data/transactions/pqsig.go : PQSig
+ */
+export declare class TransactionSignaturePQsig implements Encodable {
+    private static encodingSchemaValue;
+    static get encodingSchema(): Schema;
+    /**
+     * (pk)
+     */
+    publicKey: Uint8Array;
+    /**
+     * (sch) identifies the internal signature scheme.
+     */
+    scheme: string;
+    /**
+     * (sig)
+     */
+    signature: Uint8Array;
+    /**
+     * (slt) a single byte, added to ensure the hashed address is not an Ed25519 curve
+     * point
+     */
+    salt?: number;
+    /**
+     * Creates a new `TransactionSignaturePQsig` object.
+     * @param publicKey - (pk)
+     * @param scheme - (sch) identifies the internal signature scheme.
+     * @param signature - (sig)
+     * @param salt - (slt) a single byte, added to ensure the hashed address is not an Ed25519 curve
+     * point
+     */
+    constructor({ publicKey, scheme, signature, salt, }: {
+        publicKey: string | Uint8Array;
+        scheme: string;
+        signature: string | Uint8Array;
+        salt?: number | bigint;
+    });
+    getEncodingSchema(): Schema;
+    toEncodingData(): Map<string, unknown>;
+    static fromEncodingData(data: unknown): TransactionSignaturePQsig;
+}
 /**
  * Fields for a state proof transaction.
  * Definition:

package/dist/types/composer.d.ts

@@ -93,15 +93,15 @@ export declare class AtomicTransactionComposer {
         approvalProgram?: Uint8Array;
         /** The clear program for this application call. Only set this if this is an application creation call, or if onComplete is OnApplicationComplete.UpdateApplicationOC */
         clearProgram?: Uint8Array;
-        /** The global integer schema size. Only set this if this is an application creation call. */
+        /** The global integer schema size. Only set this if this is an application creation call or an OnApplicationComplete.UpdateApplicationOC call. */
         numGlobalInts?: number;
-        /** The global byte slice schema size. Only set this if this is an application creation call. */
+        /** The global byte slice schema size. Only set this if this is an application creation call or an OnApplicationComplete.UpdateApplicationOC call. */
         numGlobalByteSlices?: number;
         /** The local integer schema size. Only set this if this is an application creation call. */
         numLocalInts?: number;
         /** The local byte slice schema size. Only set this if this is an application creation call. */
         numLocalByteSlices?: number;
-        /** The number of extra pages to allocate for the application's programs. Only set this if this is an application creation call. If omitted, defaults to 0. */
+        /** The number of extra pages to allocate for the application's programs. Only set this if this is an application creation call or an OnApplicationComplete.UpdateApplicationOC call. If omitted, defaults to 0. */
         extraPages?: number;
         /** Array of Address strings that represent external accounts supplied to this application. If accounts are provided here, the accounts specified in the method args will appear after these. */
         appAccounts?: Array<string | Address>;

package/dist/types/ed25519-signer.d.ts

@@ -1,7 +1,36 @@
 import { Address } from './encoding/address.js';
 import { AddressWithDelegatedLsigSigner, AddressWithMxBytesSigner, AddressWithProgramDataSigner, AddressWithTransactionSigner } from './signer.js';
+/**
+ * An ed25519 public key paired with a function that signs raw bytes with the
+ * corresponding secret key.
+ *
+ * @remarks
+ * `ed25519Signer` 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 Ed25519SigningKey {
+    /** The 32-byte ed25519 public key. */
     ed25519PublicKey: Uint8Array;
+    /** Signs the given bytes verbatim with the corresponding secret key. */
     ed25519Signer: (bytesToSign: Uint8Array) => Promise<Uint8Array>;
 }
+/**
+ * Build the full set of signers for an ed25519 key from a function that signs
+ * raw bytes with it.
+ *
+ * @remarks
+ * Each returned signer applies the domain separation its use requires
+ * ("Program", "MsigProgram", "ProgData", or the transaction prefix) before
+ * calling `ed25519Signer`, so a caller only has to supply the raw signing
+ * operation once.
+ *
+ * @param ed25519SigningKey - The public key and raw signing function to build the signers from
+ * @param sendingAddress - The address transactions are sent from. Defaults to
+ *   the address of `ed25519PublicKey`; supply it when that key is the auth
+ *   address of a rekeyed account, in which case the produced transactions carry
+ *   the key's address in their `sgnr` field.
+ * @returns An address bundled with transaction, delegated LogicSig, arbitrary
+ *   bytes and program data signers
+ */
 export declare function addressWithSignersFromRawEd25519Signer(ed25519SigningKey: Ed25519SigningKey, sendingAddress?: Address): AddressWithTransactionSigner & AddressWithDelegatedLsigSigner & AddressWithMxBytesSigner & AddressWithProgramDataSigner;

package/dist/types/encoding/address.d.ts

@@ -78,9 +78,16 @@ export declare 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 declare function addressFromPQKey(schemeBytes: Uint8Array, key: Uint8Array): {
     address: Address;
@@ -99,5 +106,7 @@ export declare function addressFromPQKey(schemeBytes: Uint8Array, key: Uint8Arra
  *
  * @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 declare function addressFromPQSig(pqsig: EncodedPQSig): Address;

package/dist/types/falcon-signer.d.ts

@@ -1,11 +1,38 @@
 import { Address } from './encoding/address.js';
-import { AddressWithDelegatedLsigSigner, AddressWithTransactionSigner } from './signer.js';
+import { AddressWithDelegatedLsigSigner, AddressWithEmptyTransactionSigner, AddressWithTransactionSigner } from './signer.js';
 /**
  * The 2-byte ASCII identifier of the Falcon-1024 post-quantum signature scheme.
  */
 export declare const FALCON_1024_SCHEME: Uint8Array;
+/**
+ * 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>;
 }
-export declare function addressWithSignersFromRawFalcon1024Signer(falconSigningKey: Falcon1024SigningKey, sendingAddress?: Address): AddressWithTransactionSigner & AddressWithDelegatedLsigSigner;
+/**
+ * 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 declare function addressWithSignersFromRawFalcon1024Signer(falconSigningKey: Falcon1024SigningKey, sendingAddress?: Address): AddressWithTransactionSigner & AddressWithDelegatedLsigSigner & AddressWithEmptyTransactionSigner;

package/dist/types/heartbeat.d.ts

@@ -26,12 +26,14 @@ export declare class Heartbeat implements Encodable {
     seed: Uint8Array;
     voteID: Uint8Array;
     keyDilution: bigint;
+    challengeDiscount: boolean;
     constructor(params: {
         address: Address;
         proof: HeartbeatProof;
         seed: Uint8Array;
         voteID: Uint8Array;
         keyDilution: bigint;
+        challengeDiscount?: boolean;
     });
     getEncodingSchema(): Schema;
     toEncodingData(): Map<string, unknown>;

package/dist/types/logicsig.d.ts

@@ -10,8 +10,20 @@ import type { DelegatedLsigSigner, ProgramDataSigner } from './signer.js';
  * @param program - Program bytes to check
  */
 export declare function sanityCheckProgram(program: Uint8Array): void;
+/**
+ * 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 declare const PROGRAM_TAG: Uint8Array;
+/**
+ * The domain-separation prefix prepended to a post-quantum delegating account's
+ * address and a program before the program is signed for delegation.
+ */
 export declare const PQ_PROGRAM_TAG: Uint8Array;
+/**
+ * The domain-separation prefix prepended to a delegating multisig account's
+ * address and a program before the program is signed for delegation.
+ */
 export declare const MSIG_PROGRAM_TAG: Uint8Array;
 /**
  LogicSig implementation
@@ -25,6 +37,11 @@ export declare 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);
     getEncodingSchema(): encoding.Schema;
@@ -54,6 +71,11 @@ export declare 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
@@ -61,10 +83,9 @@ export declare 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`
      */
     signWithSigner(signer: DelegatedLsigSigner, msig?: MultisigMetadata): Promise<Address>;
     /**
@@ -79,6 +100,24 @@ export declare class LogicSig implements encoding.Encodable {
      * @param secretKey - Secret key to sign with
      */
     appendToMultisig(secretKey: Uint8Array): void;
+    /**
+     * 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
+     */
     appendToMultisigWithSigner(signer: DelegatedLsigSigner): Promise<void>;
     /**
      * @deprecated Use `signWithSigner` followed by `.sig` instead
@@ -98,8 +137,15 @@ export declare 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
      */
     signDataWithSigner(signer: ProgramDataSigner, data: Uint8Array): Promise<Uint8Array>;
 }
@@ -172,6 +218,22 @@ export declare class LogicSigAccount implements encoding.Encodable {
      *   from other members.
      */
     signMultisig(msig: MultisigMetadata, secretKey: Uint8Array): void;
+    /**
+     * 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`
+     */
     signMultisigWithSigner(msig: MultisigMetadata, signer: DelegatedLsigSigner): Promise<void>;
     /**
      * @deprecated Use appendToMultisigWithSigner
@@ -183,6 +245,16 @@ export declare class LogicSigAccount implements encoding.Encodable {
      *   multisig account.
      */
     appendToMultisig(secretKey: Uint8Array): void;
+    /**
+     * 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
+     */
     appendToMultisigWithSigner(signer: DelegatedLsigSigner): Promise<void>;
     /**
      * @deprecated Use `signWithSigner` instead
@@ -197,8 +269,17 @@ export declare class LogicSigAccount implements encoding.Encodable {
     sign(secretKey: Uint8Array): void;
     /**
      * 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.
      */
@@ -209,6 +290,10 @@ export declare class LogicSigAccount implements encoding.Encodable {
  * returning the result
  */
 export declare function logicSigFromByte(encoded: Uint8Array): LogicSig;
+/**
+ * The domain-separation prefix prepended, along with the program's address, to
+ * data signed for verification by the `ed25519verify` opcode.
+ */
 export declare const SIGN_PROGRAM_DATA_PREFIX: Uint8Array;
 /**
  * tealSign creates a signature compatible with ed25519verify opcode from program hash

package/dist/types/makeTxn.d.ts

@@ -128,11 +128,17 @@ export declare function makeApplicationCallTxnFromObject({ sender, appIndex, onC
  */
 export declare function makeApplicationCreateTxnFromObject({ sender, onComplete, appArgs, accounts, foreignApps, foreignAssets, boxes, convertToAccess, holdings, locals, access, approvalProgram, clearProgram, numLocalInts, numLocalByteSlices, numGlobalInts, numGlobalByteSlices, extraPages, note, lease, rekeyTo, suggestedParams, }: Omit<ApplicationCallTransactionParams, 'appIndex' | 'approvalProgram' | 'clearProgram'> & Required<Pick<ApplicationCallTransactionParams, 'approvalProgram' | 'clearProgram'>> & CommonTransactionParams & ApplicationCallReferenceParams): Transaction;
 /**
- * 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
  */
-export declare function makeApplicationUpdateTxnFromObject({ sender, appIndex, appArgs, accounts, foreignApps, foreignAssets, boxes, convertToAccess, holdings, locals, access, approvalProgram, clearProgram, note, lease, rekeyTo, suggestedParams, }: Omit<ApplicationCallTransactionParams, 'onComplete' | 'numLocalInts' | 'numLocalByteSlices' | 'numGlobalInts' | 'numGlobalByteSlices' | 'extraPages' | 'approvalProgram' | 'clearProgram'> & Required<Pick<ApplicationCallTransactionParams, 'approvalProgram' | 'clearProgram'>> & CommonTransactionParams & ApplicationCallReferenceParams): Transaction;
+export declare function makeApplicationUpdateTxnFromObject({ sender, appIndex, appArgs, accounts, foreignApps, foreignAssets, boxes, convertToAccess, holdings, locals, access, approvalProgram, clearProgram, numGlobalInts, numGlobalByteSlices, extraPages, note, lease, rekeyTo, suggestedParams, }: Omit<ApplicationCallTransactionParams, 'onComplete' | 'numLocalInts' | 'numLocalByteSlices' | 'approvalProgram' | 'clearProgram'> & Required<Pick<ApplicationCallTransactionParams, 'approvalProgram' | 'clearProgram'>> & CommonTransactionParams & ApplicationCallReferenceParams): Transaction;
 /**
  * Make a transaction that deletes an application
  *

package/dist/types/mnemonic/mnemonic.d.ts

@@ -52,5 +52,7 @@ export declare function masterDerivationKeyToMnemonic(mdk: Uint8Array): string;
  * @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 declare function pq25WordMnemonicToSeed(mn: string, scheme: Uint8Array): Uint8Array;

package/dist/types/pq-signer.d.ts

@@ -1,8 +1,45 @@
 import { Address } from './encoding/address.js';
-import { AddressWithDelegatedLsigSigner, AddressWithTransactionSigner } from './signer.js';
+import { AddressWithDelegatedLsigSigner, AddressWithEmptyTransactionSigner, AddressWithTransactionSigner } from './signer.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>;
 }
-export declare function addressWithSignersFromRawPQSigner(signingKey: PQSigningKey, sendingAddress?: Address): AddressWithTransactionSigner & AddressWithDelegatedLsigSigner;
+/**
+ * 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 declare function addressWithSignersFromRawPQSigner(signingKey: PQSigningKey, sendingAddress?: Address): AddressWithTransactionSigner & AddressWithDelegatedLsigSigner & AddressWithEmptyTransactionSigner;