Struct gclient::GearApi

pub struct GearApi(/* private fields */);

The API instance contains methods to access the node.

Implementations

impl GearApi

pub async fn original_code_at( &self, code_id: CodeId, at_block_hash: Option<H256>, ) -> Result<Vec<u8>>

Returns original wasm code for the given code_id at specified at_block_hash.

pub async fn program_at( &self, program_id: ProgramId, at_block_hash: Option<H256>, ) -> Result<ActiveProgram<u32>>

Returns ActiveProgram for the given program_id at specified at_block_hash.

pub async fn transfer_keep_alive( &self, destination: ProgramId, value: u128, ) -> Result<H256>

Transfer value to destination’s account.

Sends the pallet_balances::transfer extrinsic.

This function returns a hash of the block with the transfer transaction.

pub async fn transfer_allow_death( &self, destination: ProgramId, value: u128, ) -> Result<H256>

Transfer value to destination’s account.

Sends the pallet_balances::transfer extrinsic.

This function returns a hash of the block with the transfer transaction.

pub async fn transfer_all( &self, destination: ProgramId, keep_alive: bool, ) -> Result<H256>

Transfer value to destination’s account.

Sends the pallet_balances::transfer extrinsic.

This function returns a hash of the block with the transfer transaction.

pub async fn create_program_bytes( &self, code_id: CodeId, salt: impl AsRef<[u8]>, payload: impl AsRef<[u8]>, gas_limit: u64, value: u128, ) -> Result<(MessageId, ProgramId, H256)>

Create a new program from a previously uploaded code identified by CodeId and initialize it with a byte slice payload.

Sends the pallet_gear::create_program extrinsic.

Parameters:

• code_id is the code identifier that can be obtained by calling the upload_code function;
• salt is the arbitrary data needed to generate an address for a new program (control of salt uniqueness is entirely on the function caller’s side);
• payload vector contains data to be processed in the init function of the newly deployed “child” program;
• gas_limit is the maximum gas amount allowed to spend for the program creation and initialization;
• value to be transferred to the program’s account during initialization.

This function returns a tuple with an init message identifier, newly created program identifier, and a hash of the block with the message enqueuing transaction.

See also

• create_program function initializes a newly created program with an encoded payload.
• create_program_bytes_batch function creates a batch of programs and initializes them.
• upload_code function uploads a code and returns its identifier.
• upload_program_bytes function uploads a new program and initialize it.

pub async fn create_program_bytes_batch( &self, args: impl IntoIterator<Item = (CodeId, impl AsRef<[u8]>, impl AsRef<[u8]>, u64, u128)>, ) -> Result<(Vec<Result<(MessageId, ProgramId)>>, H256)>

Create a batch of programs.

A batch is a set of programs to be created within one function call. Every entry of the args iterator is a tuple of parameters used in the create_program_bytes function. It is useful when deploying a multi-program dApp.

pub async fn create_program( &self, code_id: CodeId, salt: impl AsRef<[u8]>, payload: impl Encode, gas_limit: u64, value: u128, ) -> Result<(MessageId, ProgramId, H256)>

Same as create_program_bytes, but initializes a newly created program with an encoded payload.

See also

• upload_code function uploads a code and returns its identifier.
• upload_program function uploads a new program and initialize it.

pub async fn migrate_program( &self, src_program_id: ProgramId, src_block_hash: Option<H256>, dest_node_api: &GearApi, ) -> Result<ProgramId>

Migrates an active program identified by src_program_id onto another node identified by dest_node_api and returns the migrated program identifier. All source program data is taken at the time of src_block_hash if it is specified or the most recent one.

pub async fn get_program_pages_data_at( &self, program_id: ProgramId, block_hash: Option<H256>, ) -> Result<BTreeMap<GearPage, PageBuf>>

Get all pages with their data for program at specified block.

pub async fn get_program_specified_pages_data_at( &self, program_id: ProgramId, pages: impl Iterator<Item = GearPage>, block_hash: Option<H256>, ) -> Result<BTreeMap<GearPage, PageBuf>>

Get specified pages with their data for program at specified block.

