Centrifuge SDK

A fully typed JavaScript client to interact with the Centrifuge ecosystem. Use it to manage pools, investments, redemptions, financial reports, and more.

Table of Contents

1. Features
2. Installation
3. Getting Started
   • Initialization & Configuration
   • Queries
   • Transactions
   • Investments
   • Reports
4. Developer Guide
   • Development Mode
   • Building
   • Testing
   • Debugging
5. Contributing
   • Docs
   • PR Conventions & Versioning
6. License

Features

• Typed JavaScript/TypeScript client
• Support for mainnet & testnet environments
• Full querying interface (readonly) + subscription support
• Transaction support (awaitable or observable for updates)
• Handling of share classes, vaults, and ERC-7540 tokenized vaults
• Reports: balance sheet, profit & loss, cash flow

Installation

npm install @centrifuge/sdk

Getting Started

Initialization & Configuration

import Centrifuge from '@centrifuge/sdk'

const centrifuge = new Centrifuge({
  environment: 'mainnet' | 'testnet',         // optional, defaults to 'mainnet'
  rpcUrls?: { [chainId: number]: string },     // optional RPC endpoints
  indexerUrl?: string,                         // optional indexer API URL
  ipfsUrl?: string                             // optional IPFS gateway, default: https://ipfs.centrifuge.io
})

Queries

Queries return Observables (rxjs), which can be:

• awaited (for one value), or
• subscribed to (to receive updates when on-chain data changes)

const pools = await centrifuge.pools()

// Or subscribe
const subscription = centrifuge.pools().subscribe(
  (pools) => console.log(pools),
  (error) => console.error(error)
)

// Later, to stop updates:
subscription.unsubscribe()

Transactions

• Before calling transaction methods, set a signer on the centrifuge instance.
• The signer can be:
  • An EIP-1193-compatible provider
  • A Viem LocalAccount
• Transactions, like queries, support either awaiting for completion or subscribing for status updates.

centrifuge.setSigner(signer)
const poolId = PoolId.from(1, 1)
const pool = await centrifuge.pool(poolId)
const tx = await pool.updatePoolManagers([
  {
    address: '0xAddress',
    canManage: true,
  },
])
console.log(tx.hash)

// or, subscribe to transaction lifecycle:
const sub = pool.pool
  .updatePoolManagers([
    {
      address: '0xAddress',
      canManage: true,
    },
  ])
  .subscribe(
    (status) => console.log(status),
    (error) => console.error(error),
    () => console.log('Done')
  )

Investments

The SDK supports ERC-7540 tokenized vaults. Vaults are created per share class, chain, and currency.

const pool = await centrifuge.pool(poolId)
const scId = ShareClassId.from(poolId, 1)
const assetId = AssetId.from(centId, 1)
// Get a vault
const vault = await pool.vault(11155111, scId, assetId)

Vault Types

Vaults can behave differently depending on how the pool is configured:

• Synchronous deposit vaults These vaults follow a hybrid model using both ERC-4626 and ERC-7540. Deposits are executed instantly using ERC-4626 behavior, allowing users to receive shares immediately. However, redemptions are handled asynchronously through ERC-7540, using the Hub to queue and manage the withdrawal requests.

• Asynchronous vaults Asynchronous vaults are fully request-based and follow the ERC-7540 standard. They allow both deposit and redemption actions to be handled through an asynchronous workflow, using the Centrifuge Hub to manage requests.

You can query an individual investor’s state:

const inv = await vault.investment('0xInvestorAddress')

// Example returned fields include:
//   isAllowedToInvest
//   investmentCurrency, investmentCurrencyBalance, investmentCurrencyAllowance
//   shareCurrency, shareBalance
//   claimableInvestShares, claimableInvestCurrencyEquivalent
//   claimableRedeemCurrency, claimableRedeemSharesEquivalent
//   pendingInvestCurrency, pendingRedeemShares
//   hasPendingCancelInvestRequest, hasPendingCancelRedeemRequest

To invest:

const { investmentCurrency } = await vault.details()
const amount = Balance.fromFloat(1000, investmentCurrency.decimals)
const tx = await vault.increaseInvestOrder(amount)
console.log(result.hash)

Once processed, any claimable shares or currencies can be claimed:

const claimResult = await vault.claim()

Reports

You can generate financial reports for a pool based on on-chain + API data.

Available report types:

• token price

Filtering is supported:

type ReportFilter = {
  from?: string // e.g. '2024-01-01'
  to?: string // e.g. '2024-01-31'
  groupBy?: 'day' | 'month' | 'quarter' | 'year'
}

const fromNum = toUTCEpoch(filters.from, unit)
const toNum = toUTCEpoch(filters.to, unit)

const report = await pool.reports.sharePrices({
  from: fromNum,
  to: toNum,
  groupBy: 'day',
})

Developer Guide

Development Mode

pnpm dev

Building

pnpm build

Testing

pnpm test                # full test suite
pnpm test:single <file>  # test specific file
pnpm test:simple:single <file>
# (runs faster excluding setup files)

Debugging

This project provides a fully Dockerized environment for running both the Indexer (api-v3) and an Anvil fork (Foundry) locally. To prepare your testing environment for on-chain debugging, first set up the debugging script:

./src/debugIssues.mjs

// @ts-check

import { catchError, combineLatest, lastValueFrom, map, of, switchMap, tap } from 'rxjs'
import { parseAbiItem } from 'viem'
import { privateKeyToAccount } from 'viem/accounts'
import { AssetId, Balance, Centrifuge, PoolId, Price, ShareClass, ShareClassId } from './dist/index.js'

const abiItem = parseAbiItem('function balanceOf(address owner) view returns (uint256)')

const chainId = 1

const cent = new Centrifuge({
  environment: 'mainnet',
  pinJson: async () => 'test',
  rpcUrls: {
    1: 'http://127.0.0.1:8545',
  },
  inexerPollingInterval: 2000,
  indexerUrl: 'http://localhost:8000',
})

const account = privateKeyToAccount('0xPrivateKey')

cent.setSigner(account)

async function main() {
  const client = cent.getClient(centrifugeId)

  const pool = await cent.pool(new PoolId('PoolId'))
  const scId = new ShareClassId('0x00010000000000010000000000000001')
  const shareClass = new ShareClass(cent, pool, scId)
  const assetId = new AssetId('AssetId')

  const result = await shareClass.approveDepositsAndIssueShares([
    {
      assetId,
      approveAssetAmount: Balance.fromFloat(10, 6),
      issuePricePerShare: Price.fromFloat(1.0),
    },
  ])
}

main()

:::warning Before running the debugging script, comment out the transaction you intend to test if you don’t want it to execute. Keep in mind that running this script locally will perform the same transaction logic as it would on the testnet or mainnet. :::

Then, build and start the Docker containers:

docker compose up -d

Once you’re done, tear down the environment and remove associated volumes with:

docker compose down -v

Contributing

Docs

Detailed user & developer documentation is maintained in the documentation repository.

PR Naming Convention & Versioning

PR titles & commits should follow Conventional Commits style.

Use semantic versioning: tags/releases should be one of major, minor, patch.

If no release is needed, label as no-release.

License

This project is licensed under LGPL-3.0. See the LICENSE file for details.