coverchain-sdk

TypeScript SDK for CoverChain — parametric micro-insurance on the Celo blockchain.

CoverChain lets MiniPay users buy device, medical, and farm weather cover with cUSD. This SDK gives you typed read helpers, ABI constants, utility functions, and full TypeScript support — framework-agnostic, works with any viem-based project.

Installation

npm install coverchain-sdk viem
# or
yarn add coverchain-sdk viem
# or
pnpm add coverchain-sdk viem

Peer dependency: viem >= 2.0.0 must be installed alongside this package.

Quick start

import {
  createCoverChainConfig,
  createCeloPublicClient,
  CoverChainClient,
  formatCUSD,
} from "coverchain-sdk";

// 1. Create a config for Celo mainnet (or "alfajores" for testnet)
const config = createCoverChainConfig("celo");

// 2. Create a pre-configured viem PublicClient for Celo
const publicClient = createCeloPublicClient("celo");

// 3. Instantiate the client
const client = new CoverChainClient(publicClient, config);

// 4. Read data
const plan = await client.fetchPlan(0n);
console.log(plan.name);                          // "Device Cover"
console.log(formatCUSD(plan.monthlyPremium));    // "0.000010"

const policies = await client.fetchUserPolicies("0xYourAddress");
console.log(policies); // [0n, 1n, ...]

API Reference

Config

createCoverChainConfig(network?)

Returns a CoverChainConfig object with the contract and cUSD addresses for the given network.

const config = createCoverChainConfig("celo");
// { network: "celo", chainId: 42220, contractAddress: "0x...", cUSDAddress: "0x..." }

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | network | "celo" \| "alfajores" | "celo" | Target network |

Client

new CoverChainClient(publicClient, config)

Wraps a viem PublicClient and provides typed contract reads.

const client = new CoverChainClient(publicClient, config);

createCeloPublicClient(network?)

Convenience helper that returns a pre-configured viem PublicClient for Celo or Alfajores.

const publicClient = createCeloPublicClient("celo");

Read methods

| Method | Returns | Description | |--------|---------|-------------| | fetchPlan(planId) | Promise<Plan> | Fetch a single insurance plan | | fetchAllPlans() | Promise<Plan[]> | Fetch all plans | | fetchPolicy(policyId) | Promise<Policy> | Fetch a single policy | | fetchClaim(claimId) | Promise<Claim> | Fetch a single claim | | fetchUserPolicies(address) | Promise<bigint[]> | Get all policy IDs for a user | | fetchUserClaims(address) | Promise<bigint[]> | Get all claim IDs for a user | | fetchPlanCount() | Promise<bigint> | Total number of plans | | fetchPolicyCount() | Promise<bigint> | Total number of policies | | fetchClaimCount() | Promise<bigint> | Total number of claims | | fetchRiskPool() | Promise<bigint> | Current risk pool balance in cUSD wei | | fetchValidators() | Promise<readonly \0x${string}`[]>| All active validator addresses | |isValidator(address)|Promise| Check if an address is a validator | |hasVoted(claimId, validator)|Promise| Check if a validator voted on a claim | |isParametricTriggered(policyId)|Promise| Check if a weather payout was triggered | |fetchCUSDBalance(address)|Promise| cUSD balance of an address (wei) | |fetchCUSDAllowance(owner)|Promise` | cUSD allowance granted to the contract |

Utilities

import {
  formatCUSD,
  parseCUSD,
  truncateAddress,
  coverTypeLabel,
  claimStatusLabel,
  totalPremium,
  isPolicyActive,
  isVotingOpen,
  policySecondsRemaining,
  formatDuration,
} from "coverchain-sdk";

