agorix
AirdropMarketsCollectionsLeaderboardActivity
Agorix · Decentralized Marketplace
Independent · Resilient · Community-Run

A cross-chain marketplace, run by the community.

Discover, list, and trade across Bitcoin, Ethereum, and Solana on an open, community-run network.

Marketplace
CollectionsMarketsLeaderboardActivity
Network
GovernanceExplorerAirdropDocs
Account
ProfileSettings
Legal
Terms of ServicePrivacy PolicyYour Privacy Choices
agorix.io — Lasting Access
CID: 0xA60R1X · v0.1
AirdropMarketsCollections
D
Protocol Docs
Protocol TruthWitness Selection & AttestationEvent System & GossipWire ProtocolReward Pool and Epochs
Docs/Protocol/Protocol Truth
Protocol

Protocol Truth

The deterministic validation engine. How every node independently computes identical results from the same inputs with zero coordination.

#Protocol Truth

Protocol Truth is the foundational guarantee of the network. Every node independently computes identical results from the same inputs. There is no coordinator, no leader election, no voting on what is "true." Truth is the deterministic output of pure computation over shared state.

This property eliminates an entire class of consensus failures. Nodes do not need to agree on what happened -- they each derive the same answer from the same evidence, independently.

#The Validation Engine: validateSaleTx()

The validateSaleTx() function is the core of the protocol. It accepts a transaction and its full context, then returns a deterministic verdict. Every node that runs this function over the same inputs will produce the same output, every time, without exception.

typescript
interface ValidationInput {
  tx: TransactionData;
  quote: SignedQuote;
  listing: ListingRecord;
  witnesses: WitnessSet;
  blockContext: BlockContext;
  protocolConfig: RuntimeConfig;
}

type Verdict = "VALID" | "INVALID";

const verdict: Verdict = validateSaleTx(input);

#Validation Checks (in order)

The validator runs these checks sequentially. The first failure short-circuits and returns INVALID with a reason code. Order matters -- cheaper checks run first.

  • Protocol Version Match -- The event must declare protocol version "mvp-1". Any mismatch is an immediate rejection. This prevents cross-version contamination during upgrades.
  • Validator Version Match -- The validator version embedded in the transaction must match the version running on the evaluating node. Nodes that have not upgraded will correctly reject events produced by newer validators, preventing split-brain during rolling deploys.
  • Quote Signature Verification -- The SignedQuote attached to the transaction must carry a valid Ed25519 signature from the serving node. The signature covers the canonical JSON of the quote payload. Invalid or missing signatures are rejected outright.
  • Quote Expiration Check -- The quote has a configurable TTL (default: 15 minutes). If the current block timestamp exceeds quote.issuedAt + ttl, the quote is expired and the transaction is invalid. This prevents replay attacks with stale quotes.
  • Release Hash Consensus -- The serving node's release hash (a SHA-256 digest of the running binary) must match the network-consensus release hash stored in the governance config. Nodes running unauthorized or modified code cannot produce valid quotes.
  • Listing Status Validation -- The referenced listing must be in OPEN status and must not have passed its expiration timestamp. Delisted, sold, or expired listings cannot be purchased.
  • Asset Outpoint Verification -- For BTC transactions, the asset outpoint (txid:vout) referenced in the listing must appear in the transaction inputs. This proves the seller is actually spending the correct UTXO. For EVM/SOL chains, equivalent ownership proofs are checked.
  • Witness Set Verification -- The witness set attached to the transaction must exactly match the deterministic selection for this session. Witnesses are selected via SHA256(seed + pubkey) ranking (see Witness Selection). Any deviation in the witness set invalidates the transaction.
  • Witness Count Minimum -- The number of attesting witnesses must meet or exceed the supermajority threshold: ceil(2/3 * witnessCount). A transaction with too few attestations cannot finalize.
  • Fee Distribution Verification -- The transaction outputs must match the governance fee split with basis-point precision. Every satoshi/lamport/wei must land in the correct address. The validator recomputes the split independently and compares.
  • Seller Payout Verification -- After fees, the seller must receive exactly the correct amount. The validator independently computes salePrice - totalFees and verifies the output matches.

