> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oaknetwork.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://viem.sh).

<Tip>
  **Testnet first**

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

<Tip>
  **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](mailto:support@oaknetwork.org).
</Tip>

## 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](https://www.privy.io/) embedded wallets (see [Client Configuration](/contracts-sdk/client))
* **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

```typescript theme={null}
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](/contracts-sdk/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`](/contracts-sdk/global-params)                | `oak.globalParams(address)`            | Protocol-wide configuration registry              |
| [`CampaignInfoFactory`](/contracts-sdk/campaign-info-factory) | `oak.campaignInfoFactory(address)`     | Deploy new CampaignInfo contracts                 |
| [`CampaignInfo`](/contracts-sdk/campaign-info)                | `oak.campaignInfo(address)`            | Per-campaign configuration and state              |
| [`TreasuryFactory`](/contracts-sdk/treasury-factory)          | `oak.treasuryFactory(address)`         | Deploy treasury contracts for campaigns           |
| [`PaymentTreasury`](/contracts-sdk/payment-treasury)          | `oak.paymentTreasury(address)`         | Fiat-style payments via a payment gateway         |
| [`AllOrNothing`](/contracts-sdk/all-or-nothing)               | `oak.allOrNothingTreasury(address)`    | Crowdfunding — funds released only if goal is met |
| [`KeepWhatsRaised`](/contracts-sdk/keep-whats-raised)         | `oak.keepWhatsRaisedTreasury(address)` | Crowdfunding — creator keeps all funds raised     |
| [`ItemRegistry`](/contracts-sdk/item-registry)                | `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:

```typescript theme={null}
const [platformCount, goalAmount, raisedAmount] = await oak.multicall([
  () => gp.getNumberOfListedPlatforms(),
  () => ci.getGoalAmount(),
  () => aon.getRaisedAmount(),
]);
```

> See the full [Multicall](/contracts-sdk/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:

```typescript theme={null}
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](/contracts-sdk/events) guide for all available events per contract.

## Metrics

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

```typescript theme={null}
import { getPlatformStats, getCampaignSummary, getTreasuryReport } from '@oaknetwork/contracts-sdk/metrics';
```

| Function                                                        | Description                                         |
| --------------------------------------------------------------- | --------------------------------------------------- |
| [`getPlatformStats`](/contracts-sdk/metrics#platform-stats)     | Protocol-level statistics from GlobalParams         |
| [`getCampaignSummary`](/contracts-sdk/metrics#campaign-summary) | Financial aggregation from a CampaignInfo contract  |
| [`getTreasuryReport`](/contracts-sdk/metrics#treasury-report)   | Per-treasury financial report for any treasury type |

> See the full [Metrics](/contracts-sdk/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](/contracts-sdk/installation) — install the package and configure your chain
* [Quickstart](/contracts-sdk/quickstart) — your first contract interaction in under 5 minutes
* [Client Configuration](/contracts-sdk/client) — patterns, signer overrides, and resolution order
* [Multicall](/contracts-sdk/multicall) — batch reads into a single RPC call
* [Events](/contracts-sdk/events) — historical logs, decoding, and live event watching
* [Metrics](/contracts-sdk/metrics) — pre-built aggregation reports
* [Error Handling](/contracts-sdk/error-handling) — typed error decoding and recovery hints