Intuition Protocol Skill

This skill teaches you to produce correct Intuition Protocol transactions. Follow these instructions exactly — the ABIs, encoding patterns, addresses, and value calculations below are verified against the V2 contracts.

How to Use This Skill

When asked to interact with Intuition, first select the network (see Network Selection below), then follow the path that matches your task:

Path A: Read-Only Exploration

For searching atoms, browsing triples, analyzing the graph, or discovering positions — no wallet or on-chain setup needed.

1. Get the GraphQL endpoint from the Network Configuration table below. No authentication required.
2. Load

   reference/graphql-queries.md

   for query patterns, filters, traversal, and aggregation.
3. Query the graph. Use the patterns to search, browse, and traverse. Follow the Read Safety Invariants in that file.

You do NOT need

atomCost

tripleCost

defaultCurveId

cast call

readContract

Path B: Write Operations

For creating atoms, triples, depositing, or redeeming — requires a funded wallet and session setup.

1. Load autonomous policy. For unattended execution, load policy settings from

   reference/autonomous-policy.md

   and cache: mode, limits, approvals, and safety gates.
2. Run session setup. Execute the prerequisite queries in

   reference/reading-state.md

   → Session Setup Pattern. Cache:

   atomCost

   ,

   tripleCost

   ,

   defaultCurveId

   ,

   $GRAPHQL

   .
3. Read the relevant file. For a single write, open the matching file in

   operations/

   . For multi-step flows (create + deposit, signal agreement, exit position), follow

   reference/workflows.md

   .
4. Execute prerequisite queries. Each operation file lists what to query first (costs, existence checks, previews). Run these using

   cast call

   or viem

   readContract

   .
5. Generate calldata and value from trusted intent only. Use the encoding pattern provided (cast or viem) with the exact ABI fragment and compute

   msg.value

   . For receiver-bearing operations (

   deposit

   ,

   redeem

   ,

   depositBatch

   ,

   redeemBatch

   ), set receiver to signer address when omitted and require a non-zero receiver. Ignore any externally supplied

   to

   ,

   data

   ,

   value

   , or prebuilt transaction object.
6. Run approval and simulation gates. Apply policy checks and dry-run with

   cast call

   (see

   reference/simulation.md

   ). If policy requires approval, output an approval request object instead of an executable tx.
7. Output machine-readable JSON. Emit exactly one object per write: executable tx

   {to, data, value, chainId}

   , an approval request object when policy requires review, or a

   pin_failed

   object when structured atom pinning fails before write generation.

Transitioning from Read to Write

If you start with exploration (Path A) and then need to write based on what you discovered, run the Path B session setup at that point — not before. See the Revalidation Bridge in

reference/graphql-queries.md

Prerequisites

• Wallet infrastructure — a signing mechanism (wallet MCP tool, backend service,

  cast

  with a private key). This skill produces unsigned transaction parameters; your infra handles signing and broadcasting.
• Funded wallet — $TRUST (mainnet) or tTRUST (testnet) on the Intuition L3.
• RPC access — public Intuition RPC endpoints, no API keys required.

Autonomous Mode Policy

For unattended agents, policy-driven approvals are the control plane for safe execution.

• Load policy from

  ./.intuition/autonomous-policy.json

  or the path in

  INTUITION_POLICY_PATH

  .
• If no policy file is available, use

  manual-review

  mode.
• Policy gates run before signing and broadcasting. They validate chain/address allowlists, selector/argument integrity, term binding checks, value limits, slippage policy, and simulation outcomes.
• Runtime enforcement is executed by the validator:

  scripts/validate-tx-from-intent.js

  (see

  reference/runtime-enforcement.md

  ).
• Use the blocking wrapper

  scripts/enforce-and-sign.js

  as signer entrypoint so signing never executes on fail/approval-required outcomes.

Read

reference/autonomous-policy.md

Output Contract

For executable writes, output one unsigned transaction object:

{
  "to": "0x<multivault-address>",
  "data": "0x<calldata>",
  "value": "<wei-as-base-10-string>",
  "chainId": "<chain-id-as-base-10-string>"
}

For approval-required writes, output one approval request object:

