The IXO Matrix provides encrypted data storage and secure messaging capabilities for the Spatial Web through Matrix protocol integration. It enables private data rooms, real-time communication, and secure file storage with end-to-end encryption.

Spatial Web Architecture

IXO Matrix functions as the data persistence and communication layer within the broader Spatial Web Stack architecture, providing sovereign data storage for digital twins and secure communication channels between entity domains and users.
IXO Matrix serves as the secure data layer that:
  • Stores digital twin data in encrypted rooms
  • Enables secure communication between entity domains and users
  • Provides file storage with access control
  • Manages state through specialized bots
IXO Matrix leverages the Matrix protocol’s federation capabilities to create a network of interconnected servers:
  • Homeservers: Individual Matrix servers that store user data and room state
  • Federation Protocol: Allows communication between different homeservers
  • Identity Servers: Optional servers that help users discover each other
  • Enhanced Security: DID-based identity integration and trusted server networks
  • IXO MultiClient SDK: Unified interface for the entire Spatial Web Stack
  • IXO Matrix SDK: Direct access to Matrix functionality
  • IXO Matrix Room Bot: Automates room management tasks
  • IXO Matrix State Bot: Manages room state and access control
  • Matrix MCP Server: AI Agent interface using Model Context Protocol (upcoming)

Core Components

Data Rooms

Encrypted spaces for storing sensitive data with controlled access

Messaging

Secure real-time communication channels between entities

File Storage

End-to-end encrypted file storage with access control

State Management

Room state and configuration management through IXO Matrix State Bot

Data Room Architecture

  • Entity Rooms: Digital twin data storage
  • Project Rooms: Collaboration spaces
  • Device Rooms: IoT device telemetry
  • Verification Rooms: Oracle processing
  • End-to-End Encryption: All data encrypted by default
  • Access Control: Role-based permissions
  • Key Management: Secure key distribution
  • Audit Trails: Activity logging

Implementation Guide

Creating Data Rooms

import { MatrixClient } from '@ixo/matrixclient-sdk'

// Initialize Matrix client
const matrix = new MatrixClient({
  baseUrl: 'https://matrix.ixo.world',
  accessToken: 'YOUR_ACCESS_TOKEN'
})

// Create encrypted room
const room = await matrix.createRoom({
  name: 'Project Data Room',
  encryption: true,
  preset: 'private_chat',
  initialState: [{
    type: 'm.room.encryption',
    state_key: '',
    content: { algorithm: 'm.megolm.v1.aes-sha2' }
  }]
})

// Set room permissions
await matrix.setRoomPermissions(room.id, {
  readAccess: ['@alice:ixo.world'],
  writeAccess: ['@bob:ixo.world']
})

Storing Data

// Store encrypted data
await matrix.sendEvent(room.id, 'data.store', {
  type: 'ProjectMetrics',
  data: encryptedData,
  metadata: {
    timestamp: Date.now(),
    version: '1.0'
  }
})

// Store file
const fileEvent = await matrix.sendFile(room.id, {
  file: fileData,
  filename: 'metrics.json',
  mimetype: 'application/json'
})

Real-Time Messaging

// Send secure message
await matrix.sendMessage(room.id, {
  msgtype: 'm.text',
  body: encryptedMessage
})

// Listen for messages
matrix.on('room.message', (event) => {
  if (event.getType() === 'm.room.message') {
    console.log('New message:', event.getContent().body)
  }
})

State Management

import { createMatrixStateBotClient } from "@ixo/matrixclient-sdk";

// Initialize IXO Matrix State Bot
const stateBot = await createMatrixStateBotClient({
  baseUrl: "https://matrix.ixo.world",
  accessToken: "BOT_TOKEN"
});

// Get room state
const state = await stateBot.getRoomState(room.id);

// Update state
await stateBot.setState(
  room.id,
  "custom.state.type",
  "",
  { key: "value" }
);

Integration Components

IXO MultiClient SDK

import { IxoClient } from '@ixo/impactxclient-sdk';

// Initialize the client
const client = new IxoClient({
  matrix: {
    baseUrl: 'https://matrix.ixo.world',
    accessToken: 'YOUR_ACCESS_TOKEN'
  },
  blockchain: {
    rpcUrl: 'https://rpc.ixo.earth'
  },
  oracles: {
    baseUrl: 'https://oracles.ixo.earth'
  }
});

// Create a data room for a digital twin
const room = await client.matrix.createRoom({
  name: 'Digital Twin Data Room',
  encryption: true,
  visibility: 'private'
});

