From Blockchain Hashes to Evidence Graphs: What We Learned Building Verifiable Knowledge

Leader ●2 ●25 ●155
calendar_today • schedule10 min read

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:

  1. Take a Knowledge Card.
  2. Hash something that identifies it.
  3. Store the hash on Ethereum.
  4. 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.

Want more #opensource & #blockchain deep dives?

Join 5,955+ developers sharing real benchmarks, code breakdowns, and projects. Free forever.

2 Comments

2 votes
1

More Posts

AAIF Hits 10 Projects. Its CTO on What to Adopt Now and the Security Gaps Left Open

Tom Smithverified - Oct 23

ERC20 Edge Cases Every Smart Contract Engineer Should Know

BinnaDev - Jun 24

The Sovereign Vault — A Comprehensive Guide to Protocol-Driven AI

Ken W. Algerverified - Jun 4

Understanding Blockchain: A Developer's Guide to Blocks, Consensus, and Smart Contracts

Soumabha Mahapatra - Jul 12

What Security Teams Want From AI Agents Before They Let Them Act Alone

Tom Smithverified - Nov 18
chevron_left
4.4k Points • 182 Badges
Rimini
112Posts
17Comments
33Connections

Related Jobs

Commenters (This Week)

3 comments
1 comment

Contribute meaningful comments to climb the leaderboard and earn badges!