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.
114 lines
5 KiB
Markdown
114 lines
5 KiB
Markdown
# Smart Byte Conformance Vectors
|
|
|
|
This directory contains the conformance test-vector pack for the Smart Byte
|
|
substrate specification. Any third-party implementation, in any language, can
|
|
consume these vectors to self-certify against the canonical wire format
|
|
*without* trusting the reference implementation.
|
|
|
|
The vectors are the social contract. The spec text in `../spec/` says what the
|
|
substrate is; the vectors here say what the substrate's wire format *looks
|
|
like, byte for byte*, on the inputs the spec text describes. An implementation
|
|
that passes the vectors is canonical. An implementation that fails the vectors
|
|
is not.
|
|
|
|
The vectors are licensed CC-BY-4.0, consistent with the spec directory. They
|
|
contain no `$ref` pointers, no external URLs, and no runtime dependencies.
|
|
|
|
## What is in the pack
|
|
|
|
Each spec version has its own subdirectory (`v1/`, `v2/`, ...). Today only
|
|
`v1/` exists; it corresponds to the spec text in
|
|
`../spec/treatise_v1_parts_I_II_III_combined.md`.
|
|
|
|
A pack for a given version contains five JSON files plus `regeneration.md`:
|
|
|
|
| File | Tests |
|
|
| -------------------------------- | -------------------------------------------------------- |
|
|
| `canonicalisation_vectors.json` | CBOR canonical-encoding rules (§8 wire format) |
|
|
| `said_vectors.json` | SAID computation: BLAKE3-256 over canonical CBOR (§8.2) |
|
|
| `signature_vectors.json` | Ed25519 sign + verify over SAIDs (§8.3, §8.4) |
|
|
| `lockstep_vectors.json` | BFT supermajority commit logic (§9, §13) |
|
|
| `gossip_vectors.json` | Gossip propagation, conflict detection, ordering (§17) |
|
|
|
|
`regeneration.md` documents how to regenerate the vectors from the Rust
|
|
reference implementation (`smart-byte-rs`, landing alongside spec v1.0).
|
|
|
|
## How to consume the vectors
|
|
|
|
Each JSON file is a top-level array of vector objects. Vector objects share
|
|
the common shape:
|
|
|
|
```json
|
|
{
|
|
"name": "short-stable-identifier",
|
|
"description": "human-readable description of what is being tested",
|
|
...test-specific fields...
|
|
}
|
|
```
|
|
|
|
The conventional flow for an implementation under test (IUT):
|
|
|
|
1. Load the JSON file for the relevant spec version.
|
|
2. For each vector, run the IUT against the `input` (or equivalent field)
|
|
and compare its output to the `expected_*` field.
|
|
3. A vector passes if the IUT's output is byte-for-byte equal to the
|
|
`expected_*` field (or, for negative vectors, the IUT rejects the input
|
|
with the documented `error` class).
|
|
4. The IUT is canonical for a spec version iff every vector in that
|
|
version's pack passes.
|
|
|
|
There is no scoring, no "mostly conforms" status, and no waiver process.
|
|
A vector pack is a hard gate.
|
|
|
|
## Versioning rule
|
|
|
|
Vectors are versioned **per spec version**, not per implementation, not per
|
|
calendar release of the conformance pack.
|
|
|
|
- `v1/` corresponds to spec v1. Once spec v1 is frozen, `v1/` is append-only
|
|
in scope (additional vectors may be added that test the *same* canonical
|
|
wire format) and never modifies existing vectors' `expected_*` outputs.
|
|
- `v2/` will appear when (and only when) the spec moves to a new version
|
|
that introduces an incompatible wire-format change. The compatibility
|
|
matrix lives in `VERSIONS.md`.
|
|
- A bug in a vector pack (e.g. an `expected_*` field that disagrees with
|
|
the spec) is fixed by superseding the vector with a new one whose `name`
|
|
carries a suffix (`-fixed`, `-corrected`); the original is retained with
|
|
a `"superseded_by"` field so historical IUTs that pinned to the old
|
|
vector can detect the supersession.
|
|
|
|
## CI gate
|
|
|
|
`../../.github/workflows/conformance.yml` is the repository-level CI gate.
|
|
Every PR that touches `smart-byte/spec/` or `smart-byte/conformance/` must
|
|
pass the gate. The gate validates:
|
|
|
|
- Every JSON file in `v*/` parses as valid JSON.
|
|
- Every spec change is accompanied by a vector-pack update (a PR that
|
|
modifies `smart-byte/spec/` without modifying `smart-byte/conformance/`
|
|
is rejected at the gate).
|
|
|
|
The gate's purpose is procedural: a spec change without a vector change is
|
|
either a clarifying edit (which should declare itself by also touching the
|
|
vector pack's `regeneration.md` to record the editorial reason) or a
|
|
silent wire-format change (which is prohibited). Either way, both
|
|
directories move together.
|
|
|
|
## What the pack does not cover
|
|
|
|
The pack is the wire-format gate. It does not cover:
|
|
|
|
- Application-layer cargo schemas. Cargo is opaque to the substrate; what
|
|
a USD-byte or a joule-byte or a sensor-reading-byte *means* is a
|
|
layer-2 protocol concern. Layer-2 protocols ship their own vectors.
|
|
- Performance. The pack tests correctness, not throughput, latency, or
|
|
energy cost. Performance is documented in the reference implementation's
|
|
benchmarks.
|
|
- Operational concerns. Cluster topology choice, key custody, hardware
|
|
procurement, regulatory compliance for specific cargo types — all out
|
|
of scope for the substrate's conformance pack.
|
|
|
|
## License
|
|
|
|
The vector pack is licensed CC-BY-4.0. See `../../LICENSE` for the
|
|
repository-level license terms.
|