Smart contracts for libID, laid out per chain. solidity/ is a self-contained
Foundry project holding the EVM contracts: the ceremony verification path
(Notary Service, Proof Verifier, Platform Verifiers, and the Google JWT root
list the Google verifier reads), the identity registry, the handle escrow, the
referral splitter, the ENS resolver and the deterministic deployment factory.
rust/ and ts/ hold the bindings and the off-chain identity helpers.
solidity/ # Foundry project root
contracts/
ceremony/ # NotaryService, CeremonyProofVerifier, Platform Verifiers,
# JWT roots lists, CeremonyProfile
circuits/ # the UltraHonk verifiers the Platform Verifiers pin:
# circuits.json pins a libid-circuits release; the
# Solidity and the platform table (platforms.json,
# handles.json) are vendored from it and not committed
handles/ # HandleNode: the A-Z fold and the node hash
identity/ # IdentityRegistry
escrow/ # HandleEscrow: value sent to a handle before it is proved
referral/ # ReferralSplitter: the bind fee it sets, split between
# a referrer's handle and the treasury
ens/ # HandleResolver
factory/ # LibidFactory: deterministic CREATE3 deployment
WTIA9.sol # wrapped TIA
script/Deploy.s.sol
lib/ # git submodules (openzeppelin, forge-std)
rust/contracts/ # libid-contracts: alloy bindings + embedded artifacts
rust/identity/ # libid-identity: handle normalization, id rules, nodes
rust/profiles/ # libid-profiles: the ceremony profile constants
ts/packages/contracts/ # @libid/contracts: viem ABIs, call builders, identity helpers
scripts/ # vendoring, generators, release and CI helpers
git submodule update --init --recursive
scripts/vendor-circuit-verifiers.sh # -> solidity/contracts/circuits/*HonkVerifier.sol
cd solidity
forge build
forge testThe Honk verifiers and the platform table are gitignored and downloaded from
the pinned libID-circuits
release (see Circuit verifiers). The vendor script needs
curl, jq, tar, forge, cast, cmp and shasum or sha256sum. Two more gitignored trees are generated from
forge build; regenerate them after any change to a contract they cover:
scripts/vendor-artifacts.sh # -> rust/contracts/artifacts (the crate embeds
# it with include_dir!; cargo fails without it)
pnpm -C ts codegen # -> ts/packages/contracts/src/{abis,calls}
# (`pnpm -C ts build` needs them)CI's forge-build action vendors the verifiers before every build, and every job that compiles the crate or the package regenerates its tree, so the published crate and npm package carry the generated output.
libID-circuits' lib/identity/platforms.json holds each platform's node tags,
the circuits' buffers and its id shape; its lib/identity/handles.json holds
the shared vector table. scripts/vendor-circuit-verifiers.sh vendors both
into solidity/contracts/circuits/. After the pin moves:
python3 scripts/regen-identity-handles.py # rewrite generated outputs
python3 scripts/regen-identity-handles.py --check # verify nothing drifted
python3 scripts/regen-ceremony-profiles.py # the ceremony profile constantsregen-identity-handles.py writes the platform tables and refusals
(rust/identity/src/platforms.rs, ts/packages/contracts/src/platforms/platforms.ts)
and the vector tables beside them (vectors.rs, vectors.ts).
regen-ceremony-profiles.py writes CeremonyProfile.sol and its Rust and
TypeScript mirrors from profiles.json, taking the node tags from
platforms.json. Both outputs are committed, and CI's Generated tables job
fails when either drifts. On chain a handle is only folded, by HandleNode,
and forge runs the vectors from the vendored handles.json.
bb derives each ceremony circuit's UltraHonk verifier from its verification
key. libID-circuits runs bb
and ships the Solidity, with the platform table, in its release tarballs.
scripts/vendor-circuit-verifiers.sh downloads them into
solidity/contracts/circuits/, formatted, where forge build compiles them
and the crate embeds them, so no consumer runs bb.
solidity/contracts/circuits/circuits.json is the pin: the release version
and each tarball's sha256, checked against every download. To move it, write
the new release's version and tarball digests into circuits.json, then:
scripts/vendor-circuit-verifiers.sh # rewrite the verifiers from the pinA change spanning both repositories lands circuits first: libID-circuits tags
a release, then circuits.json pins it here and the tables are regenerated.
Each Platform Verifier pins its circuit's verifier on chain by runtime code
hash: initialize, setTrustRoots and verify revert WrongCircuit for any
other code. The hashes are constants in
solidity/contracts/circuits/CircuitCodehashes.sol, which the vendor script
writes and which is committed. forge test compares it with the verifiers on
disk; the forge-build action's git diff --exit-code after vendoring guards
the committed file. Locally:
scripts/vendor-circuit-verifiers.sh
git diff --exit-code solidity/contracts/circuits/CircuitCodehashes.sol \
solidity/contracts/circuits/IHonkVerifierErrors.solCommit both generated files with circuits.json whenever the pin moves. A new circuit release
is a new Platform Verifier implementation, not a trust-root rotation.
The registry keys identities by the nodes the circuits output, and each Platform Verifier decodes a payload that carries those nodes. This stack ships only as a fresh deployment under new canonical names; never upgrade a live proxy onto it:
IdentityRegistryuses the storage namespacelibid.storage.IdentityRegistryand its slots hold nodes: a proxy upgraded from a registry keyed otherwise would read stored entries as nodes.- The
x,githubandgoogleceremonies are at ceremony version 1 with node-carrying payloads, so a client built for another payload shape is refused at decode. HandleEscrowis deployed against this registry, never upgraded or re-pointed: its deposits are keyed by handle node, andinitializereverts unless the registry'snodeKeyed()returns true.
The Rust crates (libid-contracts,
libid-identity, libid-profiles) and the npm package
(@libid/contracts) release
together under one version. A release is cut by publishing a GitHub Release
tagged v<version>; nothing publishes from pushes or PRs.
./scripts/bump-version.sh 0.2.0 # sets the Cargo.toml files, Cargo.lock, package.json
git checkout -b release/v0.2.0
git commit -sam "chore: release v0.2.0"
# open a PR, get it merged, then:
gh release create v0.2.0 --title "v0.2.0" --generate-notesPublishing the release triggers CI's release jobs:
verify-tag: the tag must equal the version in every manifest. Theversionsjob checks the manifests agree on every PR.publish-crates: after the Solidity, Rust, Generated tables and publish dry-run jobs pass,cargo publishoflibid-identity,libid-profilesandlibid-contractswithCARGO_REGISTRY_TOKEN. A crate already on crates.io at this version is skipped, so a re-run finishes a partial release.publish-npm: afterpublish-crates, builds and publishes@libid/contractswith provenance, authenticated by npm OIDC trusted publishing. A prerelease publishes under its first prerelease identifier as the dist-tag (1.2.0-rc.1→rc); a plain version underlatest.
Dual-licensed under MIT and Apache-2.0; see LICENSE-MIT, LICENSE-APACHE
and CONTRIBUTING.md.