Skip to main content

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
// 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:

{ "data": "Machine Learning" }
{ "data": "Vitalik Buterin" }
{ "data": "2024-01-15T10:00:00Z" }

Avoid:

{ "data": "ML" }  // Ambiguous
{ "data": "VB" }  // Unclear
{ "data": "today" }  // Not specific

4. Maintain Single Purpose​

Each Atom should represent one thing:

Good:

const ethereum = { data: "Ethereum" }
const blockchain = { data: "blockchain" }
const platform = { data: "platform" }

// Combine via Triple
[Ethereum] - [is a] - [blockchain platform]

Avoid:

// 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:

{
  "type": "concept",
  "content": "Smart Contract",
  "category": "blockchain"
}

Consistent:

{
  "type": "entity",
  "content": "Uniswap Protocol",
  "category": "defi"
}

Metadata Best Practices​

Required Metadata​

Always include:

  • Creation timestamps
  • Creator's DID
  • Version information for mutable atoms
{
  "metadata": {
    "created": "2024-01-15T10:30:00Z",
    "creator": "did:ethr:mainnet:0x123...",
    "version": "1.0",
    "lastModified": "2024-01-15T10:30:00Z"
  }
}
{
  "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:

// 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:

{ "data": "Technology" }  // Too broad

Better:

{ "data": "Blockchain Technology" }
{ "data": "AI Technology" }

2. Redundant Information​

Avoid:

{
  "data": "Ethereum blockchain cryptocurrency"
}

Better:

// Separate Atoms connected via Triples
[Ethereum] - [is a] - [blockchain]
[Ethereum] - [is a] - [cryptocurrency]

3. Time-Sensitive Data Without Timestamps​

Avoid:

{ "data": "Current CEO" }

Better:

[Company X] - [has CEO] - [Person Y]
// Add temporal context via Triple metadata

4. Ambiguous References​

Avoid:

{ "data": "Paris" }  // City or person?

Better:

{ "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​