intuition-basic-template

Explore every Intuition protocol function through interactive forms — create atoms, make deposits, query vault state, and more.

Intuition is a protocol for creating and relating knowledge on-chain. Atoms are pieces of data (a person, a concept, a URL). Triples are relationships between atoms (e.g., "Alice is-a Developer"). Signals are economic commitments — you stake tokens to express conviction about atoms or triples. Learn more about primitives and the protocol in the Intuition docs.

For AI agents: Give your agent this entire README. It contains the file map, code paths, and constraints your agent needs to understand and extend this template. Agent-specific rules live in .agents/INSTRUCTIONS.md and are symlinked to CLAUDE.md, CODEX.md, and AGENTS.md via agentsync — your agent will pick them up automatically regardless of which tool you use.

What This Template Does

• Interactive forms for every protocol function: create atoms, look up data, make deposits, redeem positions, and query vault state.
• Shows the full flow for each operation: connect wallet, call the protocol, and see the decoded on-chain result.
• Everything talks directly to the Intuition smart contract — no extra layers in between.

Quick Start

git clone <your-fork-or-template-url>
cd intuition-basic-template
bun install
cp .env.example .env
bun dev

Build for production:

bun run build
bun preview

Note: Bun reserves bun build for its own bundler command, so use bun run build for the Vite production build.

For AI Agents

Architecture Summary

• Single-page SPA with six protocol tabs: Atoms, Triples, Deposits, Redemptions, Vault State, Protocol Config.
• Wallet and chain state come from wagmi + RainbowKit.
• Every protocol call lives in src/lib/protocol.ts.
• No GraphQL, no indexer, no server component layer, no wrapper abstractions.
• All forms are intentionally wallet-gated so the UI behavior stays consistent across writes and wallet-aware preview reads.

Key File Map

File	Purpose
src/main.tsx	Provider stack: WagmiProvider -> QueryClientProvider -> RainbowKitProvider -> App
src/config/wagmi.ts	RainbowKit/wagmi setup using intuitionTestnet from @0xintuition/protocol
src/lib/protocol.ts	Core teaching file: configs, parsing, defaults, write/read wrappers, event decoding
src/components/FormPanel.tsx	Reusable card + form + loading/error/result wrapper
src/components/ResultDisplay.tsx	Shared renderer for tx events, reads, and config structs
src/components/sections/AtomsSection.tsx	Atom create/read/preview panels
src/components/sections/TriplesSection.tsx	Triple create/read/preview panels
src/components/sections/DepositsSection.tsx	Deposit + batch + preview panels
src/components/sections/RedeemSection.tsx	Redeem + batch + preview/max panels
src/components/sections/VaultSection.tsx	Vault state reads
src/components/sections/ConfigSection.tsx	Global config + fee calculators
src/App.tsx	Tabbed shell that composes all six sections

Protocol Function Reference

Start here: The three most important functions are multiVaultCreateAtoms (create an atom), multiVaultDeposit (signal on any atom or triple), and multiVaultGetAtomCost (query the current creation cost). Everything else builds on these.

Atoms

Function	Type	Args / UI Inputs	Returns
multiVaultCreateAtoms	Write	atomText -> toHex(text)[]; assets auto-filled from multiVaultGetAtomCost()	txHash, explorer URL, decoded AtomCreated[]
multiVaultGetAtom	Read	atomId: bytes32	raw atomData bytes + decoded string when possible
multiVaultIsTermCreated	Read	termId: bytes32	boolean
multiVaultGetAtomCost	Read	none	current atom cost
multiVaultGetAtomConfig	Read	none	{ atomCreationProtocolFee, atomWalletDepositFee }
multiVaultPreviewAtomCreate	Read (wallet-aware)	termId: bytes32, assets: uint256	{ shares, assetsAfterFixedFees, assetsAfterFees }

Triples

