@avaprotocol/protocols

Multi-chain catalog of DeFi protocol contract addresses, ABI fragments, and event topic hashes. Curated for callers who need a canonical reference without re-deriving constants or re-vendoring protocol SDKs.

import { Protocols, Chains } from "@avaprotocol/protocols";

const pool = Protocols.aaveV3.pool[Chains.Sepolia];
// → "0x6Ae43d3271ff6888e7Fc43Fd7321a503ff738951"

const abi  = Protocols.uniswapV3.swapRouter02Abi;
// → readonly AbiFragment[] with exactInputSingle + exactOutputSingle

const sig  = Protocols.aaveV3.eventTopics.Borrow;
// → keccak256("Borrow(address,address,address,uint256,uint8,uint256,uint16)")

What's covered

Protocol	Contracts	Chains
AAVE V3	Pool, Oracle, WETH Gateway + Pool methods/events ABI + topics	Mainnet, Sepolia, Base, Base Sepolia, BNB (no WETH Gateway on BNB)
Aerodrome	Router	Base
Chainlink	ETH/USD + BTC/USD + BNB/USD feeds + AggregatorV3 ABI	Mainnet, Sepolia, BNB (BNB/USD is BNB-only)
Compound V3	USDC Comet market	Mainnet, Base
Ethena	USDe, sUSDe vault + custom (cooldown-aware) ABI	Mainnet
Frax Ether	frxETH, sfrxETH vault + standard ERC-4626 ABI	Mainnet
Lido	stETH, wstETH + L1 wrap/unwrap/rate ABI	Mainnet, Base (wstETH bridged)
Morpho Blue	Singleton + MarketParams-tuple supply/borrow/position ABI	Mainnet, Base
Rocket Pool	rETH + L1 burn/rate/value ABI	Mainnet, Base (bridged)
Sky (sDAI)	sDAI vault + standard ERC-4626 ABI	Mainnet
Spark	SparkLend Pool (AAVE V3 fork — reuse AAVE Pool ABI)	Mainnet
Superfluid	CFAv1Forwarder + setFlowrate/createFlow ABI	Mainnet, Base, BNB
Uniswap V3	SwapRouter02, QuoterV2, Permit2, Factory, NFT Position Manager, Universal Router + ABIs	Mainnet, Sepolia, Base, Base Sepolia, BNB
Wrapped Ether	Canonical wrapper of native gas + WETH9 ABI (WBNB on BNB)	Mainnet, Sepolia, Base, Base Sepolia, BNB
ERC-20	Standard approve ABI fragment	n/a

Shared ABIs (consumed by multiple protocol modules):

• aggregatorV3Abi — any Chainlink-compatible price feed
• erc4626VaultAbi — standard ERC-4626 vault (used by Frax Ether sfrxETH, Sky sDAI)

Install

yarn add @avaprotocol/protocols
# or
npm install @avaprotocol/protocols
# or
pnpm add @avaprotocol/protocols

Works with Node 18+, modern bundlers, and any TypeScript 4.7+ consumer. Ships dual CJS + ESM with full .d.ts.

Usage patterns

Pin an address by chain

import { Protocols, Chains } from "@avaprotocol/protocols";

const linkOnSepolia = Protocols.aaveV3.tokens.LINK[Chains.Sepolia]!;
// "0xf8Fb3713D459D7C1018BD0A49D19b4C44290EBE5"

Partial<Record<ChainId, …>> is the catalog's keying convention — every protocol declares which chains it covers. Use the non-null assertion (!) only when you're sure the chain is covered, or guard with if.

Compose a contract write

import { Protocols, Chains } from "@avaprotocol/protocols";

await wallet.contractWrite({
  contractAddress: Protocols.aaveV3.pool[Chains.Sepolia]!,
  contractAbi: Protocols.aaveV3.poolMethodsAbi,
  methodCalls: [
    {
      methodName: "supply",
      methodParams: [
        Protocols.aaveV3.tokens.LINK[Chains.Sepolia]!,
        "100000000000000000",   // 0.1 LINK
        wallet.address,
        "0",                    // referralCode
      ],
    },
  ],
});

Filter on an event topic

import { Protocols } from "@avaprotocol/protocols";

const filter = {
  address: Protocols.aaveV3.pool[Chains.Sepolia],
  topics: [
    Protocols.aaveV3.eventTopics.Borrow,
    null,            // any reserve
    padAddress(eoa), // onBehalfOf = my EOA
  ],
};

Address lookups by (chainId, address)

For consumers that need to recognize an address rather than look it up by name (e.g. transaction interpreters), iterate the registry directly:

import { Protocols, Chains } from "@avaprotocol/protocols";

function isAaveV3Pool(chainId: number, address: string): boolean {
  const expected = Protocols.aaveV3.pool[chainId];
  return !!expected && expected.toLowerCase() === address.toLowerCase();
}

(A first-class reverse-lookup helper may ship later; the data shape already supports it.)

Design

Three principles drive what's in vs. what's out:

