Support payload in read_state rpc call (#1349)

.github/workflows/CI-CD-gear-js-api.yml

@@ -70,7 +70,7 @@ jobs:
 
       - name: "Prepare: build programs"
         working-directory: api/programs
-        run: cargo build --release --locked
+        run: cargo build --locked
 
       - name: "Prepare: download Gear examples"
         working-directory: api/test/wasm

api/CHANGELOG.md

@@ -8,6 +8,10 @@ https://github.com/gear-tech/gear-js/pull/1353
 - Remove `sendMessageWithVoucher` and `sendReplyWithVoucher` methods according to https://github.com/gear-tech/gear/pull/3083.
 - Add optional `prepaid` and `account` fields to `api.message.send` and `api.message.sendReply` method arguments. They are used to send messages with the issued voucher.
 
+https://github.com/gear-tech/gear-js/pull/1349
+- Add `payload` parameter to `api.programState.read` and `api.programState.readUsingWasm` methods according to https://github.com/gear-tech/gear/pull/3059 and https://github.com/gear-tech/gear/pull/3173
+- Support new `ProgramMetadata` version.
+
 ## 0.32.4
 
 _07/25/2023_

api/Makefile

@@ -8,7 +8,10 @@ update:
 	@cargo update --manifest-path programs/Cargo.toml
 
 build: 
-	@cargo build --release --manifest-path programs/Cargo.toml
+	@cargo +nightly build --release --manifest-path programs/Cargo.toml
+
+build-debug: 
+	@cargo +nightly build --manifest-path programs/Cargo.toml
 
 clean:
 	@rm -rvf programs/target

api/README.md

@@ -85,14 +85,14 @@ There're 2 types of metadata.
 
 1. `ProgramMetadata` is used to encode/decode messages to/from a program as well as to read the whole state of the program
 
-_You can use `getProgramMetadata` function to create the program metadata. The function takes metadata of the program in format of hex string. It will return object of `ProgramMetadata` class that has property `types` that contains all types of the program._
+_You can use `ProgramMetadata.from` method to create the program metadata. The method takes metadata of the program in format of hex string. It will return object of `ProgramMetadata` class that has property `types` that contains all types of the program._
 
 **You should pass an object of this class to function arguments when you want to send some extrinsics that require encoding payloads**
 
 ```javascript
-import { getProgramMetadata } from '@gear-js/api';
+import { ProgramMetadata } from '@gear-js/api';
 
-const meta = getProgramMetadata(`0x...`);
+const meta = ProgramMetadata.from(`0x...`);
 meta.types.init.input; // can be used to encode input message for init entrypoint of the program
 meta.types.init.output; // can be used to decode output message for init entrypoint of the program
 // the same thing available for all entrypoints of the program
@@ -117,7 +117,7 @@ Both `ProgramMetadata` and `StateMetadata` classes have a few methods that can h
 ```javascript
 import { ProgramMetadata } from '@gear-js/api';
 
-const meta = getProgramMetadata(`0x...`);
+const meta = ProgramMetadata.from(`0x...`);
 
 meta.getTypeName(4); // will return name of type with this index
 // or
@@ -137,7 +137,7 @@ meta.createType(4, { value: 'value' }); // to encode or decode data
 
 **_Extrinsics are used to interact with programs running on blockchain networks powered by Gear Protocol_**
 
-_In all cases of sending extrinsics, there is no need to encode the payloads by yourself. It's sufficient to pass the program metadata obtained from the `getProgramMetadata` function to the methods that creates extrinsics._
+_In all cases of sending extrinsics, there is no need to encode the payloads by yourself. It's sufficient to pass the program metadata obtained from the `ProgramMetadata.from` method to the methods that creates extrinsics._
 
 ### Upload program
 
@@ -280,7 +280,7 @@ Gas calculation returns GasInfo object contains 5 parameters:
 
 ```javascript
 const code = fs.readFileSync('demo_meta.opt.wasm');
-const meta = getProgramMetadata('0x...');
+const meta = ProgramMetadata.from('0x...');
 const gas = await gearApi.program.calculateGas.handle(
   '0x...', // source id
   '0x...', //program id
@@ -388,23 +388,27 @@ console.log(`Program with address ${programId} ${programExists ? 'exists' : "doe
 There are 2 ways to read state of a program.
 
 1. Read full state of a program.
-   _To read full state of the program you need to have only metadata of this program. You can call `api.programState.read` method to get the state._
+   _To read full state of the program you need to provide metadata of this program and input payload expected by the program. You can call `api.programState.read` method to get the state._
 
    ```javascript
-   await api.programState.read({ programId: `0x...` }, programMetadata);
+   await api.programState.read({ programId: `0x...`, payload: [1, 2, 3] }, programMetadata);
 
    // Also you can read the state of the program at some specific block.
-   await api.programState.read({ programId: `0x...`, at: `0x...` }, programMetadata);
+   await api.programState.read({ programId: `0x...`, payload: [1, 2, 3], at: `0x...` }, programMetadata);
    ```
 
 2. Read state using wasm.
    _If you have some program that is able to read state and return you only necessary data you need to use `api.programState.readUsingWasm` method._
+   _Note that since `state` function of gear programs expects input payload you need to provide it in the parameters of `readUsingWasm` method_
 
    ```javascript
    const wasm = readFileSync('path/to/state.meta.wasm');
+   const stateMetadata = await getStateMetadata(wasm);
+   const programMetadata = ProgramMetadata.from('0x...');
    const state = await api.programState.readUsingWasm(
-     { programId, fn_name: 'name_of_function_to_execute', wasm, argument: { input: 'payload' } },
-     wasm,
+     { programId, fn_name: 'name_of_function_to_execute', wasm, payload: [1, 2, 3], argument: { input: 'payload' } },
+     stateMetadata,
+     programMetadata
    );
    ```