algosdk 2.8.0 → 3.0.0-beta.1

package/src/types/transactions/base.ts

@@ -1,7 +1,8 @@
+import { Address } from '../../encoding/address.js';
+import { StateProof, StateProofMessage } from '../../stateproof.js';
+
 /**
  * Enum for application transaction types.
- *
- * The full list is available at https://developer.algorand.org/docs/reference/transactions/
  */
 export enum TransactionType {
   /**
@@ -39,6 +40,11 @@ export enum TransactionType {
   stpf = 'stpf',
 }
 
+/**
+ * Check if a string is a valid transaction type
+ * @param s - string to check
+ * @returns true if s is a valid transaction type
+ */
 export function isTransactionType(s: string): s is TransactionType {
   return (
     s === TransactionType.pay ||
@@ -95,7 +101,25 @@ export enum OnApplicationComplete {
 }
 
 /**
- * A dict holding common-to-all-txns arguments
+ * Check if a value is a valid OnApplicationComplete value
+ * @param v - value to check
+ * @returns true if v is a valid OnApplicationComplete value
+ */
+export function isOnApplicationComplete(
+  v: unknown
+): v is OnApplicationComplete {
+  return (
+    v === OnApplicationComplete.NoOpOC ||
+    v === OnApplicationComplete.OptInOC ||
+    v === OnApplicationComplete.CloseOutOC ||
+    v === OnApplicationComplete.ClearStateOC ||
+    v === OnApplicationComplete.UpdateApplicationOC ||
+    v === OnApplicationComplete.DeleteApplicationOC
+  );
+}
+
+/**
+ * Contains parameters relevant to the creation of a new transaction in a specific network at a specific time
  */
 export interface SuggestedParams {
   /**
@@ -107,36 +131,34 @@ export interface SuggestedParams {
   /**
    * Integer fee per byte, in microAlgos. For a flat fee, set flatFee to true
    */
-  fee: number;
+  fee: number | bigint;
+
+  /**
+   * Minimum fee (not per byte) required for the transaction to be confirmed
+   */
+  minFee: number | bigint;
 
   /**
    * First protocol round on which this txn is valid
    */
-  firstRound: number;
+  firstValid: number | bigint;
 
   /**
    * Last protocol round on which this txn is valid
    */
-  lastRound: number;
+  lastValid: number | bigint;
 
   /**
    * Specifies genesis ID of network in use
    */
-  genesisID: string;
+  genesisID?: string;
 
   /**
    * Specifies hash genesis block of network in use
    */
-  genesisHash: string;
+  genesisHash?: Uint8Array;
 }
 
-export type SuggestedParamsWithMinFee = SuggestedParams & {
-  /**
-   * Minimum fee (not per byte) required for the transaction to be confirmed
-   */
-  minFee: number;
-};
-
 /**
  * A grouping of the app ID and name of the box in an Uint8Array
  */
@@ -144,7 +166,7 @@ export interface BoxReference {
   /**
    * A unique application index
    */
-  appIndex: number;
+  appIndex: number | bigint;
 
   /**
    * Name of box to reference
@@ -153,211 +175,245 @@ export interface BoxReference {
 }
 
 /**
- * A full list of all available transaction parameters
+ * Contains payment transaction parameters.
  *
  * The full documentation is available at:
- * https://developer.algorand.org/docs/reference/transactions/#common-fields-header-and-type
+ * https://developer.algorand.org/docs/get-details/transactions/transactions/#payment-transaction
  */
-export interface TransactionParams {
+export interface PaymentTransactionParams {
   /**
-   * String representation of Algorand address of sender
+   * Algorand address of recipient
    */
-  from: string;
+  receiver: string | Address;
 
   /**
-   * String representation of Algorand address of recipient
+   * Integer amount to send, in microAlgos. Must be nonnegative.
    */
-  to: string;
+  amount: number | bigint;
 
   /**
-   * Integer fee per byte, in microAlgos. For a flat fee, set flatFee to true
+   * Optional, indicates the sender will close their account and the remaining balance will transfer
+   * to this account
    */
-  fee: number;
+  closeRemainderTo?: string | Address;
+}
 
+/**
+ * Contains key registration transaction parameters
+ *
+ * The full documentation is available at:
+ * https://developer.algorand.org/docs/get-details/transactions/transactions/#key-registration-transaction
+ */
+export interface KeyRegistrationTransactionParams {
   /**
-   * Integer amount to send
+   * 32-byte voting key. For key deregistration, leave undefined
    */
-  amount: number | bigint;
+  voteKey?: Uint8Array | string;
 
   /**
-   * Integer first protocol round on which this txn is valid
+   * 32-byte selection key. For key deregistration, leave undefined
    */
-  firstRound: number;
+  selectionKey?: Uint8Array | string;
 
   /**
-   * Integer last protocol round on which this txn is valid
+   * 64-byte state proof key. For key deregistration, leave undefined
    */
-  lastRound: number;
+  stateProofKey?: Uint8Array | string;
 
   /**
-   * Arbitrary data for sender to store
+   * First round on which voting keys are valid
    */
-  note?: Uint8Array;
+  voteFirst?: number | bigint;
 
   /**
-   * Specifies genesis ID of network in use
+   * Last round on which voting keys are valid
    */
-  genesisID: string;
+  voteLast?: number | bigint;
 
   /**
-   * Specifies hash genesis block of network in use
+   * The dilution fo the 2-level participation key
    */
-  genesisHash: string;
+  voteKeyDilution?: number | bigint;
 
   /**
-   * Lease a transaction. The sender cannot send another txn with that same lease until the last round of original txn has passed
+   * Set this value to true to mark this account as nonparticipating.
+   *
+   * All new Algorand accounts are participating by default. This means they earn rewards.
    */
-  lease?: Uint8Array;
+  nonParticipation?: boolean;
+}
 
+/**
+ * Contains asset configuration transaction parameters.
+ *
+ * The full documentation is available at:
+ * https://developer.algorand.org/docs/get-details/transactions/transactions/#asset-configuration-transaction
+ */
+export interface AssetConfigurationTransactionParams {
   /**
-   * Close out remaining account balance to this account
+   * Asset index uniquely specifying the asset
    */
-  closeRemainderTo?: string;
+  assetIndex?: number | bigint;
 
   /**
-   * Voting key bytes. For key deregistration, leave undefined
+   * Total supply of the asset
    */
-  voteKey: Uint8Array | string;
+  total?: number | bigint;
 
   /**
-   *Selection key bytes. For key deregistration, leave undefined
+   * Integer number of decimals for asset unit calcuation
    */
-  selectionKey: Uint8Array | string;
+  decimals?: number | bigint;
 
   /**
-   * State proof key bytes. For key deregistration, leave undefined
+   * Whether asset accounts should default to being frozen
    */
-  stateProofKey: Uint8Array | string;
+  defaultFrozen?: boolean;
 
   /**
-   * First round on which voteKey is valid
+   * The Algorand address in charge of reserve, freeze, clawback, destruction, etc.
    */
-  voteFirst: number;
+  manager?: string | Address;
 
   /**
-   * Last round on which voteKey is valid
+   * The Algorand address representing asset reserve
    */
-  voteLast: number;
+  reserve?: string | Address;
 
   /**
-   * The dilution fo the 2-level participation key
+   * The Algorand address with power to freeze/unfreeze asset holdings
    */
-  voteKeyDilution: number;
+  freeze?: string | Address;
 
   /**
-   * Asset index uniquely specifying the asset
+   * The Algorand address with power to revoke asset holdings
    */
-  assetIndex: number;
+  clawback?: string | Address;
 
   /**
-   * Total supply of the asset
+   * Unit name for this asset
    */
-  assetTotal: number | bigint;
+  unitName?: string;
 
   /**
-   * Integer number of decimals for asset unit calcuation
+   * Name for this asset
    */
-  assetDecimals: number;
+  assetName?: string;
 
   /**
-   * Whether asset accounts should default to being frozen
+   * URL relating to this asset
    */
-  assetDefaultFrozen: boolean;
+  assetURL?: string;
 
   /**
-   * String representation of Algorand address in charge of reserve, freeze, clawback, destruction, etc.
+   * Uint8Array containing a hash commitment with respect to the asset. Must be exactly 32 bytes long.
    */
-  assetManager?: string;
+  assetMetadataHash?: Uint8Array;
+}
 
+/**
+ * Contains asset transfer transaction parameters.
+ *
+ * The full documentation is available at:
+ * https://developer.algorand.org/docs/get-details/transactions/transactions/#asset-transfer-transaction
+ */
+export interface AssetTransferTransactionParams {
   /**
-   * String representation of Algorand address representing asset reserve
+   * Asset index uniquely specifying the asset
    */
-  assetReserve?: string;
+  assetIndex: number | bigint;
 
   /**
-   * String representation of Algorand address with power to freeze/unfreeze asset holdings
+   * String representation of Algorand address – if provided, and if "sender" is
+   * the asset's revocation manager, then deduct from "assetSender" rather than "sender"
    */
-  assetFreeze?: string;
+  assetSender?: string | Address;
 
   /**
-   * String representation of Algorand address with power to revoke asset holdings
+   * The Algorand address of recipient
    */
-  assetClawback?: string;
+  receiver: string | Address;
 
   /**
-   * Unit name for this asset
-   */
-  assetUnitName?: string;
-  /**
-   * Name for this asset
+   * Integer amount to send
    */
-  assetName?: string;
+  amount: number | bigint;
 
   /**
-   * URL relating to this asset
+   * Close out remaining asset balance of the sender to this account
    */
-  assetURL?: string;
+  closeRemainderTo?: string | Address;
+}
 
+/**
+ * Contains asset freeze transaction parameters.
+ *
+ * The full documentation is available at:
+ * https://developer.algorand.org/docs/get-details/transactions/transactions/#asset-freeze-transaction
+ */
+export interface AssetFreezeTransactionParams {
   /**
-   * Uint8Array or UTF-8 string representation of a hash commitment with respect to the asset. Must be exactly 32 bytes long.
+   * Asset index uniquely specifying the asset
    */
-  assetMetadataHash?: Uint8Array | string;
+  assetIndex: number | bigint;
 
   /**
-   * String representation of Algorand address being frozen or unfrozen
+   * Algorand address being frozen or unfrozen
    */
-  freezeAccount: string;
+  freezeTarget: string | Address;
 
   /**
    * true if freezeTarget should be frozen, false if freezeTarget should be allowed to transact
    */
-  freezeState: boolean;
-
-  /**
-   * String representation of Algorand address – if provided, and if "from" is
-   * the asset's revocation manager, then deduct from "revocationTarget" rather than "from"
-   */
-  assetRevocationTarget?: string;
+  frozen: boolean;
+}
 
+/**
+ * Contains application call transaction parameters.
+ *
+ * The full documentation is available at:
+ * https://developer.algorand.org/docs/get-details/transactions/transactions/#application-call-transaction
+ */
+export interface ApplicationCallTransactionParams {
   /**
-   * A unique application index
+   * A unique application ID
    */
-  appIndex: number;
+  appIndex: number | bigint;
 
   /**
    * What application should do once the program has been run
    */
-  appOnComplete: OnApplicationComplete;
+  onComplete: OnApplicationComplete;
 
   /**
    * Restricts number of ints in per-user local state
    */
-  appLocalInts: number;
+  numLocalInts?: number | bigint;
 
   /**
    * Restricts number of byte slices in per-user local state
    */
-  appLocalByteSlices: number;
+  numLocalByteSlices?: number | bigint;
 
   /**
    * Restricts number of ints in global state
    */
-  appGlobalInts: number;
+  numGlobalInts?: number | bigint;
 
   /**
    * Restricts number of byte slices in global state
    */
-  appGlobalByteSlices: number;
+  numGlobalByteSlices?: number | bigint;
 
   /**
    * The compiled TEAL that approves a transaction
    */
-  appApprovalProgram: Uint8Array;
+  approvalProgram?: Uint8Array;
 
   /**
    * The compiled TEAL program that runs when clearing state
    */
-  appClearProgram: Uint8Array;
+  clearProgram?: Uint8Array;
 
   /**
    * Array of Uint8Array, any additional arguments to the application
@@ -367,69 +423,121 @@ export interface TransactionParams {
   /**
    * Array of Address strings, any additional accounts to supply to the application
    */
-  appAccounts?: string[];
+  accounts?: Array<string | Address>;
 
   /**
    * Array of int, any other apps used by the application, identified by index
    */
-  appForeignApps?: number[];
+  foreignApps?: Array<number | bigint>;
 
   /**
    * Array of int, any assets used by the application, identified by index
    */
-  appForeignAssets?: number[];
+  foreignAssets?: Array<number | bigint>;
+
+  /**
+   * Int representing extra pages of memory to rent during an application create transaction.
+   */
+  extraPages?: number | bigint;
+
+  /**
+   * A grouping of the app ID and name of the box in an Uint8Array
+   */
+  boxes?: BoxReference[];
+}
+
+/**
+ * Contains state proof transaction parameters.
+ */
+export interface StateProofTransactionParams {
+  /*
+   * Uint64 identifying a particular configuration of state proofs.
+   */
+  stateProofType?: number | bigint;
+
+  /**
+   * The state proof.
+   */
+  stateProof?: StateProof;
 
+  /**
+   * The state proof message.
+   */
+  message?: StateProofMessage;
+}
+
+/**
+ * A full list of all available transaction parameters
+ *
+ * The full documentation is available at:
+ * https://developer.algorand.org/docs/get-details/transactions/transactions/#common-fields-header-and-type
+ */
+export interface TransactionParams {
   /**
    * Transaction type
    */
-  type?: TransactionType;
+  type: TransactionType;
 
   /**
-   * Set this to true to specify fee as microalgos-per-txn.
+   * Algorand address of sender
+   */
+  sender: string | Address;
+
+  /**
+   * Optional, arbitrary data to be included in the transaction's note field
+   */
+  note?: Uint8Array;
+
+  /**
+   * Optional, 32-byte lease to associate with this transaction.
    *
-   * If the final calculated fee is lower than the protocol minimum fee, the fee will be increased to match the minimum
+   * The sender cannot send another transaction with the same lease until the last round of original
+   * transaction has passed.
    */
-  flatFee?: boolean;
+  lease?: Uint8Array;
 
   /**
-   * A dict holding common-to-all-txns arguments
+   * The Algorand address that will be used to authorize all future transactions from the sender, if provided.
+   */
+  rekeyTo?: string | Address;
+
+  /**
+   * Suggested parameters relevant to the network that will accept this transaction
    */
   suggestedParams: SuggestedParams;
 
   /**
-   * String representation of the Algorand address that will be used to authorize all future transactions
+   * Payment transaction parameters. Only set if type is TransactionType.pay
    */
-  reKeyTo?: string;
+  paymentParams?: PaymentTransactionParams;
 
   /**
-   * Set this value to true to mark this account as nonparticipating.
-   *
-   * All new Algorand accounts are participating by default. This means they earn rewards.
+   * Key registration transaction parameters. Only set if type is TransactionType.keyreg
    */
-  nonParticipation?: boolean;
+  keyregParams?: KeyRegistrationTransactionParams;
 
   /**
-   * Int representing extra pages of memory to rent during an application create transaction.
+   * Asset configuration transaction parameters. Only set if type is TransactionType.acfg
    */
-  extraPages?: number;
+  assetConfigParams?: AssetConfigurationTransactionParams;
 
   /**
-   * A grouping of the app ID and name of the box in an Uint8Array
+   * Asset transfer transaction parameters. Only set if type is TransactionType.axfer
    */
-  boxes?: BoxReference[];
+  assetTransferParams?: AssetTransferTransactionParams;
 
-  /*
-   * Uint64 identifying a particular configuration of state proofs.
+  /**
+   * Asset freeze transaction parameters. Only set if type is TransactionType.afrz
    */
-  stateProofType?: number | bigint;
+  assetFreezeParams?: AssetFreezeTransactionParams;
 
   /**
-   * Byte array containing the state proof.
+   * Application call transaction parameters. Only set if type is TransactionType.appl
    */
-  stateProof?: Uint8Array;
+  appCallParams?: ApplicationCallTransactionParams;
 
   /**
-   * Byte array containing the state proof message.
+   * State proof transaction parameters. Only set if type is TransactionType.stpf
    */
-  stateProofMessage?: Uint8Array;
+  stateProofParams?: StateProofTransactionParams;
 }