pub async fn save_program_memory_dump_at<P: AsRef<Path>>( &self, program_id: ProgramId, block_hash: Option<H256>, file_path: P, ) -> Result

Save program (identified by program_id) memory dump to the file for further restoring in gclient/gtest. Program memory dumped at the time of block_hash if presented or the most recent block.

pub async fn replace_program_memory<P: AsRef<Path>>( &self, program_id: ProgramId, file_path: P, ) -> Result

Replace entire program memory with one saved earlier in gclient/gtest

pub async fn claim_value(&self, message_id: MessageId) -> Result<(u128, H256)>

Claim value from the mailbox message identified by message_id.

Sends the pallet_gear::claim_value extrinsic.

This function returns a tuple with value and block hash containing the corresponding transaction.

See also

• claim_value_batch function claims a batch of values from the mailbox.

pub async fn claim_value_batch( &self, args: impl IntoIterator<Item = MessageId> + Clone, ) -> Result<(Vec<Result<u128>>, H256)>

Claim a batch of values from the mailbox.

A batch is a set of requests to be executed within one function call. Every entry of the args iterator is a message identifier used in the claim_value function. It is useful when processing multiple replies in the mailbox at once.

pub async fn send_message_bytes( &self, destination: ProgramId, payload: impl AsRef<[u8]>, gas_limit: u64, value: u128, ) -> Result<(MessageId, H256)>

Send a message containing a byte slice payload to the destination.

The message also contains the maximum gas_limit that can be spent and the value to be transferred to the destination’s account.

Sends the pallet_gear::send_message extrinsic.

This function returns a tuple with a new message identifier and a hash of the block with the message enqueuing transaction.

See also

• send_message function sends a message with an encoded payload.
• send_message_bytes_batch function sends a batch of messages.

pub async fn send_message_bytes_batch( &self, args: impl IntoIterator<Item = (ProgramId, impl AsRef<[u8]>, u64, u128)>, ) -> Result<(Vec<Result<(MessageId, ProgramId)>>, H256)>

Send a batch of messages.

A batch is a set of messages to be sent within one function call. Every entry of the args iterator is a tuple of parameters used in the send_message_bytes function. It is useful when invoking several programs at once or sending a sequence of messages to one program.

pub async fn send_message( &self, destination: ProgramId, payload: impl Encode, gas_limit: u64, value: u128, ) -> Result<(MessageId, H256)>

Same as send_message_bytes, but sends a message with encoded payload.

pub async fn send_reply_bytes( &self, reply_to_id: MessageId, payload: impl AsRef<[u8]>, gas_limit: u64, value: u128, ) -> Result<(MessageId, u128, H256)>

Send a reply containing a byte slice payload to the message identified by reply_to_id.

The reply also contains the maximum gas_limit that can be spent and the value to be transferred to the destination’s account.

Sends the pallet_gear::send_reply extrinsic.

This function returns a tuple with a new message identifier, transferred value, and a hash of the block with the message enqueuing transaction.

See also

• send_reply function sends a reply with an encoded payload.
• send_reply_bytes_batch function send a batch of replies.

pub async fn send_reply_bytes_batch( &self, args: impl IntoIterator<Item = (MessageId, impl AsRef<[u8]>, u64, u128)> + Clone, ) -> Result<(Vec<Result<(MessageId, ProgramId, u128)>>, H256)>

Send a batch of replies.

A batch is a set of replies to be sent within one function call. Every entry of the args iterator is a tuple of parameters used in the send_reply_bytes function. It is useful when replying to several programs at once.

The output for each call slightly differs from send_reply_bytes as the destination program id is also returned in the resulting tuple.

pub async fn send_reply( &self, reply_to_id: MessageId, payload: impl Encode, gas_limit: u64, value: u128, ) -> Result<(MessageId, u128, H256)>

Same as send_reply_bytes, but sends a reply with encoded payload.

pub async fn upload_code( &self, code: impl AsRef<[u8]>, ) -> Result<(CodeId, H256)>

Upload Wasm code to be used for creating a new program.

Sends the pallet_gear::upload_code extrinsic.

