> For the complete documentation index, see [llms.txt](https://golden-shield-digital-treasury-b.gitbook.io/product-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://golden-shield-digital-treasury-b.gitbook.io/product-docs/bondtrust-protocol/gdb-trusted-single-source-oracle-tsso.md). # GDB Trusted Single-Source Oracle (TSSO) ### What TSSO is and why GDB needs it In GDB, each GDO pool (tokenized sovereign-bond sleeve) publishes a **single authoritative NAV** derived from off-chain custodial positions and pricing. Unlike traded crypto where medianizing many feeds works, sovereign-bond NAVs are **single-source** and require (a) **cryptographic authenticity**, (b) **freshness guarantees**, and (c) **regulator-grade auditability**.\ **TSSO** is GDB’s oracle layer that signs, transports, and verifies NAV records with: * **Dual-key policy** (root vs. derivative keys) to separate high-impact updates from routine heartbeats. * **Hash-chained records** for tamper-evident history. * **On-chain verification contracts** enforcing policy and producing an immutable audit trail. * **Batch/Merkle attestations** to compress history and enable light-client proofs. *** ### 2) Architecture at a glance ``` ┌──────────────────────────┐ │ Off-chain NAV Producer │ │ • Custody positions │ │ • Prices/curves/FX │ └─────────────┬───────────┘ │ NAV_t, flows Compute & Sign (TSSO) │ ┌────────────────┴────────────────┐ │ Dual-Key Signer Service │ │ • Root Key (HSM/MPC) │ │ • Derivative Key (online) │ └───────┬───────────────┬────────┘ │ │ Root-signed Derivative-signed records records │ │ ┌───────────┴───────────┐ │ Oracle Relayer Nodes │ (batch, Merkleize, submit) └───────────┬───────────┘ │ ┌────────▼────────┐ │ TSSO Contract │ (on CNC/EVM) │ • Policy checks │ │ • Sig verify │ │ • Hash chain │ │ • Merkle roots │ └────────┬────────┘ │ ┌────────▼────────┐ │ GDO Pools / │ (pull latest NAV; drive coupon accrual, │ BondTrust Logic │ pricing, risk & disclosure) └──────────────────┘ ``` *** ### 3) Cryptographic data model **Record payload** for asset (pool) `a` at sequence `t`: $$ Rt​(a)=⟨a,NAVt​,ts​,seqt​,H(Rt−1​(a)),Πt​⟩ $$ * H(⋅)H(\cdot)H(⋅): collision-resistant hash (e.g., SHA-256). * Πt\Pi\_tΠt​: signature under **Root** or **Derivative** key. **Deviation metric** controls which key may sign: $$ δt​=∣NAVt​−NAVt−1​∣​/max(εden​,NAVt−1​) $$ **Policy**: $$ δt​≤ϵ⇒Derivative signature allowed;δt​>ϵ⇒Root signature required $$ with small εden\varepsilon\_{den}εden​ to avoid divide-by-zero, and ϵ\epsilonϵ a governance-set tolerance (e.g., 10 bps). **Anti-staleness heartbeat**: $$ ts​−ts−1​≤τmax​(else a derivative re-signature is required even if δt​=0) $$ **Batch/Merkle attestations**: Given a day’s records {Rt(i)}i=1n\\{\mathcal{R}\_t^{(i)}\\}\_{i=1}^n{Rt(i)​}i=1n​, publish root $$ MRt​=MerkleRoot({H(Rt(i)​)}) $$ to enable compact proofs of inclusion. *** ### 4) Fixed-income formalism (how NAV is computed off-chain) For a GDO pool composed of sovereign bonds j=1..Nj=1..Nj=1..N, in base currency ccc, day-count DDD, accrual day Δt\Delta tΔt: $$ Accrual t ​ \= j ∑ ​ w j ​ ⋅P j ​ ⋅r (j) ⋅ D Δt ​ $$ $$ Flowst​=j∑​wj​⋅k∈cashflows at t∑​CFj,k​(t) $$ $$ NAVtloc​=NAVt−1loc​+Accrualt​+Flowst​±MTMt​ $$ If multi-currency, translate with FX mid Xc→USD,tX\_{c\to USD,t}Xc→USD,t​: $$ NAVt​=NAVtloc​⋅Xc→USD,t​ $$ (Off-chain we compute MTM via clean price from yield: $$ P(y)=∑ci​/(1+y/m)mi+100/(1+y/m)mT $$ details omitted here but are part of the producer.) **Confidence guardrails:** optionally enforce that ∣MTMt∣|\text{MTM}\_t|∣MTMt​∣ within kσk\sigmakσ of historical NAV volatility to catch anomalous inputs. *** ### 5) On-chain verification logic (Solidity-like) ```solidity // SPDX-License-Identifier: MIT pragma solidity ^0.8.21; library Sig { function verify(bytes32 digest, bytes memory sig, address signer) internal pure returns (bool) { (bytes32 r, bytes32 s, uint8 v) = split(sig); return ecrecover(digest, v, r, s) == signer; } function split(bytes memory sig) private pure returns (bytes32 r, bytes32 s, uint8 v) { require(sig.length == 65, "bad sig"); assembly { r := mload(add(sig, 32)) s := mload(add(sig, 64)) v := byte(0, mload(add(sig, 96))) } } } contract TSSO { using Sig for bytes32; struct Rec { uint256 assetId; uint256 nav; uint64 ts; uint64 seq; bytes32 prevHash; bool rootSigned; } // governance address public rootSigner; address public derivSigner; uint256 public epsilonBps = 10; // 10 bps threshold uint64 public maxHeartbeat = 24 hours; // state per asset mapping(uint256 => Rec) public lastRec; mapping(uint256 => bytes32)public lastHash; event NavAccepted(uint256 assetId, uint256 nav, bool root, uint64 seq, bytes32 recHash); // EIP-712 style domain separator omitted for brevity function submit( Rec calldata r, bytes calldata sig, uint256 prevNav // supplied for delta check ) external { Rec memory p = lastRec[r.assetId]; require(r.seq == p.seq + 1 || p.seq == 0 && r.seq == 1, "bad seq"); require(r.prevHash == lastHash[r.assetId] || p.seq == 0, "bad link"); require(r.ts >= p.ts && r.ts + 5 minutes >= block.timestamp, "stale/clockskew"); // Deviation check (in bps) uint256 base = prevNav > 1 ? prevNav : 1; uint256 deltaBps = (r.nav > prevNav ? (r.nav - prevNav) : (prevNav - r.nav)) * 10000 / base; // Signature route bytes32 digest = keccak256(abi.encode( r.assetId, r.nav, r.ts, r.seq, r.prevHash, r.rootSigned )); if (deltaBps > epsilonBps) { require(r.rootSigned, "root required"); require(digest.verify(sig, rootSigner), "root sig bad"); } else { require(!r.rootSigned, "deriv expected"); require(digest.verify(sig, derivSigner), "deriv sig bad"); } // Heartbeat: derivative path must keep <= maxHeartbeat if (!r.rootSigned && p.seq != 0) { require(r.ts - p.ts <= maxHeartbeat, "heartbeat missed"); } // Commit bytes32 recHash = keccak256(abi.encode(r.assetId, r.nav, r.ts, r.seq, r.prevHash, r.rootSigned)); lastRec[r.assetId] = r; lastHash[r.assetId] = recHash; emit NavAccepted(r.assetId, r.nav, r.rootSigned, r.seq, recHash); } // governance setters omitted (with access control & timelock in production) } ``` **Notes:** * **Delta** vs. `epsilonBps` routes signature policy. * **Hash-link** (`prevHash`) preserves sequential integrity. * **Heartbeat** bounds staleness for derivative path. * Production adds **EIP-712**, **AccessControl**, **Timelock**, and **MPC/HSM signers**. *** ### 6) Oracle node algorithm (off-chain) ```python from dataclasses import dataclass from time import time from math import fabs EPSILON = 0.001 # 10 bps HB_MAX = 24*3600 # seconds @dataclass class Record: asset_id: int nav: float ts: int seq: int prev_hash: bytes root_signed: bool def compute_nav(positions, prices, accruals, fx): # simplified: MTM + accruals in base currency nav_prev = positions.nav_prev accrual = sum(a for a in accruals) mtm = sum(p.mtm for p in prices) return (nav_prev + accrual + mtm) * fx def sign_and_submit(state, chain): # fetch previous on-chain record prev = chain.get_last(state.asset_id) nav = compute_nav(state.positions, state.prices, state.accruals, state.fx) delta = fabs(nav - prev.nav)/max(1.0, prev.nav) rec = Record( asset_id=state.asset_id, nav=nav, ts=int(time()), seq=prev.seq + 1 if prev.seq else 1, prev_hash=prev.rec_hash if prev.seq else b'\x00'*32, root_signed=False ) if delta > EPSILON: rec.root_signed = True sig = hsm_root_sign(rec) else: # heartbeat guard if rec.ts - prev.ts > HB_MAX: # force derivative heartbeat even if delta==0 pass sig = online_deriv_sign(rec) chain.submit(rec, sig, prev.nav) ``` *** ### 7) Batch attestations & light proofs For scalability, relayers may submit a **daily Merkle root** of accepted records; auditors or anyone can verify inclusion with a short proof: $$ VerifyInclusion(H(Rt​),MRd​,π)⇒true $$ GDB exposes an endpoint `latestMerkleRoot(day)` and a view `verifyLeaf(leaf, proof)` to validate record membership without reading the entire history. *** ### 8) Security & operations * **Root key** in HSM or MPC quorum (e.g., 3-of-5), used only for out-of-tolerance updates and key rotation. * **Derivative key** online with rate-limit; rotation supported via governance. * **Alerting** when (a) frequent root usage, (b) heartbeat missed, (c) signature mismatch, (d) abnormal δt\delta\_tδt​ bursts. * **Recovery**: root can re-anchor the chain by signing a **checkpoint record** Ck\mathcal{C}\_kCk​ that binds the canonical previous hash, then resumes derivative updates. * **Regulatory access**: read-only dashboards stream records, deltas, and proofs for supervisors. *** ### 9) What TSSO enables in GDB (practical effects) * **Regulator-grade NAV provenance**: every published NAV used by GDO pools has a cryptographic lineage; disputes can be resolved by replaying signatures and hashes. * **Automated freshness**: derivative heartbeats ensure no stale NAV drives coupon accrual, pricing, or risk. * **Blast-radius control**: large NAV changes require **root approval**, protecting investors from compromised online keys. * **Composability**: on-chain contracts (BondTrust) can trust-minimize against TSSO without bespoke integrations; Merkle roots let light clients/auditors verify with small proofs. * **Performance**: batch attestations keep gas costs predictable while preserving per-record proofs when needed. *** ### 10) (Optional) tying NAV to coupons & disclosure Given daily accrual basis DDD and pool coupon r, $$ Coupont​=NAVt−1​⋅Dr​⋅Δt $$ GDO pool contracts retrieve `NAV_{t-1}`, apply accrual/cash-flow schedules, and expose `view` functions for **real-time APY, YTM, and P\&L**; human-readable disclosures can be generated from the same immutable NAV chain. *** #### TL;DR TSSO gives GDB a **provable, fresh, and policy-aware NAV layer** for sovereign-bond tokenization. The dual-key + hash-chain + Merkle design, coupled with on-chain enforcement and off-chain HSM/MPC practices, delivers a **high-assurance oracle** that regulators can audit and engineers can integrate—exactly what single-source fixed-income data needs.