Shared wire contracts for the CAFE stack: versioned structs, constants, and JSON-oriented validation helpers used across repositories. This module is a library only—it does not run as a service.
- Envelope and payload types for cross-service messages (e.g. Discovery → CPM observations).
- Exported string/enum constants for wire fields (algorithm IDs, posture labels, account kinds).
- Minimal validation that checks shape and required fields at the contract boundary.
- Canonical JSON fixtures and tests that lock serialization formats.
| Concern | Where it lives |
|---|---|
| Policy graphs, templates, instances, ranking, assessment | cafe-cpm (Crypto Policy Management) |
| Chain indexing, wallet discovery, persistence, producing observations | cafe-discovery |
| Remediation orchestration, operator workflows | Remediation services (separate repos) |
| NATS subscriptions, connection lifecycle, retries | Application code in each service; this repo may define payload types only |
Rule of thumb: if it encodes business policy or runtime wiring, it is not a cafe-contracts concern. If it defines what bytes travel on the wire so two teams can compile against the same types, it belongs here.
eventenvelope/v01/— shared event header contract (event_id,event_type,event_version,occurred_at,correlation_id,causation_id,producer) with minimal validation and canonical JSON fixture(s).observation/wallet/v01/— normativecafe.discovery.wallet.observedwire contract (event_versionv0.1):Event,Subject,Payload, exported vocabulary (account kind, algorithm ID, PQ posture, subject type),Validate(), and canonical JSON undertestdata/.cafenatsv01/— policy and remediation NATS/JSON contract bundle (event_versionv0.1 envelope):policy.assessment.requested(explicit CPM command; assessment payload v0.2 = embeddedobservation/wallet/v01snapshot +crypto_policy_id; rejectsselection_request/ couche-B fields), outbound CPM events (validation, activation, assessment, remediation request), Remediation service events, versionedNATSSubject*constants, andMAPPING.md(model-to-wire reference). No brokers or runtime logic. Naming note: this directory is transitional and is planned to be renamed to a business-oriented path (policyflow/v01,remediationflow/v01, or equivalent validated target) in a follow-up migration.address/— shared EVM address helpers for boundary handling:IsValidHexAddress,NormalizeAddress(lowercase canonical),EqualAddress(case-insensitive via canonical form), andToChecksumEIP55for user-facing rendering.validation/— tiny, reusable helpers (non-empty strings, field-scoped errors) for contract packages.
- Normative observation contract path:
observation/wallet/v01. - Normative wire identifiers:
event_type = cafe.discovery.wallet.observed,event_version = v0.1.
Import example:
import eventenvelopev01 "github.com/create2-labs/cafe-contracts/eventenvelope/v01"
import walletobsv01 "github.com/create2-labs/cafe-contracts/observation/wallet/v01"
import "github.com/create2-labs/cafe-contracts/cafenatsv01"Version directories use a short semver-like segment (v01 = 0.1) to keep import paths stable and readable.
For cross-service consistency:
- Accept EVM addresses in any valid casing at boundaries.
- Normalize to lowercase for machine keys (storage/idempotency/cache/comparison).
- Use EIP-55 checksum only for display-oriented contexts.
Example:
import "github.com/create2-labs/cafe-contracts/address"
normalized, err := address.NormalizeAddress("0x742d35Cc6634C0532925a3b844Bc454e4438f44e")
if err != nil {
// handle invalid input
}
same := address.EqualAddress(
"0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
"0x742d35cc6634c0532925a3b844bc454e4438f44e",
)
_ = normalized
_ = sameAdd to go.mod:
require github.com/create2-labs/cafe-contracts v0.0.0Use tagged releases once published; during integration, replace in a workspace is fine.
go test ./...
go vet ./...CI runs tests on pull requests to main. Release automation uses release-please (Go release type) to propose version bumps and changelogs from conventional commits.