The compliance gates
A POST /batches request runs through four gates in order. Gates 1–3 all execute and accumulate any rejection reasons. Gate 4 (OFAC) only runs when the first three pass — sanctions-list lookups are the most expensive check, and there is no reason to pay for one on a batch that already failed an earlier gate.
1. Form PR zero-flare
We look up the Texas Railroad Commission Form PR record for the lease and declared production month, and verify that the flared gas volume recorded under RRC Disposition Code 4 is zero. If any gas was vented or flared during the vintage month, the batch is rejected with reason is_zero_flare.
2. Severance status
We check the lease against the RRC Severance Master list. A severed lease means the operator is in violation of state environmental or safety rules and has been ordered to stop production. A severed lease fails this gate with reason severance_clear.
3. Volume ceiling
We sum every previously declared volume for the same lease and production month, add the new declared volume, and verify the total does not exceed the Form PR oil volume the RRC records for that lease-month. This is the primary fraud defense: an operator cannot attest to more clean oil than the state recorded them pumping. Over-ceiling submissions fail with reason volume_ceiling_exceeded.
4. OFAC SDN
We screen the operator name against the US Treasury Office of Foreign Assets Control Specially Designated Nationals list. A match fails the batch with reason ofac_hit. Results are cached per operator with a configurable TTL (24 hours by default) so repeat declarations from a known-clear operator do not hit the external screening API. A nightly re-check job re-screens every active operator and, on a newly-non-clear result, appends an OFAC_FLAG event to every previously-VERIFIED batch that operator produced — flipping those batches to FLAGGED without mutating the original event.
The vintage anchor
A batch is locked to a production month (vintage), not the current date. When an operator declares a batch for March 2026, every compliance gate runs against that month’s Form PR data and that month’s severance status — not the most recent available data.
This resolves the Form PR latency problem cleanly. RRC production data is typically one to six weeks stale at any given moment, and the environmental status of a lease can change after a vintage month closes. The vintage anchor reframes the attestation: we are not signing a claim about current status, we are signing a claim about the state of a completed period. If a lease begins flaring in April, that has no bearing on a March batch. The environmental compliance statement on a Digital Passport is immutable once issued.
The Ed25519 signing flow
When all four gates pass, the API builds a canonical JSON payload of the attested facts, SHA-256 hashes it, and signs the hash with an Ed25519 private key. The signature and the hash are persisted on the DigitalPassport row alongside a signing_key_id recording which key version produced the signature — so historical passports remain verifiable across key rotations.
The canonical payload looks like this:
{
"batch_uuid": "550e8400-e29b-41d4-a716-446655440000",
"issued_at": "2026-04-10T14:32:00Z",
"lease_id": "RRC-12345",
"operator_id": "P5-67890",
"production_month": "2026-03",
"declared_volume_bbl": 10000,
"is_zero_flare": true,
"flare_volume_mcf": 0,
"severance_clear": true,
"ofac_clear": true,
"payload_hash": "<sha256 of above fields>"
}
The corresponding public key set is published as a standards-compliant JWKS document at /.well-known/jwks.json, so any third party can verify a passport signature locally without contacting us. See the /security page for more on the cryptographic and operational posture.
The Digital Passport artifact
A successful declaration produces a Digital Passport with a stable UUID. The passport is renderable as a PDF — used for letter-of-credit document packets — and queryable at a public verify endpoint. The PDF carries a QR code linking to the verify endpoint so a bank compliance officer can move from paper to live status in one scan.
A GET /verify/:uuid call returns the current status, the issuance timestamp, a cryptographic validity result, and the ordered event log. For a clean, unflagged batch the response is:
{
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"current_status": "VERIFIED",
"issued_at": "2026-04-10T14:32:00Z",
"signature_valid": true,
"events": [
{ "type": "VERIFIED", "occurred_at": "2026-04-10T14:32:00Z" }
],
"flags": []
}
Post-issuance events (an OFAC re-check flip, a severance-list update) append as additional events; they do not mutate the original VERIFIED event. A bank that funded a trade in good faith based on a timestamped passport can demonstrate exactly what the attested state was at the time of funding, even if the status flips afterwards.