1. Intuition Network
A custom Layer 3 blockchain settling to Base, built on Arbitrum Orbit with AnyTrust DA for scale and low-cost interactions — about 10,000 cheaper and 100x faster than most of the competition.2. Intuition Protocol
The rules and logic for how knowledge is represented and monetized. The Protocol is the grammar of programmable attestations — a universal language for expressing who said what, about what, at what time, and with what conviction.3. Rust Subnet
A high-performance indexing and query layer built for developers. The Subnet turns raw attestations into actionable intelligence, powering AI agents, decentralized apps, and enterprise systems. --- ## Core Primitives Intuition is built on three simple primitives that combine to create powerful applications: ### Atoms Unique, persistent identifiers for any concept or entity—people, objects, ideas, smart contracts, or raw data. Think of them as the "nodes" in the knowledge graph or the "words" in the Intuition dictionary. - Anyone can create them permissionlessly - Each has an on-chain vault with bonding curves - Economics drive convergence to canonical versions ### Triples Structured relationships in the form [Subject]-[Predicate]-[Object]. These are the "sentences" of the Intuition system, connecting atoms to express facts, claims, and relationships. - Example: `[Vitalik] - [founderOf] - [Ethereum]` - Link three atom IDs to make assertions - Support both positive and negative attestations - Form the "edges" connecting nodes in the graph - Triples can be nested as atoms in other triples ### Signals Tokenized stakes that weight attestations with economic confidence. Signals show "who is attesting to what" and create economic skin in the game. - Represents community trust through staking - Shows collective confidence levels - Creates economic incentives for accuracy - Provides the "weights" in the knowledge graph **[→ Deep dive into Primitives](/docs/intuition-concepts/primitives)** --- ## How It Fits Together Together, they form the rails of a programmable knowledge economy where: --- ## Why This Matters for Developers Building on Intuition means you don't have to reinvent trust, identity, or data models from scratch. Attestations and identifiers give you:💾 Memory
Agents and apps don't start from zero; they inherit context.🔐 Trust
Every claim is signed, staked, and auditable.🎯 Alignment
Incentives built into the data layer itself.🌐 Portability
Your users' context and reputation follow them across apps.🔌 Interoperability
Shared identifiers and standards mean your app plugs into a larger ecosystem by default. Intuition provides the foundation. You build the apps, agents, and experiences that bring it to life. --- title: "Use Cases" description: "Discover how to build amazing applications with Intuition's decentralized knowledge graph - from list curation to verification and fraud protection" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/getting-started/use-cases" --- # Use Cases  This article outlines use cases that take advantage of Intuition's unique knowledge graph and claim infrastructure. There are many more ways to use Intuition (and we would love to see what you come up with!), but here are some ideas to get you started. ## List Curation & Ranking Systems Intuition can be used to create permissionless, community-curated ranked lists and registries. Anyone can create a list that groups together identities with a common claim about them (such as sharing a common tag, use case, purpose, etc). The list can then be curated by the original uploader and anyone else on the platform by adding additional identities or supporting/opposing each item with a financial stake to change it’s ranking. Users can filter and sort results from that list to find what matters to them. They can see the global list of everything added by anyone, just their own contributions, or items vetted by people they follow or trust. - Web3 Ecosystem: Curate trusted smart contracts, addresses, DeFi protocols, memecoins, NFT communities, and Web3 games based on reputation formed by on-chain metadata and user attestations - AI resources: Find and orchestrate trusted AI agents based on rich metadata and on-chain reputation, know the best models based on community feedback, and train AI with validated data sources and efficiently structured knowledge - Entertainment and media: Rank top and emerging music, movies, news sources, podcasts, sports teams, and more based on staked TRUST “support” positions and attestations from users you follow who share your taste - Data and Research: Find the most reliable data sources and reports based on peer review attestations and supporting positions from trusted colleagues - Consumer Products: Find and help rank top-rated consumer products, applications, and more - Product improvements: Have your community share their top feature requests and bugs to fix so you can prioritize which to tackle first - Travel: Uncover popular travel destinations through collective recommendations ## Verification and Fraud Protection Intuition helps trusted experts flag potentially dangerous websites, smart contracts, products, and more using structure claims to help everyday consumers stay safe. - Decentralized Information Validation: Engage a distributed community to verify and endorse the accuracy and authenticity of any data (e.g. smart contracts, information, packaged good supply chains, images, news, etc) - Fraud Detection and Alerts: Engage a worldwide team of incentivized auditors and moderators to report potentially dangerous or fraudulent activities, including crypto scams and malicious AI agents, and alert users when they are about to engage with a threat on the Web. - Curator & Auditor Recognition: Rank individuals—whether they're auditing contracts or curating news—based on their proficiency, accuracy, and community credibility. This ensures a transparent trajectory in both contract auditing and news curation. ## Community-Owned Social Platforms Intuition creates on-chain decentralized identities for people and concepts, and allows any account to make verifiable claims about themselves and others. These primitives can form the basis of powerful social networks, driven by publicly visible and searchable graphs of verified connections and attestations. - Portable On-Chain Identity: Each person on the social network gets a self-sovereign identity, allowing them to own their verifiable data (claims by and about them) and make it portable to any other system, instead of being locked into keeping their data with a single platform. - Advanced Signaling and Verification: Transform traditional up-vote/down-vote and/or likes/dislikes into attestations, offering richer feedback and community insights for debates, conversations, and more. - Member Credibility: Promote trust between distributed community members by highlighting verifiable achievements and certifications, providing community reputation attestations and scores, and more. ## Incentivized Ratings and Referrals Using claims, Intuition can provide on-chain ratings and referrals for media, software, travel destinations, and more. Tastemakers can earn money by being early to place support or oppose financial positions to rate promising items they know their communities will find relevant, capturing fees when subsequent reviewers follow suite. - Attestation-Backed Ratings: Transition from simplistic star ratings to attestations, ensuring each review reflects a more comprehensive and verified experience - Transparent Reviewer Profiles: Utilize attestations to validate reviewer authenticity, experience, and expertise, giving more weight to trusted community members' feedback - Community-Driven Trustworthiness: Allow community members to vouch for or against reviews, enhancing the credibility of feedback and reducing the impact of fraudulent reviews. - Simple Referrals: Businesses can request referrals for their offerings from tastemakers, rewarding those tastemakers financially when others catch on, place their own support position, and make the offering go viral. - Review Aggregation & Insights: Harness the power of structured attestation data to generate summary insights from reviews, helping customers make informed decisions faster and helping businesses understand their strengths and areas of improvement. ## Q&A Platforms Question and answer platforms can yield results from structured knowledge sharing, support/oppose positions on claims, and in-depth identity and reputation for each participant. - Claiming Expertise: Users self-attest areas of knowledge, setting the stage for their contributions and peer review. - Community Attestations: Peer validation of answers allows for real-time quality & sentiment checks. - Verification: Answer validation is reinforced by the wisdom of the crowd, balancing answer credibility. - Reputation Building: Continuous positive attestations lead to a trustworthy reputation score, distinguishing genuine experts from the crowd. ## Reputation scores Intuition facilitates both financial and social signals about identities and claims to help people construct their own sense of reputation for things they encounter. From these primitives, third-party developers can construct reputation scores that make this contextual trust easy to interpret. - Trustworthiness Index: Evaluate entities based on their past track record and overarching conduct within different contexts. - Platform Credibility: Prioritize platforms known for specific things - such as undercollateralized lending - spotlighting those with a track record for precise credit evaluations. - Credit Scoring: Harness the transparency of blockchain for decentralized credit scores, presenting a holistic and immutable snapshot of an individual's or entity's lending history. - Lending Confidence: Empower lenders to confidently engage in undercollateralized loans, underpinned by clear and transparent Web3 credit reputation metrics. ## Oracles Decentralized applications can use on-chain claims made by trusted accounts managed by people or secure bots (or a combination of these entities and their collective opinions) in Intuition to trigger other on-chain events. - Consensus Result Extraction: Derive a data beacon or collective answer based on the weight and credibility of aggregated attestations, and use it to provide triggers for smart contract logic. - Censorship Resistance: Define trust so that any entity that fits the criteria can support dApps with reliable information to guide actions, free of censorship. ## Business, Employment & Consulting Platforms Companies and consultancies, as well as the people who work for them, can use decentralized identifiers and claims made by those that have done business with them to determine whether their potential collaborators are trustworthy and fit for the task at hand. - Professional Credibility: Evaluate the authenticity of individuals, organizations, and services based on proven credentials. - Expertise Showcase: Verify the skills, experiences, and specializations of consultants to match with appropriate projects or clients. - Credential-Based Products: Incorporate platforms enhanced with reputation systems to assess credibility and reliability in the consulting domain. - Collaborative Experiences: Attest to the quality and outcome of consulting projects and share insights from fruitful partnerships. - Consultation Metrics: Utilize advanced tools and analytics to measure the impact and effectiveness of consulting services offered. - Transparent Feedback Loop: Allow clients to provide feedback on consulting services, ensuring continual improvement and trust-building in the community. ## Verified Voting Verified community members can create proposals as identities, then allow other community members to make claims about those proposals with evidence, support or oppose the proposals, or rank the proposals in a list to signal what the community should handle next. - Identity Assurance: Implement mechanisms to ensure that each vote is tied to a verified identity, eliminating duplicate votes and ensuring transparency. - Hackathon Judging: Accurately capture and reflect community votes to determine hackathon winners and associated projects, fostering a fair competitive environment. - DAO Proposal Voting: Promote permissionless executions grounded in community consensus and sentiment, enabling decentralized decisions with integrity. - Vote Attestation: Allow members to vouch for or challenge voting results, adding an additional layer of community-backed verification to the process. - Reputation-Based Voting Power: Adjust the weight of votes based on the track record and credibility of members, ensuring experienced voices have a significant say. ## Trading Knowledge Intuition can help surface knowledgable market voices, and even gather intelligence on bullish opportunities through curated lists of assets with support or oppose positions to signal their attractiveness as an investment. - Evaluate and ascertain the credibility of traders or investors based on historical decisions, profitability, and ethical behavior. - Assess and rank trading/investment platforms using community-driven reviews, transaction success rates, and security protocols. - Determine the trustworthiness of diverse investment assets through community ratings, feedback, and historical performance benchmarks. ## Verifiable Predictions, Claims & Forecasting Intuition can help people signal what they believe will happen next or be advantageous in the future, making early verifiable claims about events or opportunities and putting financial positions behind them to communicate their certainty. These claims and commitments can be used by others who need to decide what’s most likely to happen in the future, like a perpetual, non-resolving prediction market. - Know Your Futurist: Elevate trusted voices whose foresight consistently aligns with events and who posses domain knowledge, emphasizing their expertise within the community. - Provable Track Records: Assess past predictions in the form of claims from thought leaders in Intuition, including any financial stake they placed on the prediction, to determine their likelihood of correctly predicting future events. --- title: "Why Intuition?" description: "Understanding the trust crisis Intuition addresses and our mission to rebuild the internet's trust architecture" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/getting-started/why-intuition" --- # Why Intuition? > **Every interaction online is an attestation.** > A review or a purchase on Amazon, a comment on Reddit, the watching of a show on Netflix, a retweet, a LinkedIn endorsement, a 'follow', a bookmark, the ordering of an Uber, even a "like" — all are forms of attestations: claims made by things about things. But attestations today are fragmented, unverifiable, and platform-locked. They don't move with you. They don't carry weight. They aren't semantically structured and unambiguously consumable by machines. **Intuition changes that.** We've rebuilt attestations as first-class, tokenized primitives — structured, portable, and economically backed. _Attestations on steroids._ ## Decentralizing Information with Attestations **Blockchains decentralized money. Intuition decentralizes information — by offering next-generation attestation infrastructure.** An attestation in Intuition isn't just a line of text. It's: - **Verifiable** — signed and attributable - **Ownable** — belongs to the creator, not a platform - **Discoverable** — structured as a Triple (subject → predicate → object) - **Valuable** — backed by economic incentives through bonding curves This turns the messy stream of human expression into a global knowledge substrate that's actually useful to developers, communities, and AI agents. ## Information Finance: Attestations as Assets Intuition pioneers **Information Finance (InfoFi)**: the idea that information can be valued and exchanged just like money. - **Ideas become assets** — an attestation isn't just data, it's collateralized - **Reputation becomes capital** — your attestations are your portfolio of credibility - **Knowledge flows freely** — attestations aren't siloed; they're cross-platform and composable Attestations are no longer passive byproducts of online activity — they're programmable building blocks for apps and agents. ## The $200 Trillion Problem The global knowledge economy is worth over **$200 trillion**, yet: - Most of its value is created by individuals - Less than 1% of that value flows back to the creators - Instead, tech monopolies capture and silo it **The result:** broken rails, misinformation, and AI systems consuming oceans of low-quality data without provenance. Attestations are the missing rails. When data becomes signed, tokenized, and portable, it allows value to flow back to contributors and trust to flow into the systems that need it most. ## Rebuilding the Rails of Knowledge Intuition makes attestations first-class protocol objects. That means: - **Facts, claims, and perspectives** are all structured as attestations - **Credibility is collateralized** — good attestations earn rewards; bad ones cost you stake - **Distribution is programmatic** — attestations move frictionlessly across apps, chains, and agents Think of it as the Ethereum moment for knowledge: where attestations flow as freely as tokens, powering new classes of decentralized infrastructure. ## Programmatic Monetization and Distribution Attestations aren't just portable — they're **monetizable**. With Intuition, every attestation can plug into programmatic distribution rails: - Censorship-resistant search and discovery - Verifiable knowledge bases - Open data marketplaces - Training sets for AI agents Each attestation carries weight, liquidity, and discoverability, ensuring no single platform can gate what's visible or valuable. ## From Information → Intuition Why does this matter? Because **raw information without provenance is noise.** Attestations, structured and economically backed, create a higher-resolution understanding of the world. They transform scattered data into collective intuition — fueling smarter AI, safer markets, and more confident human decision-making. ## Reviving the Semantic Web with Crypto-Economic Consensus The Semantic Web failed because it required global consensus on standards without incentives to achieve it. Different organizations created competing schemas, vocabularies fragmented, and there was no mechanism to converge on shared identifiers. **Intuition solves this with crypto-economics** — the same force that achieves distributed consensus in blockchains now drives semantic standardization: - **Incentivized identifiers** — stake on canonical IDs for entities, creating economic pressure toward convergence - **Market-driven standards** — the most useful data structures attract the most stake and become de facto standards - **Emergent interoperability** — economic incentives naturally align participants toward compatible schemas - **Consensus through collateralization** — disagreements resolve through staking, not committees Where the Semantic Web asked the world to voluntarily agree on standards, Intuition makes consensus profitable. Attestations become the economic glue that binds distributed actors to shared semantic structures. ## For Developers If you're building applications that need identity, reputation, trust, or structured data — Intuition isn't optional. It's infrastructure.Data Layer Included
Inherit identity, reputation, and trust systems. No rebuilding from scratch.Network Effects
Every attestation joins a liquid ecosystem. Your users' data compounds globally.Economic Rails
Bonding curves, staking, and rewards built in. Monetization without infrastructure.AI-Ready
Verifiable context for AI agents. Training data with provenance.Great DX
TypeScript SDK, GraphQL API, comprehensive docs. Ship fast.Avoid Silos
Don't rebuild isolated systems. Plug into shared infrastructure. --- ## For Users Your data has value. Your opinions matter. Your reputation should be yours.Own Your Data
Your attestations belong to you, not platforms. Take them anywhere.Earn Value
Get rewarded when your contributions prove useful to others.Trust What You See
Know who said what, with what stake behind it.One Identity
Portable reputation across all apps and chains.Shape Knowledge
Contribute to humanity's shared knowledge graph. --- ## How It Works: Skin in the Game On Intuition, every attestation has consequences: - **Publish a useful attestation** → earn reputation and rewards - **Publish misinformation** → lose your stake and credibility - **Signal strong conviction** → stake more on your attestation - **Build trust** → accumulate a reputation that travels with you - **Use consensus identifiers** → earn more by aligning with the network - **Fork data structures** → lose money by fragmenting liquidity This flips today's internet incentives: no longer "reward the loudest," but reward the most credible and interoperable attestations. ### The Fork Choice Rule for Data Just like blockchains have fork choice rules that determine the canonical chain, Intuition creates economic pressure toward canonical identifiers and data structures. **When you use consensus identifiers, you tap into existing liquidity pools and network effects. When you create competing forks, you isolate yourself economically.** **Example:** Imagine two identifiers for "Ethereum": - **Identifier A**: Used by 10,000 attestations with $1M total stake - **Identifier B**: Used by 50 attestations with $5K total stake If you make an attestation about Ethereum: - Using **Identifier A** → Your attestation joins a liquid market, benefits from network effects, earns higher rewards - Using **Identifier B** → Your attestation is isolated, has minimal visibility, earns negligible rewards The economic incentive is clear: converge on consensus or pay the price. This same dynamic applies to data structures, schemas, and semantic relationships. The network naturally evolves toward maximum interoperability because **consensus literally pays.** ## Digital Sovereignty and Data Ownership **Your attestations are yours.** Not Facebook's, not LinkedIn's, not OpenAI's. - You **own** them - You **control** who can access them - You **capture** the value they generate - They **travel** with you across every app, chain, or agent Attestations become the backbone of digital sovereignty. ## The Trust Layer for AI AI doesn't just need more data — it needs **verifiable attestations about data**: - Who said it - With what reputation - With what conviction Intuition provides the trust graph of attestations. AI systems can finally ground themselves in data with provenance, weights, and economic signals — not just raw text. This makes AI more reliable while ensuring humans share in the value of the knowledge they produce. ## What You Can Build By treating attestations as programmable primitives, you can create: - **Verifiable identity systems** - **Reputation networks** powered by attestations - **Decentralized fact-checking** with stakes - **AI agents** that reason over attestations as context - **Information markets** where attestations themselves are the assets ## Join the Movement Intuition is about reclaiming the internet by giving attestations real weight. Whether you're a developer, researcher, or community builder, your contributions aren't just ephemeral posts — they're portable, valuable attestations that strengthen the global knowledge graph. **Together, we can rebuild the web around truth, attribution, and trust.** --- title: "Choose Appropriate Operators" description: "Use the right comparison operator for the job" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/graphql-api/best-practices/comparison-operators" --- # Choose Appropriate Operators Use the right comparison operator for better performance. ## Anti-Pattern ```graphql # BAD: Using _ilike for exact matches query GetAccount($address: String!) { accounts(where: { id: { _ilike: $address } }) { id label } } ``` ## Best Practice ```graphql # GOOD: Use _eq or primary key lookup query GetAccount($address: String!) { account(id: $address) { id label } } ``` ## Operator Guidelines - **_eq**: Exact matches (fastest) - **_ilike**: Case-insensitive pattern matching (slower) - **_in**: Multiple values - **_gt/_lt**: Comparisons - **Primary key lookup**: Most efficient (when possible) --- title: "Use Database Functions" description: "Leverage backend functions for complex queries" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/graphql-api/best-practices/database-functions" --- # Use Database Functions Use backend functions for complex queries instead of client-side filtering. ## Anti-Pattern ```graphql # BAD: Manual filtering for social queries query GetFollowingManually($address: String!) { my_positions: positions(where: { account_id: { _eq: $address } }) { vault { term { triple { # Complex filtering in application code... } } } } } ``` ## Best Practice ```graphql # GOOD: Using database functions query GetFollowingEfficiently($address: String!) { following(args: { address: $address }) { id label atom { term_id label } } } ``` ## Available Functions - `following`: Get accounts a user follows - `positions_from_following`: Social feed of positions - `search_term`: Semantic search - `signals_from_following`: Activity from followed accounts ## Benefits 1. **Faster execution**: Runs in database 2. **Less data transfer**: Filtered server-side 3. **More maintainable**: Logic in one place --- title: "Error Handling" description: "Handle GraphQL errors gracefully" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/graphql-api/best-practices/error-handling" --- # Error Handling Handle GraphQL errors gracefully in your application. ## Error Structure ```json { "data": null, "errors": [ { "message": "Field 'nonexistent_field' not found in type 'atoms'", "extensions": { "path": "$.selectionSet.atoms.selectionSet.nonexistent_field", "code": "validation-failed" } } ] } ``` ## Error Types - **validation-failed**: Query syntax or schema validation error - **constraint-violation**: Database constraint violated - **unexpected**: Internal server error ## Best Practice ```typescript import { GraphQLClient, ClientError } from 'graphql-request' try { const data = await client.request(query, variables) console.log('Success:', data) } catch (error) { if (error instanceof ClientError) { console.error('GraphQL errors:', error.response.errors) console.error('Status:', error.response.status) } else { console.error('Network error:', error) } } ``` ## Tips 1. **Check errors array**: GraphQL can return partial data with errors 2. **Log error details**: Include query and variables for debugging 3. **Show user-friendly messages**: Don't expose internal errors 4. **Implement retry logic**: For network failures --- title: "Efficient Filtering" description: "Use indexed fields and appropriate operators" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/graphql-api/best-practices/filtering" --- # Efficient Filtering Filter early and use indexed fields for better performance. ## Best Practice ```graphql query GetFilteredAtoms($type: atom_type!, $since: timestamptz!) { atoms( where: { type: { _eq: $type } created_at: { _gte: $since } } limit: 100 ) { term_id label } } ``` ## Indexed Fields These fields have database indexes: - `term_id` (primary key) - `creator_id` - `type` - `created_at` ## Operator Selection - Use `_eq` for exact matches (not `_ilike`) - Use `_ilike` only for pattern matching - Use `_in` for multiple values - Combine filters with `_and` for specificity --- title: "Use Fragments" description: "Reuse field selections with GraphQL fragments" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/graphql-api/best-practices/fragments" --- # Use Fragments Reuse field selections across queries with GraphQL fragments. ## Anti-Pattern ```graphql # BAD: Duplicating field selections query GetTriple($id: String!) { triple(term_id: $id) { subject { term_id label creator { id label } } predicate { term_id label creator { id label } } object { term_id label creator { id label } } } } ``` ## Best Practice ```graphql # GOOD: Using fragments fragment AtomBasics on atoms { term_id label creator { id label } } query GetTriple($id: String!) { triple(term_id: $id) { subject { ...AtomBasics } predicate { ...AtomBasics } object { ...AtomBasics } } } ``` ## Benefits 1. **DRY code**: Define once, use everywhere 2. **Easier maintenance**: Update in one place 3. **Consistent data**: Same fields across queries 4. **Better readability**: Named, semantic units --- title: "Pagination Best Practices" description: "Efficient pagination with limit and offset" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/graphql-api/best-practices/pagination" --- # Pagination Best Practices Always use limit and offset for efficient pagination with consistent ordering. ## Best Practice ```graphql query GetAtomsPage($limit: Int!, $offset: Int!) { total: atoms_aggregate { aggregate { count } } atoms( limit: $limit offset: $offset order_by: { created_at: desc } ) { term_id label } } ``` ## Key Points 1. **Always include order_by** for consistent results 2. **Fetch total count** using aggregates 3. **Use reasonable limits** (10-100 items per page) 4. **Calculate offset** as `(page - 1) * limit` --- title: "Query Performance" description: "Optimize GraphQL query performance" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/graphql-api/best-practices/performance" --- # Query Performance Optimize your GraphQL queries for better performance. ## Performance Checklist ### 1. Use Indexed Fields for Filtering **Indexed fields:** - `term_id` (primary keys) - `creator_id` - `type` - `created_at` - `account_id` ```graphql # GOOD: Filtering by indexed fields query GetAtoms($type: atom_type!, $since: timestamptz!) { atoms( where: { type: { _eq: $type } created_at: { _gte: $since } } ) { term_id label } } ``` ### 2. Request Only Needed Fields ```graphql # GOOD: Minimal field selection query GetAtoms { atoms(limit: 10) { term_id label } } ``` ### 3. Use Aggregates Instead of Fetching All Nodes ```graphql # GOOD: Use aggregates for counts query CountPositions($accountId: String!) { positions_aggregate(where: { account_id: { _eq: $accountId } }) { aggregate { count } } } ``` ### 4. Limit Nested Queries ```graphql # GOOD: Limit depth and breadth query GetAtomWithTriples($id: String!) { atom(term_id: $id) { label as_subject_triples(limit: 10) { predicate { label } object { label } } } } ``` ### 5. Use Primary Key Lookups When Possible ```graphql # GOOD: Direct primary key lookup query GetAtom($id: String!) { atom(term_id: $id) { term_id label } } ``` ### 6. Paginate Large Result Sets ```graphql # GOOD: Always use limit query GetAtoms($limit: Int!, $offset: Int!) { atoms( limit: $limit offset: $offset order_by: { created_at: desc } ) { term_id label } } ``` ### 7. Use Pre-Computed Tables ```graphql # GOOD: Use time-series tables query GetDailyStats($termId: String!, $curveId: numeric!) { share_price_change_stats_daily( where: { term_id: { _eq: $termId } curve_id: { _eq: $curveId } } limit: 30 ) { bucket difference } } ``` ### 8. Leverage Database Functions ```graphql # GOOD: Use backend functions query GetFollowing($address: String!) { following(args: { address: $address }) { id label } } ``` ## Monitoring - Profile query execution time - Monitor response payload sizes - Track cache hit rates - Watch for N+1 query patterns --- title: "Use Pre-Computed Statistics" description: "Leverage time-series tables for analytics" last_updated: "2026-02-19T15:00:01-05:00" source: "https://docs.intuition.systems/docs/graphql-api/best-practices/pre-computed-stats" --- # Use Pre-Computed Statistics Leverage time-series aggregation tables for efficient analytics. ## Anti-Pattern ```graphql # BAD: Computing trends from raw events query GetPriceHistory($termId: String!) { share_price_changes( where: { term_id: { _eq: $termId } } order_by: { updated_at: asc } ) { updated_at share_price total_assets total_shares } } # Then computing daily aggregates in application code ``` ## Best Practice ```graphql # GOOD: Using pre-computed daily statistics query GetDailyPriceStats($termId: String!, $curveId: numeric!) { share_price_change_stats_daily( where: { term_id: { _eq: $termId } curve_id: { _eq: $curveId } } order_by: { bucket: desc } limit: 30 ) { bucket first_share_price last_share_price difference change_count } } ``` ## Available Tables - `share_price_change_stats_hourly/daily/weekly/monthly` - `signal_stats_hourly/daily/monthly` ## Benefits 1. **Faster queries**: Pre-aggregated data 2. **Less computation**: Done server-side 3. **Smaller payloads**: Aggregated vs raw data 4. **Better UX**: Faster dashboard loading --- title: "Request Only Needed Fields" description: "Avoid over-fetching by requesting only required fields" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/graphql-api/best-practices/request-only-needed" --- # Request Only Needed Fields Avoid over-fetching by requesting only the fields you actually need. ## Anti-Pattern ```graphql # BAD: Fetching all fields when you only need a few query GetAtoms { atoms(limit: 10) { term_id data label image emoji type wallet_id block_number created_at transaction_hash creator_id creator { id label image atom_id type } # ... many more fields you don't need } } ``` ## Best Practice ```graphql # GOOD: Request only what you need query GetAtoms { atoms(limit: 10) { term_id label image } } ``` ## Benefits 1. **Faster queries**: Less data to fetch and serialize 2. **Reduced bandwidth**: Smaller response payloads 3. **Lower memory usage**: Less data to process client-side 4. **Better caching**: Smaller cache footprints ## Tips - Start minimal and add fields as needed - Remove unused fields from queries - Use fragments for commonly requested field sets - Profile queries to identify over-fetching --- title: "Subscriptions vs Polling" description: "When to use subscriptions vs polling" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/graphql-api/best-practices/subscriptions-vs-polling" --- # Subscriptions vs Polling Choose the right approach for your data update needs. ## Use Subscriptions When - Building real-time dashboards - Monitoring live protocol activity - Data changes frequently (multiple times per minute) - User expects immediate updates - Creating notification systems **Example:** ```graphql subscription WatchMyPositions($cursor: [positions_stream_cursor_input]!) { positions_stream(cursor: $cursor, batch_size: 10) { id shares vault { current_share_price } } } ``` ## Use Polling When - Data updates infrequently (e.g., daily statistics) - Real-time updates aren't critical for UX - Minimizing server connections is important - Building static reports or analytics **Example:** ```graphql query GetStats { stats { total_accounts total_atoms total_triples } } # Poll every 30 seconds or on user action ``` ## Guidelines - **Polling interval**: 30-60 seconds for most use cases - **Subscription batch_size**: 10-50 items - **Handle reconnections**: Store last cursor for resumability --- title: "Use Variables" description: "Always use variables for dynamic values" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/graphql-api/best-practices/variables" --- # Use Variables Always use variables for dynamic values instead of hardcoding. ## Anti-Pattern ```graphql # BAD: Hardcoding values query { atoms(where: { type: { _eq: Person } }) { term_id label } } ``` ## Best Practice ```graphql # GOOD: Using variables query GetAtomsByType($type: atom_type!) { atoms(where: { type: { _eq: $type } }) { term_id label } } ``` **Variables:** ```json { "type": "Person" } ``` ## Benefits 1. **Reusability**: Same query, different values 2. **Type safety**: GraphQL validates variable types 3. **Security**: Prevents injection attacks 4. **Caching**: Better query plan caching --- title: "Custom Queries" description: "Common GraphQL query examples and patterns for the Intuition API" last_updated: "2026-02-28T21:52:51-05:00" source: "https://docs.intuition.systems/docs/graphql-api/custom-queries" --- # Custom Queries This page provides practical examples of common GraphQL queries for the Intuition API. ## Best Practices 1. **Use Fragments**: Create reusable fragments for common fields 2. **Optimize Queries**: Only request the fields you need 3. **Handle Errors**: Always implement proper error handling 4. **Cache Strategically**: Use React Query's caching capabilities 5. **Type Safety**: Leverage generated types for better development experience ## Basic Queries ### Fetching a Single Atom Use the primary key lookup for fetching a single atom by its `term_id`: ```graphql query GetAtom($term_id: String!) { atom(term_id: $term_id) { term_id label image type created_at creator { id label } value { thing { name description url } person { name description url } organization { name description url } } } } ``` ### Fetching Triples Query triples with Hasura's `where` filtering: ```graphql query GetTriples($subjectId: String, $predicateLabel: String, $limit: Int = 20) { triples( where: { subject_id: { _eq: $subjectId } predicate: { label: { _ilike: $predicateLabel } } } order_by: { created_at: desc } limit: $limit ) { term_id subject { term_id label } predicate { term_id label } object { term_id label } created_at } } ``` ### Fetching Signals Query signal events for a specific atom or account: ```graphql query GetSignals($accountId: String!, $limit: Int = 20) { signals( where: { account_id: { _eq: $accountId } } order_by: { created_at: desc } limit: $limit ) { id delta atom_id triple_id created_at account { label } } } ``` ## Advanced Queries ### Search Use the `search_term` database function for text search: ```graphql query SearchAtoms($query: String!, $limit: Int = 20) { search_term(args: { query: $query }, limit: $limit) { id type atom { label image creator { id label } } } } ``` ### Pagination Hasura uses offset-based pagination with `limit` and `offset`: ```graphql query GetAtomsPaginated($limit: Int!, $offset: Int!) { atoms_aggregate { aggregate { count } } atoms( limit: $limit offset: $offset order_by: { created_at: desc } ) { term_id label image type created_at } } ``` ## React Query Hooks ### Using Generated Hooks ```tsx import { useGetAtomQuery } from '@0xintuition/graphql' function AtomViewer({ atomId }: { atomId: string }) { const { data, isLoading, error } = useGetAtomQuery({ variables: { termId: atomId } }) if (isLoading) returnLoading...
if (error) return Error: {error.message}
return (
{data?.atom?.label}
Type: {data?.atom?.type}
Triples ({triples?.triples?.length || 0})
{triples?.triples?.map(triple => (
{triple.subject.label} - {triple.predicate.label} - {triple.object.label}
))}
Loading...
if (error) return Error: {error.message}
return {/* Render stats data */}
}
```
```tsx
import { useAtomsQuery, useTriplesQuery, useUserPositionsQuery } from '@0xintuition/graphql'
function MyComponent() {
// Query atoms
const { data: atoms, isLoading: atomsLoading } = useAtomsQuery({
variables: { limit: 10 }
})
// Query triples
const { data: triples, isLoading: triplesLoading } = useTriplesQuery({
variables: { limit: 10 }
})
// Query user positions
const { data: positions } = useUserPositionsQuery({
variables: { userAddress: '0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6' }
})
if (atomsLoading || triplesLoading) {
return Loading...
}
return (
Atoms ({atoms?.atoms?.length || 0})
{atoms?.atoms?.map(atom => (
{atom.label} - {atom.type}
))}
Triples ({triples?.triples?.length || 0})
{triples?.triples?.map(triple => (
{triple.subject.label} - {triple.predicate.label} - {triple.object.label}
))}
Get by ID
Search & Filter
### AtomsGet by ID
Search & Filter
### ClaimsGet by ID
Search & Filter
### EventsGet by ID
Search & Filter
### FollowsGet by ID
Search & Filter
### ListsGet by ID
Search & Filter
### PointsGet by ID
Search & Filter
### PositionsGet by ID
Search & Filter
### SignalsGet by ID
Search & Filter
### StatsGet
Search & Filter
### TagsGet by ID
Search & Filter
### TriplesGet by ID
Search & Filter
### VaultsGet by ID
Search & Filter
These hooks are generated via GraphQL Code Generator and may expand over time as new documents are added. See the package source below for the current and authoritative list. ## Source Code The GraphQL package source code is available on GitHub: [`intuition-ts/packages/graphql`](https://github.com/0xIntuition/intuition-ts/tree/main/packages/graphql) ## Related Resources - [GraphQL Code Generator](https://the-guild.dev/graphql/codegen) - [React Query Documentation](https://tanstack.com/query) --- title: "Overview" description: "Introduction to the Intuition GraphQL API and its main features" last_updated: "2026-02-11T14:23:51-05:00" source: "https://docs.intuition.systems/docs/graphql-api/overview" --- # Overview # GraphQL API Overview Intuition provides GraphQL APIs for querying its knowledge graph in a convenient and versatile way. **Available endpoints**Intuition mainnet
```text https://mainnet.intuition.sh/v1/graphql ``` target="_blank" rel="noreferrer" Try on GraphQL ExplorerIntuition testnet
```text https://testnet.intuition.sh/v1/graphql ``` target="_blank" rel="noreferrer" Try on GraphQL Explorer Alternatively, you can import these URLs from the GraphQL package: ```ts import { API_URL_PROD, API_URL_DEV } from '@0xintuition/graphql' ``` If this is your first time using GraphQL, you can learn more at [graphql.org](https://graphql.org/). There are a few ways to get started with this GraphQL API, depending on the level of abstraction and customization you require :SDK
Integrate with Intuition smart contracts using our TypeScript SDK.Custom Queries
Create bespoke GraphQL queries for your specific use case. ### GraphQL PackageInstall it with NPM
Install and use the NPM package with ready-made React Query hooks.Use it as a GraphQL Generator
Use the GraphQL package to generate your own queries and mutations. ## See GraphQL in Action Check out these complete tutorials using the GraphQL API: - **[Finding Top Dapps](/docs/tutorials/queries/finding-top-dapps-on-coinbase)** - Query and rank decentralized applications by market cap - **[Building Activity Feeds](/docs/tutorials/queries/building-user-activity-feeds)** - Create real-time user activity streams - **[Discovering Trusted Accounts](/docs/tutorials/queries/discovering-most-trusted-accounts)** - Build trust graphs and find reliable accounts - **[Finding Related Claims](/docs/tutorials/queries/finding-related-claims)** - Traverse the knowledge graph to find connections [More tutorials →](/docs/tutorials/overview) ## Interactive Playground Try the Intuition GraphQL API straight from your browser! The playground below connects to the live testnet endpoint and allows you to explore the knowledge graph in real time. --- title: "Following Query" description: "Query following relationships in the social graph" last_updated: "2026-02-28T21:52:51-05:00" source: "https://docs.intuition.systems/docs/graphql-api/queries/accounts/following" --- # Following Query Query the social graph to find who an account follows and who follows them. ## Query Structure ```graphql query GetFollowing( $account_id: String! $limit: Int $offset: Int ) { following( where: { follower_id: { _eq: $account_id } } limit: $limit offset: $offset ) { id label image } following_aggregate(where: { follower_id: { _eq: $account_id } }) { aggregate { count } } } ``` ## Variables ```json { "account_id": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045", "limit": 20, "offset": 0 } ``` ## Response Fields | Field | Type | Description | |-------|------|-------------| | `id` | `String` | Account address | | `label` | `String` | Human-readable name | | `image` | `String` | Profile image URL | ## Expected Response ```json { "data": { "following": [ { "id": "0x123...", "follower": { "label": "vitalik.eth", "image": "ipfs://Qm..." }, "following": { "label": "alice.eth", "image": "ipfs://Qm..." } } ], "following_aggregate": { "aggregate": { "count": 150 } } } } ``` ## Interactive Example id: 'who-follows', title: 'Who Account Follows', query: `query GetFollowing($account_id: String!, $limit: Int!) { following( where: { follower_id: { _eq: $account_id } } limit: $limit ) { id label image following_aggregate(where: { follower_id: { _eq: $account_id } }) { aggregate { count }`, variables: { account_id: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045', limit: 10 }, id: 'followers', title: 'Account Followers', query: `query GetFollowers($account_id: String!, $limit: Int!) { following( where: { following_id: { _eq: $account_id } } limit: $limit ) { id label image following_aggregate(where: { following_id: { _eq: $account_id } }) { aggregate { count }`, variables: { account_id: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045', limit: 10 }, id: 'mutual-follows', title: 'Check Mutual Follow', query: `query CheckMutualFollow($account_a: String!, $account_b: String!) { a_follows_b: following(where: { follower_id: { _eq: $account_a } following_id: { _eq: $account_b } }) { id b_follows_a: following(where: { follower_id: { _eq: $account_b } following_id: { _eq: $account_a } }) { id }`, variables: { account_a: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045', account_b: '0xabc...' ]; ## Use Cases ### Following List Get list of accounts a user follows: ```typescript async function getFollowing(accountId: string, options: { limit?: number offset?: number } = {}) { const query = ` query GetFollowing($account_id: String!, $limit: Int!, $offset: Int!) { following( where: { follower_id: { _eq: $account_id } } limit: $limit offset: $offset ) { id label image } following_aggregate(where: { follower_id: { _eq: $account_id } }) { aggregate { count } } } ` const data = await client.request(query, { account_id: accountId, limit: options.limit || 20, offset: options.offset || 0 }) return { accounts: data.following, total: data.following_aggregate.aggregate.count } } ``` ### Followers List Get accounts that follow a user: ```typescript async function getFollowers(accountId: string) { const query = ` query GetFollowers($account_id: String!) { following( where: { following_id: { _eq: $account_id } } ) { id label image } following_aggregate(where: { following_id: { _eq: $account_id } }) { aggregate { count } } } ` const data = await client.request(query, { account_id: accountId }) return { followers: data.following, count: data.following_aggregate.aggregate.count } } ``` ### Check if Following Check if one account follows another: ```typescript async function isFollowing( followerId: string, followingId: string ): Promise{count} {tab}
{loading ? (-
{accounts.map(account => (
-
Popular in Your Network
{grouped.map(({ atom, holders, totalShares }) => (
{holders.slice(0, 3).map(h => (
} "{h.label}")
))}
{holders.length > 3 && (
+{holders.length - 3} more
)}
{account.image && (
})
)}
)
}
```
### Check Account Existence
```typescript
async function accountExists(address: string): Promise{account.label || truncateAddress(account.id)}
{account.type} {account.id}
setQuery(e.target.value)}
/>
)
}
```
## Related
- [Search Term](./search-term) - Global search
- [Following](/docs/graphql-api/queries/accounts/following) - Following relationships
---
title: "Search Positions"
description: "Search positions on a specific subject"
last_updated: "2026-02-28T21:52:51-05:00"
source: "https://docs.intuition.systems/docs/graphql-api/queries/search/search-positions"
---
# Search Positions
# Search Positions on Subject
Search for positions (stakes) related to a specific subject. This function takes an array of addresses and a JSONB search fields object to filter positions.
## Query Structure
```graphql
query SearchPositionsOnSubject(
$addresses: _text!
$searchFields: jsonb!
$limit: Int
) {
search_positions_on_subject(
args: {
addresses: $addresses
search_fields: $searchFields
}
limit: $limit
order_by: { shares: desc }
) {
id
account_id
account {
label
image
}
shares
created_at
vault {
term_id
term {
triple {
predicate { label }
object { label }
}
}
}
}
}
```
## Variables
| Variable | Type | Required | Description |
|----------|------|----------|-------------|
| `addresses` | `_text` | Yes | PostgreSQL text array of account addresses to search |
| `search_fields` | `jsonb` | Yes | JSONB object specifying search criteria |
| `limit` | `Int` | No | Maximum results |
```json
{
"addresses": "{0xd8da6bf26964af9d7eed9e03e53415d37aa96045}",
"searchFields": {},
"limit": 20
}
```
The `addresses` parameter uses PostgreSQL's `_text` array format: `{addr1,addr2}` (curly braces, comma-separated, no quotes within the braces).
## Response Fields
The function returns position rows, so all position fields are available:
| Field | Type | Description |
|-------|------|-------------|
| `id` | `String` | Position identifier |
| `account_id` | `String` | Account holding position |
| `account` | `accounts` | Account details (relationship) |
| `shares` | `numeric` | Shares held |
| `created_at` | `timestamptz` | Position creation time |
| `vault` | `vaults` | Associated vault (relationship) |
## Use Cases
### Find Who Believes Something
See all positions from specific accounts:
```typescript
async function getPositionsForAccounts(addresses: string[]) {
const query = `
query GetPositions($addresses: _text!, $searchFields: jsonb!) {
search_positions_on_subject(
args: {
addresses: $addresses
search_fields: $searchFields
}
order_by: { shares: desc }
limit: 50
) {
account {
id
label
image
}
vault {
term {
triple {
predicate { label }
object { label }
}
}
}
shares
}
}
`
// Format as PostgreSQL text array
const pgArray = `{${addresses.join(',')}}`
const data = await client.request(query, {
addresses: pgArray,
searchFields: {}
})
return data.search_positions_on_subject
}
```
## Best Practices
1. **Order by shares** - Show most-supported positions first
2. **Group results** - Aggregate positions by claim
3. **Show supporter count** - Indicate social proof
4. **Link to profiles** - Make supporters clickable
## Related
- [Search Term](./search-term) - Search atoms by text
- [User Positions](/docs/graphql-api/queries/vaults/user-positions) - Account position queries
---
title: "Search Term"
description: "Search atoms and terms by text"
last_updated: "2026-02-28T21:52:51-05:00"
source: "https://docs.intuition.systems/docs/graphql-api/queries/search/search-term"
---
# Search Term
Search for atoms by their label or data content.
## Query Structure
```graphql
query SearchTerm(
$query: String!
$limit: Int
$offset: Int
) {
search_term(
args: { query: $query }
limit: $limit
offset: $offset
) {
id
type
created_at
atom {
label
image
creator {
id
label
image
}
}
}
}
```
## Variables
| Variable | Type | Required | Description |
|----------|------|----------|-------------|
| `query` | `String` | Yes | Search query text |
| `limit` | `Int` | No | Maximum results (default: 20) |
| `offset` | `Int` | No | Pagination offset |
```json
{
"query": "ethereum",
"limit": 10,
"offset": 0
}
```
## Response Fields
The function returns `terms` rows. Metadata fields like `label`, `image`, and `creator` are accessed via the `atom` relationship:
| Field | Type | Description |
|-------|------|-------------|
| `id` | `String` | Unique term identifier |
| `type` | `String` | Term type |
| `created_at` | `DateTime` | Creation timestamp |
| `atom` | `atoms` | Related atom with metadata (label, image, creator) |
| `atom.label` | `String` | Human-readable label |
| `atom.image` | `String` | Image URL (IPFS) |
| `atom.creator` | `accounts` | Creator account (id, label, image) |
## Expected Response
```json
{
"data": {
"search_term": [
{
"id": "0x57d94c116a33bb460428eced262b7ae2ec6f865e7aceef6357cec3d034e8ea21",
"type": "Thing",
"created_at": "2024-01-01T00:00:00Z",
"atom": {
"label": "Ethereum",
"image": "ipfs://QmXnnyufdzAWL5CqZ2RnSNgPbvCc1ALT73s6epPrRnZ1Xy",
"creator": {
"id": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
"label": "vitalik.eth",
"image": "ipfs://Qm..."
}
}
}
]
}
}
```
## Interactive Example
id: 'basic-search',
title: 'Basic Search',
query: `query SearchTerm($query: String!, $limit: Int!) {
search_term(args: { query: $query }, limit: $limit) {
id
type
atom {
label
image
}`,
variables: {
query: 'ethereum',
limit: 10
},
id: 'search-with-creator',
title: 'Search with Creator Info',
query: `query SearchTerm($query: String!, $limit: Int!) {
search_term(args: { query: $query }, limit: $limit) {
id
type
created_at
atom {
label
image
creator {
id
label
image
}`,
variables: {
query: 'bitcoin',
limit: 5
];
## Use Cases
### Search Autocomplete
Implement search-as-you-type:
```typescript
import { debounce } from 'lodash'
async function searchAtoms(searchQuery: string, limit: number = 10) {
if (searchQuery.length < 2) return []
const gqlQuery = `
query SearchTerm($query: String!, $limit: Int!) {
search_term(args: { query: $query }, limit: $limit) {
id
type
atom {
label
image
}
}
}
`
const data = await client.request(gqlQuery, { query: searchQuery, limit })
return data.search_term
}
// Debounced version for autocomplete
const debouncedSearch = debounce(searchAtoms, 300)
```
### Filter by Type
Search and filter by atom type:
```typescript
async function searchByType(
searchQuery: string,
type: 'Thing' | 'Person' | 'Organization'
) {
const gqlQuery = `
query SearchByType($query: String!, $type: String!) {
search_term(
args: { query: $query }
where: { type: { _eq: $type } }
limit: 20
) {
id
type
atom {
label
image
}
}
}
`
return client.request(gqlQuery, { query: searchQuery, type })
}
```
## Search Tips
1. **Minimum length**: Search works best with 2+ characters
2. **Case insensitive**: "ethereum" and "Ethereum" return same results
3. **Partial matching**: "eth" matches "Ethereum"
4. **Combine with filters**: Add `where` clause for type/creator filtering
## Best Practices
1. **Debounce input** - Wait 300ms after typing before searching
2. **Show loading state** - Indicate when search is in progress
3. **Handle empty results** - Show helpful message when no matches
4. **Limit results** - Start with 5-10 results, load more on demand
## Related
- [Search from Following](./search-from-following) - Social search
- [Search Positions](./search-positions) - Position search
- [List Atoms](/docs/graphql-api/queries/atoms/list-filter) - Filter-based atom queries
---
title: "Aggregate Signals"
description: "Aggregate statistics for signals"
last_updated: "2026-02-28T21:52:51-05:00"
source: "https://docs.intuition.systems/docs/graphql-api/queries/signals/aggregate-signals"
---
# Aggregate Signals
Query aggregate statistics for signals including counts, sums, and averages.
## Query Structure
```graphql
query GetSignalsAggregate($where: signals_bool_exp) {
signals_aggregate(where: $where) {
aggregate {
count
sum {
delta
}
avg {
delta
}
max {
delta
created_at
}
min {
delta
created_at
}
}
}
}
```
## Variables
```json
{
"where": {
"created_at": { "_gte": "2024-01-01T00:00:00Z" }
}
}
```
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `count` | `Int` | Total number of signals |
| `sum.delta` | `String` | Total amount in wei |
| `avg.delta` | `Float` | Average amount |
| `max.delta` | `String` | Maximum amount |
| `max.created_at` | `DateTime` | Most recent signal |
| `min.delta` | `String` | Minimum amount |
| `min.created_at` | `DateTime` | Oldest signal |
## Expected Response
```json
{
"data": {
"signals_aggregate": {
"aggregate": {
"count": 1500,
"sum": {
"delta": "150000000000000000000"
},
"avg": {
"delta": 100000000000000000
},
"max": {
"delta": "10000000000000000000",
"created_at": "2024-01-15T23:59:59Z"
},
"min": {
"delta": "1000000000000000",
"created_at": "2024-01-01T00:00:01Z"
}
}
}
}
}
```
## Interactive Example
id: 'total-stats',
title: 'Total Signal Statistics',
query: `query GetSignalsAggregate {
signals_aggregate {
aggregate {
count
sum {
delta
}`,
variables: {}
},
id: 'deposits-stats',
title: 'Deposit Statistics',
query: `query GetDepositsAggregate {
signals_aggregate(where: { deposit_id: { _is_null: false } }) {
aggregate {
count
sum {
delta
avg {
delta
}`,
variables: {}
},
id: 'account-stats',
title: 'Account Signal Statistics',
query: `query GetAccountStats($account_id: String!) {
deposits: signals_aggregate(where: {
account_id: { _eq: $account_id }
deposit_id: { _is_null: false }
}) {
aggregate {
count
sum { delta }
redemptions: signals_aggregate(where: {
account_id: { _eq: $account_id }
redemption_id: { _is_null: false }
}) {
aggregate {
count
sum { delta }
}`,
variables: {
account_id: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045'
];
## Use Cases
### Protocol Dashboard
Display overall protocol statistics:
```typescript
async function getProtocolStats() {
const query = `
query GetProtocolStats {
deposits: signals_aggregate(where: { deposit_id: { _is_null: false } }) {
aggregate {
count
sum { delta }
}
}
redemptions: signals_aggregate(where: { redemption_id: { _is_null: false } }) {
aggregate {
count
sum { delta }
}
}
total: signals_aggregate {
aggregate {
count
}
}
}
`
const data = await client.request(query)
return {
totalSignals: data.total.aggregate.count,
totalDeposits: data.deposits.aggregate.count,
totalDepositVolume: data.deposits.aggregate.sum.delta,
totalRedemptions: data.redemptions.aggregate.count,
totalRedemptionVolume: data.redemptions.aggregate.sum.delta
}
}
```
### Account Statistics
Get deposit/redemption stats for an account:
```typescript
async function getAccountStats(accountId: string) {
const query = `
query GetAccountStats($account_id: String!) {
deposits: signals_aggregate(where: {
account_id: { _eq: $account_id }
deposit_id: { _is_null: false }
}) {
aggregate {
count
sum { delta }
avg { delta }
}
}
redemptions: signals_aggregate(where: {
account_id: { _eq: $account_id }
redemption_id: { _is_null: false }
}) {
aggregate {
count
sum { delta }
}
}
}
`
const data = await client.request(query, { account_id: accountId })
const depositSum = BigInt(data.deposits.aggregate.sum?.delta || '0')
const redemptionSum = BigInt(data.redemptions.aggregate.sum?.delta || '0')
return {
depositCount: data.deposits.aggregate.count,
depositVolume: depositSum,
redemptionCount: data.redemptions.aggregate.count,
redemptionVolume: redemptionSum,
netFlow: depositSum - redemptionSum
}
}
```
### Time-Based Analysis
Analyze signals over time periods:
```typescript
async function getMonthlyStats(year: number, month: number) {
const startDate = new Date(year, month - 1, 1)
const endDate = new Date(year, month, 0, 23, 59, 59)
const query = `
query GetMonthlyStats($start: timestamptz!, $end: timestamptz!) {
signals_aggregate(where: {
created_at: { _gte: $start, _lte: $end }
}) {
aggregate {
count
sum { delta }
}
}
deposits: signals_aggregate(where: {
created_at: { _gte: $start, _lte: $end }
deposit_id: { _is_null: false }
}) {
aggregate {
count
sum { delta }
}
}
}
`
return client.request(query, {
start: startDate.toISOString(),
end: endDate.toISOString()
})
}
```
## Grouping with nodes
For grouped aggregates, use the `nodes` field:
```graphql
query GetSignalsByAtom {
signals_aggregate(
where: { atom_id: { _is_null: false } }
distinct_on: atom_id
) {
nodes {
atom_id
term {
atom {
label
}
}
}
aggregate {
count
}
}
}
```
## Best Practices
1. **Use filters** - Narrow down aggregates for performance
2. **Handle big numbers** - Use BigInt for wei values
3. **Cache results** - Aggregate queries can be expensive
4. **Combine queries** - Fetch multiple aggregates in one request
## Related
- [List Signals](./list-signals) - Individual signals
- [Signals from Following](./signals-from-following) - Social signals
- [Protocol Stats](/docs/graphql-api/queries/stats/protocol-stats) - Overall statistics
---
title: "List Signals"
description: "Query signals (deposits/redemptions) with filtering and pagination"
last_updated: "2026-02-28T21:52:51-05:00"
source: "https://docs.intuition.systems/docs/graphql-api/queries/signals/list-signals"
---
# List Signals
Query deposit and redemption signals with rich filtering, sorting, and pagination capabilities.
## Query Structure
```graphql
query GetSignals(
$where: signals_bool_exp
$order_by: [signals_order_by!]
$limit: Int
$offset: Int
) {
signals(
where: $where
order_by: $order_by
limit: $limit
offset: $offset
) {
id
delta
account_id
account {
id
label
image
}
atom_id
term {
atom {
term_id
label
image
}
}
triple_id
block_number
created_at
transaction_hash
}
}
```
## Variables
| Variable | Type | Description |
|----------|------|-------------|
| `where` | `signals_bool_exp` | Filter conditions |
| `order_by` | `[signals_order_by!]` | Sort order |
| `limit` | `Int` | Maximum results (default: 20) |
| `offset` | `Int` | Pagination offset |
```json
{
"order_by": [{ "created_at": "desc" }],
"limit": 20,
"offset": 0
}
```
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `id` | `String` | Unique signal identifier |
| `delta` | `String` | Amount in wei |
| `account_id` | `String` | Account address |
| `account` | `Account` | Account details with label/image |
| `atom_id` | `String` | Related atom ID (if atom signal) |
| `term` | `Term` | Related term (contains nested `atom` with label/image) |
| `triple_id` | `String` | Related triple ID (if triple signal) |
| `block_number` | `Int` | Block number |
| `created_at` | `DateTime` | Event timestamp |
| `transaction_hash` | `String` | Transaction hash |
## Expected Response
```json
{
"data": {
"signals": [
{
"id": "0x123...-1",
"delta": "1000000000000000000",
"account_id": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
"account": {
"id": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
"label": "vitalik.eth",
"image": "ipfs://Qm..."
},
"atom_id": "0x57d94c116a33bb...",
"term": {
"atom": {
"id": "0x57d94c116a33bb...",
"label": "Ethereum",
"image": "ipfs://Qm..."
}
},
"triple_id": null,
"block_number": 12345678,
"created_at": "2024-01-15T10:30:00Z",
"transaction_hash": "0xabc..."
}
]
}
}
```
## Interactive Example
id: 'recent-signals',
title: 'Recent Signals',
query: `query GetSignals($limit: Int!) {
signals(limit: $limit, order_by: { created_at: desc }) {
id
delta
account {
label
image
term {
atom {
label
created_at
}`,
variables: { limit: 10 }
},
id: 'account-signals',
title: 'Signals by Account',
query: `query GetAccountSignals($account_id: String!, $limit: Int!) {
signals(
where: { account_id: { _eq: $account_id } }
order_by: { created_at: desc }
limit: $limit
) {
id
delta
term {
atom {
label
triple_id
created_at
}`,
variables: {
account_id: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
limit: 20
},
id: 'deposits-only',
title: 'Deposits Only',
query: `query GetDeposits($limit: Int!) {
signals(
order_by: { delta: desc }
limit: $limit
) {
id
delta
account {
label
term {
atom {
label
created_at
}`,
variables: { limit: 10 }
];
## Use Cases
### Activity Feed
Build a real-time activity feed:
```typescript
async function getActivityFeed(limit: number = 50) {
const query = `
query GetActivityFeed($limit: Int!) {
signals(
order_by: { created_at: desc }
limit: $limit
) {
id
delta
account {
id
label
image
}
term {
atom {
label
image
}
}
triple_id
created_at
}
}
`
const data = await client.request(query, { limit })
return data.signals.map(signal => ({
...signal,
message: formatSignalMessage(signal)
}))
}
function formatSignalMessage(signal: Signal): string {
const target = signal.term?.atom?.label ?? `Triple ${signal.triple_id}`
return `${signal.account.label} signaled on ${target}`
}
```
### Account History
Get complete signal history for an account:
```typescript
async function getAccountHistory(
accountId: string,
options: { limit?: number; offset?: number } = {}
) {
const query = `
query GetAccountHistory(
$account_id: String!
$limit: Int!
$offset: Int!
) {
signals(
where: { account_id: { _eq: $account_id } }
order_by: { created_at: desc }
limit: $limit
offset: $offset
) {
id
delta
term {
atom { label }
}
triple_id
created_at
transaction_hash
}
signals_aggregate(where: { account_id: { _eq: $account_id } }) {
aggregate {
count
}
}
}
`
const data = await client.request(query, {
account_id: accountId,
limit: options.limit || 20,
offset: options.offset || 0
})
return {
signals: data.signals,
total: data.signals_aggregate.aggregate.count
}
}
```
### Filter by Date Range
```typescript
async function getSignalsByDateRange(
startDate: Date,
endDate: Date
) {
const query = `
query GetSignalsByDate($start: timestamptz!, $end: timestamptz!) {
signals(
where: {
created_at: { _gte: $start, _lte: $end }
}
order_by: { created_at: desc }
) {
id
delta
account { label }
created_at
}
}
`
return client.request(query, {
start: startDate.toISOString(),
end: endDate.toISOString()
})
}
```
## Filtering Options
### By Amount
```graphql
# Large signals (> 1 ETH)
signals(where: {
delta: { _gt: "1000000000000000000" }
})
```
### By Atom or Triple
```graphql
# Signals for specific atom
signals(where: { atom_id: { _eq: "0x..." } })
# Signals for specific triple
signals(where: { triple_id: { _eq: "0x..." } })
```
## Best Practices
1. **Use pagination** - Always limit results for large datasets
2. **Order by timestamp** - Most recent signals are usually most relevant
3. **Include context** - Fetch account and atom labels for display
4. **Cache appropriately** - Signals are immutable once created
## Related
- [Aggregate Signals](./aggregate-signals) - Signal statistics
- [Signals from Following](./signals-from-following) - Social feed
- [Subscriptions](/docs/graphql-api/subscriptions/overview) - Real-time signals
---
title: "Signals Queries"
description: "Query deposit and redemption signals with rich context"
last_updated: "2026-02-19T15:00:01-05:00"
source: "https://docs.intuition.systems/docs/graphql-api/queries/signals/overview"
---
# Signals Queries
Signals represent deposit and redemption events in the Intuition protocol. Unlike raw blockchain events, signals include enriched context such as account labels, atom metadata, and related positions.
## Available Queries
| Query | Description |
|-------|-------------|
| [`signals`](./list-signals) | Query signals with filtering and pagination |
| [`signals_aggregate`](./aggregate-signals) | Aggregate statistics for signals |
| [`signals_from_following`](./signals-from-following) | Query signals from followed accounts |
## What Are Signals?
Signals are contextual representations of position changes:
- **Deposits**: When an account stakes ETH on an atom or triple
- **Redemptions**: When an account withdraws from a position
Each signal includes:
- The account that made the action
- The target atom or triple
- Amount and shares involved
- Timestamp and block information
- Full context of related entities
## Quick Start
```typescript
import { GraphQLClient } from 'graphql-request'
import { API_URL_PROD } from '@0xintuition/graphql'
const client = new GraphQLClient(API_URL_PROD)
// Get recent signals
const query = `
query GetSignals($limit: Int!) {
signals(limit: $limit, order_by: { block_timestamp: desc }) {
id
signal_type
delta
account {
label
image
}
atom {
label
}
block_timestamp
}
}
`
const data = await client.request(query, { limit: 20 })
```
## Signal Types
| Type | Description |
|------|-------------|
| `Deposit` | Staking ETH on a position |
| `Redemption` | Withdrawing from a position |
## Common Filters
```graphql
# Filter by signal type
signals(where: { signal_type: { _eq: "Deposit" } })
# Filter by account
signals(where: { account_id: { _eq: "0x..." } })
# Filter by atom
signals(where: { atom_id: { _eq: "0x..." } })
# Filter by date range
signals(where: {
block_timestamp: {
_gte: "2024-01-01T00:00:00Z",
_lte: "2024-01-31T23:59:59Z"
}
})
```
## Related Documentation
- [List Signals](./list-signals) - Query signals with filters
- [Aggregate Signals](./aggregate-signals) - Signal statistics
- [Signals from Following](./signals-from-following) - Social signal feed
- [Activity Feed Example](/docs/graphql-api/examples/activity-feed) - Building activity feeds
---
title: "Signals from Following"
description: "Query signals from accounts you follow"
last_updated: "2026-02-28T21:52:51-05:00"
source: "https://docs.intuition.systems/docs/graphql-api/queries/signals/signals-from-following"
---
# Signals from Following
Query signals (deposits and redemptions) from accounts that a specific user follows. This enables building personalized social activity feeds.
## Query Structure
```graphql
query GetSignalsFromFollowing(
$account_id: String!
$limit: Int
$offset: Int
$where: signals_from_following_bool_exp
) {
signals_from_following(
args: { account_id: $account_id }
where: $where
limit: $limit
offset: $offset
order_by: { created_at: desc }
) {
id
delta
account {
id
label
image
}
term {
atom {
term_id
label
image
}
}
triple_id
created_at
}
}
```
## Variables
| Variable | Type | Required | Description |
|----------|------|----------|-------------|
| `account_id` | `String` | Yes | The account whose following list to use |
| `limit` | `Int` | No | Maximum results (default: 20) |
| `offset` | `Int` | No | Pagination offset |
| `where` | `signals_from_following_bool_exp` | No | Additional filters |
```json
{
"account_id": "0xd8da6bf26964af9d7eed9e03e53415d37aa96045",
"limit": 20,
"offset": 0
}
```
## Response Fields
| Field | Type | Description |
|-------|------|-------------|
| `id` | `String` | Signal identifier |
| `delta` | `String` | Amount in wei |
| `account` | `Account` | Account that made the signal |
| `term` | `Term` | Related term (contains nested `atom` with label/image) |
| `triple_id` | `String` | Related triple ID (if triple signal) |
| `created_at` | `DateTime` | Event timestamp |
## Expected Response
```json
{
"data": {
"signals_from_following": [
{
"id": "0x123...-1",
"delta": "1000000000000000000",
"account": {
"id": "0xabc...",
"label": "alice.eth",
"image": "ipfs://Qm..."
},
"term": {
"atom": {
"id": "0x57d94c...",
"label": "Ethereum",
"image": "ipfs://Qm..."
}
},
"triple_id": null,
"created_at": "2024-01-15T10:30:00Z"
}
]
}
}
```
## Interactive Example
id: 'following-signals',
title: 'Signals from Following',
query: `query GetSignalsFromFollowing($account_id: String!, $limit: Int!) {
signals_from_following(
args: { account_id: $account_id }
limit: $limit
order_by: { created_at: desc }
) {
id
delta
account {
label
image
term {
atom {
label
created_at
}`,
variables: {
account_id: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
limit: 10
},
id: 'deposits-from-following',
title: 'Deposits from Following',
query: `query GetDepositsFromFollowing($account_id: String!, $limit: Int!) {
signals_from_following(
args: { account_id: $account_id }
where: { deposit_id: { _is_null: false } }
limit: $limit
order_by: { delta: desc }
) {
id
delta
account {
label
term {
atom {
label
created_at
}`,
variables: {
account_id: '0xd8da6bf26964af9d7eed9e03e53415d37aa96045',
limit: 10
];
## Use Cases
### Social Activity Feed
Build a personalized feed showing activity from followed accounts:
```typescript
async function getSocialFeed(
accountId: string,
options: { limit?: number; offset?: number } = {}
) {
const query = `
query GetSocialFeed(
$account_id: String!
$limit: Int!
$offset: Int!
) {
signals_from_following(
args: { account_id: $account_id }
limit: $limit
offset: $offset
order_by: { created_at: desc }
) {
id
delta
account {
id
label
image
}
term {
atom {
label
image
}
}
triple_id
created_at
}
}
`
const data = await client.request(query, {
account_id: accountId,
limit: options.limit || 20,
offset: options.offset || 0
})
return data.signals_from_following.map(signal => ({
...signal,
formattedMessage: formatActivityMessage(signal)
}))
}
function formatActivityMessage(signal: Signal): string {
const target = signal.term?.atom?.label ?? `Triple ${signal.triple_id}`
const amount = formatEther(signal.delta)
return `${signal.account.label} signaled on ${target} (${amount} ETH)`
}
```
### React Social Feed Component
```tsx
function SocialFeed({ accountId }: { accountId: string }) {
const [offset, setOffset] = useState(0)
const LIMIT = 20
const { data, loading, fetchMore } = useQuery(GET_SIGNALS_FROM_FOLLOWING, {
variables: {
account_id: accountId,
limit: LIMIT,
offset: 0
}
})
if (loading && !data) return From Your Network
{data?.search_term_from_following.map(term => (Activity from People You Follow
{signals.length === 0 ? (No recent activity from people you follow
) : ( <> {signals.map(signal => (
{signal.account.label}
signaled on
{signal.term?.atom?.label ?? `Triple ${signal.triple_id}`}
{formatEther(signal.delta)} ETH
Loading...
if (error) return Error: {error.message}
return (
{data?.atoms.map(atom => (
))}
)
}
```
---
*For more examples and advanced patterns, check out our [GraphQL SDK](https://github.com/0xIntuition/intuition-ts/tree/main/packages/graphql) and [Example Queries](/docs/graphql-api/examples/atom-with-vault) page.*
---
title: "Subscriptions Overview"
description: "Real-time subscriptions with cursor-based streaming"
last_updated: "2026-02-28T21:52:51-05:00"
source: "https://docs.intuition.systems/docs/graphql-api/subscriptions/overview"
---
# Subscriptions Overview
The GraphQL API supports real-time subscriptions for live data updates using cursor-based streaming.
## Basic Subscription Pattern
```graphql
subscription WatchAtoms(
$cursor: [atoms_stream_cursor_input]!
$batchSize: Int!
) {
atoms_stream(
cursor: $cursor
batch_size: $batchSize
) {
term_id
label
created_at
}
}
```
## Variables
```json
{
"cursor": [{
"initial_value": { "created_at": "2024-01-01T00:00:00Z" },
"ordering": "ASC"
}],
"batchSize": 10
}
```
## Cursor Configuration
- **initial_value**: Starting point for the stream
- **ordering**: Sort direction (ASC or DESC)
- **batch_size**: Number of items per batch
## When to Use Subscriptions
**Use subscriptions when:**
- Building real-time dashboards
- Monitoring live protocol activity
- Creating notification systems
- Data changes frequently
**Use polling when:**
- Data updates infrequently
- Real-time updates aren't critical
- Minimizing server connections
## Available Streaming Subscriptions
The API provides streaming subscriptions for all major entities:
### Core Entity Streams
| Subscription | Description |
|--------------|-------------|
| `atoms_stream` | New and updated atoms |
| `triples_stream` | New and updated triples |
| `accounts_stream` | Account updates |
| `positions_stream` | Position changes |
| `vaults_stream` | Vault updates |
### Activity Streams
| Subscription | Description |
|--------------|-------------|
| `signals_stream` | Real-time deposits and redemptions |
| `events_stream` | Raw blockchain events |
| `deposits_stream` | Deposit events |
| `redemptions_stream` | Redemption events |
### Position Tracking Streams
| Subscription | Description |
|--------------|-------------|
| `positions_with_value_stream` | Position updates with computed PnL/value |
| `position_changes_stream` | Individual position change events |
### Price & Stats Streams
| Subscription | Description |
|--------------|-------------|
| `share_price_changes_stream` | Share price updates |
| `chainlink_prices_stream` | Oracle price updates |
| `fee_transfers_stream` | Protocol fee transfers |
| `protocol_fee_accruals_stream` | Protocol fee accrual events |
| `stats_stream` | Protocol statistics updates |
### Time-Series Streams
| Subscription | Description |
|--------------|-------------|
| `share_price_change_stats_hourly_stream` | Hourly price stat updates |
| `share_price_change_stats_daily_stream` | Daily price stat updates |
| `signal_stats_hourly_stream` | Hourly signal stat updates |
| `signal_stats_daily_stream` | Daily signal stat updates |
| `term_total_state_changes_stream` | Term state change updates |
### Graph Structure Streams
| Subscription | Description |
|--------------|-------------|
| `terms_stream` | Term entity updates |
| `triple_terms_stream` | Triple-term relationship updates |
| `triple_vaults_stream` | Triple vault data updates |
| `subject_predicates_stream` | Subject-predicate pair updates |
### Leaderboard Streams
| Subscription | Description |
|--------------|-------------|
| `pnl_leaderboard_entry_stream` | PnL leaderboard updates |
| `pnl_leaderboard_stats_stream` | Leaderboard aggregate stats updates |
| `account_pnl_rank_stream` | Account rank changes |
### Social Streams
| Subscription | Description |
|--------------|-------------|
| `following_stream` | Following relationship changes |
## WebSocket Connection
Connect using a WebSocket client:
```typescript
import { createClient } from 'graphql-ws'
const client = createClient({
url: 'wss://mainnet.intuition.sh/v1/graphql',
})
// Subscribe to signals
const unsubscribe = client.subscribe(
{
query: `
subscription WatchSignals($cursor: [signals_stream_cursor_input]!) {
signals_stream(cursor: $cursor, batch_size: 10) {
id
signal_type
delta
account {
label
}
atom {
label
}
block_timestamp
}
}
`,
variables: {
cursor: [{
initial_value: { block_timestamp: new Date().toISOString() },
ordering: 'ASC'
}]
}
},
{
next: (data) => {
console.log('New signal:', data)
},
error: (error) => {
console.error('Subscription error:', error)
},
complete: () => {
console.log('Subscription complete')
}
}
)
```
## Example: Live Activity Feed
```typescript
import { createClient } from 'graphql-ws'
const client = createClient({
url: 'wss://mainnet.intuition.sh/v1/graphql',
})
function createActivityFeed(onSignal: (signal: Signal) => void) {
return client.subscribe(
{
query: `
subscription LiveActivityFeed($cursor: [signals_stream_cursor_input]!) {
signals_stream(cursor: $cursor, batch_size: 5) {
id
signal_type
delta
account {
label
image
}
atom {
label
image
}
triple {
subject { label }
predicate { label }
object { label }
}
block_timestamp
}
}
`,
variables: {
cursor: [{
initial_value: { block_timestamp: new Date().toISOString() },
ordering: 'ASC'
}]
}
},
{
next: (result) => {
const signals = result.data?.signals_stream || []
signals.forEach(onSignal)
},
error: console.error
}
)
}
```
## Example: Position Price Alerts
```typescript
function watchPositionPrices(
vaultId: string,
onPriceChange: (price: string) => void
) {
return client.subscribe(
{
query: `
subscription WatchVaultPrice(
$vault_id: String!
$cursor: [share_price_changes_stream_cursor_input]!
) {
share_price_changes_stream(
cursor: $cursor
batch_size: 1
where: { vault_id: { _eq: $vault_id } }
) {
share_price
block_timestamp
}
}
`,
variables: {
vault_id: vaultId,
cursor: [{
initial_value: { block_timestamp: new Date().toISOString() },
ordering: 'ASC'
}]
}
},
{
next: (result) => {
const changes = result.data?.share_price_changes_stream || []
changes.forEach(change => onPriceChange(change.share_price))
}
}
)
}
```
## Best Practices
1. **Store last cursor** to resume after disconnection
2. **Use batch_size** to control data flow (10-50)
3. **Filter subscriptions** with where clauses
4. **Handle reconnections** gracefully
5. **Implement exponential backoff** for reconnection attempts
6. **Clean up subscriptions** when components unmount
## Related
- [Real-time Positions](/docs/graphql-api/subscriptions/real-time-positions) - Position updates
- [Price Updates](/docs/graphql-api/subscriptions/price-updates) - Price streaming
- [Subscriptions vs Polling](/docs/graphql-api/best-practices/subscriptions-vs-polling) - When to use each
---
title: "Price Updates"
description: "Subscribe to share price changes in real-time"
last_updated: "2026-02-28T21:52:51-05:00"
source: "https://docs.intuition.systems/docs/graphql-api/subscriptions/price-updates"
---
# Price Updates
# Price Update Subscriptions
Subscribe to real-time share price changes.
## Subscription Structure
```graphql
subscription WatchPriceChanges(
$cursor: [share_price_changes_stream_cursor_input]!
$termId: String!
$batchSize: Int!
) {
share_price_changes_stream(
cursor: $cursor
batch_size: $batchSize
where: { term_id: { _eq: $termId } }
) {
term_id
curve_id
share_price
block_timestamp
block_number
transaction_hash
}
}
```
## Best Practices
1. **Filter by term_id** for specific vault
2. **Use batch_size** to control update frequency
3. **Track price changes** using `share_price` and `block_timestamp`
4. **Update charts** with new data points
---
title: "Real-Time Positions"
description: "Subscribe to position changes in real-time"
last_updated: "2026-01-05T17:16:01-08:00"
source: "https://docs.intuition.systems/docs/graphql-api/subscriptions/real-time-positions"
---
# Real-Time Positions
# Real-Time Position Updates
Subscribe to position changes for live portfolio tracking.
## Subscription Structure
```graphql
subscription WatchPositions(
$cursor: [positions_stream_cursor_input]!
$accountId: String
$batchSize: Int!
) {
positions_stream(
cursor: $cursor
batch_size: $batchSize
where: {
account_id: { _eq: $accountId }
shares: { _gt: "0" }
}
) {
id
shares
vault {
term_id
current_share_price
}
}
}
```
## Best Practices
1. **Filter by account** for user-specific updates
2. **Filter shares > 0** for active positions only
3. **Update UI state** with new data
4. **Resume from last cursor** after disconnection
---
title: "Use Cases"
description: "Real-world examples and step-by-step tutorials to use the Intuition GraphQL API"
last_updated: "2026-01-05T17:16:01-08:00"
source: "https://docs.intuition.systems/docs/graphql-api/use-cases/overview"
---
# Use Cases
# GraphQL API Use Cases
This section contains practical, step-by-step tutorials for common use cases when working with the Intuition GraphQL API. Each example explains how to build real-world applications with our semantic knowledge graph.
## Available Examples
Select a use case above to see detailed step-by-step implementation guides.
{atom.label}
Type: {atom.type}
Finding the Top dApps on Coinbase
Query and rank decentralized applications based on market data.Discovering the Most Trusted Accounts
Find highly trusted accounts based on stake and activity.Building User Activity Feeds
Create personalized activity streams for users.Finding Related Claims
Discover linked triples and relationship patterns. --- title: "Writes" description: "Guide to write data using GraphQL mutations in the Intuition API" last_updated: "2026-02-28T21:52:51-05:00" source: "https://docs.intuition.systems/docs/graphql-api/writes" --- # Writes ## Understanding Mutations vs Smart Contract Operations The Intuition GraphQL API provides mutations for **off-chain operations** like uploading metadata to IPFS. For **on-chain operations** like creating atoms, triples, and positions, you must use the [Intuition SDK](/docs/intuition-sdk/installation-and-setup) or interact directly with the smart contracts. **GraphQL mutations** handle: - Uploading metadata to IPFS (pinThing, pinPerson, pinOrganization) **Smart contract operations** handle: - Creating atoms - Creating triples - Taking positions (depositing/redeeming) - All on-chain state changes Use the [SDK](/docs/intuition-sdk/installation-and-setup) for smart contract interactions. ## Available Mutations ### IPFS & Metadata Mutations | Mutation | Description | Documentation | |----------|-------------|---------------| | `pinThing` | Pin Thing metadata to IPFS | [Pin Thing](/docs/graphql-api/mutations/pin-thing) | | `pinPerson` | Pin Person metadata to IPFS | [Pin Person](/docs/graphql-api/mutations/pin-person) | | `pinOrganization` | Pin Organization metadata to IPFS | [Pin Organization](/docs/graphql-api/mutations/pin-organization) | | `uploadImage` | Upload base64 image to IPFS | [Upload Image](/docs/graphql-api/mutations/images/upload-image) | | `uploadImageFromUrl` | Upload image from URL to IPFS | [Upload from URL](/docs/graphql-api/mutations/images/upload-image-from-url) | | `uploadJsonToIpfs` | Upload JSON metadata to IPFS | [Upload JSON](/docs/graphql-api/mutations/images/upload-json-to-ipfs) | Chart and PnL operations are **queries**, not mutations. See: - [PnL Queries](/docs/graphql-api/queries/pnl/overview) - Profit & Loss tracking - [Chart Queries](/docs/graphql-api/queries/charts/overview) - Chart generation ## Pin Mutations ### pinThing Mutation Pin a Thing entity to IPFS: ```graphql mutation PinThing($thing: PinThingInput!) { pinThing(thing: $thing) { uri } } ``` **Variables:** ```json { "thing": { "name": "Ethereum", "description": "A decentralized blockchain platform", "image": "ipfs://QmXnnyufdzAWL5CqZ2RnSNgPbvCc1ALT73s6epPrRnZ1Xy", "url": "https://ethereum.org" } } ``` ### pinPerson Mutation Pin a Person entity to IPFS: ```graphql mutation PinPerson($person: PinPersonInput!) { pinPerson(person: $person) { uri } } ``` **Variables:** ```json { "person": { "name": "Vitalik Buterin", "description": "Co-founder of Ethereum", "email": "vitalik@ethereum.org", "identifier": "vitalik.eth", "image": "ipfs://Qm...", "url": "https://vitalik.ca" } } ``` ### pinOrganization Mutation Pin an Organization entity to IPFS: ```graphql mutation PinOrganization($organization: PinOrganizationInput!) { pinOrganization(organization: $organization) { uri } } ``` **Variables:** ```json { "organization": { "name": "Ethereum Foundation", "description": "Non-profit supporting Ethereum", "email": "info@ethereum.org", "image": "ipfs://Qm...", "url": "https://ethereum.foundation" } } ``` ## Image Upload Mutations ### uploadImage Upload a base64-encoded image: ```graphql mutation UploadImage($image: UploadImageInput!) { uploadImage(image: $image) { images { url original_url safe score model created_at } } } ``` ### uploadImageFromUrl Upload an image from a URL: ```graphql mutation UploadImageFromUrl($image: UploadImageFromUrlInput!) { uploadImageFromUrl(image: $image) { images { url original_url safe score } } } ``` ### uploadJsonToIpfs Upload JSON metadata: ```graphql mutation UploadJsonToIpfs($json: jsonb!) { uploadJsonToIpfs(json: $json) { hash name size } } ``` ## Complete Workflow Example Here's how to prepare metadata for atom creation: ```typescript import { GraphQLClient } from 'graphql-request' import { API_URL_PROD } from '@0xintuition/graphql' import { createMultivaultClient } from '@0xintuition/sdk' const graphqlClient = new GraphQLClient(API_URL_PROD) // Step 1: Upload image to IPFS (via GraphQL) const imageResult = await graphqlClient.request(` mutation UploadImageFromUrl($image: UploadImageFromUrlInput!) { uploadImageFromUrl(image: $image) { images { url } } } `, { image: { url: 'https://example.com/logo.png' } }) // Step 2: Upload metadata to IPFS (via GraphQL) const metadataResult = await graphqlClient.request(` mutation PinThing($thing: PinThingInput!) { pinThing(thing: $thing) { uri } } `, { thing: { name: 'My Project', description: 'Description of my project', image: imageResult.uploadImageFromUrl.images[0].url, url: 'https://example.com' } }) // Step 3: Create atom on-chain (via SDK) const multivault = createMultivaultClient(walletClient) const atomId = await multivault.createAtom({ uri: metadataResult.pinThing.uri }) ``` ## Best Practices ### 1. Complete Metadata Provide comprehensive metadata for better discoverability: ```typescript const thing = { name: 'Project Name', // Required description: 'Full description', // Recommended image: 'ipfs://...', // Recommended url: 'https://...' // Optional } ``` ### 2. Use IPFS URLs Always reference images using IPFS URLs for permanence: ```typescript // Good - permanent image: 'ipfs://QmXnnyufdzAWL5CqZ2RnSNgPbvCc1ALT73s6epPrRnZ1Xy' // Avoid - may change image: 'https://example.com/image.png' ``` ### 3. Error Handling ```typescript try { const result = await graphqlClient.request(UPLOAD_IMAGE, { image: input }) console.log('Uploaded:', result.uploadImage.images[0].url) } catch (error) { if (error.message.includes('File too large')) { console.error('Image exceeds size limit') } else if (error.message.includes('Invalid')) { console.error('Invalid image format') } } ``` ### 4. Size Limits | Upload Type | Maximum Size | |-------------|--------------| | Image (base64) | 5 MB | | Image from URL | 10 MB | | JSON | 1 MB | ## TypeScript Integration Use the `@0xintuition/graphql` package for type-safe mutations: ```typescript import { usePinThingMutation, useUploadImageFromUrlMutation } from '@0xintuition/graphql' function CreateAtomForm() { const [pinThing] = usePinThingMutation() const [uploadImage] = useUploadImageFromUrlMutation() const handleSubmit = async (data: FormData) => { // Upload image first const imageResult = await uploadImage({ variables: { image: { url: data.imageUrl } } }) // Then pin metadata const thingResult = await pinThing({ variables: { thing: { name: data.name, description: data.description, image: imageResult.data.uploadImageFromUrl.images[0].url, url: data.url } } }) // Use the IPFS URI for atom creation const ipfsUri = thingResult.data.pinThing.uri // ... create atom via SDK } return } ``` ## Related Resources - [PnL Queries](/docs/graphql-api/queries/pnl/overview) - Profit & Loss tracking - [Chart Queries](/docs/graphql-api/queries/charts/overview) - Chart generation - [SDK Documentation](/docs/intuition-sdk/installation-and-setup) - On-chain operations - [GraphQL Reads](/docs/graphql-api/reads) - Query documentation --- title: "Introduction" description: "Introduction to Intuition - the decentralized protocol for building the world's first open, semantic, and token-curated knowledge graph" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs" --- # Introduction **Intuition is a decentralized protocol for building the world's first open, semantic, and token-curated knowledge graph.** It provides the infrastructure for verifiable attestations, portable identity, and trustful interactions at scale—creating a universal data layer that enables information to flow freely across applications, blockchains, and AI agents. ## What is Intuition? While blockchains have historically decentralized money, **Intuition decentralizes information**—specifically its trust, ownership, discoverability, and monetization. By transforming unstructured, siloed data into structured, verifiable, and economically-backed attestations, Intuition creates a Semantic Web of Trust that makes knowledge programmable and interoperable. ### Core Capabilities - **Universal Identity**: Decentralized identifiers (DIDs) for people, concepts, organizations, and AI agents with portable, self-sovereign identity management - **Verifiable Attestations**: Structured claims (subject-predicate-object triples) that are signed, attributable, and economically staked - **Knowledge Graph**: A semantic layer where facts and opinions coexist with verifiable provenance and economic signals - **Economic Incentives**: Bonding curves and cryptoeconomic mechanisms that align participants toward canonical standards and high-quality data ## The Architecture Intuition consists of four foundational layers: ### 1. Intuition Network A custom Layer 3 blockchain settling to Base, built on Arbitrum Orbit with AnyTrust DA for scalability and cost-efficiency—approximately 10,000x cheaper and 100x faster than traditional alternatives. ### 2. Intuition Protocol The rules and primitives for representing, incentivizing, and monetizing knowledge through: - **Atoms**: Unique identifiers for any entity or concept - **Triples**: Structured attestations linking atoms in subject-predicate-object relationships - **Signals**: Economic stakes that weight attestations with conviction and accountability ### 3. Rust Subnet A high-performance indexing and query layer providing real-time APIs and GraphQL endpoints for querying the knowledge graph at scale. ### 4. SDK The developer interface providing TypeScript SDKs, client libraries, and comprehensive developer tools that enable seamless integration with the Intuition stack. The SDK abstracts the complexity of working with the underlying layers, offering type-safe methods for creating atoms, triples, and signals, as well as querying the knowledge graph. ## Why Intuition Matters Current information systems suffer from fragmentation, lack of provenance, misaligned incentives, and centralized control. Intuition addresses these challenges by: - **Making attestations portable**: Your data, identity, and reputation travel with you across platforms - **Establishing provenance**: Every claim is signed, timestamped, and attributable to its source - **Aligning incentives**: Economic mechanisms reward accuracy and discourage misinformation - **Enabling interoperability**: Shared identifiers and standards create a composable knowledge ecosystem - **Empowering creators**: Data contributors own and monetize their attestations rather than enriching platforms ## Use Cases Intuition enables a wide range of applications: - **Decentralized identity and reputation systems** - **Verifiable credentials and attestations** - **AI agents with trusted context and memory** - **Collaborative knowledge curation and fact-checking** - **Information markets and data monetization** - **Cross-platform social graphs and preferences** ## Getting Started Whether you're building applications, contributing data, or exploring the knowledge graph, Intuition provides the tools and infrastructure you need: - **Developers**: Use our SDKs, APIs, and smart contracts to integrate attestations into your applications - **Contributors**: Create and stake attestations to build reputation and earn rewards - **Applications**: Leverage the knowledge graph for trusted context, identity, and data - **AI Systems**: Access verifiable, semantically-structured training data with provenance ## Learn More - [Introduction](/docs/getting-started/overview) — Understand Intuition's vision and the problems it solves - [Quickstart](/docs/quick-start/using-the-sdk) — Get started building with Intuition - [Primitives](/docs/intuition-concepts/primitives) — Deep dive into Atoms, Triples, and Signals - [Developer Tools](/docs/getting-started/developer-stack) — Explore SDKs, APIs, and integration guides - [Network](/docs/intuition-network) — Learn about the Intuition Network architecture - [Economics](/docs/intuition-concepts/economics) — Understand the cryptoeconomic incentive model ## For AI Agents Intuition documentation is optimized for AI agent access: - [llms.txt](/llms.txt) — Concise documentation index for LLM consumption - [llms-full.txt](/llms-full.txt) — Complete documentation in LLM-friendly format --- **Intuition transforms information from passive data into programmable, verifiable, and valuable attestations—building the trust layer for the decentralized web.** --- title: "Create Atom" description: "Learn how to create atoms and manage their associated vaults" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/interaction-guide/create-atom" --- # Create Atom Creating atoms in the Intuition protocol involves interacting with the EthMultiVault contract to establish new entities in the knowledge graph. This process includes creating the atom itself and managing its associated vault. ## Prerequisites This implementation guide assumes that you've completed the setup steps in the [Overview](/docs/interaction-guide/overview) guide. Steps for creating the `createMultivaultContract` and the `publicClient` referenced in this implementation example can be found in the overview. ## Implementation We recommend creating a `multivault.ts` that includes the following atom creation functionality:Core Atom Creation Pattern
{`// Create atom with initial deposit const createAtomConfig = { ...multiVaultContract, functionName: 'createAtom', args: [atomData, initialDeposit], // Execute transaction const hash = await walletClient.writeContract(createAtomConfig) // Wait for confirmation const receipt = await publicClient.waitForTransactionReceipt({ hash })`} ## Complete Example Here is a full example of the atom creation pattern used in the `createAtom` function:Full Implementation
{`export async function createAtom( contract: string, atomData: string, initialDeposit: bigint, walletClient: WalletClient, publicClient: PublicClient ) { const multiVaultContract = createMultiVaultContract(contract) // Prepare atom creation transaction const createAtomConfig = { ...multiVaultContract, functionName: 'createAtom', args: [atomData, initialDeposit], try { // Execute the transaction const hash = await walletClient.writeContract(createAtomConfig) // Wait for transaction confirmation const receipt = await publicClient.waitForTransactionReceipt({ hash }) // Parse events to get atom ID const atomCreatedEvent = receipt.logs.find( log => log.eventName === 'AtomCreated' if (!atomCreatedEvent) { throw new Error('Atom creation event not found') const atomId = atomCreatedEvent.args.atomId const vaultId = atomCreatedEvent.args.vaultId return { success: true, atomId, vaultId, transactionHash: hash, receipt } catch (error) { return { success: false, error: error.message }`} ## Key Functions We use this pattern to create atoms and manage their lifecycle:createAtom
Creates a new atom with optional initial deposit and returns atom/vault IDs.validateAtomData
Validates atom data format and ensures it meets protocol requirements.estimateAtomCost
Estimates the cost of creating an atom including fees and gas costs. ## Usage ExampleBasic Atom Creation
{`// Create a new atom const atomData = "did:ethr:mainnet:0x1234567890abcdef" const initialDeposit = parseEther("0.1") const result = await createAtom( MULTIVAULT_CONTRACT_ADDRESS, atomData, initialDeposit, walletClient, publicClient if (result.success) { console.log({ atomId: result.atomId, vaultId: result.vaultId, transactionHash: result.transactionHash } else { console.error('Atom creation failed:', result.error) }`} ## Error HandlingCommon Error Scenarios
Insufficient Funds
Ensure wallet has sufficient ETH for gas and deposit amount.Invalid Atom Data
Validate atom data format before submission.Network Issues
Handle RPC failures and network connectivity issues. ## Best Practices - Always validate atom data before submission - Estimate costs before executing transactions - Implement proper error handling and user feedback - Use multicall patterns for batch operations - Monitor transaction status and provide confirmation feedback ## Next Steps After creating atoms, explore: - [Create Triple](/docs/interaction-guide/create-triple) - Learn how to create relationships between atoms - [Deposit & Return](/docs/interaction-guide/deposit-return) - Manage vault deposits and withdrawals - [Retrieve Vault Details](/docs/interaction-guide/retrieve-vault-details) - Get comprehensive vault information For a full reference implementation, see the [Intuition TypeScript SDK](https://github.com/0xIntuition/intuition-ts). --- title: "Create Triple" description: "Learn how to create triples and manage their relationships" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/interaction-guide/create-triple" --- # Create Triple Creating triples in the Intuition protocol involves establishing relationships between atoms through the EthMultiVault contract. This process creates both the triple structure and its associated vaults for positive and negative positions. ## Prerequisites This implementation guide assumes that you've completed the setup steps in the [Overview](/docs/interaction-guide/overview) guide and have existing atoms to work with. ## Implementation We recommend creating a `multivault.ts` that includes the following triple creation functionality:Core Triple Creation Pattern
{`// Create triple with initial deposit const createTripleConfig = { ...multiVaultContract, functionName: 'createTriple', args: [subjectId, predicateId, objectId, initialDeposit], // Execute transaction const hash = await walletClient.writeContract(createTripleConfig)`} ## Key Functions We use this pattern to create triples and manage their lifecycle:createTriple
Creates a new triple with optional initial deposit and returns triple/vault IDs.validateTripleComponents
Validates that subject, predicate, and object atoms exist and are valid.estimateTripleCost
Estimates the cost of creating a triple including fees and gas costs. ## Usage ExampleBasic Triple Creation
{`// Create a new triple const subjectId = 123n // Atom ID for "Alice" const predicateId = 456n // Atom ID for "knows" const objectId = 789n // Atom ID for "Bob" const initialDeposit = parseEther("0.1") const result = await createTriple( MULTIVAULT_CONTRACT_ADDRESS, subjectId, predicateId, objectId, initialDeposit, walletClient, publicClient )`} ## Vault Management Each triple creates two vaults:Positive Vault
For users who believe the triple is true. Deposits here signal agreement.Negative Vault
For users who believe the triple is false. Deposits here signal disagreement. ## Best Practices - Validate all atom IDs before creating triples - Check for existing triples to avoid duplicates - Estimate costs before executing transactions - Implement proper error handling and user feedback - Use multicall patterns for batch operations ## Next Steps After creating triples, explore: - [Deposit & Return](/docs/interaction-guide/deposit-return) - Manage vault deposits and withdrawals - [Retrieve Vault Details](/docs/interaction-guide/retrieve-vault-details) - Get comprehensive vault information For a full reference implementation, see the [Intuition TypeScript SDK](https://github.com/0xIntuition/intuition-ts). --- title: "Deposit & Return" description: "Manage deposits and withdrawals from vaults with proper fee handling" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/interaction-guide/deposit-return" --- # Deposit & Return Managing deposits and withdrawals from vaults in the Intuition protocol involves interacting with the EthMultiVault contract to stake and unstake tokens. This process includes proper fee handling and share price calculations. ## Prerequisites This implementation guide assumes that you've completed the setup steps in the [Overview](/docs/interaction-guide/overview) guide. Steps for creating the `createMultivaultContract` and the `publicClient` referenced in this implementation example can be found in the overview. ## Implementation We recommend creating a `multivault.ts` that includes the following deposit and withdrawal functionality:Core Deposit Pattern
{`// Deposit into vault const depositConfig = { ...multiVaultContract, functionName: 'deposit', args: [vaultId, amount], // Execute transaction const hash = await walletClient.writeContract(depositConfig)`} ## Key Functions We use these patterns to manage vault deposits and withdrawals:deposit
Deposit tokens into a vault and receive shares based on current share price.withdraw
Withdraw tokens from a vault by burning shares at current share price.estimateDeposit
Estimate the number of shares received for a given deposit amount. ## Usage ExamplesBasic Deposit
{`// Deposit into vault const vaultId = 123n const amount = parseEther("0.1") const result = await deposit( MULTIVAULT_CONTRACT_ADDRESS, vaultId, amount, walletClient, publicClient )`}Basic Withdrawal
{`// Withdraw from vault const vaultId = 123n const shares = parseEther("10") const result = await withdraw( MULTIVAULT_CONTRACT_ADDRESS, vaultId, shares, walletClient, publicClient )`} ## Fee StructureUnderstanding Fees
Entry Fee
Fee charged when depositing into a vault, calculated as a percentage of deposit.Exit Fee
Fee charged when withdrawing from a vault, calculated as a percentage of withdrawal.Protocol Fee
Fee collected by the protocol for maintaining the system and infrastructure. ## Share Price DynamicsBonding Curve Mechanics
Price Discovery
Share price increases as more tokens are deposited into the vault.Early Adopter Advantage
Early depositors receive more shares for the same token amount.Liquidity Provision
Vaults provide continuous liquidity for depositors and withdrawers. ## Best Practices - Always estimate fees before executing transactions - Consider share price impact when depositing large amounts - Implement proper error handling for failed transactions - Monitor vault state and share prices before transactions - Use multicall patterns for batch operations - Provide clear feedback to users about fee structures ## Next Steps After managing deposits and withdrawals, explore: - [Retrieve Vault Details](/docs/interaction-guide/retrieve-vault-details) - Get comprehensive vault information - [Create Atom](/docs/interaction-guide/create-atom) - Create atoms to deposit into - [Create Triple](/docs/interaction-guide/create-triple) - Create triples with associated vaults For a full reference implementation, see the [Intuition TypeScript SDK](https://github.com/0xIntuition/intuition-ts). --- title: "Overview" description: "Introduction to Intuition contract interactions and smart contract operations" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/interaction-guide/overview" --- # Overview # Contract Interactions Overview The Intuition protocol's smart contracts manage complex state involving Atoms, Triples, and their associated vaults. When interacting with these primitives, we recommend retrieving state data directly from the EthMultiVault contract. ## Key ConceptsMulticall Operations
Batch multiple read-only contract calls into a single request to reduce RPC calls and improve performance.State Management
Retrieve comprehensive vault information including assets, share prices, and user positions.Configuration Access
Access global protocol configuration including fee structures and minimum deposits. ## Implementation Approach We utilize multicall operations that batch multiple read-only contract calls into a single request. This approach significantly reduces RPC calls and provides data you'll need for contract interactions, such as the `atomCost` that is referenced in the contract interaction guides.Core Multicall Pattern
{`// Core multicall configuration const coreContractConfigs = [ ...multiVaultContract, functionName: 'vaults', args: [vid], }, ...multiVaultContract, functionName: 'currentSharePrice', args: [vid], }, // ... additional calls ] // Execute multicall const resp: MulticallResponse[] = await publicClient.multicall({ contracts: coreContractConfigs, })`} ## Available InteractionsCreate Atom
Learn how to create new atoms and manage their associated vaults.Create Triple
Understand how to create triples and manage their relationships.Deposit & Return
Manage deposits and withdrawals from vaults with proper fee handling.Retrieve Vault Details
Get comprehensive vault information including assets, prices, and positions. ## Prerequisites Before diving into contract interactions, ensure you have: - Basic understanding of Intuition's core concepts (Atoms, Triples, Vaults) - Familiarity with Ethereum development and smart contract interactions - Knowledge of multicall patterns and batch operations - Access to the Intuition SDK and development environment ## Next Steps Explore the specific interaction guides to learn how to: - Create and manage atoms and triples - Handle deposits and withdrawals - Retrieve vault state information - Implement proper error handling and validation Each guide provides detailed implementation examples and best practices for working with Intuition's smart contracts. --- title: "Retrieve Vault Details" description: "Get comprehensive vault information including assets, prices, and positions" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/interaction-guide/retrieve-vault-details" --- # Retrieve Vault Details The Intuition protocol's EthMultiVault contract manages complex state involving Atoms, Triples, and their associated vaults. When interacting with these primitives, we recommend retrieving the state data directly from the EthMultiVault contract. We utilize multicall operations that batch multiple read-only contract calls into a single request. This approach significantly reduces RPC calls and provides data you'll need for contract interactions, such as the `atomCost` that is referenced in the contract interaction guides. ## Implementation This implementation guide assumes that you've completed the steps in the [Overview](/docs/interaction-guide/overview) guide. Steps for creating the `createMultivaultContract` and the `publicClient` referenced in this implementation example can be found in the overview. We recommend creating a `multivault.ts` that includes the following:Core Multicall Configuration
{`// createMultiVaultcontract const multiVaultContract = createMultiVaultContract(contract) // Core multicall configuration const coreContractConfigs = [ ...multiVaultContract, functionName: 'vaults', args: [vid], }, ...multiVaultContract, functionName: 'currentSharePrice', args: [vid], }, // ... additional calls ] // Execute multicall const resp: MulticallResponse[] = await publicClient.multicall({ contracts: coreContractConfigs, })`} ## Complete Example Here is a full example of the multicall pattern used in the `getMultivaultConfig` function:Full Implementation
{`export async function getMultiVaultConfig(contract: string) { const multiVaultContract = createMultiVaultContract(contract) const coreContractConfigs = [ ...multiVaultContract, functionName: 'generalConfig', args: [], }, ...multiVaultContract, functionName: 'vaultFees', args: [0], }, ...multiVaultContract, functionName: 'atomConfig', args: [], }, ] const resp: MulticallResponse[] = await publicClient.multicall({ contracts: coreContractConfigs, const admin = resp[0].result[0] as \`0x\${string}\` const protocol_vault = resp[0].result[1] as \`0x\${string}\` const fee_denominator = resp[0].result[2] as bigint const formatted_fee_denominator = formatUnits(fee_denominator, 18) const min_deposit = resp[0].result[3] as bigint const formatted_min_deposit = formatUnits(min_deposit, 18) const min_share = resp[0].result[4] as bigint const formatted_min_share = formatUnits(min_share, 18) const entry_fee = resp[1].result[0] as bigint const formatted_entry_fee = formatUnits(entry_fee, 18) const exit_fee = resp[1].result[1] as bigint const formatted_exit_fee = formatUnits(exit_fee, 18) const protocol_fee = resp[1].result[2] as bigint const formatted_protocol_fee = formatUnits(protocol_fee, 18) const atom_cost = resp[2].result[0] as bigint const formatted_atom_cost = formatUnits(atom_cost, 18) const atom_creation_fee = resp[2].result[1] as bigint const formatted_atom_creation_fee = formatUnits(atom_creation_fee, 18) return { admin, protocol_vault, fee_denominator: fee_denominator.toString(), formatted_fee_denominator, min_deposit: min_deposit.toString(), formatted_min_deposit, min_share: min_share.toString(), formatted_min_share, entry_fee: entry_fee.toString(), formatted_entry_fee, exit_fee: exit_fee.toString(), formatted_exit_fee, protocol_fee: protocol_fee.toString(), formatted_protocol_fee, atom_cost: atom_cost.toString(), formatted_atom_cost, atom_creation_fee: atom_creation_fee.toString(), formatted_atom_creation_fee, } as MultivaultConfig }`} ## Key Functions We use this multicall pattern to retrieve configuration that we're able to use throughout the app:getVaultDetails
Retrieves comprehensive vault information including total assets, conviction, current share price, fee configurations, user-specific positions, and counter-vault details.getMultiVaultConfig
Retrieves global protocol configuration including fee structures, minimum deposits, and protocol admin addresses. ## Usage Example The full `getVaultDetails` function follows the same pattern used in the `getMultiVaultConfig` example but is too large to include in the docs. We recommend looking at the [Intuition TypeScript SDK](https://github.com/0xIntuition/intuition-ts/blob/main/apps/portal/app/.server/multivault.ts) for a full reference implementation.Basic Usage
{`// Fetch vault and countervault details with user positions: const vaultDetails = await getVaultDetails( MULTIVAULT_CONTRACT_ADDRESS, vaultId, userWallet, counterVaultId // Access formatted values such as atom_cost and triple_cost console.log({ atomCost: vaultDetails.atom_cost, tripleCost: vaultDetails.triple_cost, })`} ## Reference Implementation For a full example of how we implement all of our EthMultiVault multicalls, you can look at a reference implementation in our monorepo: - [https://github.com/0xIntuition/intuition-ts/blob/main/apps/portal/app/.server/multivault.ts](https://github.com/0xIntuition/intuition-ts/blob/main/apps/portal/app/.server/multivault.ts) ## Best Practices - Use multicall patterns to reduce RPC calls and improve performance - Always handle errors gracefully when retrieving vault data - Cache vault details when possible to reduce redundant calls - Validate returned data before using it in your application - Monitor vault state changes and update your UI accordingly ## Next Steps After retrieving vault details, explore: - [Create Atom](/docs/interaction-guide/create-atom) - Create atoms and manage their vaults - [Create Triple](/docs/interaction-guide/create-triple) - Create triples with associated vaults - [Deposit & Return](/docs/interaction-guide/deposit-return) - Manage vault deposits and withdrawals For a full reference implementation, see the [Intuition TypeScript SDK](https://github.com/0xIntuition/intuition-ts). --- title: "System Architecture" description: "Overview of Intuition's technical architecture and design principles" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/intuition-concepts/architecture" --- # System Architecture This guide provides an overview of Intuition's technical architecture and how the various components work together. ## High-Level Architecture Intuition is built as a multi-layer system: ### Layer 1: On-Chain Primitives - **Smart Contracts**: Core protocol logic - **MultiVault System**: Atom and Triple vaults - **Bonding Curves**: Price discovery mechanisms - **ERC-1155 Tokens**: Atom and Triple representations ### Layer 2: Off-Chain Data - **IPFS/Arweave**: Decentralized storage for Atom data - **DIDs**: Decentralized identifier resolution - **Metadata**: Rich context and descriptions ### Layer 3: Indexing & Query - **GraphQL API**: Efficient data querying - **PostgreSQL**: Indexed on-chain data - **Real-time Subscriptions**: Live updates - **Aggregation Tables**: Pre-computed statistics ### Layer 4: Application Layer - **SDK**: Developer-friendly abstractions - **React Hooks**: Frontend integrations - **UI Components**: Reusable interface elements ## Core Components ### MultiVault Contract Central smart contract managing: - Atom creation and storage - Triple creation and validation - Vault deposits and redemptions - Fee distribution - Share calculations Key functions: ```solidity createAtom(bytes atomData) createTriple(uint256 subject, uint256 predicate, uint256 object) deposit(uint256 vaultId, uint256 amount) redeem(uint256 vaultId, uint256 shares) ``` ### Trust Bonding Contract Manages staking and rewards: - Epoch-based rewards - Lock mechanisms - Utilization tracking - APY calculations ### Atom Warden Controls Atom wallets: - Grants agency to Atoms - Manages Atom-owned assets - Executes transactions on behalf of Atoms ## Data Flow ### Creating an Atom 1. User submits atomData 2. Data hashed to generate unique ID 3. Check for existing Atom with same ID 4. If new, mint ERC-1155 token 5. Create associated vault 6. Emit AtomCreated event 7. Optional: Initial deposit to signal ### Creating a Triple 1. Verify subject, predicate, object Atoms exist 2. Generate Triple ID from component hashes 3. Create Triple vault (for) 4. Create counter-triple vault (against) 5. Emit TripleCreated event 6. Optional: Initial deposit to signal ### Staking/Signaling 1. User deposits tokens into vault 2. Bonding curve calculates shares to mint 3. Distribute fees to existing shareholders 4. Mint shares to depositor 5. Update vault TVL 6. Emit Deposited event 7. Index in GraphQL database ## Event System ### Key Events ```solidity event AtomCreated(uint256 indexed vaultId, bytes atomData) event TripleCreated(uint256 indexed vaultId, uint256 subject, uint256 predicate, uint256 object) event Deposited(uint256 indexed vaultId, address indexed depositor, uint256 amount, uint256 shares) event Redeemed(uint256 indexed vaultId, address indexed redeemer, uint256 shares, uint256 amount) event FeeTransfer(uint256 indexed vaultId, address indexed recipient, uint256 amount) ``` ### Event Processing 1. Smart contract emits event 2. Indexer catches event 3. Parse event data 4. Update PostgreSQL tables 5. Trigger GraphQL subscriptions 6. Notify connected clients ## Security Model ### Access Control - Permissionless Atom/Triple creation - Wallet-controlled deposits/redemptions - Protocol-controlled fee distribution - Governance-controlled parameters ### Economic Security - Bonding curves prevent manipulation - Fees deter spam and abuse - Staking aligns incentives - Slashing for malicious behavior (potential) ### Data Integrity - Deterministic Atom IDs prevent duplicates - IPFS ensures data availability - On-chain proofs of existence - DIDs provide verifiable credentials ## Scalability Considerations ### On-Chain Efficiency - Batch operations where possible - Optimized storage patterns - Event-based indexing - Layer 2 compatibility planned ### Off-Chain Scaling - GraphQL for efficient queries - Aggregation tables for statistics - Caching strategies - CDN for static content ### Future Optimizations - ZK-proofs for privacy - Optimistic rollups for throughput - Sharding for data distribution - Cross-chain bridges --- ## Next Steps - [Protocol Overview](/docs/protocol/getting-started/overview) - Detailed contract documentation - [SDK Overview](/docs/intuition-sdk/quick-start) - Using the SDK - [GraphQL API](/docs/graphql-api/overview) - Querying the system --- title: "Bonding Curves" description: "How bonding curves create markets for knowledge" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/intuition-concepts/economics/bonding-curves" --- # Bonding Curves Bonding curves are a core economic primitive in Intuition, determining how the price of shares changes as more users stake tokens in Atom and Triple vaults. ## What is a Bonding Curve? A bonding curve is a mathematical function that defines the relationship between the supply of tokens and their price. In Intuition: - Price increases as more tokens are staked - Price decreases as tokens are withdrawn - Creates continuous liquidity - Eliminates need for order books ## How Bonding Curves Work ### Basic Mechanics 1. **Initial Price**: First stake gets shares at base price 2. **Progressive Pricing**: Each subsequent stake pays slightly more 3. **Continuous Market**: No waiting for buyers/sellers 4. **Deterministic**: Price is always calculable from supply ### Example Progression ``` Stake 1: 100 tokens → 100 shares (price: 1.00) Stake 2: 100 tokens → 95 shares (price: 1.05) Stake 3: 100 tokens → 91 shares (price: 1.10) Stake 4: 100 tokens → 87 shares (price: 1.15) ``` ## Curve Types in Intuition ### Linear Curve Simple linear progression: - Price = basePrice + (supply * slope) - Predictable, straightforward - Used for most standard vaults ### Offset Progressive Curve More complex pricing with offset: - Allows for custom curve shapes - Can have different growth rates - Used for specialized vaults ## Bonding Curve Demo ## Dynamic Pricing Benefits Intuition uses bonding curves to create dynamic pricing mechanisms that automatically adjust based on supply and demand. This sophisticated approach provides multiple benefits:Automated Market Making
Liquidity is provided automatically through mathematical curves, eliminating the need for traditional order books or manual market makers.Early Incentives
Early participants get better prices, encouraging adoption and rewarding pioneers who identify valuable data structures before they become widely recognized.Supply Control
Prices increase as more tokens are minted, preventing inflation while ensuring scarcity creates value for established data structures.Economic Alignment
Pricing automatically reflects the value of underlying assets, ensuring market mechanisms accurately represent the true worth of data and relationships. ## Economic Implications ### For Early Stakers **Advantages:** - Get shares at lower prices - Earn fees from all future stakers - Benefit from price appreciation - Higher ownership percentage **Risks:** - May not attract later stakers - TVL could remain low - Limited fee generation if unused ### For Later Stakers **Advantages:** - Join proven, popular data - Higher confidence in value - More established signal **Disadvantages:** - Pay premium prices - Lower ownership percentage - Less potential upside ## Liquidity Benefits ### Always Available - No need to find counterparty - Instant stake/unstake - Deterministic pricing - No slippage from order books ### Price Discovery - Continuous price updates - Reflects real demand - Self-balancing mechanism - Market-driven valuations ## Curve Parameters ### Configurable Elements 1. **Base Price**: Starting price for first share 2. **Curve Slope**: Rate of price increase 3. **Curve Type**: Linear vs progressive 4. **Reserve Ratio**: Backing percentage ### Governance - Curve parameters may be adjustable - Community governance controls changes - Different curves for different vault types - Balances accessibility and sustainability --- ## Next Steps - [Fees & Rewards](/docs/intuition-concepts/economics/fees-and-rewards) - Understanding the fee structure - [Tokenomics](/docs/intuition-concepts/economics/tokenomics) - Learn about $TRUST token utility - [Incentive Design](/docs/intuition-concepts/economics/incentive-design) - How economics drive consensus --- title: "Fees and Rewards" description: "Understanding fee structure and reward mechanisms" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/intuition-concepts/economics/fees-and-rewards" --- # Fees and Rewards # Fees & Rewards In the Intuition system, interactions incur fees similar to gas costs in blockchain transactions. These fees serve critical roles in maintaining system integrity, incentivizing contributions, and fostering high-quality data. ## Purpose of Fees ### Preventing Abuse and Attacks Decentralized systems face risks such as Sybil and DoS attacks. Intuition mitigates these through economic disincentives: - Fees deter malicious activity by imposing costs - Network resilience: attacks inadvertently benefit the system through fee payments - Similar to how Ethereum benefits from all transaction fees ### Encouraging Active Participation Economic incentives motivate meaningful contributions: - Historical challenge: Web2 platforms (Amazon, Yelp, Wikipedia) struggle with participation - Intuition mirrors blockchain block rewards model - Tangible incentives for creating valuable data ### Promoting High-Quality Data Shifts focus from quantity to quality: - Economic mechanisms discourage irrelevant data - Rewards align with data quality and usage - Reduces "junk data" proliferation ### Establishing Standards Through Incentives Traditional standards creation is challenging ("standards hell"): - Applies blockchain consensus principles to social consensus - Financial rewards for distributed agreement - Extends to data structures, schemas, formats, identifiers ## Fee Types Every interaction with the knowledge graph involves two types of fees: - **Gas fees**: Network transaction fees paid to the maintainers of the Intuition Network for processing transactions - **Protocol fees**: Fees that flow through the Intuition protocol to reward data contributors and maintain the ecosystem Because Intuition breaks data down into discrete, tokenized units, the system is aware of 'who owns what data' at any given point in time. Because of this, the system is able to programmatically flow value — such as these fees — through data as that data is interacted with. ## Fee Allocation When users interact with or create data, these combined fees support both network operations and data contributor rewards through the following mechanisms:Purchasing Equity in the Data
To purchase tokens of an Atom or Triple, users deposit $TRUST (the native token of the Intuition Network and Protocol) into the Vault of the respective Atom or Triple. You pay a protocol fee proportional to your deposit amount. In return, you receive tokens of that specific Atom or Triple, entitling you to rewards generated by that data point proportional to your ownership percentage.Rewarding Prior Contributors
When interacting with data, part of the protocol fee is distributed to all existing shareholders (prior contributors). This encourages early, meaningful contributions, as users who add valuable data will continue to be rewarded over time through protocol fees, while gas fees go to network validators.Protocol Maintenance
A portion of the protocol fee is paid to the Intuition protocol for platform maintenance and development. This ensures Intuition can be self-sustaining and exist in perpetuity, without risk of shutting down. ## Fee Structure Details ### Entry Fees - Charged when depositing into vaults - Distributed to existing shareholders - Incentivizes early discovery - Amount varies by bonding curve position ### Exit Fees - May be charged on withdrawal - Helps stabilize vaults - Prevents rapid speculation - Protects remaining stakers ### Protocol Fees - Portion goes to protocol treasury - Funds development and maintenance - Supports ecosystem growth - Governed by community ### Atom Deposit Fraction - Special fee for Atom interactions - Ensures Atom owners benefit when used in Triples - Aligns incentives across primitives - Creates value flow through graph structure ## Fractals Data Structure Incentives The data model (Atoms, Triples, Signal) enables programmatic value distribution: ### Example: YouTube Video Like 1. User creates Triple: `[User] [likes] [YouTube Video]` 2. Creation fee rewards owners of component Atoms 3. Initial deposit grants Triple ownership 4. Future deposits reward this user 5. Value flows through entire structure This ensures: - High-quality data remains prominent - Incentives align with accuracy - Meaningful contributions rewarded - Natural quality filtering ## Reward Distribution ### Share-Proportional Rewards Rewards distributed based on ownership: ```typescript yourReward = totalFees * (yourShares / totalShares) ``` ### Temporal Advantages Early participants benefit more: - Better share prices - Longer fee accumulation period - Compound growth effects ### Usage-Based Generation More useful data generates more fees: - Popular Atoms referenced frequently - Valuable Triples queried often - Infrastructure data constantly used ## Aligning Incentives with Data Structure Economic model motivates users to: - **Converge on Entities**: Consensus on key data points - **Adopt Effective References**: Best ways to structure data - **Support Quality**: Back accurate, useful information - **Create Standards**: Emerge organically through use Drives fractal consensus from individual Atoms to complex nested Triples. ## Self-Regulating Ecosystem Economic integration achieves: - **System Security**: Fees deter attacks - **Meaningful Contributions**: Rewards motivate quality - **Structured Consensus**: Incentive-driven standardization - **Sustainable Growth**: Value flows support development --- ## Next Steps - [Bonding Curves](/docs/intuition-concepts/economics/bonding-curves) - Understand pricing mechanics - [Tokenomics](/docs/intuition-concepts/economics/tokenomics) - Learn about $TRUST token - [Incentive Design](/docs/intuition-concepts/economics/incentive-design) - How economics drive consensus --- title: "Incentive Design" description: "How economics drive consensus and reduce fragmentation" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/intuition-concepts/economics/incentive-design" --- # Incentive Design Intuition's economic model is carefully designed to solve fundamental challenges in decentralized knowledge systems: fragmentation, quality control, and consensus formation. ## Reducing Fragmentation In many systems, user-generated tags and classifications, known as **folksonomies**, can lead to fragmented and disorganized data. Different people might use different labels for the same thing, making it hard to gather or analyze information effectively. Intuition solves this by encouraging users to converge on a common set of identifiers. Intuition acts as a consensus mechanism not just for identifiers, but also for data structures—it is essentially a consensus mechanism for the 'state of the state' of decentralized systems, where participants are economically incentivized to converge on consensus identifiers and data structures. ## Market-Driven Consensus Intuition uses a **market-driven consensus** model inspired by blockchain technology. In systems like Proof of Work (PoW) and Proof of Stake (PoS), participants are economically incentivized to act in ways that benefit the network. Users are motivated to use established and widely recognized identifiers because doing so increases their potential rewards from future interactions. This model mirrors the behavior of prediction markets and automated market makers (AMMs), where participants align with the most trusted and valuable options due to market incentives. ## Token-Curated Graph (TCG) As users interact with and endorse certain identifiers, Intuition naturally creates a **token-curated graph (TCG)**—a graph of popular, widely used identifiers and data structures. These identifiers become the standard, and the system self-regulates based on user interactions and rewards, ensuring only the most valuable data structures rise to prominence. ### How TCG Works 1. **Network Effects**: Popular identifiers attract more usage 2. **Economic Signals**: Staking patterns reveal community preferences 3. **Quality Filtering**: Valuable data naturally accumulates more stake 4. **Emergent Standards**: Consensus forms organically through market forces ## Keynesian Beauty Contest Application Intuition also applies the **Keynesian Beauty Contest** concept, where users are rewarded for choosing options they believe others will choose. This drives consensus on data structures and identifiers, as users are motivated to align their actions with the choices of the broader community, ensuring the most popular and widely accepted options become the standard. ### Strategic Behavior - Users predict which identifiers will become canonical - Early adoption of future standards yields higher rewards - Community alignment is incentivized over fragmentation - Consensus emerges from collective intelligence ## Early Adopter Advantage Users who are quick to interact with new data—whether it's creating or endorsing an identity or claim—are rewarded more as the data gains traction. This system encourages users to contribute and adopt important data early, creating a race to establish high-quality, valuable information that others will rely on. The earlier you participate, the more rewards you can earn over time as others use the same data. Early contributors receive ongoing distributions from all future interactions with their contributed data. ### Reward Mechanisms for Early Adopters - **Better Pricing**: Lower entry costs on bonding curves - **Larger Ownership**: Higher percentage of total shares - **Ongoing Fees**: Continuous rewards from future participants - **Compound Growth**: Reinvestment opportunities multiply returns ## Convergence Incentives The economic model creates powerful incentives for convergence: ### For Data Creators - First-mover advantage for valuable identifiers - Ongoing rewards as usage grows - Reputation building through quality contributions - Economic exposure to data success ### For Data Consumers - Lower costs when using established identifiers - Access to higher quality, verified data - Network effects increase data utility - Confidence in widely-adopted standards ## Consensus Mechanisms ### Social Consensus Unlike traditional blockchain consensus (PoW, PoS), Intuition enables consensus on: - Data structures and schemas - Canonical identifiers for entities - Standard predicates and relationships - Quality and accuracy of information ### Economic Alignment The system aligns economic incentives with consensus goals: - Rewards for standardization over fragmentation - Penalties (higher costs) for creating duplicates - Benefits for early identification of winning standards - Sustainable model for long-term participation ## Anti-Fragmentation Design ### Traditional Problems Without economic incentives: - Multiple competing identifiers for same entity - Inconsistent data structures and formats - Low-quality, unverified information - Difficulty achieving agreement on standards ### Intuition's Solutions Economic mechanisms that: - Make convergence more profitable than fragmentation - Reward early adopters of canonical identifiers - Create network effects around quality data - Enable market-driven quality control ## Summary By integrating these economic principles, Intuition creates a dynamic, decentralized ecosystem where users are continuously rewarded for valuable contributions, and the community naturally converges on high-quality, standardized data structures. This economic framework ensures sustainable growth while maintaining the platform's security and reliability, creating a virtuous cycle of value creation and distribution that benefits all participants in the Intuition ecosystem. --- ## Next Steps - [Tokenomics](/docs/intuition-concepts/economics/tokenomics) - Understand $TRUST token utility - [Bonding Curves](/docs/intuition-concepts/economics/bonding-curves) - Learn about dynamic pricing - [Fees & Rewards](/docs/intuition-concepts/economics/fees-and-rewards) - See how rewards flow --- title: "Economics" description: "Understanding Intuition's token-curated knowledge graph economics" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/intuition-concepts/economics" --- # Economics # Economics Overview Intuition is built on the idea that information deserves its own decentralized distribution and financial rails. Just as blockchains turned money into programmable assets, Intuition turns information into tokenized, ownable, and composable units that anyone can create and monetize in. At the core are Atoms (entities) and Triples (relationships). As users publish, curate, and stake on these objects, they generate a token-curated knowledge graph where ownership weights are represented by positions in $TRUST — the native token of the Intuition Network and Protocol. ## The Vision The economics of Intuition transform every digital interaction into an economic opportunity. Every like, comment, review, connection, and action you take across the web becomes an economic bet, allowing you to buy meaningful ownership in any piece of data. The goal is not to tokenize data just for the sake of a token. The economics of Intuition are designed to:1. Incentivize Expression
2. Incentivize Convergence on Canonical Identifiers
3. Incentivize Consensus on Standards and Structures
--- ## $TRUST Token The native token $TRUST enables users to: - Accumulate stake in the information you believe in - Retain true ownership of what you create - Earn as that data gains traction and value across the network ### External Resources For deeper understanding of Intuition's economic foundations: - **[Trust Whitepaper](https://cdn.prod.website-files.com/65cdf366e68587fd384547f0/68316bdfe42a265d3dc45498_trust-whitepaper.pdf)** - Comprehensive overview of the economic model and theoretical foundations - **[$TRUST Tokenomics Dashboard](https://app.forgd.com/share/trust/9837b0d0-e11f-410f-80e6-62a0b6fe13ff/public)** - Detailed token economics, distribution, and utility --- ## Example Flow: How the Incentives Work ### 1. Expression **Alice creates a new Atom: a DID for Tesla, Inc.** - She publishes an attestation: `[Tesla] – [foundedBy] – [Elon Musk]`, staking $TRUST behind it - Because she was first, she captures the early-mover rewards ### 2. Convergence **Bob considers creating his own identifier for Tesla** - But Alice's Atom already has traction, with value flowing into its bonding curve - The economics reward Bob for using the existing canonical DID instead of fragmenting the graph ### 3. Consensus on Standards **Carol proposes that `foundedBy` and `headquarteredIn` should be standard predicates for corporate entities** - The network's incentive structure rewards attestations that align with these schemas - As more users adopt them, `foundedBy` becomes a consensus-backed data standard ### 4. Ongoing Rewards **As developers and AI agents query Tesla-related data, fees flow back to the identifiers and attestations that power those queries** - Alice, Bob, and Carol all share in the economic upside of having built durable, widely used pieces of the graph --- ## Reward Dynamics To maximize engagement and data quality, the system favors contributions that are:New or Early
First-mover advantages for valuable identifiers and attestationsWidely Useful
Network effects amplify rewards for commonly referenced knowledgeStandards-Aligned
Stronger incentives for adopting schemas and canonical identifiersFuture-Facing
Forward-looking value assessment ensures durable contributions --- ## Next Steps Explore the specific mechanisms that power Intuition's economics: - [Tokenomics](/docs/intuition-concepts/economics/tokenomics) - Deep dive into $TRUST token distribution and utility - [Bonding Curves](/docs/intuition-concepts/economics/bonding-curves) - How dynamic pricing creates markets for knowledge - [Fees & Rewards](/docs/intuition-concepts/economics/fees-and-rewards) - Understanding the fee structure and reward mechanisms - [Incentive Design](/docs/intuition-concepts/economics/incentive-design) - How economics drive consensus and reduce fragmentation --- title: "$TRUST Tokenomics" description: "Understanding the $TRUST token distribution and utility" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/intuition-concepts/economics/tokenomics" --- # $TRUST Tokenomics $TRUST is the native token of the Intuition Network and Protocol, designed to enable economic participation in the decentralized knowledge graph. ## Token Purpose The $TRUST token serves as the fundamental economic unit within Intuition, enabling: - **Ownership in Data**: Stake $TRUST to acquire ownership shares in Atoms and Triples - **Reward Mechanism**: Earn rewards as your contributed data gains traction and usage - **Economic Signaling**: Express confidence in specific data points through token deposits - **Network Incentives**: Align participant behavior with network growth and data quality ## Token Utility ### Staking and Ownership When you deposit $TRUST into an Atom or Triple vault: - You receive shares representing ownership in that data point - Your ownership percentage determines your share of future rewards - Early stakers benefit from lower prices on the bonding curve - Ownership grants you economic exposure to data usage and popularity ### Earning Mechanisms $TRUST holders can earn through: - **Protocol Fees**: Distributed proportionally to data owners when others interact with their data - **Network Effects**: More valuable data generates more fees for stakeholders - **Early Adoption**: First movers capture outsized rewards for creating valuable identifiers - **Compound Growth**: Reinvest rewards to increase ownership stakes ### Governance and Participation While initially focused on economic participation, $TRUST may evolve to include: - Protocol parameter governance - Standards and schema proposals - Community-driven ecosystem development - Treasury allocation decisions ## Distribution Model The $TRUST token distribution is designed to: - Reward early contributors and builders - Incentivize long-term network participation - Support sustainable ecosystem growth - Align stakeholder incentives with protocol success ## Staking Mechanisms ### Vault Deposits Depositing $TRUST into vaults involves: 1. Selecting an Atom or Triple to stake on 2. Choosing deposit amount 3. Paying protocol fees (which reward existing stakeholders) 4. Receiving shares based on bonding curve pricing 5. Earning proportional rewards from future deposits ### Redemption When withdrawing $TRUST: - Redeem shares for underlying assets - Price determined by bonding curve at redemption time - May incur exit fees to stabilize vaults - Reduces your ownership percentage in that data ## Economic Security The token model provides security through: - **Economic Disincentives**: Fees deter spam and malicious activity - **Stake-Weighted Reputation**: Larger stakes signal stronger conviction - **Attack Resistance**: Attacks inadvertently benefit the system through fee payments - **Sustainable Incentives**: Self-funding model supports long-term viability ## External Resources For comprehensive information about $TRUST tokenomics: - **[Trust Whitepaper](https://cdn.prod.website-files.com/65cdf366e68587fd384547f0/68316bdfe42a265d3dc45498_trust-whitepaper.pdf)** - Full technical and economic specification - **[$TRUST Tokenomics Dashboard](https://app.forgd.com/share/trust/9837b0d0-e11f-410f-80e6-62a0b6fe13ff/public)** - Live tokenomics data, distribution details, and analytics --- ## Next Steps - [Bonding Curves](/docs/intuition-concepts/economics/bonding-curves) - Understand how $TRUST pricing works - [Fees & Rewards](/docs/intuition-concepts/economics/fees-and-rewards) - Learn how rewards are distributed - [Incentive Design](/docs/intuition-concepts/economics/incentive-design) - Explore economic incentive mechanisms --- title: "Atom Best Practices" description: "Patterns and guidelines for creating high-quality, reusable Atoms in the Intuition ecosystem" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/intuition-concepts/primitives/Atoms/best-practices" --- # Atom Best Practices This guide provides comprehensive best practices for creating effective, reusable Atoms that contribute to a high-quality Intuition knowledge graph. ## Creating Effective Atoms ### 1. Leverage Deterministic IDs Remember that identical atomData will always produce the same Atom ID. This ensures: - No duplicate Atoms for the same data - Predictable, verifiable identifiers - Consistent references across the network ```typescript // Same data = same Atom ID const atom1 = createAtom({ data: "Ethereum" }) const atom2 = createAtom({ data: "Ethereum" }) // atom1.id === atom2.id (always true) ``` ### 2. Check for Similar Atoms Before creating new Atoms, search for existing canonical Atoms: - Reduces fragmentation - Leverages existing Signal - Improves data consistency - Benefits from accumulated trust ### 3. Use Clear, Descriptive Data Choose unambiguous, descriptive data values: **Good:** ```json { "data": "Machine Learning" } { "data": "Vitalik Buterin" } { "data": "2024-01-15T10:00:00Z" } ``` **Avoid:** ```json { "data": "ML" } // Ambiguous { "data": "VB" } // Unclear { "data": "today" } // Not specific ``` ### 4. Maintain Single Purpose Each Atom should represent one thing: **Good:** ```javascript const ethereum = { data: "Ethereum" } const blockchain = { data: "blockchain" } const platform = { data: "platform" } // Combine via Triple [Ethereum] - [is a] - [blockchain platform] ``` **Avoid:** ```javascript // Too much packed into one Atom const composite = { data: "Ethereum is a blockchain platform founded in 2015" } ``` ### 5. Consider Reusability Design Atoms that others will want to reference: - Use common terminology - Follow domain conventions - Keep scope focused - Think composably ## Atom Design Patterns Think of Atoms as **words in the Intuition dictionary**: - They are the lego-like pieces that snap into many contexts - Community Signal concentrates on the words that matter most - Triples form the "sentences" that connect these dictionary words together ### Pattern: Universal Concepts Create Atoms for widely-applicable concepts: ``` [true] [false] [yes] [no] [member of] [created by] [owns] ``` ### Pattern: Domain-Specific Terms Use precise domain language: ``` [smart contract] [ERC-20 token] [liquidity pool] [validator node] ``` ### Pattern: Temporal Markers Include specific timestamps or dates: ``` [2024-01-15] [Q1 2024] [2024-01-15T10:30:00Z] ``` ## Integration with Triples Atoms gain their true power when connected via Triples: ### Subject Atoms The entity being described: ``` [Alice] [Ethereum] [USDC Token] ``` ### Predicate Atoms The relationship or property: ``` [owns] [created] [member of] [deployed on] ``` ### Object Atoms The value or target: ``` [Bob] [blockchain] [Ethereum network] [2024-01-15] ``` This separation allows each component to be independently verified, updated, and trusted. ## Naming Conventions ### Consistency Rules 1. **Use camelCase for property names** in structured data 2. **Maintain consistent terminology** across related atoms 3. **Follow established domain conventions** 4. **Use singular form** unless specifically plural ### Examples **Good:** ```json { "type": "concept", "content": "Smart Contract", "category": "blockchain" } ``` **Consistent:** ```json { "type": "entity", "content": "Uniswap Protocol", "category": "defi" } ``` ## Metadata Best Practices ### Required Metadata Always include: - Creation timestamps - Creator's DID - Version information for mutable atoms ```json { "metadata": { "created": "2024-01-15T10:30:00Z", "creator": "did:ethr:mainnet:0x123...", "version": "1.0", "lastModified": "2024-01-15T10:30:00Z" } } ``` ### Optional but Recommended ```json { "metadata": { "description": "Brief description of the Atom", "tags": ["relevant", "keywords"], "category": "domain-category", "source": "https://source-url.com", "license": "CC-BY-4.0" } } ``` ## Scalable Design ### Design for Composability Create Atoms that can be combined in multiple ways: ```javascript // Reusable building blocks const alice = { data: "Alice" } const bob = { data: "Bob" } const friendOf = { data: "friend of" } const knows = { data: "knows" } // Multiple compositions [Alice] - [friend of] - [Bob] [Alice] - [knows] - [Bob] ``` ### Consider Future Extensibility Design with growth in mind: - Use versioning - Include extension points - Maintain backward compatibility - Document changes ### Maintain Backward Compatibility When updating Atoms: - Preserve existing fields - Add new fields carefully - Document breaking changes - Consider migration paths ## Common Pitfalls to Avoid ### 1. Overly Broad Atoms **Avoid:** ```json { "data": "Technology" } // Too broad ``` **Better:** ```json { "data": "Blockchain Technology" } { "data": "AI Technology" } ``` ### 2. Redundant Information **Avoid:** ```json { "data": "Ethereum blockchain cryptocurrency" } ``` **Better:** ```json // Separate Atoms connected via Triples [Ethereum] - [is a] - [blockchain] [Ethereum] - [is a] - [cryptocurrency] ``` ### 3. Time-Sensitive Data Without Timestamps **Avoid:** ```json { "data": "Current CEO" } ``` **Better:** ```json [Company X] - [has CEO] - [Person Y] // Add temporal context via Triple metadata ``` ### 4. Ambiguous References **Avoid:** ```json { "data": "Paris" } // City or person? ``` **Better:** ```json { "data": "Paris, France" } { "data": "Paris Hilton" } ``` ## Performance Considerations ### Optimize for Queries - Use indexed fields - Keep data structures flat when possible - Minimize nested complexity - Consider query patterns ### Balance Detail and Size - Include necessary context - Avoid bloat - Use references for large data - Store heavy content off-chain (IPFS) ## Quality Checklist Before creating an Atom, verify: - [ ] Clear, unambiguous data - [ ] Single, focused purpose - [ ] Follows naming conventions - [ ] Includes required metadata - [ ] Checked for existing similar Atoms - [ ] Designed for reusability - [ ] Appropriate granularity - [ ] Verifiable content - [ ] Respects community standards - [ ] Documented if complex --- ## Next Steps - [Triple Fundamentals](../triples/fundamentals) - Learn how to connect Atoms into meaningful relationships - [Signal Fundamentals](../signals/fundamentals) - Understand how to build trust in your Atoms - [Atom Structuring](./structuring) - Review advanced structuring techniques --- title: "Atom Fundamentals" description: "Understanding Atoms - the fundamental units of data in the Intuition knowledge graph" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/intuition-concepts/primitives/Atoms/fundamentals" --- # Atom Fundamentals Atoms are the foundational building blocks of Intuition's knowledge graph – the words in our global dictionary. Think of Intuition as a vast, collaborative dictionary where anyone can create a new word, and each word has its own globally persistent, unique digital identifier that can be used to reference it across the entire internet. ## What are Atoms? A system facilitating the arrival at social consensus around globally persistent canonical identifiers for all things demands that these identifiers possess a few key attributes.Decentralized Identifiers
These identifiers should be decentralized identifiers, providing unique, secure, and verifiable identification without any reliance on a central authority.Associated Data
These identifiers should have a sufficient amount of associated data to ensure precise referencing of specific entities, concepts, or pieces of information.Agent-Centric State
These identifiers must have some agent-centric state that is capable of tracking the usage of the identifier across contexts. ## The Atom Solution To solve for these requirements, the concepts of Atoms emerge as the foundation of the Intuition framework, representing the most fundamental units of data. These units can range from a single word to a complex concept, serving as discrete, manageable, and referenceable pieces of information that facilitate seamless data integration and manipulation across the web. In the spirit of the Semantic Web and linked data, an Atom can correspond to virtually anything: - **People**: User identities, profiles, public figures - **Organizations**: Companies, DAOs, institutions, projects - **Addresses**: Cryptocurrency wallets, smart contracts, validators - **Documents**: Files, articles, research papers, certificates - **Temporal markers**: Dates, timestamps, time periods - **Categories**: Tags, classifications, taxonomies - **Concepts**: Ideas, words, phrases, abstract notionsKey Benefits of Atoms
Universal Reference
Start to reference data universally across the web.User Equity
Grant users equity in data as they signal its relevancy through usage.Active Participation
Reward users for signaling the relevancy of data, encouraging active participation. Each Atom is made universally referenceable through a decentralized identifier. This approach ensures that every Atom is uniquely identifiable and can be consistently referenced across the web, maintaining data integrity and meaning regardless of the system or context. ## Technical Architecture ### Core Structure Under the hood, creating a new Atom mints a tokenized record using the ERC-1155 multi-token standard that includes: 1. **Unique Atom ID**: A permanent, immutable identifier deterministically derived from the atomData 2. **Atom Data**: Can contain any arbitrary data (URIs, text, JSON, references to external resources) 3. **Associated Smart Contract Wallet**: Enabling the Atom itself to own assets and interact with contracts Each Atom's unique ID is deterministically generated based on its `atomData` field – meaning the same data will always produce the same Atom ID. This ensures that duplicate Atoms cannot be created for identical data, and anyone can independently verify an Atom's ID by hashing its data. Every Atom carries `atomData` which can contain any arbitrary information relevant to that entity. For example: - An Atom for "Solar Energy" might contain a link to a Wikipedia page about solar power - An Atom for a user's identity might contain a DID document reference or profile JSON - An Atom for a document might contain an IPFS content hash - An Atom for a concept might contain a simple text string or structured JSON data The uniqueness of each Atom is enforced by hashing its underlying data, preventing duplicate Atoms for the same piece of data. This approach allows Atoms to segment data into discrete, manageable units that can be easily combined and reused across diverse contexts and applications. ### Decentralized Identifiers (DIDs)Example DID
{`// An example DID did:ethr:mainnet:0x3b0bc51ab9de1e5b7b6e34e5b960285805c41736 // An example DID Document "id": "did:ethr:mainnet:0x3b0bc51ab9de1e5b7b6e34e5b960285805c41736", "verificationMethod": [ "id": "did:ethr:mainnet:0x3b0bc51ab9de1e5b7b6e34e5b960285805c41736#controller", "type": "EcdsaSecp256k1RecoveryMethod2020", "controller": "did:ethr:mainnet:0x3b0bc51ab9de1e5b7b6e34e5b960285805c41736", "blockchainAccountId": "eip155:1:0x3b0BC51Ab9De1e5B7B6E34E5b960285805C41736" ], "authentication": [ "did:ethr:mainnet:0x3b0bc51ab9de1e5b7b6e34e5b960285805c41736#controller" ], "assertionMethod": [ "did:ethr:mainnet:0x3b0bc51ab9de1e5b7b6e34e5b960285805c41736#controller" ], "@context": [ "https://www.w3.org/ns/did/v1", "https://w3id.org/security/suites/secp256k1recovery-2020/v2", "https://w3id.org/security/v3-unstable" ] }`} ## Components of an AtomAtom Data
Describes the concept or entity represented by an Atom, typically stored off-chain using decentralized storage solutions like IPFS or Arweave, with a URI pointing to this data stored on-chain.Atom Wallet
A smart contract wallet associated with each Atom, granting it agency over its identity. This wallet is controlled by a specialized smart contract known as the Atom Warden.Atom Vault
A mechanism that allows users to deposit tokens into an Atom, signaling its relevance and support within the system. The Total Value Locked (TVL) in an Atom Vault indicates the Atom's acceptance and importance. ### Staking Vaults and Bonding Curves Each Atom has one or more Vaults attached to it for staking. These vaults operate on a bonding curve, meaning: - The cost to acquire a stake (or "share") in an Atom increases as more is already staked - Early stakers get a larger stake for their investment - Latecomers pay a premium for popular Atoms This mechanism incentivizes early discovery of important Atoms and creates a form of priority signaling – the community collectively "bids up" the Atoms deemed valuable or relevant by risking capital in their vaults. ### Atom Creation Process ## Data Requirements To ensure reliable referencing of entities, concepts, or data within an Atom, each Atom must include at least minimal corresponding data. This data can be of any type, stored anywhere, and presented in any format.Recommended Data Practices
Verifiable Data Registry
Use a Verifiable Data Registry to strengthen data usability through guarantees around immutability, availability, liveness, and persistence.Supported Structures
Adhere to supported data structures and schemas for better interoperability and reliability.Timestamp Inclusion
For mutable data, include a timestamp to ensure future references understand exactly what the data represented at the moment of attestation. ## Atom Ownership and Token Curated Registries Given the permissionless nature of the system, multiple Atoms may be representative of the same concept. To foster consensus on high-quality Atoms and establish canonical identifiers for all things, Intuition employs the concept of a Token Curated Registry (TCR).TCR Benefits
Fractional Ownership
Users gain fractional ownership over the Atoms they interact with and receive a portion of the interaction fees each respective Atom generates.Incentivized Engagement
This model incentivizes engagement with popular Atoms, encouraging active participation in the ecosystem.Quality Ranking
A TCR emerges, ranking Atoms based on their relevance using metrics such as an Atom's Total Value Locked (TVL). As users increasingly interact with these Atoms, a TCR emerges, ranking Atoms based on their relevance using metrics such as an Atom's Total Value Locked (TVL). This mechanism facilitates ecosystem convergence on and easy discoverability of the most valuable and widely accepted Atoms/identifiers representing each concept. ## Atoms as Building Blocks Atoms are categorized into three primary roles within semantic structures: ### Subjects The entity or concept being described in a relationship. ### Predicates The relationship or attribute that connects subjects to objects. ### Objects The value or characteristic attributed to the subject through the predicate. This structure facilitates the creation of **Triples** that articulate specific assertions or facts about the world, which we'll explore in the next section. --- ## Next Steps Now that you understand Atom fundamentals, explore: - [Atom Structuring](./structuring) - Learn advanced techniques for structuring Atoms effectively - [Atom Best Practices](./best-practices) - Discover patterns and guidelines for creating high-quality Atoms - [Triple Fundamentals](../triples/fundamentals) - Learn how Atoms combine to form relationships - [Signal Fundamentals](../signals/fundamentals) - Understand how users interact with Atoms through signaling --- title: "Atom Structuring" description: "Advanced techniques for structuring Atoms effectively in the Intuition knowledge graph" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/intuition-concepts/primitives/Atoms/structuring" --- # Atom Structuring Understanding how to properly structure Atoms is crucial for building effective applications on the Intuition protocol. This guide covers advanced techniques and patterns for creating well-designed, reusable Atoms. ## Design Principles: Atomic Granularity A crucial best practice is keeping information modular and atomic. You are economically incentivized to create "flatter" Atoms – each representing a single, minimal concept – rather than packing composite information into one Atom. ### Why Granularity Matters Consider representing the statement: **"Tiger Research was founded in 2021"** #### Monolithic Approach (Not Recommended) ```javascript // One Atom containing all information const statementAtom = { data: "Tiger Research was founded in 2021" } ``` Problems with this approach: - Hard to verify which part might be incorrect if disputed - Cannot reuse individual components - Difficult to update or correct specific elements - Less composable with other data #### Atomic Approach (Best Practice) ```javascript // Three separate Atoms const tigerResearchAtom = { data: "Tiger Research" } const foundedInAtom = { data: "founded in" } const year2021Atom = { data: "2021" } // Connected via a Triple const foundingTriple = { subject: tigerResearchAtom, predicate: foundedInAtom, object: year2021Atom } ``` Benefits of this approach: - Each piece can be independently verified and traced - Individual components are reusable (the `[2021]` Atom can be used in countless other triples) - Corrections can be made to specific elements without discarding everything - Trust accrued by each Atom benefits all its usages ## Economic Incentives for Granularity Intuition's economic model naturally guides users toward optimal granularity: - **Reusable Atoms** accumulate more Signal as they're referenced in multiple Triples - **High-Signal Atoms** attract more stakes, increasing their network gravity - **Composite Atoms** with embedded data are less likely to be reused or staked - **Modular Design** maximizes potential for community adoption and value accrual ## Atom Structure Components ### Basic Structure An Atom consists of three core components: 1. **Decentralized Identifier (DID)** - Unique identifier for the atom 2. **Data Content** - The actual information being represented 3. **Metadata** - Additional context and properties ### Example Atom Structure ```json { "id": "did:ethr:mainnet:0x3b0bc51ab9de1e5b7b6e34e5b960285805c41736", "data": { "type": "concept", "content": "Machine Learning", "description": "A subset of artificial intelligence that enables systems to learn and improve from experience", "tags": ["AI", "technology", "computing"] }, "metadata": { "created": "2024-01-15T10:30:00Z", "creator": "did:ethr:mainnet:0x123...", "version": "1.0" } } ``` ## Atom Categories ### Concept Atoms Represent abstract ideas, categories, or classifications. ```json { "type": "concept", "content": "Blockchain Technology", "category": "technology" } ``` ### Entity Atoms Represent specific people, places, or things. ```json { "type": "entity", "content": "Ethereum", "category": "blockchain", "properties": { "founded": "2015", "creator": "Vitalik Buterin" } } ``` ### Attribute Atoms Represent characteristics or properties. ```json { "type": "attribute", "content": "Decentralized", "category": "property", "appliesTo": ["blockchain", "governance"] } ``` ## Flexibility and Scope Atoms are not limited to static concepts. They can represent: - **Dynamic entities**: User-generated content, evolving documents - **Abstract concepts**: Tags, categories, classifications - **Data structures**: JSON schemas, configuration templates - **Content chunks**: Text snippets, code fragments (via IPFS CID) Regardless of what an Atom represents, the principles remain consistent: 1. Give it a clear, unique identity 2. Include relevant data in the atomData field 3. Keep its scope narrow for maximum verifiability and reusability ## Creating Atoms Programmatically ### Using the SDK ```typescript import { createAtomFromString, getEthMultiVaultAddressFromChainId, } from '@0xintuition/sdk' import { createPublicClient, createWalletClient, http } from 'viem' import { privateKeyToAccount } from 'viem/accounts' import { sepolia } from 'viem/chains' // 1) Configure viem clients const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`) const walletClient = createWalletClient({ account, chain: sepolia, transport: http() }) const publicClient = createPublicClient({ chain: sepolia, transport: http() }) // 2) Resolve MultiVault address for the current chain const multivaultAddress = getEthMultiVaultAddressFromChainId(sepolia.id) // 3) Create an Atom from a simple string label const result = await createAtomFromString( { walletClient, publicClient, address: multivaultAddress }, 'Machine Learning', ) console.log('Created atom vaultId:', result.state.vaultId) ``` ## Validation Guidelines Ensure your atoms follow these validation rules: - **Required Fields**: `id`, `data.content`, `metadata.created` - **Content Length**: Minimum 1 character, maximum 10,000 characters - **Tag Count**: Maximum 20 tags per atom - **Metadata**: Must include creator DID and timestamp ## Atom Relationships ### Direct References ```json { "content": "Deep Learning", "relatedAtoms": [ "did:ethr:mainnet:0x...", // Machine Learning atom "did:ethr:mainnet:0x..." // Neural Networks atom ] } ``` ### Hierarchical Structure ```json { "content": "Artificial Intelligence", "children": [ "did:ethr:mainnet:0x...", // Machine Learning "did:ethr:mainnet:0x..." // Expert Systems ] } ``` ## Quality Guidelines ### Content Quality - Ensure accuracy and verifiability - Use clear, concise language - Provide sufficient context - Avoid redundant or duplicate atoms ### Technical Quality - Follow proper DID standards - Include comprehensive metadata - Use consistent data formats - Implement proper versioning ### Community Standards - Respect intellectual property - Avoid misleading or false information - Contribute to the ecosystem's growth - Engage with the community constructively --- ## Next Steps - [Atom Best Practices](./best-practices) - Detailed guidelines for effective Atom design - [Triple Fundamentals](../triples/fundamentals) - Learn how to connect Atoms into relationships - [Signal Fundamentals](../signals/fundamentals) - Understand how to measure Atom usage and relevance --- title: "Capturing Signal" description: "Advanced techniques for capturing and interpreting signal in the knowledge graph" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/intuition-concepts/primitives/Signals/capturing" --- # Capturing Signal This guide covers advanced techniques for capturing signal from users and interpreting signal data within the Intuition ecosystem. ## Signal Capture Mechanisms ### Direct Staking Users explicitly deposit tokens to signal support or opposition: ```typescript // Deposit into an Atom vault await deposit(atomVaultId, amount) // Deposit into a Triple vault (positive side) await deposit(tripleVaultIdFor, amount) // Deposit into counter-triple vault (negative side) await deposit(counterTripleVaultIdAgainst, amount) ``` ### Continuous Markets Staking is not a one-time vote but a continuous market: - Add more stake to increase your signal - Withdraw stake (with potential rewards or penalties) - Counter-stake on opposite sides for Triples - Market "odds" constantly adjust to reflect aggregated beliefs ## Interpreting Signal Strength ### Analyzing TVL (Total Value Locked) Higher TVL generally indicates: - Greater community interest - More economic backing - Higher perceived relevance or truth - Stronger consensus (for Triples) ### Consensus Metrics For Triples, analyze the balance between positive and negative vaults: ```typescript const consensusScore = positiveStake / (positiveStake + negativeStake) // Result between 0 and 1 // > 0.5 = net positive consensus // < 0.5 = net negative consensus // ≈ 0.5 = disputed/uncertain ``` ### Attestor Quality Consider not just the amount staked, but who is staking: - Number of unique attestors - Reputation of attestors - Historical accuracy of attestors - Domain expertise of attestors ## Advanced Applications ### Following Lists Instead of creating 1,000 separate "following" claims, use a single Triple: ``` [User X] - [following] - [Creator Y] ``` Multiple users adjust their balances on this Triple to express following. To see all followers, examine who has positive balances. ### Tiered Preferences Users can express varying levels of interest by staking different amounts: ```typescript // Strong support await deposit(tripleVaultId, 100) // Moderate support await deposit(tripleVaultId, 10) // Weak support await deposit(tripleVaultId, 1) ``` ### Prediction Markets Signal can function as a prediction market mechanism where: - Early accurate signals are rewarded - Later participants pay premium prices - Market prices reflect collective probability assessment ## Economic Dynamics ### Fee Distribution When someone stakes on an Atom or Triple: - Existing stakers earn fees from the new deposit - Fee amount depends on bonding curve position - Creates incentive to identify valuable data early ### Self-Refinement The economic model drives system improvement: 1. Stakers who identify valuable data earn more rewards 2. Stakers on unused data earn less 3. Useful information becomes economically advantageous to support 4. Irrelevant claims naturally receive less stake --- ## Next Steps - [Signal Rewards](./rewards) - Understand fee and reward calculations - [Signal Fundamentals](./fundamentals) - Review signal basics --- title: "Signal Fundamentals" description: "Understanding Signals - the trust and consensus layer of the knowledge graph" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/intuition-concepts/primitives/Signals/fundamentals" --- # Signal Fundamentals Signals represent the trust, confidence, or relevance that the community assigns to Atoms and Triples in the Intuition knowledge graph. Think of the knowledge graph as a weighted graph where Signal is the weight on each node (Atom) or edge (Triple), indicating how strongly people believe in or care about this information. ## Understanding Signals Signal, in the context of Intuition, refers to any action or indication that expresses intent, belief, or support. Signals can be classified into three broad categories: explicit signal, implicit signal, and transitive signal. Signals transform static data into a dynamic, trusted intelligence layer. When someone stakes tokens on an Atom or Triple, they emit a Signal expressing that they find that piece of information important or true. ## Types of Signal ### Explicit Signal A clear, intentional action taken by a user to express support, belief, or intent. These actions are directly observable and often involve a formal mechanism within the system. **Examples:** - Voting mechanisms - Signed attestations - Token staking - Direct claims ### Implicit Signal Indirect or inferred indications of support, belief, or intent. This signal is not always directly observable and is often deduced from user behavior or patterns. **Examples:** - Frequency of queries and references - Inclusion in other Triples - Application usage metrics - Usage patterns ### Transitive Signal Trust or belief that is passed along through a network of relationships. This type of signal leverages the idea that trust can be extended through connections. **Example:** If User A attests to something about User B, and User C trusts User A, then User C extends trust to User B. ## Signal in Intuition Though all systems naturally generate implicit signal, explicit signal in Intuition is expressed in a novel format that enables and incentivizes the creation of many-to-one, non-deterministic attestations. In Intuition, these semantic statements do not have a single 'issuer' - instead, anyone/anything can signal support or rejection of any existing statement/attestation at any point in time. ## How Signals are Created The core mechanism for creating signals is through **staking** (also called attesting). When you deposit tokens into an Atom's vault or a Triple's vaults, you're effectively buying "shares" in that piece of information. ### Staking Mechanics - **Atoms**: Each Atom has a single staking vault - **Triples**: Each Triple has two vaults (positive and negative) - **Shares**: Your stake represents proportional ownership and conviction For example: - Staking 100 TRUST on the Atom `[Ethereum]` gives you a fraction of total Atom Shares for `[Ethereum]` - Staking 50 TRUST on `[Alice] is Friend Of [Bob]` in the affirmative vault gives you Triple Shares supporting that friendship claim ### Bonding Curves The bonding curve mechanics mean share prices depend on existing stake levels: - Early stakers get better prices - Later stakers pay more for the same signal increment - This creates a perpetual prediction market for information ## Atom Signal Within the Intuition framework, users signal their belief in the relevance of an Atom by adjusting their balance on that Atom. **Balance Interpretation:** - **Zero Balance**: No signal, neutral stance - **Positive Balance**: Indicates belief in relevance (higher = stronger) - Users earn fees proportional to their ownership stake ## Triple Signal In the Intuition framework, users signal their belief in both the relevance and truthfulness of a Triple by modifying their balance on that Triple. **Triple Balance System:** - **Zero Balance**: No signal, neutral stance - **Positive Balance**: Affirms the Triple (considered true and relevant) - **Negative Balance**: Signals rejection (considered false but relevant) ### Example: Trustworthiness Triple For a Triple asserting `[Vitalik][is][trustworthy]`: - **Positive Balance**: Believes Vitalik is trustworthy - **Negative Balance**: Believes Vitalik is not trustworthy - **Zero Balance**: No opinion on trustworthiness ## Total Value Locked and Consensus Each Atom and Triple accrues **Total Value Locked (TVL)** in its vaults—a direct measure of tokenized trust. Higher TVL generally implies greater relevance or credibility. The consensus score weighs multiple variables: - Amount staked on each side - Number of distinct attestors - Past reliability (reputation) of attestors Creating an Atom or Triple is distinctly different from taking a position on them. While users have the option to both create and take a position at the time of creation, the Initial Deposit is not required. A user who makes no Initial Deposit will only create an Atom or Triple, which does not constitute a Signal. --- ## Next Steps - [Capturing Signal](./capturing) - Learn advanced techniques for signal capture - [Signal Rewards](./rewards) - Understand the economic incentives and reward distribution - [Atom Fundamentals](../atoms/fundamentals) - Review Atom basics - [Triple Fundamentals](../triples/fundamentals) - Review Triple basics --- title: "Signal Rewards" description: "Understanding fee structures and reward distribution for signal participants" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/intuition-concepts/primitives/Signals/rewards" --- # Signal Rewards Understanding the economic incentives and reward mechanisms is crucial for participating effectively in the Intuition signal economy. ## Fee Structure ### Entry Fees When a user deposits tokens into an Atom or Triple vault: - A small fee is charged on the deposit - Fee goes to existing vault shareholders - Incentivizes early discovery and staking ### Exit Fees When a user withdraws their stake: - A fee may be charged on redemption - Helps stabilize the vault - Discourages rapid speculation ### Protocol Fees A portion of fees goes to: - Protocol treasury - Development funding - Network maintenance ## Reward Distribution ### Share-Based Rewards When you stake on an Atom or Triple, you receive shares: ```typescript // Example reward calculation const yourShares = 45 const totalShares = 1000 const ownershipPercent = yourShares / totalShares // 4.5% // When new fees come in const newFees = 100 const yourReward = newFees * ownershipPercent // 4.5 tokens ``` ### Bonding Curve Dynamics The bonding curve affects both: - **Entry Price**: Later stakers pay more per share - **Exit Price**: Early stakers can exit at profit if TVL grew Example progression: 1. First staker: 100 tokens → 100 shares (1:1 ratio) 2. Second staker: 100 tokens → 90 shares (worse ratio) 3. Third staker: 100 tokens → 82 shares (even worse ratio) ### Value Flow Examples **Popular Identity Atom**: - Thousands of Triples reference it - Queries constantly traverse through it - Early stakers earn fees from every interaction **Valuable Triple**: - News services query it - Financial models reference it - Token holders earn from all usage ## Economic Incentives ### Early Discovery Rewards - First stakers get best prices - Accumulate more shares per token - Earn fees from all future stakers - Benefit from TVL growth ### Quality Curation Rewards - Staking on useful data generates ongoing fees - Popular Atoms/Triples attract more interaction - More interaction = more fees to distribute - Creates virtuous cycle for quality content ### Information as Asset Class This creates an economy where: - **Discovery is rewarded**: Find and stake on useful data early - **Curation has value**: Your stake helps validate quality - **Usage generates returns**: Popular data pays dividends - **Information becomes an asset**: Data literally has owners who profit from its use ## Calculating Expected Returns ### Factors Affecting Returns 1. **Your Share Percentage**: Higher ownership = more fees 2. **Vault Activity**: More deposits = more fees distributed 3. **Usage Frequency**: How often the data is queried/used 4. **Time in Vault**: Longer staking = more fee events ### Risk Considerations - **TVL Decline**: If others withdraw, share value may decrease - **Competition**: Similar Atoms/Triples may fragment interest - **Accuracy**: False claims may lose support over time - **Market Dynamics**: Bonding curve means exit prices vary ## Maximizing Rewards ### Strategies 1. **Early Identification**: Stake on valuable data before others 2. **Quality Focus**: Choose Atoms/Triples likely to be used 3. **Long-Term Holding**: Benefit from accumulated fees 4. **Diversification**: Spread stake across multiple entities ### Anti-Patterns to Avoid - Staking on duplicate/redundant data - Following hype without substance - Short-term speculation - Ignoring signal quality --- ## Next Steps - [Economics Overview](../../economics/bonding-curves) - Deep dive into bonding curve mechanics - [Fees & Rewards](../../economics/fees-rewards) - Detailed fee structure - [Signal Fundamentals](./fundamentals) - Review signal basics --- title: "Triple Fundamentals" description: "Understanding Triples - semantic relationships that form the knowledge graph" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/intuition-concepts/primitives/Triples/fundamentals" --- # Triple Fundamentals If Atoms are the words in Intuition's global dictionary, Triples are the sentences we create from those words. A Triple connects three Atoms to assert a relationship or fact in the form **[Subject] – [Predicate] – [Object]**. ## Understanding Triples A Triple is a fundamental data structure that expresses relationships between Atoms, following the classic RDF triple format used in semantic web technologies. This makes Intuition's data inherently machine-readable and structured. With discrete units of data established through Atoms, defining relationships between these units to form higher-order structures is essential. Intuition achieves this by employing Semantic Triples, ensuring a uniform and discrete structure that can be prescribed a decentralized identifier and have some associated agent-centric state. ## Triple Structure Triples consist of three elements: Subject, Predicate, and Object, with each element represented as an Atom. This Subject-Predicate-Object format allows users to clearly and explicitly define relationships between Atoms.Subject
The entity or concept being described in the relationship.Predicate
The relationship or attribute that connects the subject to the object.Object
The value or characteristic attributed to the subject through the predicate. Every Triple represents a claim—it asserts that a Subject has some relationship (Predicate) to an Object. For example: ``` [Alice] -- [lives In] --> [Paris] ``` This Triple asserts a fact about Alice's location, where: - **Alice** is the subject Atom - **livesIn** is the predicate Atom (describing the type of relationship) - **Paris** is the object Atom Each component of a Triple is an Atom ID under the hood. The system doesn't store free-form text "Alice" or "Paris" but rather pointers to those Atom records, which might contain rich data, alternate labels, and additional metadata. ## Example Triples ### Simple Triple Example ``` Subject: "Bob" Predicate: "age" Object: "34" ``` In this example, each component—Subject, Predicate, and Object is an Atom, and the Triple expresses a specific relationship between these Atoms. ### Professional Credential ``` [Dr. Smith] — [has degree] — [Harvard Medical School] ``` Expressing educational credentials as structured data. ### Smart Contract Deployment ``` [UniswapV3] — [was deployed on] — [2021-05-05] ``` Recording blockchain events as semantic relationships. ## Fractal Data Representations Triples offer a flexible yet structured method for representing data relationships. By allowing Triples to act as Atoms within other Triples, Intuition facilitates the expression, storage, and usage of arbitrarily complex data models that can scale and evolve over time. This flexibility is crucial for capturing intricate relationships and dynamics within data, enabling users to construct sophisticated applications and services on the Intuition framework. This approach maintains discrete, referenceable units for data at every layer of the structure, ensuring scalability and precision in data representation. ## The Graph Structure Triples naturally form a graph of nodes and links. You can visualize: - **Atoms as nodes** in the graph - **Triples as directed edges** from subject to object, labeled by the predicate This graph structure enables powerful capabilities: - Deterministic queries like "find all objects that Alice is connected to via livesIn" - Traversal of relationships to discover indirect connections - Pattern matching across the knowledge graph ## Triple Ownership and Token Curated Registries Akin to the process outlined for Atoms, the structure of Triples allows users to gain fractional ownership of Triples through interaction. Each interaction generates interaction fees, which are distributed to the owners of each respective Triple, creating an incentivized Token Curated Registry (TCR) for data structures. The TCR encourages system participants to adopt common ways of structuring data by offering economic rewards. This approach promotes an organic, incentive-driven structuring of data, contrasting with more rigid and traditional methods such as standards committees, which often struggle to achieve effective standardization. ## Integration with Other Primitives ### With Atoms - Triples connect Atoms into meaningful relationships - Atoms gain context through Triple connections - Triple predicates can themselves be Atoms for maximum flexibility ### With Signals - Signals add weight to Triple claims through staking - Community validates Triples through Signal attestations - Signal strength directly affects Triple credibility and consensus ## Summary Triples allow Intuition to form a living, searchable web of knowledge. When adding Triples, the goal is to make each claim as clear and verifiable as possible, selecting the right words (Atoms) from the global dictionary, and then letting the network of users and their Signals determine validity. With Atoms as the words in our global dictionary and Triples as the sentences we construct from them, we can express any arbitrarily-complex concept while maintaining discrete, referenceable structure. --- ## Next Steps - [Triple Structuring](./structuring) - Learn advanced techniques for creating effective Triples - [Nested Triples](./nested-triples) - Understand how to build complex, layered claims - [Signal Fundamentals](../signals/fundamentals) - Discover how the community validates Triples --- title: "Nested Triples" description: "Creating meta-claims and context through nested Triple structures" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/intuition-concepts/primitives/Triples/nested-triples" --- # Nested Triples # Nested Triples: Meta-Claims & Context One of Intuition's most powerful features is that Triples can reference other Triples, effectively nesting statements to provide context or provenance. Intuition supports using a Triple itself as a Subject or Object in another Triple. ## Understanding Nested Triples Think of it as linguistic compression—instead of repeatedly expressing complex relationships, you create them once and reference them by ID. A Triple about "Alice's employment at a specific company with particular conditions" becomes a single referenceable unit. That unit can then be used in higher-order statements about employment trends, verification claims, or temporal changes. This creates a hierarchy of meaning where complex ideas are built from simpler ones, yet each level remains independently addressable and verifiable. ## Example: Disputing a Claim Consider an initial Triple: ``` [Bob] -- [isFriendOf] --> [Alice] ``` If Alice disagrees with this claim, we can create a nested Triple: ``` [Alice] -- [disproves] --> (Bob isFriendOf Alice) ``` Here, the Object of the second Triple is not an Atom but a reference to the first Triple (identified by its Triple ID). Alice is essentially asserting that the friendship claim is false. ## Adding Evidence & Sources You can link Triples to evidence or citations: ``` [Triple X] -- [basedOn] --> [Document Y] ``` This ability to compose Triples into higher-order statements gives the graph a fractal quality—small facts build into bigger facts, and complex relationships can be broken down into simpler ones. ## Linguistic Compression The result is an extraordinarily efficient knowledge transmission system. Rather than sending verbose descriptions, systems can exchange compact Triple IDs that expand into rich, contextual information. Each ID carries with it not just data, but the entire graph of relationships, evidence, and community consensus that supports it. ## Use Cases ### Temporal Context ``` [[Alice works at Company X]] -- [valid from] --> [2024-01-01] [[Alice works at Company X]] -- [valid until] --> [2024-12-31] ``` ### Provenance Tracking ``` [[Ethereum is secure]] -- [claimed by] --> [Security Firm Y] [[Ethereum is secure]] -- [verified on] --> [2024-01-15] ``` ### Meta-Information ``` [[Product X is good]] -- [confidence level] --> [0.85] [[Product X is good]] -- [number of attestors] --> [150] ``` --- ## Next Steps - [Signal Fundamentals](../signals/fundamentals) - Learn how the community validates nested claims - [Triple Structuring](./structuring) - Review best practices for Triple design --- title: "Triple Structuring" description: "Advanced techniques for structuring effective Triples in the knowledge graph" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/intuition-concepts/primitives/Triples/structuring" --- # Triple Structuring Understanding how to properly structure Triples is essential for building rich, queryable knowledge graphs. This guide covers techniques for creating well-designed semantic relationships. ## Basic Triple Structure ```json { "id": "did:ethr:mainnet:0x...", "subject": "did:ethr:mainnet:0x...", "predicate": "did:ethr:mainnet:0x...", "object": "did:ethr:mainnet:0x...", "metadata": { "created": "2024-01-15T10:30:00Z", "creator": "did:ethr:mainnet:0x...", "confidence": 0.95 } } ``` ## Triple Categories ### 1. Property Triples Describe attributes or characteristics of entities. **Example**: "Ethereum is decentralized" ```json { "subject": "did:ethr:mainnet:0x...", // Ethereum "predicate": "did:ethr:mainnet:0x...", // is "object": "did:ethr:mainnet:0x...", // decentralized "type": "property" } ``` ### 2. Relationship Triples Connect entities through specific relationships. **Example**: "Vitalik Buterin created Ethereum" ```json { "subject": "did:ethr:mainnet:0x...", // Vitalik Buterin "predicate": "did:ethr:mainnet:0x...", // created "object": "did:ethr:mainnet:0x...", // Ethereum "type": "relationship" } ``` ### 3. Classification Triples Establish hierarchical or categorical relationships. **Example**: "Machine Learning is a subset of AI" ```json { "subject": "did:ethr:mainnet:0x...", // Machine Learning "predicate": "did:ethr:mainnet:0x...", // is a subset of "object": "did:ethr:mainnet:0x...", // AI "type": "classification" } ``` ## Creating Triples Programmatically ### Using the SDK ```typescript import { createAtomFromString, createTripleStatement } from '@0xintuition/sdk' import { createPublicClient, createWalletClient, http } from 'viem' import { privateKeyToAccount } from 'viem/accounts' import { sepolia } from 'viem/chains' import { getEthMultiVaultAddressFromChainId } from '@0xintuition/sdk' // Configure viem clients const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`) const walletClient = createWalletClient({ account, chain: sepolia, transport: http() }) const publicClient = createPublicClient({ chain: sepolia, transport: http() }) // Get MultiVault address const multivaultAddress = getEthMultiVaultAddressFromChainId(sepolia.id) // Create a Triple const result = await createTripleStatement( { walletClient, publicClient, address: multivaultAddress }, subjectVaultId, predicateVaultId, objectVaultId ) ``` ## Best Practices ### 1. Use Atomic Components - Each component (subject, predicate, object) should be a focused Atom - Avoid embedding complex data in individual components - Leverage reusable Atoms for common concepts ### 2. Choose Clear Predicates - Use widely understood relationship terms - Be specific but not overly verbose - Consider standardizing on common predicates ### 3. Maintain Consistency - Follow naming conventions across related Triples - Use consistent data types - Align with community standards ### 4. Enable Composability - Design Triples that can combine with others - Consider how Triples might be queried together - Think about nested Triple possibilities --- ## Next Steps - [Nested Triples](./nested-triples) - Learn how to create meta-claims and context - [Signal Fundamentals](../signals/fundamentals) - Understand how to validate Triples --- title: "Primitives" description: "Understanding Intuition's core primitives - Atoms, Triples, and Signals - the building blocks of a decentralized knowledge graph" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/intuition-concepts/primitives" --- # Primitives # Primitives Overview Intuition's data model is built on three fundamental primitives that work together to create a rich, self-regulating knowledge graph. These primitives form the foundation of the ecosystem and enable the creation of a structured, semantic web of trust.Atoms
The basic entities or identifiers - unique decentralized identifiers for everything in existence. Think of them as the nodes in the knowledge graph, or the words in the dictionary. Atoms are Intuition's atomic unit of knowledge, enabling unique, persistent, canonical identifiers for all things - not just people.Triples
Structured relationships or claims linking entities together in Subject-Predicate-Object format. These are the edges in the knowledge graph / the sentences in the language of Intuition. A composition of Atoms - defined as Semantic Triples which represent the relationships between Atoms.Signals
The weight of Atoms and Triples, derived from the total amount of ETH deposited in Atom and Triple Vaults. These represent the edge weights in the graph, or 'who is saying what about what, with what level of conviction'. The weight of trust or consensus behind each entity or claim, determined by community staking. --- ## The Three Primitives Explained ### Atoms: Universal Identifiers for Everything An **Atom** is a unique decentralized identifier that can reference literally anything – from people and organizations to concepts, data points, or even raw bytes of information. Each Atom acts as a globally referenceable identity in the Intuition system, with an on-chain ID that serves as its permanent, verifiable address. The digital universe is vast, where everything from tangible objects to abstract concepts can be endowed with a digital identity. Atoms confer unique recognition and definition to persons, places, ideas, or even memes, ensuring each entity's distinct presence. Within Intuition, every Atom is secured by a unique DID (Decentralized Identifier) and an Ethereum wallet address, establishing a verifiable foundation. Unlike traditional identifiers that are limited to URIs or specific data formats, Atoms can point to **arbitrary data (bytes)**. This means an Atom can reference: - **Raw strings**: Direct text like "Alice", "is friend of", or "2024-01-15" - **URIs**: Web pages, IPFS hashes, blockchain addresses - **Binary data**: Images, documents, encrypted content - **Structured data**: JSON objects, protocol buffers, or any serialized format - **Abstract concepts**: Ideas, emotions, or theoretical constructs #### Real-World Atom Examples **Person Atom** ``` Atom ID: 0x123... Data: "alice.eth" (ENS name as raw string) ``` **Concept Atom** ``` Atom ID: 0x456... Data: "trustworthy" (abstract quality) ``` **Data Hash Atom** ``` Atom ID: 0x789... Data: 0xabcd...ef12 (IPFS content hash as bytes) ``` **Date Atom** ``` Atom ID: 0xabc... Data: "2024-01-15T09:00:00Z" (ISO timestamp) ``` **Smart Contract Atom** ``` Atom ID: 0xdef... Data: 0x742d35...8930 (Ethereum contract address) ``` Atoms are sometimes called "identities" in the protocol because they give any entity – whether tangible or abstract – a persistent, verifiable digital identity that can be referenced and validated by anyone in the network. Atoms are categorized into three primary roles within semantic structures: **Subjects**, **Predicates**, and **Objects**. This structure facilitates the creation of **Triples** that articulate specific assertions or facts about the world. --- ### Triples: Expressing Relationships as Claims A **Triple** is a structured claim that follows the semantic format of **[Subject] – [Predicate] – [Object]**, where each component is itself an Atom. This creates a precise, machine-readable way to express facts, relationships, and assertions about the world. Triples are higher-order structures within Intuition, used to define relationships between Atoms. Each Triple consists of three components: a Subject, Predicate, and Object, all of which are Atoms. This structure enables precise, machine-readable representations of data, facilitating complex and interconnected attestations. #### Example Triple Structures **Social Relationship** [Alice] — [is friend of] — [Bob] **Professional Credential** [Dr. Smith] — [has degree] — [Harvard Medical School] **Smart Contract Deployment** [UniswapV3] — [was deployed on] — [2021-05-05] **Product Rating** [iPhone 15] — [has rating] — [4.5 stars] Triples can reference other Triples as Atoms, enabling arbitrarily complex statements. For example: ``` [[Alice is friend of Bob]] — [was established on] — [2024-01-01] ``` This meta-claim adds temporal context to the friendship relationship. Triples can be used as Atoms in other Triples, allowing for the expression of arbitrarily complex statements in a standardized format. In many contexts, Triples are also referred to as **Claims** or **Attestations** because they represent assertions that can be verified, disputed, or supported by the community. --- ### Signals: Quantified Trust Through Staking **Signal** represents the aggregated attestation state of an Atom or Triple – essentially, how much the community trusts or believes in that piece of information. Signal is generated through economic staking, where users deposit tokens into an entity's vault to express their conviction. Signal in Intuition refers to any action that expresses intent, belief, or support within the system. Signals can be explicit, such as voting mechanisms or signed attestations, or implicit, inferred from user behavior.Positive Signal
Users stake tokens to support an Atom or Triple, indicating they believe it's true, valuable, or important.Counter Signal
Users can stake against claims they disagree with, creating a market for truth discovery.Dynamic Updates
Signal changes in real-time as users stake, withdraw, or shift their positions, creating a living consensus. #### How Signal Works 1. **Staking Mechanism**: Users deposit tokens into Atom or Triple vaults 2. **Weight Calculation**: More stake = stronger signal of trust/importance 3. **Relative Comparison**: Signal strength is evaluated relative to alternatives 4. **Economic Incentives**: Stakers earn fees from future deposits, encouraging early and accurate signaling #### Signal Mechanisms Users hold positions on Atoms and Triples, signaling their stance by increasing their balance on the relevant entities. Signals contribute to the nuanced expression of trust and belief, allowing for a dynamic and tiered system of preferences within the decentralized ecosystem. Creating an Atom or Triple is distinctly different from taking a position on them. While users have the option to both create and take a position on an Atom/Triple at the time of creation, this Initial Deposit is not required. A user who makes no Initial Deposit will only create an Atom or Triple, which does not constitute a Signal. --- ## How the Primitives Work Together The true power of Intuition emerges when these three primitives interact: ### Many-to-One Attestations Unlike traditional systems where a single authority issues certificates or attestations, Intuition enables many-to-one non-deterministic attestations: - Multiple Validators - Weighted Consensus - No Single Point of Failure - Dynamic Evolution ### Composition of Knowledge Acknowledging the potential for any entity, concept, or piece of data to hold a digital identity opens the door to collaboratively crafting an expansive knowledge graph. By arranging Atoms into Triples, we co-create a graph mapping out entities' interrelations and factual, verifiable assertions about the world. ### Example: Building a Reputation Graph Consider how these primitives combine to create a decentralized reputation system: In this example: - **Atoms** define the entities (Alice, developer, React) - **Triples** express relationships (Alice is a developer, Alice knows React) - **Signals** quantify community confidence (1000 TRUST backs the developer claim) --- ## Key Benefits of This ArchitectureUniversal Composability
Any data type can become an Atom, and any relationship can be expressed as a Triple, creating infinite possibilities for knowledge representation.Self-Regulating Truth
Economic incentives through Signal staking create a market for truth, where accurate information naturally accumulates more support.Interoperability
Standardized semantic structure enables different applications to understand and build upon the same knowledge graph.Progressive Trust
Trust isn't binary – it's a spectrum measured by Signal strength, allowing for nuanced representation of confidence and belief. --- ## Getting Started with Primitives To begin working with Intuition's primitives, consider these pathways: ### For Developers 1. **Create Atoms** for entities in your domain (users, products, concepts) 2. **Define Triples** to express relationships between those entities 3. **Monitor Signals** to understand community consensus 4. **Build applications** that leverage the knowledge graph ### For Users 1. **Discover existing Atoms** relevant to your interests 2. **Stake on Triples** you believe are true or important 3. **Create new Claims** to contribute knowledge 4. **Earn rewards** from successful early signaling ### For Data Scientists 1. **Analyze Signal patterns** to identify emerging truths 2. **Query the Triple graph** for relationship insights 3. **Track Atom evolution** over time 4. **Build prediction models** based on Signal dynamics --- ## Explore PrimitivesAtoms
Deep dive into Atoms - the fundamental building blocks. Learn about their structure, design principles, and best practices for creating effective Atoms.Triples
Explore Triples - semantic relationships between Atoms. Understand how to structure complex claims, work with nested triples, and query the knowledge graph.Signals
Master Signals - the trust layer. Learn about staking mechanisms, signal interpretation, reward distribution, and how to leverage signals for consensus. --- The beauty of Intuition's primitives lies in their simplicity and composability. Three simple concepts – Atoms, Triples, and Signals – combine to create a powerful system for decentralized knowledge and trust. --- title: "Trust Mechanisms Overview" description: "Understanding how trust and attestation work in the Intuition ecosystem" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/intuition-concepts/trust-mechanisms" --- # Trust Mechanisms Overview Intuition creates a decentralized trust layer through its primitives and economic incentives. This guide explains how trust emerges and is validated in the system. ## Many-to-One Attestations Unlike traditional systems where a single authority issues certificates or attestations, Intuition enables **many-to-one non-deterministic attestations**: ### Key Characteristics - **Multiple Validators**: Any number of users can signal their belief - **Weighted Consensus**: Aggregate signal determines confidence level - **No Single Point of Failure**: Truth emerges from collective validation - **Dynamic Evolution**: Attestations change as new information emerges ## Trust Generation Mechanisms ### Explicit Trust Direct attestations through staking: - Users lock tokens to express belief - Economic skin in the game - Clear, verifiable positions - Trackable over time ### Implicit Trust Derived from usage patterns: - Frequency of references - Inclusion in applications - Query patterns - Network effects ### Transitive Trust Trust propagates through relationships: - Trusted sources carry more weight - Web-of-trust effects - Personalized trust graphs - Reality Tunnels leverage this ## Attestation Types ### Identity Attestations Verifying entities are who they claim: ``` [Address X] - [is controlled by] - [Person Y] [Account] - [verified by] - [KYC Provider] ``` ### Fact Attestations Asserting truth of statements: ``` [Company X] - [acquired] - [Company Y] [Event Z] - [occurred on] - [Date] ``` ### Credential Attestations Verifying qualifications: ``` [Person] - [has degree from] - [University] [Developer] - [contributed to] - [Project] ``` ## Trust Evaluation ### Factors Considered 1. **Stake Amount**: Economic backing of claim 2. **Attestor Quality**: Reputation and history 3. **Attestor Diversity**: Number of independent validators 4. **Time Factor**: How long has consensus held 5. **Counter-Signal**: Strength of opposing views ### Consensus Calculation ```typescript // Example simplified consensus const totalFor = sumStakes(positiveAttestors) const totalAgainst = sumStakes(negativeAttestors) const consensus = totalFor / (totalFor + totalAgainst) // Weighted by attestor reputation const weightedConsensus = sumWeightedStakes(attestors, reputations) ``` ## Trust Discovery ### Finding Trusted Data Users can filter information by trust criteria: ```typescript // Minimum trust thresholds const trustedClaims = query({ minStake: 10000, minConsensus: 0.8, minAttestors: 10 }) // Specific attestor requirements const verified = query({ requireSignalFrom: ["Official Source", "Domain Expert"] }) ``` ### Reality Tunnels Create personalized trust lenses: - Define whose signals matter to you - Weight different attestor types - Filter based on trust criteria - Multiple valid worldviews ## Verification Mechanisms ### On-Chain Verification - All stakes are transparent - View who attested to what - See stake amounts and timing - Verify bonding curve positions ### Off-Chain Verification - IPFS-stored data integrity - DID document validation - External source linking - Cross-reference checking ## Trust Building Over Time ### Reputation Accumulation - Consistent accurate signals build reputation - Early correct attestations rewarded - Historical track record visible - Stake-weighted influence ### Network Effects - More participants increase reliability - Diverse attestors strengthen consensus - Cross-validation improves accuracy - System self-improves ## Trust Anti-Patterns ### Centralization Risks - Whale dominance - Cartel formation - Sybil attempts - Mitigated through diverse signals ### Quality Issues - Popularity ≠ accuracy - Echo chambers - Misinformation campaigns - Addressed through counter-signals --- ## Next Steps - [Signal Fundamentals](../primitives/signals/fundamentals) - How trust is expressed - [Architecture Overview](../architecture/system-design) - System design for trust - [Economics](../economics/bonding-curves) - Economic trust incentives --- title: "Intuition Network" description: "Intuition Network architecture and infrastructure" last_updated: "2026-02-11T09:19:02-05:00" source: "https://docs.intuition.systems/docs/intuition-network" --- # Intuition Network Intuition Network is a specialized Layer 3 blockchain built on Arbitrum Orbit, optimized for knowledge graph operations and decentralized attestations. ## Architecture Intuition leverages a multi-layer architecture designed for performance, cost-efficiency, and scalability: - **Layer 3 on Base** - Built using Arbitrum Orbit technology - **AnyTrust DA** - Arbitrum's data availability solution for scalability - **Specialized for Knowledge Graphs** - Optimized for semantic triple operations - **EVM Compatible** - Full Ethereum smart contract compatibility ### Performance Benefits - **~10,000x cheaper** than Ethereum mainnet - **~100x faster** transaction times - **Block time:** ~2 seconds - **Transaction finality:** Less than 10 seconds - **Throughput:** 1000+ TPS ## Network Details **For developer setup and configuration, see:** [Network Configuration](/docs/quick-start/network-details) ### Testnet The Intuition testnet is currently active for development and testing. - **Chain ID:** 13579 - **RPC URL:** https://testnet.rpc.intuition.systems/ - **Explorer:** https://testnet.explorer.intuition.systems - **Currency:** tTRUST (testnet TRUST) **Testnet Tools:** - **Portal** - Web interface for creating atoms and triples - **Bridge** - Token bridge from Base Sepolia - **Explorer** - Blockchain explorer at https://testnet.explorer.intuition.systems - **RPC Endpoints** - API access via https://testnet.rpc.intuition.systems/ ### Mainnet > Coming soon! Testnet is currently active for development. ## Running a Node Want to run your own Intuition node for indexing and querying the knowledge graph? **Node Setup** - Contact support for node setup information Running a node provides: - **Full data access** - Complete knowledge graph indexing - **Custom queries** - Direct database access - **GraphQL API** - Self-hosted query capabilities - **Privacy** - No reliance on third-party infrastructure ## Infrastructure Components ### RPC Endpoints Managed infrastructure providing API access to the network: - **HTTP RPC:** For standard web3 calls - **WebSocket RPC:** For real-time subscriptions - **Rate limiting:** Fair usage policies apply Use the RPC endpoint at https://testnet.rpc.intuition.systems/ for development. ### Indexing Layer The Rust-based indexing subnet provides: - **Fast queries** - Optimized database for knowledge graph traversal - **GraphQL API** - Flexible query language for complex graph operations - **Real-time updates** - Live data synchronization - **Semantic search** - Full-text search across atoms and triples Learn more: [GraphQL API](/docs/graphql-api/overview) ### Settlement Layer Transactions settle to Base (via Base Sepolia for testnet): - **Security inheritance** - Leverages Ethereum's security - **Data availability** - AnyTrust committee ensures data availability - **Fraud proofs** - Optimistic rollup security model ## Network Economics ### Gas Costs Gas costs on Intuition are dramatically lower than Ethereum: - **Atom creation:** ~1/10,000th the cost - **Triple creation:** ~1/10,000th the cost - **Vault operations:** ~1/10,000th the cost ### Native Token **$TRUST** is the native token of Intuition Network: - **Gas fees** - Pay for transactions - **Staking** - Signal on atoms and triples - **Governance** - (Coming soon) See [Signals](/docs/intuition-concepts/primitives/Signals/fundamentals) for information about staking and token usage. ## Getting Started ### For Users 1. **[Connect to Testnet](/docs/resources/faq#how-do-i-connect-to-the-intuition-testnet)** - Setup your wallet 2. **[Get Test Tokens](https://intuition-testnet.hub.caldera.xyz/)** - Use the faucet 3. **Explore Tools** - Use Portal and Explorer to interact with the network ### For Developers 1. **[Network Configuration](/docs/quick-start/network-details)** - Configure your environment 2. **[SDK Setup](/docs/intuition-sdk/installation-and-setup)** - Install development tools 3. **[Quickstart Guide](/docs/quick-start/using-the-sdk)** - Build something! ### For Node Operators Contact support for node setup and deployment information. ## Support & Monitoring - **[Network Status](https://status.intuition.systems)** - Real-time status monitoring - **[Community Support](/docs/resources/community-and-support)** - Get help - **[FAQ](/docs/resources/faq)** - Common questions ## Next StepsConfigure Development
Set up your development environment to start building on Intuition.Run a Node
Self-host the indexing layer for direct database access and GraphQL API.Use Testnet Tools
Access Portal, Bridge, Explorer, and other testnet services. --- title: "Intuition Mainnet" description: "Welcome to the Intuition Mainnet - your development and testing environment for building on the Intuition Network." last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/intuition-network/mainnet" --- # Intuition Mainnet Welcome to the Intuition Mainnet - your development and testing environment for building on the Intuition Network. Intuition leverages **Caldera's Metalayer** infrastructure to provide seamless cross-chain bridging capabilities. As part of Caldera's **Internet of Chains**, we benefit from a robust, interconnected ecosystem of blockchain networks. ## Network Configuration | Parameter | Value | |-----------|-------| | **Network Name** | Intuition Mainnet | | **Chain ID** | 1155 | | **Native Token** | $TRUST | | **RPC URL** | `https://rpc.intuition.systems/http` | | **WebSocket URL** | `wss://rpc.intuition.systems/ws` | | **Block Explorer** | [https://explorer.intuition.systems](https://explorer.intuition.systems) | ## Bridging & Hub Vist the Intuition Testnet Hub at: - [https://hub.intuition.systems](https://hub.intuition.systems) - [https://intuition.hub.caldera.xyz/](https://intuition.hub.caldera.xyz) The hub creates essential information about the network plus actions like easily adding network details to a wallet and bridging assets between Intuition Mainnet and Base Mainnet. **You can bridge assets between Intuition Mainnet and Base Mainnet using the hub.** ## Explorer Access the Intuition Testnet Explorer directly at: - [https://explorer.intuition.systems](https://explorer.intuition.systems) The Intuition Explorer is a comprehensive blockchain explorer built on Blockscout, providing detailed insights into all network activity on the Intuition testnet. Monitor transactions, explore blocks, and analyze network performance with this powerful exploration tool. ## RPC Access the Intuition Testnet RPC directly at: - [https://rpc.intuition.systems/http](https://rpc.intuition.systems/http) The Intuition RPC accepts JSON-RPC requests and returns JSON-RPC responses. It provides programmatic access to the Intuition network. --- title: "Powered By Caldera" description: "The Intuition Network is powered by Caldera's Metalayer, a cross-chain infrastructure that enables seamless asset transfers between different blockchain networks." last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/intuition-network/powered-by-caldera" --- # Powered By Caldera ### Intuition is Powered by Caldera's Metalayer The Intuition Network is powered by Caldera's Metalayer, a cross-chain infrastructure that enables seamless asset transfers between different blockchain networks. ### What is Caldera's Metalayer? The Metalayer is Caldera's innovative cross-chain infrastructure that enables: - **Unified Bridging**: A single interface for transferring assets across multiple chains in the Caldera ecosystem - **Shared Security**: Leveraging collective security models across interconnected chains - **Interoperability**: Native communication between different blockchain networks without complex integrations - **Simplified UX**: One-click bridging experiences that abstract away technical complexity ### The Internet of Chains Caldera's Internet of Chains represents a new paradigm in blockchain connectivity: - **Network Effects**: Each new chain added to the ecosystem increases the value for all participants - **Composability**: Applications can seamlessly interact across different chains without friction - **Shared Liquidity**: Assets can flow freely between chains, improving capital efficiency - **Unified Standards**: Common protocols and standards across all connected chains ### Benefits for Intuition Users By being part of this ecosystem, Intuition users gain: - **Access to Multiple Networks**: Bridge assets from any chain in the Caldera network - **Lower Costs**: Shared infrastructure reduces operational costs - **Enhanced Security**: Battle-tested bridge infrastructure used by multiple production networks - **Future Connectivity**: Automatic access to new chains as they join the ecosystem ### How It Works The Metalayer uses advanced cryptographic techniques and consensus mechanisms to ensure: 1. **Asset Security**: Multi-signature validation and fraud proofs protect bridged assets 2. **Fast Finality**: Optimized confirmation times for cross-chain transfers 3. **Reliability**: Redundant infrastructure ensures high availability 4. **Transparency**: All bridge operations are verifiable on-chain ### Learn More - [Caldera Documentation](https://docs.caldera.xyz) - [Internet of Chains Overview](https://caldera.xyz/internet-of-chains) - [Bridge Technical Specifications](https://docs.caldera.xyz/metalayer) ## Support Need help? Join our [Discord](https://discord.gg/RgBenkX4mx) community for support. --- title: "Remote Procedure Call (RPC)" description: "The Intuition RPC (Remote Procedure Call) service provides programmatic access to the Intuition network." last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/intuition-network/rpc" --- # Remote Procedure Call (RPC) The Intuition RPC (Remote Procedure Call) service provides programmatic access to the Intuition network. RPC endpoints allow developers and applications to: - Query blockchain data - Submit transactions - Monitor network state - Access historical data - Interact with smart contracts ## Available Endpoints ### Core RPC Methods - **eth_getBalance**: Get account balance - **eth_getBlockByNumber**: Retrieve block information - **eth_getTransactionByHash**: Get transaction details - **eth_sendRawTransaction**: Submit signed transactions - **eth_call**: Execute contract calls - **eth_getLogs**: Retrieve event logs ## Usage Examples Using the `viem` library: ```javascript import { createPublicClient, http } from 'viem' import { mainnet } from 'viem/chains' const client = createPublicClient({ chain: mainnet, transport: http('https://1.rpc.thirdweb.com/...'), }) ``` Using the `ethers` library: ```javascript import ethers from 'ethers'; // Connect to Intuition RPC const provider = new ethers.providers.JsonRpcProvider( 'https://rpc.intuition.network' ); // Query account balance const balance = await provider.getBalance(address); // Get latest block const block = await provider.getBlock('latest'); ``` ## Authentication RPC access requires authentication for production use: --- title: "Intuition Testnet" description: "Welcome to the Intuition Testnet - your development and testing environment for building on the Intuition Network." last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/intuition-network/testnet" --- # Intuition Testnet Welcome to the Intuition Testnet - your development and testing environment for building on the Intuition Network. Intuition leverages **Caldera's Metalayer** infrastructure to provide seamless cross-chain bridging capabilities. As part of Caldera's **Internet of Chains**, we benefit from a robust, interconnected ecosystem of blockchain networks. ## Network Configuration | Parameter | Value | |-----------|-------| | **Network Name** | Intuition Testnet | | **Chain ID** | 13579 | | **Native Token** | $TTRUST | | **RPC URL** | `https://testnet.rpc.intuition.systems/http` | | **WebSocket URL** | `wss://testnet.rpc.intuition.systems/ws` | | **Block Explorer** | [https://explorer.intuition.systems](https://explorer.intuition.systems) | ## Bridging & Hub Vist the Intuition Testnet Hub at: - [https://testnet.hub.intuition.systems](https://testnet.hub.intuition.systems) - [https://intuition-testnet.hub.caldera.xyz/](https://intuition-testnet.hub.caldera.xyz/) The hub creates essential information about the network plus actions like easily adding network details to a wallet and bridging assets between Intuition Testnet and Base Sepolia. ## Explorer Access the Intuition Testnet Explorer directly at: - [https://testnet.explorer.intuition.systems](https://testnet.explorer.intuition.systems) - [https://testnet.rpc.intuition.systems](https://testnet.rpc.intuition.systems) The Intuition Explorer is a comprehensive blockchain explorer built on Blockscout, providing detailed insights into all network activity on the Intuition testnet. Monitor transactions, explore blocks, and analyze network performance with this powerful exploration tool. ## RPC Access the Intuition Testnet RPC directly at: - [https://testnet.rpc.intuition.systems/http](https://testnet.rpc.intuition.systems/http) The Intuition RPC accepts JSON-RPC requests and returns JSON-RPC responses. It provides programmatic access to the Intuition network. --- title: "Run on Kubernetes Cluster" description: "A comprehensive Kubernetes-based deployment infrastructure for blockchain indexing and data services, managed with ArgoCD and Terraform." last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/intuition-node/kubernetes" --- # Run on Kubernetes Cluster A comprehensive Kubernetes-based deployment infrastructure for blockchain indexing and data services, managed with ArgoCD and Terraform. ## Architecture Overview This project deploys a complete blockchain indexing platform on Google Cloud Platform (GCP) using: - **GKE Cluster**: Multi-node pool Kubernetes cluster - **ArgoCD**: GitOps-based continuous deployment - **Terraform**: Infrastructure as Code for GCP resources - **Kustomize**: Kubernetes manifest management ## Core Services ### Data Layer - **TimescaleDB**: Time-series database with PostgreSQL extensions and AI capabilities - **Indexer Database**: Dedicated database for blockchain indexing operations ### Application Services - **GraphQL Engine**: Hasura GraphQL API for data access - **IPFS Node**: InterPlanetary File System for decentralized storage - **Safe Content Service**: Content validation and processing - **TimescaleDB Vectorizer Worker**: Vector processing for AI/ML workloads - **Histocrawler**: Historical data crawling and indexing service - **Image Guard**: Image validation and security service - **RPC Proxy**: Blockchain RPC request routing and caching ### Consumer Services - **Decoded Consumer**: Blockchain event decoding and processing - **IPFS Upload Consumer**: IPFS content upload and management - **Resolver Consumer**: Data resolution and lookup services ### Management Tools - **pgAdmin**: PostgreSQL administration interface - **Ingress Controller**: Traffic routing and load balancing ## Infrastructure Components ### GKE Cluster Suggested Configuration - **Region**: `us-west2` - **Project**: `be-cluster` - **Network**: Custom VPC with private/public subnets - **Node Pools**: - `db-pool`: n2-standard-16 (dedicated for databases) - `app-pool`: e2-standard-2 (application services) - `consumer-pool`: custom-4-8192 (data processing) ### Storage - **Persistent Volumes**: GCP Persistent Disk with resizable storage class - **IPFS Storage**: 50Gi persistent volume for IPFS data - **Database Storage**: 50Gi for TimescaleDB ## Project Structure ``` gcp-deployment/ ├── apps/ # Kubernetes applications │ ├── consumers/ # Data processing consumers │ │ ├── decoded/ # Blockchain event decoder │ │ ├── ipfs-upload/ # IPFS upload processor │ │ └── resolver/ # Data resolver service │ ├── graphql/ # Hasura GraphQL engine │ ├── histocrawler/ # Historical data crawler │ ├── image-guard/ # Image validation service │ ├── indexer-db/ # Indexer database │ ├── ipfs/ # IPFS node │ ├── pgadmin/ # PostgreSQL admin │ ├── rpc-proxy/ # RPC request proxy │ ├── safe-content/ # Content validation service │ ├── timescale_db/ # TimescaleDB instance │ ├── timescale_db_vectorizer/ # Vector processing │ └── ingress/ # Ingress configuration ├── argocd/ # ArgoCD configuration │ ├── coreapps/ # Core application definitions │ ├── namespacedapps/ # Namespace-specific apps │ ├── projects/ # ArgoCD project definitions │ └── repos/ # Repository secrets ├── terraform/ # Infrastructure as Code │ └── debug-gke/ # GKE cluster provisioning └── test-kustomize/ # Kustomize testing ``` ## Quick Start ### Prerequisites - Google Cloud SDK - Terraform >= 1.0 - kubectl - ArgoCD CLI ### 1. Deploy Infrastructure ```bash cd terraform/debug-gke terraform init terraform plan terraform apply ``` ### 2. Configure ArgoCD ```bash # Get GKE credentials gcloud container clusters get-credentials debug-cluster --region us-west2 # Install ArgoCD kubectl create namespace argocd kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml # Apply ArgoCD configuration kubectl apply -f argocd/ ``` ### 3. Deploy Applications Applications are automatically deployed via ArgoCD GitOps. The system monitors the Git repository and applies changes automatically. ## Configuration ### Environment Variables Key services require environment-specific configuration: - **GraphQL Engine**: Database connection, CORS settings - **TimescaleDB**: PostgreSQL credentials, AI extensions - **IPFS**: Storage paths, network configuration - **Safe Content**: Content validation rules - **Histocrawler**: Blockchain endpoints, indexing parameters - **Image Guard**: Image scanning policies, security rules - **RPC Proxy**: Upstream RPC endpoints, caching configuration - **Consumers**: Event processing queues, database connections ### Secrets Management Secrets are managed through Kubernetes secrets and external secret providers: - Database credentials - API keys - Service account tokens ## Monitoring & Observability ### Health Checks - Liveness probes configured for all services - Readiness probes for database services - Custom health endpoints for GraphQL and IPFS ### Logging - Structured logging enabled for GraphQL engine - Query logging for debugging - WebSocket and HTTP request logging ## Security ### Network Security - Private GKE cluster with private nodes - VPC-native networking - NAT gateway for outbound internet access - Ingress controller for external access ### Access Control - Workload Identity for GCP service accounts - Kubernetes RBAC - ArgoCD project-based access control ## Development ### Local Development ```bash # Test Kustomize configurations cd test-kustomize kubectl kustomize . | kubectl apply --dry-run=client # Validate manifests kubectl kustomize apps/graphql/ | kubectl apply --dry-run=client ``` ### Adding New Services 1. Create service directory in `apps/` 2. Add Kubernetes manifests (deployment, service, etc.) 3. Create ArgoCD application definition 4. Update project permissions if needed ## CI/CD Pipeline The deployment follows GitOps principles: 1. Code changes pushed to Git repository 2. ArgoCD detects changes automatically 3. Applications updated in Kubernetes cluster 4. Health checks validate deployment ## Scaling ### Horizontal Scaling - Application services can scale horizontally via HPA - Database services use StatefulSets for data persistence - IPFS and GraphQL support multiple replicas ### Vertical Scaling - Node pools can be resized via Terraform - Storage volumes support online resizing - Resource limits configured per service ## Troubleshooting ### Common Issues 1. **Database Connection**: Check TimescaleDB service and secrets 2. **IPFS Storage**: Verify PVC and storage class 3. **GraphQL Health**: Check liveness probe and database connectivity 4. **ArgoCD Sync**: Verify repository access and permissions 5. **Consumer Processing**: Check event queue connectivity and processing status 6. **Histocrawler**: Verify blockchain endpoint accessibility 7. **Image Guard**: Check image scanning service health 8. **RPC Proxy**: Validate upstream RPC endpoint connectivity ### Debug Commands ```bash # Check pod status kubectl get pods -A # View logs kubectl logs -f deployment/graphql-engine # Check ArgoCD applications argocd app list # Validate Terraform state terraform plan ``` ## Additional Resources - [GKE Documentation](https://cloud.google.com/kubernetes-engine/docs) - [ArgoCD User Guide](https://argo-cd.readthedocs.io/) - [TimescaleDB Documentation](https://docs.timescale.com/) - [Hasura GraphQL Engine](https://hasura.io/docs/) - [Hasura Documentation](https://hasura.io/docs/) - [Alchemy Dashboard](https://dashboard.alchemy.com/) - [Pinata Documentation](https://docs.pinata.cloud/) --- title: "Local Development Setup" description: "Set up your local environment for developing and testing Intuition node services." last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/intuition-node/local-setup" --- # Local Development Setup Set up your local environment for developing and testing Intuition node services. ### Using Local Ethereum Node Add to your `.env` file: ```bash INTUITION_CONTRACT_ADDRESS=0xB92EA1B47E4ABD0a520E9138BB59dBd1bC6C475B START_BLOCK=0 ``` Create local test data: ```bash cd integration-tests npm install npm run create-predicates ``` ### Manual Service Management ```bash # Start all services docker-compose -f docker/docker-compose-apps.yml up -d # Stop all services ./scripts/stop.sh # View logs docker-compose -f docker/docker-compose-apps.yml logs -f ``` --- title: "Overview" description: "Learn how to set up and run your own Intuition node to participate in the network using the official Rust implementation." last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/intuition-node/overview" --- # Overview Learn how to set up and run your own Intuition node to participate in the network using the official Rust implementation. ## What is an Intuition Node? The `intuition-rs` workspace is a comprehensive Rust workspace for blockchain data indexing and processing, featuring a modular architecture with multiple specialized services. This implementation provides high performance, memory safety, and reliability for running Intuition nodes and backend services. Running an Intuition node requires Docker, Rust toolchain, and proper environment configuration. This guide provides comprehensive setup instructions for local development and production deployments. ### Supported Contract Versions - Multivault v2.0 ## Why Run a Node? Running your own Intuition node provides several key benefits: - **Full Data Access**: Direct access to all blockchain data without relying on third-party services - **Network Participation**: Actively contribute to the decentralization and resilience of the Intuition network - **Custom Indexing**: Tailor data indexing and processing to your specific needs - **Performance Control**: Optimize performance and resource allocation based on your requirements - **Enhanced Privacy**: Process and query data without exposing your queries to external services - **Development Freedom**: Ideal for building and testing applications in a controlled environment ## Architecture This workspace contains the following core services:Core Services
CLI: Terminal UI client for interacting with the Intuition system Consumer: Event processing pipeline using Redis Streams (RAW, DECODED, and RESOLVER consumers) Models: Domain models and data structures for the Intuition systemInfrastructure Services
Hasura: GraphQL API with database migrations and configuration Image Guard: Image processing and validation service RPC Proxy: RPC call proxy with caching for eth_call methodsSupporting Services
Histocrawler: Historical data crawler Shared Utils: Common utilities and shared code Migration Scripts: Database migration utilities ### Event Processing Pipeline The system processes blockchain events through multiple stages: 1. **RAW** - Raw event ingestion from blockchain 2. **DECODED** - Event decoding and parsing 3. **RESOLVER** - Data resolution and enrichment 4. **IPFS-UPLOAD** - Upload images to IPFS and track them in the local DB ## Prerequisites ### Required Tools ### Environment Configuration You'll need to set up environment variables for various services. Create a `.env` file based on the `.env.sample` template with the following required variables: | Variable | Description | Source | |----------|-------------|---------| | `OPENAI_API_KEY` | OpenAI API key for AI features | [OpenAI Platform](https://platform.openai.com/api-keys) | | `PINATA_GATEWAY_TOKEN` | Pinata gateway token for IPFS | [Pinata Dashboard](https://app.pinata.cloud/developers/gateway-settings) | | `PINATA_API_JWT` | Pinata API JWT for IPFS uploads | [Pinata Dashboard](https://app.pinata.cloud/developers/api-keys) | | `BASE_MAINNET_RPC_URL` | Base mainnet RPC endpoint | [Alchemy Dashboard](https://dashboard.alchemy.com/apps) | | `BASE_SEPOLIA_RPC_URL` | Base sepolia testnet RPC endpoint | [Alchemy Dashboard](https://dashboard.alchemy.com/apps) | | `ETHEREUM_MAINNET_RPC_URL` | Ethereum mainnet RPC endpoint | [Alchemy Dashboard](https://dashboard.alchemy.com/apps) | | `LINEA_MAINNET_RPC_URL` | Linea mainnet RPC endpoint | [Alchemy Dashboard](https://dashboard.alchemy.com/apps) | | `LINEA_SEPOLIA_RPC_URL` | Linea sepolia testnet RPC endpoint | [Alchemy Dashboard](https://dashboard.alchemy.com/apps) | | `TRUST_TESTNET_RPC_URL` | Trust testnet RPC endpoint (local geth) | Local development | | `TRUST_MAINNET_RPC_URL` | Trust mainnet RPC endpoint (local geth) | Local development | | `INDEXER_SCHEMA` | Database schema for indexer (set to "local") | Local development | | `INTUITION_CONTRACT_ADDRESS` | Intuition contract address | Contract deployment | ## Next Steps Once you understand the architecture and have the prerequisites ready: 1. Learn about [why we chose Rust](rust-backend.md) for the backend implementation 2. Explore [Local Development Setup](local-setup.md) for development workflows 3. Check [Kubernetes Deployment](kubernetes.md) for production deployments --- title: "Run an Intuition Node" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/intuition-node/run-an-intuition-node" --- # Run an Intuition Node ## Running the System ### Option 1: Using Published Docker Images (Recommended) ```bash # Start with local Ethereum node cargo make start-local ``` ### Option 2: Building from Source ```bash # Build all Docker images from source cargo make build-docker-images # Start the system cargo make start-local ``` ### Option 3: Running with Integration Tests ```bash # Start with tests enabled cargo make start-local test ``` ## Testing ### Run All Tests ```bash cargo nextest run ``` ### Run Integration Tests ```bash cd integration-tests export VITE_INTUITION_CONTRACT_ADDRESS=0x.... pnpm test src/follow.test.ts ``` ### Run Specific Test Suites ```bash # Test account operations pnpm test src/create-person.test.ts # Test vault operations pnpm test src/vaults.test.ts # Test AI agents pnpm test src/ai-agents.test.ts ``` ### Development Testing #### CLI Tool ```bash # Run the CLI to verify latest data ./scripts/cli.sh ``` #### Code Quality ```bash # Format code cargo make fmt # Run linter cargo make clippy # Run all checks cargo make check ``` #### Database Operations ```bash # Start services and run migrations cargo make start-docker-and-migrate # Manual migration (if needed) cp .env.sample .env source .env ``` ## Monitoring and Observability ### Logging The system includes comprehensive logging capabilities: **Features:** - **Structured JSON Logging**: All services output machine-readable logs - **Container Logs**: Direct access to service logs via Docker - **Log Filtering**: Easy filtering by log level and service **Benefits:** - **Debugging**: Quickly find and analyze issues across services - **Performance Monitoring**: Track service performance and bottlenecks - **Audit Trail**: Complete visibility into system operations **Getting Started:** 1. Start the system: `cargo make start-local` 2. View logs: `docker logsCLI
Terminal UI client for interacting with the Intuition systemConsumer
Event processing pipeline using Redis StreamsHistocrawler
Historical data crawler for blockchain indexingImage Guard
Image processing and validation serviceRPC Proxy
RPC call proxy with intelligent cachingModels
Domain models and data structuresShared Utils
Common utilities used across services ### Infrastructure Components The infrastructure layer provides essential services: - **Hasura**: GraphQL API engine with database migrations - **Blockscout**: Blockchain explorer for network transparency - **Drizzle**: Type-safe database schema management - **Geth**: Local Ethereum node for development - **Prometheus**: Metrics collection and monitoring ### Development Tools The repository includes comprehensive tooling: - **Docker Compose**: Orchestrates all services for local development - **Cargo Make**: Task automation and build scripts - **Integration Tests**: End-to-end testing with pnpm - **Shell Scripts**: Quick commands for common operations ## Why Rust? The Intuition backend is built with Rust, a systems programming language that offers unique advantages for blockchain infrastructure:Performance and Efficiency
Zero-cost abstractions: Write high-level code without runtime overhead Memory efficiency: Minimal memory footprint compared to garbage-collected languages Concurrent processing: Built-in support for safe concurrent operations Native performance: Compiles to machine code for maximum speedSafety and Reliability
Memory safety: Eliminates entire classes of bugs (null pointer dereferences, buffer overflows, data races) Type safety: Strong static typing catches errors at compile time Error handling: Explicit error handling through Result types No runtime crashes: Memory safety guarantees prevent unexpected crashesDeveloper Experience
Modern tooling: Cargo package manager and build system Rich ecosystem: Growing library ecosystem for blockchain and web services Documentation: Built-in documentation tools and testing framework Community: Active and supportive open-source communityBlockchain-Specific Benefits
Predictable performance: No garbage collection pauses during critical operations Resource optimization: Efficient resource usage for indexing large amounts of blockchain data WebAssembly support: Can compile to WASM for cross-platform compatibility Security: Memory safety is crucial when handling financial transactions and user data --- title: "Working with Atoms" description: "Create and query atoms using the SDK" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/intuition-sdk/atoms-guide" --- # Working with Atoms **Conceptual overview:** [Atoms Fundamentals](/docs/intuition-concepts/primitives/Atoms/fundamentals) Atoms are unique identifiers for any entity—people, concepts, smart contracts, or data. This guide covers all ways to create and query atoms using the SDK. ## Table of Contents - [Creating from Strings](#creating-from-strings) - [Creating from Thing (JSON-LD)](#creating-from-thing) - [Creating from Ethereum Accounts](#creating-from-ethereum-accounts) - [Creating from Smart Contracts](#creating-from-smart-contracts) - [Creating from IPFS](#creating-from-ipfs) - [Batch Creation](#batch-creation) - [Querying Atoms](#querying-atoms) --- ## Creating from Strings The simplest way to create an atom is from a plain string. ### Function Signature ```typescript function createAtomFromString( config: WriteConfig, data: string, deposit?: bigint ): Promise
{atomId &&
)
}
```
## Custom Hooks
Create reusable hooks for SDK operations:
```typescript title="useCreateAtom.ts"
import { useMutation } from '@tanstack/react-query'
import { usePublicClient, useWalletClient, useChainId } from 'wagmi'
import {
createAtomFromString,
getMultiVaultAddressFromChainId,
} from '@0xintuition/sdk'
import { parseEther } from 'viem'
export function useCreateAtom() {
const chainId = useChainId()
const publicClient = usePublicClient()
const { data: walletClient } = useWalletClient()
return useMutation({
mutationFn: async ({ data, deposit }: { data: string, deposit?: string }) => {
if (!publicClient || !walletClient) {
throw new Error('Wallet not connected')
}
const address = getMultiVaultAddressFromChainId(chainId)
return createAtomFromString(
{ walletClient, publicClient, address },
data,
deposit ? parseEther(deposit) : undefined
)
},
})
}
// Usage in component
function MyComponent() {
const createAtom = useCreateAtom()
const handleCreate = async () => {
const result = await createAtom.mutateAsync({
data: 'My Atom',
deposit: '0.01',
})
console.log('Created:', result.state.termId)
}
return (
)
}
```
## Query Hooks
Fetch data with React Query:
```typescript title="useAtomDetails.ts"
import { useQuery } from '@tanstack/react-query'
import { getAtomDetails } from '@0xintuition/sdk'
export function useAtomDetails(atomId: string | undefined) {
return useQuery({
queryKey: ['atom', atomId],
queryFn: () => atomId ? getAtomDetails(atomId) : null,
enabled: !!atomId,
staleTime: 30000, // 30 seconds
})
}
// Usage
function AtomDisplay({ atomId }: { atomId: string }) {
const { data: atom, isLoading, error } = useAtomDetails(atomId)
if (isLoading) return Created: {atomId}
}Loading...
if (error) return Error loading atom
if (!atom) return null
return (
{atom.label}
Creator: {atom.creator}
Shares: {atom.vault.totalShares}
Atom Manager
{/* Search */}Search Atoms
setSearchQuery(e.target.value)} placeholder="Search..." /> {searchResults?.atoms.map(atom => ({atom.label}
))}
Create Atom
setNewAtomData(e.target.value)} placeholder="Atom data..." />
{/* Search */}
{/* Create */}
{/* Details */}
{selectedAtomId && (
)}
)}
)
}
```
## Advanced Patterns
### Optimistic Updates
```typescript
const createAtom = useMutation({
mutationFn: createAtomFunction,
onMutate: async (newAtom) => {
// Cancel outgoing refetches
await queryClient.cancelQueries({ queryKey: ['search'] })
// Snapshot previous value
const previous = queryClient.getQueryData(['search'])
// Optimistically update
queryClient.setQueryData(['search'], (old: any) => ({
...old,
atoms: [...(old?.atoms || []), { id: 'temp', label: newAtom.data }],
}))
return { previous }
},
onError: (err, newAtom, context) => {
// Rollback on error
queryClient.setQueryData(['search'], context?.previous)
},
onSettled: () => {
queryClient.invalidateQueries({ queryKey: ['search'] })
},
})
```
### Dependent Queries
```typescript
function AtomWithTriples({ atomId }: { atomId: string }) {
const atom = useAtomDetails(atomId)
const triples = useQuery({
queryKey: ['triples', atomId],
queryFn: () => fetchTriplesForAtom(atomId),
enabled: !!atom.data, // Only fetch when atom is loaded
})
return (/* ... */)
}
```
## Related Resources
- [React Integration](./react.md)
- [TanStack Query Documentation](https://tanstack.com/query)
## See Also
- [Wagmi Hooks](https://wagmi.sh)
- [SDK Query Functions](../search/global-search.md)
---
title: "SDK Migration V1 to V2"
description: "Migrating SDK from v1.5 to v2.0"
last_updated: "2026-01-05T17:16:01-08:00"
source: "https://docs.intuition.systems/docs/intuition-sdk/migration-guide"
---
# SDK Migration V1 to V2
# Migrating SDK from v1.5 to v2.0
This guide helps you migrate your code from v1.x to v2.0.0-alpha of the Intuition TypeScript packages. This is a **major version update** with significant breaking changes due to the underlying contract migration from `EthMultiVault` to `MultiVault`.
## Contract Migration Overview
The core smart contract has been upgraded from `EthMultiVault` to `MultiVault`, introducing significant architectural changes that impact all TypeScript libraries built on top.
### Key Contract Changes
#### 1. **ID System Migration**
- **EthMultiVault**: Uses `uint256` for atom/triple IDs
- **MultiVault**: Uses `bytes32` for term IDs (atoms and triples are now "terms")
#### 2. **Terminology Changes**
- **EthMultiVault**: Atoms and Triples as separate entities
- **MultiVault**: Unified "Terms" concept (atoms and triples are both terms)
- **EthMultiVault**: Vault IDs
- **MultiVault**: Term IDs with Curve IDs for bonding curves
#### 3. **Bonding Curve Integration**
- **EthMultiVault**: Limited bonding curve support
- **MultiVault**: Full bonding curve integration with curve IDs for all operations
## Breaking Changes Overview
### Package Version Updates
| Package | Previous Version | New Version |
| ----------------------- | ---------------- | --------------- |
| `@0xintuition/protocol` | `1.0.0-alpha.1` | `2.0.0` |
| `@0xintuition/sdk` | `1.0.0-alpha.3` | `2.0.0` |
| `@0xintuition/graphql` | `1.0.0-alpha.3` | `2.0.0` |
| `@0xintuition/cli` | `0.0.2` | `2.0.0` |
## 1. Contract Migration Impact
### Contract Function Mapping
The migration from `EthMultiVault` to `MultiVault` requires updating all contract interactions. Here's the complete function mapping:
#### Core Creation Functions
##### Atom Creation
```solidity
// EthMultiVault
function createAtom(bytes atomUri) payable returns (uint256)
function batchCreateAtom(bytes[] atomUris) payable returns (uint256[])
// MultiVault
function createAtoms(bytes[] data, uint256[] assets) payable returns (bytes32[])
```
##### Triple Creation
```solidity
// EthMultiVault
function createTriple(uint256 subjectId, uint256 predicateId, uint256 objectId) payable returns (uint256)
function batchCreateTriple(uint256[] subjectIds, uint256[] predicateIds, uint256[] objectIds) payable returns (uint256[])
// MultiVault
function createTriples(bytes32[] subjectIds, bytes32[] predicateIds, bytes32[] objectIds, uint256[] assets) payable returns (bytes32[])
```
#### Deposit Functions
##### EthMultiVault
```solidity
function depositAtom(address receiver, uint256 id) payable returns (uint256)
function depositTriple(address receiver, uint256 id) payable returns (uint256)
function batchDeposit(address receiver, uint256[] termIds, uint256[] amounts) payable returns (uint256[])
```
##### MultiVault
```solidity
function deposit(address receiver, bytes32 termId, uint256 curveId, uint256 minShares) payable returns (uint256)
function depositBatch(address receiver, bytes32[] termIds, uint256[] curveIds, uint256[] assets, uint256[] minShares) payable returns (uint256[])
```
#### Redeem Functions
##### EthMultiVault
```solidity
function redeemAtom(uint256 shares, address receiver, uint256 id) returns (uint256)
function redeemTriple(uint256 shares, address receiver, uint256 id) returns (uint256)
function batchRedeem(uint256 percentage, address receiver, uint256[] ids) returns (uint256[])
```
##### MultiVault
```solidity
function redeem(address receiver, bytes32 termId, uint256 curveId, uint256 shares, uint256 minAssets) returns (uint256)
function redeemBatch(address receiver, bytes32[] termIds, uint256[] curveIds, uint256[] shares, uint256[] minAssets) returns (uint256[])
```
### Contract Address Changes: `EthMultiVault` → `MultiVault`
**Before:**
```typescript
import { EthMultiVaultAbi } from '@0xintuition/protocol'
import { getEthMultiVaultAddress } from '@0xintuition/sdk'
const address = getEthMultiVaultAddress(chainId)
```
**After:**
```typescript
import { intuitionTestnet, MultiVaultAbi } from '@0xintuition/protocol'
import { getMultiVaultAddressFromChainId } from '@0xintuition/sdk'
const address = getMultiVaultAddressFromChainId(intuitionTestnet.id)
```
### Contract Event Changes
#### EthMultiVault Events
```solidity
event AtomCreated(address indexed creator, address indexed atomWallet, bytes atomData, uint256 vaultId)
event TripleCreated(address indexed creator, uint256 subjectId, uint256 predicateId, uint256 objectId, uint256 vaultId)
```
#### MultiVault Events
```solidity
event AtomCreated(address indexed creator, bytes32 indexed termId, bytes atomData, address atomWallet)
event TripleCreated(address indexed creator, bytes32 indexed termId, bytes32 subjectId, bytes32 predicateId, bytes32 objectId)
```
### Data Structure Migration
#### ID Handling Update
```typescript
// Before (EthMultiVault)
const atomId: bigint = 123n;
const tripleId: bigint = 456n;
// After (MultiVault)
const atomId: `0x${string}` = "0x1234..."; // 32-byte hash
const tripleId: `0x${string}` = "0x5678..."; // 32-byte hash
```
#### Query Functions
```solidity
// EthMultiVault
function atoms(uint256 atomId) view returns (bytes)
function getTripleAtoms(uint256 id) view returns (uint256, uint256, uint256)
// MultiVault
function atom(bytes32 atomId) view returns (bytes)
function getAtom(bytes32 atomId) view returns (bytes)
function triple(bytes32 tripleId) view returns (bytes32, bytes32, bytes32)
function getTriple(bytes32 tripleId) view returns (bytes32, bytes32, bytes32)
```
#### Share and Asset Conversions
```solidity
// EthMultiVault
function convertToShares(uint256 assets, uint256 id) view returns (uint256)
function convertToAssets(uint256 shares, uint256 id) view returns (uint256)
// MultiVault
function convertToShares(bytes32 termId, uint256 curveId, uint256 assets) view returns (uint256)
function convertToAssets(bytes32 termId, uint256 curveId, uint256 shares) view returns (uint256)
```
### New MultiVault Features
#### 1. **Utilization Tracking**
```typescript
const userUtilization = await multiVault.getUserUtilizationForEpoch(
userAddress,
epoch,
)
const totalUtilization = await multiVault.getTotalUtilizationForEpoch(epoch)
```
#### 2. **Epoch System**
```typescript
const currentEpoch = await multiVault.currentEpoch()
const lastActiveEpoch = await multiVault.lastActiveEpoch(userAddress)
```
#### 3. **Enhanced Fee Management**
```typescript
// Atom wallet deposit fees
const accumulatedFees =
await multiVault.accumulatedAtomWalletDepositFees(atomWallet)
await multiVault.claimAtomWalletDepositFees(termId)
// Protocol fees by epoch
const protocolFees = await multiVault.accumulatedProtocolFees(epoch)
```
#### 4. **Improved Preview Functions**
```typescript
// Preview with different scenarios
const [shares, assetsAfterFees] = await multiVault.previewDeposit(termId, curveId, assets);
const [shares, assetsAfterFixedFees, assetsAfterFees] = await multiVault.previewAtomCreate(termId, curveId, assets);
```
## 2. TypeScript Library Changes
### Protocol Package (`@0xintuition/protocol`)
#### Atom Creation: Singular → Plural
**Before:**
```typescript
import {
createAtom,
createAtomCalculateBaseCost,
createAtomEncode,
} from '@0xintuition/protocol'
// Single atom creation
await createAtom(config, { args: [atomUri], value })
// Encoding
const encodedData = createAtomEncode(atomUri)
// Cost calculation
const cost = await createAtomCalculateBaseCost(config)
```
**After:**
```typescript
import {
createAtoms,
createAtomsEncode,
getAtomCost,
} from '@0xintuition/protocol'
// Atoms creation (supports single or multiple)
await createAtoms(config, {
args: [
[atomUri1, atomUri2],
[assets1, assets2],
],
value,
})
// Encoding
const encodedData = createAtomsEncode([atomUri1, atomUri2], [assets1, assets2])
// Cost calculation
const cost = await getAtomCost(config)
```
#### Triple Creation: Singular → Plural
**Before:**
```typescript
import {
createTriple,
createTripleCalculateBaseCost,
createTripleEncode,
} from '@0xintuition/protocol'
await createTriple(config, {
args: [subjectId, predicateId, objectId],
value,
})
const encodedData = createTripleEncode(subjectId, predicateId, objectId)
const cost = await createTripleCalculateBaseCost(config)
```
**After:**
```typescript
import {
createTriples,
createTriplesEncode,
getTripleCost,
} from '@0xintuition/protocol'
await createTriples(config, {
args: [
[subjectId1, subjectId2],
[predicateId1, predicateId2],
[objectId1, objectId2],
[assets1, assets2],
],
value,
})
const encodedData = createTriplesEncode(
[subjectId1, subjectId2],
[predicateId1, predicateId2],
[objectId1, objectId2],
[assets1, assets2],
)
const cost = await getTripleCost(config)
```
#### Deposit and Redeem Simplification
**Before:**
```typescript
import {
depositAtom,
depositAtomEncode,
depositTriple,
depositTripleEncode,
redeemAtom,
redeemAtomEncode,
redeemTriple,
redeemTripleEncode,
} from '@0xintuition/protocol'
// Separate functions for atoms and triples
await depositAtom(config, { args: [receiver, atomId], value })
await depositTriple(config, { args: [receiver, tripleId], value })
await redeemAtom(config, { args: [shares, receiver, atomId] })
await redeemTriple(config, { args: [shares, receiver, tripleId] })
```
**After:**
```typescript
import {
deposit,
depositEncode,
redeem,
redeemEncode,
} from '@0xintuition/protocol'
// Unified functions for any vault (atom or triple)
await deposit(config, {
args: [receiver, termId, curveId, assets, minShares],
value,
})
await redeem(config, { args: [receiver, termId, cirveId, shares, minAssets] })
// Unified encoding
const depositData = depositEncode(receiver, vaultId)
const redeemData = redeemEncode(shares, receiver, vaultId)
```
#### Batch Operations Renamed
**Before:**
```typescript
import {
batchCreateAtom,
batchCreateTriple,
batchDepositCurve,
batchRedeemCurve,
} from '@0xintuition/protocol'
```
**After:**
```typescript
import {
createAtoms, // Replaces batchCreateAtom
createTriples, // Replaces batchCreateTriple
depositBatch, // Replaces batchDepositCurve
redeemBatch, // Replaces batchRedeemCurve
} from '@0xintuition/protocol'
```
#### Multicall Function Name
**Before:**
```typescript
import { multiCallIntuitionConfigs } from '@0xintuition/protocol'
const config = await multiCallIntuitionConfigs({ address, publicClient })
```
**After:**
```typescript
import { multicallIntuitionConfig } from '@0xintuition/protocol'
const config = await multicallIntuitionConfig({ address, publicClient })
```
#### Removed EthMultiVault API
**Before:**
```typescript
import { EthMultiVault } from '@0xintuition/protocol'
const ethMultiVault = new EthMultiVault({ publicClient, walletClient })
const result = await ethMultiVault.createAtom('hello')
```
**After:**
```typescript
import {
getMultiVaultAddressFromChainId,
intuitionTestnet,
MultiVaultAbi,
} from '@0xintuition/protocol'
import { getContract } from 'viem'
const multiVault = getContract({
abi: MultiVaultAbi,
address: getMultiVaultAddressFromChainId(intuitionTestnet.id),
client: {
public: publicClient,
wallet: walletClient,
},
})
const atomCost = await multiVault.read.getAtomCost()
const result = await multiVault.createAtoms([['hello'], [atomCost]], {
value: atomCost,
})
```
### Bonding Curve Integration
The new `MultiVault` contract requires curve IDs for all operations:
```typescript
// MultiVault requires curve ID for all operations
const defaultCurveId = await multiVault.getBondingCurveConfig().defaultCurveId
// Use in all deposit/redeem operations
await multiVault.deposit(receiver, termId, defaultCurveId, minShares, {
value: assets,
})
```
### Migration Steps
#### Step 1: Update Function Calls
##### Creating Atoms
```typescript
// Before
const atomId = await ethMultiVault.createAtom(atomData, { value: fee });
// After
const atomIds = await multiVault.createAtoms([atomData], [assets], { value: totalValue });
const atomId = atomIds[0];
```
##### Depositing
```typescript
// Before
const shares = await ethMultiVault.depositAtom(receiver, atomId, { value: assets });
// After
const shares = await multiVault.deposit(receiver, termId, curveId, minShares, { value: assets });
```
##### Redeeming
```typescript
// Before
const assets = await ethMultiVault.redeemAtom(shares, receiver, atomId);
// After
const assets = await multiVault.redeem(receiver, termId, curveId, shares, minAssets);
```
## 3. SDK Package Changes (`@0xintuition/sdk`)
### API Function Renaming
**Before:**
```typescript
import { getAtom, getTriple } from '@0xintuition/sdk'
const atomData = await getAtom('124862')
const tripleData = await getTriple('54670')
```
**After:**
```typescript
import { getAtomDetails, getTripleDetails } from '@0xintuition/sdk'
const atomData = await getAtomDetails(
'0x57d94c116a33bb460428eced262b7ae2ec6f865e7aceef6357cec3d034e8ea21',
)
const tripleData = await getTripleDetails(
'0x4957d3f442acc301ad71e73f26efd6af78647f57dacf2b3a686d91fa773fe0b6',
)
```
### Triple Creation Parameter Changes
**Before:**
```typescript
import { createTripleStatement } from '@0xintuition/sdk'
const triple = await createTripleStatement(config, {
args: [subjectVaultId, predicateVaultId, objectVaultId],
depositAmount: 1000000000000000000n, // Optional
})
```
**After:**
```typescript
import { createTripleStatement } from '@0xintuition/sdk'
const triple = await createTripleStatement(config, {
args: [
[subjectVaultId],
[predicateVaultId],
[objectVaultId],
[1000000000000000000n],
],
value: 1000000000000000000n, // Required
})
```
## 4. Configuration Changes
### EthMultiVault Config
```solidity
struct GeneralConfig {
address admin;
address protocolMultisig;
uint256 feeDenominator;
uint256 minDeposit;
uint256 minShare;
uint256 atomUriMaxLength;
uint256 decimalPrecision;
uint256 minDelay;
}
```
### MultiVault Config
```solidity
struct GeneralConfig {
address admin;
address protocolMultisig;
uint256 feeDenominator;
address trustBonding; // New
uint256 minDeposit;
uint256 minShare;
uint256 atomDataMaxLength; // Renamed
uint256 decimalPrecision;
// minDelay removed
}
```
## 5. Removed Functions
The following functions have been removed and replaced:
### Protocol Package
- `createAtom` → `createAtoms`
- `createTriple` → `createTriples`
- `batchCreateAtom` → `createAtoms`
- `batchCreateTriple` → `createTriples`
- `depositAtom` / `depositTriple` → `deposit`
- `redeemAtom` / `redeemTriple` → `redeem`
- `createAtomCalculateBaseCost` → `getAtomCost`
- `createTripleCalculateBaseCost` → `getTripleCost`
- All curve-specific functions → `depositBatch` / `redeemBatch`
- `atoms-by-hash.ts` file completely removed
### SDK Package
- `createThing` → `createAtomFromThing`
- `createEthereumAccount` → `createAtomFromEthereumAccount`
- `getEthMultiVaultAddress` → `getMultiVaultAddressFromChainId`
- `getAtom` → `getAtomDetails`
- `getTriple` → `getTripleDetails`
## 6. Breaking Changes Summary
1. **All IDs changed from `uint256` to `bytes32`**
2. **Curve ID parameter required for most operations**
3. **Batch functions have different signatures**
4. **Event structures updated**
5. **Some functions renamed or merged**
6. **New slippage protection with `minShares`/`minAssets` parameters**
## 7. Best Practices
1. **Always use the default curve ID** unless you have specific bonding curve requirements
2. **Implement proper slippage protection** with min/max parameters
3. **Handle the new epoch system** for utilization tracking
4. **Update your event listeners** to match new event structures
5. **Use preview functions** to estimate outcomes before transactions
## 📝 Summary
This major version update consolidates and simplifies the API while adding new functionality. The main changes are:
- **Contract Migration**: `EthMultiVault` → `MultiVault` with architectural improvements
- **ID System**: Changed from `uint256` to `bytes32` for all term identifiers
- **Bonding Curves**: Full integration requiring curve IDs for all operations
- **Singular → Plural**: Functions now support batch operations by default
- **Unified APIs**: Simplified deposit/redeem functions for all vault types
- **Enhanced Features**: New utilization tracking, epoch system, and preview functions
- **Event Updates**: Improved event parsing with new event structures
Take your time with the migration and test thoroughly. The new API is more powerful and consistent, providing a better developer experience.
---
title: "Quick Start"
description: "Create your first atom and triple with the Intuition SDK in minutes"
last_updated: "2026-01-05T17:16:01-08:00"
source: "https://docs.intuition.systems/docs/intuition-sdk/quick-start"
---
# Quick Start
Get started with the Intuition SDK by creating your first atom and triple in minutes.
## Auto-Generated Package Documentation
For a complete list of `0xintuition/sdk` functions and interfaces, see the [Intuition SDK documentation](https://github.com/0xIntuition/intuition-ts/tree/main/packages/sdk/docs).
- [Intuition SDK NPM](https://www.npmjs.com/package/@0xintuition/sdk)
- [Intuition SDK GitHub](https://github.com/0xIntuition/intuition-ts/tree/main/packages/sdk/docs)
For a complete list of `0xintuition/protocol` functions and interfaces, see the [Intuition Protocol documentation](https://github.com/0xIntuition/intuition-ts/tree/main/packages/protocol/docs).
- [Intuition Protocol NPM](https://www.npmjs.com/package/@0xintuition/protocol)
- [Intuition Protocol GitHub](https://github.com/0xIntuition/intuition-ts/tree/main/packages/protocol/docs)
For a complete list of `0xintuition/graphql` functions and interfaces, see the [Intuition Protocol documentation](https://github.com/0xIntuition/intuition-ts/tree/main/packages/graphql).
- [Intuition Protocol NPM](https://www.npmjs.com/package/@0xintuition/graphql)
- [Intuition Protocol GitHub](https://github.com/0xIntuition/intuition-ts/tree/main/packages/graphql)
## Overview
In this quick start guide, you'll:
1. Set up the SDK clients
2. Create an atom from a string
3. Create a triple (subject-predicate-object statement)
4. Query atom details
## Prerequisites
- [Installed the SDK](./installation.md)
- Have a wallet with testnet TRUST tokens ([get testnet tokens](https://testnet.faucet.intuition.systems))
- Your wallet private key
## Step 1: Set Up Clients
Create a new file and set up your Viem clients:
```typescript title="quickstart.ts"
import {
intuitionTestnet,
getMultiVaultAddressFromChainId,
createAtomFromString,
createTripleStatement,
getAtomDetails,
} from '@0xintuition/sdk'
import { createPublicClient, createWalletClient, http, parseEther } from 'viem'
import { privateKeyToAccount } from 'viem/accounts'
// Setup account and clients
const account = privateKeyToAccount('0xYOUR_PRIVATE_KEY')
const publicClient = createPublicClient({
chain: intuitionTestnet,
transport: http(),
})
const walletClient = createWalletClient({
chain: intuitionTestnet,
transport: http(),
account,
})
const address = getMultiVaultAddressFromChainId(intuitionTestnet.id)
```
## Step 2: Create Your First Atom
Create an atom from a simple string:
```typescript
// Create an atom
const atom = await createAtomFromString(
{ walletClient, publicClient, address },
'TypeScript',
parseEther('0.01') // Optional: initial deposit of 0.01 TRUST
)
console.log('Created atom!')
console.log('Atom ID:', atom.state.termId)
console.log('Transaction:', atom.transactionHash)
console.log('URI:', atom.uri)
```
Expected output:
```
Created atom!
Atom ID: 0x1234567890abcdef...
Transaction: 0xabcdef1234567890...
URI: TypeScript
```
## Step 3: Query Atom Details
Fetch the atom details from the Intuition API:
```typescript
// Wait a moment for indexing
await new Promise(resolve => setTimeout(resolve, 2000))
// Query atom details
const details = await getAtomDetails(atom.state.termId)
console.log('Atom Details:')
console.log('- Label:', details.label)
console.log('- Creator:', details.creator)
console.log('- Vault Assets:', details.vault.totalShares)
```
## Step 4: Create a Triple
Create a triple (statement) connecting three atoms:
```typescript
// Create three atoms
const alice = await createAtomFromString(
{ walletClient, publicClient, address },
'Alice'
)
const follows = await createAtomFromString(
{ walletClient, publicClient, address },
'follows'
)
const bob = await createAtomFromString(
{ walletClient, publicClient, address },
'Bob'
)
// Create triple: "Alice follows Bob"
const triple = await createTripleStatement(
{ walletClient, publicClient, address },
{
args: [
[alice.state.termId], // subjects
[follows.state.termId], // predicates
[bob.state.termId], // objects
[parseEther('0.1')], // deposit per triple
],
value: parseEther('0.1'), // total transaction value
}
)
console.log('Created triple!')
console.log('Triple ID:', triple.state[0].args.tripleId)
console.log('Transaction:', triple.transactionHash)
```
## Complete Example
Here's the complete quick start script:
```typescript title="quickstart.ts"
import {
intuitionTestnet,
getMultiVaultAddressFromChainId,
createAtomFromString,
createTripleStatement,
getAtomDetails,
} from '@0xintuition/sdk'
import { createPublicClient, createWalletClient, http, parseEther } from 'viem'
import { privateKeyToAccount } from 'viem/accounts'
async function main() {
// Setup
const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`)
const publicClient = createPublicClient({
chain: intuitionTestnet,
transport: http(),
})
const walletClient = createWalletClient({
chain: intuitionTestnet,
transport: http(),
account,
})
const address = getMultiVaultAddressFromChainId(intuitionTestnet.id)
// Create an atom
console.log('Creating atom...')
const atom = await createAtomFromString(
{ walletClient, publicClient, address },
'TypeScript',
parseEther('0.01')
)
console.log('✓ Atom created:', atom.state.termId)
// Wait for indexing
await new Promise(resolve => setTimeout(resolve, 2000))
// Query details
const details = await getAtomDetails(atom.state.termId)
console.log('✓ Atom label:', details.label)
// Create three atoms for a triple
console.log('\nCreating atoms for triple...')
const alice = await createAtomFromString(
{ walletClient, publicClient, address },
'Alice'
)
const follows = await createAtomFromString(
{ walletClient, publicClient, address },
'follows'
)
const bob = await createAtomFromString(
{ walletClient, publicClient, address },
'Bob'
)
// Create triple
console.log('Creating triple...')
const triple = await createTripleStatement(
{ walletClient, publicClient, address },
{
args: [
[alice.state.termId],
[follows.state.termId],
[bob.state.termId],
[parseEther('0.1')],
],
value: parseEther('0.1'),
}
)
console.log('✓ Triple created:', triple.state[0].args.tripleId)
console.log('\nSuccess! You created your first atom and triple.')
}
main()
.then(() => process.exit(0))
.catch((error) => {
console.error('Error:', error)
process.exit(1)
})
```
## Run the Example
```bash
# Set your private key
export PRIVATE_KEY=0xYOUR_PRIVATE_KEY
# Run the script
npx tsx quickstart.ts
```
## Understanding the Code
### Atoms
Atoms are the fundamental entities in Intuition. They can represent:
- Simple strings (`"TypeScript"`)
- Ethereum addresses (`"0x1234..."`)
- IPFS content (`"ipfs://bafkreib..."`)
- Rich entities (JSON-LD objects)
### Triples
Triples connect atoms in subject-predicate-object relationships:
- **Subject**: The atom being described (`Alice`)
- **Predicate**: The relationship type (`follows`)
- **Object**: The target atom (`Bob`)
### Deposits
Each atom and triple has a vault for deposits:
- Depositing increases your stake in an entity
- You receive shares based on a bonding curve
- Shares can be redeemed later for assets
## Next Steps
Now that you've created your first atom and triple, explore:
### Atom Operations
- [**Create from Thing**](../atoms/create-from-thing.md) - Create rich entities with metadata
- [**Create from Ethereum Account**](../atoms/create-from-ethereum-account.md) - Create identity atoms
- [**Batch Creation**](../atoms/batch-creation.md) - Create multiple atoms efficiently
### Triple Operations
- [**Querying Triples**](../triples/querying.md) - Fetch triple details
- [**Counter Triples**](../triples/counter-triples.md) - Work with opposing positions
### Vault Operations
- [**Deposits**](../vaults/deposits.md) - Deposit into vaults
- [**Redemptions**](../vaults/redemptions.md) - Redeem shares
### Search & Discovery
- [**Global Search**](../search/global-search.md) - Search across all entities
- [**Semantic Search**](../search/advanced-queries.md) - Find similar content
## Common Issues
### Transaction Reverts
If your transaction reverts, check:
1. You have sufficient TRUST balance
2. The atoms exist before creating a triple
3. The deposit amount is greater than 0
### Indexing Delays
The Intuition API may take a few seconds to index new entities. Add a delay before querying:
```typescript
await new Promise(resolve => setTimeout(resolve, 2000))
```
### Network Errors
Ensure you're connected to the correct network:
```typescript
console.log('Network:', intuitionTestnet.name)
console.log('Chain ID:', intuitionTestnet.id)
```
## See Also
- [Core Concepts](../../../core-concepts/primitives/overview.md) - Understand atoms and triples
- [SDK Examples](../examples/create-atom-from-string.md) - More detailed examples
- [GraphQL Queries](../../graphql-api/queries/atoms/single-atom.md) - Query protocol data
---
title: "Search and Discovery"
description: "Search atoms, triples, and perform advanced queries"
last_updated: "2026-01-05T17:16:01-08:00"
source: "https://docs.intuition.systems/docs/intuition-sdk/search-guide"
---
# Search and Discovery
Discover atoms, triples, accounts, and collections using powerful search capabilities including full-text search, semantic search, and batch entity lookups.
## Table of Contents
- [Global Search](#global-search)
- [Searching Atoms](#searching-atoms)
- [Searching Triples](#searching-triples)
- [Advanced Queries](#advanced-queries)
---
## Global Search
Search across all entity types (atoms, accounts, triples, collections) with a single query.
### Function Signature
```typescript
function globalSearch(
query: string,
options?: GlobalSearchOptions
): PromiseSearch Atoms
setSearchQuery(e.target.value)} placeholder="Search..." /> {search.isLoading &&Searching...
} {search.data?.atoms.map(atom => ( setSelectedAtomId(atom.id)}
style={{ cursor: 'pointer' }}
>
{atom.label}
))}
Create Atom
setNewAtomData(e.target.value)} placeholder="Atom data..." /> {createAtom.isError && (Error: {createAtom.error.message}
)}Atom Details
{atomDetails.isLoading &&Loading...
} {atomDetails.data && (Label: {atomDetails.data.label}
Creator: {atomDetails.data.creator}
Shares: {atomDetails.data.vault.totalShares}
Intuition Quickstart
{atomId && ( )}General Support
Get general support and assistance for questions about Intuition.Website
Visit our official website for the latest updates, information, and resources. ## Feedback & ImprovementGitHub
Contribute to our open-source projects, report issues, and suggest improvements.Feedback
Share your feedback, suggestions, and ideas to help improve Intuition. --- title: "FAQ" description: "Frequently Asked Questions about Intuition" last_updated: "2026-02-11T09:19:02-05:00" source: "https://docs.intuition.systems/docs/resources/faq" --- # FAQ This page is organized into expandable sections for easy navigation. Click on any section below to explore the questions within that category. Getting Started - Basic information about Intuition and how to begin ## Getting Started ### What is Intuition? Intuition is a decentralized protocol that enables the creation of trustful interactions through atomic primitives. It provides a foundation for building decentralized applications that can establish and maintain trust between parties without centralized intermediaries. The protocol uses atomic primitives (atoms, triples, signals, and bonding curves) to create trustful interactions. These primitives can be combined to build complex decentralized applications that maintain trust through cryptographic proofs and economic incentives. ### How do I get started with Intuition? **Step 1: Read the Documentation** Start with the [Getting Started](/docs/getting-started/overview) guides to understand the core concepts. **Step 2: Connect to Testnet** Visit the [Intuition Hub](https://intuition-testnet.hub.caldera.xyz/) to access the testnet and get your development environment set up. **Step 3: Set up Development Environment** Install the necessary SDKs and tools for your preferred programming language. **Step 4: Build Your First App** Follow the tutorials to create a simple application using Intuition primitives. **Step 5: Join the Community** Connect with other developers and get support through our community channels. ### What are the main components of Intuition? **Atoms**: The basic units of trust and reputation - unique identifiers for any entity (people, concepts, products) **Triples**: Relationships between atoms that encode trust - structured as Subject → Predicate → Object **Signals**: Mechanisms for updating trust relationships - actions that express intent, belief, or support **Bonding Curves**: Economic models for token pricing and liquidity - automated market making for application tokens Development & Integration - Programming languages, integration, and deployment ## Development & Integration ### What programming languages are supported? Intuition supports multiple programming languages through various SDKs: - **JavaScript/TypeScript**: Official SDK with full feature support - **Python**: Python SDK for backend development - **Rust**: Low-level SDK for performance-critical applications - **Go**: Go SDK for server-side applications ### How do I connect to the Intuition testnet? **Step 1: Access the Hub** Visit the [Intuition Hub](https://intuition-testnet.hub.caldera.xyz/) for centralized access to all Intuition L3 network services. **Step 2: Configure Your Wallet** Add the Intuition testnet to your wallet using the network details provided in the hub dashboard. The hub will display the current Chain ID and RPC URL. **Step 3: Get Test Tokens** Use the built-in faucet available in the hub to obtain test tokens for development and testing. **Step 4: Explore Services** Access the Bridge for cross-chain transfers, Explorer for blockchain exploration, and monitor network status through the status page. ### How do I integrate Intuition into my existing app? **Step 1: Install SDK** Add the appropriate Intuition SDK to your project using your package manager. **Step 2: Configure Connection** Set up connection to the Intuition testnet first using the network details from the [Hub](https://intuition-testnet.hub.caldera.xyz/). **Step 3: Implement Primitives** Use atoms, triples, signals, and bonding curves in your application logic. **Step 4: Test Integration** Thoroughly test your integration on testnet before production deployment. ### How do I deploy an application? **Step 1: Develop Your App** Build your application using Intuition primitives and follow best practices. **Step 2: Test on Testnet** Use the [Intuition testnet](https://intuition-testnet.hub.caldera.xyz/) to thoroughly test your application before mainnet deployment. Access all testnet services through the hub. **Step 3: Deploy Contracts** Deploy your smart contracts to the network using the appropriate deployment tools. Start with testnet deployment first. **Step 4: Launch Application** Make your application available to users and monitor its performance using the network monitoring tools. ### What are the best practices for building with Intuition? **Start Simple**: Begin with basic primitives before building complex systems to understand the fundamentals. **Test Extensively**: Use the [Intuition testnet](https://intuition-testnet.hub.caldera.xyz/) for all development and testing to avoid costly mistakes. Access the full testing infrastructure through the hub. **Follow Security Guidelines**: Implement proper security measures and follow established patterns. **Document Your Code**: Maintain clear documentation for your applications to help other developers. **Monitor Applications**: Use the network monitoring tools to track your application's performance and catch issues early. Economics & Rewards - Token economics, bonding curves, and earning rewards ## Economics & Rewards ### How does the token economics work? Intuition uses a dual-token system: **INTUITION**: The main network token used for staking, governance, and network security. **Application Tokens**: Specific to individual applications for their economic models and bonding curves. The system provides automated market making and liquidity for application tokens, enabling dynamic pricing and efficient token distribution through bonding curves. ### How can I earn rewards? **Staking**: Stake INTUITION tokens to earn rewards and participate in network security. **Running Nodes**: Operate network nodes to earn block rewards and contribute to decentralization. **Building Applications**: Create successful applications that generate fees and provide value to users. **Contributing**: Participate in governance and development to help shape the protocol's future. ### What are bonding curves? Bonding curves are mathematical functions that determine token pricing based on supply and demand. They provide: - **Automated Market Making**: Continuous liquidity without traditional market makers - **Dynamic Pricing**: Token prices that automatically adjust based on supply and demand - **Efficient Distribution**: Fair token distribution through mathematical models - **Liquidity Provision**: Built-in liquidity for application tokens Troubleshooting & Support - Common issues and getting help ## Troubleshooting & Support ### How do I handle errors and edge cases? **Implement Error Handling**: Add comprehensive error handling to your applications to gracefully handle failures. **Use Fallback Mechanisms**: Implement fallbacks for critical operations to ensure reliability. **Monitor Applications**: Set up monitoring and alerting for your applications to catch issues early. **Plan for Upgrades**: Design your applications to be upgradeable as the protocol evolves. ### What if I can't connect to the testnet? If you're having trouble connecting to the Intuition testnet, try these troubleshooting steps: **Check Network Configuration** Verify that your wallet is configured with the correct network details from the [Hub dashboard](https://intuition-testnet.hub.caldera.xyz/). The Chain ID and RPC URL should match exactly. **Check Network Status** Visit the network status page to see if there are any ongoing issues with the testnet services. **Clear Wallet Cache** Try clearing your wallet's cache or switching to a different RPC endpoint if multiple are available in the hub. **Check Firewall/VPN** Ensure your firewall or VPN isn't blocking connections to the testnet endpoints. ### What if my transaction fails? If your transaction fails, check your wallet to confirm whether your tokens have been returned. In most cases, failed transactions automatically result in the tokens being returned to your wallet. Common causes of transaction failures: - **Insufficient Gas**: Ensure you have enough gas for the transaction - **Network Congestion**: Try again during less busy periods - **Incorrect Parameters**: Double-check all transaction parameters before signing - **Network Issues**: Check the Hub for any ongoing L3 network problems ### How do I get help and support? **Community Support**: Join our [Discord](https://discord.com/invite/0xintuition) for real-time help from the community. **Documentation**: Check our comprehensive [documentation](/docs) for detailed guides and tutorials. **GitHub**: Report issues and contribute to the project on [GitHub](https://github.com/0xintuition). **Email Support**: Contact us directly at [support@intuition.systems](mailto:support@intuition.systems) for technical assistance. Use Cases & Contributing - Applications and ecosystem participation ## Use Cases & Contributing ### What are the main use cases for Intuition? **Knowledge Curation**: Build applications that help users discover and verify information through community consensus. **Social Platforms**: Create decentralized social networks with built-in reputation and trust systems. **Trust & Reputation**: Develop verifiable reputation systems that work across platforms and applications. **Verification & QA**: Use collective intelligence to verify and validate any type of information or claim. **Prediction Markets**: Build prediction markets with built-in verification and community consensus. **Business & Professional Platforms**: Create platforms that verify professional credentials and facilitate trusted business relationships. ### How do I contribute to the Intuition ecosystem? **Develop Applications**: Build applications that leverage Intuition's primitives and contribute to the ecosystem. **Improve Documentation**: Help improve our documentation by suggesting edits or contributing new guides. **Participate in Governance**: Stake tokens and participate in protocol governance decisions. **Report Issues**: Help improve the protocol by reporting bugs and suggesting improvements. **Community Building**: Help grow the community by answering questions and mentoring new developers. ## Need More Help?Can't find what you're looking for?
We're here to help! Reach out to our community or support team for assistance. Join Community Contact Support --- title: "Glossary" description: "Key terms and definitions for Intuition" last_updated: "2026-02-11T09:19:02-05:00" source: "https://docs.intuition.systems/docs/resources/glossary" --- # Glossary Comprehensive glossary of key terms used in Intuition documentation. ## A ### Atom A unique decentralized identifier for any entity, concept, or piece of data. Atoms are the fundamental building blocks of the knowledge graph. **See:** [Atoms Fundamentals](/docs/intuition-concepts/primitives/Atoms/fundamentals) **Example:** An atom representing "TypeScript" or an Ethereum address "0x742d35..." ### Attestation A verifiable claim or statement made on-chain using triples. Attestations can be supported or opposed through signals (staking). **See:** [Triples Fundamentals](/docs/intuition-concepts/primitives/Triples/fundamentals) **Example:** `[Alice] [endorses] [Bob]` is an attestation that Alice endorses Bob. ### AnyTrust DA Arbitrum's data availability solution that provides a trust-minimized alternative to standard rollup data availability. Uses a committee of trusted parties. **See:** [Network Architecture](/docs/intuition-network) ## B ### Bonding Curve A mathematical function that determines the price of vault shares based on supply. As more people stake, the price increases proportionally. **See:** [Signals](/docs/intuition-concepts/primitives/Signals/fundamentals) **Formula:** `price = k * supply^n` (where k and n are constants) ### Bridge A smart contract system that allows transferring assets between different blockchain networks. Intuition uses a bridge to connect testnet to Base Sepolia. **See:** [Network Overview](/docs/intuition-network) ## C ### Counter-Triple A triple that opposes or contradicts another triple. Used for expressing disagreement or alternative views in the knowledge graph. **Example:** - Triple: `[Contract A] [is safe] [true]` - Counter: `[Contract A] [is safe] [false]` **See:** [Triple Operations](/docs/intuition-sdk/triples-guide) ### Creator Fee A fee paid to the creator of an atom or triple when others interact with it. Incentivizes quality contributions. **See:** [Signals](/docs/intuition-concepts/primitives/Signals/fundamentals) ## D ### DID (Decentralized Identifier) A W3C standard for decentralized, self-sovereign identities. Intuition atoms can serve as DIDs for entities. **See:** [Core Concepts](/docs/intuition-concepts/primitives) **Format:** `did:intuition:FAQ
Frequently asked questions about Intuition. From basic concepts to advanced implementation details, get quick answers to common questions.Glossary
Comprehensive glossary of key terms and definitions. Master the essential terminology for working with Intuition.Tutorials
Step-by-step guides for building with Intuition. Learn by doing with hands-on tutorials covering common use cases. ## Community & SupportCommunity Channels
Connect with the Intuition community. Join Discord, Forum discussions, and follow us on Twitter for updates.Contributing
Help improve Intuition. Learn how to contribute to the protocol, documentation, and ecosystem.GitHub
Open source repositories for the Intuition protocol, SDK, and tools. Contribute code or report issues. ## SecurityAudit Reports
Third-party security audits of Intuition smart contracts. Review audit findings and security best practices.Bug Bounty
Report security vulnerabilities and earn rewards. Help keep Intuition secure through our bug bounty program. ## AI Agent Integrationllms.txt
Concise documentation index optimized for LLM consumption. Quick reference for AI agents integrating with Intuition.llms-full.txt
Complete documentation in LLM-friendly format. Full protocol reference for advanced AI agent integration. ## External Links ### Official Platforms - **[Website](https://intuition.systems)** - Official Intuition website - **[Portal](https://portal.intuition.systems)** - Protocol explorer and interface - **[Network Hub](https://testnet.hub.intuition.systems/)** - Testnet dashboard and tools - **[Blog](https://intuition.systems/blog)** - News, updates, and deep dives ### Developer Tools - **[GitHub](https://github.com/0xIntuition)** - Source code and repositories - **[NPM Packages](https://www.npmjs.com/org/0xintuition)** - Published npm packages - **[Status Page](https://status.intuition.systems)** - Network status monitoring ### Network Monitoring - **[Network Health](/docs/intuition-network)** - Real-time status - **[Testnet Explorer](https://testnet.explorer.intuition.systems)** - Blockchain explorer - **[GraphQL Playground](https://mainnet.intuition.sh/v1/graphql)** - Query interface ## Learning Resources ### Core Concepts - **[Primitives Overview](/docs/intuition-concepts/primitives)** - Understanding atoms, triples, and signals - **[Economics](/docs/intuition-concepts/economics)** - Tokenomics and incentive design - **[Architecture](/docs/intuition-concepts/architecture)** - System design and architecture ### Developer Guides - **[SDK Documentation](/docs/intuition-sdk/installation-and-setup)** - TypeScript SDK - **[Protocol API](/docs/protocol/api-reference/multivault/atoms)** - Smart contract API - **[GraphQL API](/docs/graphql-api/getting-started/introduction)** - Query language ### Tutorials - **[Create Your First Atom](/docs/tutorials/overview)** - Getting started - **[Build a Reputation System](/docs/tutorials/reputation-system)** - Intermediate tutorial - **[Custom Indexing](/docs/tutorials/advanced/batch-operations)** - Advanced topics ## Stay Updated ### Social Media - **[Twitter](https://twitter.com/0xIntuition)** - Latest news and announcements - **[Discord](https://discord.gg/RgBenkX4mx)** - Community chat and support - **[Newsletter](https://intuition.systems/newsletter)** - Monthly updates and highlights ### Development Updates - **[GitHub Releases](https://github.com/0xIntuition/intuition-contracts/releases)** - Protocol releases - **[SDK Changelog](https://github.com/0xIntuition/intuition-ts/releases)** - SDK updates - **[Documentation Updates](https://github.com/0xIntuition/intuition-docs/commits/main)** - Docs changelog ## Additional ToolsNetwork Health
Monitor real-time network status and uptime statistics. Stay informed about maintenance and incidents. --- title: "Key Terms" description: "Essential terminology and concepts for the Intuition ecosystem" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/resources/key-terms" --- # Key Terms This page defines the essential terminology and concepts you need to understand the Intuition protocol. Terms are organized by category to help you quickly find what you're looking for. ## Quick Navigation This page is organized into expandable sections for easy navigation. Click on any section below to explore the terms within that category. Core Primitives - Fundamental building blocks of the Intuition protocol ## Core Primitives ### **Atoms** **Atoms** are the fundamental building blocks of the Intuition knowledge graph. Each atom represents a unique entity or concept and points to arbitrary data via a URI. **Key Characteristics:** - **Universal Identifiers**: Each atom has a unique identifier across the entire system - **URI References**: Atoms point to any arbitrary URI (web pages, IPFS hashes, etc.) - **Economic Units**: Atoms can have economic value through bonding curves - **Composable**: Atoms can be combined to create more complex structures **Examples:** - A person's profile (points to their social media or personal website) - A smart contract address (points to the contract's metadata) - A piece of content (points to the actual content file) - An organization (points to their official website) ### **Triples** **Triples** represent relationships between atoms, forming the edges of the knowledge graph. Each triple consists of three atoms: a subject, predicate, and object. **Structure:** ``` Subject → Predicate → Object ``` **Key Characteristics:** - **Semantic Relationships**: Express meaningful connections between entities - **Economic Value**: Triples can have economic value through bonding curves - **Verifiable**: All relationships are cryptographically verifiable - **Composable**: Triples can be combined to create complex knowledge structures **Examples:** - **Subject**: Alice (atom) - **Predicate**: "works for" (atom) - **Object**: Intuition Systems (atom) This creates the statement: "Alice works for Intuition Systems" ### **Signals** **Signals** represent user attestations or endorsements of atoms and triples. They indicate the strength of belief or support for a particular piece of information. **Key Characteristics:** - **Economic Weight**: Signals have economic value and can be traded - **Subjective**: Represent personal beliefs and opinions - **Aggregatable**: Multiple signals can be combined to show collective sentiment - **Time-Bound**: Signals can change over time as opinions evolve **Types of Signals:** - **Positive Signals**: Endorsements or agreements - **Negative Signals**: Disagreements or refutations - **Neutral Signals**: Acknowledgment without taking a position Economic Components - Financial and incentive mechanisms ## Economic Components ### **Bonding Curves** **Bonding curves** are mathematical functions that determine the price of shares in atoms and triples based on supply and demand. They create economic incentives for information quality. **Key Functions:** - **Price Discovery**: Automatically determine fair market value - **Incentive Alignment**: Reward early adopters of valuable information - **Liquidity**: Provide continuous trading opportunities - **Anti-Speculation**: Prevent manipulation through mathematical constraints **Curve Types:** - **Pro-Rata Curves**: Linear pricing for stable assets - **Bonding Curves**: Dynamic pricing that rewards early adopters - **Custom Curves**: Specialized functions for specific use cases ### **Vaults** **Vaults** are smart contracts that hold the economic value associated with atoms and triples. They manage deposits, redemptions, and share distribution. **Key Functions:** - **Asset Management**: Safely store and manage user deposits - **Share Distribution**: Mint and burn shares based on economic activity - **Fee Collection**: Collect small fees to maintain the system - **Liquidity Provision**: Enable users to enter and exit positions **Vault Types:** - **Pro-Rata Vaults**: Traditional vaults with stable pricing - **Bonding Curve Vaults**: Dynamic vaults with variable pricing - **Multi-Curve Vaults**: Vaults supporting multiple pricing models ### **Terms** **Terms** are the conceptual representations of atoms and triples that contain multiple vaults. They represent the underlying semantic meaning regardless of economic implementation. **Key Characteristics:** - **Semantic Identity**: Maintains the core meaning across different vaults - **Economic Flexibility**: Can have multiple vaults with different curves - **Market Cap Aggregation**: Combines value across all associated vaults - **Universal Reference**: Provides a stable identifier for the concept Network Components - Protocol infrastructure and governance ## Network Components ### **Trust Protocol** The **Trust Protocol** is the foundational mechanism that enables trustful interactions through cryptoeconomic incentives. It rewards users for contributing valuable information. **Core Principles:** - **Economic Incentives**: Users are rewarded for valuable contributions - **Quality Signals**: Economic activity indicates information quality - **Decentralized Curation**: No central authority controls information - **Transparent Rules**: All mechanisms are open and verifiable ### **Knowledge Graph** The **Knowledge Graph** is the collective network of atoms, triples, and signals that represents humanity's shared knowledge. It grows organically through user contributions. **Key Features:** - **Permissionless**: Anyone can contribute information - **Verifiable**: All contributions are cryptographically verifiable - **Composable**: Information can be combined and reused - **Economic**: Valuable information is economically rewarded ### **Attestations** **Attestations** are user statements about atoms and triples that contribute to the collective knowledge. They can be positive, negative, or neutral. **Types of Attestations:** - **Factual Claims**: Statements about objective reality - **Opinions**: Subjective beliefs and preferences - **Endorsements**: Support for existing information - **Refutations**: Disagreements with existing information Technical Components - Developer tools and APIs ## Technical Components ### **GraphQL API** The **GraphQL API** provides a unified interface for querying and interacting with the Intuition knowledge graph. It enables efficient data retrieval and real-time updates. **Key Features:** - **Real-Time Queries**: Get live data from the knowledge graph - **Flexible Schema**: Query exactly the data you need - **Subscription Support**: Receive updates as data changes - **Batch Operations**: Efficiently process multiple requests ### **SDKs** **Software Development Kits (SDKs)** provide pre-built tools and libraries for integrating with the Intuition protocol. They simplify common development tasks. **Available SDKs:** - **JavaScript/TypeScript SDK**: For web applications - **React Components**: Pre-built UI components - **GraphQL Client**: Optimized for Intuition's GraphQL API - **Smart Contract Interfaces**: For direct blockchain interaction ### **Smart Contracts** **Smart contracts** are the on-chain components that handle the economic and governance aspects of the Intuition protocol. They ensure transparency and immutability. **Core Contracts:** - **EthMultiVault**: Manages deposits, redemptions, and share distribution - **AtomWallet**: Handles atom and triple creation - **BondingCurveRegistry**: Manages different curve implementations - **TrustBonding**: Implements trust-based economic mechanisms User Roles - Different ways to participate in the ecosystem ## User Roles ### **Attestors** **Attestors** are users who contribute information to the knowledge graph by creating atoms, triples, and signals. They are rewarded for valuable contributions. **Responsibilities:** - **Information Creation**: Add new atoms and triples to the graph - **Quality Assurance**: Provide signals to indicate information quality - **Community Building**: Participate in knowledge curation - **Economic Participation**: Engage with bonding curves and vaults ### **Curators** **Curators** are users who specialize in organizing and validating information within the knowledge graph. They help maintain quality and coherence. **Activities:** - **Signal Provision**: Provide economic signals for information quality - **Relationship Mapping**: Create meaningful triples between atoms - **Quality Assessment**: Evaluate and endorse valuable information - **Community Leadership**: Guide discussions and resolve disputes ### **Developers** **Developers** build applications and tools that interact with the Intuition protocol. They create the interfaces and experiences that make the knowledge graph accessible. **Development Areas:** - **Frontend Applications**: User interfaces for interacting with the graph - **Data Analytics**: Tools for analyzing knowledge graph data - **Integration Services**: APIs and services that connect to Intuition - **Mobile Applications**: Native mobile experiences Economic Terms - Financial metrics and market concepts ## Economic Terms ### **Market Cap** **Market cap** represents the total theoretical value of all shares in a term (atom or triple). It is calculated as the product of total shares and current share price. **Calculation:** ``` Market Cap = Total Shares × Current Share Price ``` **Significance:** - **Value Indicator**: Shows the perceived value of information - **Comparison Metric**: Allows comparison between different terms - **Investment Guide**: Helps users make informed decisions - **Quality Signal**: Higher market caps often indicate higher quality ### **Share Price** **Share price** is the current cost to purchase one share of a term. It is determined by the bonding curve function based on supply and demand. **Factors Affecting Price:** - **Supply**: Number of shares currently in circulation - **Demand**: User interest and willingness to pay - **Curve Function**: Mathematical relationship between supply and price - **Market Activity**: Recent trading volume and patterns ### **Liquidity** **Liquidity** refers to the ease with which shares can be bought or sold without significantly affecting the price. High liquidity enables efficient trading. **Liquidity Factors:** - **Trading Volume**: Amount of shares traded regularly - **Market Depth**: Number of buy and sell orders - **Price Stability**: How much price changes with large trades - **Accessibility**: How easy it is for users to participate Governance Terms - Protocol governance and decision-making ## Governance Terms ### **Proposals** **Proposals** are suggested changes to the Intuition protocol that are voted on by the community. They can include parameter changes, new features, or governance updates. **Proposal Types:** - **Parameter Changes**: Adjusting bonding curve parameters - **Feature Additions**: Adding new functionality to the protocol - **Governance Updates**: Changing how decisions are made - **Emergency Actions**: Responding to critical issues ### **Voting** **Voting** is the process by which the community makes decisions about the protocol. Votes are weighted by economic stake and participation. **Voting Mechanisms:** - **Token Weighted**: Votes are proportional to token holdings - **Time Locked**: Some proposals require time delays - **Multi-Sig**: Critical decisions require multiple approvals - **Emergency Powers**: Special procedures for urgent situations --- > **Ready to dive deeper?** Explore our [Architecture Guide](/docs/getting-started/architecture) to understand how these components work together, or check out our [Quick Start Guide](/docs/quick-start/using-the-sdk) to begin building with Intuition. --- title: "Optimizing Batch Operations" description: "Efficiently create multiple atoms and triples" last_updated: "2026-01-05T17:16:01-08:00" source: "https://docs.intuition.systems/docs/tutorials/advanced/batch-operations" --- # Optimizing Batch Operations > Coming soon! This tutorial will show how to efficiently create and manage multiple atoms and triples in batches. Learn how to optimize gas costs and improve performance when creating many atoms, triples, or signals at once. ## What You'll Learn This tutorial will cover: - Batch atom creation - Bulk triple creation - Multi-sig signal deposits - Gas optimization strategies - Transaction batching patterns - Error handling for batch operations ## In the Meantime See these resources: - [SDK Documentation](/docs/intuition-sdk/installation-and-setup) - [Protocol API Reference](/docs/protocol/api-reference/multivault/atoms) - [Performance Best Practices](/docs/intuition-sdk/quick-start) ## Quick Example ```typescript // Conceptual example - API may differ async function batchCreateAtoms(atomsData: ArraySafe DeFi Protocols] -->|subject| T1[Triple
contains] List -->|subject| T2[Triple
contains] List -->|subject| T3[Triple
contains] T1 -->|object| Item1[Item Atom
Aave] T2 -->|object| Item2[Item Atom
Uniswap] T3 -->|object| Item3[Item Atom
Compound] T1 -->|vault| V1[Vault 1] T2 -->|vault| V2[Vault 2] T3 -->|vault| V3[Vault 3] V1 -->|signals| S1[100 ETH
Rank #1] V2 -->|signals| S2[75 ETH
Rank #2] V3 -->|signals| S3[50 ETH
Rank #3] style List fill:#e1f5ff style Item1 fill:#e1f5ff style Item2 fill:#e1f5ff style Item3 fill:#e1f5ff style T1 fill:#fff4e1 style T2 fill:#fff4e1 style T3 fill:#fff4e1 style S1 fill:#e8f5e9 style S2 fill:#e8f5e9 style S3 fill:#e8f5e9 ``` **How It Works:** 1. **Lists** are atoms (e.g., "Top DeFi Protocols") 2. **Items** are atoms (e.g., "Aave", "Uniswap") 3. **Membership** is a triple: `[List] [contains] [Item]` 4. **Ranking** is determined by total stake in each triple's vault 5. **Curation** happens through signals (deposit = vouch, redeem = challenge) ## Part 1: Data Model Design ### Atoms We'll Create **List Atoms:** ```typescript { type: 'thing', value: 'Safe DeFi Protocols' } ``` **Item Atoms:** ```typescript // Option 1: Simple string { type: 'thing', value: 'Aave' } // Option 2: Contract address { type: 'account', value: '0x7Fc66500c84A76Ad7e9c93437bFc5Ac33E2DDaE9' // AAVE token } // Option 3: URL { type: 'thing', value: 'https://aave.com' } ``` ### Triple Structure Each list entry is a triple: ``` Subject: List ("Safe DeFi Protocols") Predicate: "contains" or "includes" Object: Item ("Aave") ``` The total signals on this triple = community confidence in this item being in the list. ## Part 2: Creating Lists ### Initialize SDK ```typescript import { createMultivault, getAtomId } from '@0xintuition/sdk' const multivault = createMultivault({ privateKey: process.env.PRIVATE_KEY!, rpcUrl: 'https://sepolia.base.org', multivaultAddress: '0x...' }) ``` ### Create a List Atom ```typescript async function createList(listName: string, description?: string) { try { const atomData = { type: 'thing', value: listName } const result = await multivault.createAtom({ atomUri: atomData }) console.log(`List created: ${listName}`) console.log(`List ID: ${result.atomId}`) // Optionally store metadata off-chain if (description) { // Store in IPFS or database await storeListMetadata(result.atomId, { name: listName, description, creator: multivault.getWalletAddress(), createdAt: Date.now() }) } return result.atomId } catch (error) { console.error('Error creating list:', error) throw error } } // Create example lists const safeDefiList = await createList( 'Safe DeFi Protocols', 'Community-vetted DeFi protocols with strong security records' ) const topNFTList = await createList( 'Top NFT Collections', 'Highest quality NFT projects' ) ``` ### Create the "contains" Predicate ```typescript async function createContainsPredicate() { const predicateData = { type: 'thing', value: 'contains' } const predicateId = getAtomId(predicateData) const exists = await multivault.atomExists(predicateId) if (!exists) { const result = await multivault.createAtom({ atomUri: predicateData }) return result.atomId } return predicateId } const containsPredicateId = await createContainsPredicate() ``` ## Part 3: Adding Items to Lists ### Submit an Item ```typescript async function submitToList( listAtomId: string, itemName: string, itemType: 'thing' | 'account' = 'thing', initialStake: bigint = BigInt(0) ) { try { // Create or get item atom const itemAtomId = getAtomId({ type: itemType, value: itemName.toLowerCase() }) const itemExists = await multivault.atomExists(itemAtomId) if (!itemExists) { await multivault.createAtom({ atomUri: { type: itemType, value: itemName.toLowerCase() } }) } // Create membership triple const result = await multivault.createTriple({ subjectId: listAtomId, predicateId: containsPredicateId, objectId: itemAtomId }) console.log(`Item submitted: ${itemName}`) console.log(`Triple ID: ${result.tripleId}`) // Optionally add initial stake if (initialStake > 0) { await multivault.depositTriple({ id: result.tripleId, amount: initialStake, receiver: multivault.getWalletAddress() }) } return result.tripleId } catch (error) { console.error('Error submitting item:', error) throw error } } // Submit DeFi protocols await submitToList(safeDefiList, 'Aave', 'thing', BigInt('1000000000000000000')) // 1 ETH await submitToList(safeDefiList, 'Uniswap', 'thing', BigInt('750000000000000000')) // 0.75 ETH await submitToList(safeDefiList, 'Compound', 'thing', BigInt('500000000000000000')) // 0.5 ETH ``` ### Batch Submit Items ```typescript async function batchSubmitToList( listAtomId: string, items: Array<{ name: string; type: 'thing' | 'account'; stake: bigint }> ) { const results = [] for (const item of items) { const tripleId = await submitToList( listAtomId, item.name, item.type, item.stake ) results.push({ name: item.name, tripleId }) } return results } // Add multiple items at once await batchSubmitToList(topNFTList, [ { name: 'CryptoPunks', type: 'thing', stake: BigInt('2000000000000000000') }, { name: 'Bored Ape Yacht Club', type: 'thing', stake: BigInt('1500000000000000000') }, { name: 'Azuki', type: 'thing', stake: BigInt('1000000000000000000') } ]) ``` ## Part 4: Curating with Signals ### Vouching for an Item (Deposit Signal) ```typescript async function vouchForItem(tripleId: string, amount: bigint) { try { const result = await multivault.depositTriple({ id: tripleId, amount: amount, receiver: multivault.getWalletAddress() }) console.log(`Vouched with ${amount} wei`) console.log(`Transaction: ${result.transactionHash}`) return result } catch (error) { console.error('Error vouching:', error) throw error } } // Vouch for Aave with 0.5 ETH await vouchForItem(aaveTripleId, BigInt('500000000000000000')) ``` ### Challenging an Item (Redeem Signal) ```typescript async function challengeItem(tripleId: string, amount: bigint, reason?: string) { try { const result = await multivault.redeemTriple({ id: tripleId, amount: amount }) console.log(`Challenged with ${amount} wei`) // Record challenge reason if (reason) { await storeChallengeReason(tripleId, { challenger: multivault.getWalletAddress(), amount: amount.toString(), reason, timestamp: Date.now() }) } return result } catch (error) { console.error('Error challenging:', error) throw error } } // Challenge a suspicious entry await challengeItem( suspiciousTripleId, BigInt('100000000000000000'), 'This protocol has security vulnerabilities' ) ``` ## Part 5: Ranking Algorithm ### Query List Items with Stakes ```typescript import { request, gql } from 'graphql-request' const GRAPHQL_ENDPOINT = 'https://mainnet.intuition.sh/v1/graphql' const GET_LIST_ITEMS = gql` query GetListItems($listAtomId: String!) { triples( where: { subject_id: { _eq: $listAtomId } predicate: { label: { _eq: "contains" } } } ) { term_id object { term_id label type } term { vaults(where: { curve_id: { _eq: "2" } }) { total_shares current_share_price position_count positions(order_by: { shares: desc }) { account_id shares created_at } } } } } ` async function getListItems(listAtomId: string) { const data = await request(GRAPHQL_ENDPOINT, GET_LIST_ITEMS, { listAtomId }) return data.triples } ``` ### Calculate Ranking ```typescript interface RankedItem { tripleId: string name: string rank: number totalStake: bigint vouchCount: number challengeCount: number confidence: number netSignal: bigint } function calculateRanking(items: any[]): RankedItem[] { const ranked = items.map(item => { const vault = item.term?.vaults?.[0] const positions = vault?.positions || [] // Total stake from all positions const totalStake = positions.reduce( (sum: bigint, p: any) => sum + BigInt(p.shares), BigInt(0) ) // Confidence score considers both amount and number of positions const stakeWeight = Math.log10(Number(totalStake) / 1e18 + 1) const participantWeight = Math.sqrt(positions.length) const confidence = stakeWeight * participantWeight return { tripleId: item.term_id, name: item.object.label, rank: 0, // Will be set after sorting totalStake, vouchCount: positions.length, challengeCount: 0, confidence, netSignal: totalStake } }) // Sort by net signal (descending) ranked.sort((a, b) => { const diff = Number(b.netSignal - a.netSignal) if (diff !== 0) return diff // Tiebreaker: more participants = higher rank return b.vouchCount - a.vouchCount }) // Assign ranks ranked.forEach((item, index) => { item.rank = index + 1 }) return ranked } // Usage const items = await getListItems(safeDefiList) const rankings = calculateRanking(items) console.log('Ranked Items:') rankings.forEach(item => { console.log(`#${item.rank} ${item.name}`) console.log(` Stake: ${Number(item.totalStake) / 1e18} ETH`) console.log(` Vouches: ${item.vouchCount}, Challenges: ${item.challengeCount}`) console.log(` Confidence: ${item.confidence.toFixed(2)}`) }) ``` ### Alternative: Time-Weighted Ranking Give more weight to recent signals: ```typescript function calculateTimeWeightedRanking(items: any[], decayRate: number = 0.95): RankedItem[] { const now = Date.now() / 1000 const ranked = items.map(item => { const signals = item.signals || [] let weightedVouches = BigInt(0) let weightedChallenges = BigInt(0) let vouchCount = 0 let challengeCount = 0 for (const signal of signals) { const age = now - signal.timestamp const daysPassed = age / (60 * 60 * 24) const decay = Math.pow(decayRate, daysPassed) const weightedDelta = BigInt(Math.floor(Number(signal.delta) * decay)) if (signal.direction === 'for') { weightedVouches += weightedDelta vouchCount++ } else { weightedChallenges += weightedDelta challengeCount++ } } const netSignal = weightedVouches - weightedChallenges return { tripleId: item.id, name: item.object.value, rank: 0, totalStake: weightedVouches, vouchCount, challengeCount, confidence: Math.log10(Number(netSignal) / 1e18 + 1) * Math.sqrt(vouchCount), netSignal } }) ranked.sort((a, b) => Number(b.netSignal - a.netSignal)) ranked.forEach((item, index) => { item.rank = index + 1 }) return ranked } ``` ## Part 6: Dispute Resolution ### Automatic Removal Threshold Remove items that fall below a threshold: ```typescript async function enforceMinimumStake( listAtomId: string, minimumStake: bigint ) { const items = await getListItems(listAtomId) const rankings = calculateRanking(items) const itemsToRemove = rankings.filter(item => item.netSignal < minimumStake) console.log(`Removing ${itemsToRemove.length} items below threshold`) for (const item of itemsToRemove) { // Note: Triples cannot be deleted, but we can flag them as removed await markItemAsRemoved(item.tripleId, 'Below minimum stake threshold') } return itemsToRemove } ``` ### Challenge Period Implement a waiting period before acceptance: ```typescript interface Submission { tripleId: string submittedAt: number challengePeriod: number } const CHALLENGE_PERIOD = 7 * 24 * 60 * 60 // 7 days in seconds async function getSubmissionStatus(tripleId: string): Promise<'pending' | 'accepted' | 'rejected'> { const submission = await getSubmissionMetadata(tripleId) const now = Date.now() / 1000 const elapsed = now - submission.submittedAt // Still in challenge period if (elapsed < submission.challengePeriod) { return 'pending' } // After challenge period, check net signal const item = await getTripleById(tripleId) const signals = item.signals || [] const netSignal = signals.reduce((sum, s) => { const delta = BigInt(s.delta) return s.direction === 'for' ? sum + delta : sum - delta }, BigInt(0)) // Positive net signal = accepted return netSignal > 0 ? 'accepted' : 'rejected' } ``` ## Part 7: UI Components ### List Display Component ```tsx import React, { useEffect, useState } from 'react' interface ListItem { rank: number name: string stake: string vouches: number challenges: number } export function CuratedList({ listAtomId }: { listAtomId: string }) { const [items, setItems] = useState
Loading list...
return (
{items.map(item => (
#{item.rank}
{item.name}
{item.stake} ETH staked
{item.vouches} vouches, {item.challenges} challenges
Submit Item to List
setItemName(e.target.value)} placeholder="Item name (e.g., Aave)" /> setInitialStake(e.target.value)} placeholder="Initial stake (ETH)" />{itemName}
Browse Curated Lists
{lists.map(list => (
))}
0xScam...] -->|is_safe| T1[Triple: FALSE] Contract -->|is_safe| T2[Triple: TRUE] T1 -->|signals| Expert1[Expert Signal
10 ETH Against] T1 -->|signals| User1[User Signal
1 ETH Against] T2 -->|signals| User2[User Signal
0.5 ETH For] T1 -->|weighted by| Rep1[Expert Reputation
High Trust] T2 -->|weighted by| Rep2[User Reputation
Low Trust] Result[Safety Score: -95%
UNSAFE] style Contract fill:#ffebee style T1 fill:#fff4e1 style T2 fill:#fff4e1 style Expert1 fill:#e8f5e9 style Result fill:#ffcdd2 ``` **How It Works:** 1. **Contracts** are represented as atoms 2. **Safety claims** are triples: `[Contract] [is_safe] [TRUE/FALSE]` 3. **Signals** represent votes for/against safety 4. **Expert weighting** gives more influence to trusted reporters 5. **Safety scores** aggregate weighted signals ## Part 1: Data Model ### Atoms **Contract Atoms:** ```typescript { type: 'account', value: '0x...' // Contract address } ``` **Boolean Atoms:** ```typescript { type: 'thing', value: 'true' } { type: 'thing', value: 'false' } ``` ### Predicates - `is_safe` - Safety claim predicate - `is_scam` - Alternative scam flag - `has_vulnerability` - Specific security issue ### Triple Examples **Safe Contract:** ``` [0xUniswap...] [is_safe] [true] ``` **Unsafe Contract:** ``` [0xScamToken...] [is_safe] [false] ``` ## Part 2: Setup and Initialization ### Initialize SDK ```typescript import { createMultivault, getAtomId } from '@0xintuition/sdk' const multivault = createMultivault({ privateKey: process.env.PRIVATE_KEY!, rpcUrl: 'https://sepolia.base.org', multivaultAddress: '0x...' }) ``` ### Create Boolean Atoms ```typescript async function initializeBooleanAtoms() { const trueAtom = { type: 'thing', value: 'true' } const falseAtom = { type: 'thing', value: 'false' } // Create or get atoms const trueId = getAtomId(trueAtom) const falseId = getAtomId(falseAtom) const trueExists = await multivault.atomExists(trueId) const falseExists = await multivault.atomExists(falseId) if (!trueExists) { await multivault.createAtom({ atomUri: trueAtom }) } if (!falseExists) { await multivault.createAtom({ atomUri: falseAtom }) } return { trueId, falseId } } const { trueId, falseId } = await initializeBooleanAtoms() ``` ### Create Predicates ```typescript async function createSafetyPredicates() { const predicates = ['is_safe', 'is_scam', 'has_vulnerability'] const predicateIds: Record
Checking safety...
if (!safety || safety.status === 'unknown') {
return No reports
}
const getColor = () => {
if (safety.status === 'safe') return 'green'
if (safety.status === 'unsafe') return 'red'
return 'gray'
}
return (
{safety.status === 'safe' ? '✓' : '⚠'}
{safety.status.toUpperCase()}
Score: {safety.score}/100
Confidence: {(safety.confidence * 100).toFixed(0)}%
{safety.totalReporters} reporters