Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
138 lines (112 loc) · 5.92 KB

CONTRIBUTING.md

File metadata and controls

138 lines (112 loc) · 5.92 KB
Raw

Contributing

This package has two public surfaces driven from the same source data:

  1. The npm package @polygonlabs/meta — typed as const ABI modules under ./abi/*, typed network metadata under ./info/*, plus raw JSON under ./network/*.
  2. The public HTTP endpoint at https://static.polygon.technology/... — same JSON files served verbatim by an nginx Docker image.

The single source of truth for both is the JSON tree under network/. Adding a new ABI or network means dropping JSON files into network/; the typed TS modules are codegenned at build time.

Adding a new ABI

The repo-root network/ directory is the single source of truth. It feeds both the npm package (via scripts/codegen.ts) and the static.polygon.technology nginx image (via Dockerfile).

  1. Get the ABI as JSON from your build pipeline (foundry, hardhat, solc, Etherscan). The expected shape is { "abi": [...] }.
  2. Drop it at <repo-root>/network/<chain>/<version>/artifacts/<type>/<ContractName>.json where <chain> is mainnet or testnet, <version> is the network identifier (v1, cherry, amoy, cardona), and <type> is the artifact bucket (pos, plasma, fx-portal, genesis, zkevm).
  3. From inside packages/meta/, run pnpm run codegen. The script:
    • Reads <repo-root>/network/networks.json (the canonical registry) and walks each <chain>/<version>/ referenced there.
    • Emits src/generated/abi/<...>.ts and src/generated/info/<...>.ts as export const ... = ... as const; modules.
    • Mirrors the entire <repo-root>/network/ tree into packages/meta/network/ so the @polygonlabs/meta/network/* subpath export resolves to the same paths consumers of @maticnetwork/meta@2.x already use.
    • Hard-errors on a missing index.json, missing artifacts/ directory, missing JSON files under a type, or any entry in networks.json whose tree is incomplete — silent skips here would publish a package whose codegen is out of sync with the JSON.
  4. Run pnpm run build (codegen + tsc -p tsconfig.build.json) to verify the emitted .d.ts carries the as const tuple type.
  5. Commit both the JSON in <repo-root>/network/ and the regenerated files under packages/meta/src/generated/ in the same commit. The PR gate runs codegen-drift-check (regenerate, then git diff --exit-code) and fails when the two disagree. .gitattributes marks packages/meta/src/generated/** as linguist-generated so GitHub collapses it in the PR diff by default. packages/meta/network/ is gitignored — it is a pure publish artifact rebuilt by prepack before pnpm publish.
  6. Add a changeset describing the addition (pnpm exec changeset add).

Don't hand-edit anything under src/generated/. It is tracked (so reviewers can see exactly what ships) but regenerated by pnpm run codegen. The only authored surface is the JSON in <repo-root>/network/; the typed TS modules are codegenned.

While editing JSON under network/, run pnpm run codegen:watch in a side terminal — src/generated/ re-emits within ~200 ms of each save, keeping in-editor types accurate without a manual rebuild.

Adding a new network

  1. Drop a <repo-root>/network/<chain>/<version>/index.json with the network metadata (match the shape used by sibling networks).

  2. Drop ABI JSON files under <repo-root>/network/<chain>/<version>/artifacts/<type>/... per "Adding a new ABI" above.

  3. Append an entry to <repo-root>/network/networks.json:

    { "network": "<chain>", "version": "<version>" }

  4. Run pnpm run codegen and pnpm run build.

  5. Add a changeset.

Why as const

Each generated ABI module looks like:

export const abi = [...] as const;

The as const is load-bearing, not stylistic — without it, TypeScript widens the array element type to a generic shape and viem/wagmi/abitype consumers lose the ability to infer function names, argument types, and return types at the call site. The codegen script always emits the as const automatically; if you ever need to extend the codegen, preserve it.

Build

pnpm run codegen      # emit src/generated/**.ts from network/
pnpm run build        # codegen + tsc → dist/

prepack runs build, so pnpm pack and pnpm publish always emit a fresh dist.

Node version: build vs. runtime

codegen runs the script directly with node scripts/codegen.ts, which relies on Node's native TypeScript execution — so building this package requires Node 24. That requirement is declared in devEngines.runtime.

The published package, however, is pure data: every module under dist/generated/** is an export const ... = [...] as const literal with no runtime code, so it runs on any Node that supports ESM subpath exports. engines.node is therefore set to >=20 to describe the consumer runtime, not the build toolchain. Don't raise it to match the build requirement — that would force a Node 24 floor on downstream SDKs (e.g. @polygonlabs/pos-sdk) that legitimately target Node 20 for no runtime reason.

Release

This repo uses Changesets for versioning. Open a PR with a .changeset/<name>.md file describing the user-visible change. Merging the PR opens a "Version Packages" PR that bumps the version and writes the changelog. Merging that PR publishes to npm and tags the release. Do not run pnpm exec changeset publish manually, and do not run npm publish directly.

HTTP endpoint deployment

The Docker image that serves static.polygon.technology is built and deployed via the existing GitHub Actions workflows (.github/workflows/deployment.yml, deployment_gcp.yml, build_and_deploy.yml) on every push to master. Those workflows copy the network/ JSON tree into nginx and ship it. They are out of scope for this contribution guide; nothing in network/ needs special treatment to be served.