Function	Type	Args / UI Inputs	Returns
multiVaultCreateTriples	Write	subjectIds[], predicateIds[], objectIds[]; assets auto-filled from multiVaultGetTripleCost()	txHash, explorer URL, decoded TripleCreated[]
multiVaultGetTriple	Read	tripleId: bytes32	{ subjectId, predicateId, objectId }
multiVaultIsTriple	Read	tripleId: bytes32	boolean
multiVaultGetTripleCost	Read	none	current triple cost
multiVaultGetTripleConfig	Read	none	{ tripleCreationProtocolFee, atomDepositFractionForTriple }
multiVaultGetInverseTripleId	Read	tripleId: bytes32	inverse triple ID
multiVaultIsCounterTriple	Read	tripleId: bytes32	boolean

Deposits

Function	Type	Args / UI Inputs	Returns
multiVaultDeposit	Write	receiver, termId, curveId, minShares, assets	txHash, explorer URL, decoded Deposited[]
multiVaultDepositBatch	Write	receiver, termIds[], curveIds[], assets[], minShares[]	txHash, explorer URL, decoded Deposited[]
multiVaultPreviewDeposit	Read (wallet-aware)	termId, curveId, assets	{ shares, assetsAfterFees }

Redemptions

Function	Type	Args / UI Inputs	Returns
multiVaultRedeem	Write	receiver, termId, curveId, shares, minAssets	txHash, explorer URL, decoded Redeemed[]
multiVaultRedeemBatch	Write	receiver, termIds[], curveIds[], shares[], minAssets[]	txHash, explorer URL, decoded Redeemed[]
multiVaultPreviewRedeem	Read (wallet-aware)	termId, curveId, shares	{ assetsAfterFees, sharesUsed }
multiVaultMaxRedeem	Read	sender, termId, curveId	max redeemable shares

Vault State

Function	Type	Args / UI Inputs	Returns
multiVaultGetVault	Read	termId, curveId	{ totalShares, totalAssets }
multiVaultGetShares	Read	account, termId, curveId	share balance
multiVaultCurrentSharePrice	Read	termId, curveId	share price
multiVaultConvertToAssets	Read	termId, curveId, shares	converted asset amount
multiVaultConvertToShares	Read	termId, curveId, assets	converted share amount

Protocol Config

Function	Type	Args / UI Inputs	Returns
multiVaultGetGeneralConfig	Read	none	global config struct
multiVaultEntryFeeAmount	Read	assets	entry fee amount
multiVaultExitFeeAmount	Read	assets	exit fee amount
multiVaultProtocolFeeAmount	Read	assets	protocol fee amount

Code Paths

Write Pattern

1. Build ReadConfig / WriteConfig with getReadConfig() and getWriteConfig().
2. Resolve payable amounts when required.
   • Atoms: multiVaultGetAtomCost()
   • Triples: multiVaultGetTripleCost()
3. Normalize UI input.
   • Atom text -> toHex(text)
   • CSV / newline batch fields -> arrays
   • Blank receiver -> connected wallet address
4. Execute the protocol helper.
5. Wait for the receipt and parse the emitted events.
6. Render txHash, explorer link, and decoded event tables.

Read Pattern

1. Build ReadConfig.
2. Parse user input into protocol-native values (bytes32, uint256, address).
3. Call the corresponding helper from @0xintuition/protocol.
4. Normalize tuples/structs into plain objects.
5. Render a key/value table through ResultDisplay.

Protocol Package Imports

Core imports used in this template:

import {
  intuitionTestnet,
  getMultiVaultAddressFromChainId,
  multiVaultCreateAtoms,
  multiVaultCreateTriples,
  multiVaultDeposit,
  multiVaultRedeem,
  eventParseAtomCreated,
  eventParseTripleCreated,
  eventParseDeposited,
  eventParseRedeemed,
  type ReadConfig,
  type WriteConfig,
} from '@0xintuition/protocol'

Common Modifications

