dotcodeschool

dotcodeschool

Submit Feedback

Some specifics around PAPI are needed

As explained in a previous step, running the CLI command papi add, downloads the metadata for a chain and then uses that metadata to generate all the type descriptors, placing them under the .papi directory.

It's important to know that the descriptors exported by the codegen should be treated as a black box. When importing the descriptors of a chain, the type might not actually match what's in runtime, and its internals are subject to change. It has to be treated as an opaque token, passing it directly to client's method: .getTypedApi(). That method returns a TypedApi interface.

TypedAPI interface

The TypedApi interface, simplifies interaction with the runtime metadata, making it easy to query storage, submit transactions, and more — all while offering a smooth developer experience.

It achieves this by utilizing the type descriptors generated by the PAPI CLI (discussed earlier), which are used to define the types available during development.

This structure allows for seamless access to chain functionality, ensuring that everything from runtime calls to storage queries is fully typed, reducing errors and making your code more reliable.

The structure of the TypedApi object looks like this:

type TypedApi = {
  query: StorageApi;
  tx: TxApi;
  event: EvApi;
  apis: RuntimeCallsApi;
  constants: ConstApi;
  compatibilityToken: Promise<CompatibilityToken>;
};

Example of using

In order to "access the chain functionality" as described the following code snippet can be used:

// Import the generated descriptor
import { dot } from "@polkadot-api/descriptors";
....
// after creating the provider and initializing the client
// use that client to get the interface by passing the decsriptor
const dotApi = client.getTypedApi(dot);
...
// Then the strongly typed interface can be used in a sync or async
// manner depending on what needs to be called from the interface
// (deep dive into more here: https://papi.how/typed/ )
const accountInfo = await dotApi.query.System.Account.getValue(address);

Looking at the last line, it is obvious that we are trying to query a chain's account information based on its address.

Breakdown of the Query:

  • dotApi: As mentioned, this is an instance that provides access to various modules and their methods of Polkadot chain
  • query: This segment of the API is used to retrieve information from the blockchain without making any changes to its state. Queries are read-only operations.
  • System: This refers to the System module, which provides foundational information about the blockchain. It includes various functionalities like querying account information, system health, and other basic parameters of the network.
  • Account: Within the System module, the Account component allows you to interact with account-specific data. This includes balances, nonce (transaction count), and the account's state.
  • getValue(address): This method retrieves the account information for a specific address provided as an argument. The address parameter should be a valid account identifier (either a public key or an address).

The returned value typically includes details such as the account's free balance, reserved balance, and potentially other state data. e.g.:

const { free, reserved } = accountInfo.data;

Just some additional context about balances

In Polkadot, the total balance of an account is computed as the sum of two components: free balance and reserved balance. Here's a breakdown:

  1. Free Balance: The free balance represents the amount of tokens that an account has available for transactions, staking, or other operations. This is the liquid balance that the user can actively spend, transfer, or use for transactions.

  2. Reserved Balance: The reserved balance is the portion of the account’s tokens that cannot be spent freely. Tokens may be reserved for various reasons such as bonding for staking, governance, certain on-chain operations (e.g., creating identity, reserving a slot in parachain auctions) a.k.a deposits. While the reserved balance is still owned by the account holder, it cannot be transferred or used until it's released from its reserved state.

  3. Total Balance: The total balance of an account is calculated as:

total_balance = free_balance + reserved_balance

This formula gives the overall account balance, but not all of it is available for transactions. The free balance is the spendable portion, while the reserved balance remains locked.

Loading...

Some specifics around PAPI are needed

As explained in a previous step, running the CLI command papi add, downloads the metadata for a chain and then uses that metadata to generate all the type descriptors, placing them under the .papi directory.

It's important to know that the descriptors exported by the codegen should be treated as a black box. When importing the descriptors of a chain, the type might not actually match what's in runtime, and its internals are subject to change. It has to be treated as an opaque token, passing it directly to client's method: .getTypedApi(). That method returns a TypedApi interface.

TypedAPI interface

The TypedApi interface, simplifies interaction with the runtime metadata, making it easy to query storage, submit transactions, and more — all while offering a smooth developer experience.

It achieves this by utilizing the type descriptors generated by the PAPI CLI (discussed earlier), which are used to define the types available during development.

This structure allows for seamless access to chain functionality, ensuring that everything from runtime calls to storage queries is fully typed, reducing errors and making your code more reliable.

The structure of the TypedApi object looks like this:

type TypedApi = {
  query: StorageApi;
  tx: TxApi;
  event: EvApi;
  apis: RuntimeCallsApi;
  constants: ConstApi;
  compatibilityToken: Promise<CompatibilityToken>;
};

Example of using

In order to "access the chain functionality" as described the following code snippet can be used:

// Import the generated descriptor
import { dot } from "@polkadot-api/descriptors";
....
// after creating the provider and initializing the client
// use that client to get the interface by passing the decsriptor
const dotApi = client.getTypedApi(dot);
...
// Then the strongly typed interface can be used in a sync or async
// manner depending on what needs to be called from the interface
// (deep dive into more here: https://papi.how/typed/ )
const accountInfo = await dotApi.query.System.Account.getValue(address);

Looking at the last line, it is obvious that we are trying to query a chain's account information based on its address.

Breakdown of the Query:

  • dotApi: As mentioned, this is an instance that provides access to various modules and their methods of Polkadot chain
  • query: This segment of the API is used to retrieve information from the blockchain without making any changes to its state. Queries are read-only operations.
  • System: This refers to the System module, which provides foundational information about the blockchain. It includes various functionalities like querying account information, system health, and other basic parameters of the network.
  • Account: Within the System module, the Account component allows you to interact with account-specific data. This includes balances, nonce (transaction count), and the account's state.
  • getValue(address): This method retrieves the account information for a specific address provided as an argument. The address parameter should be a valid account identifier (either a public key or an address).

The returned value typically includes details such as the account's free balance, reserved balance, and potentially other state data. e.g.:

const { free, reserved } = accountInfo.data;

Just some additional context about balances

In Polkadot, the total balance of an account is computed as the sum of two components: free balance and reserved balance. Here's a breakdown:

  1. Free Balance: The free balance represents the amount of tokens that an account has available for transactions, staking, or other operations. This is the liquid balance that the user can actively spend, transfer, or use for transactions.

  2. Reserved Balance: The reserved balance is the portion of the account’s tokens that cannot be spent freely. Tokens may be reserved for various reasons such as bonding for staking, governance, certain on-chain operations (e.g., creating identity, reserving a slot in parachain auctions) a.k.a deposits. While the reserved balance is still owned by the account holder, it cannot be transferred or used until it's released from its reserved state.

  3. Total Balance: The total balance of an account is calculated as:

total_balance = free_balance + reserved_balance

This formula gives the overall account balance, but not all of it is available for transactions. The free balance is the spendable portion, while the reserved balance remains locked.

Loading...

Back

Next