| Function | Signature | Description | |----------|-----------|-------------| | formatCUSD | (amount: bigint, decimals?: number) => string | Wei → human-readable cUSD (e.g. "0.000010") | | parseCUSD | (amount: string) => bigint | Human-readable cUSD → wei | | truncateAddress | (address: string, chars?: number) => string | "0x1234…abcd" | | coverTypeLabel | (coverType: CoverType) => string | "Device Cover" / "Medical Cover" / "Farm Weather Cover" | | claimStatusLabel | (status: ClaimStatus) => string | "Pending" / "Approved" / "Rejected" / "Paid" | | totalPremium | (monthlyPremium: bigint, months: number) => bigint | Total cost for N months | | isPolicyActive | (policy: Policy) => boolean | Active and not expired | | isVotingOpen | (claim: Claim) => boolean | Claim is pending and within voting window | | policySecondsRemaining | (policy: Policy) => number | Seconds until policy expires | | formatDuration | (seconds: number) => string | "27 days" / "3 hours" |

Types

import type { Plan, Policy, Claim } from "coverchain-sdk";
import { CoverType, ClaimStatus } from "coverchain-sdk";

Plan

interface Plan {
  coverType: CoverType;   // DEVICE | MEDICAL | WEATHER
  name: string;
  monthlyPremium: bigint; // in cUSD wei (18 decimals)
  maxPayout: bigint;
  active: boolean;
}

Policy

interface Policy {
  holder: `0x${string}`;
  planId: bigint;
  startDate: bigint;      // Unix timestamp
  endDate: bigint;        // Unix timestamp
  premiumPaid: bigint;    // cumulative, in cUSD wei
  active: boolean;
}

Claim

interface Claim {
  policyId: bigint;
  claimant: `0x${string}`;
  evidence: string;          // IPFS hash or description
  requestedAmount: bigint;   // in cUSD wei
  status: ClaimStatus;       // PENDING | APPROVED | REJECTED | PAID
  submittedAt: bigint;       // Unix timestamp
  approvalVotes: bigint;
  rejectionVotes: bigint;
  paid: boolean;
}

Constants

import {
  COVER_CHAIN_ADDRESS,
  CUSD_ADDRESS,
  COVER_CHAIN_ABI,
  ERC20_ABI,
  VALIDATOR_STAKE,
  VOTING_PERIOD,
  MIN_CLAIM_AMOUNT,
  CHAIN_IDS,
} from "coverchain-sdk";

| Constant | Value | Description | |----------|-------|-------------| | COVER_CHAIN_ADDRESS[42220] | 0x7208A100... | Mainnet contract | | CUSD_ADDRESS[42220] | 0x765DE816... | Mainnet cUSD token | | VALIDATOR_STAKE | 100000000000000n | 0.0001 cUSD in wei | | VOTING_PERIOD | 259200 | 3 days in seconds | | MIN_CLAIM_AMOUNT | 1000000000000n | 0.000001 cUSD in wei |

Using with wagmi / RainbowKit

coverchain-sdk exports the ABI and addresses directly — plug them into wagmi hooks:

import { useReadContract, useWriteContract } from "wagmi";
import { COVER_CHAIN_ABI, COVER_CHAIN_ADDRESS } from "coverchain-sdk";

// Read
const { data: riskPool } = useReadContract({
  address: COVER_CHAIN_ADDRESS[42220],
  abi: COVER_CHAIN_ABI,
  functionName: "riskPool",
});

// Write
const { writeContract } = useWriteContract();

writeContract({
  address: COVER_CHAIN_ADDRESS[42220],
  abi: COVER_CHAIN_ABI,
  functionName: "purchasePolicy",
  args: [0n, 3n], // planId 0, 3 months
});

Contract addresses

| Network | Contract | cUSD | |---------|----------|------| | Celo Mainnet | 0x7208A100F67eeA5414168fAF7df5feCc817AB070 | 0x765DE816845861e75A25fCA122bb6898B8B1282a | | Alfajores Testnet | — | 0x874069Fa1Eb16D44d622F2e0Ca25eeA172369bC1 |

License

MIT