XGuard AI

Verifiable pre-sign security and policy infrastructure for X Layer.

Know what a transaction does before you sign. XGuard combines deterministic transaction decoding, X Layer RPC intelligence, OKX OnchainOS Mainnet simulation evidence, Intent vs Reality, and evidence-grounded AI advisory with versioned receipts, SHA-256 integrity, Ed25519 deployment-key attestation, deterministic wallet/dApp policy, and real X Layer Mainnet receipt anchoring.

Transaction → Evidence → Receipt Integrity → Deployment-key Authenticity → Policy Action → Mainnet Receipt Anchor

The Policy Guard returns ALLOW, WARN, REQUIRE_REVIEW, or BLOCK_RECOMMENDED. AI Advisory never controls policy state, ALLOW is not a guarantee of safety, and nothing connects, signs, or broadcasts automatically.

Live Mainnet Proof

• Chain: X Layer Mainnet — 196
• Anchor Contract: 0xf4505A4e8dEca4659b8A2054555788Ddc1f5AcE5
• Deployment Tx: 0x435ffbb932a66462bd846851535b594dbc3fad6b13f64d3ba9f17023a8fd73cb
• First Anchor Tx: 0xd2c244178a313c1367ce60ed679661cce4740fd27e62e7722b8eadd995b54347
• Receipt Digest: 0xef6cf319eb689233180f465d331969c91a9c5c07d893047294bdda5de0da0eab · anchored(bytes32) = true

The anchor records the exact existing V5 SHA-256 receipt digest without rehashing. It proves only that the configured contract recorded that digest in a confirmed Chain 196 transaction; receipt integrity, XGuard authorship, policy, and transaction safety remain separate claims.

Production: xguard-ai-six.vercel.app · GitHub: github.com/leafwithered/xguard-ai · Final Demo: xguard-ai-build-x-final.mp4

X account: @AevrynHQ · Build X post: View post

What judges can verify

1. Safe Transfer — 8 LOW, an explainable deterministic baseline.
2. Ambiguous Approval — deterministic 20 LOW, LOW confidence, UNDETERMINED; approve(address,uint256) is not forced into ERC20 semantics without token-standard evidence.
3. Suspicious Airdrop — deterministic 78 HIGH, MISMATCH; claim intent conflicts with setApprovalForAll(true).
4. Live OKX Mainnet Simulation — a public historical approval fixture can be loaded explicitly for real, read-only provider evidence on Chain 196.
5. Analysis Receipt — inspect a random analysis ID, schema version, normalized provenance, and SHA-256 fingerprint; export JSON explicitly.
6. Verify Receipt — verify the current receipt or import a JSON receipt locally; tampering fails the integrity check.
7. Signed Analysis Attestation — verify that the exact receipt fingerprint was signed by the Ed25519 key configured for this deployment.
8. Policy Guard — inspect a deterministic integration recommendation and stable reason codes; AI does not control the decision.
9. X Layer Mainnet Anchor — verify the exact V5 SHA-256 receipt digest through the configured contract on Mainnet 196 without automatic wallet interaction.

Judge Mode only loads examples and navigates. The user must explicitly select Analyze risk. It never connects a wallet, signs, records, or broadcasts.

Competition build status

This is the final Build X competition build. Its receipt integrity, deployment-key attestation, deterministic policy, and X Layer Mainnet anchor remain separate verification layers.

• Testnet 1952 retains the V3 RPC/preflight path and never calls the Mainnet simulator.
• Mainnet 196 adds optional OKX OnchainOS simulation with chainIndex: "196".
• A Live Provider badge appears only for normalized AVAILABLE evidence with HTTP 200 and business code 0 on Mainnet 196.
• RPC and OKX simulation remain separate evidence sources; disagreement is surfaced and lowers confidence.
• Missing credentials, timeout, rate limiting, malformed responses, and provider errors never disable deterministic analysis.
• Empty provider risk entries mean only that no entries were returned—not that a transaction is safe.
• Every completed analysis adds a backward-compatible analysisReceipt response field with schema 1.0.0 and xguard-c14n-v1 integrity.
• When configured, the API adds an optional analysisAttestation signed by the deployment's Ed25519 key; missing or invalid signing configuration never breaks analysis or the V5 receipt.
• Standalone V5 receipt export is unchanged. A separate Attested Analysis Package binds the receipt fingerprint to the deployment key.
• Attested package verification resolves the deployment's trusted public key and never trusts a key supplied by an uploaded package.
• Export and verification are explicit actions. Verification does not call AI, OKX, RPC, a wallet, or a blockchain.
• A separate adjacent policyDecision uses only normalized deterministic evidence and does not modify the V5 receipt or V6 attestation formats.
• Use sdk/xguard.ts and examples/wallet-integration.ts for a compact, repository-local integration example.

