@cobuild/wire

Shared wire-level contracts for Cobuild clients/services.

Scope

• OAuth constants + scope/PKCE/redirect validation helpers
• JWT claim parsing helpers for CLI access token payloads
• EVM/wallet validation helpers for network/token/mode contracts
• Bearer token parsing
• Idempotency key/header contract
• Goal-create calldata validation/builders and GoalDeployed receipt decoding helpers
• Base-only governance planners, payload coders, and receipt decoding helpers
• Base-only participant write planners for treasury donations, stake/premium flows, prize-vault claims, and flow allocation maintenance
• x402 payload/domain/type builders + payload validation
• Farcaster signup wire contracts (typed-data, preflight, call-plan + executable-call builders)
• Farcaster hosted contract envelopes for signup success/error responses and x402 payment responses

Non-goals

• Signing runtime (wallet/CDP implementations)
• DB adapters or framework/server bindings
• UI components

Quick start

pnpm install
pnpm typecheck
pnpm test

Protocol ABI generation

pnpm wagmi and pnpm generate keep Basescan as the default ABI source of truth. For fast post-deploy refreshes inside this workspace, use the local-artifact mode instead.

• pnpm generate:local (or WIRE_ABI_SOURCE=local pnpm wagmi) uses sibling v1-core/out artifacts so ABI refreshes do not wait on explorer verification.
• Default mode is Basescan; WIRE_ABI_SOURCE=basescan forces the same behavior explicitly.
• WIRE_ABI_SOURCE=local requires sibling Forge artifacts and fails fast if they are missing.
• BASESCAN_API_KEY (fallback ETHERSCAN_API_KEY) is required for default Basescan generation.
• WIRE_V1_CORE_PATH can override the default sibling v1-core repo location when needed.

Consumer workflow

Committed downstream state should use the published @cobuild/wire package, not a sibling link: or file: dependency.

• Current direct consumers in this workspace: cli, chat-api, indexer, and interface/apps/web.
• cli, chat-api, and interface/apps/web expose temporary local integration helpers (wire:use-local / wire:use-published) for testing unpublished wire changes against a sibling checkout.
• cli, chat-api, interface, and indexer all run wire:ensure-published from pre-commit so local link/file specs do not land in commits by accident.

After publishing a new @cobuild/wire version, bump only the sibling repos that consume the changed surface:

• ABI/address/event changes usually require indexer first, then any user-facing consumers.
• Auth, wallet, x402, or Farcaster helper changes usually require chat-api, cli, and/or interface/apps/web.
• Use each consumer repo's local published-version helper where present; otherwise update the dependency semver directly and refresh the lockfile.

wire now exposes a manual sibling sync helper:

pnpm run sync:repos -- --version 0.1.5 --wait-for-publish

The wrapper delegates to the shared cobuild-sync-dependent-repos helper from @cobuild/repo-tools. Before the next published repo-tools bump lands here, it falls back to the sibling repo-tools checkout in this workspace if the installed bin is not present yet.

Release runs can invoke the same flow automatically after push. Use --no-sync-upstreams or WIRE_SKIP_UPSTREAM_SYNC=1 when you need to prepare a release tag without bumping sibling repos yet.