algosdk 3.7.0 → 3.8.0

package/src/signer.ts

@@ -36,10 +36,25 @@ 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;
 }
 
+/**
+ * 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)
@@ -49,11 +64,26 @@ export interface AddressWithEmptyTransactionSigner extends Addressable {
   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
- * */
+/**
+ * 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
@@ -65,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/types/block.ts

@@ -112,6 +112,10 @@ export class TxnCommitments implements Encodable {
         key: 'txn256', // sha256Commitment
         valueSchema: new FixedLengthByteArraySchema(32),
       },
+      {
+        key: 'txn512', // sha512Commitment
+        valueSchema: new FixedLengthByteArraySchema(64),
+      },
     ])
   );
 
@@ -126,12 +130,19 @@ export class TxnCommitments implements Encodable {
    */
   public sha256Commitment: Uint8Array;
 
+  /**
+   * Root of transaction vector commitment merkle tree using SHA512 hash function
+   */
+  public sha512Commitment: Uint8Array;
+
   constructor(params: {
     nativeSha512_256Commitment: Uint8Array;
     sha256Commitment: Uint8Array;
+    sha512Commitment?: Uint8Array;
   }) {
     this.nativeSha512_256Commitment = params.nativeSha512_256Commitment;
     this.sha256Commitment = params.sha256Commitment;
+    this.sha512Commitment = params.sha512Commitment ?? new Uint8Array(64);
   }
 
   // eslint-disable-next-line class-methods-use-this
@@ -143,6 +154,7 @@ export class TxnCommitments implements Encodable {
     return new Map<string, unknown>([
       ['txn', this.nativeSha512_256Commitment],
       ['txn256', this.sha256Commitment],
+      ['txn512', this.sha512Commitment],
     ]);
   }
 
@@ -153,6 +165,7 @@ export class TxnCommitments implements Encodable {
     return new TxnCommitments({
       nativeSha512_256Commitment: data.get('txn'),
       sha256Commitment: data.get('txn256'),
+      sha512Commitment: data.get('txn512'),
     });
   }
 }
@@ -509,6 +522,10 @@ export class BlockHeader implements Encodable {
         key: 'prev', // branch
         valueSchema: new BlockHashSchema(),
       },
+      {
+        key: 'prev512', // branch512
+        valueSchema: new FixedLengthByteArraySchema(64),
+      },
       {
         key: 'seed', // seed
         valueSchema: new ByteArraySchema(),
@@ -574,6 +591,14 @@ export class BlockHeader implements Encodable {
         valueSchema: ParticipationUpdates.encodingSchema,
         embedded: true,
       },
+      {
+        key: 'ld', // load
+        valueSchema: new Uint64Schema(),
+      },
+      {
+        key: 'ct', // congestionTax
+        valueSchema: new Uint64Schema(),
+      },
     ])
   );
 
@@ -587,6 +612,11 @@ export class BlockHeader implements Encodable {
    */
   public branch: Uint8Array;
 
+  /**
+   * Previous block hash, using SHA-512
+   */
+  public branch512: Uint8Array;
+
   /**
    * Sortition seed
    */
@@ -655,9 +685,22 @@ export class BlockHeader implements Encodable {
 
   public participationUpdates: ParticipationUpdates;
 
+  /**
+   * Load is the degree to which a block is full. Currently, it is based on the number of bytes in
+   * the final block, compared to the maximum allowed. It is expressed as a fixed-point integer with
+   * 6 digits of precision. So, 1,000,000 is a completely full block.
+   */
+  public load: bigint;
+
+  /**
+   * CongestionTax is the fee required, beyond the MinFee, for "normal" transactions in this block.
+   */
+  public congestionTax: bigint;
+
   public constructor(params: {
     round: bigint;
     branch: Uint8Array;
+    branch512?: Uint8Array;
     seed: Uint8Array;
     txnCommitments: TxnCommitments;
     timestamp: bigint;
@@ -673,9 +716,12 @@ export class BlockHeader implements Encodable {
     txnCounter: bigint;
     stateproofTracking: Map<number, StateProofTrackingData>;
     participationUpdates: ParticipationUpdates;
+    load?: bigint;
+    congestionTax?: bigint;
   }) {
     this.round = params.round;
     this.branch = params.branch;
+    this.branch512 = params.branch512 ?? new Uint8Array(64);
     this.seed = params.seed;
     this.txnCommitments = params.txnCommitments;
     this.timestamp = params.timestamp;
@@ -691,6 +737,8 @@ export class BlockHeader implements Encodable {
     this.txnCounter = params.txnCounter;
     this.stateproofTracking = params.stateproofTracking;
     this.participationUpdates = params.participationUpdates;
+    this.load = params.load ?? BigInt(0);
+    this.congestionTax = params.congestionTax ?? BigInt(0);
   }
 
   // eslint-disable-next-line class-methods-use-this
@@ -702,6 +750,7 @@ export class BlockHeader implements Encodable {
     const data = new Map<string, unknown>([
       ['rnd', this.round],
       ['prev', this.branch],
+      ['prev512', this.branch512],
       ['seed', this.seed],
       ['ts', this.timestamp],
       ['gen', this.genesisID],
@@ -711,6 +760,8 @@ export class BlockHeader implements Encodable {
       ['bi', this.bonus],
       ['pp', this.proposerPayout],
       ['tc', this.txnCounter],
+      ['ld', this.load],
+      ['ct', this.congestionTax],
       [
         'spt',
         convertMap(this.stateproofTracking, (key, value) => [
@@ -736,6 +787,7 @@ export class BlockHeader implements Encodable {
     return new BlockHeader({
       round: data.get('rnd'),
       branch: data.get('prev'),
+      branch512: data.get('prev512'),
       seed: data.get('seed'),
       txnCommitments: TxnCommitments.fromEncodingData(data),
       timestamp: data.get('ts'),
@@ -757,6 +809,8 @@ export class BlockHeader implements Encodable {
         ]
       ),
       participationUpdates: ParticipationUpdates.fromEncodingData(data),
+      load: data.get('ld'),
+      congestionTax: data.get('ct'),
     });
   }
 }