See the Mainnet Anchor specification, human deployment guide, Policy Engine specification, Analysis Receipt specification, Signed Attestation specification, integration guide, OpenAPI, and judge demo.

Evidence hierarchy

XGuard reports these layers separately:

Layer	Meaning
Final Risk Score	max(Deterministic Known Risk, AI Advisory)
Deterministic Known Risk	Rule- and decoder-backed heuristic severity
AI Advisory	Evidence-grounded score/explanation; may raise but never lower the deterministic floor
Confidence / Verdict / Execution	Whether evidence is sufficient, whether the case is assessed, and current-state preflight outcome
Consequences / Intent	What signing does and whether that matches the user’s stated goal
X Layer RPC	Bytecode, scoped EIP-1967 implementation-slot check, eth_call, and eth_estimateGas
OKX Simulation	Additional Mainnet provider evidence: intention, changes, gas, failure reason, and risk entries

The primary score is never labeled “known risk” when AI raised it. For example, an Ambiguous Approval may show deterministic 20 LOW, AI 75 HIGH, and final 75 HIGH while remaining LOW confidence and UNDETERMINED.

Deterministic Safety Invariant

Final Risk = max(Deterministic Known Risk, AI Advisory)

AI can explain evidence or raise final risk, but it cannot reduce deterministic known-risk signals, rewrite RPC/simulation facts, change the deterministic verdict, or turn missing evidence into proof of safety. If the AI provider is missing, unavailable, slow, or malformed, XGuard falls back to Local Analysis.

Why X Layer and OKX

X Layer is where transaction intent, contract behavior, and user confirmation meet. XGuard uses X Layer RPC for chain-specific bytecode and bounded preflight evidence on both supported networks. The historical RiskRegistry on Testnet 1952 creates a compact public proof that a user reviewed an assessment without executing the analyzed transaction. The current XGuardReceiptAnchor on Mainnet 196 separately records the exact SHA-256 digest of a versioned Analysis Receipt.

On X Layer Mainnet, OKX OnchainOS adds an independent read-only simulation view. That evidence improves consequence visibility but is deliberately bounded: provider evidence is not a safety verdict, and Testnet 1952 is never sent to the Mainnet-only simulation endpoint.

Architecture

flowchart TD
    U[User transaction + optional intent] --> D[Deterministic decoder and rules]
    D --> R[X Layer RPC intelligence and preflight]
    R --> O{Mainnet 196?}
    O -->|yes| S[OKX read-only simulation]
    O -->|no: Testnet 1952| E[Normalized evidence]
    S --> E
    E --> C[Consequences + confidence + verdict]
    E --> A[One optional AI advisory call]
    C --> F[Deterministic safety invariant]
    A --> F
    F --> V[Final assessment]
    V --> P[Versioned Analysis Receipt]
    P --> K[xguard-c14n-v1]
    K --> Z[SHA-256 fingerprint]
    Z --> T[Ed25519 deployment attestation]
    T --> X[Export / Verify / API]
    Z --> M[X Layer Mainnet Receipt Anchor]
    V --> G[Deterministic Policy Guard]
    V --> H[Human decision]
    H --> Q[Optional existing Testnet RiskRegistry]

Loading

lib/analyze-pipeline.ts owns evidence-first orchestration. lib/evidence.ts creates a bounded, normalized evidence object before lib/ai/provider.ts is called. The provider adapter is configured only on the server through AI_API_KEY, AI_BASE_URL, and AI_MODEL; the public client does not expose or prove the upstream provider identity.

lib/analysis-receipt.ts is the shared server/browser implementation for receipt construction, strict validation, canonicalization, fingerprinting, and local verification. Integrity verification confirms content consistency only; it does not prove safety or XGuard authorship.

lib/analysis-attestation.ts validates packages and verifies signatures against the deployment trust root. Server-only signing derives the public SPKI key from one configured PKCS#8 private key. Attestation verification confirms deployment-key authenticity of a receipt fingerprint, not transaction safety, provider truth, finality, on-chain anchoring, or legal identity.

X Layer integration