This function returns a tuple with a code identifier and a hash of the block with the code uploading transaction. The code identifier can be used when creating a program using the create_program function.

See also

• create_program function creates a program from a previously uploaded code and initializes it.
• upload_program function uploads a new program and initialize it.

pub async fn upload_code_batch( &self, args: impl IntoIterator<Item = impl AsRef<[u8]>>, ) -> Result<(Vec<Result<CodeId>>, H256)>

Upload a batch of codes.

A batch is a set of codes to be uploaded within one function call. Every entry of the args iterator is a byte slice used in the upload_code function. It is useful when deploying a multi-program dApp.

pub async fn upload_code_by_path( &self, path: impl AsRef<Path>, ) -> Result<(CodeId, H256)>

Upload Wasm code from the file referenced by path to be used for creating a new program.

Same as upload_code, but reads the code from a file instead of using a byte vector.

Works with absolute and relative paths (relative to the root dir of the repo).

pub async fn upload_program_bytes( &self, code: impl AsRef<[u8]>, salt: impl AsRef<[u8]>, payload: impl AsRef<[u8]>, gas_limit: u64, value: u128, ) -> Result<(MessageId, ProgramId, H256)>

Upload a new program and initialize it with a byte slice payload.

Sends the pallet_gear::upload_program extrinsic.

Parameters:

• code is the byte slice containing a binary Wasm code of the program;
• salt is the arbitrary data needed to generate an address for a new program (control of salt uniqueness is entirely on the function caller’s side);
• payload vector contains data to be processed in the init function of the newly deployed “child” program;
• gas_limit is the maximum gas amount allowed to spend for the program creation and initialization;
• value to be transferred to the program’s account during initialization.

See also

• create_program_bytes function creates a program from a previously uploaded code.
• upload_code function uploads a code and returns its identifier.
• upload_program function uploads a program and initializes it with an encoded payload.

pub async fn upload_program_bytes_batch( &self, args: impl IntoIterator<Item = (impl AsRef<[u8]>, impl AsRef<[u8]>, impl AsRef<[u8]>, u64, u128)>, ) -> Result<(Vec<Result<(MessageId, ProgramId)>>, H256)>

Upload a batch of programs.

A batch is a set of programs to be uploaded within one function call. Every entry of the args iterator is a tuple used in the upload_program_bytes function. It is useful when deploying a multi-program dApp.

pub async fn upload_program_bytes_by_path( &self, path: impl AsRef<Path>, salt: impl AsRef<[u8]>, payload: impl AsRef<[u8]>, gas_limit: u64, value: u128, ) -> Result<(MessageId, ProgramId, H256)>

Upload a new program from the file referenced by path and initialize it with a byte slice payload.

Same as upload_program_bytes, but reads the program from a file instead of using a byte vector.

Works with absolute and relative paths (relative to the root dir of the repo).

pub async fn upload_program( &self, code: impl AsRef<[u8]>, salt: impl AsRef<[u8]>, payload: impl Encode, gas_limit: u64, value: u128, ) -> Result<(MessageId, ProgramId, H256)>

Same as upload_program_bytes, but initializes a newly uploaded program with an encoded payload.

See also

• create_program function creates a program from a previously uploaded code.
• upload_code function uploads a code and returns its identifier.

pub async fn upload_program_by_path( &self, path: impl AsRef<Path>, salt: impl AsRef<[u8]>, payload: impl Encode, gas_limit: u64, value: u128, ) -> Result<(MessageId, ProgramId, H256)>

Upload a new program from the file referenced by path and initialize it with an encoded payload.

Same as upload_program, but reads the program from a file instead of using a byte vector.

Works with absolute and relative paths (relative to the root dir of the repo).

pub async fn set_code(&self, code: impl AsRef<[u8]>) -> Result<H256>

Upgrade the runtime with the code containing the Wasm code of the new runtime.

Sends the pallet_system::set_code extrinsic.

pub async fn set_code_by_path(&self, path: impl AsRef<Path>) -> Result<H256>

Upgrade the runtime by reading the code from the file located at the path.

