algosdk 3.7.0 → 3.9.0-beta.1

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

@@ -1,8 +1,45 @@
 import { Address } from './encoding/address.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>;
 }
+/**
+ * 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;

package/dist/types/signer.d.ts

@@ -21,9 +21,24 @@ export interface Addressable {
  *   corresponds to the signed transaction from txnGroup[indexesToSign[i]]
  */
 export type TransactionSigner = (txnGroup: Transaction[], 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)
@@ -32,11 +47,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) => Promise<{
     address: Address;
 } & ({
@@ -46,14 +76,47 @@ export type DelegatedLsigSigner = (lsig: LogicSig, msig?: MultisigMetadata) => P
 } | {
     pqsig: EncodedPQSig;
 })>;
+/**
+ * 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/dist/types/signing.d.ts

@@ -3,6 +3,11 @@ import { SignedTransaction } from './signedTransaction.js';
 import { Transaction } from './transaction.js';
 import { LogicSig, LogicSigAccount } from './logicsig.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 declare const SIGN_BYTES_PREFIX: Uint8Array;
 /**
  * @deprecated Use signTransactionWithSigner
@@ -25,6 +30,23 @@ export declare function signTransaction(txn: Transaction, sk: Uint8Array): {
     txID: string;
     blob: 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 declare function signTransactionWithSigner(txn: Transaction, signer: TransactionSigner): Promise<ReturnType<typeof signTransaction> & {
     stxn: SignedTransaction;
 }>;

package/dist/types/types/block.d.ts

@@ -49,9 +49,14 @@ export declare class TxnCommitments implements Encodable {
      * Root of transaction vector commitment merkle tree using SHA256 hash function
      */
     sha256Commitment: Uint8Array;
+    /**
+     * Root of transaction vector commitment merkle tree using SHA512 hash function
+     */
+    sha512Commitment: Uint8Array;
     constructor(params: {
         nativeSha512_256Commitment: Uint8Array;
         sha256Commitment: Uint8Array;
+        sha512Commitment?: Uint8Array;
     });
     getEncodingSchema(): Schema;
     toEncodingData(): Map<string, unknown>;
