+
+ {/* Network indicator */}
+ {isDemoMode ? (
+
+
+ Demo Mode
+
+ ) : (
+
+
+ {networkName}
+
+ )}
+
+ {/* Wallet Connect */}
+
+
+
+
+
+ Live Onchain Feed
+
+
+
+ {Array.from({ length: 5 }).map((_, i) => (
+
+ ))}
+
+
+
+ ⚠ Indexer Unavailable
+
+
+ Could not connect to the Intuition indexer. Showing local data only.
+
+
+
+
+
+ Live Onchain Feed
+
+
+
No onchain triples found yet.
+
+
+
+
+
+ Live Onchain Feed
+
+
+
+ {triples.length} triples
+
+
+
+
+ {triples.map((triple) => (
+ setExpandedId(expandedId === triple.id ? null : triple.id)}
+ />
+ ))}
+
+
+
+
+ {triple.subject.label || `Atom #${triple.subject.id}`}
+
+
+ {triple.predicate.label || `→`}
+
+
+ {triple.object.label || `Atom #${triple.object.id}`}
+
+
+ #{triple.id}
+
+
+
+ {isExpanded && (
+
+
+ Creator:
+ {triple.creator.slice(0, 8)}...{triple.creator.slice(-6)}
+
+
+ Tx:
+ {triple.transactionHash.slice(0, 10)}...
+
+
+ Block:
+ {triple.blockNumber}
+
+
+ )}
+
+
+
+ Connecting to indexer...
+
+
+ );
+ }
+
+ if (!atoms && !triples) return null;
+
+ return (
+
+
+
+ Live
+
+ {atoms && (
+
+ {atoms.length}+ atoms on-chain
+
+ )}
+ {triples && (
+
+ {triples.length}+ triples on-chain
+
+ )}
+
+ );
+}
diff --git a/src/config/env.ts b/src/config/env.ts
new file mode 100644
index 0000000..2d256eb
--- /dev/null
+++ b/src/config/env.ts
@@ -0,0 +1,65 @@
+import { z } from 'zod';
+
+/**
+ * Typed environment loader with zod validation.
+ * Single source of truth for all environment variables.
+ * Validates at module load — a misconfigured .env crashes at boot
+ * rather than producing late opaque failures during contract calls.
+ */
+
+const HexAddress = z
+ .string()
+ .regex(/^0x[a-fA-F0-9]{40}$/, 'Must be a valid 0x-prefixed 40-char hex address');
+
+const ChainId = z.coerce.number().refine(
+ (id) => id === 1155 || id === 13579,
+ 'Chain ID must be 1155 (mainnet) or 13579 (testnet)',
+);
+
+const envSchema = z.object({
+ VITE_CHAIN_ID: ChainId,
+ VITE_MULTIVAULT_ADDRESS: HexAddress,
+ VITE_GRAPHQL_URL: z.string().url(),
+ VITE_RPC_URL: z.string().url(),
+ VITE_WALLETCONNECT_PROJECT_ID: z.string().min(1).optional().default(''),
+});
+
+function loadEnv() {
+ const raw = {
+ VITE_CHAIN_ID: import.meta.env.VITE_CHAIN_ID,
+ VITE_MULTIVAULT_ADDRESS: import.meta.env.VITE_MULTIVAULT_ADDRESS,
+ VITE_GRAPHQL_URL: import.meta.env.VITE_GRAPHQL_URL,
+ VITE_RPC_URL: import.meta.env.VITE_RPC_URL,
+ VITE_WALLETCONNECT_PROJECT_ID: import.meta.env.VITE_WALLETCONNECT_PROJECT_ID,
+ };
+
+ const result = envSchema.safeParse(raw);
+
+ if (!result.success) {
+ const missing = result.error.issues
+ .map((i) => ` ${i.path.join('.')}: ${i.message}`)
+ .join('\n');
+ console.warn(
+ `⚠️ Intuition env validation failed (running in demo mode):\n${missing}`,
+ );
+ // Return safe defaults for demo/development mode
+ return {
+ VITE_CHAIN_ID: 13579 as const,
+ VITE_MULTIVAULT_ADDRESS: '0x430BbF52503Bd4801E51182f4cB9f8F534225DE5' as `0x${string}`,
+ VITE_GRAPHQL_URL: 'https://api.intuition.systems/v1/graphql',
+ VITE_RPC_URL: 'https://rpc.intuition.systems',
+ VITE_WALLETCONNECT_PROJECT_ID: '',
+ isDemo: true,
+ };
+ }
+
+ return { ...result.data, isDemo: false };
+}
+
+export const env = loadEnv();
+
+/** Derived network name for UI display */
+export const networkName = env.VITE_CHAIN_ID === 1155 ? 'Intuition Mainnet' : 'Intuition Testnet';
+
+/** Whether running in demo mode (env not fully configured) */
+export const isDemoMode = 'isDemo' in env && env.isDemo === true;
diff --git a/src/hooks/use-submit-claim.ts b/src/hooks/use-submit-claim.ts
new file mode 100644
index 0000000..e3d57a8
--- /dev/null
+++ b/src/hooks/use-submit-claim.ts
@@ -0,0 +1,89 @@
+import { useCallback, useState } from 'react';
+import { useAccount } from 'wagmi';
+import { useCreateAtom } from '../intuition/hooks/use-create-atom';
+import { env } from '../config/env';
+
+type SubmitStatus = 'idle' | 'submitting' | 'confirming' | 'success' | 'error';
+
+interface SubmitState {
+ status: SubmitStatus;
+ error: string | null;
+ txHash: string | null;
+}
+
+/**
+ * Orchestrates onchain claim submission from the ClaimBuilder.
+ *
+ * Flow:
+ * 1. User clicks "Submit Onchain"
+ * 2. Subject atom is created via MultiVault.createAtom()
+ * 3. Transaction is confirmed on-chain
+ * 4. UI shows success with tx hash link
+ *
+ * Note: Full triple creation (subject → predicate → object) requires
+ * atom IDs from the indexer. This first version creates the subject atom
+ * as proof of on-chain integration. Triple linking will follow once the
+ * indexer returns atom IDs from the creation receipt.
+ */
+export function useSubmitClaim() {
+ const { isConnected } = useAccount();
+ const { createAtom, isPending, isConfirming, isSuccess, error, hash, reset } = useCreateAtom();
+ const [submitError, setSubmitError] = useState(null);
+
+ const status: SubmitStatus = isPending
+ ? 'submitting'
+ : isConfirming
+ ? 'confirming'
+ : isSuccess
+ ? 'success'
+ : error || submitError
+ ? 'error'
+ : 'idle';
+
+ const state: SubmitState = {
+ status,
+ error: error?.message ?? submitError,
+ txHash: hash ?? null,
+ };
+
+ const canSubmit = isConnected && !env.isDemo && status === 'idle';
+
+ const submitClaim = useCallback(
+ // eslint-disable-next-line @typescript-eslint/no-unused-vars
+ (subject: string, _subjectType: string | null) => {
+ setSubmitError(null);
+
+ if (!isConnected) {
+ setSubmitError('Connect your wallet first');
+ return;
+ }
+
+ if (env.isDemo) {
+ setSubmitError('Onchain submission is disabled in demo mode');
+ return;
+ }
+
+ if (!subject.trim()) {
+ setSubmitError('Subject cannot be empty');
+ return;
+ }
+
+ // Create atom with minimum required deposit (0.0001 ETH)
+ const minDeposit = BigInt('100000000000000'); // 0.0001 ETH in wei
+ createAtom(subject.trim(), minDeposit);
+ },
+ [isConnected, createAtom],
+ );
+
+ const resetSubmit = useCallback(() => {
+ setSubmitError(null);
+ reset();
+ }, [reset]);
+
+ return {
+ submitClaim,
+ resetSubmit,
+ canSubmit,
+ ...state,
+ };
+}
diff --git a/src/intuition/abi/multivault.ts b/src/intuition/abi/multivault.ts
new file mode 100644
index 0000000..14a900f
--- /dev/null
+++ b/src/intuition/abi/multivault.ts
@@ -0,0 +1,56 @@
+import { parseAbi } from 'viem';
+
+/**
+ * MultiVault contract ABI fragments.
+ * Sourced from the canonical Intuition V2 contracts.
+ * Split into read and write subsets for safety.
+ */
+
+/** Read-only ABI fragments for queries and cost checks */
+export const multivaultReadAbi = parseAbi([
+ // Cost queries
+ 'function atomCost() view returns (uint256)',
+ 'function tripleCost() view returns (uint256)',
+ 'function getAtomCost() view returns (uint256)',
+ 'function getTripleCost() view returns (uint256)',
+
+ // Existence checks
+ 'function isAtomId(uint256 atomId) view returns (bool)',
+ 'function isTripleId(uint256 tripleId) view returns (bool)',
+
+ // Atom data
+ 'function atoms(uint256 atomId) view returns (bytes)',
+ 'function atomsByHash(bytes32 hash) view returns (uint256)',
+
+ // Triple data
+ 'function triples(uint256 tripleId) view returns (uint256 subjectId, uint256 predicateId, uint256 objectId)',
+
+ // Vault state
+ 'function getVaultTotalAssets(uint256 vaultId) view returns (uint256)',
+ 'function getVaultTotalShares(uint256 vaultId) view returns (uint256)',
+
+ // Preview functions
+ 'function previewDeposit(uint256 assets, uint256 vaultId) view returns (uint256)',
+ 'function previewRedeem(uint256 shares, uint256 vaultId) view returns (uint256)',
+
+ // Config
+ 'function defaultCurveId() view returns (uint256)',
+]);
+
+/** Write ABI fragments for creating atoms/triples and managing deposits */
+export const multivaultWriteAbi = parseAbi([
+ // Create
+ 'function createAtom(bytes atomData) payable returns (uint256)',
+ 'function batchCreateAtom(bytes[] atomData) payable returns (uint256[])',
+ 'function createTriple(uint256 subjectId, uint256 predicateId, uint256 objectId) payable returns (uint256)',
+ 'function batchCreateTriple(uint256[] subjectIds, uint256[] predicateIds, uint256[] objectIds) payable returns (uint256[])',
+
+ // Deposit / Redeem
+ 'function depositAtom(address receiver, uint256 atomId) payable returns (uint256)',
+ 'function depositTriple(address receiver, uint256 tripleId) payable returns (uint256)',
+ 'function redeemAtom(uint256 shares, address receiver, uint256 atomId) returns (uint256)',
+ 'function redeemTriple(uint256 shares, address receiver, uint256 tripleId) returns (uint256)',
+]);
+
+/** Combined ABI for consumers that need both read and write */
+export const multivaultAbi = [...multivaultReadAbi, ...multivaultWriteAbi] as const;
diff --git a/src/intuition/chains.ts b/src/intuition/chains.ts
new file mode 100644
index 0000000..605f901
--- /dev/null
+++ b/src/intuition/chains.ts
@@ -0,0 +1,42 @@
+import { defineChain } from 'viem';
+import { env } from '../config/env';
+
+/**
+ * Intuition L3 chain definitions.
+ * The Intuition Network is an Arbitrum Orbit L3 that settles to Base.
+ * Not in viem's built-in chain list, so declared via defineChain.
+ */
+
+export const intuitionMainnet = defineChain({
+ id: 1155,
+ name: 'Intuition Mainnet',
+ nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+ rpcUrls: {
+ default: { http: ['https://rpc.intuition.systems'] },
+ },
+ blockExplorers: {
+ default: { name: 'Intuition Explorer', url: 'https://explorer.intuition.systems' },
+ },
+});
+
+export const intuitionTestnet = defineChain({
+ id: 13579,
+ name: 'Intuition Testnet',
+ nativeCurrency: { name: 'Ether', symbol: 'ETH', decimals: 18 },
+ rpcUrls: {
+ default: { http: ['https://rpc-testnet.intuition.systems'] },
+ },
+ blockExplorers: {
+ default: { name: 'Intuition Testnet Explorer', url: 'https://explorer-testnet.intuition.systems' },
+ },
+ testnet: true,
+});
+
+export type IntuitionChainId = 1155 | 13579;
+export type IntuitionChain = typeof intuitionMainnet | typeof intuitionTestnet;
+
+/** Get the chain definition based on the configured chain ID */
+export function getIntuitionChain(chainId?: IntuitionChainId): IntuitionChain {
+ const id = chainId ?? env.VITE_CHAIN_ID;
+ return id === 1155 ? intuitionMainnet : intuitionTestnet;
+}
diff --git a/src/intuition/hooks/use-atoms.ts b/src/intuition/hooks/use-atoms.ts
new file mode 100644
index 0000000..d484579
--- /dev/null
+++ b/src/intuition/hooks/use-atoms.ts
@@ -0,0 +1,30 @@
+import { useQuery } from '@tanstack/react-query';
+import { getAtoms, searchAtoms } from '../services/graphql.service';
+import type { IntuitionAtom } from '../types';
+
+/**
+ * React Query hook to fetch live atoms from the Intuition indexer.
+ * Falls back gracefully if the indexer is unreachable.
+ */
+export function useAtoms(limit = 50, offset = 0) {
+ return useQuery({
+ queryKey: ['intuition-atoms', limit, offset],
+ queryFn: () => getAtoms(limit, offset),
+ staleTime: 30_000, // 30s cache
+ retry: 2,
+ refetchOnWindowFocus: false,
+ });
+}
+
+/**
+ * Search atoms by label with debounced query.
+ */
+export function useSearchAtoms(searchTerm: string, limit = 20) {
+ return useQuery({
+ queryKey: ['intuition-atoms-search', searchTerm, limit],
+ queryFn: () => searchAtoms(searchTerm, limit),
+ enabled: searchTerm.length >= 2,
+ staleTime: 30_000,
+ retry: 1,
+ });
+}
diff --git a/src/intuition/hooks/use-create-atom.ts b/src/intuition/hooks/use-create-atom.ts
new file mode 100644
index 0000000..e4f6644
--- /dev/null
+++ b/src/intuition/hooks/use-create-atom.ts
@@ -0,0 +1,36 @@
+import { useWriteContract, useWaitForTransactionReceipt } from 'wagmi';
+import { multivaultWriteAbi } from '../abi/multivault';
+import { MULTIVAULT_ADDRESS } from '../wagmi-config';
+
+/**
+ * Hook to create an atom onchain via MultiVault.createAtom().
+ * The atom data is encoded as UTF-8 bytes.
+ */
+export function useCreateAtom() {
+ const { writeContract, data: hash, isPending, error, reset } = useWriteContract();
+
+ const { isLoading: isConfirming, isSuccess } = useWaitForTransactionReceipt({
+ hash,
+ });
+
+ const createAtom = (label: string, value: bigint) => {
+ const atomData = new TextEncoder().encode(label);
+ writeContract({
+ address: MULTIVAULT_ADDRESS,
+ abi: multivaultWriteAbi,
+ functionName: 'createAtom',
+ args: [atomData as unknown as `0x${string}`],
+ value,
+ });
+ };
+
+ return {
+ createAtom,
+ hash,
+ isPending,
+ isConfirming,
+ isSuccess,
+ error,
+ reset,
+ };
+}
diff --git a/src/intuition/hooks/use-create-triple.ts b/src/intuition/hooks/use-create-triple.ts
new file mode 100644
index 0000000..f59103d
--- /dev/null
+++ b/src/intuition/hooks/use-create-triple.ts
@@ -0,0 +1,40 @@
+import { useWriteContract, useWaitForTransactionReceipt } from 'wagmi';
+import { multivaultWriteAbi } from '../abi/multivault';
+import { MULTIVAULT_ADDRESS } from '../wagmi-config';
+
+/**
+ * Hook to create a triple onchain via MultiVault.createTriple().
+ * A triple links subject → predicate → object atoms.
+ */
+export function useCreateTriple() {
+ const { writeContract, data: hash, isPending, error, reset } = useWriteContract();
+
+ const { isLoading: isConfirming, isSuccess } = useWaitForTransactionReceipt({
+ hash,
+ });
+
+ const createTriple = (
+ subjectId: bigint,
+ predicateId: bigint,
+ objectId: bigint,
+ value: bigint,
+ ) => {
+ writeContract({
+ address: MULTIVAULT_ADDRESS,
+ abi: multivaultWriteAbi,
+ functionName: 'createTriple',
+ args: [subjectId, predicateId, objectId],
+ value,
+ });
+ };
+
+ return {
+ createTriple,
+ hash,
+ isPending,
+ isConfirming,
+ isSuccess,
+ error,
+ reset,
+ };
+}
diff --git a/src/intuition/hooks/use-intuition-session.ts b/src/intuition/hooks/use-intuition-session.ts
new file mode 100644
index 0000000..30a7152
--- /dev/null
+++ b/src/intuition/hooks/use-intuition-session.ts
@@ -0,0 +1,42 @@
+import { useReadContract } from 'wagmi';
+import { multivaultReadAbi } from '../abi/multivault';
+import { MULTIVAULT_ADDRESS } from '../wagmi-config';
+import { toCurveId } from '../types';
+import type { IntuitionSessionState } from '../types';
+
+/**
+ * Hook that caches protocol session data: atomCost, tripleCost, defaultCurveId.
+ * Returns a discriminated union: loading | error | success.
+ */
+export function useIntuitionSession(): IntuitionSessionState {
+ const { data: atomCost, isLoading: loadingAtom, error: errorAtom } = useReadContract({
+ address: MULTIVAULT_ADDRESS,
+ abi: multivaultReadAbi,
+ functionName: 'getAtomCost',
+ });
+
+ const { data: tripleCost, isLoading: loadingTriple, error: errorTriple } = useReadContract({
+ address: MULTIVAULT_ADDRESS,
+ abi: multivaultReadAbi,
+ functionName: 'getTripleCost',
+ });
+
+ const { data: curveId, isLoading: loadingCurve, error: errorCurve } = useReadContract({
+ address: MULTIVAULT_ADDRESS,
+ abi: multivaultReadAbi,
+ functionName: 'defaultCurveId',
+ });
+
+ const isLoading = loadingAtom || loadingTriple || loadingCurve;
+ const error = errorAtom || errorTriple || errorCurve;
+
+ if (isLoading) return { status: 'loading' };
+ if (error) return { status: 'error', error: error as Error };
+
+ return {
+ status: 'success',
+ atomCost: atomCost as bigint,
+ tripleCost: tripleCost as bigint,
+ defaultCurveId: toCurveId((curveId as bigint) ?? 0n),
+ };
+}
diff --git a/src/intuition/hooks/use-triples.ts b/src/intuition/hooks/use-triples.ts
new file mode 100644
index 0000000..1873d98
--- /dev/null
+++ b/src/intuition/hooks/use-triples.ts
@@ -0,0 +1,29 @@
+import { useQuery } from '@tanstack/react-query';
+import { getTriples, getTriplesForAtom } from '../services/graphql.service';
+import type { IntuitionTriple } from '../types';
+
+/**
+ * React Query hook to fetch live triples from the Intuition indexer.
+ */
+export function useTriples(limit = 50, offset = 0) {
+ return useQuery({
+ queryKey: ['intuition-triples', limit, offset],
+ queryFn: () => getTriples(limit, offset),
+ staleTime: 30_000,
+ retry: 2,
+ refetchOnWindowFocus: false,
+ });
+}
+
+/**
+ * Fetch triples related to a specific atom.
+ */
+export function useTriplesForAtom(atomId: string | undefined, limit = 50) {
+ return useQuery({
+ queryKey: ['intuition-triples-atom', atomId, limit],
+ queryFn: () => getTriplesForAtom(atomId!, limit),
+ enabled: !!atomId,
+ staleTime: 30_000,
+ retry: 1,
+ });
+}
diff --git a/src/intuition/index.ts b/src/intuition/index.ts
new file mode 100644
index 0000000..b27b89d
--- /dev/null
+++ b/src/intuition/index.ts
@@ -0,0 +1,41 @@
+/**
+ * Intuition Protocol Integration Module
+ *
+ * Self-contained module providing:
+ * - Chain definitions for Intuition L3
+ * - Branded types for type-safe contract interactions
+ * - MultiVault ABI fragments
+ * - Wagmi configuration
+ * - GraphQL indexer service
+ * - React hooks for reading/writing atoms and triples
+ */
+
+// Config
+export { wagmiConfig, MULTIVAULT_ADDRESS } from './wagmi-config';
+export { getIntuitionChain, intuitionMainnet, intuitionTestnet } from './chains';
+
+// Types
+export type {
+ AtomId,
+ TripleId,
+ CurveId,
+ IntuitionAtom,
+ IntuitionTriple,
+ IntuitionSessionState,
+} from './types';
+export { toAtomId, toTripleId, toCurveId } from './types';
+
+// ABI
+export { multivaultReadAbi, multivaultWriteAbi, multivaultAbi } from './abi/multivault';
+
+// Services
+export { getAtoms, getTriples, searchAtoms, getTriplesForAtom } from './services/graphql.service';
+export { pinThing, pinPerson, pinOrganization, pinAtomData, isCaip10Address } from './services/ipfs.service';
+export type { IpfsUri, ThingInput, PersonInput, OrganizationInput, AtomPinRequest } from './services/ipfs.service';
+
+// Hooks
+export { useIntuitionSession } from './hooks/use-intuition-session';
+export { useAtoms, useSearchAtoms } from './hooks/use-atoms';
+export { useTriples, useTriplesForAtom } from './hooks/use-triples';
+export { useCreateAtom } from './hooks/use-create-atom';
+export { useCreateTriple } from './hooks/use-create-triple';
diff --git a/src/intuition/services/graphql.service.ts b/src/intuition/services/graphql.service.ts
new file mode 100644
index 0000000..498a70d
--- /dev/null
+++ b/src/intuition/services/graphql.service.ts
@@ -0,0 +1,182 @@
+import { env } from '../../config/env';
+import type { IntuitionAtom, IntuitionTriple } from '../types';
+
+/**
+ * GraphQL service for querying the Intuition indexer.
+ * Fetches atoms, triples, and positions from the knowledge graph.
+ */
+
+const GRAPHQL_URL = env.VITE_GRAPHQL_URL;
+
+async function gqlFetch(query: string, variables?: Record): Promise {
+ const res = await fetch(GRAPHQL_URL, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ query, variables }),
+ });
+
+ if (!res.ok) {
+ throw new Error(`GraphQL request failed: ${res.status} ${res.statusText}`);
+ }
+
+ const json = await res.json();
+ if (json.errors?.length) {
+ throw new Error(`GraphQL errors: ${JSON.stringify(json.errors)}`);
+ }
+
+ return json.data as T;
+}
+
+/** Fetch recent atoms from the indexer */
+export async function getAtoms(limit = 50, offset = 0): Promise {
+ const query = `
+ query GetAtoms($limit: Int!, $offset: Int!) {
+ atoms(limit: $limit, offset: $offset, order_by: { blockTimestamp: desc }) {
+ id
+ vaultId
+ label
+ type
+ image
+ creator { id }
+ blockNumber
+ blockTimestamp
+ transactionHash
+ }
+ }
+ `;
+
+ try {
+ const data = await gqlFetch<{ atoms: Array> }>(query, { limit, offset });
+ return (data.atoms || []).map(mapAtom);
+ } catch (err) {
+ console.warn('Failed to fetch atoms from indexer:', err);
+ return [];
+ }
+}
+
+/** Fetch recent triples from the indexer */
+export async function getTriples(limit = 50, offset = 0): Promise {
+ const query = `
+ query GetTriples($limit: Int!, $offset: Int!) {
+ triples(limit: $limit, offset: $offset, order_by: { blockTimestamp: desc }) {
+ id
+ vaultId
+ subject { id vaultId label type image creator { id } blockNumber blockTimestamp transactionHash }
+ predicate { id vaultId label type image creator { id } blockNumber blockTimestamp transactionHash }
+ object { id vaultId label type image creator { id } blockNumber blockTimestamp transactionHash }
+ creator { id }
+ blockNumber
+ blockTimestamp
+ transactionHash
+ counterVaultId
+ }
+ }
+ `;
+
+ try {
+ const data = await gqlFetch<{ triples: Array> }>(query, { limit, offset });
+ return (data.triples || []).map(mapTriple);
+ } catch (err) {
+ console.warn('Failed to fetch triples from indexer:', err);
+ return [];
+ }
+}
+
+/** Search atoms by label */
+export async function searchAtoms(searchTerm: string, limit = 20): Promise {
+ const query = `
+ query SearchAtoms($search: String!, $limit: Int!) {
+ atoms(where: { label: { _ilike: $search } }, limit: $limit, order_by: { blockTimestamp: desc }) {
+ id
+ vaultId
+ label
+ type
+ image
+ creator { id }
+ blockNumber
+ blockTimestamp
+ transactionHash
+ }
+ }
+ `;
+
+ try {
+ const data = await gqlFetch<{ atoms: Array> }>(query, {
+ search: `%${searchTerm}%`,
+ limit,
+ });
+ return (data.atoms || []).map(mapAtom);
+ } catch (err) {
+ console.warn('Failed to search atoms:', err);
+ return [];
+ }
+}
+
+/** Get triples for a specific atom (as subject, predicate, or object) */
+export async function getTriplesForAtom(atomId: string, limit = 50): Promise {
+ const query = `
+ query GetTriplesForAtom($atomId: String!, $limit: Int!) {
+ triples(
+ where: {
+ _or: [
+ { subject: { id: { _eq: $atomId } } }
+ { predicate: { id: { _eq: $atomId } } }
+ { object: { id: { _eq: $atomId } } }
+ ]
+ }
+ limit: $limit
+ order_by: { blockTimestamp: desc }
+ ) {
+ id
+ vaultId
+ subject { id vaultId label type image creator { id } blockNumber blockTimestamp transactionHash }
+ predicate { id vaultId label type image creator { id } blockNumber blockTimestamp transactionHash }
+ object { id vaultId label type image creator { id } blockNumber blockTimestamp transactionHash }
+ creator { id }
+ blockNumber
+ blockTimestamp
+ transactionHash
+ counterVaultId
+ }
+ }
+ `;
+
+ try {
+ const data = await gqlFetch<{ triples: Array> }>(query, { atomId, limit });
+ return (data.triples || []).map(mapTriple);
+ } catch (err) {
+ console.warn('Failed to fetch triples for atom:', err);
+ return [];
+ }
+}
+
+// ─── Mappers ──────────────────────────────────────────
+
+function mapAtom(raw: Record): IntuitionAtom {
+ return {
+ id: String(raw.id ?? ''),
+ vaultId: String(raw.vaultId ?? ''),
+ label: String(raw.label ?? ''),
+ type: String(raw.type ?? ''),
+ image: raw.image ? String(raw.image) : undefined,
+ creator: String((raw.creator as Record)?.id ?? ''),
+ blockNumber: String(raw.blockNumber ?? ''),
+ blockTimestamp: String(raw.blockTimestamp ?? ''),
+ transactionHash: String(raw.transactionHash ?? ''),
+ };
+}
+
+function mapTriple(raw: Record): IntuitionTriple {
+ return {
+ id: String(raw.id ?? ''),
+ vaultId: String(raw.vaultId ?? ''),
+ subject: mapAtom(raw.subject as Record),
+ predicate: mapAtom(raw.predicate as Record),
+ object: mapAtom(raw.object as Record),
+ creator: String((raw.creator as Record)?.id ?? ''),
+ blockNumber: String(raw.blockNumber ?? ''),
+ blockTimestamp: String(raw.blockTimestamp ?? ''),
+ transactionHash: String(raw.transactionHash ?? ''),
+ counterVaultId: raw.counterVaultId ? String(raw.counterVaultId) : undefined,
+ };
+}
diff --git a/src/intuition/services/ipfs.service.ts b/src/intuition/services/ipfs.service.ts
new file mode 100644
index 0000000..bea18e8
--- /dev/null
+++ b/src/intuition/services/ipfs.service.ts
@@ -0,0 +1,233 @@
+/**
+ * IPFS Pinning Service for structured atom data.
+ *
+ * The Intuition protocol requires atoms (except CAIP-10 addresses) to be
+ * pinned to IPFS before on-chain creation. The indexer GraphQL endpoint
+ * exposes `pinThing`, `pinPerson`, and `pinOrganization` mutations that
+ * wrap Pinata/Helia and return an `ipfs://` URI.
+ *
+ * This service:
+ * 1. Provides typed wrappers for all three pin mutations
+ * 2. Implements automatic retry with exponential backoff
+ * 3. Caches recent pins to avoid duplicate IPFS uploads
+ * 4. Offers a high-level `pinAtomData()` that auto-selects the correct
+ * mutation based on schema.org type detection
+ *
+ * @see https://docs.intuition.systems/atoms/pinning
+ */
+
+import { env } from '../../config/env';
+
+// ─── Types ───────────────────────────────────────────────────────────
+export type IpfsUri = `ipfs://${string}`;
+
+/** schema.org Thing — base type for all structured atoms. */
+export interface ThingInput {
+ name: string;
+ description?: string;
+ image?: string;
+ url?: string;
+}
+
+/** schema.org Person — extends Thing with identity fields. */
+export interface PersonInput extends ThingInput {
+ email?: string;
+ identifier?: string;
+}
+
+/** schema.org Organization — extends Thing with org fields. */
+export interface OrganizationInput extends ThingInput {
+ email?: string;
+}
+
+/** Discriminated union for type-safe atom pinning. */
+export type AtomPinRequest =
+ | { type: 'Thing'; data: ThingInput }
+ | { type: 'Person'; data: PersonInput }
+ | { type: 'Organization'; data: OrganizationInput };
+
+// ─── GraphQL Mutations ───────────────────────────────────────────────
+
+const PIN_THING = `
+ mutation PinThing($name: String!, $description: String!, $image: String!, $url: String!) {
+ pinThing(thing: { name: $name, description: $description, image: $image, url: $url }) {
+ uri
+ }
+ }
+`;
+
+const PIN_PERSON = `
+ mutation PinPerson($name: String!, $description: String!, $image: String!, $url: String!, $email: String!, $identifier: String!) {
+ pinPerson(person: { name: $name, description: $description, image: $image, url: $url, email: $email, identifier: $identifier }) {
+ uri
+ }
+ }
+`;
+
+const PIN_ORGANIZATION = `
+ mutation PinOrganization($name: String!, $description: String!, $image: String!, $url: String!, $email: String!) {
+ pinOrganization(organization: { name: $name, description: $description, image: $image, url: $url, email: $email }) {
+ uri
+ }
+ }
+`;
+
+// ─── LRU Pin Cache ───────────────────────────────────────────────────
+const PIN_CACHE = new Map();
+const MAX_CACHE = 128;
+
+function cacheKey(req: AtomPinRequest): string {
+ return `${req.type}:${JSON.stringify(req.data)}`;
+}
+
+function cacheSet(key: string, uri: IpfsUri): void {
+ if (PIN_CACHE.size >= MAX_CACHE) {
+ const oldest = PIN_CACHE.keys().next().value;
+ if (oldest) PIN_CACHE.delete(oldest);
+ }
+ PIN_CACHE.set(key, uri);
+}
+
+// ─── Retry Logic ─────────────────────────────────────────────────────
+const MAX_RETRIES = 3;
+const BASE_DELAY_MS = 500;
+
+async function sleep(ms: number): Promise {
+ return new Promise((r) => setTimeout(r, ms));
+}
+
+// ─── Core GraphQL Executor ───────────────────────────────────────────
+
+interface PinResponse {
+ [key: string]: { uri?: string | null } | null | undefined;
+}
+
+async function executePinMutation(
+ query: string,
+ variables: Record,
+): Promise {
+ let lastError: Error | null = null;
+
+ for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+ try {
+ const res = await fetch(env.VITE_GRAPHQL_URL, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ query, variables }),
+ });
+
+ if (!res.ok) {
+ throw new Error(`IPFS pin failed: HTTP ${res.status} ${res.statusText}`);
+ }
+
+ const json = (await res.json()) as { data?: PinResponse; errors?: Array<{ message: string }> };
+
+ if (json.errors?.length) {
+ throw new Error(`IPFS pin GraphQL error: ${json.errors[0]?.message ?? 'unknown'}`);
+ }
+
+ // Extract URI from whichever mutation key exists
+ const data = json.data;
+ if (!data) throw new Error('IPFS pin returned no data');
+
+ const mutationResult = Object.values(data).find((v) => v && typeof v === 'object');
+ const uri = mutationResult?.uri;
+
+ if (!uri || !uri.startsWith('ipfs://')) {
+ throw new Error(`IPFS pin returned invalid URI: ${uri}`);
+ }
+
+ return uri as IpfsUri;
+ } catch (err) {
+ lastError = err instanceof Error ? err : new Error(String(err));
+ if (attempt < MAX_RETRIES - 1) {
+ await sleep(BASE_DELAY_MS * Math.pow(2, attempt));
+ }
+ }
+ }
+
+ throw lastError ?? new Error('IPFS pin exhausted retries');
+}
+
+// ─── Coerce helpers (optional → empty string for GraphQL) ────────────
+function coerce(val: string | undefined): string {
+ return val ?? '';
+}
+
+// ─── Public API ──────────────────────────────────────────────────────
+
+/** Pin a schema.org Thing to IPFS. */
+export async function pinThing(input: ThingInput): Promise {
+ return executePinMutation(PIN_THING, {
+ name: input.name,
+ description: coerce(input.description),
+ image: coerce(input.image),
+ url: coerce(input.url),
+ });
+}
+
+/** Pin a schema.org Person to IPFS. */
+export async function pinPerson(input: PersonInput): Promise {
+ return executePinMutation(PIN_PERSON, {
+ name: input.name,
+ description: coerce(input.description),
+ image: coerce(input.image),
+ url: coerce(input.url),
+ email: coerce(input.email),
+ identifier: coerce(input.identifier),
+ });
+}
+
+/** Pin a schema.org Organization to IPFS. */
+export async function pinOrganization(input: OrganizationInput): Promise {
+ return executePinMutation(PIN_ORGANIZATION, {
+ name: input.name,
+ description: coerce(input.description),
+ image: coerce(input.image),
+ url: coerce(input.url),
+ email: coerce(input.email),
+ });
+}
+
+/**
+ * High-level auto-router: pins atom data based on discriminated type.
+ * Implements LRU caching to avoid duplicate IPFS uploads for identical atoms.
+ *
+ * @example
+ * ```ts
+ * const uri = await pinAtomData({ type: 'Person', data: { name: 'Vitalik', email: 'vb@ethereum.org' } });
+ * // => 'ipfs://Qm...'
+ * ```
+ */
+export async function pinAtomData(request: AtomPinRequest): Promise {
+ const key = cacheKey(request);
+ const cached = PIN_CACHE.get(key);
+ if (cached) return cached;
+
+ let uri: IpfsUri;
+
+ switch (request.type) {
+ case 'Thing':
+ uri = await pinThing(request.data);
+ break;
+ case 'Person':
+ uri = await pinPerson(request.data);
+ break;
+ case 'Organization':
+ uri = await pinOrganization(request.data);
+ break;
+ }
+
+ cacheSet(key, uri);
+ return uri;
+}
+
+/**
+ * Check if a string looks like a CAIP-10 blockchain address.
+ * CAIP-10 atoms are NOT pinned — they're submitted as raw string bytes.
+ */
+export function isCaip10Address(value: string): boolean {
+ // CAIP-10 format: ::
+ // e.g., eip155:1:0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
+ return /^[a-z0-9-]+:\d+:0x[a-fA-F0-9]{40}$/.test(value);
+}
diff --git a/src/intuition/types.ts b/src/intuition/types.ts
new file mode 100644
index 0000000..b17fb28
--- /dev/null
+++ b/src/intuition/types.ts
@@ -0,0 +1,64 @@
+/**
+ * Branded ID types for type-safe contract interactions.
+ * Prevents mixing up atom IDs with triple IDs at the type level.
+ */
+
+declare const __brand: unique symbol;
+type Brand = T & { readonly [__brand]: B };
+
+/** Unique identifier for an Atom in the MultiVault */
+export type AtomId = Brand;
+
+/** Unique identifier for a Triple in the MultiVault */
+export type TripleId = Brand;
+
+/** Unique identifier for a bonding curve */
+export type CurveId = Brand;
+
+/** Helper to create branded IDs from raw bigints */
+export const toAtomId = (id: bigint): AtomId => id as AtomId;
+export const toTripleId = (id: bigint): TripleId => id as TripleId;
+export const toCurveId = (id: bigint): CurveId => id as CurveId;
+
+/** Exhaustiveness check helper */
+export function assertNever(x: never): never {
+ throw new Error(`Unexpected value: ${x}`);
+}
+
+/** Intuition Atom from the indexer */
+export interface IntuitionAtom {
+ id: string;
+ vaultId: string;
+ label: string;
+ type: string;
+ image?: string;
+ creator: string;
+ blockNumber: string;
+ blockTimestamp: string;
+ transactionHash: string;
+}
+
+/** Intuition Triple from the indexer */
+export interface IntuitionTriple {
+ id: string;
+ vaultId: string;
+ subject: IntuitionAtom;
+ predicate: IntuitionAtom;
+ object: IntuitionAtom;
+ creator: string;
+ blockNumber: string;
+ blockTimestamp: string;
+ transactionHash: string;
+ counterVaultId?: string;
+}
+
+/** Session state for Intuition protocol costs */
+export type IntuitionSessionState =
+ | { status: 'loading' }
+ | { status: 'error'; error: Error }
+ | {
+ status: 'success';
+ atomCost: bigint;
+ tripleCost: bigint;
+ defaultCurveId: CurveId;
+ };
diff --git a/src/intuition/wagmi-config.ts b/src/intuition/wagmi-config.ts
new file mode 100644
index 0000000..c082385
--- /dev/null
+++ b/src/intuition/wagmi-config.ts
@@ -0,0 +1,23 @@
+import { http } from 'wagmi';
+import { getDefaultConfig } from '@rainbow-me/rainbowkit';
+import { env } from '../config/env';
+import { getIntuitionChain } from './chains';
+
+/**
+ * Wagmi configuration wired to the env-selected Intuition chain.
+ * Uses RainbowKit's getDefaultConfig for wallet connectors.
+ */
+
+const chain = getIntuitionChain();
+
+export const wagmiConfig = getDefaultConfig({
+ appName: 'Intuition Ontology',
+ projectId: env.VITE_WALLETCONNECT_PROJECT_ID || 'demo-project-id',
+ chains: [chain],
+ transports: {
+ [chain.id]: http(env.VITE_RPC_URL),
+ },
+});
+
+/** The MultiVault contract address */
+export const MULTIVAULT_ADDRESS = env.VITE_MULTIVAULT_ADDRESS as `0x${string}`;
diff --git a/src/main.tsx b/src/main.tsx
index f24bbaf..1024fcd 100644
--- a/src/main.tsx
+++ b/src/main.tsx
@@ -1,14 +1,47 @@
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { BrowserRouter } from 'react-router-dom';
+import { WagmiProvider } from 'wagmi';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { RainbowKitProvider, darkTheme, lightTheme } from '@rainbow-me/rainbowkit';
+import '@rainbow-me/rainbowkit/styles.css';
import './globals.css';
import App from './App';
+import { wagmiConfig } from './intuition/wagmi-config';
+
+const queryClient = new QueryClient({
+ defaultOptions: {
+ queries: {
+ staleTime: 30_000,
+ retry: 2,
+ },
+ },
+});
createRoot(document.getElementById('root')!).render(
-
-
-
+
+
+
+
+
+
+
+
+
,
);
diff --git a/src/pages/home.tsx b/src/pages/home.tsx
index bf8e29c..684d36f 100644
--- a/src/pages/home.tsx
+++ b/src/pages/home.tsx
@@ -5,7 +5,10 @@ import { RelationshipGraph } from '../components/relationship-graph';
import { PredicateExplorer } from '../components/predicate-explorer';
import { ClaimHistory } from '../components/claim-history';
import { BatchBuilder } from '../components/batch-builder';
+import { OnchainFeed } from '../components/onchain-feed';
+import { OnchainStats } from '../components/onchain-stats';
import { useClaimWorkspace } from '../lib/use-claim-workspace';
+import { useSubmitClaim } from '../hooks/use-submit-claim';
export function HomePage() {
const {
@@ -20,6 +23,14 @@ export function HomePage() {
fillFromMatrix,
} = useClaimWorkspace();
+ const {
+ submitClaim,
+ canSubmit,
+ status,
+ error: onchainError,
+ txHash,
+ } = useSubmitClaim();
+
return (
@@ -29,11 +40,25 @@ export function HomePage() {
onPredicateChange={setSelectedPredicateId}
onSave={saveClaim}
onAddToBatch={addToBatch}
+ onSubmitOnchain={submitClaim}
+ onchainStatus={status}
+ onchainError={onchainError}
+ onchainTxHash={txHash}
+ canSubmitOnchain={canSubmit}
/>
+ {/* Live onchain data from Intuition protocol */}
+
+
+ {/* Live stats augmenting the static ontology views */}
+
+
Ontology Explorer
+
+
+