@algorandfoundation/algokit-utils 2.3.3-beta.3 → 2.3.3-beta.5

package/types/network-client.d.ts

@@ -1,20 +1,97 @@
-import type { TokenHeader } from 'algosdk/dist/types/client/urlTokenBaseHTTPClient';
-/** Config for an Algorand SDK client */
-export interface AlgoClientConfig {
-    /** Base URL of the server e.g. http://localhost, https://testnet-api.algonode.cloud/, etc. */
-    server: string;
-    /** The port to use e.g. 4001, 443, etc. */
-    port?: string | number;
-    /** The token to use for API authentication (or undefined if none needed) - can be a string, or an object with the header key => value */
-    token?: string | TokenHeader;
-}
-/** Config for an algo config */
-export interface AlgoConfig {
-    /** Algo client configuration */
-    algodConfig: AlgoClientConfig;
-    /** Indexer client configuration */
-    indexerConfig: AlgoClientConfig;
-    /** Kmd configuration */
-    kmdConfig: AlgoClientConfig;
-}
+import { Algodv2, Indexer, Kmd } from 'algosdk';
+import { AlgoClientConfig, AlgoConfig } from './types/network-client';
+/** Retrieve configurations from environment variables when defined or get defaults (expects to be called from a Node.js environment not algod-side) */
+export declare function getConfigFromEnvOrDefaults(): AlgoConfig;
+/** Retrieve the algod configuration from environment variables (expects to be called from a Node.js environment not algod-side) */
+export declare function getAlgodConfigFromEnvironment(): AlgoClientConfig;
+/** Retrieve the indexer configuration from environment variables (expects to be called from a Node.js environment not algod-side) */
+export declare function getIndexerConfigFromEnvironment(): AlgoClientConfig;
+/** Returns the Algorand configuration to point to the AlgoNode service
+ *
+ * @param network Which network to connect to - TestNet or MainNet
+ * @param config Which algod config to return - Algod or Indexer
+ */
+export declare function getAlgoNodeConfig(network: 'testnet' | 'mainnet', config: 'algod' | 'indexer'): AlgoClientConfig;
+/** Returns the Algorand configuration to point to the default LocalNet
+ *
+ * @param configOrPort Which algod config to return - algod, kmd, or indexer OR a port number
+ */
+export declare function getDefaultLocalNetConfig(configOrPort: 'algod' | 'indexer' | 'kmd' | number): AlgoClientConfig;
+/** Returns an algod SDK client that automatically retries on idempotent calls
+ *
+ * @param config The config if you want to override the default (getting config from process.env)
+ * @example Default (load from environment variables)
+ *
+ *  ```typescript
+ *  // Uses process.env.ALGOD_SERVER, process.env.ALGOD_PORT and process.env.ALGOD_TOKEN
+ *  // Automatically detects if you are using PureStake to switch in the right header name for ALGOD_TOKEN
+ *  const algod = getAlgoClient()
+ *  await algod.healthCheck().do()
+ *  ```
+ * @example AlgoNode (testnet)
+ * ```typescript
+ *  const algod = getAlgoClient(getAlgoNodeConfig('testnet', 'algod'))
+ *  await algod.healthCheck().do()
+ * ```
+ * @example AlgoNode (mainnet)
+ * ```typescript
+ *  const algod = getAlgoClient(getAlgoNodeConfig('mainnet', 'algod'))
+ *  await algod.healthCheck().do()
+ * ```
+ * @example Custom (e.g. default LocalNet, although we recommend loading this into a .env and using the Default option instead)
+ * ```typescript
+ *  const algod = getAlgoClient({server: 'http://localhost', port: '4001', token: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'})
+ *  await algod.healthCheck().do()
+ * ```
+ */
+export declare function getAlgoClient(config?: AlgoClientConfig): Algodv2;
+/** Returns an indexer SDK client that automatically retries on idempotent calls
+ *
+ * @param config The config if you want to override the default (getting config from process.env)
+ * @example Default (load from environment variables)
+ *
+ *  ```typescript
+ *  // Uses process.env.INDEXER_SERVER, process.env.INDEXER_PORT and process.env.INDEXER_TOKEN
+ *  // Automatically detects if you are using PureStake to switch in the right header name for INDEXER_TOKEN
+ *  const indexer = getAlgoIndexerClient()
+ *  await indexer.makeHealthCheck().do()
+ *  ```
+ * @example AlgoNode (testnet)
+ * ```typescript
+ *  const indexer = getAlgoIndexerClient(getAlgoNodeConfig('testnet', 'indexer'))
+ *  await indexer.makeHealthCheck().do()
+ * ```
+ * @example AlgoNode (mainnet)
+ * ```typescript
+ *  const indexer = getAlgoIndexerClient(getAlgoNodeConfig('mainnet', 'indexer'))
+ *  await indexer.makeHealthCheck().do()
+ * ```
+ * @example Custom (e.g. default LocalNet, although we recommend loading this into a .env and using the Default option instead)
+ * ```typescript
+ *  const indexer = getAlgoIndexerClient({server: 'http://localhost', port: '8980', token: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'})
+ *  await indexer.makeHealthCheck().do()
+ * ```
+ */
+export declare function getAlgoIndexerClient(config?: AlgoClientConfig): Indexer;
+/**
+ * Returns a KMD SDK client that automatically retries on idempotent calls
+ *
+ * KMD client allows you to export private keys, which is useful to get the default account in a LocalNet network.
+ *
+ * @param config The config if you want to override the default (getting config from process.env)
+ * @example Default (load from environment variables)
+ *
+ *  ```typescript
+ *  // Uses process.env.ALGOD_SERVER, process.env.KMD_PORT (or if not specified: port 4002) and process.env.ALGOD_TOKEN
+ *  const kmd = getAlgoKmdClient()
+ *  ```
+ * @example Custom (e.g. default LocalNet, although we recommend loading this into a .env and using the Default option instead)
+ * ```typescript
+ *  const kmd = getAlgoKmdClient({server: 'http://localhost', port: '4002', token: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa'})
+ * ```
+ */
+export declare function getAlgoKmdClient(config?: AlgoClientConfig): Kmd;
+export declare function isTestNet(algod: Algodv2): Promise<boolean>;
+export declare function isMainNet(algod: Algodv2): Promise<boolean>;
+export { isLocalNet } from './localnet';
 //# sourceMappingURL=network-client.d.ts.map

