potforge

TypeScript SDK for Pot — stablecoin fundraisers on Celo (cUSD) and Stacks (sBTC). Read the contract, sign a createPot, decode contribution events, build share URLs, claim from the STX faucet.

pnpm add @winsznx/potforge viem

viem is a peer dependency (^2.21.0). The Stacks subpath is dependency-free — it talks to the Hiro v2 API over fetch so consumers don't pay the @stacks/connect bundle weight unless they want to.

What's in the box

• Contract bindings for the live Pot deployments (Celo mainnet + Stacks mainnet)
• Read helpers for getPot, nextPotId, event indexing with configurable lookback
• Write helpers for createPot, contribute, endorsePot, votePot, plus a cUSD allowance no-op
• Metadata utilities — canonical JSON shape + keccak256 hash so on-chain metadataHash always verifies
• Formatters for cUSD wei + microSTX, address shortening, time-left math
• Share intents — twitter / whatsapp / telegram URL builders
• Hiro v2 balance + tx-status fetch with explorer URL helpers

Layout

@winsznx/potforge             chain-neutral utilities (formatters, share URLs, addresses, types)
@winsznx/potforge/celo        viem-based reads + writes against the EVM Pot.sol
@winsznx/potforge/stacks      hiro v2 + Clarity call-shape builders

Tree-shakeable, dual ESM + CJS, source maps shipped. Strict TypeScript, noUncheckedIndexedAccess on.

Quick start — Celo

import { makePublicClient } from "@winsznx/potforge/celo";
import { readPot, readNextPotId } from "@winsznx/potforge/celo";
import { formatCusd, progressLabel } from "@winsznx/potforge";

const client = makePublicClient({ selector: "mainnet" });

const total = await readNextPotId(client);
const pot = await readPot(client, 0n);

console.log(
  `Pot 0 — ${formatCusd(pot.raised)}/${formatCusd(pot.target)} cUSD (${progressLabel(pot.raised, pot.target)})`,
);

Create a pot (Celo)

import { makeWalletClient, writeCreatePot, ensureCusdAllowance } from "@winsznx/potforge/celo";
import { metadataHash, parseCusd, CELO_ADDRESSES } from "@winsznx/potforge";

const wallet = makeWalletClient(process.env.PRIVATE_KEY as `0x${string}`);

const hash = await writeCreatePot(wallet, {
  target: parseCusd("500"),
  deadlineSec: Math.floor(Date.now() / 1000) + 7 * 24 * 3600,
  refundIfMissed: true,
  metadataHash: metadataHash({
    title: "Replace the school roof",
    description: "Storm took it out last week.",
  }),
});

console.log("tx", hash);

Stacks — read balance + build a call

import { fetchStxBalance, claimStxCall, formatStx } from "@winsznx/potforge/stacks";
import { STACKS_CONTRACTS } from "@winsznx/potforge";

const bal = await fetchStxBalance("SP31DP8F8CF2GXSZBHHHK5J6Y061744E1TNFGYWYV", "mainnet");
console.log("STX:", formatStx(bal.balance));

// Pass into @stacks/connect's request('stx_callContract', ...) in your app:
const shape = claimStxCall("mainnet");
console.log(shape.contract); // SP31...WYV.stx-faucet

Addresses (mainnet)

• Pot — 0xEf2DF00E73F37AE499Dd7Eb35E33b776CFBa1502
• PotBadges — 0xeFdF9073adD638b17EC5259C8Ace640c077b3146
• cUSD — 0x765DE816845861e75A25fCA122bb6898B8B1282a
• Stacks deployer — SP31DP8F8CF2GXSZBHHHK5J6Y061744E1TNFGYWYV

Develop

pnpm install
pnpm typecheck
pnpm test
pnpm build

License

MIT — see LICENSE.