GuidesTrustlessness
Trustlessness Spec
Normative checklist for trust-minimized verification on Terp Network — build, hash, compare, decide
import { Callout } from 'fumadocs-ui/components/callout';
Trustlessness Spec
This page is the short normative checklist for verification work on Terp Network. Philosophy and manifesto: Trustlessness concept. Step-by-step procedures: Trustlessness guides.
Trust model
Mandate
No user should be required to trust a third party to verify the integrity of the network, its software, or its state.
Trust assumptions (what we still need)
| Assumption | Why it remains | Mitigation |
|---|---|---|
| Honest majority / BFT of validator set | Consensus safety | Run software you verified; diversify operators |
| Correct light client / IBC client | Cross-chain safety | Verify client state; multiple sources |
| Correct local machine | Build environment integrity | Reproducible Docker builds; checksum installers |
| Availability of source | Reproducibility | Mirror critical repos; pin tags/commits |
Trust minimization requirements
For any artifact labeled “official” or used with real value:
- Source available at a pinned commit/tag
- Build instructions reproducible by a third party
- Hash published independently of a single UI
- User can refuse the artifact if hashes diverge
Verification workflow (normative)
Every trustlessness guide follows the same four steps:
1. Build from source (or obtain a pinned artifact)
2. Compute hash (SHA-256 or documented algorithm)
3. Compare against on-chain or independently published reference
4. Decide — match → use; mismatch → stop and investigate| Step | Pass criterion |
|---|---|
| Build | Clean checkout of the claimed tag; documented toolchain/optimizer |
| Hash | Deterministic digest over the exact bytes users will run |
| Compare | Same algorithm and encoding (hex/base64) as the reference |
| Decide | Explicit human or CI gate — no silent continue on mismatch |
Artifact verification matrix
| Artifact | Reference | Procedure |
|---|---|---|
terpd / installer scripts | Published checksums | Verify, Terp Installer |
| Release binaries | GitHub release + checksums | Integrity |
| CosmWasm code | On-chain checksum for code_id | Compile & verify code ID |
| IBC metadata export | Independent checksums of JSON dumps | IBC Info checksums |
| Static websites | Content hashes / source comparison | Verify website |
| ZK circuits | Reproducible build + key verification | Verify circuit |
| Genesis / chain config | Official + secondary mirrors | Genesis, Public endpoints |
Common mismatches
| Cause | What you see | What to do |
|---|---|---|
| Wrong optimizer / compiler version | WASM or binary hash differs | Pin versions from release notes |
| Platform differences | Native binary hash differs across OS/arch | Compare per-arch checksums; prefer Docker reproducible builds |
| Local modifications | Dirty git tree | git status; rebuild from clean tag |
| Wrong tag / fork | Hash matches neither release nor chain | Confirm repo URL and tag |
| Encoding mismatch | “Different” hashes that are the same bytes | Normalize hex case / base64 |
Requirements for guides and tooling
Docs and automation that claim to be production-ready SHOULD:
- Document the exact command that produces the hash
- Link the reference (on-chain query or published file)
- Include a failure path (what if mismatch)
- Prefer public RPC examples users can re-point to their own node
Apps and deployment pipelines SHOULD:
- Fail CI on hash mismatch
- Record tag, commit, and digest next to deploys
- Avoid “trust the CDN” as the only control