Same as set_code, but reads the runtime code from a file instead of using a byte vector.

pub async fn set_code_without_checks( &self, code: impl AsRef<[u8]>, ) -> Result<H256>

Upgrade the runtime with the code containing the Wasm code of the new runtime but without checks.

Sends the pallet_system::set_code_without_checks extrinsic.

pub async fn set_code_without_checks_by_path( &self, path: impl AsRef<Path>, ) -> Result<H256>

Upgrade the runtime by reading the code from the file located at the path.

Same as set_code_without_checks, but reads the runtime code from a file instead of using a byte vector.

pub async fn force_set_balance( &self, to: impl Into<MultiAddress<AccountId32, ()>>, new_free: u128, ) -> Result<H256>

Set the free balance of the to account to new_free.

Sends the pallet_balances::set_balance extrinsic.

pub async fn upload_code_with_voucher( &self, voucher_id: VoucherId, code: impl AsRef<[u8]>, ) -> Result<(CodeId, H256)>

Same as upload_code, but upload code using voucher.

pub async fn send_message_bytes_with_voucher( &self, voucher_id: VoucherId, destination: ProgramId, payload: impl AsRef<[u8]>, gas_limit: u64, value: u128, keep_alive: bool, ) -> Result<(MessageId, H256)>

Same as send_message_bytes, but sends a message using voucher.

pub async fn send_message_with_voucher( &self, voucher_id: VoucherId, destination: ProgramId, payload: impl Encode, gas_limit: u64, value: u128, keep_alive: bool, ) -> Result<(MessageId, H256)>

Same as send_message_bytes_with_voucher, but sends a message with encoded payload.

pub async fn send_reply_bytes_with_voucher( &self, voucher_id: VoucherId, reply_to_id: MessageId, payload: impl AsRef<[u8]>, gas_limit: u64, value: u128, keep_alive: bool, ) -> Result<(MessageId, u128, H256)>

Same as send_reply_bytes, but sends a reply using voucher.

pub async fn send_reply_with_voucher( &self, voucher_id: VoucherId, reply_to_id: MessageId, payload: impl Encode, gas_limit: u64, value: u128, keep_alive: bool, ) -> Result<(MessageId, u128, H256)>

Same as send_reply_bytes_with_voucher, but sends a reply with encoded payload.

impl GearApi

pub async fn calculate_create_gas( &self, origin: Option<H256>, code_id: CodeId, payload: Vec<u8>, value: u128, allow_other_panics: bool, ) -> Result<GasInfo>

Execute an RPC to calculate the gas required to create a program from a code and process an initialization message.

Actually sends the gear_calculateInitCreateGas RPC to the node. The function’s parameters are:

• origin (optional) is the caller’s public address;
• code_id is the uploaded code identifier that can be obtained by calling the upload_code function;
• payload vector contains data to be processed by the program;
• value to be transferred to the program’s account;
• allow_other_panics flag indicates ignoring a trap during the program’s execution;
• at (optional) allows executing the RPC at the specified block identified by its hash.

pub async fn calculate_create_gas_at( &self, origin: Option<H256>, code_id: CodeId, payload: Vec<u8>, value: u128, allow_other_panics: bool, at: Option<H256>, ) -> Result<GasInfo>

Same as calculate_create_gas, but calculates the gas at the block identified by its hash.

pub async fn calculate_upload_gas( &self, origin: Option<H256>, code: Vec<u8>, payload: Vec<u8>, value: u128, allow_other_panics: bool, ) -> Result<GasInfo>

Execute an RPC to calculate the gas required to upload a program and process an initialization message.

Actually sends the gear_calculateInitUploadGas RPC to the node. The function’s parameters are:

• origin (optional) is the caller’s public address;
• code is the buffer containing the Wasm binary code of the Gear program;
• payload vector contains data to be processed by the program;
• value to be transferred to the program’s account;
• allow_other_panics flag indicates ignoring a trap during the program’s execution;
• at (optional) allows executing the RPC at the specified block identified by its hash.

pub async fn calculate_upload_gas_at( &self, origin: Option<H256>, code: Vec<u8>, payload: Vec<u8>, value: u128, allow_other_panics: bool, at: Option<H256>, ) -> Result<GasInfo>

