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 first

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

Deployed addresses

You 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