Contracts SDK

The @oaknetwork/contracts-sdk package is a TypeScript SDK for interacting with Oak Network smart contracts. It provides a type-safe client with full read/write access to all Oak protocol contracts, built on top of viem.

Testnet firstStart by pointing the SDK at Celo Sepolia testnet (CHAIN_IDS.CELO_TESTNET_SEPOLIA) to experiment without risking real funds.

Deployed addressesYou need deployed contract addresses to use this SDK — including factory addresses (for example CampaignInfoFactory, TreasuryFactory) and any protocol contracts you call through the client. The SDK interacts with Oak Network smart contracts that must already be deployed on-chain. To get your contract addresses and sandbox environment access, contact our team at support@oaknetwork.org.

Highlights

Flexible signers — simple keyed client, read-only RPC client, per-entity or per-call signer overrides, or full viem PublicClient / WalletClient setup including Privy embedded wallets (see Client Configuration)
Entity factories for every on-chain contract: oak.globalParams(address), oak.campaignInfo(address), etc.
Typed reads, writes, and simulations — every method is fully typed with TypeScript
Typed error decoding — parseContractError() turns raw revert data into SDK errors with recovery hints
Pure utility exports — hashing, encoding, time helpers, and chain resolution with zero client dependency
Tree-shakeable entry points — import only what you need: @oaknetwork/contracts-sdk/utils, @oaknetwork/contracts-sdk/client, etc.

Quick example

import { createOakContractsClient, CHAIN_IDS, keccak256, toHex } from '@oaknetwork/contracts-sdk';

const oak = createOakContractsClient({
  chainId: CHAIN_IDS.CELO_TESTNET_SEPOLIA,
  rpcUrl: 'https://forno.celo-sepolia.celo-testnet.org',
  privateKey: '0x...',
});

const gp = oak.globalParams('0x...');

const admin = await gp.getProtocolAdminAddress();
const fee = await gp.getProtocolFeePercent();

console.log('Admin:', admin, 'Fee:', fee);

See the full walkthrough in the Quickstart guide.

Contract entities

The SDK ships 8 contract entity modules. Call the factory method on the client to get a typed entity for a deployed contract address.

Entity	Factory	What it does
`GlobalParams`	`oak.globalParams(address)`	Protocol-wide configuration registry
`CampaignInfoFactory`	`oak.campaignInfoFactory(address)`	Deploy new CampaignInfo contracts
`CampaignInfo`	`oak.campaignInfo(address)`	Per-campaign configuration and state
`TreasuryFactory`	`oak.treasuryFactory(address)`	Deploy treasury contracts for campaigns
`PaymentTreasury`	`oak.paymentTreasury(address)`	Fiat-style payments via a payment gateway
`AllOrNothing`	`oak.allOrNothingTreasury(address)`	Crowdfunding — funds released only if goal is met
`KeepWhatsRaised`	`oak.keepWhatsRaisedTreasury(address)`	Crowdfunding — creator keeps all funds raised
`ItemRegistry`	`oak.itemRegistry(address)`	Manage items available for purchase in campaigns

Multicall

Batch multiple read calls into a single RPC round-trip. Works across different contract entities:

const [platformCount, goalAmount, raisedAmount] = await oak.multicall([
  () => gp.getNumberOfListedPlatforms(),
  () => ci.getGoalAmount(),
  () => aon.getRaisedAmount(),
]);

See the full Multicall guide for standalone usage and cross-contract batching.

Events

Every contract entity exposes an events property for fetching historical logs, decoding raw logs, and watching live events:

const gp = oak.globalParams('0x...');

// Fetch historical logs
const logs = await gp.events.getPlatformEnlistedLogs();

// Decode raw logs from a receipt
const decoded = gp.events.decodeLog({ topics: log.topics, data: log.data });

// Watch live events
const unwatch = gp.events.watchPlatformEnlisted((logs) => {
  console.log('New platform enlisted:', logs);
});

See the full Events guide for all available events per contract.

Metrics

Pre-built aggregation functions that combine multiple on-chain reads into meaningful reports:

import { getPlatformStats, getCampaignSummary, getTreasuryReport } from '@oaknetwork/contracts-sdk/metrics';

Function	Description
`getPlatformStats`	Protocol-level statistics from GlobalParams
`getCampaignSummary`	Financial aggregation from a CampaignInfo contract
`getTreasuryReport`	Per-treasury financial report for any treasury type

See the full Metrics guide.

Entry points

Import path	Contents
`@oaknetwork/contracts-sdk`	Everything — client, types, utils, errors
`@oaknetwork/contracts-sdk/client`	`createOakContractsClient` only
`@oaknetwork/contracts-sdk/contracts`	Contract entity factories only
`@oaknetwork/contracts-sdk/utils`	Utility functions only (no client)
`@oaknetwork/contracts-sdk/errors`	Error classes and `parseContractError` only
`@oaknetwork/contracts-sdk/metrics`	Platform, campaign, and treasury reporting helpers

Next up

Installation — install the package and configure your chain
Quickstart — your first contract interaction in under 5 minutes
Client Configuration — patterns, signer overrides, and resolution order
Multicall — batch reads into a single RPC call
Events — historical logs, decoding, and live event watching
Metrics — pre-built aggregation reports
Error Handling — typed error decoding and recovery hints

Getting Started

Contract Entities

Examples

Use Cases

Reference

Highlights

Quick example

Contract entities

Multicall

Events

Metrics

Entry points

Next up

​Highlights

​Quick example

​Contract entities

​Multicall

​Events

​Metrics

​Entry points

​Next up

Highlights

Quick example

Contract entities

Multicall

Events

Metrics

Entry points

Next up