Cookbook

This Cookbook contains ready-to-use code snippets for common operations with the Flare Transaction SDK.

Retrieve account balances

The Flare network uses two chains:

C-Chain (Contract Chain, EVM-compatible, smart contracts)
P-Chain (Platform Chain, staking & validators)

Both derive addresses from the same public key.

// Get the public key from your wallet
const publicKey = await wallet.getPublicKey();

// Derive the addresses for each chain
const cAddress = network.getCAddress(publicKey);
const pAddress = network.getPAddress(publicKey);

// Get a full balance overview
const balance = await network.getBalance(publicKey);

// Or, query for specific balances
const cBalance = await network.getBalanceOnC(cAddress);
const cWrappedBalance = await network.getBalanceWrappedOnC(publicKeyOrCAddress);
const pBalance = await network.getBalanceOnP(publicKey);
const stakedBalance = await network.getBalanceStakedOnP(publicKey);

info

Balances are returned in nats (the smallest FLR unit, equivalent to wei). Use Amount.nats() or Amount.wnats() helpers to convert human-readable values.

Wrap and transfer

Transfer native FLR and its wrapped form (WFLR) on the C-Chain. Wrapping is required for governance and FTSO delegation, since only WFLR can be delegated.

FLR (native token) lives on both chains.
WFLR (wrapped FLR) exists only on the C-Chain for use in smart contracts and delegation.
The SDK provides simple helpers for wrapping, unwrapping, and transferring.

import { Amount } from "@flarenetwork/flare-tx-sdk";

// Transfer 1 FLR
await network.transferNative(wallet, recipientAddress, Amount.nats(1)); // Amount.nats handles the conversion to wei

// Wrap 1 FLR -> 1 WFLR
await network.wrapNative(wallet, Amount.nats(1));

// Transfer 1 WFLR
await network.transferWrapped(wallet, recipientAddress, Amount.wnats(1));

// Unwrap 1 WFLR -> 1 FLR
await network.unwrapToNative(wallet, Amount.wnats(1));

info

All transfers return a transaction receipt once confirmed.
Wrapping/unwrapping is required to participate in FTSO delegation and governance.

Claim rewards

Flare supports multiple reward sources: FlareDrops, staking rewards, rNat (e.g. rFLR), and FTSO rewards.

FlareDrops

Rewards periodically distributed to token holders.

// Check and claim FlareDrop rewards
const flareDropAmount = await network.getClaimableFlareDropReward(cAddress);
if (flareDropAmount > 0) {
  await network.claimFlareDropReward(wallet);
}

Optional parameters:

rewardOwner (address) - C-Chain address of the reward owner
recipient (address) - C-Chain address to receive the reward
wrap (bool) - true for WFLR, false for FLR (default).

Staking rewards

Earned from delegating tokens to validators on the P-Chain.

// Check and claim staking rewards
const stakingRewardAmount = await network.getClaimableStakingReward(cAddress);
if (stakingRewardAmount > 0) {
  await network.claimStakingReward(wallet);
}

Optional parameters are the same as FlareDrops.

rFLR rewards

rNat tokens (rFLR on Flare) represent vested rewards. They are backed by WFLR in a dedicated rNat account. The flow of rFLR:

rFLR (reward token) → backed by WFLR → claimable → withdraw → optional penalty if locked.

List and claim

// Get a list of all rNat projects
let projects = await network.getRNatProjects();

Returns an array of objects of type RNatProject with:

id (int) - Project ID
name (string) - Project name
claimingDisabled (bool) - Whether claiming rewards is disabled for this project

Claim rewards for one or more projects:

await network.claimRNatReward(wallet, [projectId1, projectId2]);

Claimed rewards are deposited as wrapped coins to the rNat account linked to the wallet's C-Chain address.

Manage balances

Check and claim the unlocked balance:

// Check the unlocked balance:
const unlocked = await network.getUnlockedBalanceWrappedOnRNatAccount(cAddress);

