Skip to content

PROJECT.md

Latest commit

 

History

History
209 lines (174 loc) · 6.22 KB

PROJECT.md

File metadata and controls

209 lines (174 loc) · 6.22 KB
Raw

Certael — Project Source of Truth

Product

Certael is asset-integrity infrastructure for tokenized real-world assets (RWAs).

Working tagline: Know what backs it.

Certael exists because token ownership onchain does not by itself prove that the underlying real-world asset still exists, remains properly collateralized, is legally enforceable, is honestly valued, or can be exited when needed.

Core Product Systems

  1. Certael Passport — canonical asset identity, issuer, legal structure, underlying asset, custodian, jurisdiction, token contract, redemption terms, and evidence provenance.
  2. Certael Proof — Proof-of-Reality reconciliation between onchain claims and offchain evidence.
  3. Certael Risk — explainable, evidence-backed integrity and risk scoring.
  4. Certael Exit — compares realistic exit routes such as secondary liquidity, issuer redemption, RFQ, and borrowing where supported.
  5. Certael ID — privacy-preserving compliance/eligibility credentials; raw KYC data must not be placed onchain.

Primary Users

  • Investor / trader
  • RWA issuer / asset manager
  • Institution / analyst
  • Auditor / verifier

The investor journey is the primary demo path. Issuer functionality must still exist sufficiently to show a complete business loop.

Core User Journey

Discover asset → inspect Passport → verify backing with Proof-of-Reality → understand Risk → verify eligibility → acquire/interact → monitor → compare Exit routes.

Product Surfaces

  • Public landing page
  • Explore Assets
  • Asset Detail
    • Overview
    • Passport
    • Proof-of-Reality
    • Risk
    • Integrity Agent
    • Compliance / Eligibility
    • Buy / Interact
    • Exit
  • Portfolio / Monitor
  • Integrity / Network intelligence
  • Issuer Portal
  • Evidence detail / provenance view
  • Network selector

Strategic Expansion

Certael Markets is a roadmap product: RWA trading with meme-token-level ease of discovery and interaction, constrained by real verification, transfer restrictions, investor eligibility, and compliance.

Long-term flow: Discover → Verify → Buy → Trade → Monitor → Exit

Do not implement this as unrestricted permissionless trading for assets whose legal structure does not allow it.

Chain Strategy

One company, one product, one core codebase, multiple chain adapters.

BOT Chain

BOT is the first priority for the current Builder Challenge. Certael's BOT integration must be substantive, not cosmetic.

BOT version should use BOT Mainnet for meaningful integrity/business state, including as appropriate:

  • asset registry / canonical asset identity
  • evidence commitments
  • Proof-of-Reality integrity state
  • risk/integrity checkpoints
  • compliance gating
  • core wallet business flow
  • settlement / liquidity interaction where validated

X Layer / OKX

Same product and core architecture, but an X Layer adapter. Use X Layer/OKX-native data, wallet, liquidity, builder attribution, and trading infrastructure where validated and relevant.

Shared Rule

Chain-specific adapters must never cause the core product to fork into separate products.

Frontend-First Strategy

Frontend is built first using typed fixtures and stable interfaces. The UI must call abstractions such as:

  • getAsset
  • getEvidence
  • getRisk
  • getEligibility
  • getExitRoutes

Fixture adapters are replaced later by backend/API adapters without redesigning the UI.

Technical Direction

Frontend

  • Next.js
  • React
  • TypeScript
  • Tailwind CSS
  • wagmi
  • viem
  • TanStack Query
  • Zod

Backend

  • Node.js / TypeScript
  • Fastify preferred initially
  • PostgreSQL / Supabase
  • Redis
  • BullMQ or equivalent only when background jobs are genuinely needed

Smart Contracts

  • Solidity
  • Foundry
  • OpenZeppelin Contracts
  • forge-std

Data / Intelligence

Python may be used for data analysis, scoring research, or financial processing where it materially helps.

Evidence Model

Every claim should preserve:

  • source
  • source type
  • observed time
  • effective time
  • verification status
  • evidence hash/signature where available
  • confidence where appropriate
  • provenance chain
  • independence classification

Supported evidence states:

  • VERIFIED
  • ATTESTED
  • DERIVED
  • SELF-REPORTED
  • STALE
  • CONFLICTED
  • UNVERIFIED

Issuer-provided data must never be silently presented as independent verification.

AI Integrity Agent

AI is a controlled reasoning layer, not the source of truth.

AI may:

  • correlate evidence
  • extract structured claims
  • identify contradictions
  • summarize issuer/legal documents
  • investigate unusual changes
  • explain risk
  • recommend actions

AI must not:

  • invent evidence
  • unilaterally alter financial truth
  • arbitrarily change risk scores
  • execute privileged onchain actions without deterministic policy and authorization checks

Architecture: Evidence → normalization → deterministic checks → AI investigation → policy validation → authorized state transition.

Security Principle

Security is continuous, not a final pre-submission task. See SECURITY.md.

Git / Delivery Principle

  • no direct feature work on main
  • scoped branch/worktree per independent task
  • review before merge
  • tests must pass before merge
  • full repository checks after merge
  • no secrets in commits
  • documentation must be updated when product truth changes

Documentation Principle

Code and documentation must never knowingly disagree.

Product Quality Principle

This is being built as a real company/product first and a hackathon submission second. Avoid generic hackathon copy, fake integrations, fake verification, or shallow chain deployments.

Non-Goals for Initial Build

  • generic chatbot
  • meaningless analytics dashboard
  • unlabelled mock financial data
  • fake institutional integrations
  • unnecessary CMS/admin work
  • separate BOT and X Layer products
  • feature expansion that breaks the core user journey

README Standard

README is a product and judging surface, not an afterthought. It should eventually cover:

  • one-line thesis
  • problem
  • product
  • architecture
  • five systems
  • Proof-of-Reality
  • evidence model
  • BOT integration
  • X Layer integration
  • AI Integrity Agent
  • contracts / deployed addresses
  • security / threat model / audit status
  • data provenance
  • local setup
  • testing
  • deployment
  • demo walkthrough
  • known limitations
  • roadmap