Writer API & Zevo integration

The ingest writer service (services/ingest/cmd/writer in the chain repo) accepts HTTPS submissions from the Carbon12 platform backend and broadcasts signed MsgIssue rows for schema scope3_business_travel_v1 (ADR-0023).

Public deployments

Do not use private keys from devnet/genesis/keys.json on internet-facing writers. Mint a fresh ops key and gov-admitted participant for hosted testnet (services/ingest/sdk/README.md).

Run locally (chain repo)

make install
make devnet-env   # or make testnet-up

export C12_CHAIN_ID=c12-testnet-1
export C12_GRPC=52.6.69.73:9200
export C12_RPC=https://rpc.testnet.carbon12.network
export C12_HOME=$HOME/.c12d
export INGEST_API_KEY=your-secret-key
export INGEST_STORE=/var/lib/c12/ingest-store

go run ./services/ingest/cmd/writer

INGEST_API_KEY is required — process exits if unset (services/ingest/writer/server.go).

Authentication

Fail-closed constant-time comparison. Send either:

• Authorization: Bearer <INGEST_API_KEY>
• X-API-Key: <INGEST_API_KEY>

POST /v1/zevo/trips

Idempotent by booking id / derived event id.

Request body (JSON):

{
  "booking_id": "zevo-booking-1001",
  "fleet_ref": "zevo-fleet-1",
  "start": "2027-01-10T14:00:00Z",
  "end": "2027-01-10T15:30:00Z",
  "distance_miles": 12.4,
  "co2e_g": 4520,
  "state": "CA",
  "geohash": "9q5cs"
}

Field	Notes
booking_id	Idempotency key
fleet_ref	Maps to registered asset (e.g. a:zevo-fleet-1 fixture)
distance_miles	Converted to integer metres off-chain before issue
co2e_g	Integer grams CO₂e (co2e parameter)
geohash	Optional; see geohash resolution below

Response:

{
  "issued": 1,
  "skipped": 0,
  "event_id": "...",
  "tx_hash": "..."
}

POST /v1/zevo/trips/sync

Polls Zevo adapter and issues new trips.

• Optional header X-Since-RFC3339 for incremental sync.
• Live mode: set ZEVO_TRIPS_URL and ZEVO_API_TOKEN (Bearer to Zevo core API).
• Without live env, adapter replays adapter/zevo/fixtures/trips_q1.json.

Geohash resolution

Order (normalize.ResolveTripGeohash):

1. Explicit geohash on request (validated)
2. Coarse prefix from state (e.g. CA → 9q5c)
3. INGEST_DEFAULT_GEOHASH env
4. Empty string (valid for mobile assets)

Platform notes

• POCA / emission factors stay off-chain; chain stores integer quantities only.
• Fund minter bank account (p:zevo-integrator on fixtures) for gas and checking deposits.
• Custodial wallet products: subject to counsel before mainnet (sdk/README.md).

Go reuse

import (
  "github.com/Carbon12-Chain/chain/services/ingest/adapter/zevo"
  "github.com/Carbon12-Chain/chain/services/ingest/submitter"
)

Use submitter.RunTrips with a poll function for batch jobs.

Hosted URL

The hosted Writer API HTTPS base URL is available to integration partners on request (contact Carbon12 Labs / your integration channel). Route shape and auth are normative from services/ingest/writer/server.go:

• POST /v1/zevo/trips
• POST /v1/zevo/trips/sync

Deploy the writer yourself for lab use with go run ./services/ingest/cmd/writer (see above).