@alephium/web3 0.39.3 → 0.40.0

package/dist/src/api/api-alephium.d.ts

@@ -1007,7 +1007,7 @@ export declare class HttpClient<SecurityDataType = unknown> {
 }
 /**
  * @title Alephium API
- * @version 2.11.0
+ * @version 2.14.0
  * @baseUrl ../
  */
 export declare class Api<SecurityDataType extends unknown> extends HttpClient<SecurityDataType> {

package/dist/src/api/api-alephium.js

@@ -151,7 +151,7 @@ class HttpClient {
 exports.HttpClient = HttpClient;
 /**
  * @title Alephium API
- * @version 2.11.0
+ * @version 2.14.0
  * @baseUrl ../
  */
 class Api extends HttpClient {

package/dist/src/codec/instr-codec.d.ts

@@ -170,6 +170,7 @@ export declare const AddModN: Instr;
 export declare const U256ToString: Instr;
 export declare const I256ToString: Instr;
 export declare const BoolToString: Instr;
+export declare const GroupOfAddress: Instr;
 export declare const LoadMutField: (index: number) => Instr;
 export declare const StoreMutField: (index: number) => Instr;
 export declare const ApproveAlph: Instr;
@@ -221,6 +222,8 @@ export declare const LoadImmFieldByIndex: Instr;
 export declare const PayGasFee: Instr;
 export declare const MinimalContractDeposit: Instr;
 export declare const CreateMapEntry: (immFields: number, mutFields: number) => Instr;
+export declare const MethodSelector: (selector: number) => Instr;
+export declare const CallExternalBySelector: (selector: number) => Instr;
 export declare class InstrCodec implements Codec<Instr> {
     parser: Parser;
     encode(instr: Instr): Buffer;

package/dist/src/codec/instr-codec.js

@@ -2,8 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.U256Lt = exports.U256Neq = exports.U256Eq = exports.U256Mod = exports.U256Div = exports.U256Mul = exports.U256Sub = exports.U256Add = exports.I256Ge = exports.I256Gt = exports.I256Le = exports.I256Lt = exports.I256Neq = exports.I256Eq = exports.I256Mod = exports.I256Div = exports.I256Mul = exports.I256Sub = exports.I256Add = exports.BoolToByteVec = exports.BoolNeq = exports.BoolEq = exports.BoolOr = exports.BoolAnd = exports.BoolNot = exports.Pop = exports.StoreLocal = exports.LoadLocal = exports.AddressConst = exports.ByteConst = exports.U256Const = exports.I256Const = exports.U256Const5 = exports.U256Const4 = exports.U256Const3 = exports.U256Const2 = exports.U256Const1 = exports.U256Const0 = exports.I256ConstN1 = exports.I256Const5 = exports.I256Const4 = exports.I256Const3 = exports.I256Const2 = exports.I256Const1 = exports.I256Const0 = exports.ConstFalse = exports.ConstTrue = exports.Return = exports.CallExternal = exports.CallLocal = void 0;
 exports.ByteVecToAddress = exports.ByteVecSlice = exports.Log5 = exports.Log4 = exports.Log3 = exports.Log2 = exports.Log1 = exports.VerifyRelativeLocktime = exports.VerifyAbsoluteLocktime = exports.TxInputsSize = exports.TxInputAddressAt = exports.TxId = exports.BlockTarget = exports.BlockTimeStamp = exports.NetworkId = exports.VerifyED25519 = exports.VerifySecP256K1 = exports.VerifyTxSignature = exports.Sha3 = exports.Sha256 = exports.Keccak256 = exports.Blake2b = exports.Assert = exports.IfFalse = exports.IfTrue = exports.Jump = exports.IsContractAddress = exports.IsAssetAddress = exports.AddressToByteVec = exports.AddressNeq = exports.AddressEq = exports.ByteVecConcat = exports.ByteVecSize = exports.ByteVecNeq = exports.ByteVecEq = exports.U256ToByteVec = exports.U256ToI256 = exports.I256ToByteVec = exports.I256ToU256 = exports.U256SHR = exports.U256SHL = exports.U256Xor = exports.U256BitOr = exports.U256BitAnd = exports.U256ModMul = exports.U256ModSub = exports.U256ModAdd = exports.U256Ge = exports.U256Gt = exports.U256Le = void 0;
-exports.TransferAlphToSelf = exports.TransferAlphFromSelf = exports.TransferAlph = exports.IsPaying = exports.TokenRemaining = exports.AlphRemaining = exports.ApproveToken = exports.ApproveAlph = exports.StoreMutField = exports.LoadMutField = exports.BoolToString = exports.I256ToString = exports.U256ToString = exports.AddModN = exports.MulModN = exports.GetSegragatedSignature = exports.VerifyBIP340Schnorr = exports.U256ModExp = exports.U256Exp = exports.I256Exp = exports.TxGasFee = exports.TxGasAmount = exports.TxGasPrice = exports.DEBUG = exports.BlockHash = exports.Swap = exports.AssertWithErrorCode = exports.Dup = exports.StoreLocalByIndex = exports.LoadLocalByIndex = exports.ContractIdToAddress = exports.Log9 = exports.Log8 = exports.Log7 = exports.Log6 = exports.EthEcRecover = exports.U256From32Byte = exports.U256From16Byte = exports.U256From8Byte = exports.U256From4Byte = exports.U256From2Byte = exports.U256From1Byte = exports.U256To32Byte = exports.U256To16Byte = exports.U256To8Byte = exports.U256To4Byte = exports.U256To2Byte = exports.U256To1Byte = exports.Zeros = exports.Encode = void 0;
-exports.instrsCodec = exports.instrCodec = exports.InstrCodec = exports.CreateMapEntry = exports.MinimalContractDeposit = exports.PayGasFee = exports.LoadImmFieldByIndex = exports.LoadImmField = exports.AlphTokenId = exports.SubContractIdOf = exports.SubContractId = exports.NullContractAddress = exports.CopyCreateSubContractAndTransferToken = exports.CreateSubContractAndTransferToken = exports.CopyCreateContractAndTransferToken = exports.CreateContractAndTransferToken = exports.ContractExists = exports.StoreMutFieldByIndex = exports.LoadMutFieldByIndex = exports.CopyCreateSubContractWithToken = exports.CopyCreateSubContract = exports.CreateSubContractWithToken = exports.CreateSubContract = exports.LockApprovedAssets = exports.BurnToken = exports.CopyCreateContractWithToken = exports.MigrateWithFields = exports.MigrateSimple = exports.ContractInitialCodeHash = exports.ContractInitialStateHash = exports.CallerCodeHash = exports.CallerInitialStateHash = exports.IsCallerFromTxScript = exports.CallerAddress = exports.CallerContractId = exports.SelfAddress = exports.SelfContractId = exports.DestroySelf = exports.CopyCreateContract = exports.CreateContractWithToken = exports.CreateContract = exports.TransferTokenToSelf = exports.TransferTokenFromSelf = exports.TransferToken = void 0;
+exports.TransferAlphFromSelf = exports.TransferAlph = exports.IsPaying = exports.TokenRemaining = exports.AlphRemaining = exports.ApproveToken = exports.ApproveAlph = exports.StoreMutField = exports.LoadMutField = exports.GroupOfAddress = exports.BoolToString = exports.I256ToString = exports.U256ToString = exports.AddModN = exports.MulModN = exports.GetSegragatedSignature = exports.VerifyBIP340Schnorr = exports.U256ModExp = exports.U256Exp = exports.I256Exp = exports.TxGasFee = exports.TxGasAmount = exports.TxGasPrice = exports.DEBUG = exports.BlockHash = exports.Swap = exports.AssertWithErrorCode = exports.Dup = exports.StoreLocalByIndex = exports.LoadLocalByIndex = exports.ContractIdToAddress = exports.Log9 = exports.Log8 = exports.Log7 = exports.Log6 = exports.EthEcRecover = exports.U256From32Byte = exports.U256From16Byte = exports.U256From8Byte = exports.U256From4Byte = exports.U256From2Byte = exports.U256From1Byte = exports.U256To32Byte = exports.U256To16Byte = exports.U256To8Byte = exports.U256To4Byte = exports.U256To2Byte = exports.U256To1Byte = exports.Zeros = exports.Encode = void 0;
+exports.instrsCodec = exports.instrCodec = exports.InstrCodec = exports.CallExternalBySelector = exports.MethodSelector = exports.CreateMapEntry = exports.MinimalContractDeposit = exports.PayGasFee = exports.LoadImmFieldByIndex = exports.LoadImmField = exports.AlphTokenId = exports.SubContractIdOf = exports.SubContractId = exports.NullContractAddress = exports.CopyCreateSubContractAndTransferToken = exports.CreateSubContractAndTransferToken = exports.CopyCreateContractAndTransferToken = exports.CreateContractAndTransferToken = exports.ContractExists = exports.StoreMutFieldByIndex = exports.LoadMutFieldByIndex = exports.CopyCreateSubContractWithToken = exports.CopyCreateSubContract = exports.CreateSubContractWithToken = exports.CreateSubContract = exports.LockApprovedAssets = exports.BurnToken = exports.CopyCreateContractWithToken = exports.MigrateWithFields = exports.MigrateSimple = exports.ContractInitialCodeHash = exports.ContractInitialStateHash = exports.CallerCodeHash = exports.CallerInitialStateHash = exports.IsCallerFromTxScript = exports.CallerAddress = exports.CallerContractId = exports.SelfAddress = exports.SelfContractId = exports.DestroySelf = exports.CopyCreateContract = exports.CreateContractWithToken = exports.CreateContract = exports.TransferTokenToSelf = exports.TransferTokenFromSelf = exports.TransferToken = exports.TransferAlphToSelf = void 0;
 /*
 Copyright 2018 - 2022 The Alephium Authors
 This file is part of the alephium project.
@@ -27,6 +27,7 @@ const array_codec_1 = require("./array-codec");
 const compact_int_codec_1 = require("./compact-int-codec");
 const bytestring_codec_1 = require("./bytestring-codec");
 const lockup_script_codec_1 = require("./lockup-script-codec");
+const signed_int_codec_1 = require("./signed-int-codec");
 const byteStringArrayCodec = new array_codec_1.ArrayCodec(bytestring_codec_1.byteStringCodec);
 const CallLocal = (index) => ({ code: 0x00, value: { index } });
 exports.CallLocal = CallLocal;
@@ -180,6 +181,7 @@ exports.AddModN = { code: 0x88, value: {} };
 exports.U256ToString = { code: 0x89, value: {} };
 exports.I256ToString = { code: 0x8a, value: {} };
 exports.BoolToString = { code: 0x8b, value: {} };
+exports.GroupOfAddress = { code: 0x8c, value: {} };
 const LoadMutField = (index) => ({ code: 0xa0, value: { index } });
 exports.LoadMutField = LoadMutField;
 const StoreMutField = (index) => ({ code: 0xa1, value: { index } });
@@ -235,6 +237,14 @@ exports.PayGasFee = { code: 0xd0, value: {} };
 exports.MinimalContractDeposit = { code: 0xd1, value: {} };
 const CreateMapEntry = (immFields, mutFields) => ({ code: 0xd2, value: { immFields, mutFields } });
 exports.CreateMapEntry = CreateMapEntry;
+const MethodSelector = (selector) => {
+    return { code: 0xd3, value: { index: selector } };
+};
+exports.MethodSelector = MethodSelector;
+const CallExternalBySelector = (selector) => {
+    return { code: 0xd4, value: { index: selector } };
+};
+exports.CallExternalBySelector = CallExternalBySelector;
 class InstrCodec {
     constructor() {
         this.parser = binary_parser_1.Parser.start()
@@ -382,6 +392,7 @@ class InstrCodec {
                 [exports.U256ToString.code]: binary_parser_1.Parser.start(),
                 [exports.I256ToString.code]: binary_parser_1.Parser.start(),
                 [exports.BoolToString.code]: binary_parser_1.Parser.start(),
+                [exports.GroupOfAddress.code]: binary_parser_1.Parser.start(),
                 0xa0: binary_parser_1.Parser.start().uint8('index'),
                 0xa1: binary_parser_1.Parser.start().uint8('index'),
                 [exports.ApproveAlph.code]: binary_parser_1.Parser.start(),
@@ -432,7 +443,9 @@ class InstrCodec {
                 [exports.LoadImmFieldByIndex.code]: binary_parser_1.Parser.start(),
                 [exports.PayGasFee.code]: binary_parser_1.Parser.start(),
                 [exports.MinimalContractDeposit.code]: binary_parser_1.Parser.start(),
-                0xd2: binary_parser_1.Parser.start().uint8('immFields').uint8('mutFields')
+                0xd2: binary_parser_1.Parser.start().uint8('immFields').uint8('mutFields'),
+                0xd3: binary_parser_1.Parser.start().int32('index'),
+                0xd4: binary_parser_1.Parser.start().int32('index')
             }
         });
     }
@@ -460,6 +473,9 @@ class InstrCodec {
             const value = instrValue;
             result.push(value.immFields, value.mutFields);
         }
+        else if (instr.code === 0xd3 || instr.code === 0xd4) {
+            result.push(...signed_int_codec_1.signedIntCodec.encode(instrValue.index));
+        }
         return buffer_1.Buffer.from(result);
     }
     decode(input) {

package/dist/src/contract/contract.d.ts

@@ -321,6 +321,15 @@ export declare function addStdIdToFields<F extends Fields>(contract: Contract, f
     __stdInterfaceId: HexString;
 });
 export declare function testMethod<I extends ContractInstance, F extends Fields, A extends Arguments, R, M extends Record<string, Map<Val, Val>> = Record<string, Map<Val, Val>>>(factory: ContractFactory<I, F>, methodName: string, params: Optional<TestContractParams<F, A, M>, 'testArgs' | 'initialFields'>): Promise<TestContractResult<R, M>>;
+export declare class RalphMap<K extends Val, V extends Val> {
+    private readonly parentContract;
+    private readonly parentInstance;
+    private readonly mapName;
+    constructor(parentContract: Contract, parentInstance: ContractInstance, mapName: string);
+    get(key: K): Promise<V | undefined>;
+    contains(key: K): Promise<boolean>;
+}
+export declare function getMapItem<R extends Val>(parentContract: Contract, parentInstance: ContractInstance, mapName: string, key: Val): Promise<R | undefined>;
 export declare abstract class ContractInstance {
     readonly address: Address;
     readonly contractId: string;

package/dist/src/contract/contract.js

@@ -43,7 +43,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.tryGetCallResult = exports.getTokenIdFromUnsignedTx = exports.getContractIdFromUnsignedTx = exports.getContractEventsCurrentCount = exports.multicallMethods = exports.callMethod = exports.subscribeContractEvents = exports.subscribeContractEvent = exports.decodeEvent = exports.subscribeContractDestroyedEvent = exports.subscribeContractCreatedEvent = exports.fetchContractState = exports.ContractInstance = exports.testMethod = exports.addStdIdToFields = exports.subscribeEventsFromContract = exports.decodeContractDestroyedEvent = exports.decodeContractCreatedEvent = exports.DestroyContractEventAddresses = exports.CreateContractEventAddresses = exports.ExecutableScript = exports.ContractFactory = exports.randomTxId = exports.fromApiEventFields = exports.fromApiArray = exports.getDefaultValue = exports.fromApiFields = exports.Script = exports.Contract = exports.Artifact = exports.Project = exports.Struct = exports.ProjectArtifact = exports.DEFAULT_COMPILER_OPTIONS = exports.DEFAULT_NODE_COMPILER_OPTIONS = exports.StdIdFieldName = void 0;
+exports.tryGetCallResult = exports.getTokenIdFromUnsignedTx = exports.getContractIdFromUnsignedTx = exports.getContractEventsCurrentCount = exports.multicallMethods = exports.callMethod = exports.subscribeContractEvents = exports.subscribeContractEvent = exports.decodeEvent = exports.subscribeContractDestroyedEvent = exports.subscribeContractCreatedEvent = exports.fetchContractState = exports.ContractInstance = exports.getMapItem = exports.RalphMap = exports.testMethod = exports.addStdIdToFields = exports.subscribeEventsFromContract = exports.decodeContractDestroyedEvent = exports.decodeContractCreatedEvent = exports.DestroyContractEventAddresses = exports.CreateContractEventAddresses = exports.ExecutableScript = exports.ContractFactory = exports.randomTxId = exports.fromApiEventFields = exports.fromApiArray = exports.getDefaultValue = exports.fromApiFields = exports.Script = exports.Contract = exports.Artifact = exports.Project = exports.Struct = exports.ProjectArtifact = exports.DEFAULT_COMPILER_OPTIONS = exports.DEFAULT_NODE_COMPILER_OPTIONS = exports.StdIdFieldName = void 0;
 const buffer_1 = require("buffer/");
 const fs_1 = __importDefault(require("fs"));
 const fs_2 = require("fs");
@@ -1321,6 +1321,44 @@ async function testMethod(factory, methodName, params) {
     };
 }
 exports.testMethod = testMethod;
+class RalphMap {
+    constructor(parentContract, parentInstance, mapName) {
+        this.parentContract = parentContract;
+        this.parentInstance = parentInstance;
+        this.mapName = mapName;
+    }
+    async get(key) {
+        return getMapItem(this.parentContract, this.parentInstance, this.mapName, key);
+    }
+    async contains(key) {
+        return this.get(key).then((v) => v !== undefined);
+    }
+}
+exports.RalphMap = RalphMap;
+async function getMapItem(parentContract, parentInstance, mapName, key) {
+    const index = parentContract.mapsSig?.names.findIndex((name) => name === mapName);
+    const mapType = index === undefined ? undefined : parentContract.mapsSig?.types[`${index}`];
+    if (mapType === undefined) {
+        throw new Error(`Map ${mapName} does not exist in contract ${parentContract.name}`);
+    }
+    const [keyType, valueType] = ralph.parseMapType(mapType);
+    const mapItemContractId = calcWrapperContractId(parentInstance.contractId, index, key, keyType, parentInstance.groupIndex);
+    const mapItemAddress = (0, utils_1.addressFromContractId)(mapItemContractId);
+    try {
+        const state = await (0, global_1.getCurrentNodeProvider)().contracts.getContractsAddressState(mapItemAddress);
+        const fieldsSig = getContractFieldsSig(valueType);
+        const fields = fromApiFields(state.immFields, state.mutFields, fieldsSig, parentContract.structs);
+        return fields['value'];
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.includes('KeyNotFound')) {
+            // the map item contract does not exist
+            return undefined;
+        }
+        throw error;
+    }
+}
+exports.getMapItem = getMapItem;
 function buildMapInfo(contract, fields) {
     const mapsSig = contract.mapsSig;
     if (mapsSig === undefined)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alephium/web3",
-  "version": "0.39.3",
+  "version": "0.40.0",
   "description": "A JS/TS library to interact with the Alephium platform",
   "license": "GPL",
   "main": "dist/src/index.js",
@@ -27,7 +27,7 @@
   },
   "author": "Alephium dev <dev@alephium.org>",
   "config": {
-    "alephium_version": "2.11.0",
+    "alephium_version": "2.14.0",
     "explorer_backend_version": "1.17.0"
   },
   "type": "commonjs",
@@ -90,7 +90,7 @@
     "build": "rm -rf dist/* && npx tsc --build . && webpack",
     "test": "jest -i --config ./jest-config.json",
     "update-schemas": "npm run update-schema:alephium && npm run update-schema:explorer",
-    "update-schema:alephium": "npx swagger-typescript-api --disable-throw-on-error -t ./configs -o ./src/api -n api-alephium.ts -p https://raw.githubusercontent.com/alephium/alephium/rhone-upgrade/api/src/main/resources/openapi.json",
+    "update-schema:alephium": "npx swagger-typescript-api --disable-throw-on-error -t ./configs -o ./src/api -n api-alephium.ts -p https://raw.githubusercontent.com/alephium/alephium/v${npm_package_config_alephium_version}/api/src/main/resources/openapi.json",
     "update-schema:explorer": "npx swagger-typescript-api --disable-throw-on-error -t ./configs -o ./src/api -n api-explorer.ts -p https://raw.githubusercontent.com/alephium/explorer-backend/v${npm_package_config_explorer_backend_version}/app/src/main/resources/explorer-backend-openapi.json",
     "check-versions": "node scripts/check-versions.js ${npm_package_config_alephium_version} ${npm_package_config_explorer_backend_version}"
   }

package/src/api/api-alephium.ts

@@ -1306,7 +1306,7 @@ export class HttpClient<SecurityDataType = unknown> {
 
 /**
  * @title Alephium API
- * @version 2.11.0
+ * @version 2.14.0
  * @baseUrl ../
  */
 export class Api<SecurityDataType extends unknown> extends HttpClient<SecurityDataType> {

package/src/codec/instr-codec.ts

@@ -22,6 +22,7 @@ import { compactUnsignedIntCodec, compactSignedIntCodec, DecodedCompactInt } fro
 import { ByteString, byteStringCodec } from './bytestring-codec'
 import { LockupScript, lockupScriptCodec } from './lockup-script-codec'
 import { Codec } from './codec'
+import { signedIntCodec } from './signed-int-codec'
 
 const byteStringArrayCodec = new ArrayCodec(byteStringCodec)
 
@@ -192,6 +193,7 @@ export const AddModN: Instr = { code: 0x88, value: {} }
 export const U256ToString: Instr = { code: 0x89, value: {} }
 export const I256ToString: Instr = { code: 0x8a, value: {} }
 export const BoolToString: Instr = { code: 0x8b, value: {} }
+export const GroupOfAddress: Instr = { code: 0x8c, value: {} }
 export const LoadMutField = (index: number): Instr => ({ code: 0xa0, value: { index } })
 export const StoreMutField = (index: number): Instr => ({ code: 0xa1, value: { index } })
 export const ApproveAlph: Instr = { code: 0xa2, value: {} }
@@ -246,6 +248,12 @@ export const CreateMapEntry: (immFields: number, mutFields: number) => Instr = (
   immFields: number,
   mutFields: number
 ) => ({ code: 0xd2, value: { immFields, mutFields } })
+export const MethodSelector: (selector: number) => Instr = (selector: number) => {
+  return { code: 0xd3, value: { index: selector } }
+}
+export const CallExternalBySelector: (selector: number) => Instr = (selector: number) => {
+  return { code: 0xd4, value: { index: selector } }
+}
 
 export class InstrCodec implements Codec<Instr> {
   parser = Parser.start()
@@ -393,6 +401,7 @@ export class InstrCodec implements Codec<Instr> {
         [U256ToString.code]: Parser.start(),
         [I256ToString.code]: Parser.start(),
         [BoolToString.code]: Parser.start(),
+        [GroupOfAddress.code]: Parser.start(),
         0xa0: Parser.start().uint8('index'),
         0xa1: Parser.start().uint8('index'),
         [ApproveAlph.code]: Parser.start(),
@@ -443,7 +452,9 @@ export class InstrCodec implements Codec<Instr> {
         [LoadImmFieldByIndex.code]: Parser.start(),
         [PayGasFee.code]: Parser.start(),
         [MinimalContractDeposit.code]: Parser.start(),
-        0xd2: Parser.start().uint8('immFields').uint8('mutFields')
+        0xd2: Parser.start().uint8('immFields').uint8('mutFields'),
+        0xd3: Parser.start().int32('index'),
+        0xd4: Parser.start().int32('index')
       }
     })
 
@@ -465,6 +476,8 @@ export class InstrCodec implements Codec<Instr> {
     } else if (instr.code === 0xd2) {
       const value = instrValue as CreateMapEntryValue
       result.push(value.immFields, value.mutFields)
+    } else if (instr.code === 0xd3 || instr.code === 0xd4) {
+      result.push(...signedIntCodec.encode((instrValue as InstrValueWithIndex).index))
     }
 
     return Buffer.from(result)

package/src/contract/contract.ts

@@ -2007,6 +2007,56 @@ export async function testMethod<
   } as TestContractResult<R, M>
 }
 
+export class RalphMap<K extends Val, V extends Val> {
+  constructor(
+    private readonly parentContract: Contract,
+    private readonly parentInstance: ContractInstance,
+    private readonly mapName: string
+  ) {}
+
+  async get(key: K): Promise<V | undefined> {
+    return getMapItem(this.parentContract, this.parentInstance, this.mapName, key)
+  }
+
+  async contains(key: K): Promise<boolean> {
+    return this.get(key).then((v) => v !== undefined)
+  }
+}
+
+export async function getMapItem<R extends Val>(
+  parentContract: Contract,
+  parentInstance: ContractInstance,
+  mapName: string,
+  key: Val
+): Promise<R | undefined> {
+  const index = parentContract.mapsSig?.names.findIndex((name) => name === mapName)
+  const mapType = index === undefined ? undefined : parentContract.mapsSig?.types[`${index}`]
+  if (mapType === undefined) {
+    throw new Error(`Map ${mapName} does not exist in contract ${parentContract.name}`)
+  }
+  const [keyType, valueType] = ralph.parseMapType(mapType)
+  const mapItemContractId = calcWrapperContractId(
+    parentInstance.contractId,
+    index!,
+    key,
+    keyType,
+    parentInstance.groupIndex
+  )
+  const mapItemAddress = addressFromContractId(mapItemContractId)
+  try {
+    const state = await getCurrentNodeProvider().contracts.getContractsAddressState(mapItemAddress)
+    const fieldsSig = getContractFieldsSig(valueType)
+    const fields = fromApiFields(state.immFields, state.mutFields, fieldsSig, parentContract.structs)
+    return fields['value'] as R
+  } catch (error) {
+    if (error instanceof Error && error.message.includes('KeyNotFound')) {
+      // the map item contract does not exist
+      return undefined
+    }
+    throw error
+  }
+}
+
 interface MapInfo {
   name: string
   value: Map<Val, Val>