Same as calculate_upload_gas, but calculates the gas at the block identified by its hash.

pub async fn calculate_handle_gas( &self, origin: Option<H256>, destination: ProgramId, payload: Vec<u8>, value: u128, allow_other_panics: bool, ) -> Result<GasInfo>

Execute an RPC to calculate the gas required to handle a message.

Actually sends the gear_calculateHandleGas RPC to the node. The function’s parameters are:

• origin (optional) is the caller’s public address;
• destination is the program address;
• payload vector contains data to be processed by the program;
• value to be transferred to the program’s account;
• allow_other_panics flag indicates ignoring a trap during the program’s execution;
• at (optional) allows executing the RPC at the specified block identified by its hash.

pub async fn calculate_handle_gas_at( &self, origin: Option<H256>, destination: ProgramId, payload: Vec<u8>, value: u128, allow_other_panics: bool, at: Option<H256>, ) -> Result<GasInfo>

Same as calculate_handle_gas, but calculates the gas at the block identified by its hash.

pub async fn calculate_reply_gas( &self, origin: Option<H256>, message_id: MessageId, payload: Vec<u8>, value: u128, allow_other_panics: bool, ) -> Result<GasInfo>

Execute an RPC to calculate the gas required to reply to the received message from the mailbox.

Actually sends the gear_calculateReplyGas RPC to the node. The function’s parameters are:

• origin (optional) is the caller’s public address;
• message_id is a message identifier required to find it in the mailbox;
• exit_code is the status code of the reply;
• payload vector contains data to be processed by the program;
• value to be transferred to the program’s account;
• allow_other_panics flag indicates ignoring a trap during the program’s execution;
• at (optional) allows executing the RPC at the specified block identified by its hash.

pub async fn calculate_reply_gas_at( &self, origin: Option<H256>, message_id: MessageId, payload: Vec<u8>, value: u128, allow_other_panics: bool, at: Option<H256>, ) -> Result<GasInfo>

Same as calculate_reply_gas, but calculates the gas at the block identified by its hash.

pub async fn read_state_bytes( &self, program_id: ProgramId, payload: Vec<u8>, ) -> Result<Vec<u8>>

Read the program’s state as a byte vector.

pub async fn read_state_bytes_at( &self, program_id: ProgramId, payload: Vec<u8>, at: Option<H256>, ) -> Result<Vec<u8>>

Same as read_state_bytes, but reads the program’s state at the block identified by its hash.

pub async fn read_state<D: Decode>( &self, program_id: ProgramId, payload: Vec<u8>, ) -> Result<D>

Read the program’s state as decoded data.

pub async fn read_state_at<D: Decode>( &self, program_id: ProgramId, payload: Vec<u8>, at: Option<H256>, ) -> Result<D>

Same as read_state, but reads the program’s state at the block identified by its hash.

pub async fn read_state_bytes_using_wasm( &self, program_id: ProgramId, payload: Vec<u8>, fn_name: &str, wasm: Vec<u8>, argument: Option<Vec<u8>>, ) -> Result<Vec<u8>>

Read the program’s state as a byte vector using a meta Wasm.

pub async fn read_state_bytes_using_wasm_at( &self, program_id: ProgramId, payload: Vec<u8>, fn_name: &str, wasm: Vec<u8>, argument: Option<Vec<u8>>, at: Option<H256>, ) -> Result<Vec<u8>>

Same as read_state_bytes_using_wasm, but reads the program’s state at the block identified by its hash.

pub async fn read_state_using_wasm<E: Encode, D: Decode>( &self, program_id: ProgramId, payload: Vec<u8>, fn_name: &str, wasm: Vec<u8>, argument: Option<E>, ) -> Result<D>

Read the program’s state as decoded data using a meta Wasm.

pub async fn read_state_using_wasm_at<E: Encode, D: Decode>( &self, program_id: ProgramId, payload: Vec<u8>, fn_name: &str, wasm: Vec<u8>, argument: Option<E>, at: Option<H256>, ) -> Result<D>

