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

package/algorand-client.mjs

@@ -0,0 +1,349 @@
+import { nobleEd25519Generator } from "./packages/crypto/src/ed25519.mjs";
+import { AppManager } from "./app-manager.mjs";
+import { TransactionComposer } from "./composer.mjs";
+import { ClientManager } from "./client-manager.mjs";
+import { AccountManager } from "./account-manager.mjs";
+import { AlgorandClientTransactionCreator } from "./algorand-client-transaction-creator.mjs";
+import { AlgorandClientTransactionSender } from "./algorand-client-transaction-sender.mjs";
+import { AppDeployer } from "./app-deployer.mjs";
+import { AssetManager } from "./asset-manager.mjs";
+import { NetworkManager } from "./network-manager.mjs";
+
+//#region src/algorand-client.ts
+/**
+* A client that brokers easy access to Algorand functionality.
+*/
+var AlgorandClient = class AlgorandClient {
+	_clientManager;
+	_accountManager;
+	_appManager;
+	_appDeployer;
+	_assetManager;
+	_networkManager;
+	_transactionSender;
+	_transactionCreator;
+	_cachedSuggestedParams;
+	_cachedSuggestedParamsExpiry;
+	_cachedSuggestedParamsTimeout = 3e3;
+	_defaultValidityWindow = void 0;
+	/**
+	* A set of error transformers to use when an error is caught in simulate or execute
+	* `registerErrorTransformer` and `unregisterErrorTransformer` can be used to add and remove
+	* error transformers from the set.
+	*/
+	_errorTransformers = /* @__PURE__ */ new Set();
+	constructor(config) {
+		this._clientManager = new ClientManager(config, this);
+		this._accountManager = new AccountManager(this._clientManager, { ed25519Generator: config.ed25519Generator ?? nobleEd25519Generator });
+		this._appManager = new AppManager(this._clientManager.algod);
+		this._assetManager = new AssetManager(this._clientManager.algod, (config) => this.newGroup(config));
+		this._networkManager = new NetworkManager(this._clientManager.algod, this);
+		this._transactionSender = new AlgorandClientTransactionSender((config) => this.newGroup(config), this._assetManager, this._appManager);
+		this._transactionCreator = new AlgorandClientTransactionCreator((config) => this.newGroup(config));
+		this._appDeployer = new AppDeployer(this._appManager, this._transactionSender, this._clientManager.indexerIfPresent);
+	}
+	/**
+	* Sets the default validity window for transactions.
+	* @param validityWindow The number of rounds between the first and last valid rounds
+	* @returns The `AlgorandClient` so method calls can be chained
+	* @example
+	* ```typescript
+	* const algorand = AlgorandClient.mainNet().setDefaultValidityWindow(1000);
+	* ```
+	*/
+	setDefaultValidityWindow(validityWindow) {
+		this._defaultValidityWindow = BigInt(validityWindow);
+		return this;
+	}
+	/**
+	* Sets the default signer to use if no other signer is specified.
+	* @param signer The signer to use, either a `TransactionSigner` or a `AddressWithSigner`
+	* @returns The `AlgorandClient` so method calls can be chained
+	* @example
+	* ```typescript
+	* const signer = new SigningAccount(account, account.addr)
+	* const algorand = AlgorandClient.mainNet().setDefaultSigner(signer)
+	* ```
+	*/
+	setDefaultSigner(signer) {
+		this._accountManager.setDefaultSigner(signer);
+		return this;
+	}
+	/**
+	* Tracks the given account (object that encapsulates an address and a signer) for later signing.
+	* @param account The account to register, which can be a `AddressWithSigner` or
+	*  a `algosdk.Account`, `algosdk.LogicSigAccount`, `SigningAccount` or `MultisigAccount`
+	* @example
+	* ```typescript
+	* const accountManager = AlgorandClient.mainNet()
+	*  .setSignerFromAccount(algosdk.generateAccount())
+	*  .setSignerFromAccount(new algosdk.LogicSigAccount(program, args))
+	*  .setSignerFromAccount(new SigningAccount(account, sender))
+	*  .setSignerFromAccount(new MultisigAccount({version: 1, threshold: 1, addrs: ["ADDRESS1...", "ADDRESS2..."]}, [account1, account2]))
+	*  .setSignerFromAccount({addr: "SENDERADDRESS", signer: transactionSigner})
+	* ```
+	* @returns The `AlgorandClient` so method calls can be chained
+	*/
+	setSignerFromAccount(account) {
+		this._accountManager.setSignerFromAccount(account);
+		return this;
+	}
+	/**
+	* Tracks the given signer against the given sender for later signing.
+	* @param sender The sender address to use this signer for
+	* @param signer The signer to sign transactions with for the given sender
+	* @returns The `AlgorandClient` so method calls can be chained
+	* @example
+	* ```typescript
+	* const signer = new SigningAccount(account, account.addr)
+	* const algorand = AlgorandClient.mainNet().setSigner(signer.addr, signer.signer)
+	* ```
+	*/
+	setSigner(sender, signer) {
+		this._accountManager.setSigner(sender, signer);
+		return this;
+	}
+	/**
+	* Sets a cache value to use for suggested transaction params.
+	* @param suggestedParams The suggested params to use
+	* @param until A date until which to cache, or if not specified then the timeout is used
+	* @returns The `AlgorandClient` so method calls can be chained
+	* @example
+	* ```typescript
+	* const algorand = AlgorandClient.mainNet().setSuggestedParamsCache(suggestedParams, new Date(+new Date() + 3_600_000))
+	* ```
+	*/
+	setSuggestedParamsCache(suggestedParams, until) {
+		this._cachedSuggestedParams = suggestedParams;
+		this._cachedSuggestedParamsExpiry = until ?? new Date(+/* @__PURE__ */ new Date() + this._cachedSuggestedParamsTimeout);
+		return this;
+	}
+	/**
+	* Sets the timeout for caching suggested params.
+	* @param timeout The timeout in milliseconds
+	* @returns The `AlgorandClient` so method calls can be chained
+	* @example
+	* ```typescript
+	* const algorand = AlgorandClient.mainNet().setSuggestedParamsCacheTimeout(10_000)
+	* ```
+	*/
+	setSuggestedParamsCacheTimeout(timeout) {
+		this._cachedSuggestedParamsTimeout = timeout;
+		return this;
+	}
+	/**
+	* Get suggested params for a transaction (either cached or from algod if the cache is stale or empty)
+	* @returns The suggested transaction parameters.
+	* @example
+	* const params = await AlgorandClient.mainNet().getSuggestedParams();
+	*/
+	async getSuggestedParams() {
+		if (this._cachedSuggestedParams && (!this._cachedSuggestedParamsExpiry || this._cachedSuggestedParamsExpiry > /* @__PURE__ */ new Date())) return { ...this._cachedSuggestedParams };
+		this._cachedSuggestedParams = await this._clientManager.algod.suggestedParams();
+		this._cachedSuggestedParamsExpiry = new Date((/* @__PURE__ */ new Date()).getTime() + this._cachedSuggestedParamsTimeout);
+		return { ...this._cachedSuggestedParams };
+	}
+	/**
+	* Get clients, including algosdk clients and app clients.
+	* @returns The `ClientManager` instance.
+	* @example
+	* const clientManager = AlgorandClient.mainNet().client;
+	*/
+	get client() {
+		return this._clientManager;
+	}
+	/**
+	* Get or create accounts that can sign transactions.
+	* @returns The `AccountManager` instance.
+	* @example
+	* const accountManager = AlgorandClient.mainNet().account;
+	*/
+	get account() {
+		return this._accountManager;
+	}
+	/**
+	* Methods for interacting with assets.
+	* @returns The `AssetManager` instance.
+	* @example
+	* const assetManager = AlgorandClient.mainNet().asset;
+	*/
+	get asset() {
+		return this._assetManager;
+	}
+	/**
+	* Methods for interacting with apps.
+	* @returns The `AppManager` instance.
+	* @example
+	* const appManager = AlgorandClient.mainNet().app;
+	*/
+	get app() {
+		return this._appManager;
+	}
+	/**
+	* Methods for deploying apps and managing app deployment metadata.
+	* @returns The `AppDeployer` instance.
+	* @example
+	* const deployer = AlgorandClient.mainNet().appDeployer;
+	*/
+	get appDeployer() {
+		return this._appDeployer;
+	}
+	/**
+	* Methods for interacting with the network.
+	* Provides utilities for querying blockchain state and waiting for specific conditions.
+	* @returns The `NetworkManager` instance.
+	* @example
+	* ```typescript
+	* // Get last round
+	* const lastRound = await algorand.network.getLastRound()
+	*
+	* // Wait for a specific round
+	* await algorand.network.waitUntilRound(1000n)
+	*
+	* // LocalNet-specific: block warp
+	* await algorand.network.localNet.blockWarp(100n)
+	* ```
+	*/
+	get network() {
+		return this._networkManager;
+	}
+	/**
+	* Register a function that will be used to transform an error caught when simulating or executing
+	* composed transaction groups made from `newGroup`
+	*/
+	registerErrorTransformer(transformer) {
+		this._errorTransformers.add(transformer);
+	}
+	unregisterErrorTransformer(transformer) {
+		this._errorTransformers.delete(transformer);
+	}
+	/** Start a new `TransactionComposer` transaction group
+	* @returns A new instance of `TransactionComposer`.
+	* @example
+	* {@includeCode ./algorand-client.spec.ts#example-newGroup}
+	* @see [Full working example](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/algorand-client.spec.ts)
+	*/
+	newGroup(composerConfig) {
+		return new TransactionComposer({
+			algod: this.client.algod,
+			getSigner: (addr) => this.account.getSigner(addr),
+			getSuggestedParams: () => this.getSuggestedParams(),
+			defaultValidityWindow: this._defaultValidityWindow,
+			appManager: this._appManager,
+			errorTransformers: [...this._errorTransformers],
+			composerConfig
+		});
+	}
+	/**
+	* Methods for sending a transaction.
+	* @returns The `AlgorandClientTransactionSender` instance.
+	* @example
+	* const result = await AlgorandClient.mainNet().send.payment({
+	*  sender: "SENDERADDRESS",
+	*  receiver: "RECEIVERADDRESS",
+	*  amount: algo(1)
+	* })
+	*/
+	get send() {
+		return this._transactionSender;
+	}
+	/**
+	* Methods for creating a transaction.
+	* @returns The `AlgorandClientTransactionCreator` instance.
+	* @example
+	* const payment = await AlgorandClient.mainNet().createTransaction.payment({
+	*  sender: "SENDERADDRESS",
+	*  receiver: "RECEIVERADDRESS",
+	*  amount: algo(1)
+	* })
+	*/
+	get createTransaction() {
+		return this._transactionCreator;
+	}
+	/**
+	* Creates an `AlgorandClient` pointing at default LocalNet ports and API token.
+	* @returns An instance of the `AlgorandClient`.
+	* @example
+	* {@includeCode ./algorand-client.spec.ts#example-defaultLocalNet}
+	* @see [Full working example](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/algorand-client.spec.ts)
+	*/
+	static defaultLocalNet() {
+		return new AlgorandClient({
+			algodConfig: ClientManager.getDefaultLocalNetConfig("algod"),
+			indexerConfig: ClientManager.getDefaultLocalNetConfig("indexer"),
+			kmdConfig: ClientManager.getDefaultLocalNetConfig("kmd")
+		});
+	}
+	/**
+	* Creates an `AlgorandClient` pointing at TestNet using AlgoNode.
+	* @returns An instance of the `AlgorandClient`.
+	* @example
+	* const algorand = AlgorandClient.testNet();
+	*/
+	static testNet() {
+		return new AlgorandClient({
+			algodConfig: ClientManager.getAlgoNodeConfig("testnet", "algod"),
+			indexerConfig: ClientManager.getAlgoNodeConfig("testnet", "indexer"),
+			kmdConfig: void 0
+		});
+	}
+	/**
+	* Creates an `AlgorandClient` pointing at MainNet using AlgoNode.
+	* @returns An instance of the `AlgorandClient`.
+	* @example
+	* const algorand = AlgorandClient.mainNet();
+	*/
+	static mainNet() {
+		return new AlgorandClient({
+			algodConfig: ClientManager.getAlgoNodeConfig("mainnet", "algod"),
+			indexerConfig: ClientManager.getAlgoNodeConfig("mainnet", "indexer"),
+			kmdConfig: void 0
+		});
+	}
+	/**
+	* Creates an `AlgorandClient` pointing to the given client(s).
+	* @param clients The clients to use.
+	* @returns An instance of the `AlgorandClient`.
+	* @example
+	* const algorand = AlgorandClient.fromClients({ algod, indexer, kmd });
+	*/
+	static fromClients(clients) {
+		return new AlgorandClient(clients);
+	}
+	/**
+	* Creates an `AlgorandClient` loading the configuration from environment variables.
+	*
+	* Retrieve configurations from environment variables when defined or get default LocalNet configuration if they aren't defined.
+	*
+	* Expects to be called from a Node.js environment.
+	*
+	* If `process.env.ALGOD_SERVER` is defined it will use that along with optional `process.env.ALGOD_PORT` and `process.env.ALGOD_TOKEN`.
+	*
+	* If `process.env.INDEXER_SERVER` is defined it will use that along with optional `process.env.INDEXER_PORT` and `process.env.INDEXER_TOKEN`.
+	*
+	* If either aren't defined it will use the default LocalNet config.
+	*
+	* It will return a KMD configuration that uses `process.env.KMD_PORT` (or port 4002) if `process.env.ALGOD_SERVER` is defined,
+	* otherwise it will use the default LocalNet config unless it detects testnet or mainnet.
+	* @returns An instance of the `AlgorandClient`.
+	* @example
+	* const client = AlgorandClient.fromEnvironment();
+	*/
+	static fromEnvironment() {
+		return new AlgorandClient(ClientManager.getConfigFromEnvironmentOrLocalNet());
+	}
+	/**
+	* Creates  an `AlgorandClient` from the given config.
+	* @param config The config to use.
+	* @returns An instance of the `AlgorandClient`.
+	* @example
+	* const client = AlgorandClient.fromConfig({ algodConfig, indexerConfig, kmdConfig });
+	*/
+	static fromConfig(config) {
+		return new AlgorandClient(config);
+	}
+};
+
+//#endregion
+export { AlgorandClient };
+//# sourceMappingURL=algorand-client.mjs.map