// Withdraw unlocked wrapped coins:
await network.withdrawFromRNatAccount(wallet);

Get the full balance:

let balance = await network.getRNatAccountBalance(cAddress);

The returned RNatAccountBalance object includes:

wNatBalance (int) - Wrapped coin balance (wei)
rNatBalance (int) - rNat token balance (wei)
lockedBalance (int) - Locked wrapped coin balance (wei)

Withdrawing all funds

You can also withdraw all funds (locked + unlocked):

await network.withdrawAllFromRNatAccount(wallet, /* wrap: boolean */ true);

Withdrawing locked balance incurs a penalty, so the withdrawn amount will be reduced.

FlareDrops and rFLR

The balance of rNat tokens equals the difference between rewards received and withdrawn. Note that the wrapped coins in an rNat account can exceed the rNat token balance.

For example, wrapped coins can grow by claiming FlareDrop rewards earned from vested balances.

Check unclaimed FlareDrop rewards:

let rNatAccountAddress = await network.getRNatAccount(cAddress);
let amount = await network.getClaimableFlareDropReward(rNatAccountAddress);

Claim them:

await network.claimFlareDropReward(
  wallet,
  rNatAccountAddress,
  rNatAccountAddress,
  true,
);

FTSO delegation rewards

Rewards earned by delegating WFLR to FTSO providers.

// Check and claim FTSO delegation rewards
const ftsoRewardAmount = await network.getClaimableFtsoReward(cAddress);
if (ftsoRewardAmount > 0) {
  await network.claimFtsoReward(wallet);
}

Optional parameters:

rewardOwner (address) - C-Chain address of the reward owner
recipient (address) - C-Chain address of where the reward should be transferred
wrap (bool) - transfer reward as native (default) or wrapped.

Claim with proofs

If a reward isn't initialized, you must provide a Merkle proof available in the flare-foundation/fsp-rewards repository. As an example for reward epoch 320, see the proofs in reward-distribution-data.json.

await network.claimFtsoReward(wallet, rewardOwner, recipient, wrap, proofs);

where proofs is an array of objects FtsoRewardClaimWithProof with:

merkleProof (array of string) - The Merkle proof in hexadecimal encoding.
body (FtsoRewardClaim ) - Same structure as FtsoRewardState without the initialised parameter.

Delegate to FTSO providers

Delegating WFLR to FTSO providers allows you to earn rewards while contributing to decentralized price feeds. You may delegate to one or two providers.

import { Amount } from "@flarenetwork/flare-tx-sdk";

// Get current delegations
const delegations = await network.getFtsoDelegatesOf(cAddress);

// Delegate 100% to one provider
await network.delegateToFtso(wallet, provider, Amount.percentages(100));

// Split 50/50 between two providers
await network.delegateToFtso(
  wallet,
  provider1,
  Amount.percentages(50),
  provider2,
  Amount.percentages(50),
);

// Remove all delegations
await network.undelegateFromFtso(wallet);

info

Delegations are expressed in basis points (1% = 100 bp).
Rewards can later be claimed via getClaimableFtsoReward.

Stake on P-Chain

Staking involves moving funds to the P-Chain, delegating them, and later transferring them back. The SDK automates these steps.

Transfer from C to P-Chain: This operation performs a C-Chain export followed by a P-Chain import automatically.
```
// Transfer 100 FLR from C-Chain to P-Chain
await network.transferToP(wallet, Amount.nats(100));
```

Delegate on P-Chain: Once funds are on the P-Chain, you can delegate them.

const amountToDelegate = Amount.nats(50);
const nodeId = "NodeID-P73B..."; // The ID of the validator
const startTime = Math.floor(Date.now() / 1000); // Current unix timestamp
const endTime = startTime + 14 * 24 * 60 * 60; // e.g. end in 14 days

await network.delegateOnP(
  wallet,
  amountToDelegate,
  nodeId,
  startTime,
  endTime,
);