Same as read_state_using_wasm, but reads the program’s state at the block identified by its hash.

pub async fn read_state_bytes_using_wasm_by_path( &self, program_id: ProgramId, payload: Vec<u8>, fn_name: &str, path: impl AsRef<Path>, argument: Option<Vec<u8>>, ) -> Result<Vec<u8>>

Read the program’s state using a meta Wasm file referenced by its path.

pub async fn read_state_bytes_using_wasm_by_path_at( &self, program_id: ProgramId, payload: Vec<u8>, fn_name: &str, path: impl AsRef<Path>, argument: Option<Vec<u8>>, at: Option<H256>, ) -> Result<Vec<u8>>

Same as read_state_using_wasm_by_path, but reads the program’s state at the block identified by its hash.

pub async fn read_state_using_wasm_by_path<E: Encode, D: Decode>( &self, program_id: ProgramId, payload: Vec<u8>, fn_name: &str, path: impl AsRef<Path>, argument: Option<E>, ) -> Result<D>

Read the program’s state using a meta Wasm file referenced by its path.

pub async fn read_state_using_wasm_by_path_at<E: Encode, D: Decode>( &self, program_id: ProgramId, payload: Vec<u8>, fn_name: &str, path: impl AsRef<Path>, argument: Option<E>, at: Option<H256>, ) -> Result<D>

Same as read_state_using_wasm_by_path, but reads the program’s state at the block identified by its hash.

pub async fn read_metahash(&self, program_id: ProgramId) -> Result<H256>

Read the program’s metahash.

pub async fn read_metahash_at( &self, program_id: ProgramId, at: Option<H256>, ) -> Result<H256>

Same as read_metahash, but read the program’s metahash at the block identified by its hash.

pub async fn calculate_reply_for_handle( &self, origin: Option<H256>, destination: ProgramId, payload: Vec<u8>, gas_limit: u64, value: u128, ) -> Result<ReplyInfo>

Execute an RPC call is used to figure out the reply on calling Gear::send_message(..).

Actually sends the gear_calculateReplyForHandle RPC to the node. The function’s parameters are:

• origin (optional) is the caller’s public address;
• destination is the program address;
• payload vector contains data to be processed by the program;
• gas_limit: maximum amount of gas the program can spend before it is halted.
• value to be transferred to the program’s account;
• at (optional) allows executing the RPC at the specified block identified by its hash.

pub async fn calculate_reply_for_handle_at( &self, origin: Option<H256>, destination: ProgramId, payload: Vec<u8>, gas_limit: u64, value: u128, at: Option<H256>, ) -> Result<ReplyInfo>

Same as calculate_reply_for_handle, but calculates the gas at the block identified by its hash.

impl GearApi

pub fn block_gas_limit(&self) -> Result<u64>

Return the total gas limit per block (also known as a gas budget).

pub fn expected_block_time(&self) -> Result<u64>

The expected average block time at which BABE should be creating blocks.

Since BABE is probabilistic it is not trivial to figure out what the expected average block time should be based on the slot duration and the security parameter c (where 1 - c represents the probability of a slot being empty).

pub async fn last_block_hash(&self) -> Result<H256>

Return a hash of the last block.

pub async fn last_block_number(&self) -> Result<u32>

Return a number of the last block (also known as block height).

pub async fn last_events(&self) -> Result<Vec<RuntimeEvent>>

Return vector of events contained in the last block.

pub async fn block_number_at(&self, block_hash: H256) -> Result<u32>

Return a number of the specified block identified by the block_hash.

pub async fn get_block_hash(&self, block_number: u32) -> Result<H256>

Get a hash of a block identified by its block_number.

pub async fn last_block_timestamp(&self) -> Result<u64>

Return a timestamp of the last block.

The timestamp is the number of milliseconds elapsed since the Unix epoch.

pub async fn events_at(&self, block_hash: H256) -> Result<Vec<RuntimeEvent>>

Return vector of events contained in the specified block identified by the block_hash.

pub async fn events_since( &self, block_hash: H256, max_depth: usize, ) -> Result<Vec<RuntimeEvent>>