package/algorand-client.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"algorand-client.mjs","names":[],"sources":["../src/algorand-client.ts"],"sourcesContent":["import { SuggestedParams } from '@algorandfoundation/algokit-algod-client'\nimport { Address, ReadableAddress } from '@algorandfoundation/algokit-common'\nimport { nobleEd25519Generator } from '@algorandfoundation/algokit-crypto'\nimport { AddressWithTransactionSigner, LogicSigAccount, MultisigAccount, TransactionSigner } from '@algorandfoundation/algokit-transact'\nimport { AccountManager, AccountManagerConfig } from './account-manager'\nimport { AlgorandClientTransactionCreator } from './algorand-client-transaction-creator'\nimport { AlgorandClientTransactionSender } from './algorand-client-transaction-sender'\nimport { AppDeployer } from './app-deployer'\nimport { AppManager } from './app-manager'\nimport { AssetManager } from './asset-manager'\nimport { AlgoSdkClients, ClientManager } from './client-manager'\nimport { ErrorTransformer, TransactionComposer, TransactionComposerConfig } from './composer'\nimport { AlgoConfig } from './network-client'\nimport { NetworkManager } from './network-manager'\n\n/**\n * A client that brokers easy access to Algorand functionality.\n */\nexport class AlgorandClient {\n  private _clientManager: ClientManager\n  private _accountManager: AccountManager\n  private _appManager: AppManager\n  private _appDeployer: AppDeployer\n  private _assetManager: AssetManager\n  private _networkManager: NetworkManager\n  private _transactionSender: AlgorandClientTransactionSender\n  private _transactionCreator: AlgorandClientTransactionCreator\n\n  private _cachedSuggestedParams?: SuggestedParams\n  private _cachedSuggestedParamsExpiry?: Date\n  private _cachedSuggestedParamsTimeout: number = 3_000 // three seconds\n\n  private _defaultValidityWindow: bigint | undefined = undefined\n\n  /**\n   * A set of error transformers to use when an error is caught in simulate or execute\n   * `registerErrorTransformer` and `unregisterErrorTransformer` can be used to add and remove\n   * error transformers from the set.\n   */\n  private _errorTransformers: Set<ErrorTransformer> = new Set()\n\n  private constructor(config: (AlgoConfig | AlgoSdkClients) & Partial<AccountManagerConfig>) {\n    this._clientManager = new ClientManager(config, this)\n    this._accountManager = new AccountManager(this._clientManager, { ed25519Generator: config.ed25519Generator ?? nobleEd25519Generator })\n    this._appManager = new AppManager(this._clientManager.algod)\n    this._assetManager = new AssetManager(this._clientManager.algod, (config) => this.newGroup(config))\n    this._networkManager = new NetworkManager(this._clientManager.algod, this)\n    this._transactionSender = new AlgorandClientTransactionSender((config) => this.newGroup(config), this._assetManager, this._appManager)\n    this._transactionCreator = new AlgorandClientTransactionCreator((config) => this.newGroup(config))\n    this._appDeployer = new AppDeployer(this._appManager, this._transactionSender, this._clientManager.indexerIfPresent)\n  }\n\n  /**\n   * Sets the default validity window for transactions.\n   * @param validityWindow The number of rounds between the first and last valid rounds\n   * @returns The `AlgorandClient` so method calls can be chained\n   * @example\n   * ```typescript\n   * const algorand = AlgorandClient.mainNet().setDefaultValidityWindow(1000);\n   * ```\n   */\n  public setDefaultValidityWindow(validityWindow: number | bigint) {\n    this._defaultValidityWindow = BigInt(validityWindow)\n    return this\n  }\n\n  /**\n   * Sets the default signer to use if no other signer is specified.\n   * @param signer The signer to use, either a `TransactionSigner` or a `AddressWithSigner`\n   * @returns The `AlgorandClient` so method calls can be chained\n   * @example\n   * ```typescript\n   * const signer = new SigningAccount(account, account.addr)\n   * const algorand = AlgorandClient.mainNet().setDefaultSigner(signer)\n   * ```\n   */\n  public setDefaultSigner(signer: TransactionSigner | AddressWithTransactionSigner): AlgorandClient {\n    this._accountManager.setDefaultSigner(signer)\n    return this\n  }\n\n  /**\n   * Tracks the given account (object that encapsulates an address and a signer) for later signing.\n   * @param account The account to register, which can be a `AddressWithSigner` or\n   *  a `algosdk.Account`, `algosdk.LogicSigAccount`, `SigningAccount` or `MultisigAccount`\n   * @example\n   * ```typescript\n   * const accountManager = AlgorandClient.mainNet()\n   *  .setSignerFromAccount(algosdk.generateAccount())\n   *  .setSignerFromAccount(new algosdk.LogicSigAccount(program, args))\n   *  .setSignerFromAccount(new SigningAccount(account, sender))\n   *  .setSignerFromAccount(new MultisigAccount({version: 1, threshold: 1, addrs: [\"ADDRESS1...\", \"ADDRESS2...\"]}, [account1, account2]))\n   *  .setSignerFromAccount({addr: \"SENDERADDRESS\", signer: transactionSigner})\n   * ```\n   * @returns The `AlgorandClient` so method calls can be chained\n   */\n  public setSignerFromAccount(account: AddressWithTransactionSigner | LogicSigAccount | MultisigAccount) {\n    this._accountManager.setSignerFromAccount(account)\n    return this\n  }\n\n  /**\n   * Tracks the given signer against the given sender for later signing.\n   * @param sender The sender address to use this signer for\n   * @param signer The signer to sign transactions with for the given sender\n   * @returns The `AlgorandClient` so method calls can be chained\n   * @example\n   * ```typescript\n   * const signer = new SigningAccount(account, account.addr)\n   * const algorand = AlgorandClient.mainNet().setSigner(signer.addr, signer.signer)\n   * ```\n   */\n  public setSigner(sender: string | Address, signer: TransactionSigner) {\n    this._accountManager.setSigner(sender, signer)\n    return this\n  }\n\n  /**\n   * Sets a cache value to use for suggested transaction params.\n   * @param suggestedParams The suggested params to use\n   * @param until A date until which to cache, or if not specified then the timeout is used\n   * @returns The `AlgorandClient` so method calls can be chained\n   * @example\n   * ```typescript\n   * const algorand = AlgorandClient.mainNet().setSuggestedParamsCache(suggestedParams, new Date(+new Date() + 3_600_000))\n   * ```\n   */\n  public setSuggestedParamsCache(suggestedParams: SuggestedParams, until?: Date) {\n    this._cachedSuggestedParams = suggestedParams\n    this._cachedSuggestedParamsExpiry = until ?? new Date(+new Date() + this._cachedSuggestedParamsTimeout)\n    return this\n  }\n\n  /**\n   * Sets the timeout for caching suggested params.\n   * @param timeout The timeout in milliseconds\n   * @returns The `AlgorandClient` so method calls can be chained\n   * @example\n   * ```typescript\n   * const algorand = AlgorandClient.mainNet().setSuggestedParamsCacheTimeout(10_000)\n   * ```\n   */\n  public setSuggestedParamsCacheTimeout(timeout: number) {\n    this._cachedSuggestedParamsTimeout = timeout\n    return this\n  }\n\n  /**\n   * Get suggested params for a transaction (either cached or from algod if the cache is stale or empty)\n   * @returns The suggested transaction parameters.\n   * @example\n   * const params = await AlgorandClient.mainNet().getSuggestedParams();\n   */\n  public async getSuggestedParams(): Promise<SuggestedParams> {\n    if (this._cachedSuggestedParams && (!this._cachedSuggestedParamsExpiry || this._cachedSuggestedParamsExpiry > new Date())) {\n      return {\n        ...this._cachedSuggestedParams,\n      }\n    }\n\n    this._cachedSuggestedParams = await this._clientManager.algod.suggestedParams()\n    this._cachedSuggestedParamsExpiry = new Date(new Date().getTime() + this._cachedSuggestedParamsTimeout)\n\n    return {\n      ...this._cachedSuggestedParams,\n    }\n  }\n\n  /**\n   * Get clients, including algosdk clients and app clients.\n   * @returns The `ClientManager` instance.\n   * @example\n   * const clientManager = AlgorandClient.mainNet().client;\n   */\n  public get client() {\n    return this._clientManager\n  }\n\n  /**\n   * Get or create accounts that can sign transactions.\n   * @returns The `AccountManager` instance.\n   * @example\n   * const accountManager = AlgorandClient.mainNet().account;\n   */\n  public get account() {\n    return this._accountManager\n  }\n\n  /**\n   * Methods for interacting with assets.\n   * @returns The `AssetManager` instance.\n   * @example\n   * const assetManager = AlgorandClient.mainNet().asset;\n   */\n  public get asset() {\n    return this._assetManager\n  }\n\n  /**\n   * Methods for interacting with apps.\n   * @returns The `AppManager` instance.\n   * @example\n   * const appManager = AlgorandClient.mainNet().app;\n   */\n  public get app() {\n    return this._appManager\n  }\n\n  /**\n   * Methods for deploying apps and managing app deployment metadata.\n   * @returns The `AppDeployer` instance.\n   * @example\n   * const deployer = AlgorandClient.mainNet().appDeployer;\n   */\n  public get appDeployer() {\n    return this._appDeployer\n  }\n\n  /**\n   * Methods for interacting with the network.\n   * Provides utilities for querying blockchain state and waiting for specific conditions.\n   * @returns The `NetworkManager` instance.\n   * @example\n   * ```typescript\n   * // Get last round\n   * const lastRound = await algorand.network.getLastRound()\n   *\n   * // Wait for a specific round\n   * await algorand.network.waitUntilRound(1000n)\n   *\n   * // LocalNet-specific: block warp\n   * await algorand.network.localNet.blockWarp(100n)\n   * ```\n   */\n  public get network() {\n    return this._networkManager\n  }\n\n  /**\n   * Register a function that will be used to transform an error caught when simulating or executing\n   * composed transaction groups made from `newGroup`\n   */\n  public registerErrorTransformer(transformer: ErrorTransformer) {\n    this._errorTransformers.add(transformer)\n  }\n\n  public unregisterErrorTransformer(transformer: ErrorTransformer) {\n    this._errorTransformers.delete(transformer)\n  }\n\n  /** Start a new `TransactionComposer` transaction group\n   * @returns A new instance of `TransactionComposer`.\n   * @example\n   * {@includeCode ./algorand-client.spec.ts#example-newGroup}\n   * @see [Full working example](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/algorand-client.spec.ts)\n   */\n  public newGroup(composerConfig?: TransactionComposerConfig) {\n    return new TransactionComposer({\n      algod: this.client.algod,\n      getSigner: (addr: ReadableAddress) => this.account.getSigner(addr),\n      getSuggestedParams: () => this.getSuggestedParams(),\n      defaultValidityWindow: this._defaultValidityWindow,\n      appManager: this._appManager,\n      errorTransformers: [...this._errorTransformers],\n      composerConfig: composerConfig,\n    })\n  }\n\n  /**\n   * Methods for sending a transaction.\n   * @returns The `AlgorandClientTransactionSender` instance.\n   * @example\n   * const result = await AlgorandClient.mainNet().send.payment({\n   *  sender: \"SENDERADDRESS\",\n   *  receiver: \"RECEIVERADDRESS\",\n   *  amount: algo(1)\n   * })\n   */\n  public get send() {\n    return this._transactionSender\n  }\n\n  /**\n   * Methods for creating a transaction.\n   * @returns The `AlgorandClientTransactionCreator` instance.\n   * @example\n   * const payment = await AlgorandClient.mainNet().createTransaction.payment({\n   *  sender: \"SENDERADDRESS\",\n   *  receiver: \"RECEIVERADDRESS\",\n   *  amount: algo(1)\n   * })\n   */\n  public get createTransaction() {\n    return this._transactionCreator\n  }\n\n  // Static methods to create an `AlgorandClient`\n\n  /**\n   * Creates an `AlgorandClient` pointing at default LocalNet ports and API token.\n   * @returns An instance of the `AlgorandClient`.\n   * @example\n   * {@includeCode ./algorand-client.spec.ts#example-defaultLocalNet}\n   * @see [Full working example](https://github.com/algorandfoundation/algokit-utils-ts/blob/main/src/algorand-client.spec.ts)\n   */\n  public static defaultLocalNet() {\n    return new AlgorandClient({\n      algodConfig: ClientManager.getDefaultLocalNetConfig('algod'),\n      indexerConfig: ClientManager.getDefaultLocalNetConfig('indexer'),\n      kmdConfig: ClientManager.getDefaultLocalNetConfig('kmd'),\n    })\n  }\n\n  /**\n   * Creates an `AlgorandClient` pointing at TestNet using AlgoNode.\n   * @returns An instance of the `AlgorandClient`.\n   * @example\n   * const algorand = AlgorandClient.testNet();\n   */\n  public static testNet() {\n    return new AlgorandClient({\n      algodConfig: ClientManager.getAlgoNodeConfig('testnet', 'algod'),\n      indexerConfig: ClientManager.getAlgoNodeConfig('testnet', 'indexer'),\n      kmdConfig: undefined,\n    })\n  }\n\n  /**\n   * Creates an `AlgorandClient` pointing at MainNet using AlgoNode.\n   * @returns An instance of the `AlgorandClient`.\n   * @example\n   * const algorand = AlgorandClient.mainNet();\n   */\n  public static mainNet() {\n    return new AlgorandClient({\n      algodConfig: ClientManager.getAlgoNodeConfig('mainnet', 'algod'),\n      indexerConfig: ClientManager.getAlgoNodeConfig('mainnet', 'indexer'),\n      kmdConfig: undefined,\n    })\n  }\n\n  /**\n   * Creates an `AlgorandClient` pointing to the given client(s).\n   * @param clients The clients to use.\n   * @returns An instance of the `AlgorandClient`.\n   * @example\n   * const algorand = AlgorandClient.fromClients({ algod, indexer, kmd });\n   */\n  public static fromClients(clients: AlgoSdkClients) {\n    return new AlgorandClient(clients)\n  }\n\n  /**\n   * Creates an `AlgorandClient` loading the configuration from environment variables.\n   *\n   * Retrieve configurations from environment variables when defined or get default LocalNet configuration if they aren't defined.\n   *\n   * Expects to be called from a Node.js environment.\n   *\n   * If `process.env.ALGOD_SERVER` is defined it will use that along with optional `process.env.ALGOD_PORT` and `process.env.ALGOD_TOKEN`.\n   *\n   * If `process.env.INDEXER_SERVER` is defined it will use that along with optional `process.env.INDEXER_PORT` and `process.env.INDEXER_TOKEN`.\n   *\n   * If either aren't defined it will use the default LocalNet config.\n   *\n   * It will return a KMD configuration that uses `process.env.KMD_PORT` (or port 4002) if `process.env.ALGOD_SERVER` is defined,\n   * otherwise it will use the default LocalNet config unless it detects testnet or mainnet.\n   * @returns An instance of the `AlgorandClient`.\n   * @example\n   * const client = AlgorandClient.fromEnvironment();\n   */\n  public static fromEnvironment() {\n    return new AlgorandClient(ClientManager.getConfigFromEnvironmentOrLocalNet())\n  }\n\n  /**\n   * Creates  an `AlgorandClient` from the given config.\n   * @param config The config to use.\n   * @returns An instance of the `AlgorandClient`.\n   * @example\n   * const client = AlgorandClient.fromConfig({ algodConfig, indexerConfig, kmdConfig });\n   */\n  public static fromConfig(config: AlgoConfig) {\n    return new AlgorandClient(config)\n  }\n}\n"],"mappings":"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"}

