From Blockchain Hashes to Evidence Graphs: What We Learned Building Verifiable Knowledge
When we started experimenting with verifiable knowledge in MyZubster, the first implementation looked simple:
- Take a Knowledge Card.
- Hash something that identifies it.
- Store the hash on Ethereum.
- Use the blockchain record as proof.
The implementation worked.
The model was wrong.
Not because the cryptography failed, but because we were asking a hash to represent more meaning than it actually contained.
That mistake eventually led us to build Evidence Graph v1, a small architecture for separating claims, evidence, canonical representations, cryptographic digests, and blockchain attestations.
This is the engineering path that got us there.
The real-world test case
We didn't want to design the system around purely synthetic examples.
Our test case came from an actual software contribution associated with a MyZubster Knowledge Card.
The contributor worked on a local stack involving Docker Compose, Ollama, Qdrant, an API, and Open WebUI.
During testing, a problem was identified in the document ingestion process. The chunking logic was modified to better respect paragraph and line boundaries while preserving overlap and avoiding loops.
After re-ingestion, the resulting knowledge base contained:
46 knowledge chunks loaded into Qdrant
1 empty document skipped
The contribution gave us several interesting objects:
person
software contribution
Knowledge Card
Git commit
test results
repository
The next question was how to make the resulting evidence cryptographically verifiable.
Attempt 1: Hash the URL
Our first Ethereum Sepolia experiment used a small smart contract called MyZubsterProof.
The contract stored a bytes32 digest.
For the first experiment, we calculated SHA-256 over the URL of the Knowledge Card.
Cryptographically, this worked.
But consider what was actually being committed:
Knowledge Card URL
↓
SHA-256
↓
Ethereum Sepolia
The problem is subtle but important.
The URL identifies a resource.
It doesn't necessarily identify the exact content of that resource.
The content behind the URL could change without changing the URL itself.
Therefore the blockchain record established something closer to:
This URL string corresponds to this digest.
It did not establish:
These exact Knowledge Card contents correspond to this digest.
That distinction motivated a second implementation.
Attempt 2: Canonical content
For Proof v2 we created a canonical JSON representation of the Knowledge Card.
The payload was committed to Git as:
proofs/knowledge-card-6abaaefb3a7460c4574a45fd-v1.json
The exact file contains:
3168 bytes
We calculated SHA-256 over those exact bytes.
The result was:
6097e05866bafceec24663d2638cb1dae5742ac78284abbfd45cc9c3b0bfb845
That digest was supplied to a new immutable MyZubsterProof contract deployed on Ethereum Sepolia.
The deployed contract is:
0x21787249Df054132093FcF09bB914C0CCC539390
on:
Ethereum Sepolia
chainId 11155111
Calling:
knowledgeHash()
returns:
0x6097e05866bafceec24663d2638cb1dae5742ac78284abbfd45cc9c3b0bfb845
Now the proof had much clearer semantics.
Reproducing the hash
A cryptographic proof isn't particularly useful if only the original application can verify it.
So we tested the process independently.
We retrieved the exact payload from its Git commit and calculated SHA-256 locally.
For example:
sha256sum proofs/knowledge-card-6abaaefb3a7460c4574a45fd-v1.json
The result:
6097e05866bafceec24663d2638cb1dae5742ac78284abbfd45cc9c3b0bfb845
During our final verification we compared expected and calculated values:
expected:
6097e05866bafceec24663d2638cb1dae5742ac78284abbfd45cc9c3b0bfb845
actual:
6097e05866bafceec24663d2638cb1dae5742ac78284abbfd45cc9c3b0bfb845
RESULT: MATCH
So we now had:
Git commit
↓
exact 3168-byte payload
↓
SHA-256
↓
6097e058...
↓
Ethereum Sepolia
↓
knowledgeHash()
↓
6097e058...
This is reproducible without trusting the MyZubster application.
But it still doesn't prove that the claims inside the JSON are true.
That became the next engineering problem.
Cryptographic integrity isn't semantic verification
Imagine hashing this statement:
Alice built a distributed database.
Then storing the resulting digest on Ethereum.
What has been demonstrated?
We may be able to establish that:
these bytes
↓ SHA-256
this digest
↓
this blockchain record
But Ethereum cannot conclude:
Alice actually built the database.
The blockchain verifies its own state.
It doesn't automatically verify the external-world meaning of the data being committed.
That distinction led us to separate several concepts that we had initially treated too closely:
claim
evidence
canonical representation
cryptographic integrity
attestation
verification
And that became the basis for Evidence Graph v1.
Building Evidence Graph v1
Instead of treating “proof” as one object, we represent the evidence system as typed nodes and typed relationships.
A simplified graph looks like:
Person
│
│ CLAIMS
▼
Claim
│
│ DESCRIBED_BY
▼
Knowledge Card
│
│ SUPPORTED_BY
▼
Evidence
│
│ CANONICALIZED_AS
▼
Canonical Payload
│
│ HASHED_AS
▼
Digest
│
│ ATTESTED_BY
▼
Attestation
The key design decision is that these relationships have deliberately narrow meanings.
CLAIMS
Person
│
│ CLAIMS
▼
Claim
This tells us who is associated with a claim.
It does not tell us whether the claim has been independently verified.
For our experiment, a simplified claim was:
N4K48
↓ CLAIMS
"Contributed improvements to a knowledge ingestion workflow"
DESCRIBED_BY
The claim can be associated with a Knowledge Card:
Claim
│
│ DESCRIBED_BY
▼
Knowledge Card
Again, this isn't verification.
It tells us where the claim is represented.
SUPPORTED_BY
The Knowledge Card or claim can reference evidence:
Knowledge Card
│
│ SUPPORTED_BY
▼
Evidence
An evidence reference means:
This artifact is presented as supporting material.
It doesn't automatically mean:
This artifact proves the claim.
CANONICALIZED_AS
Eventually we reach the cryptographic layer.
Evidence
│
│ CANONICALIZED_AS
▼
Canonical Payload
This explicitly separates the semantic evidence object from the deterministic representation used for hashing.
HASHED_AS
The canonical representation produces a digest:
Canonical Payload
│
│ HASHED_AS
▼
SHA-256 Digest
This is a reproducible cryptographic relationship.
Given the same bytes, another verifier should calculate the same digest.
ATTESTED_BY
Finally:
Digest
│
│ ATTESTED_BY
▼
Blockchain Attestation
This relation has intentionally limited semantics.
It means the digest has a confirmed blockchain anchor.
It does not mean:
PROVES_TRUTH
In fact, PROVES_TRUTH is deliberately rejected by Evidence Graph v1.
Making invalid semantics harder to express
Documentation alone isn't enough for a system like this.
Some semantic constraints are enforced by the implementation.
For example, an anchor with status:
NOT_REQUESTED
NOT_CONFIGURED
SUBMITTED
FAILED
must not produce an ATTESTED_BY edge.
Only a confirmed anchor can do that.
We added tests specifically for this behavior.
Similarly, an unknown semantic relationship is rejected rather than silently accepted.
That includes:
PROVES_TRUTH
This is useful because it moves part of the trust model into code.
Deterministic graph construction
Evidence Graph itself also needs an integrity mechanism.
The graph builder therefore produces a:
graphHash
from a stable representation of the graph.
Given the same inputs:
same nodes
+
same edges
+
same metadata
we expect:
same graphHash
The test suite builds the graph twice and checks exactly that:
expect(second.graphHash).toBe(first.graphHash);
This gives us deterministic graph projection.
Evidence hash and graph hash aren't the same thing
Our real N4K48 Evidence Graph experiment produced this evidence hash:
51483fbac73ec183d2f882428fd2ec823ec88eaa82a07b3a9cd2fe3324ec618b
The graph itself produced:
7dffe770d139da4a0beaf27d0b2d7e72a03bf26c5cd2180c93e1741fa8d3625e
These values are intentionally different.
The first protects the canonical Knowledge Evidence payload.
The second protects the graph representation.
In other words:
evidenceHash
↓
integrity of evidence payload
graphHash
↓
integrity of graph representation
Conflating those two would remove useful information from the architecture.
An unexpected result: zero attestations
When we generated the Evidence Graph for the real Knowledge Card, the graph contained:
7 nodes
7 edges
0 attestation nodes
At first glance, that might look strange.
We had already created an Ethereum Proof v2.
Why wasn't it included?
Because the hashes were different.
The Evidence Graph evidence object produced:
51483fbac73ec183d2f882428fd2ec823ec88eaa82a07b3a9cd2fe3324ec618b
The earlier canonical Knowledge Card Proof v2 produced:
6097e05866bafceec24663d2638cb1dae5742ac78284abbfd45cc9c3b0bfb845
They represent different canonical objects.
Pretending that the Ethereum contract attested 51483f... would have been incorrect.
So the system produced:
attestation nodes: 0
That wasn't a missing feature.
It was the correct result.
Two valid cryptographic chains
We therefore currently have two related but separate structures.
The new Evidence Graph:
Person
↓
Claim
↓
Knowledge Card
↓
Evidence
↓
Canonical Evidence Payload
↓
51483f...
And the earlier Proof v2:
Knowledge Card
↓
canonical Knowledge Card payload
↓
6097e0...
↓
Ethereum Sepolia
The Knowledge Card connects the concepts.
The two digests aren't interchangeable.
This turned out to be one of the most useful results of the experiment.
The API is intentionally read-only
Evidence Graph v1 also exposes:
POST /api/knowledge-evidence/graph
The endpoint projects existing evidence into a graph.
It deliberately doesn't:
persist the graph
publish the evidence
send blockchain transactions
declare independent verification
A successful response explicitly contains:
{
"success": true,
"persisted": false,
"publication_performed": false,
"independently_verified": false
}
This keeps projection separate from side effects.
Generating a graph should not accidentally publish information or trigger a blockchain transaction.
Knowledge Cards are composed outside the evidence hash
We faced another design choice.
Should adding a Knowledge Card modify the original evidence payload?
We decided it shouldn't.
Instead, the Knowledge Card is composed at the graph layer:
Claim
│
├──── SUPPORTED_BY ──── Evidence
│ ▲
│ │
└──── DESCRIBED_BY ── Knowledge Card
│
└── SUPPORTED_BY
The original evidence payload and its hash remain unchanged.
This lets us enrich the graph without silently rewriting the cryptographic history of the evidence object.
Testing the semantics
At the end of this iteration, our focused regression gate contained:
3 test suites
18 tests
18 passed
The tests include cases for:
deterministic graph generation
invalid graph edges
unknown semantic relations
Knowledge Evidence projection
canonical payload construction
digest generation
confirmed blockchain anchors
unconfirmed anchors
tampered payloads
Knowledge Card composition
incomplete Knowledge Card references
full Knowledge Card → integrity-chain composition
One test explicitly attempts to use an unknown relation such as:
PROVES_TRUTH
and expects the graph builder to reject it.
Another verifies that a SUBMITTED blockchain transaction isn't treated as a confirmed attestation.
Another deliberately tampers with the canonical payload and expects integrity-chain construction to fail.
These aren't only unit tests.
They encode part of the evidence model.
What Proof v2 actually proves
After all this work, we ended up with a much narrower definition of our blockchain proof.
Proof v2 establishes:
The SHA-256 digest recorded by the Sepolia contract equals the SHA-256 digest of the exact canonical Knowledge Card payload committed to the referenced Git repository.
It does not independently establish:
the truth of every statement
ownership of every referenced artifact
professional competence
employment
authorship
the value of the contribution
Those questions require other forms of evidence and verification.
This distinction isn't a weakness of the blockchain proof.
It's what makes the proof interpretable.
Why a graph instead of a certificate?
A single credential is convenient when the thing being represented is simple.
Real software evidence often isn't.
Imagine a developer claim supported by:
Git commits
test results
code review
deployment records
Knowledge Cards
repository artifacts
external attestations
Several claims may share artifacts.
One artifact may support several claims.
One payload may have several attestations.
An attestation may come from Ethereum today and another system tomorrow.
Eventually the structure could look more like:
Git commit
│
▼
Person ── Claim ── Knowledge Card ── Evidence
│ │
│ ▼
│ Canonical Payload
│ │
│ ▼
│ Digest
│ / \
│ / \
▼ ▼ ▼
Artifact EAS Ethereum
Evidence Graph v1 doesn't implement all of that.
It establishes the vocabulary needed to get there.
Engineering lesson #1: hash the thing you mean
Our Proof v1 mistake was simple:
hash(resource identifier)
when what we really wanted was:
hash(canonical resource contents)
Those operations answer different questions.
If your proof concerns content, canonicalize and hash the content.
Engineering lesson #2: define edge semantics
A graph with vague relationships doesn't solve the problem.
Consider:
Person → Proof
What does that mean?
Authored?
Submitted?
Owns?
Was mentioned by?
Was independently verified by?
Evidence Graph became useful only when relationships became explicit:
CLAIMS
DESCRIBED_BY
SUPPORTED_BY
CANONICALIZED_AS
HASHED_AS
ATTESTED_BY
Engineering lesson #3: absence is meaningful
We initially could have attached the existing Ethereum proof to the new Evidence Graph because both related to the same Knowledge Card.
That would have produced a nicer-looking demo.
It would also have been wrong.
The digest didn't match the Evidence Graph evidence payload.
So:
0 attestation nodes
was more informative than a fabricated connection.
Failing closed matters in evidence systems.
Engineering lesson #4: blockchain should be one layer
The blockchain component became easier to reason about once we stopped treating it as the entire verification system.
The architecture now looks more like:
semantic layer
↓
evidence layer
↓
canonicalization layer
↓
cryptographic layer
↓
attestation layer
Ethereum occupies the last layer.
That's a much smaller responsibility.
And that's useful.
What's next
There are several possible directions from here:
persistent graph storage
interactive Evidence Graph visualization
Ethereum Attestation Service
W3C Verifiable Credentials
Open Badges
multiple attestations
independent evidence verification
richer provenance
We're deliberately not implementing all of them at once.
Evidence Graph v1 is intended to freeze the basic semantics before expanding the protocol.
Conclusion
We started by asking:
How can we put evidence of someone's work on a blockchain?
After building two proofs and an Evidence Graph, we'd phrase the problem differently:
How can we make the relationships between claims, evidence, cryptographic integrity, and attestations explicit and independently inspectable?
The blockchain transaction was the easy part.
The harder part was deciding what it was allowed to mean.
Our current model is:
Claim
↓
Evidence
↓
Canonical representation
↓
Cryptographic digest
↓
Attestation
with verification status kept explicit rather than inferred.
That's the main lesson from the experiment:
Integrity can be cryptographically demonstrated. Truth still requires evidence and interpretation.
A good verification architecture should know the difference.
Source code and reproducible artifacts
The Evidence Graph v1 implementation is available in:
MyZubster Evidence Graph v1 — PR #17
The exact canonical Knowledge Card payload used for Proof v2 was committed here:
Proof v2 canonical payload commit
Proof v2 documentation:
Sepolia Proof v2 documentation
The chunking contribution used in the experiment:
Knowledge ingestion improvement commit
The Proof v2 contract can be inspected on Ethereum Sepolia:
MyZubsterProof contract on Sepolia Etherscan
Deployment transaction:
Proof v2 deployment transaction
Per Coder Legion userei come titolo:
From Blockchain Hashes to Evidence Graphs: What We Learned Building Verifiable Knowledge
e come sottotitolo:
An engineering case study on canonical payloads, deterministic graphs, SHA-256, Ethereum attestations, and why integrity is not the same as truth.