• Add a new panel: extend src/lib/protocol.ts, then add one FormPanel to the relevant section component.
• Change defaults: update DEFAULT_CURVE_ID, DEFAULT_MIN_SHARES, or DEFAULT_MIN_ASSETS in src/lib/protocol.ts.
• Support mainnet: add intuitionMainnet to src/config/wagmi.ts and continue using getMultiVaultAddressFromChainId() for address resolution.
• Replace CSV batch inputs with richer UI: keep the protocol wrappers intact and swap only the section-level field collection.
• Ungate reads from wallet connection: move the disabled={!isConnected} rule in src/App.tsx to per-panel logic, but keep wallet-aware preview helpers on WriteConfig.

Environment Variables

Variable	Required	Description
VITE_WALLETCONNECT_PROJECT_ID	Yes	WalletConnect project ID used by RainbowKit / wagmi

Network Info

Testnet (default)

Item	Value
Chain	Intuition Testnet
Chain ID	13579
Native Token	$tTRUST
RPC HTTP	https://testnet.rpc.intuition.systems/http
RPC WebSocket	wss://testnet.rpc.intuition.systems/ws
Explorer	https://testnet.explorer.intuition.systems
Hub	https://testnet.hub.intuition.systems
MultiVault Address	Resolve with getMultiVaultAddressFromChainId(13579)

Getting testnet tokens

Claim 0.1 $tTRUST daily from the Intuition Testnet Hub. The hub also provides bridging and network tools.

Mainnet

Item	Value
Chain	Intuition Mainnet
Chain ID	1155
Native Token	$TRUST
RPC HTTP	https://rpc.intuition.systems/http
RPC WebSocket	wss://rpc.intuition.systems/ws
Explorer	https://explorer.intuition.systems
Hub	https://hub.intuition.systems
MultiVault Address	Resolve with getMultiVaultAddressFromChainId(1155)

Getting mainnet tokens

Bridge $TRUST from Base Mainnet through the Intuition Hub. TRUST is available as an ERC-20 on Base at 0x6cd905dF2Ed214b22e0d48FF17CD4200C1C6d8A3.

Try This With Your Agent

Copy any of these prompts into Claude, Codex, or your AI agent of choice. Give it this README for context.

• "Create an atom and immediately stake on it in a single flow." Right now creating and staking are separate forms. This combines them so you can do both in one step — great for understanding how the protocol pieces connect. Adds a new function + form panel.

• "Add a network switcher so I can use this on Intuition Mainnet too." The template runs on testnet by default. This adds mainnet ($TRUST on chain 1155) alongside testnet ($tTRUST on chain 13579) with a toggle. Touches wagmi config, protocol, and section components. See the Mainnet section above for network details.

• "Let me browse the read-only panels without connecting a wallet first." Currently everything requires a wallet connection. This makes the read panels (atom lookup, vault state, protocol config) available immediately so you can explore before connecting. Changes the gating logic in a few files.

• "Add a panel that shows my recent transactions with links to the explorer." After creating atoms or making deposits, it'd be nice to see a running history of what you've done in this session with clickable links to the block explorer. Adds a new tab + context provider.

Agent Instructions (agentsync)

This template uses agentsync to maintain a single source of truth for AI agent rules across multiple tools.

.agents/
├── agentsync.toml      ← config: which tools get symlinks
└── INSTRUCTIONS.md      ← single source of truth for agent rules

CLAUDE.md → .agents/INSTRUCTIONS.md   (Claude Code)
CODEX.md  → .agents/INSTRUCTIONS.md   (OpenAI Codex)
AGENTS.md → .agents/INSTRUCTIONS.md   (Cursor)

To update agent rules: edit .agents/INSTRUCTIONS.md. All tools see the change immediately through symlinks.

After a fresh clone: run bun run agents:apply to recreate the symlinks. You can also run bun run agents:status to check their state.

What's Not Included

• No server-side data queries, caching, or search.
• No authentication, user accounts, or saved history.
• No mainnet toggle or multi-network routing.

For those features, see the sibling repo: intuition-advanced-template.