package/amount.d.ts

@@ -1,6 +1,49 @@
-import { AlgoAmount } from "./types/amount.js";
-
 //#region src/amount.d.ts
+/** Wrapper class to ensure safe, explicit conversion between µAlgo, Algo and numbers */
+declare class AlgoAmount {
+  private amountInMicroAlgo;
+  /** Return the amount as a number in µAlgo */
+  get microAlgos(): bigint;
+  /** Return the amount as a number in µAlgo */
+  get microAlgo(): bigint;
+  /** Return the amount as a number in Algo */
+  get algos(): number;
+  /** Return the amount as a number in Algo */
+  get algo(): number;
+  /**
+   * Create a new `AlgoAmount` instance.
+   *
+   * @param amount - An object specifying the amount in Algo or µALGO. Use the key 'algo' for Algo amounts and 'microAlgo' for µALGO.
+   * @returns A new instance of `AlgoAmount` representing the specified amount.
+   * @example
+   * ```typescript
+   * const amount = new AlgoAmount({ algo: 5 });
+   * ```
+   */
+  constructor(amount: {
+    algos: number | bigint;
+  } | {
+    algo: number | bigint;
+  } | {
+    microAlgos: number | bigint;
+  } | {
+    microAlgo: number | bigint;
+  });
+  toString(): string;
+  /** valueOf allows you to use `AlgoAmount` in comparison operations such as `<` and `>=` etc.,
+   * but it's not recommended to use this to convert to a number, it's much safer to explicitly call
+   * the algos or microAlgos properties
+   */
+  valueOf(): number;
+  /** Create a `AlgoAmount` object representing the given number of Algo */
+  static Algos(amount: number | bigint): AlgoAmount;
+  /** Create a `AlgoAmount` object representing the given number of Algo */
+  static Algo(amount: number | bigint): AlgoAmount;
+  /** Create a `AlgoAmount` object representing the given number of µAlgo */
+  static MicroAlgos(amount: number | bigint): AlgoAmount;
+  /** Create a `AlgoAmount` object representing the given number of µAlgo */
+  static MicroAlgo(amount: number | bigint): AlgoAmount;
+}
 declare global {
   interface Number {
     /**
@@ -33,25 +76,37 @@ declare global {
 }
 /** Returns an amount of Algo using AlgoAmount
  * @param algos The amount of Algo
+ * @example
+ * {@includeCode ./amount.spec.ts#example-algos}
+ * @see {@link AlgoAmount}
  */
 declare const algos: (algos: number | bigint) => AlgoAmount;
 /** Returns an amount of Algo using AlgoAmount
  * @param algos The amount of Algo
+ * @example
+ * {@includeCode ./amount.spec.ts#example-algo}
  */
 declare const algo: (algos: number | bigint) => AlgoAmount;
 /** Returns an amount of µAlgo using AlgoAmount
  * @param microAlgos The amount of µAlgo
+ * @example
+ * {@includeCode ./amount.spec.ts#example-microAlgos}
+ * @see {@link algos} for Algo denomination
  */
 declare const microAlgos: (microAlgos: number | bigint) => AlgoAmount;
 /** Returns an amount of µAlgo using AlgoAmount
  * @param microAlgos The amount of µAlgo
+ * @example
+ * {@includeCode ./amount.spec.ts#example-microAlgo}
  */
 declare const microAlgo: (microAlgos: number | bigint) => AlgoAmount;
 /** Returns an amount of µAlgo to cover standard fees for the given number of transactions using AlgoAmount
  * @param numberOfTransactions The of standard transaction fees to return the amount of Algo
+ * @example
+ * {@includeCode ./amount.spec.ts#example-transactionFees}
  */
 declare const transactionFees: (numberOfTransactions: number) => AlgoAmount;
 declare const ALGORAND_MIN_TX_FEE: AlgoAmount;
 //#endregion
-export { ALGORAND_MIN_TX_FEE, algo, algos, microAlgo, microAlgos, transactionFees };
+export { ALGORAND_MIN_TX_FEE, AlgoAmount, algo, algos, microAlgo, microAlgos, transactionFees };
 //# sourceMappingURL=amount.d.ts.map

package/amount.js

@@ -1,58 +1,150 @@
-const require_amount = require('./types/amount.js');
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
 //#region src/amount.ts
+/** Wrapper class to ensure safe, explicit conversion between µAlgo, Algo and numbers */
+var AlgoAmount = class AlgoAmount {
+	amountInMicroAlgo;
+	/** Return the amount as a number in µAlgo */
+	get microAlgos() {
+		return this.amountInMicroAlgo;
+	}
+	/** Return the amount as a number in µAlgo */
+	get microAlgo() {
+		return this.amountInMicroAlgo;
+	}
+	/** Return the amount as a number in Algo */
+	get algos() {
+		return microalgosToAlgos(Number(this.amountInMicroAlgo));
+	}
+	/** Return the amount as a number in Algo */
+	get algo() {
+		return microalgosToAlgos(Number(this.amountInMicroAlgo));
+	}
+	/**
+	* Create a new `AlgoAmount` instance.
+	*
+	* @param amount - An object specifying the amount in Algo or µALGO. Use the key 'algo' for Algo amounts and 'microAlgo' for µALGO.
+	* @returns A new instance of `AlgoAmount` representing the specified amount.
+	* @example
+	* ```typescript
+	* const amount = new AlgoAmount({ algo: 5 });
+	* ```
+	*/
+	constructor(amount) {
+		this.amountInMicroAlgo = "microAlgos" in amount ? BigInt(amount.microAlgos) : "microAlgo" in amount ? BigInt(amount.microAlgo) : "algos" in amount ? BigInt(algosToMicroalgos(Number(amount.algos))) : BigInt(algosToMicroalgos(Number(amount.algo)));
+	}
+	toString() {
+		return `${this.microAlgo.toLocaleString("en-US")} µALGO`;
+	}
+	/** valueOf allows you to use `AlgoAmount` in comparison operations such as `<` and `>=` etc.,
+	* but it's not recommended to use this to convert to a number, it's much safer to explicitly call
+	* the algos or microAlgos properties
+	*/
+	valueOf() {
+		return Number(this.microAlgo);
+	}
+	/** Create a `AlgoAmount` object representing the given number of Algo */
+	static Algos(amount) {
+		return new AlgoAmount({ algos: amount });
+	}
+	/** Create a `AlgoAmount` object representing the given number of Algo */
+	static Algo(amount) {
+		return new AlgoAmount({ algos: amount });
+	}
+	/** Create a `AlgoAmount` object representing the given number of µAlgo */
+	static MicroAlgos(amount) {
+		return new AlgoAmount({ microAlgos: amount });
+	}
+	/** Create a `AlgoAmount` object representing the given number of µAlgo */
+	static MicroAlgo(amount) {
+		return new AlgoAmount({ microAlgos: amount });
+	}
+};
+const MICROALGOS_TO_ALGOS_RATIO = 1e6;
+const INVALID_MICROALGOS_ERROR_MSG = "Microalgos should be positive and less than 2^53 - 1.";
+/**
+* microalgosToAlgos converts microalgos to algos
+* @param microalgos - number
+* @returns number
+*/
+function microalgosToAlgos(microalgos) {
+	if (microalgos < 0 || !Number.isSafeInteger(microalgos)) throw new Error(INVALID_MICROALGOS_ERROR_MSG);
+	return microalgos / MICROALGOS_TO_ALGOS_RATIO;
+}
+/**
+* algosToMicroalgos converts algos to microalgos
+* @param algos - number
+* @returns number
+*/
+function algosToMicroalgos(algos) {
+	const microalgos = algos * MICROALGOS_TO_ALGOS_RATIO;
+	return Math.round(microalgos);
+}
 Number.prototype.microAlgos = function() {
-	return require_amount.AlgoAmount.MicroAlgo(this);
+	return AlgoAmount.MicroAlgo(this);
 };
 Number.prototype.algos = function() {
-	return require_amount.AlgoAmount.Algo(this);
+	return AlgoAmount.Algo(this);
 };
 Number.prototype.microAlgo = function() {
-	return require_amount.AlgoAmount.MicroAlgo(this);
+	return AlgoAmount.MicroAlgo(this);
 };
 Number.prototype.algo = function() {
-	return require_amount.AlgoAmount.Algo(this);
+	return AlgoAmount.Algo(this);
 };
 BigInt.prototype.microAlgo = function() {
-	return require_amount.AlgoAmount.MicroAlgo(this);
+	return AlgoAmount.MicroAlgo(this);
 };
 BigInt.prototype.algo = function() {
-	return require_amount.AlgoAmount.Algo(this);
+	return AlgoAmount.Algo(this);
 };
 /** Returns an amount of Algo using AlgoAmount
 * @param algos The amount of Algo
+* @example
+* {@includeCode ./amount.spec.ts#example-algos}
+* @see {@link AlgoAmount}
 */
-const algos = (algos$1) => {
-	return require_amount.AlgoAmount.Algo(algos$1);
+const algos = (algos) => {
+	return AlgoAmount.Algo(algos);
 };
 /** Returns an amount of Algo using AlgoAmount
 * @param algos The amount of Algo
+* @example
+* {@includeCode ./amount.spec.ts#example-algo}
 */
-const algo = (algos$1) => {
-	return require_amount.AlgoAmount.Algo(algos$1);
+const algo = (algos) => {
+	return AlgoAmount.Algo(algos);
 };
 /** Returns an amount of µAlgo using AlgoAmount
 * @param microAlgos The amount of µAlgo
+* @example
+* {@includeCode ./amount.spec.ts#example-microAlgos}
+* @see {@link algos} for Algo denomination
 */
-const microAlgos = (microAlgos$1) => {
-	return require_amount.AlgoAmount.MicroAlgo(microAlgos$1);
+const microAlgos = (microAlgos) => {
+	return AlgoAmount.MicroAlgo(microAlgos);
 };
 /** Returns an amount of µAlgo using AlgoAmount
 * @param microAlgos The amount of µAlgo
+* @example
+* {@includeCode ./amount.spec.ts#example-microAlgo}
 */
-const microAlgo = (microAlgos$1) => {
-	return require_amount.AlgoAmount.MicroAlgo(microAlgos$1);
+const microAlgo = (microAlgos) => {
+	return AlgoAmount.MicroAlgo(microAlgos);
 };
 /** Returns an amount of µAlgo to cover standard fees for the given number of transactions using AlgoAmount
 * @param numberOfTransactions The of standard transaction fees to return the amount of Algo
+* @example
+* {@includeCode ./amount.spec.ts#example-transactionFees}
 */
 const transactionFees = (numberOfTransactions) => {
-	return require_amount.AlgoAmount.MicroAlgo(BigInt(numberOfTransactions) * ALGORAND_MIN_TX_FEE.microAlgo);
+	return AlgoAmount.MicroAlgo(BigInt(numberOfTransactions) * ALGORAND_MIN_TX_FEE.microAlgo);
 };
-const ALGORAND_MIN_TX_FEE = require_amount.AlgoAmount.MicroAlgo(1e3);
+const ALGORAND_MIN_TX_FEE = AlgoAmount.MicroAlgo(1e3);
 
 //#endregion
 exports.ALGORAND_MIN_TX_FEE = ALGORAND_MIN_TX_FEE;
+exports.AlgoAmount = AlgoAmount;
 exports.algo = algo;
 exports.algos = algos;
 exports.microAlgo = microAlgo;