@algorandfoundation/algokit-utils 7.0.0-beta.8 → 7.0.0

package/types/composer.d.ts

@@ -11,7 +11,10 @@ import SimulateResponse = algosdk.modelsv2.SimulateResponse;
 import modelsv2 = algosdk.modelsv2;
 export declare const MAX_TRANSACTION_GROUP_SIZE = 16;
 /** Options to control a simulate request */
-export type SimulateOptions = Expand<Omit<ConstructorParameters<typeof modelsv2.SimulateRequest>[0], 'txnGroups'>>;
+export type SimulateOptions = Expand<Omit<ConstructorParameters<typeof modelsv2.SimulateRequest>[0], 'txnGroups'>> & {
+    /** Whether or not to skip signatures for all built transactions and use an empty signer instead. */
+    skipSignatures?: boolean;
+};
 /** Common parameters for defining a transaction. */
 export type CommonTransactionParams = {
     /** The address of the account sending the transaction. */
@@ -284,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. */
@@ -368,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';
@@ -389,7 +398,7 @@ export type Txn = (PaymentParams & {
     type: 'assetOptOut';
 }) | ((AppCallParams | AppCreateParams | AppUpdateParams) & {
     type: 'appCall';
-}) | (OnlineKeyRegistrationParams & {
+}) | ((OnlineKeyRegistrationParams | OfflineKeyRegistrationParams) & {
     type: 'keyReg';
 }) | (algosdk.TransactionWithSigner & {
     type: 'txnWithSigner';
@@ -399,8 +408,8 @@ 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 */
@@ -417,7 +426,7 @@ export type AlgoKitComposerParams = {
      */
     appManager?: AppManager;
 };
-/** Set of transactions built by `AlgoKitComposer`. */
+/** Set of transactions built by `TransactionComposer`. */
 export interface BuiltTransactions {
     /** The built transactions */
     transactions: algosdk.Transaction[];
@@ -426,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 */
@@ -448,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.
      *
@@ -514,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.
      *
@@ -522,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.
      *
@@ -530,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.
      *
@@ -540,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.
      *
@@ -578,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;

package/types/composer.js

@@ -1,24 +1,22 @@
 'use strict';
 
-Object.defineProperty(exports, '__esModule', { value: true });
-
 var algosdk = require('algosdk');
 var config = require('../config.js');
-var performAtomicTransactionComposerSimulate = require('../transaction/perform-atomic-transaction-composer-simulate.js');
 var transaction = require('../transaction/transaction.js');
 var types_app = require('./app.js');
 var types_appManager = require('./app-manager.js');
-var types_asyncEventEmitter = require('./async-event-emitter.js');
+var types_lifecycleEvents = require('./lifecycle-events.js');
 var types_networkClient = require('./network-client.js');
 
+var AtomicTransactionComposer = algosdk.AtomicTransactionComposer;
 var isTransactionWithSigner = algosdk.isTransactionWithSigner;
 var encodeAddress = algosdk.encodeAddress;
 var modelsv2 = algosdk.modelsv2;
 const MAX_TRANSACTION_GROUP_SIZE = 16;
-/** AlgoKit Composer helps you compose and execute transactions as a transaction group. */
-class AlgoKitComposer {
+/** TransactionComposer helps you compose and execute transactions as a transaction group. */
+class TransactionComposer {
     /**
-     * Create an `AlgoKitComposer`.
+     * Create a `TransactionComposer`.
      * @param params The configuration for this composer
      */
     constructor(params) {
@@ -225,6 +223,15 @@ class AlgoKitComposer {
         this.txns.push({ ...params, type: 'keyReg' });
         return this;
     }
+    /**
+     * 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) {
+        this.txns.push({ ...params, type: 'keyReg' });
+        return this;
+    }
     /**
      * Add the transactions within an `AtomicTransactionComposer` to the transaction group.
      * @param atc The `AtomicTransactionComposer` to build transactions from and add to the group
@@ -238,7 +245,7 @@ class AlgoKitComposer {
     buildAtc(atc, processTransaction) {
         const group = atc.buildGroup();
         const txnWithSigners = group.map((ts, idx) => {
-            // Remove underlying group ID from the transaction since it will be re-grouped when this AlgoKitComposer is built
+            // Remove underlying group ID from the transaction since it will be re-grouped when this TransactionComposer is built
             ts.txn.group = undefined;
             // Process transaction if a function is provided
             ts.txn = processTransaction?.(ts.txn, idx) ?? ts.txn;
@@ -295,14 +302,22 @@ class AlgoKitComposer {
      */
     async buildMethodCall(params, suggestedParams, includeSigner) {
         const methodArgs = [];
+        const transactionsForGroup = [];
         const isAbiValue = (x) => {
             if (Array.isArray(x))
                 return x.length == 0 || x.every(isAbiValue);
             return typeof x === 'bigint' || typeof x === 'boolean' || typeof x === 'number' || typeof x === 'string' || x instanceof Uint8Array;
         };
-        for (let i = 0; i < (params.args ?? []).length; i++) {
+        for (let i = (params.args ?? []).length - 1; i >= 0; i--) {
             const arg = params.args[i];
             if (arg === undefined) {
+                // An undefined transaction argument signals that the value will be supplied by a method call argument
+                if (algosdk.abiTypeIsTransaction(params.method.args[i].type) && transactionsForGroup.length > 0) {
+                    // Move the last transaction from the group to the method call arguments to appease algosdk
+                    const placeholderTransaction = transactionsForGroup.splice(-1, 1)[0];
+                    methodArgs.push(placeholderTransaction);
+                    continue;
+                }
                 throw Error(`No value provided for argument ${i + 1} within call to ${params.method.name}`);
             }
             if (isAbiValue(arg)) {
@@ -315,7 +330,10 @@ class AlgoKitComposer {
             }
             if ('method' in arg) {
                 const tempTxnWithSigners = await this.buildMethodCall(arg, suggestedParams, includeSigner);
-                methodArgs.push(...tempTxnWithSigners);
+                // If there is any transaction args, add to the atc
+                // Everything else should be added as method args
+                methodArgs.push(...tempTxnWithSigners.slice(-1)); // Add the method call itself as a method arg
+                transactionsForGroup.push(...tempTxnWithSigners.slice(0, -1).reverse()); // Add any transaction arguments to the atc
                 continue;
             }
             const txn = await arg;
@@ -327,10 +345,11 @@ class AlgoKitComposer {
                             ? params.signer.signer
                             : params.signer
                         : this.getSigner(encodeAddress(txn.from.publicKey))
-                    : AlgoKitComposer.NULL_SIGNER,
+                    : TransactionComposer.NULL_SIGNER,
             });
         }
         const methodAtc = new algosdk.AtomicTransactionComposer();
+        transactionsForGroup.reverse().forEach((txn) => methodAtc.addTransaction(txn));
         const appId = Number('appId' in params ? params.appId : 0n);
         const approvalProgram = 'approvalProgram' in params
             ? typeof params.approvalProgram === 'string'
@@ -360,10 +379,10 @@ class AlgoKitComposer {
                         ? Math.floor((approvalProgram.length + (clearStateProgram?.length ?? 0)) / types_app.APP_PAGE_MAX_SIZE)
                         : 0
                 : undefined,
-            numLocalInts: appId === 0 ? ('schema' in params ? params.schema?.localInts ?? 0 : 0) : undefined,
-            numLocalByteSlices: appId === 0 ? ('schema' in params ? params.schema?.localByteSlices ?? 0 : 0) : undefined,
-            numGlobalInts: appId === 0 ? ('schema' in params ? params.schema?.globalInts ?? 0 : 0) : undefined,
-            numGlobalByteSlices: appId === 0 ? ('schema' in params ? params.schema?.globalByteSlices ?? 0 : 0) : undefined,
+            numLocalInts: appId === 0 ? ('schema' in params ? (params.schema?.localInts ?? 0) : 0) : undefined,
+            numLocalByteSlices: appId === 0 ? ('schema' in params ? (params.schema?.localByteSlices ?? 0) : 0) : undefined,
+            numGlobalInts: appId === 0 ? ('schema' in params ? (params.schema?.globalInts ?? 0) : 0) : undefined,
+            numGlobalByteSlices: appId === 0 ? ('schema' in params ? (params.schema?.globalByteSlices ?? 0) : 0) : undefined,
             method: params.method,
             signer: includeSigner
                 ? params.signer
@@ -371,8 +390,8 @@ class AlgoKitComposer {
                         ? params.signer.signer
                         : params.signer
                     : this.getSigner(params.sender)
-                : AlgoKitComposer.NULL_SIGNER,
-            methodArgs: methodArgs,
+                : TransactionComposer.NULL_SIGNER,
+            methodArgs: methodArgs.reverse(),
             // note, lease, and rekeyTo are set in the common build step
             note: undefined,
             lease: undefined,
@@ -485,12 +504,12 @@ class AlgoKitComposer {
             txn = algosdk.makeApplicationCreateTxnFromObject({
                 ...sdkParams,
                 extraPages: 'extraProgramPages' in params
-                    ? params.extraProgramPages ?? Math.floor((approvalProgram.length + clearStateProgram.length) / types_app.APP_PAGE_MAX_SIZE)
+                    ? (params.extraProgramPages ?? Math.floor((approvalProgram.length + clearStateProgram.length) / types_app.APP_PAGE_MAX_SIZE))
                     : 0,
-                numLocalInts: 'schema' in params ? params.schema?.localInts ?? 0 : 0,
-                numLocalByteSlices: 'schema' in params ? params.schema?.localByteSlices ?? 0 : 0,
-                numGlobalInts: 'schema' in params ? params.schema?.globalInts ?? 0 : 0,
-                numGlobalByteSlices: 'schema' in params ? params.schema?.globalByteSlices ?? 0 : 0,
+                numLocalInts: 'schema' in params ? (params.schema?.localInts ?? 0) : 0,
+                numLocalByteSlices: 'schema' in params ? (params.schema?.localByteSlices ?? 0) : 0,
+                numGlobalInts: 'schema' in params ? (params.schema?.globalInts ?? 0) : 0,
+                numGlobalByteSlices: 'schema' in params ? (params.schema?.globalByteSlices ?? 0) : 0,
                 approvalProgram: approvalProgram,
                 clearProgram: clearStateProgram,
             });
@@ -501,7 +520,32 @@ class AlgoKitComposer {
         return this.commonTxnBuildStep(params, txn, suggestedParams);
     }
     buildKeyReg(params, suggestedParams) {
-        const txn = algosdk.makeKeyRegistrationTxnWithSuggestedParams(params.sender, undefined, params.voteKey, params.selectionKey, Number(params.voteFirst), Number(params.voteLast), Number(params.voteKeyDilution), suggestedParams, undefined, false, params.stateProofKey);
+        let txn;
+        if ('voteKey' in params) {
+            // algosdk throws when voteFirst is 0, so we need to set it to 1, then switch back to 0 after creating the transaction
+            const voteFirst = params.voteFirst === 0n ? 1n : params.voteFirst;
+            txn = algosdk.makeKeyRegistrationTxnWithSuggestedParamsFromObject({
+                from: params.sender,
+                voteKey: params.voteKey,
+                selectionKey: params.selectionKey,
+                voteFirst: Number(voteFirst),
+                voteLast: Number(params.voteLast),
+                voteKeyDilution: Number(params.voteKeyDilution),
+                suggestedParams,
+                nonParticipation: false,
+                stateProofKey: params.stateProofKey,
+            });
+            if (params.voteFirst === 0n) {
+                txn.voteFirst = 0;
+            }
+        }
+        else {
+            txn = algosdk.makeKeyRegistrationTxnWithSuggestedParamsFromObject({
+                from: params.sender,
+                suggestedParams,
+                nonParticipation: params.preventAccountFromEverParticipatingAgain,
+            });
+        }
         return this.commonTxnBuildStep(params, txn, suggestedParams);
     }
     /** Builds all transaction types apart from `txnWithSigner`, `atc` and `methodCall` since those ones can have custom signers that need to be retrieved. */
@@ -568,7 +612,7 @@ class AlgoKitComposer {
                             : [];
                 transactions.push(...transactionsWithSigner.map((ts) => ts.txn));
                 transactionsWithSigner.forEach((ts, idx) => {
-                    if (ts.signer && ts.signer !== AlgoKitComposer.NULL_SIGNER) {
+                    if (ts.signer && ts.signer !== TransactionComposer.NULL_SIGNER) {
                         signers.set(idx, ts.signer);
                     }
                 });
@@ -663,30 +707,60 @@ class AlgoKitComposer {
      * @returns The simulation result
      */
     async simulate(options) {
-        await this.build();
-        if (config.Config.debug && !config.Config.traceAll) {
-            // Dump the traces to a file for use with AlgoKit AVM debugger
-            // Checks for false on traceAll because it should have been already
-            // executed above
-            const simulateResponse = await performAtomicTransactionComposerSimulate.performAtomicTransactionComposerSimulate(this.atc, this.algod);
-            await config.Config.events.emitAsync(types_asyncEventEmitter.EventType.TxnGroupSimulated, {
-                simulateResponse,
-            });
+        const atc = options?.skipSignatures ? new AtomicTransactionComposer() : this.atc;
+        // Build the transactions
+        if (options?.skipSignatures) {
+            options.allowEmptySignatures = true;
+            options.fixSigners = true;
+            // Build transactions uses empty signers
+            const transactions = await this.buildTransactions();
+            for (const txn of transactions.transactions) {
+                atc.addTransaction({ txn, signer: TransactionComposer.NULL_SIGNER });
+            }
+            atc['methodCalls'] = transactions.methodCalls;
+        }
+        else {
+            // Build creates real signatures
+            await this.build();
         }
-        const { methodResults, simulateResponse } = await this.atc.simulate(this.algod, new modelsv2.SimulateRequest({ txnGroups: [], ...options }));
-        if (simulateResponse && simulateResponse.txnGroups[0].failedAt) {
-            const error = new Error(`Transaction failed at transaction(s) ${simulateResponse.txnGroups[0].failedAt.join(', ')} in the group. ${simulateResponse.txnGroups.find((x) => x.failureMessage)?.failureMessage}`);
+        const { methodResults, simulateResponse } = await atc.simulate(this.algod, new modelsv2.SimulateRequest({
+            txnGroups: [],
+            ...options,
+            ...(config.Config.debug
+                ? {
+                    allowEmptySignatures: true,
+                    fixSigners: true,
+                    allowMoreLogging: true,
+                    execTraceConfig: new modelsv2.SimulateTraceConfig({
+                        enable: true,
+                        scratchChange: true,
+                        stackChange: true,
+                        stateChange: true,
+                    }),
+                }
+                : undefined),
+        }));
+        const failedGroup = simulateResponse?.txnGroups[0];
+        if (failedGroup?.failureMessage) {
+            const errorMessage = `Transaction failed at transaction(s) ${failedGroup.failedAt?.join(', ') || 'unknown'} in the group. ${failedGroup.failureMessage}`;
+            const error = new Error(errorMessage);
+            if (config.Config.debug) {
+                await config.Config.events.emitAsync(types_lifecycleEvents.EventType.TxnGroupSimulated, { simulateResponse });
+            }
             error.simulateResponse = simulateResponse;
             throw error;
         }
-        const transactions = this.atc.buildGroup().map((t) => t.txn);
+        if (config.Config.debug && config.Config.traceAll) {
+            await config.Config.events.emitAsync(types_lifecycleEvents.EventType.TxnGroupSimulated, { simulateResponse });
+        }
+        const transactions = atc.buildGroup().map((t) => t.txn);
         return {
             confirmations: simulateResponse.txnGroups[0].txnResults.map((t) => t.txnResult),
             transactions: transactions,
             txIds: transactions.map((t) => t.txID()),
             groupId: Buffer.from(transactions[0].group ?? new Uint8Array()).toString('base64'),
             simulateResponse,
-            returns: methodResults.map((m) => m),
+            returns: methodResults.map(transaction.getABIReturnValue),
         };
     }
     /**
@@ -703,8 +777,8 @@ class AlgoKitComposer {
     }
 }
 /** Signer used to represent a lack of signer */
-AlgoKitComposer.NULL_SIGNER = algosdk.makeEmptyTransactionSigner();
+TransactionComposer.NULL_SIGNER = algosdk.makeEmptyTransactionSigner();
 
 exports.MAX_TRANSACTION_GROUP_SIZE = MAX_TRANSACTION_GROUP_SIZE;
-exports.default = AlgoKitComposer;
+exports.TransactionComposer = TransactionComposer;
 //# sourceMappingURL=composer.js.map