1. Static, on-chain-public data only. Addresses, ABI fragments, event topic hashes, well-known token references. No private/embargoed protocol addresses; no RPC URLs, API keys, or credentials.
2. No UI metadata. Per-action labels, descriptions, slugs, capability tags belong to each consumer's UX layer. This keeps the package tree-shakeable, language-agnostic, and reusable across web UIs, server-side indexers, partner SDKs, and CLI tooling.
3. Curated ABI fragments, not full ABIs. Each protocol module ships only the methods + events callers routinely touch (e.g., AAVE Pool's supply/borrow/repay/withdraw + the 5 monitorable events, not the full ~80-method ABI). Keeps the bundle small and the API surface reviewable. Need a method not in the catalog? Open a PR — adding one fragment is a small diff.

Comparison with adjacent projects

Project	Scope	This catalog's delta
@bgd-labs/aave-address-book	AAVE-only, exhaustive	Spans 14+ protocols. Borrows the shape + governance model.
@uniswap/sdk-core	Uniswap-only, addresses + math primitives	We ship Uniswap as one entry; don't duplicate the math.
blockchain-addressbook	Multi-protocol, Beefy-opinionated	Includes ABI fragments + event topics; not Beefy-vault-shaped.
Uniswap TokenLists	Tokens only, standardized schema	Complementary — we ship protocol contracts; you bring your own token list.

There's no equivalent multi-protocol + multi-chain + addresses + ABIs + topics package in the npm ecosystem today, so this fills a gap. See tests/catalog.test.ts for shape guarantees.

Adding a new protocol

1. Create src/protocols/<protocol>.ts with the per-chain address maps, ABI fragments, and event topics following the existing modules as templates (aave-v3.ts is the most complete example).
2. Wire it through src/protocols/index.ts — add the import, the re-export, and the entry in the Protocols.* namespace.
3. Add the entry to the supported-protocols table in this README + to the it("exports every shipped protocol", ...) test.
4. Open a PR — CI runs typecheck + tests + build + tarball verification across Node 18/20/22.

Address verification: link to the canonical source (Etherscan-verified deployment, protocol docs, official address book). PRs that don't cite a source for the addresses won't merge.

Tokens sidecar (for non-TS consumers)

yarn build writes a per-chain JSON file under dist/tokens/ alongside the JS + d.ts outputs:

dist/tokens/
├── ethereum.json       (chain 1)
├── sepolia.json        (chain 11155111)
├── base.json           (chain 8453)
├── base-sepolia.json   (chain 84532)
├── bnb-mainnet.json    (chain 56)
└── holesky.json        (chain 17000)

Each file is a stable-sorted array of { id, name, symbol, decimals } entries — the same schema the EigenLayer-AVS Go aggregator already consumes under token_whitelist/*.json, so a Go service can pick up the catalog without depending on the TS toolchain. id is the lowercased address (matching Go's read-side normalization). Metadata fields TS consumers use (description, website, logoUrl, links) are intentionally omitted; TS callers import the Tokens namespace from source instead.

When to run it

• Automatically — yarn build invokes yarn build:tokens-sidecar as its last step, so any release publishes a fresh sidecar in the npm tarball.
• Standalone — yarn build:tokens-sidecar when you've edited src/tokens/ and want to inspect the generated JSON without rebuilding declarations + JS.

Adding a new chain

The script throws fast if the catalog grows a token on a chain that isn't registered in CHAIN_FILE_NAMES inside scripts/build-tokens-sidecar.ts:

[tokens-sidecar] no file name registered for chain <id>.
Add it to CHAIN_FILE_NAMES in scripts/build-tokens-sidecar.ts.

Fix is one line — append [Chains.NewChain]: "newchain-mainnet" to the map. The error message points at the exact file so this can't silently ship an incomplete sidecar.

Consuming the sidecar (Go example)

// EigenLayer-AVS already does this for its checked-in
// token_whitelist/*.json; the dist/tokens/*.json from this package
// match the same schema.
type tokenEntry struct {
    ID       string `json:"id"`
    Name     string `json:"name"`
    Symbol   string `json:"symbol"`
    Decimals int    `json:"decimals"`
}

raw, err := os.ReadFile("path/to/dist/tokens/sepolia.json")
// ... json.Unmarshal(raw, &entries) ...

Releasing

This package uses changesets for versioning. The day-to-day flow:

# 1. Make your code changes on a feature branch.
yarn changeset                   # interactive prompt; pick bump level + write the changelog entry
git add .changeset && git commit -m "..."
git push                         # open PR as normal

When the PR merges to main, the Release workflow (.github/workflows/release.yml) either:

• Opens (or updates) a "Version Packages" PR that runs yarn changeset version — bumps package.json + writes CHANGELOG.md. Review and merge that PR.
• Or, if there are no pending changesets, runs yarn release (yarn build && yarn changeset publish) — which publishes to npm with the right dist-tag automatically (stable → latest, pre-release → its identifier).

Publishing manually (escape hatch)

If you need to publish without the GitHub Action — e.g. an emergency release from a machine that has npm login credentials:

yarn build                        # produces dist/ + tokens sidecar
npm whoami                        # verify logged in
npm publish --access public       # for stable versions; goes to `latest`
# or for a pre-release:
npm publish --access public --tag dev

prepublishOnly: yarn build runs the build chain automatically if you forget, so even npm publish alone is safe.

Versioning

Semver. Until 1.0.0, breaking changes can land in minor versions (0.x), but address corrections are always patches.

• Patch (0.1.x) — address corrections, bug fixes, doc-only changes.
• Minor (0.x.0) — new protocols, new chains, additive ABI fragments.
• Major (x.0.0) — renames, restructures, breaking removals.

The dev npm tag tracks the latest pre-release; latest stays on stable.

License

MIT — see LICENSE.