package/types/network-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"network-client.d.ts","sourceRoot":"","sources":["../../src/types/network-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kDAAkD,CAAA;AAEnF,wCAAwC;AACxC,MAAM,WAAW,gBAAgB;IAC/B,8FAA8F;IAC9F,MAAM,EAAE,MAAM,CAAA;IACd,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IACtB,yIAAyI;IACzI,KAAK,CAAC,EAAE,MAAM,GAAG,WAAW,CAAA;CAC7B;AAED,gCAAgC;AAChC,MAAM,WAAW,UAAU;IACzB,gCAAgC;IAChC,WAAW,EAAE,gBAAgB,CAAA;IAC7B,mCAAmC;IACnC,aAAa,EAAE,gBAAgB,CAAA;IAC/B,wBAAwB;IACxB,SAAS,EAAE,gBAAgB,CAAA;CAC5B"}
+{"version":3,"file":"network-client.d.ts","sourceRoot":"","sources":["../../src/network-client.ts"],"names":[],"mappings":"AAAA,OAAgB,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,SAAS,CAAA;AAGxD,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AAErE,uJAAuJ;AACvJ,wBAAgB,0BAA0B,IAAI,UAAU,CAwBvD;AAED,mIAAmI;AACnI,wBAAgB,6BAA6B,IAAI,gBAAgB,CAchE;AAED,qIAAqI;AACrI,wBAAgB,+BAA+B,IAAI,gBAAgB,CAclE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,EAAE,MAAM,EAAE,OAAO,GAAG,SAAS,GAAG,gBAAgB,CAK/G;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,YAAY,EAAE,OAAO,GAAG,SAAS,GAAG,KAAK,GAAG,MAAM,GAAG,gBAAgB,CAM7G;AAUD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAIhE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAIvE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,GAAG,CAK/D;AAED,wBAAsB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAGhE;AACD,wBAAsB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAGhE;AAED,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA"}

package/types/testing/account.d.ts

@@ -0,0 +1,14 @@
+import { Account, Algodv2, Kmd } from 'algosdk';
+import { GetTestAccountParams } from '../types/testing';
+/**
+ * Creates an ephemeral Algorand account for the purposes of testing.
+ * Returns a newly created random test account that is funded from the dispenser
+ * DO NOT USE THIS TO CREATE A MAINNET ACCOUNT!
+ * Note: By default this will log the mnemonic of the account.
+ * @param param0 The config for the test account to generate
+ * @param algod An algod client
+ * @param kmd A KMD client, if not specified then a default KMD client will be loaded from environment variables
+ * @returns The account, with private key loaded
+ */
+export declare function getTestAccount({ suppressLog, initialFunds }: GetTestAccountParams, algod: Algodv2, kmd?: Kmd): Promise<Account>;
+//# sourceMappingURL=account.d.ts.map

