Evidence

Evidence is the flagship Yano X product. It takes a document — a product inspection certificate, a compliance attestation, a case file — and turns publishing it into a provable, multi-party, externally-executed workflow.

The flow

How Evidence publishes a documentConcept

• App ledger: Release, Evidence record.
• Document → Release (stage, then release).
• Release → object.put.
• Release → ipfs.pin.
• object.put → Object storage.
• ipfs.pin → IPFS.
• ipfs.pin → Evidence record (two results).
• Evidence record → kafka.publish (storage ready).
• kafka.publish → Kafka.
• Evidence record → Cardano (anchor).

Document

The exact bytes are staged in object storage, and their IPFS CID is computed, before anything is submitted. The ledger holds the document’s identity, version, and hashes, never the document.

Release

In evidence-v1-gated, a registry entry and a member approval for the exact command come first. evidence.release.v1 then records the version and emits the storage effects in one atomic step. In role-evidence, named business actors approve instead. Tutorial 4 →

Evidence record

Status is derived from authenticated receipts, never asserted. Storage moves from STORAGE_PENDING to STORAGE_READY, or to PARTIAL, STORAGE_FAILED, or EXPIRED. Notification then moves through NOTIFICATION_PENDING to READY.

object.put

Copies the staged bytes to an immutable, versioned destination and never overwrites a different object. The receipt records size, SHA-256, and destination fingerprint.

ipfs.pin

Pins a known CID on a configured Kubo node. A confirmed pin is a point-in-time report, not proof of lasting availability.

kafka.publish

Publishes the canonical evidence.available.v1 event once storage is ready. The receipt records the destination fingerprint, partition, and offset.

Cardano

A script anchor publishes a certified state root. The demo checks the anchor transaction on every member and that its datum commits to the certified root. Cardano anchoring →

Every member records what was authorized and what each connector reported. Connector effects run only after finality, and each result comes back into the ledger once.

• your document
• deterministic, on every member
• connector effect
• external system
• Cardano

The chain records what was authorized. Object storage, IPFS, and Kafka are executed by the effect runtime after the finality gate, and each result comes back on-chain and is incorporated exactly once. Business status is derived from those receipts: STORAGE_PENDING, then STORAGE_READY (or PARTIAL, STORAGE_FAILED, EXPIRED), then NOTIFICATION_PENDING and READY.

What it actually proves

The reference scenario verifies all of the following together:

• the exact archived object bytes, checksum, version, retention identity, and destination fingerprint;
• the exact IPFS CID, the retrieved bytes, and the configured pin state;
• the Kafka destination fingerprint, event bytes, partition, and offset;
• identical committed state across three app ledger members;
• state and effect inclusion proofs bound to the same root;
• threshold-signed finality evidence; and
• the Cardano script-anchor transaction, its state-thread token, and the canonical inline datum.

It also exercises executor failure after an external acknowledgement, fenced failover, reconciliation without duplicate mutation, and restart with retained state. The same scenario runs through Docker Compose and through ordinary host processes.

What it does not prove

That the document’s contents are true. Evidence proves that identified participants approved these exact bytes, in this exact order, and that connectors reported storing them. Domain validity stays with the domain.

It also does not prove durable availability. A pin or an object write is proven at the moment it was reported; long-term retention is an operational property you must monitor separately.

Two profiles

Profile	Approvers	Use when	Selected by
evidence-v1-gated	Validator members	The organizations running nodes are the ones who approve.	The composite machine’s preset; the default in the Tutorial 4 harness
role-evidence	Business actors, by role	The approvers are people — a QA manager, an auditor, a regulator — whose keys are not node keys.	The evidence-ledger recipe; the harness with --machine role

evidence-v1-gated combines registry, approvals, document trail, and approval-coordinated evidence publication under one state root. A compatibility evidence-v1 preset keeps direct evidence commands for existing deployments.

role-evidence adds governed organizations, actor and key revisions, role policies, organization-distinct quorums, and portable actor signatures. This is the distinction between “a node transported this” and “a named person at a named organization authorized this” — see Tutorial 5.

The v1 domain contract

The wire contract is deliberately narrow and strictly canonical CBOR on topic evidence.command.v1:

• canonical SUBMIT, NOTIFY, and REPUBLISH commands;
• immutable head, version-record, effect-reference, and terminal-result codecs;
• canonical evidence.available Kafka event bytes;
• evidence/get request and response contracts that return the exact proven state keys and values;
• domain-separated state keys, effect scopes, and Kafka keys; and
• deterministic status derivation with fail-closed connector receipt checks.

The wire schema version is separate from the monotonically increasing business version. Immutable version records sit behind a small head record, and business status is derived from authenticated connector results rather than asserted.

Modules

Artifact	Repo path	Role
yano-x-evidence-contracts	products/evidence/contracts	No-SPI canonical codecs, usable off-chain.
yano-x-evidence-registry	products/evidence/registry	The deterministic state machine, its provider, and a bundle-owned read-only domain API.
yano-x-evidence-profile	products/evidence/profile	The evidence-v1-gated and role-evidence composite profiles.
yano-x-evidence-client	products/evidence/client	Typed client for commands and proof-carrying reads.

Run it

The evidence-ledger recipe is the configuration-only path. It selects the role-evidence profile, so before the first release the generated project also needs its governed organizations, actors, and role policies; apply the generated role bootstrap plan first.

./yano.sh appchain init --non-interactive \
  --recipe evidence-ledger --network devnet --members 3 --runtime jvm \
  --output evidence-chain

For the complete connector demo — real object storage, a Kubo IPFS node, and Kafka — follow Tutorial 4. It runs the evidence-v1-gated profile by default and needs Docker with Compose v2.

Deployments additionally need the release-matched optional connector bundles installed in plugins/ on every executor node, plus the external services themselves.

Deeper reading

• Tutorial 4 — evidence publication
• Tutorial 5 — domain-role approvals
• Evidence chain demo — the full scripted scenario and its acceptance checks.
• Domain actors and role-aware approvals
• Profile governance runbook