algosdk 3.7.0-beta.1 → 3.7.0

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/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/pq-signer.ts

@@ -5,6 +5,7 @@ import { MultisigMetadata } from './multisig.js';
 import { SignedTransaction } from './signedTransaction.js';
 import {
   AddressWithDelegatedLsigSigner,
+  AddressWithEmptyTransactionSigner,
   AddressWithTransactionSigner,
   DelegatedLsigSigner,
   TransactionSigner,
@@ -22,7 +23,9 @@ export interface PQSigningKey {
 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 +59,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 +117,7 @@ export function addressWithSignersFromRawPQSigner(
   return {
     address: sendingAddress ?? authAddress,
     txnSigner,
+    emptyTxnSigner,
     delegatedLsigSigner,
   };
 }

package/src/signer.ts

@@ -40,6 +40,15 @@ export interface AddressWithTransactionSigner extends Addressable {
   txnSigner: TransactionSigner;
 }
 
+export interface AddressWithEmptyTransactionSigner extends Addressable {
+  /**
+   * A TransactionSigner that produces unsigned (or placeholder-signed)
+   * transactions. This must only be used to simulate transactions with the
+   * `allowEmptySignatures` option enabled.
+   */
+  emptyTxnSigner: TransactionSigner;
+}
+
 /** Function for signing logic signatures for delegation
  *  @param lsig - The logic signature that is being signed for delegation
  *  @param msig - Optional multisig account that should be set when a public key is signing as a subsigner of a multisig

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 {

package/src/types/statedelta.ts

@@ -139,6 +139,10 @@ export class AppParams implements Encodable {
       { key: 'lsch', valueSchema: StateSchema.encodingSchema }, // localStateSchema
       { key: 'gsch', valueSchema: StateSchema.encodingSchema }, // globalStateSchema
       { key: 'epp', valueSchema: new Uint64Schema() }, // extraProgramPages
+      { key: 'v', valueSchema: new Uint64Schema() }, // version
+      { key: 'ss', valueSchema: new AddressSchema() }, // sizeSponsor
+      { key: 'fbr', valueSchema: new BooleanSchema() }, // foreignBoxReads
+      { key: 'fba', valueSchema: new BooleanSchema() }, // familyBoxAccess
     ])
   );
 
@@ -148,6 +152,20 @@ export class AppParams implements Encodable {
   public localStateSchema: StateSchema;
   public globalStateSchema: StateSchema;
   public extraProgramPages: number;
+  public version: bigint;
+  /**
+   * If non-zero, the account that must hold MBR for extra program pages and the
+   * global schema.
+   */
+  public sizeSponsor: Address;
+  /**
+   * When true, any app may read this app's boxes.
+   */
+  public foreignBoxReads: boolean;
+  /**
+   * When true, apps with the same creator may read and write this app's boxes.
+   */
+  public familyBoxAccess: boolean;
 
   constructor(params: {
     approvalProgram: Uint8Array;
@@ -156,6 +174,10 @@ export class AppParams implements Encodable {
     localStateSchema: StateSchema;
     globalStateSchema: StateSchema;
     extraProgramPages: number;
+    version?: bigint;
+    sizeSponsor?: Address;
+    foreignBoxReads?: boolean;
+    familyBoxAccess?: boolean;
   }) {
     this.approvalProgram = params.approvalProgram;
     this.clearStateProgram = params.clearStateProgram;
@@ -163,6 +185,10 @@ export class AppParams implements Encodable {
     this.localStateSchema = params.localStateSchema;
     this.globalStateSchema = params.globalStateSchema;
     this.extraProgramPages = params.extraProgramPages;
+    this.version = params.version ?? BigInt(0);
+    this.sizeSponsor = params.sizeSponsor ?? Address.zeroAddress();
+    this.foreignBoxReads = params.foreignBoxReads ?? false;
+    this.familyBoxAccess = params.familyBoxAccess ?? false;
   }
 
   // eslint-disable-next-line class-methods-use-this
@@ -178,6 +204,10 @@ export class AppParams implements Encodable {
       ['lsch', this.localStateSchema.toEncodingData()],
       ['gsch', this.globalStateSchema.toEncodingData()],
       ['epp', this.extraProgramPages],
+      ['v', this.version],
+      ['ss', this.sizeSponsor],
+      ['fbr', this.foreignBoxReads],
+      ['fba', this.familyBoxAccess],
     ]);
   }
 
@@ -195,6 +225,10 @@ export class AppParams implements Encodable {
       localStateSchema: StateSchema.fromEncodingData(data.get('lsch')),
       globalStateSchema: StateSchema.fromEncodingData(data.get('gsch')),
       extraProgramPages: Number(data.get('epp')),
+      version: data.get('v'),
+      sizeSponsor: data.get('ss'),
+      foreignBoxReads: data.get('fbr'),
+      familyBoxAccess: data.get('fba'),
     });
   }
 }

package/src/types/transactions/base.ts

@@ -592,6 +592,17 @@ export interface HeartbeatTransactionParams {
    * Must match hbAddress account's current KeyDilution.
    */
   keyDilution: bigint;
+
+  /**
+   * Requests the challenge fee discount: when set, the required fee is reduced
+   * by one min fee. The network verifies that hbAddress is actually under
+   * challenge before granting it, and a heartbeat claiming the discount may not
+   * carry any extra fields (note, lease, group, etc.).
+   *
+   * Only allowed once transaction size pricing is enabled. Before that, the
+   * discount was inferred from an underpaid singleton heartbeat instead.
+   */
+  challengeDiscount?: boolean;
 }
 
 /**

package/src/utils/utils.ts

@@ -205,3 +205,16 @@ export function ensureUint64(value: unknown): bigint {
   }
   return bigIntValue;
 }
+
+export function isEmptyObject(obj: any) {
+  if (!obj || typeof obj !== 'object') return false;
+
+  for (const key in obj) {
+    if (Object.prototype.hasOwnProperty.call(obj, key)) {
+      if (obj[key] !== undefined) {
+        return false;
+      }
+    }
+  }
+  return true;
+}