package/types/testing/account.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"account.d.ts","sourceRoot":"","sources":["../../../src/testing/account.ts"],"names":[],"mappings":"AAAA,OAAgB,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,SAAS,CAAA;AAIxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AAEvD;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,EAAE,WAAW,EAAE,YAAY,EAAE,EAAE,oBAAoB,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,OAAO,CAAC,CAgBrI"}

package/types/testing/fixtures/algokit-log-capture-fixture.d.ts

@@ -0,0 +1,19 @@
+import { AlgoKitLogCaptureFixture } from '../../types/testing';
+/**
+ * Creates a test fixture for capturing AlgoKit logs.
+ *
+ * @example ```typescript
+ * const logs = algoKitLogCaptureFixture()
+ *
+ * beforeEach(logs.beforeEach)
+ * afterEach(logs.afterEach)
+ *
+ * test('My test', () => {
+ *     const capturedLogs = logs.testLogger.capturedLogs
+ * })
+ * ```
+ *
+ * @returns The fixture
+ */
+export declare const algoKitLogCaptureFixture: () => AlgoKitLogCaptureFixture;
+//# sourceMappingURL=algokit-log-capture-fixture.d.ts.map

package/types/testing/fixtures/algokit-log-capture-fixture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"algokit-log-capture-fixture.d.ts","sourceRoot":"","sources":["../../../../src/testing/fixtures/algokit-log-capture-fixture.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAA;AAG9D;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,wBAAwB,EAAE,MAAM,wBAqB5C,CAAA"}

package/types/testing/fixtures/algorand-fixture.d.ts

@@ -0,0 +1,48 @@
+import { AlgoConfig } from '../../types/network-client';
+import { AlgorandFixture, AlgorandFixtureConfig } from '../../types/testing';
+/**
+ * Creates a test fixture for automated testing against Algorand.
+ * By default it tests against an environment variable specified client
+ *  if the standard environment variables are specified, otherwise against
+ *  a default LocalNet instance, but you can pass in an algod, indexer
+ *  and/or kmd if you want to test against an explicitly defined network.
+ *
+ * @example ```typescript
+ * const algorand = algorandFixture()
+ *
+ * beforeEach(algorand.beforeEach, 10_000)
+ *
+ * test('My test', async () => {
+ *     const {algod, indexer, testAccount, ...} = algorand.context
+ *     // test things...
+ * })
+ * ```
+ *
+ * @param fixtureConfig The fixture configuration
+ * @returns The fixture
+ */
+export declare function algorandFixture(fixtureConfig?: AlgorandFixtureConfig): AlgorandFixture;
+/**
+ * Creates a test fixture for automated testing against Algorand.
+ * By default it tests against an environment variable specified client
+ *  if the standard environment variables are specified, otherwise against
+ *  a default LocalNet instance, but you can pass in an algod, indexer
+ *  and/or kmd if you want to test against an explicitly defined network.
+ *
+ * @example ```typescript
+ * const algorand = algorandFixture(undefined, getConfigFromEnvOrDefaults())
+ *
+ * beforeEach(algorand.beforeEach, 10_000)
+ *
+ * test('My test', async () => {
+ *     const {algod, indexer, testAccount, ...} = algorand.context
+ *     // test things...
+ * })
+ * ```
+ *
+ * @param fixtureConfig The fixture configuration
+ * @param config The algo configuration
+ * @returns The fixture
+ */
+export declare function algorandFixture(fixtureConfig: AlgorandFixtureConfig | undefined, config: AlgoConfig): AlgorandFixture;
+//# sourceMappingURL=algorand-fixture.d.ts.map

package/types/testing/fixtures/algorand-fixture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"algorand-fixture.d.ts","sourceRoot":"","sources":["../../../../src/testing/fixtures/algorand-fixture.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAA;AACvD,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAuD,MAAM,qBAAqB,CAAA;AAEjI;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAAC,aAAa,CAAC,EAAE,qBAAqB,GAAG,eAAe,CAAA;AAEvF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,eAAe,CAAC,aAAa,EAAE,qBAAqB,GAAG,SAAS,EAAE,MAAM,EAAE,UAAU,GAAG,eAAe,CAAA"}

package/types/testing/fixtures/index.d.ts

@@ -0,0 +1,3 @@
+export * from './algokit-log-capture-fixture';
+export * from './algorand-fixture';
+//# sourceMappingURL=index.d.ts.map

package/types/testing/fixtures/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/testing/fixtures/index.ts"],"names":[],"mappings":"AAAA,cAAc,+BAA+B,CAAA;AAC7C,cAAc,oBAAoB,CAAA"}

package/types/testing/index.d.ts