Return vector of events contained in blocks since the block identified by the block_hash but no more than in max_depth blocks.

pub async fn queue_processing_enabled(&self) -> Result<bool>

Check whether the message queue processing is stopped or not.

pub async fn queue_processing_stalled(&self) -> Result<bool>

Looks at two blocks from the stream and checks if the Gear block number has grown from block to block or not.

impl GearApi

pub async fn get_mailbox_message( &self, message_id: MessageId, ) -> Result<Option<(UserStoredMessage, Interval<u32>)>>

Get a message identified by message_id from the mailbox.

pub async fn get_mailbox_account_message( &self, account_id: impl IntoAccountId32, message_id: MessageId, ) -> Result<Option<(UserStoredMessage, Interval<u32>)>>

Get a message identified by message_id from the account_id’s mailbox.

pub async fn get_mailbox_account_messages( &self, account_id: impl IntoAccountId32, count: u32, ) -> Result<Vec<(UserStoredMessage, Interval<u32>)>>

Get up to count messages from the mailbox for the provided account_id.

pub async fn get_mailbox_messages( &self, count: u32, ) -> Result<Vec<(UserStoredMessage, Interval<u32>)>>

Get up to count messages from the mailbox.

pub async fn total_balance( &self, account_id: impl IntoAccountId32, ) -> Result<u128>

Get the total balance of the account identified by account_id.

Total balance includes free and reserved funds.

pub async fn free_balance( &self, account_id: impl IntoAccountId32, ) -> Result<u128>

Get the free funds balance of the account identified by account_id.

pub async fn reserved_balance( &self, account_id: impl IntoAccountId32, ) -> Result<u128>

Get the reserved funds balance of the account identified by account_id.

impl GearApi

pub async fn issue_voucher( &self, spender: ProgramId, balance: u128, programs: Option<Vec<ProgramId>>, code_uploading: bool, duration: u32, ) -> Result<(VoucherId, H256)>

Issue a new voucher.

Returns issued voucher_id at specified at_block_hash.

Arguments:

• spender: user id that is eligible to use the voucher;
• balance: voucher balance could be used for transactions fees and gas;
• programs: pool of programs spender can interact with, if None - means any program, limited by Config param;
• code_uploading: allow voucher to be used as payer for upload_code transactions fee;
• duration: amount of blocks voucher could be used by spender and couldn’t be revoked by owner. Must be out in [MinDuration; MaxDuration] constants. Expiration block of the voucher calculates as: current bn (extrinsic exec bn) + duration + 1.

pub async fn update_voucher( &self, spender: ProgramId, voucher_id: VoucherId, move_ownership: Option<ProgramId>, balance_top_up: Option<u128>, append_programs: Option<Option<Vec<ProgramId>>>, code_uploading: Option<bool>, prolong_duration: u32, ) -> Result<(VoucherId, H256)>

Update existing voucher.

This extrinsic updates existing voucher: it can only extend vouchers rights in terms of balance, validity or programs to interact pool.

Can only be called by the voucher owner.

Arguments:

• spender: account id of the voucher spender;
• voucher_id: voucher id to be updated;
• move_ownership: optionally moves ownership to another account;
• balance_top_up: optionally top ups balance of the voucher from origins balance;
• append_programs: optionally extends pool of programs by Some(programs_set) passed or allows it to interact with any program by None passed;
• code_uploading: optionally allows voucher to be used to pay fees for upload_code extrinsics;
• prolong_duration: optionally increases expiry block number. If voucher is expired, prolongs since current bn. Validity prolongation (since current block number for expired or since storage written expiry) should be in [MinDuration; MaxDuration], in other words voucher couldn’t have expiry greater than current block number + MaxDuration.

pub async fn revoke_voucher( &self, spender: ProgramId, voucher_id: VoucherId, ) -> Result<(VoucherId, H256)>

Revoke existing voucher.

This extrinsic revokes existing voucher, if current block is greater than expiration block of the voucher (it is no longer valid).

Currently it means sending of all balance from voucher account to voucher owner without voucher removal from storage map, but this behavior may change in future, as well as the origin validation: only owner is able to revoke voucher now.