Analysis network	Chain ID	RPC	OKX Transaction Simulation
X Layer Testnet	1952	Supported: https://testrpc.xlayer.tech/terigon with bounded preflight	Mainnet simulation not used
X Layer Mainnet	196	Supported: https://rpc.xlayer.tech with bounded preflight	OKX OnchainOS read-only transaction simulation supported with chainIndex: "196"

RPC checks are isolated and timeout-bounded:

• eth_getCode identifies EOA versus contract and reports bytecode size.
• eth_getStorageAt checks only the EIP-1967 implementation slot; it does not exclude every proxy type.
• eth_call records current-state success/revert evidence.
• eth_estimateGas reports an estimate when available.

These are bounded preflight checks, not an audit or full trace/state-diff guarantee.

Historical Testnet evidence

• Network: X Layer Testnet (1952)
• RiskRegistry: 0xf4505A4e8dEca4659b8A2054555788Ddc1f5AcE5
• Deployment transaction: 0xf4169572833b69bb7a5cb234d092f7ab1b27e15d2520e6544591c2358533c75b
• Verified user transaction: 0x1492bc179e98fe5fe79add3528f8f1f26990ab37e189a98d4c4a052d6fd11bcb
• Receipt: success; RiskAssessmentRecorded emitted with score 12

This separate historical RiskRegistry proof is on Testnet 1952; it is not the Mainnet 196 receipt anchor. Neither contract holds funds or creates a token.

Local development

pnpm install --frozen-lockfile
copy .env.example .env.local
pnpm run dev

Open http://localhost:3000. Without AI or OKX credentials, deterministic Local Analysis and the Testnet RPC path remain usable.

Server-side configuration

Variable	Purpose
AI_API_KEY	AI provider key
AI_BASE_URL	OpenAI-compatible base URL
AI_MODEL	Provider model identifier
XLAYER_RPC_URL	Testnet RPC
XLAYER_MAINNET_RPC_URL	Mainnet RPC
OKX_API_KEY	OKX API key
OKX_SECRET_KEY	OKX signing secret
OKX_API_PASSPHRASE	OKX passphrase
XGUARD_ATTESTATION_PRIVATE_KEY_PEM_B64	Base64 of complete PKCS#8 Ed25519 private-key PEM file bytes; server-only
XGUARD_ATTESTATION_KEY_ID	Public bounded identifier for the deployment attestation key
NEXT_PUBLIC_RISK_REGISTRY_ADDRESS	Public deployed Testnet registry address

DEPLOYER_PRIVATE_KEY is needed only for explicitly authorized historical/developer contract deployment tooling and must never be configured in the browser or committed. The Production application does not use it. The current Mainnet Receipt Anchor is already deployed and publicly verifiable.

Verification

pnpm run build
pnpm run contract:test
pnpm run risk:test
pnpm run ai:test
pnpm run decoder:test
pnpm run fusion:test
pnpm run intelligence:test
pnpm run transaction-analyzer:test
pnpm run judge:test
pnpm run analysis-state:test
pnpm run consequence:test
pnpm run intent:test
pnpm run pipeline:test
pnpm run token-standard:test
pnpm run security-benchmark:test
pnpm run simulation:test
pnpm run presentation:test
pnpm run receipt:test
pnpm run attestation:test

V6 preserves the complete V5 corpus and its exact receipt fingerprints, then adds ephemeral-key signing, strict binding, trusted-key verification, recomputed-fingerprint attack, failure-isolation, privacy, and trust-language coverage.

Limitations

• Scores are heuristic severity, not calibrated fraud probabilities.
• RPC preflight and OKX simulation are current-state, bounded evidence—not proof of safety.
• Contract reputation and verified-source provenance are not yet integrated.
• AI and deterministic rules can miss malicious behavior or create false positives.
• This prototype has a basic in-memory API rate limit and no availability SLA.
• Receipt fingerprints provide content integrity only. Ed25519 attestations add deployment-key authenticity of the fingerprint, not provider authentication, transaction safety, finality, on-chain anchoring, or legal identity.

Demo history

The final competition video is demo/xguard-ai-build-x-final.mp4, an 88-second 1920×1080 H.264 capture of the canonical Production trust path. The earlier demo/xguard-ai-build-x-demo.mp4 remains unchanged as historical evidence; it is not the final competition demo.

License

Released under the MIT License. Submission fields are in docs/SUBMISSION.md; contact email remains only in the official form.