#Fee Computation

Fees are computed with basis-point precision (1 basis point = 0.01%). No floating-point arithmetic is used. All fee math uses integer basis-point multiplication followed by deterministic rounding.

text
totalFee = (salePrice * feeBps) / 10000
foundationShare = (totalFee * foundationBps) / 10000
networkShare = totalFee - foundationShare
sellerPayout = salePrice - totalFee
ParameterDefaultGovernance Range
Marketplace fee200 bps (2.00%)50 -- 500 bps
Foundation share5000 bps (50% of fee)3000 -- 7000 bps
Network share (reward pool)5000 bps (50% of fee)3000 -- 7000 bps

The foundation and network shares are complementary -- they must sum to 10000 bps (100% of the fee). Governance votes can shift the split within the allowed range.

#Protocol Version

The current protocol version is "mvp-1". This string is embedded in every protocol event and every validation context. Version mismatches cause immediate rejection.

Validator versioning is separate from protocol versioning. The validator version tracks the implementation revision. Two nodes can run different validator versions and still agree on protocol truth, as long as both correctly implement the same protocol version.

#Canonical JSON and Deterministic Hashing

All protocol data that gets hashed or signed must first be serialized to canonical JSON. The canonical form is defined in services/protocol/src/hash.ts:

  • Keys are sorted lexicographically at every nesting level
  • No extraneous whitespace (no pretty-printing)
  • Numbers use their minimal JSON representation
  • No undefined values (stripped before serialization)

This produces a deterministic byte string for any given object, regardless of insertion order or runtime quirks.

Hashing uses SHA-256 from the @noble/hashes library (a zero-dependency, audited implementation). The hash is computed over the UTF-8 bytes of the canonical JSON string and output as a lowercase hex digest.

typescript
import type { CanonicalJsonValue } from "@agorix/protocol/hash";
import { sha256 } from "@noble/hashes/sha256";
import { bytesToHex } from "@noble/hashes/utils";

function canonicalHash(obj: CanonicalJsonValue): string {
  const json = canonicalStringify(obj);
  return bytesToHex(sha256(new TextEncoder().encode(json)));
}

#LLM Advisory Layer

The protocol includes an optional LLM advisory layer that generates risk notes for listings and transactions. These notes are stored in the llmRiskNotes table and surfaced in the UI as informational warnings.

Critical rule: LLM risk notes are NON-CONSENSUS. They never affect validation verdicts. They are never included in hashed payloads. They are never part of attestation data. Only deterministic code decides protocol truth.

Examples of advisory notes:

  • "This collection has unusual transfer patterns"
  • "Price is significantly below floor"
  • "Seller has no transaction history"

Nodes may run different LLM models or disable the advisory layer entirely. This has zero effect on protocol correctness.

#Rust Node-Core Parity

The critical validation paths run in both TypeScript and a Rust microservice (node-core). The Rust implementation is a line-by-line port of the TypeScript protocol logic:

text
POST /v1/protocol/truth/evaluate   -- Full validateSaleTx()
POST /v1/protocol/validate         -- Individual check execution
POST /v1/witness/select            -- Deterministic witness selection
POST /v1/fees/split                -- Fee computation

Both runtimes must produce identical results for identical inputs. The integration test suite runs every validation scenario against both runtimes and diffs the outputs. Any divergence is a release-blocking bug.

The Rust runtime is used for performance-critical paths (batch validation, replay). The TypeScript runtime is the reference implementation. When in doubt, TypeScript is authoritative.

PreviousArchitectureNext Witness Selection & Attestation

On this page

  • Protocol Truth
  • The Validation Engine: validateSaleTx()
  • Validation Checks (in order)
  • Fee Computation
  • Protocol Version
  • Canonical JSON and Deterministic Hashing
  • LLM Advisory Layer
  • Rust Node-Core Parity