@algorandfoundation/algokit-utils 10.0.0-alpha.4 → 10.0.0-alpha.41

package/app-manager.d.ts

@@ -0,0 +1,323 @@
+import { Address, ReadableAddress } from "./packages/common/src/address.js";
+import { ABIValue } from "./packages/abi/src/abi-value.js";
+import { ABIType } from "./packages/abi/src/abi-type.js";
+import { ABIMethod, ABIReturn } from "./packages/abi/src/abi-method.js";
+import { BoxReference as BoxReference$1 } from "./packages/transact/src/transactions/app-call.js";
+import { AddressWithTransactionSigner } from "./packages/transact/src/signer.js";
+import { TealValue } from "./packages/algod_client/src/models/teal-value.js";
+import { EvalDelta } from "./packages/algod_client/src/models/eval-delta.js";
+import { PendingTransactionResponse } from "./packages/algod_client/src/models/pending-transaction-response.js";
+import { AlgodClient } from "./packages/algod_client/src/client.js";
+import { AppState, BoxName, CompiledTeal, TealTemplateParams } from "./app.js";
+
+//#region src/app-manager.d.ts
+/** Information about an app. */
+interface AppInformation {
+  /** The ID of the app. */
+  appId: bigint;
+  /** The escrow address that the app operates with. */
+  appAddress: Address;
+  /**
+   * Approval program.
+   */
+  approvalProgram: Uint8Array;
+  /**
+   * Clear state program.
+   */
+  clearStateProgram: Uint8Array;
+  /**
+   * The address that created this application. This is the address where the
+   * parameters and global state for this application can be found.
+   */
+  creator: Address;
+  /**
+   * Current global state values.
+   */
+  globalState: AppState;
+  /** The number of allocated ints in per-user local state. */
+  localInts: number;
+  /** The number of allocated byte slices in per-user local state. */
+  localByteSlices: number;
+  /** The number of allocated ints in global state. */
+  globalInts: number;
+  /** The number of allocated byte slices in global state. */
+  globalByteSlices: number;
+  /** Any extra pages that are needed for the smart contract. */
+  extraProgramPages?: number;
+  /** The number of updates to the application programs */
+  version?: number;
+}
+/**
+ * Something that identifies an app box name - either a:
+ *  * `Uint8Array` (the actual binary of the box name)
+ *  * `string` (that will be encoded to a `Uint8Array`)
+ *  * `AddressWithSigner` (that will be encoded into the
+ *    public key address of the corresponding account)
+ */
+type BoxIdentifier = string | Uint8Array | AddressWithTransactionSigner;
+/**
+ * A grouping of the app ID and name identifier to reference an app box.
+ */
+interface BoxReference {
+  /**
+   * A unique application id
+   */
+  appId: bigint;
+  /**
+   * Identifier for a box name
+   */
+  name: BoxIdentifier;
+}
+/**
+ * Parameters to get and decode a box value as an ABI type.
+ */
+interface BoxValueRequestParams {
+  /** The ID of the app return box names for */
+  appId: bigint;
+  /** The name of the box to return either as a string, binary array or `BoxName` */
+  boxName: BoxIdentifier;
+  /** The ABI type to decode the value using */
+  type: ABIType;
+}
+/**
+ * Parameters to get and decode a box value as an ABI type.
+ */
+interface BoxValuesRequestParams {
+  /** The ID of the app return box names for */
+  appId: bigint;
+  /** The names of the boxes to return either as a string, binary array or BoxName` */
+  boxNames: BoxIdentifier[];
+  /** The ABI type to decode the value using */
+  type: ABIType;
+}
+/** Allows management of application information. */
+declare class AppManager {
+  private _algod;
+  private _compilationResults;
+  /**
+   * Creates an `AppManager`
+   * @param algod An algod instance
+   */
+  constructor(algod: AlgodClient);
+  /**
+   * Compiles the given TEAL using algod and returns the result, including source map.
+   *
+   * The result of this compilation is also cached keyed by the TEAL
+   *  code so it can be retrieved via `getCompilationResult`.
+   *
+   * This function is re-entrant; it will only compile the same code once.
+   *
+   * @param tealCode The TEAL code
+   * @returns The information about the compiled file
+   * @example
+   * ```typescript
+   * const compiled = await appManager.compileTeal(tealProgram)
+   * ```
+   */
+  compileTeal(tealCode: string): Promise<CompiledTeal>;
+  /**
+   * Performs template substitution of a teal template and compiles it, returning the compiled result.
+   *
+   * Looks for `TMPL_{parameter}` for template replacements and replaces AlgoKit deploy-time control parameters
+   * if deployment metadata is specified.
+   *
+   * * `TMPL_UPDATABLE` for updatability / immutability control
+   * * `TMPL_DELETABLE` for deletability / permanence control
+   *
+   * @param tealTemplateCode The TEAL logic to compile
+   * @param templateParams Any parameters to replace in the .teal file before compiling
+   * @param deploymentMetadata The deployment metadata the app will be deployed with
+   * @returns The information about the compiled code
+   * @example
+   * ```typescript
+   * const compiled = await appManager.compileTealTemplate(tealTemplate, { TMPL_APP_ID: 12345n }, { updatable: true, deletable: false })
+   * ```
+   */
+  compileTealTemplate(tealTemplateCode: string, templateParams?: TealTemplateParams, deploymentMetadata?: {
+    updatable?: boolean;
+    deletable?: boolean;
+  }): Promise<CompiledTeal>;
+  /**
+   * Returns a previous compilation result.
+   * @param tealCode The TEAL code
+   * @returns The information about the previously compiled file
+   *  or `undefined` if that TEAL code wasn't previously compiled
+   * @example
+   * ```typescript
+   * const compiled = appManager.getCompilationResult(tealProgram)
+   * ```
+   */
+  getCompilationResult(tealCode: string): CompiledTeal | undefined;
+  /**
+   * Returns the current app information for the app with the given ID.
+   *
+   * @example
+   * ```typescript
+   * const appInfo = await appManager.getById(12353n);
+   * ```
+   *
+   * @param appId The ID of the app
+   * @returns The app information
+   */
+  getById(appId: bigint): Promise<AppInformation>;
+  /**
+   * Returns the current global state values for the given app ID and account address
+   *
+   * @param appId The ID of the app to return global state for
+   * @returns The current global state for the given app
+   * @example
+   * ```typescript
+   * const globalState = await appManager.getGlobalState(12353n);
+   * ```
+   */
+  getGlobalState(appId: bigint): Promise<AppState>;
+  /**
+   * Returns the current local state values for the given app ID and account address
+   *
+   * @param appId The ID of the app to return local state for
+   * @param address The string address of the account to get local state for the given app
+   * @returns The current local state for the given (app, account) combination
+   * @example
+   * ```typescript
+   * const localState = await appManager.getLocalState(12353n, 'ACCOUNTADDRESS');
+   * ```
+   */
+  getLocalState(appId: bigint, address: ReadableAddress): Promise<AppState>;
+  /**
+   * Returns the names of the current boxes for the given app.
+   * @param appId The ID of the app return box names for
+   * @returns The current box names
+   * @example
+   * ```typescript
+   * const boxNames = await appManager.getBoxNames(12353n);
+   * ```
+   */
+  getBoxNames(appId: bigint): Promise<BoxName[]>;
+  /**
+   * Returns the value of the given box name for the given app.
+   * @param appId The ID of the app return box names for
+   * @param boxName The name of the box to return either as a string, binary array or `BoxName`
+   * @returns The current box value as a byte array
+   * @example
+   * ```typescript
+   * const boxValue = await appManager.getBoxValue(12353n, 'boxName');
+   * ```
+   */
+  getBoxValue(appId: bigint, boxName: BoxIdentifier | BoxName): Promise<Uint8Array>;
+  /**
+   * Returns the value of the given box names for the given app.
+   * @param appId The ID of the app return box names for
+   * @param boxNames The names of the boxes to return either as a string, binary array or `BoxName`
+   * @returns The current box values as a byte array in the same order as the passed in box names
+   * @example
+   * ```typescript
+   * const boxValues = await appManager.getBoxValues(12353n, ['boxName1', 'boxName2']);
+   * ```
+   */
+  getBoxValues(appId: bigint, boxNames: (BoxIdentifier | BoxName)[]): Promise<Uint8Array[]>;
+  /**
+   * Returns the value of the given box name for the given app decoded based on the given ABI type.
+   * @param request The parameters for the box value request
+   * @returns The current box value as an ABI value
+   * @example
+   * ```typescript
+   * const boxValue = await appManager.getBoxValueFromABIType({ appId: 12353n, boxName: 'boxName', type: new ABIUintType(32) });
+   * ```
+   */
+  getBoxValueFromABIType(request: BoxValueRequestParams): Promise<ABIValue>;
+  /**
+   * Returns the value of the given box names for the given app decoded based on the given ABI type.
+   * @param request The parameters for the box value request
+   * @returns The current box values as an ABI value in the same order as the passed in box names
+   * @example
+   * ```typescript
+   * const boxValues = await appManager.getBoxValuesFromABIType({ appId: 12353n, boxNames: ['boxName1', 'boxName2'], type: new ABIUintType(32) });
+   * ```
+   */
+  getBoxValuesFromABIType(request: BoxValuesRequestParams): Promise<ABIValue[]>;
+  /**
+   * Returns a `algosdk.BoxReference` given a `BoxIdentifier` or `BoxReference`.
+   * @param boxId The box to return a reference for
+   * @returns The box reference ready to pass into a `algosdk.Transaction`
+   * @example
+   * ```typescript
+   * const boxRef = AppManager.getBoxReference('boxName');
+   * ```
+   */
+  static getBoxReference(boxId: BoxIdentifier | BoxReference): BoxReference$1;
+  /**
+   * Converts an array of global/local state values from the algod api to a more friendly
+   * generic object keyed by the UTF-8 value of the key.
+   * @param state A `global-state`, `local-state`, `global-state-deltas` or `local-state-deltas`
+   * @returns An object keyeed by the UTF-8 representation of the key with various parsings of the values
+   * @example
+   * ```typescript
+   * const stateValues = AppManager.decodeAppState(state);
+   * ```
+   */
+  static decodeAppState(state: {
+    key: Uint8Array;
+    value: TealValue | EvalDelta;
+  }[]): AppState;
+  /**
+   * Returns any ABI return values for the given app call arguments and transaction confirmation.
+   * @param confirmation The transaction confirmation from algod
+   * @param method The ABI method
+   * @returns The return value for the method call
+   * @example
+   * ```typescript
+   * const returnValue = AppManager.getABIReturn(confirmation, ABIMethod.fromSignature('hello(string)void'));
+   * ```
+   */
+  static getABIReturn(confirmation: PendingTransactionResponse | undefined, method: ABIMethod | undefined): ABIReturn | undefined;
+  private static hasAbiReturnPrefix;
+  /**
+   * Replaces AlgoKit deploy-time deployment control parameters within the given TEAL template code.
+   *
+   * * `TMPL_UPDATABLE` for updatability / immutability control
+   * * `TMPL_DELETABLE` for deletability / permanence control
+   *
+   * Note: If these values are defined, but the corresponding `TMPL_*` value
+   *  isn't in the teal code it will throw an exception.
+   *
+   * @param tealTemplateCode The TEAL template code to substitute
+   * @param params The deploy-time deployment control parameter value to replace
+   * @returns The replaced TEAL code
+   * @example
+   * ```typescript
+   * const tealCode = AppManager.replaceTealTemplateDeployTimeControlParams(tealTemplate, { updatable: true, deletable: false });
+   * ```
+   */
+  static replaceTealTemplateDeployTimeControlParams(tealTemplateCode: string, params: {
+    updatable?: boolean;
+    deletable?: boolean;
+  }): string;
+  /**
+   * Performs template substitution of a teal file.
+   *
+   * Looks for `TMPL_{parameter}` for template replacements.
+   *
+   * @param tealTemplateCode The TEAL template code to make parameter replacements in
+   * @param templateParams Any parameters to replace in the teal code
+   * @returns The TEAL code with replacements
+   * @example
+   * ```typescript
+   * const tealCode = AppManager.replaceTealTemplateParams(tealTemplate, { TMPL_APP_ID: 12345n });
+   * ```
+   */
+  static replaceTealTemplateParams(tealTemplateCode: string, templateParams?: TealTemplateParams): string;
+  /**
+   * Remove comments from TEAL code (useful to reduce code size before compilation).
+   *
+   * @param tealCode The TEAL logic to strip
+   * @returns The TEAL without comments
+   * @example
+   * ```typescript
+   * const stripped = AppManager.stripTealComments(tealProgram);
+   * ```
+   */
+  static stripTealComments(tealCode: string): string;
+}
+//#endregion
+export { AppInformation, AppManager, BoxIdentifier, BoxReference, BoxValueRequestParams, BoxValuesRequestParams };
+//# sourceMappingURL=app-manager.d.ts.map