@algorandfoundation/algokit-utils 7.0.0-beta.9 → 8.0.0-beta.1

package/types/composer.d.ts

@@ -1,4 +1,4 @@
-import algosdk from 'algosdk';
+import algosdk, { Address } from 'algosdk';
 import { TransactionSignerAccount } from './account';
 import { AlgoAmount } from './amount';
 import { AppManager, BoxIdentifier, BoxReference } from './app-manager';
@@ -18,7 +18,7 @@ export type SimulateOptions = Expand<Omit<ConstructorParameters<typeof modelsv2.
 /** Common parameters for defining a transaction. */
 export type CommonTransactionParams = {
     /** The address of the account sending the transaction. */
-    sender: string;
+    sender: string | Address;
     /** The function used to sign transaction(s); if not specified then
      *  an attempt will be made to find a registered signer for the
      *  given `sender` or use a default signer (if configured).
@@ -28,7 +28,7 @@ export type CommonTransactionParams = {
      *
      * **Warning:** Please be careful with this parameter and be sure to read the [official rekey guidance](https://developer.algorand.org/docs/get-details/accounts/rekey/).
      */
-    rekeyTo?: string;
+    rekeyTo?: string | Address;
     /** Note to attach to the transaction. Max of 1000 bytes. */
     note?: Uint8Array | string;
     /** Prevent multiple transactions with the same lease being included within the validity window.
@@ -44,7 +44,7 @@ export type CommonTransactionParams = {
     /** Throw an error if the fee for the transaction is more than this amount; prevents overspending on fees during high congestion periods. */
     maxFee?: AlgoAmount;
     /** How many rounds the transaction should be valid for, if not specified then the registered default validity window will be used. */
-    validityWindow?: number;
+    validityWindow?: number | bigint;
     /**
      * Set the first round this transaction is valid.
      * If left undefined, the value from algod will be used.
@@ -58,14 +58,14 @@ export type CommonTransactionParams = {
 /** Parameters to define a payment transaction. */
 export type PaymentParams = CommonTransactionParams & {
     /** The address of the account that will receive the Algo */
-    receiver: string;
+    receiver: string | Address;
     /** Amount to send */
     amount: AlgoAmount;
     /** If given, close the sender account and send the remaining balance to this address
      *
      * *Warning:* Be careful with this parameter as it can lead to loss of funds if not used correctly.
      */
-    closeRemainderTo?: string;
+    closeRemainderTo?: string | Address;
 };
 /** Parameters to define an asset create transaction.
  *
@@ -136,7 +136,7 @@ export type AssetCreateParams = CommonTransactionParams & {
      *
      * If not set (`undefined` or `""`) at asset creation or subsequently set to empty by the `manager` the asset becomes permanently immutable.
      */
-    manager?: string;
+    manager?: string | Address;
     /**
      * The address of the optional account that holds the reserve (uncirculated supply) units of the asset.
      *
@@ -150,7 +150,7 @@ export type AssetCreateParams = CommonTransactionParams & {
      *
      * If not set (`undefined` or `""`) at asset creation or subsequently set to empty by the manager the field is permanently empty.
      */
-    reserve?: string;
+    reserve?: string | Address;
     /**
      * The address of the optional account that can be used to freeze or unfreeze holdings of this asset for any account.
      *
@@ -158,7 +158,7 @@ export type AssetCreateParams = CommonTransactionParams & {
      *
      * If not set (`undefined` or `""`) at asset creation or subsequently set to empty by the manager the field is permanently empty.
      */
-    freeze?: string;
+    freeze?: string | Address;
     /**
      * The address of the optional account that can clawback holdings of this asset from any account.
      *
@@ -168,7 +168,7 @@ export type AssetCreateParams = CommonTransactionParams & {
      *
      * If not set (`undefined` or `""`) at asset creation or subsequently set to empty by the manager the field is permanently empty.
      */
-    clawback?: string;
+    clawback?: string | Address;
 };
 /** Parameters to define an asset reconfiguration transaction.
  *
@@ -185,7 +185,7 @@ export type AssetConfigParams = CommonTransactionParams & {
      *
      * If not set (`undefined` or `""`) the asset will become permanently immutable.
      */
-    manager: string | undefined;
+    manager: string | Address | undefined;
     /**
      * The address of the optional account that holds the reserve (uncirculated supply) units of the asset.
      *
@@ -199,7 +199,7 @@ export type AssetConfigParams = CommonTransactionParams & {
      *
      * If not set (`undefined` or `""`) the field will become permanently empty.
      */