Arguments:

• spender: account id of the voucher spender;
• voucher_id: voucher id to be revoked.

pub async fn decline_voucher( &self, voucher_id: VoucherId, ) -> Result<(VoucherId, H256)>

Decline existing and not expired voucher.

This extrinsic expires voucher of the caller, if it’s still active, allowing it to be revoked.

Arguments:

• voucher_id: voucher id to be declined.

pub async fn decline_voucher_with_voucher( &self, voucher_id: VoucherId, ) -> Result<(VoucherId, H256)>

Decline existing and not expired voucher with voucher.

impl GearApi

pub fn builder() -> GearApiBuilder

Create api builder

pub async fn init(address: WSAddress) -> Result<Self>

Create and init a new GearApi specified by its address on behalf of the default Alice user.

pub async fn init_with( address: WSAddress, suri: impl AsRef<str>, ) -> Result<Self>

Create and init a new GearApi specified by its address and suri.

SURI is a Substrate URI that identifies a user by a mnemonic phrase or provides default users from the keyring (e.g., “//Alice”, “//Bob”, etc.). The password for URI should be specified in the same suri, separated by the ':' char.

pub fn with(self, suri: impl AsRef<str>) -> Result<Self>

Change SURI to the provided suri and return Self.

pub async fn dev() -> Result<Self>

Create and init a new GearApi instance that will be used with the local node working in developer mode (running with --dev argument).

pub async fn dev_from_path(path: impl AsRef<OsStr>) -> Result<Self>

Create and init a new GearApi instance via spawning a new node process in development mode using the --dev flag and listening on an a random port number. The node process uses a binary specified by the path param. Ideally, the binary should be downloaded by means of CI pipeline from https://get.gear.rs.

pub async fn vara_dev_from_path(path: impl AsRef<OsStr>) -> Result<Self>

Create and init a new GearApi instance via spawning a new node process in development mode using the --chain=vara-dev, --validator, --tmp flags and listening on an a random port number. The node process uses a binary specified by the path param. Ideally, the binary should be downloaded by means of CI pipeline from https://get.gear.rs.

pub fn print_node_logs(&mut self)

Print node logs.

pub async fn vara_testnet() -> Result<Self>

Create and init a new GearApi instance that will be used with the public Vara testnet node.

pub async fn vara() -> Result<Self>

Create and init a new GearApi instance that will be used with the public Vara node.

pub async fn subscribe(&self) -> Result<EventListener>

Create an EventListener to subscribe and handle continuously incoming events.

pub fn set_nonce(&mut self, nonce: u64)

Set the number used once (nonce) that will be used while sending extrinsics.

If set, this nonce is added to the extrinsic and provides a unique identifier of the transaction sent by the current account. The nonce shows how many prior transactions have occurred from this account. This helps protect against replay attacks or accidental double-submissions.

pub async fn rpc_nonce(&self) -> Result<u64>

Get the next number used once (nonce) from the node.

Actually sends the system_accountNextIndex RPC to the node.

pub fn account_id(&self) -> &AccountId32

Return the signer account address.

Examples

use gclient::{GearApi, Result};
use gsdk::ext::sp_runtime::AccountId32;

#[tokio::test]
async fn account_test() -> Result<()> {
    let api = GearApi::dev().await?;
    let alice_id = hex!("d43593c715fdd31c61141abd04a99fd6822c8558854ccde39a5684e7a56da27d");
    assert_eq!(api.account_id(), &AccountId32::from(alice_id));
    Ok(())
}

Trait Implementations

impl Clone for GearApi

fn clone(&self) -> GearApi

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl From<(Api, Pair)> for GearApi

fn from((api, signer): (Api, Pair)) -> Self

Converts to this type from the input type.

impl From<Api> for GearApi

fn from(api: Api) -> Self

Converts to this type from the input type.

impl From<GearApi> for Signer

fn from(api: GearApi) -> Self

Converts to this type from the input type.

impl From<Signer> for GearApi

fn from(signer: Signer) -> Self

Converts to this type from the input type.