Client Capabilities
The @ocap/client library provides a robust and intuitive way to interact with Forge blockchain nodes. It abstracts away the complexities of low-level blockchain communication, allowing developers to focus on building decentralized applications. This section offers a high-level overview of the GraphQLClient's core functionalities, categorizing them into querying blockchain data, sending transactions (mutations), and subscribing to real-time blockchain events. It also introduces the helper methods designed to simplify transaction encoding and signing.
For more detailed information on each capability, please refer to the dedicated sections:
Core Functionalities Overview#
The GraphQLClient is designed to streamline your application's interaction with the blockchain. Its capabilities can be broadly categorized as follows:
Querying Blockchain Data#
The GraphQLClient provides a set of query methods to retrieve various types of data from the blockchain. This includes fetching information about the chain's state, specific blocks, transactions, accounts, and assets. These methods allow your application to read the current state of the blockchain efficiently.
Example: Querying Chain Information
const GraphQLClient = require('@ocap/client');
const client = new GraphQLClient('http://localhost:8210/api');
(async () => {
const chainInfo = await client.getChainInfo();
const forgeState = await client.getForgeState();
const block = await client.getBlock({ height: 2 });
console.log('getChainInfo', chainInfo);
console.log('getForgeState', forgeState);
console.log('getBlock', block);
})();This example demonstrates how to use client.getChainInfo(), client.getForgeState(), and client.getBlock() to retrieve fundamental blockchain data such as chain network details, global forge state, and specific block information.
Sending Transactions (Mutations)#
Sending transactions, also known as mutations, is how your application writes data to the blockchain. The GraphQLClient simplifies the process of creating, signing, and broadcasting transactions. It provides both low-level methods for encoding and signing, as well as convenient helper methods that combine these steps for common transaction types.
Example: Declaring an Identity
const Mcrypto = require('@ocap/mcrypto');
const GraphQLClient = require('@ocap/client');
const { fromRandom, WalletType } = require('@ocap/wallet');
const client = new GraphQLClient('http://localhost:8210/api');
(async () => {
const wallet = fromRandom(
WalletType({
role: Mcrypto.types.RoleType.ROLE_ACCOUNT,
pk: Mcrypto.types.KeyType.SECP256K1,
hash: Mcrypto.types.HashType.SHA3,
})
);
const hash = await client.declare({
moniker: 'username',
wallet,
});
console.log(hash);
})();In this example, client.declare() is a high-level helper method that handles the encoding, signing (using the provided wallet), and sending of a DeclareTx to register a new identity on the blockchain. The returned hash is the unique identifier for the submitted transaction.
Subscribing to Events#
The GraphQLClient allows your application to subscribe to real-time events on the blockchain. This push-based mechanism enables applications to react instantly to changes, such as new blocks being mined, transactions being committed, or specific account/asset state updates. While the core client provides the subscription interface, the specific event types you can subscribe to depend on the blockchain's capabilities.
For a list of available subscription methods, you can use client.getSubscriptions().
Helper Methods for Transaction Preparation#
Beyond direct query and send operations, the GraphQLClient offers a suite of helper methods that facilitate the preparation of transactions. These include methods to:
getTxEncodeMethods(): List all methods that can encode a transaction object into a binary format.getTxSignMethods(): List all methods that can sign an encoded transaction using a wallet.getTxMultiSignMethods(): List all methods for multi-party transaction signing, supporting scenarios where multiple parties need to approve a transaction.
These methods are crucial for building complex transaction flows, especially when dealing with multi-signature requirements or when you need to inspect transaction payloads before sending.
Next Steps#
This section provided a high-level overview of the GraphQLClient's capabilities. To dive deeper into specific transaction types and how to utilize the client's methods for common blockchain operations, proceed to the Transaction Types and Usage section.