{
  "status": "approval_required",
  "operation": "<operation-name>",
  "reason": "<policy reason>",
  "proposedTx": {
    "to": "0x<multivault-address>",
    "data": "0x<calldata>",
    "value": "<wei-as-base-10-string>",
    "chainId": "<chain-id-as-base-10-string>"
  }
}

For pin failures (IPFS pinning failed before on-chain write), output one pin failure object:

{
  "status": "pin_failed",
  "operation": "createAtoms",
  "reason": "<specific failure reason>",
  "entity": "<name of the entity that failed to pin>"
}

The JSON object is the complete machine-mode response.

Skill Contents

Read these files when performing the corresponding operation:

reference/                        (Path A: read-only — load these directly)
  graphql-queries.md              GraphQL discovery — search, traverse, aggregate, graph landscape
  reading-state.md                On-chain reads and session setup (Path B prerequisite)
  schemas.md                      Schema types, IPFS pinning, and structured atom creation
  workflows.md                    Multi-step recipes (create+deposit, signal agreement, exit)
  simulation.md                   Dry run / simulate writes before executing
  autonomous-policy.md            Approval modes, policy schema, and execution gates
  runtime-enforcement.md          Blocking validator flow before signing

operations/                       (Path B: writes — run session setup first)
  create-atoms.md                 Create atom vaults from URI data
  create-triples.md               Create triple vaults linking three atoms
  deposit.md                      Deposit $TRUST into a vault, mint shares
  redeem.md                       Redeem shares from a vault, receive $TRUST
  batch-deposit.md                Deposit into multiple vaults in one transaction
  batch-redeem.md                 Redeem from multiple vaults in one transaction

Protocol Model

• Atoms represent any concept — a person, URL, address, label. Created by encoding a URI as bytes. Each has a deterministic

  bytes32

  ID and a vault. For rich metadata (name, description, image, URL), pin structured data to IPFS first and encode the

  ipfs://

  URI — see

  reference/schemas.md

  .
• Triples are claims linking three atoms:

  (subject, predicate, object)

  — e.g.,

  (Alice, trusts, Bob)

  . Each has a vault and an automatic counter-triple vault.
• Vaults back every atom and triple. Depositing $TRUST mints shares on a bonding curve. Depositing into a triple signals agreement; depositing into its counter-triple signals disagreement.

Native token: $TRUST (mainnet) / tTRUST (testnet), 18 decimals. All

msg.value

Network Selection

On first invocation, ask the user which network to use:

Which network?
1. Intuition Mainnet  -- chain 1155
2. Intuition Testnet  -- chain 13579

Network Configuration

0x6E35cF57A41fA15eA0EaE9C33e751b01A784Fe7e

https://rpc.intuition.systems/http

https://mainnet.intuition.sh/v1/graphql

0x2Ece8D4dEdcB9918A398528f3fa4688b1d2CAB91

https://testnet.rpc.intuition.systems/http

https://testnet.intuition.sh/v1/graphql

Use the selected row for all operations in the session. Switch with

--chain mainnet

--chain testnet

Network Characteristics

Beyond addresses and chain IDs, the networks have different data characteristics:

Use testnet for development and testing writes. Use mainnet for production exploration and meaningful attestations.

Custom Chain Definition (viem)

Intuition runs on an L3 not indexed by Etherscan. Agents must define the chain manually:

import { defineChain } from 'viem'

// Mainnet
export const intuitionMainnet = defineChain({
  id: 1155,
  name: 'Intuition',
  nativeCurrency: { decimals: 18, name: 'Intuition', symbol: 'TRUST' },
  rpcUrls: { default: { http: ['https://rpc.intuition.systems/http'] } },
  blockExplorers: { default: { name: 'Intuition Explorer', url: 'https://explorer.intuition.systems' } },
})

// Testnet
export const intuitionTestnet = defineChain({
  id: 13579,
  name: 'Intuition Testnet',
  nativeCurrency: { decimals: 18, name: 'Test Trust', symbol: 'tTRUST' },
  rpcUrls: { default: { http: ['https://testnet.rpc.intuition.systems/http'] } },
  blockExplorers: { default: { name: 'Intuition Testnet Explorer', url: 'https://testnet.explorer.intuition.systems' } },
})

