Connection

To participate in the network, we need to send requests and receive responses from a node in the network. We have tools like ethers.js, web3.js and FCL helps to compose request payloads and decode responses.

Overview

The ConnectionState defines the ability to interact with a blockchain network.

interface ConnectionState {
    /** Get web3 SDK instance */
    getWeb3?: (initial?: Web3ConnectionOptions) => Promise<Web3>
    /** Get web3 provider instance */
    getWeb3Provider?: (initial?: Web3ConnectionOptions) => Promise<Web3Provider>
    /** Get connection */
    getConnection?: (initial?: Web3ConnectionOptions) => Promise<Web3Connection>
}

The primary task of this state is to implement a Connection for the network. It describes the commonality of a network to be adopted.

interface Connection {
    /** Get the web3 SDK instance. */
    getWeb3(initial?: Web3ConnectionOptions): Promise<Web3>
    /** Get the latest block number. */
    getBlockNumber(initial?: Web3ConnectionOptions): Promise<number>
    /** Sign message */
    signMessage(dataToSign: string, signType?: string, initial?: Web3ConnectionOptions): Promise<Signature>
    /** Send a transaction and wait for mining */
    sendTransaction(transaction: Transaction, initial?: Web3ConnectionOptions): Promise<string>
    /** Build connection */
    connect(initial?: Web3ConnectionOptions): Promise<Account<ChainId>>
}

With a Connection, we can do:

• To create an SDK instance.
• To get the instant block number.
• To sign a plain message.
• To send a transaction and wait for confirmation.
• To connect to a wallet provider.

In the UI components, we use useWeb3Connection to access the connection of a specific network.

const signature = await connection.signMessage(/* ... */)

Options

We could alter the connection with the options parameter in actions. It gives us the chance to override the current connection settings.

interface ConnectionOptions<ChainId, ProviderType, Transaction> {
    /** Designate the subnetwork id of the transaction. */
    chainId?: ChainId
    /** Designate the signer of the transaction. */
    account?: string
    /** Designate the provider to handle the transaction. */
    providerType?: ProviderType
    /** Fragments to merge into the transaction. */
    overrides?: Partial<Transaction>
}

To override settings in the connection scope, take options as the last parameter of the useWeb3Connection hook. It will alter every invocation on the connection.

const connection = useWeb3Connection(NetworkPluginID.PLUGIN_EVM, {
    // all invocation on the connection will send to polygon network
    chainId: ChainId.Polygon,
})

// fetch the instant block number of polygon network
const blockNumber = connection.getBlockNumber()

// fetch the instant balance of address on polygon network
const balance = connection.getBalance(address)

Moreover, each method accepts options as the last parameter, overriding settings for that invocation.

const connection = useWeb3Connection(NetworkPluginID.PLUGIN_EVM)

// fetch the instant block number of polygon network
const blockNumber = connection.getBlockNumber({
    // only this invocation gets an alteration
    chainId: ChainId.Polygon,
})

// fetch the instant balance of address on the currently selected network (might not polygon network)
const balance = connection.getBalance(address)

Usage

getWeb3

const web3 = await connection.getWeb3([options])

Get Web3 SDK instance of the currently selected network.

Parameters

1. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Promise<Web3> - The Web3 SDK instance.

Example

// get web3js instance
const connection = useWeb3Connection(NetworkPluginID.PLUGIN_EVM)

const getWeb3 = useCallback(() => {
    const web3 = await connection.getWeb3()

    // learn more: https://web3js.readthedocs.io/
    await web3.eth.callTransaction(/* ... */)
}, [connection])

// get solana SDK instance
const solanaConnection = useWeb3Connection(NetworkPluginID.PLUGIN_SOLANA)

const getSolanaWeb3 = useCallback(() => {
    const web3 = await connection.getWeb3()

    // learn more: https://docs.solana.com/developing/clients/javascript-reference
    const connection = new web3.Connection(/* ... */)
    const slot = await connection.getSlot()
}, [connection])

getWeb3Provider

getWeb3Provider(initial?: Web3ConnectionOptions): Promise<Web3Provider>

Get the internal web3 provider instance which is the fundamental description of a wallet provider. A network might define a wallet protocol. E.g., https://eips.ethereum.org/EIPS/eip-1193.

