Technical reference

Architecture

Four layers, each with a single job. The chain never holds user content — only a 32-byte hash of it — so the database stays authoritative for the work while the ledger stays authoritative for the proof.

Auth is Supabase Auth reached through Stellar wallet sign-in (SEP-10): the wallet signs a self-verifying challenge transaction and the server mints a session. The deployment’s network is fixed by NEXT_PUBLIC_STELLAR_NETWORK (mainnet or, by default, testnet) and the contract it anchors against by NEXT_PUBLIC_MILESTONE_PROOF_CONTRACT_ID.

On-chain contract

milestone_proofis an owner-gated registry. A project owner registers a project reference, a submitter attaches a proof hash for a milestone, and the project owner approves or rejects it. Only the 32-byte proof hash lives on chain; the artifact stays off chain. Identifiers are the app’s own UUIDs, passed as Soroban String and capped at 64 characters.

Proposed ──submit──▶ Submitted ──approve──▶ Approved   (terminal)
                        │
                        └────reject───▶ Rejected ──submit──▶ Submitted …

Data model

The off-chain layer is plain-SQL migrations. Access is derived entirely from project_members: every table has Row Level Security enabled and no permissive default, so with RLS on and no matching policy the answer is “no rows”.

Anchoring flow

Signing happens in the browser, so a single Server Action cannot own the whole transaction. It splits in three, and anchoring is deliberately additive — it never writes milestones.status. Moving a milestone through the approval flow in the app and proving it on chain are separate acts, and the two are allowed to disagree; the UI shows both.

1. 1 · Prepare (server)

   prepare* authorizes the caller, computes the SHA-256 proof hash over a canonical, length-prefixed encoding of the milestone and its linked proofs (server-only, encoding pinned to utf8), then assembles and simulates the contract call and hands back base64 XDR plus the simulated fee. Simulation surfaces a contract error — an already-approved milestone, an unregistered project — before the user is asked to sign, costing nothing.

2. 2 · Sign (browser)

   The wallet kit signs that XDR string and nothing else. The same signTransaction call every supported wallet already implements.

3. 3 · Submit (server)

   submit* treats the signed XDR as untrusted input: assertInvocation re-derives what the transaction is allowed to be and refuses anything else — exactly one operation, an invokeContract host function, the configured contract id, and the expected function name. Only then does it submit through Soroban RPC and poll getTransaction until success (a timeout or TRY_AGAIN_LATER is an error, not an optimistic success). It reads version back from the contract by simulation, then inserts a milestone_anchors row whose signer_address comes from the verified transaction, never from a profile field.

The client half of this lives in web/src/lib/chain/client.ts and web/src/lib/chain/actions.ts; the contract calls go through a TypeScript client generated by stellar contract bindings typescript from the deployed contract, never hand-written.

API routes

A handful of Route Handlers under web/src/app/api. The two Horizon readers sit behind the auth gate so neither can be used as an open Horizon proxy, and both use a plain fetch — stellar.ts stays dependency-free and does the arithmetic.

Public proof pages

A milestone’s proof, reachable by someone with no account, lives at /p/[slug]/[milestone] — outside the (app)route group, so no session is required. It is the product’s claim made checkable by the person the claim is for: a title, a status, the anchor history and the decisions with their reasons, each with a link to the ledger, so a reader can verify the hashes on stellar.expert without trusting the page.

The data comes only from the public_milestone_proof(p_slug, p_milestone_id) function. Every table keeps its RLS unchanged and anon holds no membership row, so a direct read returns nothing; the function is a SECURITY DEFINER window that returns a fixed, hand-listed shape — project name, milestone title, status, network, contract id, owner address, the anchor list and the review list, and nothing else. It returns null unless the project’s owner turned on public_proofs. Not-published, no-such-milestone and wrong-project all return null and are deliberately indistinguishable: telling them apart would confirm that private work exists.

A milestone linked to a doqtri heading also carries docSource: the doc id, the heading’s node id and label (the milestone title), the doc version the link was written against, and the project id once the project is registered on chain (where it is public already, and never shown) — never the doc’s title, which is doqtri’s private note title, and never the stored doc URL. The page shows it as a “Planned in doqtri” block, and treats it as a pointer, not as evidence: anyone who may write the link could have written it. It reads this deployment’s DoqtriRegistry (DOQTRI_REGISTRY_CONTRACT_ID on DOQTRI_REGISTRY_NETWORK) with a read-only Soroban simulation, cached for 30 seconds, and makes two checks. The node id, its status and version appear only when get_node has tool “qdit” and an artifact_refnaming this project and milestone; otherwise the block says only that the milestone is linked to the doc and not signed in doqtri yet. The doc check, labelled “doc anchored at version ≥ V”, holds when get_documentis at or past the linked version (with a “plan changed since” note when past it). The block says verified only when both hold, naming the on-chain version; anything else is not verified with its reason, or an explicit “could not check” when a read failed or no registry is configured. The heading’s own record counts as Verified only when get_milestone_statusalso shows the milestone Approved at the version it names. “Open in doqtri” goes to DOQTRI_ORIGIN/d/<doc id>, built by qdit, and is absent when DOQTRI_ORIGIN is unset. An unlinked milestone has no docSource key and its page is unchanged.

Above that block, a linked milestone shows its proof chain as an ordered list of four steps: plan version (both checks above holding), submitted and approved (the milestone’s current record from get_milestone_statuson the project’s own contract, read when the page loads and cached the same way), and verified in doqtri (the heading’s record, Verified for the version approved on chain). Each step says in words whether it is done, pending, does not match, or could not be checked, with the ledger time or the time qdit recorded it. Submitted and approved link the transaction from the anchor history at the record’s version; with none, they link the contract and say that Stellar RPC keeps events for about 7 days, so an older transaction cannot be looked up there. Plan version and verified link the DoqtriRegistrycontract, because qdit does not keep doqtri’s transactions.

Verify it yourself

The WASM hash is the point: anyone can rebuild this source and check the bytes deployed match the code. If it does not, the deployed bytes are not this code.

# Reproduce the deployed contract
cd contracts
stellar contract build          # → target/wasm32v1-none/release/milestone_proof.wasm

# Compare against the deployed hash on both networks:
#   d4bbe221cbe9837cf277448d0fe3aa99cf0dd9213a98db15b671a34dadf2a8b4

# Inspect the live interface directly
stellar contract info interface --id milestone_proof --network testnet

Deployment is not upgradable, by choice — no admin address, no upgrade entry point. A bug means deploying a new contract id and migrating the per-project chain_contract_idthe app stores, since a project’s ownership stays behind in the old contract rather than being upgraded in place. Individual anchors are verifiable independently of qdit: every milestone_anchors row names a transaction hash you can open on the explorer, and the ledger — not the database — is authoritative.

Prefer the app? Open the proof registry or the dashboard.