@@ -196,6 +201,10 @@ export declare class BlockHeader implements Encodable {
      * Previous block hash
      */
     branch: Uint8Array;
+    /**
+     * Previous block hash, using SHA-512
+     */
+    branch512: Uint8Array;
     /**
      * Sortition seed
      */
@@ -249,9 +258,20 @@ export declare class BlockHeader implements Encodable {
      */
     stateproofTracking: Map<number, StateProofTrackingData>;
     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.
+     */
+    load: bigint;
+    /**
+     * CongestionTax is the fee required, beyond the MinFee, for "normal" transactions in this block.
+     */
+    congestionTax: bigint;
     constructor(params: {
         round: bigint;
         branch: Uint8Array;
+        branch512?: Uint8Array;
         seed: Uint8Array;
         txnCommitments: TxnCommitments;
         timestamp: bigint;
@@ -267,6 +287,8 @@ export declare class BlockHeader implements Encodable {
         txnCounter: bigint;
         stateproofTracking: Map<number, StateProofTrackingData>;
         participationUpdates: ParticipationUpdates;
+        load?: bigint;
+        congestionTax?: bigint;
     });
     getEncodingSchema(): Schema;
     toEncodingData(): Map<string, unknown>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "algosdk",
-  "version": "3.7.0",
+  "version": "3.9.0-beta.1",
   "description": "The official JavaScript SDK for Algorand",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -45,7 +45,10 @@
   },
   "repository": {
     "type": "git",
-    "url": "git://github.com/algorand/js-algorand-sdk.git"
+    "url": "git+https://github.com/algorand/js-algorand-sdk.git"
+  },
+  "overrides": {
+    "basic-ftp": ">=6.2.1"
   },
   "dependencies": {
     "algorand-msgpack": "^1.1.0",
@@ -58,31 +61,38 @@
     "vlq": "^2.0.4"
   },
   "devDependencies": {
+    "@algorandfoundation/falcon-wasm": "1.0.0",
+    "@commitlint/cli": "^19.8.1",
+    "@commitlint/config-conventional": "^19.8.1",
+    "@semantic-release/exec": "^7.1.0",
+    "@semantic-release/git": "^10.0.1",
     "@types/json-bigint": "^1.0.0",
-    "@types/mocha": "^8.2.2",
+    "@types/mocha": "^10.0.10",
     "@types/node": "^20.11.5",
-    "@typescript-eslint/eslint-plugin": "^6.18.1",
-    "@typescript-eslint/parser": "^6.18.1",
+    "@typescript-eslint/eslint-plugin": "^8.70.1",
+    "@typescript-eslint/parser": "^8.70.1",
     "assert": "^2.0.0",
-    "chromedriver": "^136.0.3",
+    "better-npm-audit": "^3.11.0",
+    "chromedriver": "^154.0.0",
     "concurrently": "^6.2.0",
+    "conventional-changelog-conventionalcommits": "8.0.0",
     "cucumber": "^5.1.0",
     "es-abstract": "^1.18.3",
-    "eslint": "8.22.0",
+    "eslint": "^8.57.1",
     "eslint-config-airbnb-base": "^15.0.0",
     "eslint-config-prettier": "^9.1.0",
     "eslint-import-resolver-typescript": "^3.6.1",
     "eslint-plugin-import": "^2.25.2",
-    "eslint-plugin-tsdoc": "^0.2.11",
-    "express": "^4.19.2",
-    "@algorandfoundation/falcon-wasm": "1.0.0",
+    "eslint-plugin-tsdoc": "^0.5.3",
+    "express": "^4.22.3",
     "geckodriver": "^4.3.0",
     "husky": "^4.3.8",
     "lint-staged": "^10.5.4",
-    "mocha": "^11.1.0",
+    "mocha": "^12.0.2",
     "mock-http-server": "^1.4.3",
     "prettier": "^3.2.1",
     "selenium-webdriver": "^4.10.0",
+    "semantic-release": "^25.0.9",
     "source-map-loader": "^2.0.2",
     "ts-loader": "^9.3.1",
     "tsx": "^4.7.0",
@@ -103,11 +113,109 @@
     "lint": "eslint .",
     "lint:fix": "eslint --fix .",
     "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "check-types": "tsc --noEmit",
+    "audit": "better-npm-audit audit",
+    "commit-lint": "commitlint --edit -o",
+    "semantic-release": "semantic-release",
     "example": "ts-node"
   },
+  "release": {
+    "branches": [
+      {
+        "name": "main",
+        "prerelease": "beta",
+        "channel": "beta"
+      },
+      {
+        "name": "release"
+      }
+    ],
+    "plugins": [
+      [
+        "@semantic-release/commit-analyzer",
+        {
+          "preset": "conventionalcommits",
+          "releaseRules": [
+            {
+              "type": "build",
+              "release": "patch"
+            },
+            {
+              "type": "chore",
+              "release": "patch"
+            },
+            {
+              "type": "refactor",
+              "release": "patch"
+            }
+          ]
+        }
+      ],
+      [
+        "@semantic-release/release-notes-generator",
+        {
+          "preset": "conventionalcommits",
+          "presetConfig": {
+            "types": [
+              {
+                "type": "feat",
+                "scope": "nye",
+                "section": "Not Yet Enabled"
+              },
+              {
+                "type": "feat",
+                "section": "Features"
+              },
+              {
+                "type": "fix",
+                "section": "Bug Fixes"
+              },
+              {
+                "type": "build",
+                "section": "Dependencies and Other Build Updates",
+                "hidden": false
+              },
+              {
+                "type": "refactor",
+                "section": "Code Refactoring"
+              }
+            ]
+          }
+        }
+      ],
+      "@semantic-release/npm",
+      [
+        "@semantic-release/exec",
+        {
+          "prepareCmd": "node scripts/ci/update-readme-sri.js ${nextRelease.version}"
+        }
+      ],
+      [
+        "@semantic-release/git",
+        {
+          "assets": [
+            "README.md"
+          ],
+          "message": "chore(release): update README to v${nextRelease.version} [skip ci]"
+        }
+      ],
+      [
+        "@semantic-release/github",
+        {
+          "assets": [
+            {
+              "path": "dist/browser/algosdk.min.js",
+              "label": "Minified browser bundle (algosdk.min.js)"
+            }
+          ]
+        }
+      ]
+    ]
+  },
   "author": "Algorand, llc",
   "license": "MIT",
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.0"
   }
 }

package/src/ed25519-signer.ts

@@ -25,11 +25,40 @@ import {
 } from './types/transactions/encoded.js';
 import { arrayEqual, concatArrays } from './utils/utils.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 function addressWithSignersFromRawEd25519Signer(
   ed25519SigningKey: Ed25519SigningKey,
   sendingAddress: Address = new Address(ed25519SigningKey.ed25519PublicKey)

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

@@ -11,11 +11,38 @@ 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