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 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 Example

Basic 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 Handling

Common 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 - Learn how to create relationships between atoms
Deposit & Return - Manage vault deposits and withdrawals
Retrieve Vault Details - Get comprehensive vault information

For a full reference implementation, see the Intuition TypeScript SDK.

Prerequisites​

Implementation​