feat(sol): LibID, a Solidity library for using libID from contracts

[SupremaLex]

LibID, a Solidity library for using libID from contracts. It lives in sol/ so the contracts repo does not have to know its own deployed addresses.

import {LibID} from "libid/LibID.sol";

LibID.requireHolder(LibID.GITHUB, handle, 2 hours);
address holder = LibID.resolve(LibID.GITHUB, "octocat");
bytes32 node = LibID.pay(LibID.GITHUB, handle, msg.value, msg.sender);

What it is

• One file, sol/src/LibID.sol. It imports nothing, and every function is internal, so there is nothing to deploy or link. It works with solc 0.8.20 and later.
• Built-in addresses, one library per environment. libID-contracts 0.17.0 gives each environment its own factory, so LibID has the production addresses (Ethereum mainnet: IdentityRegistry 0xbefD…9a83, HandleEscrow 0x17a2…bbf7). LibIDTestnet has the same functions with the testnet addresses (Sepolia and Eden: 0x25F2…D640, 0x5735…d8e5). It is generated from LibID.sol by sol/script/testnet.sh, so an integrator switches with import {LibIDTestnet as LibID} from "libid/LibIDTestnet.sol";. Within an environment the addresses never change; contract updates are upgrades at the same address.
• Reads:
  • resolve, with or without a maximum proof age;
  • bindingOf, which returns the holder and observedAt;
  • resolveId and publishedHandleOf.
• Gates: isHolder and requireHolder, which revert NotHolder(holder, caller) or ProofTooOld(observedAt).
• Payments through HandleEscrow:
  • pay (ETH) and payToken (ERC-20) both return the escrow node, which comes from the registry's handleNodeOfHash; both revert LibIDUnavailable unless the escrow resolves through LibID's registry;
  • refund(handleNode, …) takes that node back.
• Availability:
  • isAvailable() covers the registry, which is enough for reads and gates;
  • isEscrowAvailable() covers payments, and also checks that the escrow resolves through that registry.
  • Every other function reverts LibIDUnavailable on a chain without the contract it needs.

Behaviour to know

• Proof age. A proof bound a moment ago can read 0 to 65 minutes old on GitHub and X, and 0 to 2 hours on Google (5 minutes and 1 hour when the notary's and chain's clocks agree). The verifiers date observedAt a fixed allowance before the evidence, and accept evidence that is already a while old. The NatSpec and README give these ranges.
• Handles: case never matters. A leading @ is dropped on GitHub and X. Google handles keep dots and +tags, and a leading @ is invalid there.
• Payments call out. When the handle is held, the holder's code receives the ETH. Callers must guard against reentrancy, and should avoid paying many handles in one call.
• Approvals: payToken approves the amount first and resets to zero only if the token refuses. It reads only the first word of the answer.

Tests (sol/test/LibID.t.sol)

• Real contracts: the libID-contracts v0.15.0 proxies are placed at the built-in addresses with vm.etch, and handles are bound through the real bind. Bindings are dated as the real verifiers date them, using the allowances from CeremonyProfile, at both ends of each acceptance window.
• Addresses: a test recomputes both libraries' addresses from their environment's factory and the CREATE3 derivation of the canonical names.
• 54 tests, including payments whose node comes from the registry's handleNodeOfHash, an escrow bound to another registry, token refunds (plain and both fee-on-transfer kinds), both ends of each verifier's age window, and the test base below.
• LibIDTestBase (sol/src/test/LibIDTestBase.sol): a Foundry base for integrators testing their own contracts.
  • It places the real contracts at the built-in addresses, with a stand-in verifier this repo owns.
  • On a fork where libID is already deployed, it uses that deployment.
  • It works inside a caller's prank.
  • bindHandle dates proofs at the platform's real age (5 minutes for GitHub and X, 1 hour for Google) and advances the clock, so binds in one block do not collide.
  • The README gives context-specific remappings and compiler settings. sol/integrator/ is a project built from exactly those lines on solc 0.8.24, and CI builds and tests it.
• Fork tests against live Ethereum mainnet (LibID), Sepolia and Eden (LibIDTestnet). Each reads, then pays a fresh handle in ETH and in a token and refunds it, and binds through LibIDTestBase on the live deployment, on the local fork only. They are skipped locally without ETH_RPC_URL, SEPOLIA_RPC_URL and EDEN_RPC_URL. In CI, LIBID_REQUIRE_FORK makes a missing RPC fail the step.
• Dependencies: libID-contracts v0.15.0 and forge-std v1.17.0 are git submodules under sol/lib/, pinned in the committed foundry.lock. LibIDTestBase imports libID-contracts; LibID.sol imports nothing.

CI

A new sol job runs on pushes to main, nightly (to catch drift in the live deployments), and on pull requests that touch sol/, .gitmodules or the CI workflow:

• forge fmt --check;
• forge lint -D notes;
• script/testnet.sh, failing if LibIDTestnet.sol changes;
• a solc 0.8.20 legacy-pipeline build of LibID.sol and LibIDTestnet.sol;
• forge test;
• the mainnet, Sepolia and Eden fork tests;
• the integrator project (script/integrator.sh).

Known limitations

• Install size: forge install libid-org/libid pulls the whole repo and the test-only submodules for one file.
• Registry calls: a held handle costs two calls, an unheld one three. libID-contracts popup: mobile-WebKit flake in close-right-after-navigate (CI only) #86 adds handleBindingOf, which makes it one, once deployed.
• Local chains: a local deployment lands at other addresses; in tests, LibIDTestBase places the contracts at the built-in ones.
• CI depends on public RPCs: the fork step calls publicnode for mainnet and Sepolia, and Eden's own RPC.

[cloudflare-workers-and-pages]

🚀 Deploying Preview to Cloudflare 🚀

Preview URL: https://feat-solidity-lib.previews.lib.id, https://feat-solidity-lib-libid.grounded-systems.workers.dev (commit 6be51e6)

This URL reflects your latest Preview deployment

Preview Deployments by commit

Status	Deployment URL	Commit	Updated (UTC)	See this deployment's details
Build: Success ✅ Deployment: Success ✅ View logs ↗	https://19205aba.previews.lib.id, https://19205aba-libid.grounded-systems.workers.dev	6be51e6	2026-10-05T10:03:26.829Z	Visit the dashboard ↗