🪸 @reef-chain/evm-util-lib

A TypeScript SDK providing unified utilities to interact with the Reef Network — combining Substrate (Reef chain) and EVM-compatible tooling for contracts, tokens, NFTs, accounts, and more.

⚙️ Installation

npm install @reef-chain/evm-util-lib
# or
yarn add @reef-chain/evm-util-lib

🚀 Quick Start

Before using any module, you must initialize the Reef state (network + provider):

import { reefState, network } from "@reef-chain/evm-util-lib";

await reefState.initReefState(network.config.NETWORK_CONFIGS.localhost);

console.log("✅ Reef initialized!");

This sets up:

• A connected Substrate WsProvider
• Global reactive state for provider and network
• Shared context for all EVM and Substrate utilities

Imports

import { reefState } from "@reef-chain/evm-util-lib";

🔹 initReefState(network: NetworkConfig): Promise<ReefStateResponse>

Initializes the Reef provider and network context. Must be called before any other module.

import { reefState, network } from "@reef-chain/evm-util-lib";

await reefState.initReefState(network.config.NETWORK_CONFIGS.localhost);

🔹 getProvider(): Provider

Returns the connected Substrate provider.

🔹 getNetwork(): NetworkConfig

Returns the currently selected network config.

Both throw an error if Reef hasn’t been initialized yet.

🔹 Reactive Streams

reefState.provider$.subscribe((p) => console.log("Provider ready:", p));
reefState.network$.subscribe((n) => console.log("Network switched:", n));

Imports

import { network } from "@reef-chain/evm-util-lib";

🔹 initProvider(providerUrl: string)

Creates a new WsProvider and connects to the given Substrate node.

const provider = await network.provider.initProvider("wss://rpc.reefscan.com/ws");

🔹 NETWORK_CONFIGS

Built-in configurations for quick setup:

| Network | Substrate RPC | EVM RPC | Explorer | | --------------- | ----------------------------------- | ---------------------------------- | ---------------------- | | ReefMainnet | ws://34.123.142.246:9944 | http://34.123.142.246:8545 | Parity Blockscout | | ReefTestnet | wss://rpc-testnet.reefscan.com/ws | https://evm-testnet.reefscan.com | testnet.reefscan.com | | ReefLocalhost | ws://localhost:9944 | http://localhost:8545 | http://localhost |

Example:

const mainnet = network.config.NETWORK_CONFIGS.mainnet;

Imports

import { account } from "@reef-chain/evm-util-lib";

Includes:

• nativePallet — handle Substrate balances
• revivePallet — handle Revive bridge EVM logic

🔹 nativePallet

getBalance(address: string): Promise<string>

Fetch native REEF balance from Substrate.

const bal = await account.nativePallet.getBalance("5F...");

🔹 revivePallet

getReviveEvmAddress(address: string): Promise<string>

Converts Substrate address → EVM-compatible address.

const evmAddr = await account.revivePallet.getReviveEvmAddress("5F...");

sendToReviveEvmAddress(keypair, toAddress: string): Promise<boolean>

Sends REEF tokens to a Revive EVM address.

await account.revivePallet.sendToReviveEvmAddress(keypair, "0xEvm...");

getNativeAddress(reviveEvmAddress: string): Promise<string>

Finds original Substrate account for a Revive EVM address.

const nativeAddr = await account.revivePallet.getNativeAddress("0x...");

getBalance(reviveEvmAddress: string): Promise<string>

Fetches EVM-side balance for a Revive address.

const balance = await account.revivePallet.getBalance("0x...");

Imports

import { signers } from "@reef-chain/evm-util-lib";

🔹 MnemonicSigner

Implements the Substrate Signer interface using a mnemonic phrase.

const signer = new signers.MnemonicSigner("seed sock milk update ...");
const addr = await signer.getAddress();

signPayload(payload: SignerPayloadJSON)

Signs Substrate extrinsic payloads.

signRaw(payloadRaw: SignerPayloadRaw)

Signs arbitrary data or messages.

Example usage

import { reefState, network, signers } from "@reef-chain/evm-util-lib";

await reefState.initReefState(network.config.NETWORK_CONFIGS.localhost);
const signer = new signers.MnemonicSigner("seed sock milk update ...");

const addr = await signer.getAddress();
console.log("Address:", addr);

Imports

import { evm } from "@reef-chain/evm-util-lib";

Provides multiple EVM-related APIs via submodules.

| Submodule | Description | | ----------- | ---------------------------- | | tx | Transaction details | | blocks | Block info | | addresses | Token holders & REEF holders | | tokens | Tokens & transfers | | contracts | Verified smart contracts | | nfts | NFT ownership | | event | Live updates via Pusher |

🔹 evm.tx

getTransactionInfo(txHash: string): Promise<TransactionInfo>

Fetches full transaction details from BlockScout.

const tx = await evm.tx.getTransactionInfo("0x...");

🔹 evm.blocks

getBlockInfo(hashOrBlockNo: string): Promise<BlockInfo>

Fetch block info, miner, and gas stats.

const block = await evm.blocks.getBlockInfo("11456971");

🔹 evm.addresses

getReefHolders(): Promise<ReefHolder[]>

Fetches all REEF token holders recursively using pagination.

const holders = await evm.addresses.getReefHolders();

getTokenHolders(address: string): Promise<any[]>

Fetches all holders for a given ERC token.

const tokenHolders = await evm.addresses.getTokenHolders("0xEE3dAE...");

🔹 evm.tokens

getTokens(query: string, types?: TokenType[]): Promise<Token[]>

Search for tokens by name/symbol and type (ERC-20, ERC-721, ERC-1155).

const tokens = await evm.tokens.getTokens("usd", ["ERC-20"]);

getTokenTransfers(tokenAddress: string): Promise<TokenTransfer[]>

Recursively fetch all token transfers.

const transfers = await evm.tokens.getTokenTransfers("0xEE3dAE...");

🔹 evm.contracts

getAllContracts(query?: string): Promise<SmartContract[]>

Fetch all verified smart contracts (optionally filtered by q).

const verified = await evm.contracts.getAllContracts("dex");

getVerifiedContract(address: string): Promise<any>

Fetch a specific verified contract’s metadata.

const contract = await evm.contracts.getVerifiedContract("0x...");

🔹 evm.nfts

getNftsForUser(address: string): Promise<any[]>

Fetch NFTs owned by an address (ERC-721, ERC-1155, ERC-404).

const nfts = await evm.nfts.getNftsForUser("0x5b17...");

🔹 evm.event

evmAddressesEventsObs$

Reactive Pusher observable for real-time address updates.

evm.event.evmAddressesEventsObs$.subscribe(console.log);

🧩 Type Definitions

This library is fully typed with interfaces like:

• NetworkConfig, Provider
• BlockInfo, TransactionInfo
• Token, TokenTransfer, SmartContract
• ReefHolder, ReefStateResponse

All methods return properly typed promises.

🧱 Architecture

• Built on @polkadot/api for Substrate
• Uses ethers.js for EVM queries
• Integrates BlockScout APIs
• Fully reactive via rxjs

✨ Example End-to-End

import { reefState, network, evm, account } from "@reef-chain/evm-util-lib";

await reefState.initReefState(network.config.NETWORK_CONFIGS.mainnet);

const block = await evm.blocks.getBlockInfo("latest");
const tokens = await evm.tokens.getTokens("reef");
const balance = await account.nativePallet.getBalance("5F...");

console.log({ block, tokens, balance });

👨‍💻 Author

Anukul Pandey Building Reef-based developer infrastructure 🪸