@@ -0,0 +1,6 @@
+export * from './account';
+export * from './fixtures';
+export * from './indexer';
+export * from './test-logger';
+export * from './transaction-logger';
+//# sourceMappingURL=index.d.ts.map

package/types/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/testing/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,sBAAsB,CAAA"}

package/types/testing/indexer.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Runs the given indexer call until a 404 error is no longer returned.
+ * Tried every 200ms up to 20 times.
+ * Very rudimentary implementation designed for automated testing.
+ * @example ```typescript
+ * const transaction = await runWhenIndexerCaughtUp(() => indexer.lookupTransactionByID(txnId).do())
+ * ```
+ * @param run The code to run
+ * @returns The result (as a promise), or throws if the indexer didn't catch up in time
+ */
+export declare function runWhenIndexerCaughtUp<T>(run: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=indexer.d.ts.map

package/types/testing/indexer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexer.d.ts","sourceRoot":"","sources":["../../../src/testing/indexer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAuBjF"}

package/types/testing/test-logger.d.ts

@@ -0,0 +1,41 @@
+import { Logger } from '../types/logging';
+import { LogSnapshotConfig } from '../types/testing';
+/** Exposes an AlgoKit logger which captures log messages, while wrapping an original logger.
+ * This is useful for automated testing.
+ */
+export declare class TestLogger implements Logger {
+    private originalLogger;
+    private logs;
+    /**
+     * Create a new test logger that wraps the given logger if provided.
+     * @param originalLogger The optional original logger to wrap.
+     */
+    constructor(originalLogger?: Logger);
+    /** Returns all logs captured thus far. */
+    get capturedLogs(): string[];
+    /** Clears all logs captured so far. */
+    clear(): void;
+    /**
+     * Returns a captured log snapshot.
+     * This helps ensure that the provided configuration items won't appear
+     *  with random values in the log snapshot, but rather will get substituted with predictable ids.
+     *
+     * https://jestjs.io/docs/snapshot-testing#2-tests-should-be-deterministic
+     *
+     * @example Jest Example
+     * ```typescript
+     * const logger = new TestLogger()
+     * ...
+     * expect(logger.getLogSnapshot()).toMatchSnapshot()
+     * ```
+     * @param config The snapshot configuration
+     * @returns The snapshotted logs.
+     */
+    getLogSnapshot(config?: LogSnapshotConfig): string;
+    error(message: string, ...optionalParams: unknown[]): void;
+    warn(message: string, ...optionalParams: unknown[]): void;
+    info(message: string, ...optionalParams: unknown[]): void;
+    verbose(message: string, ...optionalParams: unknown[]): void;
+    debug(message: string, ...optionalParams: unknown[]): void;
+}
+//# sourceMappingURL=test-logger.d.ts.map

package/types/testing/test-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test-logger.d.ts","sourceRoot":"","sources":["../../../src/testing/test-logger.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AACzC,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAEpD;;GAEG;AACH,qBAAa,UAAW,YAAW,MAAM;IACvC,OAAO,CAAC,cAAc,CAAoB;IAC1C,OAAO,CAAC,IAAI,CAAU;IAEtB;;;OAGG;gBACS,cAAc,CAAC,EAAE,MAAM;IAKnC,0CAA0C;IAC1C,IAAI,YAAY,IAAI,MAAM,EAAE,CAE3B;IAED,uCAAuC;IACvC,KAAK;IAIL;;;;;;;;;;;;;;;OAeG;IACH,cAAc,CAAC,MAAM,CAAC,EAAE,iBAAiB;IAczC,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,cAAc,EAAE,OAAO,EAAE,GAAG,IAAI;IAI1D,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,cAAc,EAAE,OAAO,EAAE,GAAG,IAAI;IAIzD,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,cAAc,EAAE,OAAO,EAAE,GAAG,IAAI;IAIzD,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,cAAc,EAAE,OAAO,EAAE,GAAG,IAAI;IAI5D,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,cAAc,EAAE,OAAO,EAAE,GAAG,IAAI;CAI3D"}

package/types/testing/transaction-logger.d.ts

@@ -0,0 +1,29 @@
+import { Algodv2, Indexer } from 'algosdk';
+/**
+ * Allows you to keep track of Algorand transaction IDs by wrapping an `Algodv2` in a proxy.
+ * Useful for automated tests.
+ */
+export declare class TransactionLogger {
+    private _sentTransactionIds;
+    /**
+     * The list of transaction IDs that has been logged thus far.
+     */
+    get sentTransactionIds(): Readonly<string[]>;
+    /**
+     * Clear all logged IDs.
+     */
+    clear(): void;
+    /**
+     * The method that captures raw transactions and stores the transaction IDs.
+     */
+    logRawTransaction(signedTransactions: Uint8Array | Uint8Array[]): void;
+    /** Return a proxy that wraps the given Algodv2 with this transaction logger.
+     *
+     * @param algod The `Algodv2` to wrap
+     * @returns The wrapped `Algodv2`, any transactions sent using this algod instance will be logged by this transaction logger
+     */
+    capture(algod: Algodv2): Algodv2;
+    /** Wait until all logged transactions IDs appear in the given `Indexer`. */
+    waitForIndexer(indexer: Indexer): Promise<void>;
+}
+//# sourceMappingURL=transaction-logger.d.ts.map

package/types/testing/transaction-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction-logger.d.ts","sourceRoot":"","sources":["../../../src/testing/transaction-logger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAA2B,OAAO,EAAE,MAAM,SAAS,CAAA;AAGnE;;;GAGG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,mBAAmB,CAAe;IAE1C;;OAEG;IACH,IAAI,kBAAkB,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC,CAE3C;IAED;;OAEG;IACH,KAAK;IAIL;;OAEG;IACH,iBAAiB,CAAC,kBAAkB,EAAE,UAAU,GAAG,UAAU,EAAE;IAY/D;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;IAIhC,4EAA4E;IACtE,cAAc,CAAC,OAAO,EAAE,OAAO;CAGtC"}

package/types/transaction.d.ts

@@ -1,111 +1,138 @@
-import { Account, AtomicTransactionComposer, LogicSigAccount, Transaction, modelsv2 } from 'algosdk';
-import { MultisigAccount, SigningAccount, TransactionSignerAccount } from './account';
-import { AlgoAmount } from './amount';
-import { ABIReturn } from './app';
-export type TransactionNote = Uint8Array | TransactionNoteData | Arc2TransactionNote;
-export type TransactionNoteData = string | null | undefined | number | any[] | Record<string, any>;
-/** ARC-0002 compatible transaction note components https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0002.md */
-export type Arc2TransactionNote = {
-    dAppName: string;
-    format: 'm' | 'b' | 'u';
-    data: string;
-} | {
-    dAppName: string;
-    format: 'j';
-    data: TransactionNoteData;
-};
-/** The sending configuration for a transaction */
-export interface SendTransactionParams {
-    /** Whether to skip signing and sending the transaction to the chain (default: transaction signed and sent to chain, unless `atc` specified)
-     * and instead just return the raw transaction, e.g. so you can add it to a group of transactions */
-    skipSending?: boolean;
-    /** Whether to skip waiting for the submitted transaction (only relevant if `skipSending` is `false` or unset) */
-    skipWaiting?: boolean;
-    /** An optional `AtomicTransactionComposer` to add the transaction to, if specified then `skipSending: undefined` has the same effect as `skipSending: true` */
-    atc?: AtomicTransactionComposer;
-    /** Whether to suppress log messages from transaction send, default: do not suppress */
-    suppressLog?: boolean;
-    /** The flat fee you want to pay, useful for covering extra fees in a transaction group or app call */
-    fee?: AlgoAmount;
-    /** The maximum fee that you are happy to pay (default: unbounded) - if this is set it's possible the transaction could get rejected during network congestion */
-    maxFee?: AlgoAmount;
-    /** The maximum number of rounds to wait for confirmation, only applies if `skipWaiting` is `undefined` or `false`, default: wait up to 5 rounds */
-    maxRoundsToWaitForConfirmation?: number;
-}
-/** The result of sending a transaction */
-export interface SendTransactionResult {
-    /** The transaction */
-    transaction: Transaction;
-    /** The response if the transaction was sent and waited for */
-    confirmation?: modelsv2.PendingTransactionResponse;
-}
-/** The result of preparing and/or sending multiple transactions */
-export interface SendTransactionResults {
-    /** The transactions that have been prepared and/or sent */
-    transactions: Transaction[];
-    /** The responses if the transactions were sent and waited for,
-     * the index of the confirmation will match the index of the underlying transaction
-     */
-    confirmations?: modelsv2.PendingTransactionResponse[];
-}
-/** The result of preparing and/or sending multiple transactions using an `AtomicTransactionComposer` */
-export interface SendAtomicTransactionComposerResults extends SendTransactionResults {
-    /** base64 encoded representation of the group ID of the atomic group */
-    groupId: string;
-    /** The transaction IDs that have been prepared and/or sent */
-    txIds: string[];
-    /** If ABI method(s) were called the processed return values */
-    returns?: ABIReturn[];
-}
-/** The result of sending and confirming a transaction */
-export interface ConfirmedTransactionResult extends SendTransactionResult {
-    /** The response from sending and waiting for the transaction */
-    confirmation: modelsv2.PendingTransactionResponse;
-}
-/** The result of sending and confirming one or more transactions, but where there is a primary transaction of interest */
-export interface ConfirmedTransactionResults extends SendTransactionResult, SendTransactionResults {
-    /** The response from sending and waiting for the primary transaction */
-    confirmation: modelsv2.PendingTransactionResponse;
-    /** The response from sending and waiting for the transactions */
-    confirmations: modelsv2.PendingTransactionResponse[];
-}
-/** Core account abstraction when signing/sending transactions
+import algosdk, { Algodv2, AtomicTransactionComposer, modelsv2, SuggestedParams, Transaction, TransactionWithSigner } from 'algosdk';
+import { AlgoAmount } from './types/amount';
+import { AtomicTransactionComposerToSend, SendAtomicTransactionComposerResults, SendTransactionFrom, SendTransactionParams, SendTransactionResult, TransactionGroupToSend, TransactionNote, TransactionToSign } from './types/transaction';
+/** Encodes a transaction note into a byte array ready to be included in an Algorand transaction.
+ *
+ * @param note The transaction note
+ * @returns the transaction note ready for inclusion in a transaction
+ *
+ *  Case on the value of `data` this either be:
+ *   * `null` | `undefined`: `undefined`
+ *   * `string`: The string value
+ *   * Uint8Array: passthrough
+ *   * Arc2TransactionNote object: ARC-0002 compatible transaction note
+ *   * Else: The object/value converted into a JSON string representation
+ */
+export declare function encodeTransactionNote(note?: TransactionNote): Uint8Array | undefined;
+/**
+ * Returns the public address of the given transaction sender.
+ * @param sender A transaction sender
+ * @returns The public address
+ */
+export declare const getSenderAddress: (sender: SendTransactionFrom) => string;
+/**
+ * Given a transaction in a variety of supported formats, returns a TransactionWithSigner object ready to be passed to an
+ * AtomicTransactionComposer's addTransaction method.
+ * @param transaction One of: A TransactionWithSigner object (returned as is), a TransactionToSign object (signer is obtained from the
+ * signer property), a Transaction object (signer is extracted from the defaultSender parameter), an async SendTransactionResult returned by
+ * one of algokit utils' helpers (signer is obtained from the defaultSender parameter)
+ * @param defaultSender The default sender to be used to obtain a signer where the object provided to the transaction parameter does not
+ * include a signer.
+ * @returns A TransactionWithSigner object.
+ */
+export declare const getTransactionWithSigner: (transaction: TransactionWithSigner | TransactionToSign | Transaction | Promise<SendTransactionResult>, defaultSender?: SendTransactionFrom) => Promise<TransactionWithSigner>;
+/**
+ * Returns a `TransactionSigner` for the given transaction sender.
+ * This function has memoization, so will return the same transaction signer for a given sender.
+ * @param sender A transaction sender
+ * @returns A transaction signer
+ */
+export declare const getSenderTransactionSigner: (val: SendTransactionFrom) => algosdk.TransactionSigner;
+/**
+ * Signs a single transaction by the given signer.
+ * @param transaction The transaction to sign
+ * @param signer The signer to sign
+ * @returns The signed transaction as a `Uint8Array`
+ */
+export declare const signTransaction: (transaction: Transaction, signer: SendTransactionFrom) => Promise<Uint8Array>;
+/** Prepares a transaction for sending and then (if instructed) signs and sends the given transaction to the chain.
+ *
+ * @param send The details for the transaction to prepare/send, including:
+ *   * `transaction`: The unsigned transaction
+ *   * `from`: The account to sign the transaction with: either an account with private key loaded or a logic signature account
+ *   * `config`: The sending configuration for this transaction
+ * @param algod An algod client
  *
- * This type is used across the entire AlgoKit Utils library and allows you to pass through
- * many types of accounts, including:
- * * `Account` - The in-built `algosdk.Account` type for mnemonic accounts
- * * `SigningAccount` - An AlgoKit Utils class that wraps Account to provide support for rekeyed accounts
- * * `LogicSigAccount` - The in-built `algosdk.LogicSigAccount` type for logic signatures
- * * `MultisigAccount` - An AlgoKit Utils class that wraps a multisig account and provides mechanisms to get a multisig account
- * * `TransactionSignerAccount` - An AlgoKitUtils class that wraps the in-built `algosdk.TransactionSigner` along with the sender address
+ * @returns An object with transaction (`transaction`) and (if `skipWaiting` is `false` or `undefined`) confirmation (`confirmation`)
  */
-export type SendTransactionFrom = Account | SigningAccount | LogicSigAccount | MultisigAccount | TransactionSignerAccount;
-/** Defines an unsigned transaction that will appear in a group of transactions along with its signing information */
-export interface TransactionToSign {
-    /** The unsigned transaction to sign and send */
+export declare const sendTransaction: (send: {
     transaction: Transaction;
-    /** The account to use to sign the transaction, either an account (with private key loaded) or a logic signature account */
-    signer: SendTransactionFrom;
-}
-/** A group of transactions to send together as an atomic group
- * https://developer.algorand.org/docs/get-details/atomic_transfers/
+    from: SendTransactionFrom;
+    sendParams?: SendTransactionParams;
+}, algod: Algodv2) => Promise<SendTransactionResult>;
+/**
+ * Signs and sends transactions that have been collected by an `AtomicTransactionComposer`.
+ * @param atcSend The parameters controlling the send, including:
+ *  * `atc` The `AtomicTransactionComposer`
+ *  * `sendParams` The parameters to control the send behaviour
+ * @param algod An algod client
+ * @returns An object with transaction IDs, transactions, group transaction ID (`groupTransactionId`) if more than 1 transaction sent, and (if `skipWaiting` is `false` or unset) confirmation (`confirmation`)
+ */
+export declare const sendAtomicTransactionComposer: (atcSend: AtomicTransactionComposerToSend, algod: Algodv2) => Promise<SendAtomicTransactionComposerResults>;
+/**
+ * Performs a dry run of the transactions loaded into the given AtomicTransactionComposer`
+ * @param atc The AtomicTransactionComposer` with transaction(s) loaded
+ * @param algod An Algod client
+ * @returns The dryrun result
+ */
+export declare function performAtomicTransactionComposerDryrun(atc: AtomicTransactionComposer, algod: Algodv2): Promise<algosdk.DryrunResult>;
+/**
+ * Signs and sends a group of [up to 16](https://developer.algorand.org/docs/get-details/atomic_transfers/#create-transactions) transactions to the chain
+ *
+ * @param groupSend The group details to send, with:
+ *   * `transactions`: The array of transactions to send along with their signing account
+ *   * `sendParams`: The parameters to dictate how the group is sent
+ * @param algod An algod client
+ * @returns An object with transaction IDs, transactions, group transaction ID (`groupTransactionId`) if more than 1 transaction sent, and (if `skipWaiting` is `false` or unset) confirmation (`confirmation`)
+ */
+export declare const sendGroupOfTransactions: (groupSend: TransactionGroupToSend, algod: Algodv2) => Promise<Omit<SendAtomicTransactionComposerResults, "returns">>;
+/**
+ * Wait until the transaction is confirmed or rejected, or until `timeout`
+ * number of rounds have passed.
+ *
+ * @param algod An algod client
+ * @param transactionId The transaction ID to wait for
+ * @param maxRoundsToWait Maximum number of rounds to wait
+ *
+ * @return Pending transaction information
+ * @throws Throws an error if the transaction is not confirmed or rejected in the next `timeout` rounds
+ */
+export declare const waitForConfirmation: (transactionId: string, maxRoundsToWait: number | bigint, algod: Algodv2) => Promise<modelsv2.PendingTransactionResponse>;
+/**
+ * Limit the acceptable fee to a defined amount of µALGOs.
+ * This also sets the transaction to be flatFee to ensure the transaction only succeeds at
+ * the estimated rate.
+ * @param transaction The transaction to cap or suggested params object about to be used to create a transaction
+ * @param maxAcceptableFee The maximum acceptable fee to pay
+ */
+export declare function capTransactionFee(transaction: algosdk.Transaction | SuggestedParams, maxAcceptableFee: AlgoAmount): void;
+/**
+ * Allows for control of fees on a `Transaction` or `SuggestedParams` object
+ * @param transaction The transaction or suggested params
+ * @param feeControl The fee control parameters
+ */
+export declare function controlFees<T extends SuggestedParams | Transaction>(transaction: T, feeControl: {
+    fee?: AlgoAmount;
+    maxFee?: AlgoAmount;
+}): T;
+/**
+ * Returns suggested transaction parameters from algod unless some are already provided.
+ * @param params Optionally provide parameters to use
+ * @param algod Algod algod
+ * @returns The suggested transaction parameters
+ */
+export declare function getTransactionParams(params: SuggestedParams | undefined, algod: Algodv2): Promise<import("algosdk/dist/types/types/transactions/base").SuggestedParamsWithMinFee | {
+    flatFee?: boolean | undefined;
+    fee: number;
+    firstRound: number;
+    lastRound: number;
+    genesisID: string;
+    genesisHash: string;
+}>;
+/**
+ * Returns the array of transactions currently present in the given `AtomicTransactionComposer`
+ * @param atc The atomic transaction composer
+ * @returns The array of transactions with signers
  */
-export interface TransactionGroupToSend {
-    /** Any parameters to control the semantics of the send to the network */
-    sendParams?: Omit<SendTransactionParams, 'fee' | 'maxFee' | 'skipSending' | 'atc'>;
-    /** The list of transactions to send, which can either be a raw transaction (in which case `signer` is required),
-     *   the async result of an AlgoKit utils method that returns a `SendTransactionResult` (saves unwrapping the promise, be sure to pass `skipSending: true`, `signer` is also required)
-     *   or the transaction with its signer (`signer` is ignored)
-     **/
-    transactions: (TransactionToSign | Transaction | Promise<SendTransactionResult>)[];
-    /** Optional signer to pass in, required if at least one transaction provided is just the transaction, ignored otherwise */
-    signer?: SendTransactionFrom;
-}
-/** An `AtomicTransactionComposer` with transactions to send. */
-export interface AtomicTransactionComposerToSend {
-    /** The `AtomicTransactionComposer` with transactions loaded to send */
-    atc: AtomicTransactionComposer;
-    /** Any parameters to control the semantics of the send to the network */
-    sendParams?: Omit<SendTransactionParams, 'fee' | 'maxFee' | 'skipSending' | 'atc'>;
-}
+export declare function getAtomicTransactionComposerTransactions(atc: AtomicTransactionComposer): algosdk.TransactionWithSigner[];
 //# sourceMappingURL=transaction.d.ts.map

package/types/transaction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../../src/types/transaction.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../../src/transaction.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,EAAE,EACd,OAAO,EACP,yBAAyB,EACzB,QAAQ,EACR,eAAe,EACf,WAAW,EAEX,qBAAqB,EACtB,MAAM,SAAS,CAAA;AAGhB,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAE3C,OAAO,EACL,+BAA+B,EAC/B,oCAAoC,EACpC,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,EACtB,eAAe,EACf,iBAAiB,EAClB,MAAM,qBAAqB,CAAA;AAG5B;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,CAAC,EAAE,eAAe,GAAG,UAAU,GAAG,SAAS,CAcpF;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,WAAqB,mBAAmB,WAEpE,CAAA;AAWD;;;;;;;;;GASG;AACH,eAAO,MAAM,wBAAwB,gBACtB,qBAAqB,GAAG,iBAAiB,GAAG,WAAW,GAAG,QAAQ,qBAAqB,CAAC,kBACrF,mBAAmB,KAClC,QAAQ,qBAAqB,CAkB/B,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,yDAMrC,CAAA;AAEF;;;;;GAKG;AACH,eAAO,MAAM,eAAe,gBAAuB,WAAW,UAAU,mBAAmB,wBAQ1F,CAAA;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe,SACpB;IACJ,WAAW,EAAE,WAAW,CAAA;IACxB,IAAI,EAAE,mBAAmB,CAAA;IACzB,UAAU,CAAC,EAAE,qBAAqB,CAAA;CACnC,SACM,OAAO,KACb,QAAQ,qBAAqB,CA2B/B,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,6BAA6B,YAA4B,+BAA+B,SAAS,OAAO,kDAgFpH,CAAA;AAED;;;;;GAKG;AACH,wBAAsB,sCAAsC,CAAC,GAAG,EAAE,yBAAyB,EAAE,KAAK,EAAE,OAAO,iCAO1G;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,cAA8B,sBAAsB,SAAS,OAAO,mEAgCvG,CAAA;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,kBACf,MAAM,mBACJ,MAAM,GAAG,MAAM,SACzB,OAAO,KACb,QAAQ,SAAS,0BAA0B,CA4C7C,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,OAAO,CAAC,WAAW,GAAG,eAAe,EAAE,gBAAgB,EAAE,UAAU,QAgBjH;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,eAAe,GAAG,WAAW,EACjE,WAAW,EAAE,CAAC,EACd,UAAU,EAAE;IAAE,GAAG,CAAC,EAAE,UAAU,CAAC;IAAC,MAAM,CAAC,EAAE,UAAU,CAAA;CAAE,KAatD;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CAAC,MAAM,EAAE,eAAe,GAAG,SAAS,EAAE,KAAK,EAAE,OAAO;;;;;;;GAE7F;AAED;;;;GAIG;AACH,wBAAgB,wCAAwC,CAAC,GAAG,EAAE,yBAAyB,mCAMtF"}