For the network that doesn't have a provider protocol, we borrow the definition from the market leader wallet. E.g., https://docs.phantom.app/integrating/extension-and-in-app-browser-web-apps/establishing-a-connection.

Parameters

1. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Promise<Web3Provider>

Example

const provider = await connection.getWeb3Provider()

// get the EIP1193 provider and send raw JSON RPC request with it
provider.request({
    id: 0,
    jsonrpc: '2.0',
    method: 'eth_getBalance',
    params: ['0x...'],
})

connect

connect(initial?: Web3ConnectionOptions): Promise<Account<ChainId>>

Build connection.

Parameters

1. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Promise<Account<ChainId>> The account object contains the connected account address and subnetwork chain id.

Example

const account = (await connection.connect()) > { account: '0x...', chainId: ChainId.Mainnet }

disconnect

disconnect(initial?: Web3ConnectionOptions): Promise<void>

Break connection.

Parameters

1. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Promise<void>

Example

await connection.disconnect()

getGasPrice

getGasPrice(initial?: Web3ConnectionOptions): Promise<string>

Get gas price.

Parameters

1. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Example

// TODO

getTokenSchema

getTokenSchema(address: string, initial?: Web3ConnectionOptions): Promise<SchemaType | undefined>

Get schema type of given token address.

Parameters

1. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Example

// TODO

getNativeToken

getNativeToken(initial?: Web3ConnectionOptions): Promise<FungibleToken<ChainId, SchemaType>>

Get a native fungible token.

Parameters

1. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Example

// TODO

getFungibleToken

getFungibleToken(address: string, initial?: Web3ConnectionOptions): Promise<FungibleToken<ChainId, SchemaType>>

Get a fungible token.

Parameters

1. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Example

// TODO

getNonFungibleToken

getNonFungibleToken(
    address: string,
    tokenId: string,
    schema?: SchemaType,
    initial?: Web3ConnectionOptions,
): Promise<NonFungibleToken<ChainId, SchemaType>>

Get a non-fungible token.

Parameters

1. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Example

// TODO

getNonFungibleTokenOwnership

getNonFungibleTokenOwnership(
    address: string,
    tokenId: string,
    owner: string,
    schema?: SchemaType,
    initial?: Web3ConnectionOptions,
): Promise<boolean>

Detect if a non-fungible token is owned by a specific account.

Parameters

1. address - string. The token program address.
2. tokenId - string. The id of the token.
3. owner - string. The owner's address for detection
4. schema - SchemaType. An optional token schema type.
5. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Promise<boolean>

Example

const owner = '0x...'
const owned = await connection.getNonFungibleTokenOwnership(address, tokenId, owner)

getNonFungibleTokenMetadata

getNonFungibleTokenMetadata(
    address: string,
    tokenId: string,
    schema?: SchemaType,
    initial?: Web3ConnectionOptions,
): Promise<NonFungibleTokenMetadata<ChainId>>

Get a non-fungible token.

Parameters

1. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Example

// TODO

getNonFungibleTokenContract

getNonFungibleTokenContract(
    address: string,
    schema?: SchemaType,
    initial?: Web3ConnectionOptions,
): Promise<NonFungibleTokenContract<ChainId, SchemaType>>

Get a non-fungible token contract.

Parameters

1. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Example

// TODO

getNonFungibleTokenCollection

getNonFungibleTokenCollection(
    address: string,
    schema?: SchemaType,
    initial?: Web3ConnectionOptions,
): Promise<NonFungibleTokenCollection<ChainId>>

Get a non-fungible token collection.

Parameters

1. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Example

// TODO

getNativeTokenBalance

getNativeTokenBalance(initial?: Web3ConnectionOptions): Promise<string>

Get a native fungible token balance. Alias of getBalance.

Parameters

1. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Promise<string> The balance as a hex string.

Example

const balance = await connection.getNativeTokenBalance()

getFungibleTokenBalance

getFungibleTokenBalance(address: string, initial?: Web3ConnectionOptions): Promise<string>

Get fungible token balance.

Parameters

1. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Promise<string> The balance as a hex string.

Example

const balance = await connection.getFungibleTokenBalance()

getNonFungibleTokenBalance

getNonFungibleTokenBalance(address: string, tokenId?: string, schema?: SchemaType, initial?: Web3ConnectionOptions): Promise<string>

