@therootnetwork/api

Polkadot.js helpers that bundle TRN-specific types and a one-call connect helper.

Vendor-neutral, on-chain only

Published under @therootnetwork. These talk directly to TRN nodes (WS or HTTPS) — no hosted Futureverse service in the path — so they are the safest dependency to take for projects that need to outlive the Futureverse company.

Version

1.1.0

Published

2025-07-18

License

Apache-2.0

Status

trn-active

npm

https://www.npmjs.com/package/@therootnetwork/api

Types

./dist/index.d.ts

Maintainers

karishma09, aidan-starke, zees-fv, kenvu-ai

Peer deps

@polkadot/api

Recent versions

1.0.8 · 1.0.9 · 1.0.10 · 1.0.11 · 1.0.12 · 1.0.13 · 1.0.14 · 1.1.0

## Technical notes

Why use it

You want to talk to a TRN node (mainnet Root or testnet Porcini) using the standard @polkadot/api client. This package supplies the chain-specific type bundle so calls like api.tx.futurepass.proxyExtrinsic(...) and api.query.assets.metadata(2) decode/encode correctly without you wiring types by hand.

When to skip it

You only ever touch TRN through the EVM precompiles (Solidity / viem / ethers). Then you do not need the Substrate API at all — see @therootnetwork/evm.

Pairs with

• @therootnetwork/api-types — lookup-bundle peer dep
• @therootnetwork/extrinsic — higher-level extrinsic helper
• @polkadot/api — underlying client (peer)

Alternatives

• plain @polkadot/api + manual type bundle (works) — more boilerplate, easy to drift on type names

Example

import { getApiOptions, getPublicProvider } from '@therootnetwork/api';
import { ApiPromise, WsProvider } from '@polkadot/api';

const provider = new WsProvider((await getPublicProvider('root')).wsProvider);
const api = await ApiPromise.create({ ...getApiOptions(), provider });

const head = await api.rpc.chain.getHeader();
console.log('block', head.number.toNumber());

Gotchas

• The XRP balance is stored at 6 decimals on Substrate side but exposed at 18 on EVM — convert by 1e12 when crossing.
• Always pass typesBundle (or call getApiOptions()) to ApiPromise.create — without it custom TRN types decode as Bytes.

Upstream README

@therootnetwork/api

A utility package that complements the @polkadot/api to connect and interact with the Root Network node.

Install

yarn add @polkadot/api @therootnetwork/api
yarn add -D @therootnetwork/api-types # optional, for Typescript support

Usage

• Create an API instance

import "@therootnetwork/api-types"; // optional, for Typescript support
import { ApiPromise } from "@polkadot/api";
import { getApiOptions, getPublicProvider } from "@therootnetwork/api";

const api = await ApiPromise.create({
  ...getApiOptions(),
  ...getPublicProvider("root"),
});

• Use api instance to interact with node

// query and display account data
const data = await api.query.system.account("0xE04CC55ebEE1cBCE552f250e85c57B70B2E2625b");
console.log(data.toHuman());

TypeScript Support

See api-types for more details

API

function getApiOptions()

Returns an ApiOptions object that contains necessary types, rpc methods to connect the Root Network

function getPublicProvider(network: NetworkName, useWsProvider?: boolean, useArchiveNode?: boolean)

Returns a provider instance of either WsProvider or HttpProvider that connects to TRN mainnet "root" or testnet "porcini"

function getPublicProviderUrl(network: NetworkName, useWsProvider?: boolean, useArchiveNode?: boolean)

Used by getPublicProvider, simply returns public URL for the provider

Updating Metadata

To update the metadata for a newer version of the TRN runtime, run:

pnpm --filter=@therootnetwork/api-types update:meta
pnpm --filter=@therootnetwork/api-types generate:types

Then to update the test snapshot run:

pnpm test:snapshot

Source: https://www.npmjs.com/package/@therootnetwork/api · captured 2026-05-02