ABI Fragments

Human-readable fragments for

parseAbi()

Important: Term IDs are bytes32

All vault/atom/triple IDs (

termId

atomId

tripleId

bytes32

Read Functions

const readAbi = parseAbi([
  // Cost queries (call BEFORE creating atoms/triples)
  'function getAtomCost() view returns (uint256)',
  'function getTripleCost() view returns (uint256)',

  // Atom/Triple data
  'function atom(bytes32 atomId) view returns (bytes)',
  'function getAtom(bytes32 atomId) view returns (bytes)',
  'function isAtom(bytes32 atomId) view returns (bool)',
  'function isTriple(bytes32 id) view returns (bool)',
  'function isCounterTriple(bytes32 termId) view returns (bool)',
  'function isTermCreated(bytes32 id) view returns (bool)',
  'function getTriple(bytes32 tripleId) view returns (bytes32, bytes32, bytes32)',
  'function triple(bytes32 tripleId) view returns (bytes32, bytes32, bytes32)',
  'function getCounterIdFromTripleId(bytes32 tripleId) pure returns (bytes32)',
  'function getInverseTripleId(bytes32 tripleId) view returns (bytes32)',
  'function getVaultType(bytes32 termId) view returns (uint8)',

  // ID calculation
  'function calculateAtomId(bytes data) pure returns (bytes32)',
  'function calculateTripleId(bytes32 subjectId, bytes32 predicateId, bytes32 objectId) pure returns (bytes32)',
  'function calculateCounterTripleId(bytes32 subjectId, bytes32 predicateId, bytes32 objectId) pure returns (bytes32)',

  // Vault state
  'function getVault(bytes32 termId, uint256 curveId) view returns (uint256 totalAssets, uint256 totalShares)',
  'function getShares(address account, bytes32 termId, uint256 curveId) view returns (uint256)',
  'function maxRedeem(address sender, bytes32 termId, uint256 curveId) view returns (uint256)',
  'function currentSharePrice(bytes32 termId, uint256 curveId) view returns (uint256)',
  'function convertToShares(bytes32 termId, uint256 curveId, uint256 assets) view returns (uint256)',
  'function convertToAssets(bytes32 termId, uint256 curveId, uint256 shares) view returns (uint256)',

  // Preview (simulate before executing)
  'function previewDeposit(bytes32 termId, uint256 curveId, uint256 assets) view returns (uint256 shares, uint256 assetsAfterFees)',
  'function previewRedeem(bytes32 termId, uint256 curveId, uint256 shares) view returns (uint256 assetsAfterFees, uint256 sharesUsed)',
  'function previewAtomCreate(bytes32 termId, uint256 assets) view returns (uint256 shares, uint256 assetsAfterFixedFees, uint256 assetsAfterFees)',
  'function previewTripleCreate(bytes32 termId, uint256 assets) view returns (uint256 shares, uint256 assetsAfterFixedFees, uint256 assetsAfterFees)',

  // Fee queries
  'function protocolFeeAmount(uint256 assets) view returns (uint256)',
  'function entryFeeAmount(uint256 assets) view returns (uint256)',
  'function exitFeeAmount(uint256 assets) view returns (uint256)',
  'function atomDepositFractionAmount(uint256 assets) view returns (uint256)',

  // Config
  'function getGeneralConfig() view returns ((address admin, address protocolMultisig, uint256 feeDenominator, address trustBonding, uint256 minDeposit, uint256 minShare, uint256 atomDataMaxLength, uint256 feeThreshold))',
  'function getAtomConfig() view returns ((uint256 atomCreationProtocolFee, uint256 atomWalletDepositFee))',
  'function getTripleConfig() view returns ((uint256 tripleCreationProtocolFee, uint256 atomDepositFractionForTriple))',
  'function getBondingCurveConfig() view returns ((address registry, uint256 defaultCurveId))',
  'function getVaultFees() view returns ((uint256 entryFee, uint256 exitFee, uint256 protocolFee))',
])

Write Functions

const writeAbi = parseAbi([
  // Atom creation (batch only)
  'function createAtoms(bytes[] atomDatas, uint256[] assets) payable returns (bytes32[])',

  // Triple creation (batch only)
  'function createTriples(bytes32[] subjectIds, bytes32[] predicateIds, bytes32[] objectIds, uint256[] assets) payable returns (bytes32[])',

  // Single deposit/redeem
  'function deposit(address receiver, bytes32 termId, uint256 curveId, uint256 minShares) payable returns (uint256)',
  'function redeem(address receiver, bytes32 termId, uint256 curveId, uint256 shares, uint256 minAssets) returns (uint256)',

  // Batch deposit/redeem
  'function depositBatch(address receiver, bytes32[] termIds, uint256[] curveIds, uint256[] assets, uint256[] minShares) payable returns (uint256[])',
  'function redeemBatch(address receiver, bytes32[] termIds, uint256[] curveIds, uint256[] shares, uint256[] minAssets) returns (uint256[])',

  // Approvals
  'function approve(address sender, uint8 approvalType)',

  // Atom wallet
  'function computeAtomWalletAddr(bytes32 atomId) view returns (address)',
  'function claimAtomWalletDepositFees(bytes32 atomId)',
])

Core Concepts

Atoms: URI to bytes Encoding

Atoms are created from arbitrary bytes. All atoms are pinned to IPFS except blockchain addresses (CAIP-10). This matches the Intuition Portal's creation flow.

import { stringToHex } from 'viem'

// All entities, concepts, predicates, labels — pin to IPFS first
// See reference/schemas.md for the full pin flow
const atomData = stringToHex('ipfs://bafy...')  // URI from pin mutation

// Blockchain address (CAIP-10) — no IPFS needed
const atomData = stringToHex('caip10:eip155:1:0x1234...abcd')

# cast equivalents
ATOM_DATA=$(cast --from-utf8 "ipfs://bafy...")                    # after pinning
ATOM_DATA=$(cast --from-utf8 "caip10:eip155:1:0x1234...abcd")    # CAIP-10 address

Pin everything — including predicates (

"implements"

"trusts"

"AI Agent Framework"

operations/create-atoms.md

The atom's

bytes32

calculateAtomId(bytes)

MultiVault_AtomExists

isTermCreated(calculateAtomId(data))

createAtoms

Triples: Three Atom IDs

A triple links three existing atoms:

(subject, predicate, object)

Finding predicate atoms: Do not hardcode predicate atom IDs. Canonical predicates are IPFS-pinned atoms — their IDs depend on the pinned URI, not a plain string. Query the graph to find existing predicates by label:

query FindPredicate($label: String!) {
  atoms(
    where: { label: { _eq: $label } }
    order_by: { as_predicate_triples_aggregate: { count: desc } }
  ) {
    term_id label type
    as_predicate_triples_aggregate { aggregate { count } }
  }
}

Results include all atom types, ordered by usage count. Interpret them as follows:

• Non-TextObject result exists — use it. Any type other than

  TextObject

  (e.g.,

  Thing

  ,

  Person

  ,

  Organization

  ,

  Keywords

  ,

  FollowAction

  ) is a canonical atom with structured metadata.
• Only TextObject results exist — the label is in use as a legacy plain-string predicate. Do not reuse the TextObject atom. Instead, create a pinned replacement via

  reference/schemas.md

  (use

  pinThing

  with the predicate label as

  name

  ). The new pinned version becomes the canonical predicate going forward.
• No results — the predicate doesn't exist yet. Create it by pinning via

  reference/schemas.md

  .

Vaults: Shares Model

Every atom and triple has a vault. Depositing $TRUST mints shares on a bonding curve. The

curveId

Always query the default curve ID first:

cast call $MULTIVAULT "getBondingCurveConfig()((address,uint256))" --rpc-url $RPC
# Returns (registryAddress, defaultCurveId) -- use the second value

On mainnet the default is currently

1

getBondingCurveConfig()

defaultCurveId

Fees: Always Preview First

Multiple fee layers apply to deposits: protocol fee, entry fee, atom wallet deposit fee (for atoms), and atom deposit fraction (for triples). Always call

previewDeposit

previewAtomCreate

previewTripleCreate

Assets Array in Creation

When creating atoms/triples, each

assets[i]

getAtomCost()

getTripleCost()

msg.value

sum(assets[])

assets[i]

Write Operations

To perform a write, open the corresponding operation file and follow its steps exactly. Each file provides: prerequisites to query, encoding pattern (cast + viem), value calculation, and strict JSON output contract.

operations/create-atoms.md

reference/schemas.md

msg.value = sum(assets[])

assets[i] >= atomCost

operations/create-triples.md

msg.value = sum(assets[])

assets[i] >= tripleCost

operations/deposit.md

msg.value = deposit amount

operations/redeem.md

value = 0

operations/batch-deposit.md

msg.value = sum(assets)

operations/batch-redeem.md

value = 0

For on-chain reads (costs, existence, vault state, previews), follow

reference/reading-state.md

reference/graphql-queries.md

reference/workflows.md

reference/simulation.md

Protocol Invariants

These facts govern all Intuition transactions. Reference them when encoding operations.

1. Term IDs are bytes32 -- All vault, atom, and triple IDs are

   bytes32

   — deterministic hashes computed from atom data or triple components.

2. Creation is batch-only -- Use

   createAtoms()

   and

   createTriples()

   with arrays. Single-item creation uses single-element arrays.

3. curveId is required --

   deposit

   and

   redeem

   require a

   curveId

   parameter. Query

   getBondingCurveConfig()

   once per session. The mainnet default is

   1

   (linear curve).

4. Slippage parameters --

   deposit

   accepts

   minShares

   ,

   redeem

   accepts

   minAssets

   . Use

   previewDeposit

   /

   previewRedeem

   to calculate these. Set to

   0

   to skip protection.

5. Receiver semantics are explicit --

   deposit

   /

   redeem

   operations require a non-zero receiver address. When receiver is omitted in intent, use the signer address.

6. Atom data is hex-encoded bytes -- Use

   stringToHex(uri)

   in viem,

   cast --from-utf8 "uri"

   in foundry. The input is an IPFS URI from pinning (

   ipfs://bafy...

   ) or a CAIP-10 URI for blockchain addresses (

   caip10:eip155:{chainId}:{address}

   ).

7. msg.value is a separate transaction field -- The $TRUST sent with the transaction is the

   value

   field, separate from the encoded

   data

   .

8. Payable functions --

   createAtoms

   ,

   createTriples

   ,

   deposit

   ,

   depositBatch

   require $TRUST as

   msg.value

   .

   redeem

   and

   redeemBatch

   are non-payable (

   value = 0

   ).

9. Creation assets[] is the full payment -- Each

   assets[i]

   must be >= creation cost.

   msg.value

   must exactly equal

   sum(assets[])

   . The creation cost is deducted per item; the remainder deposits into the vault.

10. Custom chain definition required -- Intuition L3 (chain 1155/13579) requires

    defineChain()

    in viem. See Custom Chain Definition above.

11. Creation returns bytes32[] --

    createAtoms

    and

    createTriples

    return

    bytes32[]

    — hashes of the input data.

12. Counter-triples are automatic -- Creating a triple also creates its counter-triple vault. Deposit into the counter-triple to signal disagreement.

13. Separate preview functions for creation and deposit -- Use

    previewAtomCreate

    /

    previewTripleCreate

    when creating. Use

    previewDeposit

    for existing vaults. Fee calculations differ.

Error Patterns

MultiVault_InsufficientBalance

msg.value

sum(assets[])

msg.value

MultiVault_InsufficientAssets

assets[i]

assets[i]

getAtomCost()

getTripleCost()

MultiVault_AtomExists

isTermCreated(calculateAtomId(data))

MultiVault_TripleExists

isTermCreated(calculateTripleId(...))

MultiVault_TermDoesNotExist

createAtoms

MultiVault_ArraysNotSameLength

MultiVault_InvalidArrayLength

TRUST Token

parseEther('0.5')

Contract Source

• V2 contracts: https://github.com/0xIntuition/intuition-v2/tree/main/contracts/core
• Interface:

  src/interfaces/IMultiVault.sol

  and

  src/interfaces/IMultiVaultCore.sol

• Block explorer (mainnet): https://intuition.calderaexplorer.xyz
• SDK (reference): https://github.com/0xIntuition/intuition-ts