Get a non-fungible token balance.

Parameters

1. address - string. The token program address.
2. tokenId - string. The id of the token.
3. schema - SchemaType. An optional token schema type.
4. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Promise<string> The balance as a hex string.

Example

const balance = await connection.getNonFungibleTokenBalance()

getFungibleTokensBalance

getFungibleTokensBalance(listOfAddress: string[], initial?: Web3ConnectionOptions): Promise<Record<string, string>>

Get fungible token balance.

Parameters

1. listOfAddress - string[].
2. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Example

const listOfBalance = await connection.getFungibleTokensBalance(listOfAddress)

getNonFungibleTokensBalance

getNonFungibleTokensBalance(
    listOfAddress: string[],
    initial?: Web3ConnectionOptions,
): Promise<Record<string, string>>

Get a non-fungible token balance.

Parameters

1. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Example

// TODO

getAccount

getAccount(initial?: Web3ConnectionOptions): Promise<string>

Get the currently connected account.

Parameters

1. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Promise<string> The account address.

Example

const account = await connection.getAccount()

getChainId

getChainId(initial?: Web3ConnectionOptions): Promise<ChainId>

Get the current chain id.

Parameters

1. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Promise<ChainId> The chain id must be a natural number.

Example

const chainId = await connection.getChainId()

getBlock

getBlock(no: number, initial?: Web3ConnectionOptions): Promise<Block | null>

Get a specific block.

Parameters

1. no - number. To specific the number of the block.
2. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Promise<Block | null> The block object defined in Types.

Example

// learn more: https://web3js.readthedocs.io/en/v1.7.3/web3-eth.html#getblock
const block = await connection.getBlock()

// learn more: https://docs.solana.com/developing/clients/jsonrpc-api#getblock
const solanaBlock = await solanaConnection.getBlock()

getBlockNumber

getBlockNumber(initial?: Web3ConnectionOptions): Promise<number>

Get the latest block number.

Parameters

1. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Promise<number>

Example

const blockNumber = await connection.getBlockNumber()

getBlockTimestamp

getBlockTimestamp(initial?: Web3ConnectionOptions): Promise<number>

Get the latest block UNIX timestamp.

Parameters

1. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Promise<number>

Example

const timestamp = await connection.getBlockNumber()

// convert to a normal Date object
const date = new Date(timestamp * 1000)

getBalance

getBalance(address: string, initial?: Web3ConnectionOptions): Promise<string>

Get the latest balance of the account.

Parameters

1. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Promise<string The balance as a hex string.

Example

const balance = await connection.getBalance()

// format as Ether
formatBalance(balance, 18)

getTransaction

getTransaction(id: string, initial?: Web3ConnectionOptions): Promise<TransactionDetailed | null>

Get the detailed information of a transaction.

Parameters

1. id - string. The id of the transaction.
2. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Promise<Transaction> The transaction object defined in Types.

Example

const transaction = await connection.getTransaction(id)

getTransactionStatus

getTransactionStatus(id: string, initial?: Web3ConnectionOptions): Promise<TransactionStatusType>

Get the latest transaction status. A transaction could be one of three statuses NOT_DEPEND, SUCCEED or FAILED.

# a succeed transaction: transit from initial status to successful status
NOT_DEPEND(START) -> SUCCEED(END)

# a failed transaction: transit from initial status to failure status
NOT_DEPEND(START) -> FAILED(END)

Parameters

1. id - string. The id of a transaction.
2. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Promise<TransactionStatusType> A computed transaction status type.

Example

const status = await connection.getTransactionStatus(id)

getTransactionNonce

getTransactionNonce(address: string, initial?: Web3ConnectionOptions): Promise<number>

Get the latest transaction nonce.

Parameters

1. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Example

// TODO

getTransactionReceipt

getTransactionReceipt(id: string, initial?: Web3ConnectionOptions): Promise<TransactionReceipt | null>

Get the transaction receipt.

Parameters

1. id - string. The id of the transaction.
2. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Promise<TransactionReceipt> The tranaction receipt object defined in Types.

Example

const receipt = await connection.getTransactionReceipt(id)

getCode

getCode(address: string, initial?: Web3ConnectionOptions): Promise<string>

Get the source code of an on-chain program.

Parameters