Transfer from P to C-Chain: After your delegation period ends, move your funds back to the C-Chain.
```
// Transfer all available funds from P-Chain back to C-Chain
await network.transferToC(wallet);
```

Vote on governance proposals

Governance proposals allow community members to vote on protocol decisions using their voting power (based on WFLR balance and staking).

// Get active proposals
const proposals = await network.getFoundationProposalIds();

// Fetch details
const info = await network.getFoundationProposalInfo(proposalId);

Proposal states

State	Code	Description
PENDING	0	Voting not started
ACTIVE	1	Voting in progress
DEFEATED	2	Vote failed
SUCCEEDED	3	Vote succeeded
QUEUED	4	Queued for execution
EXPIRED	5	Expired before execution
EXECUTED	6	Executed
CANCELED	7	Canceled

Cast a vote

A proposal can be voted on only when its state is ACTIVE.

// Check if a voter has already voted:
await network.hasCastVoteForFoundationProposal(cAddress, proposalId);

const support = FoundationProposalSupport.FOR; // or FoundationProposalSupport.AGAINST

// Cast vote
await network.castVoteForFoundationProposal(wallet, proposalId, support);

Delegate votes

// Get current vote power of a voter:
// Includes both the voter’s own vote power and any delegated to them.
const votePower = await network.getCurrentGovernanceVotePower(cAddress);

// Get current delegate:
let delegate = await network.getCurrentGovernanceVoteDelegate(cAddress);

If delegate == 0x0 - No delegate assigned
If delegate != 0x0 - Voter's own vote power is zero (all delegated)

// Delegate all vote power to another address:
await network.delegateGovernanceVotePower(wallet, delegateAddress);

// Remove delegation:
await network.undelegateGovernanceVotePower(wallet);

Historical voting data

You can query a voter's vote power or delegate as applied to a specific proposal:

const votePower = await network.getVotePowerForFoundationProposal(
  cAddress,
  proposalId,
);
const delegate = await network.getVoteDelegateForFoundationProposal(
  cAddress,
  proposalId,
);

Queries may fail for older proposals, since historical governance vote data is periodically removed from C-Chain storage.

Interact with C-Chain contracts

The SDK provides helpers for interacting with any smart contract on the C-Chain.

// Call a read-only contract method
const result = await network.invokeContractCallOnC(contractAddress, abi, "methodName", [param1, param2]);

// Execute a transaction method that changes state
// The `value` parameter is for payable methods
await network.invokeContractMethodOnC(wallet, contractAddress, abi, "methodName", value, [param1, param2]);

// You can also use contract names for official Flare contracts
const contractNames = await network.getFlareContracts(); // See available names
await network.invokeContractMethodOnC(wallet, "FtsoRewardManager", abi, "claimReward", ...);

info

ABI must match the contract interface.
For official Flare contracts, names are predefined and easier to use.

Next steps

Check the Advanced Features for transaction callbacks and custom wallets.
Read the SDK source code on GitHub.

Need help or found a bug?

Open an issue on the flare-foundation/flare-tx-sdk GitHub repository.

Retrieve account balances​

Wrap and transfer​

Claim rewards​

FlareDrops​

Staking rewards​

rFLR rewards​

List and claim​

Manage balances​

FlareDrops and rFLR​

FTSO delegation rewards​

Claim with proofs​

Delegate to FTSO providers​

Stake on P-Chain​

Vote on governance proposals​

Proposal states​

Cast a vote​

Delegate votes​

Interact with C-Chain contracts​

Next steps​

Retrieve account balances

Wrap and transfer

Claim rewards

FlareDrops

Staking rewards

rFLR rewards

List and claim

Manage balances

FlareDrops and rFLR

FTSO delegation rewards

Claim with proofs

Delegate to FTSO providers

Stake on P-Chain

Vote on governance proposals

Proposal states

Cast a vote

Delegate votes

Interact with C-Chain contracts

Next steps