// Store data in the room
await client.matrix.sendEvent(room.roomId, 'data.store', {
  type: 'TwinState',
  data: encryptedData
});

IXO Matrix Room Bot

import { createMatrixRoomBotClient } from '@ixo/matrixclient-sdk';

// Initialize room bot
const bot = await createMatrixRoomBotClient({
  baseUrl: 'https://matrix.ixo.world',
  accessToken: 'BOT_TOKEN'
});

// Create entity room
const entityRoom = await bot.createEntityRoom({
  entityDid: 'did:ixo:entity/123',
  name: 'Entity Data Room',
  members: ['@alice:ixo.world', '@bob:ixo.world']
});

// Handle invites
await bot.handleInvites();

Automated Room Creation

IXO Matrix provides automated room creation for domain entities registered on the IXO blockchain. This process is managed by the Matrix Server Bot, which monitors the blockchain for new entity registrations and creates corresponding Matrix rooms.

Matrix MCP Server and AuthIXO

The upcoming Matrix MCP (Model Context Protocol) Server is a custom Anthropic-based server that enables AI Agents to interface with Matrix Servers:
  • AI Agent Integration: Allows AI agents to participate in Matrix rooms and process data
  • Context-Aware Processing: Maintains conversation context for intelligent interactions
  • Secure Agent Communication: Enables secure communication between AI agents and users
  • Multi-Modal Support: Processes various data types including text, images, and structured data
AuthIXO is IXO’s implementation of decentralized delegated authorization using Cabaility-based Access Control (CBAC):
  • Capability Tokens: Cryptographically signed tokens that grant specific permissions
  • Delegation Chains: Allow for secure delegation of capabilities across entities
  • Revocation Mechanisms: Enable immediate revocation of granted capabilities
  • Blockchain Integration: References Parent Capability on the IXO blockchain (under the accordedRight property of an entity’s DID document) and uses the Capability Delegation and Capability Invocation keys that are listed as Verification Methods and Verification Relationships in an entity’s DID document.
// Create a capability token (AuthCAP)
const capabilityToken = await AuthIXO.createCapability({
  issuer: 'did:ixo:entity/issuer',
  subject: 'did:ixo:entity/subject',
  action: 'matrix:sendMessage',
  resource: 'matrix:room:!roomId:ixo.world',
  constraints: {
    expiry: Date.now() + 86400000, // 24 hours
    maxUses: 10
  }
});

// Use the capability token to authorize an action
const result = await matrix.sendMessageWithCapability(
  roomId,
  { msgtype: 'm.text', body: 'Hello, world!' },
  capabilityToken
);
import { MatrixClient, MCPAgentClient } from '@ixo/matrixclient-sdk';

// Initialize Matrix client
const matrix = new MatrixClient({
  baseUrl: 'https://matrix.ixo.world',
  accessToken: 'YOUR_ACCESS_TOKEN'
});

// Initialize MCP Agent client
const agent = new MCPAgentClient({
  baseUrl: 'https://mcp.ixo.world',
  agentId: 'verification-agent',
  capabilities: ['data-analysis', 'verification']
});

// Connect agent to a Matrix room
await agent.joinRoom(roomId);

// Configure agent to process specific event types
await agent.subscribeToEvents(roomId, ['m.room.message', 'data.verification.request']);

// Agent automatically processes events and responds in the room

Use Cases

Digital Twin Data

Store and manage digital twin state and history with secure access controls

IoT Telemetry

Collect and process device data streams with real-time updates

Verification Data

Store verification results and evidence for audit and compliance

Collaboration

Enable secure team communication with end-to-end encryption

Security Considerations

  • Use end-to-end encryption for all rooms
  • Implement proper key management
  • Rotate encryption keys regularly
  • Secure key backup and recovery
  • Implement role-based access
  • Regular permission audits
  • Monitor room membership
  • Enforce least privilege
  • Encrypt sensitive data
  • Implement data retention
  • Regular security audits
  • Backup critical data
  • Limit federation to trusted homeservers
  • Implement server access control lists
  • Verify encryption status across federated rooms
  • Monitor federation traffic for anomalies
  • Implement proper server authentication

Best Practices

Room Management

  • Create separate rooms for different purposes
  • Use clear naming conventions
  • Document room purposes
  • Regular access reviews
  • Monitor room sizes

Data Handling

  • Validate data before storage
  • Implement error handling
  • Use appropriate event types
  • Monitor storage usage
  • Regular data cleanup

Performance

  • Batch operations when possible
  • Implement caching
  • Handle rate limits
  • Monitor API usage
  • Optimize file sizes

Next Steps