Credit Cooperative Address Book

The canonical registry of Credit Cooperative deployed contract addresses, for use in both Solidity and TypeScript/JavaScript projects. It aggregates the per-chain deployment registries that each protocol repo commits under deployments/<chainId>.json (produced by @credit-cooperative/devkit) and republishes them as typed, per-chain libraries.

What's inside

• data/<project>/<chainId>.json — the source registries, mirrored from each protocol repo. This is the input. Everything else is generated from it.
• data/<project>/abis/<Contract>.json — chain-independent ABIs, exported as typed as const values from ts/abis.ts (@credit-cooperative/address-book/abis).
• data/<project>/facility-types.json — facilityType() string → ABI contract name (e.g. "RCF" → "RCFFacility"), for identifying factory-created facilities at runtime.
• data/<project>/instances/<chainId>.json — factory-created facility/servicing instances discovered on-chain by bun scripts/sync-instances.ts (Aave-style static enumeration; only as fresh as the last sync).
• src/<Project><Chain>.sol — generated Solidity libraries of address constants (e.g. V3ProtocolPaymentRailsSepolia, V3ProtocolPaymentRailsBase).
• ts/index.ts — generated TypeScript twin (chain-keyed address maps + getAddress/getContract helpers, plus the facilityTypes and instances maps, no runtime deps).
• ts/resolve.ts — hand-written runtime resolver (@credit-cooperative/address-book/resolve): identify an arbitrary address and pair it with its ABI.

src/ and ts/ are generated and committed. Do not hand-edit them — run bun run generate. CI fails if they drift from data/.

Usage

Solidity (forge install)

forge install credit-cooperative/address-book

import { V3ProtocolPaymentRailsSepolia } from "address-book/src/V3ProtocolPaymentRailsSepolia.sol";

contract MyContract {
    address node = V3ProtocolPaymentRailsSepolia.NODE;
}

TypeScript (npm)

bun add @credit-cooperative/address-book

import {
  v3ProtocolPaymentRails,
  getAddress,
} from "@credit-cooperative/address-book";

const node = v3ProtocolPaymentRails[11155111].Node;
const cowSwap = getAddress("v3ProtocolPaymentRails", 8453, "CowSwapModule");

ABIs

import { v3ProtocolDeploymentMarketplaceAbi } from "@credit-cooperative/address-book/abis";
import { getContract } from "@credit-cooperative/address-book";

const marketplace = getContract(
  "v3ProtocolDeployment",
  11155111,
  "Marketplace",
); // { address, abi }

Identifying a contract from just its address

Facilities (RCFFacility, TLAFacility, TieredFacility, DDTLFacility) and Servicing contracts are deployed per-deal by factories, so they are not in the static address maps. Two complementary mechanisms:

1. Static instance registry — bun scripts/sync-instances.ts --chain <id> scans the OnboardingHub's FactorySet/FacilityDeployed/ServicingCreated events into data/<project>/instances/<chainId>.json (facilities, servicings, and factory addresses), which bun run generate emits as the instances map. Known deals then resolve offline. The scan stays --confirmations blocks (default 15) behind the head so reorgs cannot commit phantom entries.
2. Runtime resolver — for addresses deployed since the last sync, resolveContract probes the contract's facilityType() on-chain and picks the matching ABI. Factories expose facilityType() too, so a follow-up borrower() probe (facility-only) distinguishes kind: "facility" from kind: "factory".

import {
  resolveContract,
  reverseLookup,
} from "@credit-cooperative/address-book/resolve";

// Offline (static book + synced instances only):
const known = reverseLookup(11155111, "0x…");

// Full resolution — any viem PublicClient works as the client:
const resolved = await resolveContract(publicClient, 11155111, "0x…");
// -> { kind: "singleton" | "facility" | "factory" | "servicing" | "unknown", name?, abi?, ... }

The resolver has no runtime dependencies; the client just needs an EIP-1193 request supporting eth_call. Servicing has no facilityType(), so it is detected via the Servicing-unique totalAdvancedValue() probe — or, more strictly, pass { borrower } to confirm via OnboardingHub.servicingOf(borrower) (on chains where the hub is not in the book, this falls back to the heuristic probe).

Two caveats:

• On-chain reverts mean "not this contract type"; transport/RPC failures are re-thrown — a rate-limited endpoint never comes back as kind: "unknown".
• abi is undefined when the address book ships no ABI for that contract — check it before use. (All current projects ship ABIs; this can happen for newly onboarded projects whose abis/ dir lags.)

How it updates

1. A protocol repo runs just deploy …, which writes/updates its deployments/<chainId>.json, and the change is merged to main.
2. The repo's deployments.yml workflow dispatches a deployments-updated event here.
3. dispatch-receive.yml mirrors the changed files into data/<project>/, regenerates src/ + ts/, and opens a PR.
4. Merging + tagging publishes the npm package and updates the forge install source.

To regenerate locally after editing data/:

bun run generate         # rewrite src/ and ts/
bun run generate:check   # CI guard: fail if committed output is stale
forge test               # sanity + (with --fork-url) on-chain code checks
bun test ts/             # TypeScript consumption tests

Multi-chain note

Addresses are not assumed identical across chains — every entry is keyed by chainId. Always confirm you are reading the library/map for the chain you are deploying against.