a437feb8ab
openpay/
compliance/ PCI-DSS readiness package (scope-map,
pci-zero-architecture, hsm-kms-guidance,
qsa-checklist), citing PCI-DSS v4.0.1
requirements. (#1)
examples/pci-zero/ Runnable example demonstrating a deployment
where merchant code never touches a PAN. (#1)
crates/op-core/ Tokenized<Card> typestate + NetworkToken
+ CardNetwork + Cryptogram. (#2)
crates/op-rails-card/network_token/
NetworkTokenProvider trait + VTS adapter
+ MDES adapter, with deterministic stubs
behind a 'live' feature flag. (#2)
crates/op-driver-sdk/conformance/network_token.rs
Conformance harness for third-party
NetworkTokenProvider implementations. (#2)
crates/op-cli/src/ledger/ 'openpay ledger as-of' subcommand for
bi-temporal queries. (#3)
crates/op-orchestrator/src/telemetry.rs
OpenTelemetry span emission per
Payment<S> transition with semantic-
conventions tags. (#3)
docs/observability/ Grafana dashboard JSON + wiring guide
for the bi-temporal ledger lens. (#3)
smart-byte/
smart-byte-rs/ Rust reference implementation: envelope
encode/decode (canonical CBOR + BLAKE3
content addressing), Ed25519 sign +
verify, lockstep BFT commit MVP, Iroh
transport scaffold, CLI. (#4)
spec/identity_and_key_rotation.md
Adopts KERI SAIDs + key-event log
format; explicitly does not adopt ACDC
chaining wholesale. (#5)
conformance/v1/ 21 test vectors covering canonicalisation,
SAID computation, signature verification,
lockstep commit, gossip propagation.
CI gate enforces spec/vector coupling. (#6)
eoc/
eoc-rs/ Rust + WASM reference implementation:
4-stage cascade (cache -> kv -> graph ->
neural), joule counters via RAPL / NVML /
powermetrics, CLI, wasm-bindgen surface.
18 tests pass. (#7)
eoc-bench/ Benchmark harness, MT-Bench and Router
case sets, 'joules per MT-Bench point'
metric, 'eoc-bench run | compare' CLI. (#8)
standards/sci-for-ai-submission.md
Submission proposal mapping EOC's
receipt schema to GSF SCI-for-AI. (#9)
cookbook/ HuggingFace-style cookbook (markdown +
runnable Python) demonstrating EOC's
cascade with HF AI Energy Score. (#9)
docs/bench-v0.md Reproducibility doc for eoc-bench.
Workspace state:
- openpay clippy -- -D warnings: clean across all touched crates
- smart-byte-rs cargo test --workspace + clippy: clean
- eoc-rs cargo test --workspace + clippy: clean (18 tests)
- eoc-bench cargo check --workspace + clippy + 15 tests: clean
Rust 1.95.0 edition 2024 pinned at the open-standards root via
rust-toolchain.toml; every workspace inherits.
Closes #1 #2 #3 #4 #5 #6 #7 #8 #9.
112 lines
3.9 KiB
Markdown
112 lines
3.9 KiB
Markdown
# OpenPay Observability
|
|
|
|
The bi-temporal append-only ledger is one of OpenPay's architectural
|
|
moats: every state transition is a recorded event with both a
|
|
*valid-time* (when the event happened in the real world) and a
|
|
*transaction-time* (when the ledger learned of it). Inspecting that
|
|
moat requires three things: a CLI for ad-hoc queries, OpenTelemetry
|
|
traces over the live `Payment<S>` typestate, and a Grafana dashboard
|
|
to watch the system from the operations side.
|
|
|
|
This directory holds the second and third.
|
|
|
|
## Wiring up
|
|
|
|
### 1. OpenTelemetry collector
|
|
|
|
```yaml
|
|
# otel-collector.yaml
|
|
receivers:
|
|
otlp:
|
|
protocols:
|
|
grpc:
|
|
endpoint: 0.0.0.0:4317
|
|
http:
|
|
endpoint: 0.0.0.0:4318
|
|
exporters:
|
|
prometheus:
|
|
endpoint: 0.0.0.0:9464
|
|
service:
|
|
pipelines:
|
|
metrics:
|
|
receivers: [otlp]
|
|
exporters: [prometheus]
|
|
traces:
|
|
receivers: [otlp]
|
|
exporters: [prometheus]
|
|
```
|
|
|
|
### 2. OpenPay process
|
|
|
|
Compile `op-orchestrator` with the `telemetry` feature and set
|
|
`OPENPAY_OTLP_ENDPOINT=http://localhost:4317` in the environment.
|
|
`op_orchestrator::telemetry::init_telemetry(...)` wires the global
|
|
subscriber at startup. Every `Payment<S>` state transition emits a
|
|
span with these attributes:
|
|
|
|
| Attribute | Type | Example |
|
|
|-----------------------|---------|-------------------------------|
|
|
| `payment.id` | string | `pay_019e30baa...` |
|
|
| `payment.state.from` | string | `Authorized` |
|
|
| `payment.state.to` | string | `Captured` |
|
|
| `payment.rail` | string | `card` · `a2a` · `crypto` |
|
|
| `payment.amount.minor`| int | `1299` |
|
|
| `payment.amount.currency` | string | `USD` |
|
|
|
|
### 3. Prometheus + Grafana
|
|
|
|
Scrape the collector's prometheus exporter at `:9464`. Import
|
|
[`grafana-dashboard.json`](grafana-dashboard.json) into Grafana. The
|
|
dashboard ships with three template variables: `$rail`, `$currency`,
|
|
and the standard `$time_range`.
|
|
|
|
## Example bi-temporal query
|
|
|
|
> What was account `acct_019e3...`'s balance on **May 4** as we knew
|
|
> it on **May 5**?
|
|
|
|
```bash
|
|
op ledger as-of \
|
|
--valid 2026-05-04T00:00:00Z \
|
|
--transaction 2026-05-05T00:00:00Z \
|
|
--account acct_019e30baa9507793b467ac644636b3e2 \
|
|
--human
|
|
```
|
|
|
|
Output (with `--human`):
|
|
|
|
```
|
|
account acct_019e30baa9507793b467ac644636b3e2
|
|
valid-time 2026-05-04T00:00:00Z
|
|
transaction-time 2026-05-05T00:00:00Z
|
|
balance 12_450 minor USD
|
|
entries-cited 487
|
|
```
|
|
|
|
Strip `--human` to get the same content as structured JSON for
|
|
scripting and reconciliation tooling.
|
|
|
|
## What the dashboard shows
|
|
|
|
- **State-transition rate** — transitions per second by `(from, to)`
|
|
pair. Spikes on `Authorized → Captured` are the healthy steady state;
|
|
`* → Refunded` rate is the dispute / refund pulse.
|
|
- **In-flight by state** — current count of payments in each typestate.
|
|
Long tails in `Authorized` indicate captures that aren't landing.
|
|
- **Refund vs capture ratio** — short-window and long-window. Spikes
|
|
beyond a configurable threshold can be wired into the alert manager.
|
|
- **Rail split** — card vs A2A vs crypto, by volume and by count.
|
|
- **Latency per transition** — p50 / p95 / p99 per state transition,
|
|
bucketed by rail.
|
|
- **Error rate per state** — counts of `Err(...)` returns from each
|
|
state-transition function, bucketed by rail and error class.
|
|
|
|
## Recompute history
|
|
|
|
The bi-temporal property of the ledger is the real magic: when an old
|
|
reconciliation finds a discrepancy in last week's data, recording the
|
|
correction does not rewrite history. It appends a new entry with
|
|
*valid-time = last week, transaction-time = now*. The CLI query above
|
|
will return the correction when asked from "now" forward and the
|
|
original (uncorrected) state when asked from before "now". The
|
|
dashboard's data source does the same.
|