YinkoShield
Brief

Knowledge Center / Evidence architecture / evidence architecture · 2026·03

Append-only hash-linked ledgers — structure and storage semantics

The Local Evidence Ledger is append-only and hash-linked. The shape of the data structure is the security argument: any mutation of any record — edit, delete, reorder, splice — breaks an invariant a verifier can check locally, without coordinating with the device, without trusting the device, without a clock.

[ append-only · hash-linked · local invariant ] seq=001 · prev=00…00 payload · hash=a3f1… seq=002 · prev=a3f1… payload · hash=b71c… seq=003 · prev=b71c… payload (tampered) · hash=?? ← mutation seq=004 · prev=c2d8… ≠ hash(seq=003) payload · hash=4e9a… ← chain break seq=005 · prev=4e9a… payload · hash=ff20… // the invariant the verifier checks append-only no edit, no delete, no reorder. a deletion is detected by gap in seq. hash-linked prev_hash(N+1) == hash(N). a payload edit is detected at the next link. local mutation → global break the verifier never trusts the device; it trusts the structure the device cannot fake. // the data-structure choice is the security argument
Append-only and hash-linked is a structural property. A single mutation in the middle of the ledger breaks an invariant the verifier can check without trusting the device.

1. What the structure is

The Local Evidence Ledger is a per-device append-only sequence of records. Each record carries a payload (the typed signal — overlay, debugger, boot, binding, etc.), a monotonically increasing seq, the boot_id of the current epoch, and a prev_hash field that references the SHA-256 [2] hash of the previous record’s full serialised body. The structure is a tamper-evident hash-chain in the lineage of Crosby & Wallach [4] (and the broader secure-logging line opened by Schneier & Kelsey [3], whose forward-security construction additionally evolves the signing key per record — a property the current YEI-001 chain does not adopt; the per-record signature uses a single device-bound key) — a chain, not a Merkle tree.

Append-only is an interface contract: the ledger surface exposes an append operation only, no random-access write. The structural security argument is the per-record signature plus the hash-chain — without the per-record signatures, an attacker with raw-storage access could rewrite the entire chain consistently from a chosen prefix. The signing key (covered in self-signing-devices) is what makes that rewrite cryptographically infeasible.

The Local Evidence Ledger is per-device. There is no consensus, no peer set, no merge step. The only invariant the structure publishes is forward chain coherence — a property the verifier can check by hashing.

2. What “append-only” rules out

Three classes of mutation are ruled out by the structure itself:

  • Edit — modifying the payload of record N. Detected because hash(N) changes and prev_hash(N+1) no longer matches.
  • Delete — removing record N. Detected because seq(N+1) jumps over a value, and prev_hash(N+1) references a hash that is no longer in the chain.
  • Reorder — moving N to a later position. Detected by both the seq invariant and the prev_hash chain.

A verifier with the device’s public key and the ledger contents needs no further information to check these invariants. No clock. No counter held by the operator. No round-trip to YinkoShield.

What the structure does not detect on its own:

  • Tail truncation. Removing the last K records leaves a syntactically valid prefix; chain coherence checks pass. This failure mode requires a liveness signal — heartbeat cadence, operator-side last-seen (boot_id, seq) pinning, or a submission-window expectation — not chain structure alone.
  • Silent omission. A device that never records an event can produce a valid chain that simply does not contain it. The observer-side mitigation is the same: pinned tip + cadence.

3. Why the device cannot be trusted with a mutable ledger

A read-write ledger on a device an attacker can compromise is a ledger an attacker can rewrite. The runtime, the OS, and the storage layer are all in the attacker’s reachability surface for the threats catalogued in runtime-memory-manipulation and magisk-zygisk-modules. Any property the verifier needs that depends on the device not tampering with stored bytes is a property that does not hold under those threats.

Append-only and hash-linked is the response. The verifier does not trust the device to preserve records honestly; it trusts the structure the device cannot tamper with without detection. A local mutation propagates to a global break the verifier sees.

4. Storage layout on device

The on-device implementation lives in the application’s private storage region. Backing stores vary by platform: a flat-file log on Android (under app-private storage with File-Based Encryption / CE-key-bound), a flat append-only file or INSERT-only SQLite database on iOS (under Data Protection class NSFileProtectionCompleteUntilFirstUserAuthentication or stricter), a flat sequential file on POS Linux. The implementation detail is not load-bearing. What is load-bearing:

  • The append operation is the only mutating operation exposed by the ledger interface.
  • A new record’s prev_hash is computed against the on-disk hash of the previous record, not a cached in-memory copy.
  • The TRP, the signing operation, and the ledger writer share a single critical section serialised by a platform file-locking primitive — flock(2) on Linux, FileChannel.lock() / FileLock on Android (JVM), NSFileCoordinator or POSIX flock(2) on iOS — so concurrent sign() calls cannot fork the chain.

Storage budget on the device is bounded; the ledger has a documented retention window beyond which old records are pruned from the device after they have been delivered to the operator. The pruning is itself recorded in the ledger and signed.

5. What the verifier checks

The 8-step verifier pipeline (covered in detail in Theme 6 under verification-pseudocode) includes a chain-coherence step over whatever ledger window the operator submits. The check is local to the submission — no cross-operator coordination is needed. If the operator submits records N..N+10, the verifier hashes records N..N+9 and confirms each prev_hash(k+1) == hash(k). Any break is attributable to a specific record. The append-only hash-chain is how Execution Evidence Infrastructure (EEI) — the device-identity infrastructure layer for banking and payments — preserves the signal stream without trusting the device’s storage layer.

6. Cross-references

7. External references

[1] IETF. RFC 7515 — JSON Web Signature. datatracker.ietf.org/doc/html/rfc7515. Cited 2026-03-12.

[2] NIST. FIPS 180-4 — Secure Hash Standard (SHS). csrc.nist.gov/pubs/fips/180-4/upd1/final. Cited 2026-03-12.

[3] Schneier, B. & Kelsey, J. Cryptographic Support for Secure Logs on Untrusted Machines. USENIX Security 1998. schneier.com/academic/paperfiles/paper-secure-logs.pdf. Cited 2026-03-12.

[4] Crosby, S. & Wallach, D. Efficient Data Structures for Tamper-Evident Logging. USENIX Security 2009. usenix.org/legacy/event/sec09/tech/full_papers/crosby.pdf. Cited 2026-03-12.