-    reserve?: string;
+    reserve?: string | Address;
     /**
      * The address of the optional account that can be used to freeze or unfreeze holdings of this asset for any account.
      *
@@ -207,7 +207,7 @@ export type AssetConfigParams = CommonTransactionParams & {
      *
      * If not set (`undefined` or `""`) the field will become permanently empty.
      */
-    freeze?: string;
+    freeze?: string | Address;
     /**
      * The address of the optional account that can clawback holdings of this asset from any account.
      *
@@ -217,14 +217,14 @@ export type AssetConfigParams = CommonTransactionParams & {
      *
      * If not set (`undefined` or `""`) the field will become permanently empty.
      */
-    clawback?: string;
+    clawback?: string | Address;
 };
 /** Parameters to define an asset freeze transaction. */
 export type AssetFreezeParams = CommonTransactionParams & {
     /** The ID of the asset to freeze/unfreeze */
     assetId: bigint;
     /** The address of the account to freeze or unfreeze */
-    account: string;
+    account: string | Address;
     /** Whether the assets in the account should be frozen */
     frozen: boolean;
 };
@@ -243,19 +243,19 @@ export type AssetTransferParams = CommonTransactionParams & {
     /** Amount of the asset to transfer (in smallest divisible (decimal) units). */
     amount: bigint;
     /** The address of the account that will receive the asset unit(s). */
-    receiver: string;
+    receiver: string | Address;
     /** Optional address of an account to clawback the asset from.
      *
      * Requires the sender to be the clawback account.
      *
      * **Warning:** Be careful with this parameter as it can lead to unexpected loss of funds if not used correctly.
      */
-    clawbackTarget?: string;
+    clawbackTarget?: string | Address;
     /** Optional address of an account to close the asset position to.
      *
      * **Warning:** Be careful with this parameter as it can lead to loss of funds if not used correctly.
      */
-    closeAssetTo?: string;
+    closeAssetTo?: string | Address;
 };
 /** Parameters to define an asset opt-in transaction. */
 export type AssetOptInParams = CommonTransactionParams & {
@@ -270,7 +270,7 @@ export type AssetOptOutParams = CommonTransactionParams & {
      * The address of the asset creator account to close the asset
      *   position to (any remaining asset units will be sent to this account).
      */
-    creator: string;
+    creator: string | Address;
 };
 /** Parameters to define an online key registration transaction. */
 export type OnlineKeyRegistrationParams = CommonTransactionParams & {
@@ -287,6 +287,11 @@ export type OnlineKeyRegistrationParams = CommonTransactionParams & {
     /** The 64 byte state proof public key commitment */
     stateProofKey?: Uint8Array;
 };
+/** Parameters to define an offline key registration transaction. */
+export type OfflineKeyRegistrationParams = CommonTransactionParams & {
+    /** Prevent this account from ever participating again. The account will also no longer earn rewards */
+    preventAccountFromEverParticipatingAgain?: boolean;
+};
 /** Common parameters for defining an application call transaction. */
 export type CommonAppCallParams = CommonTransactionParams & {
     /** ID of the application; 0 if the application is being created. */
@@ -296,7 +301,7 @@ export type CommonAppCallParams = CommonTransactionParams & {
     /** Any [arguments to pass to the smart contract call](https://developer.algorand.org/docs/get-details/dapps/avm/teal/#argument-passing). */
     args?: Uint8Array[];
     /** Any account addresses to add to the [accounts array](https://developer.algorand.org/docs/get-details/dapps/smart-contracts/apps/#reference-arrays). */
-    accountReferences?: string[];
+    accountReferences?: (string | Address)[];
     /** The ID of any apps to load to the [foreign apps array](https://developer.algorand.org/docs/get-details/dapps/smart-contracts/apps/#reference-arrays). */
     appReferences?: bigint[];
     /** The ID of any assets to load to the [foreign assets array](https://developer.algorand.org/docs/get-details/dapps/smart-contracts/apps/#reference-arrays). */
@@ -371,8 +376,9 @@ export type AppMethodCall<T> = Expand<Omit<T, 'args'>> & {
      * * A transaction (where the signer will be automatically assigned)
      * * An unawaited transaction (e.g. from algorand.createTransaction.{transactionType}())
      * * Another method call (via method call params object)
+     * * undefined (this represents a placeholder transaction argument that is fulfilled by another method call argument)
      */
-    args?: (algosdk.ABIValue | TransactionWithSigner | Transaction | Promise<Transaction> | AppMethodCall<AppCreateParams> | AppMethodCall<AppUpdateParams> | AppMethodCall<AppMethodCallParams>)[];
+    args?: (algosdk.ABIValue | TransactionWithSigner | Transaction | Promise<Transaction> | AppMethodCall<AppCreateParams> | AppMethodCall<AppUpdateParams> | AppMethodCall<AppMethodCallParams> | undefined)[];
 };
 export type Txn = (PaymentParams & {
     type: 'pay';
@@ -392,7 +398,7 @@ export type Txn = (PaymentParams & {
     type: 'assetOptOut';
 }) | ((AppCallParams | AppCreateParams | AppUpdateParams) & {
     type: 'appCall';
-}) | (OnlineKeyRegistrationParams & {
+}) | ((OnlineKeyRegistrationParams | OfflineKeyRegistrationParams) & {
     type: 'keyReg';
 }) | (algosdk.TransactionWithSigner & {
     type: 'txnWithSigner';
@@ -402,25 +408,25 @@ export type Txn = (PaymentParams & {
 } | ((AppCallMethodCall | AppCreateMethodCall | AppUpdateMethodCall) & {
     type: 'methodCall';
 });
-/** Parameters to create an `AlgoKitComposer`. */
-export type AlgoKitComposerParams = {
+/** Parameters to create an `TransactionComposer`. */
+export type TransactionComposerParams = {
     /** The algod client to use to get suggestedParams and send the transaction group */
     algod: algosdk.Algodv2;
     /** The function used to get the TransactionSigner for a given address */
-    getSigner: (address: string) => algosdk.TransactionSigner;
+    getSigner: (address: string | Address) => algosdk.TransactionSigner;
     /** The method used to get SuggestedParams for transactions in the group */
     getSuggestedParams?: () => Promise<algosdk.SuggestedParams>;
     /** How many rounds a transaction should be valid for by default; if not specified
      * then will be 10 rounds (or 1000 rounds if issuing transactions to LocalNet).
      */
-    defaultValidityWindow?: number;
+    defaultValidityWindow?: bigint;
     /** An existing `AppManager` to use to manage app compilation and cache compilation results.
      *
      * If not specified than an ephemeral one will be created.
      */
     appManager?: AppManager;
 };
-/** Set of transactions built by `AlgoKitComposer`. */
+/** Set of transactions built by `TransactionComposer`. */
 export interface BuiltTransactions {
     /** The built transactions */
     transactions: algosdk.Transaction[];
@@ -429,8 +435,8 @@ export interface BuiltTransactions {
     /** Any `TransactionSigner` objects associated with any of the transactions in a map keyed by transaction index. */
     signers: Map<number, algosdk.TransactionSigner>;
 }
-/** AlgoKit Composer helps you compose and execute transactions as a transaction group. */
-export default class AlgoKitComposer {
+/** TransactionComposer helps you compose and execute transactions as a transaction group. */
+export declare class TransactionComposer {
     /** Signer used to represent a lack of signer */
     private static NULL_SIGNER;
     /** The ATC used to compose the group */
@@ -451,65 +457,65 @@ export default class AlgoKitComposer {
     private defaultValidityWindowIsExplicit;
     private appManager;
     /**
-     * Create an `AlgoKitComposer`.
+     * Create a `TransactionComposer`.
      * @param params The configuration for this composer
      */
-    constructor(params: AlgoKitComposerParams);
+    constructor(params: TransactionComposerParams);
     /**
      * Add a pre-built transaction to the transaction group.
      * @param transaction The pre-built transaction
      * @param signer Optional signer override for the transaction
      * @returns The composer so you can chain method calls
      */
-    addTransaction(transaction: Transaction, signer?: TransactionSigner): AlgoKitComposer;
+    addTransaction(transaction: Transaction, signer?: TransactionSigner): TransactionComposer;
     /**
      * Add a payment transaction to the transaction group.
      * @param params The payment transaction parameters
      * @returns The composer so you can chain method calls
      */
-    addPayment(params: PaymentParams): AlgoKitComposer;
+    addPayment(params: PaymentParams): TransactionComposer;
     /**
      * Add an asset create transaction to the transaction group.
      * @param params The asset create transaction parameters
      * @returns The composer so you can chain method calls
      */
-    addAssetCreate(params: AssetCreateParams): AlgoKitComposer;
+    addAssetCreate(params: AssetCreateParams): TransactionComposer;
     /**
      * Add an asset config transaction to the transaction group.
      * @param params The asset config transaction parameters
      * @returns The composer so you can chain method calls
      */
-    addAssetConfig(params: AssetConfigParams): AlgoKitComposer;
+    addAssetConfig(params: AssetConfigParams): TransactionComposer;
     /**
      * Add an asset freeze transaction to the transaction group.
      * @param params The asset freeze transaction parameters
      * @returns The composer so you can chain method calls
      */
-    addAssetFreeze(params: AssetFreezeParams): AlgoKitComposer;
+    addAssetFreeze(params: AssetFreezeParams): TransactionComposer;
     /**
      * Add an asset destroy transaction to the transaction group.
      * @param params The asset destroy transaction parameters
      * @returns The composer so you can chain method calls
      */
-    addAssetDestroy(params: AssetDestroyParams): AlgoKitComposer;
+    addAssetDestroy(params: AssetDestroyParams): TransactionComposer;
     /**
      * Add an asset transfer transaction to the transaction group.
      * @param params The asset transfer transaction parameters
      * @returns The composer so you can chain method calls
      */
-    addAssetTransfer(params: AssetTransferParams): AlgoKitComposer;
+    addAssetTransfer(params: AssetTransferParams): TransactionComposer;
     /**
      * Add an asset opt-in transaction to the transaction group.
      * @param params The asset opt-in transaction parameters
      * @returns The composer so you can chain method calls
      */
-    addAssetOptIn(params: AssetOptInParams): AlgoKitComposer;
+    addAssetOptIn(params: AssetOptInParams): TransactionComposer;
     /**
      * Add an asset opt-out transaction to the transaction group.
      * @param params The asset opt-out transaction parameters
      * @returns The composer so you can chain method calls
      */
-    addAssetOptOut(params: AssetOptOutParams): AlgoKitComposer;
+    addAssetOptOut(params: AssetOptOutParams): TransactionComposer;
     /**
      * Add an application create transaction to the transaction group.
      *
@@ -517,7 +523,7 @@ export default class AlgoKitComposer {
      * @param params The application create transaction parameters
      * @returns The composer so you can chain method calls
      */
-    addAppCreate(params: AppCreateParams): AlgoKitComposer;
+    addAppCreate(params: AppCreateParams): TransactionComposer;
     /**
      * Add an application update transaction to the transaction group.
      *
@@ -525,7 +531,7 @@ export default class AlgoKitComposer {
      * @param params The application update transaction parameters
      * @returns The composer so you can chain method calls
      */
-    addAppUpdate(params: AppUpdateParams): AlgoKitComposer;
+    addAppUpdate(params: AppUpdateParams): TransactionComposer;
     /**
      * Add an application delete transaction to the transaction group.
      *
@@ -533,7 +539,7 @@ export default class AlgoKitComposer {
      * @param params The application delete transaction parameters
      * @returns The composer so you can chain method calls
      */
-    addAppDelete(params: AppDeleteParams): AlgoKitComposer;
+    addAppDelete(params: AppDeleteParams): TransactionComposer;
     /**
      * Add an application call transaction to the transaction group.
      *
@@ -543,7 +549,7 @@ export default class AlgoKitComposer {
      * @param params The application call transaction parameters
      * @returns The composer so you can chain method calls
      */
-    addAppCall(params: AppCallParams): AlgoKitComposer;
+    addAppCall(params: AppCallParams): TransactionComposer;
     /**
      * Add an ABI method create application call transaction to the transaction group.
      *
@@ -581,13 +587,19 @@ export default class AlgoKitComposer {
      * @param params The online key registration transaction parameters
      * @returns The composer so you can chain method calls
      */
-    addOnlineKeyRegistration(params: OnlineKeyRegistrationParams): AlgoKitComposer;
+    addOnlineKeyRegistration(params: OnlineKeyRegistrationParams): TransactionComposer;
+    /**
+     * Add an offline key registration transaction to the transaction group.
+     * @param params The offline key registration transaction parameters
+     * @returns The composer so you can chain method calls
+     */
+    addOfflineKeyRegistration(params: OfflineKeyRegistrationParams): TransactionComposer;
     /**
      * Add the transactions within an `AtomicTransactionComposer` to the transaction group.
      * @param atc The `AtomicTransactionComposer` to build transactions from and add to the group
      * @returns The composer so you can chain method calls
      */
-    addAtc(atc: algosdk.AtomicTransactionComposer): AlgoKitComposer;
+    addAtc(atc: algosdk.AtomicTransactionComposer): TransactionComposer;
     /** Build an ATC and return transactions ready to be incorporated into a broader set of transactions this composer is composing */
     private buildAtc;
     private commonTxnBuildStep;