1. address - string. The address of the on-chain program.
2. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Promise<string> The source code of the program.

Example

// get USDC contract source
const code = await connection.getCode('0x')
// > 0x...

switchChain

switchChain?: (chainId: ChainId, initial?: Web3ConnectionOptions) => Promise<void>

Switch to a subnetwork.

Parameters

1. chainId - ChainId. The chain id of the subnetwork.
2. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Promise<void>

Example

// switch to Ethereum mainnet
await connection.switchChain(ChainId.Mainnet)

// switch to polygon network
await connection.switchChainId(ChainId.Polygon)

signMessage

const signature = await connection.signMessage(message, [signType], [options])

Sign data using the currently selected account. This account could be overrided with options.

Parameters

1. message - string. Data to sign. A UTF8 string.
2. signType - string. Switch between multiple sign algorithms. The default value for EVM is personalSign and supports typed data sign (v4) with typedDataSign.
3. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Promise<srting> - The signed signature.

Example

const message = 'Hello World'
const signature = await connection.signMessage(message, 'personalSign')
// > `0x...`

verifyMessage

verifyMessage(
    dataToVerify: string,
    signature: Signature,
    signType?: string,
    initial?: Web3ConnectionOptions,
): Promise<boolean>

Verify a message signature.

Parameters

1. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Promise<boolean>

Example

const message = 'Hello World'
const signature = await connection.signMessage(message, 'personalSign')
const verified = await connection.verifyMessage(message, signature, 'personalSign')
// > true

transferFungibleToken

transferFungibleToken(
    address: string,
    recipient: string,
    amount: string,
    memo?: string,
    initial?: Web3ConnectionOptions,
): Promise<string>

Transfer fungible token to.

Parameters

1. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Example

// TODO

transferNonFungibleToken

transferNonFungibleToken(
    address: string | undefined,
    recipient: string,
    tokenId: string,
    amount: string,
    schema?: SchemaType,
    initial?: Web3ConnectionOptions,
): Promise<string>

Transfer non-fungible token to.

Parameters

1. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Example

// TODO

signTransaction

signTransaction(transaction: Transaction, initial?: Web3ConnectionOptions): Promise<TransactionSignature>

Sign a transaction. Most time, a transaction signature is a plain string.

Parameters

1. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Promise<TransactionSignature>. An transaction signature defined in Types.

Example

const signature = await connection.signTransaction(transaction)

signTransactions

signTransactions(transactions: Transaction[], initial?: Web3ConnectionOptions): Promise<TransactionSignature[]>

Sign multiple transactions.

Parameters

1. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Promise<Array<TransactionSignature>>. An array of transaction signatures.

Example

const signatures = await connection.signTransactions(transactions)

callTransaction

callTransaction(transaction: Transaction, initial?: Web3ConnectionOptions): Promise<string>

Query a transaction.

Parameters

1. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Example

// TODO

sendTransaction

sendTransaction(transaction: Transaction, initial?: Web3ConnectionOptions): Promise<string>

Send a transaction and wait for mining.

Parameters

1. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Example

// TODO

sendSignedTransaction

sendSignedTransaction(signature: TransactionSignature, initial?: Web3ConnectionOptions): Promise<string>

Send a signed transaction.

Parameters

1. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Example

// TODO

replaceTransaction

replaceTransaction(id: string, transaction: Transaction, initial?: Web3ConnectionOptions): Promise<void>

To replace a sent transaction before it gets confirmation.

Parameters

1. id - string. The id of the transaction to be replaced.
2. transaction - Transaction. The substitute transaction.
3. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Promise<void>

Example

// TODO

const id = await connection.sendTransaction({
    /* ... */
    gasPrice: toHex(300000),
})

// replace the previously sent transaction with a higher gasPrice
await connection.replaceTransation(id, {
    /* ... */
    gasPrice: toHex(400000),
})

cancelTransaction

cancelTransaction(id: string, initial?: Web3ConnectionOptions): Promise<void>

To cancel a sent transaction before it gets confirmation.

Parameters

1. id - string. The id of the transaction to be canceled.
2. initial - Web3ConnectionOptions. An optional object to override the connection settings.

Returns

Promise<void>

Example

const hash = await connection.sendTransaction(transaction)

// cancel the previous sent transation
await connection.cancelTransaction(hash)