Domain Settings - IXO Docs Hub

A Domain in IXO represents the on-chain identity record (DID Document) of a Digital Entity, providing management capabilities for verification methods, services, and access controls. Each Digital Entity is anchored by its Domain, which forms a core component of its Digital Twin implementation. Managing Domain settings allows you to configure how your Digital Entity interacts with other participants and services on the IXO network.

IID Document Management

The IXO ID (IID) Module provides a comprehensive set of methods for managing a Domain’s properties on IXO blockchains. Each Domain has a unique identifier that resolves to a W3C-standard DID Document following the IXO ID Method specification. IIDs are IXO’s implementation of the W3C DID standard, extending it with specific features for cross-chain identity and interoperability in the Interchain ecosystem while maintaining full compatibility with the DID specification.

Key differences from standard DIDs:

Cross-chain resolution through IBC (Inter-Blockchain Communication)
Native integration with Cosmos SDK modules
Extended verification methods for blockchain-specific operations
Built-in support for IXO’s domain-specific digital twin features, such as Linked Resources, Linked Entities, Linked Claims, Accorded Rights, and Accounts

Prerequisites

Before managing Domain settings, ensure you have:

An IXO wallet with sufficient tokens for transaction fees
The Domain’s IID (identifier)
Appropriate signing authority (you must be a controller of the Domain)
The IXO SDK installed (if using programmatically)

npm install @ixo/sdk

Domain Management Operations

The following sections outline the key operations you can perform on your Domain’s IID Document.

Document Updates

Document updates allow you to modify multiple properties of your Domain’s IID Document in a single transaction.

When to use: When you need to make multiple changes to your Domain document at once, such as updating verification methods, controllers, and services simultaneously.

Important considerations:

Updates replace existing properties, so include all current values you wish to keep
Fields not included in the update will remain unchanged
Document updates are atomic - they either succeed completely or fail

interface IIDDocumentUpdate {
  context?: string[];
  controller?: string[];
  verificationMethod?: VerificationMethod[];
  authentication?: string[];
  assertionMethod?: string[];
  keyAgreement?: string[];
  capabilityInvocation?: string[];
  capabilityDelegation?: string[];
  service?: Service[];
}

async function updateIIDDocument(
  id: string,
  update: IIDDocumentUpdate
): Promise<void> {
  const msg = {
    typeUrl: "/ixo.iid.v1beta1.MsgUpdateIidDocument",
    value: {
      id,
      controller: update.controller,
      verificationMethod: update.verificationMethod,
      authentication: update.authentication,
      assertionMethod: update.assertionMethod,
      keyAgreement: update.keyAgreement,
      capabilityInvocation: update.capabilityInvocation,
      capabilityDelegation: update.capabilityDelegation,
      service: update.service
    }
  };
  
  await signAndBroadcast(msg);
}

Verification Methods

Verification methods define the cryptographic keys and proofs your Domain can use for authentication, authorization, and secure communication.

When to use: Add verification methods when you need to enable specific cryptographic operations for your Domain, such as digital signatures or key exchange.

Important considerations:

Each verification method must have a unique ID within the Domain
Different verification types support different cryptographic algorithms
Relationships determine what operations a verification method can be used for

interface VerificationMethod {
  id: string;
  type: string;
  controller: string;
  publicKeyMultibase: string;
}

async function addVerificationMethod(
  id: string,
  method: VerificationMethod,
  relationships: string[]
): Promise<void> {
  const msg = {
    typeUrl: "/ixo.iid.v1beta1.MsgAddVerification",
    value: {
      id,
      verification: method,
      relationships // e.g. ["authentication", "keyAgreement"]
    }
  };
  
  await signAndBroadcast(msg);
}

async function setVerificationRelationships(
  id: string,
  methodId: string,
  relationships: string[]
): Promise<void> {
  const msg = {
    typeUrl: "/ixo.iid.v1beta1.MsgSetVerificationRelationships",
    value: {
      id,
      methodId,
      relationships
    }
  };
  
  await signAndBroadcast(msg);
}

async function revokeVerification(
  id: string,
  methodId: string
): Promise<void> {
  const msg = {
    typeUrl: "/ixo.iid.v1beta1.MsgRevokeVerification",
    value: {
      id,
      methodId
    }
  };
  
  await signAndBroadcast(msg);
}

Services

Services allow your Domain to expose functionality to other entities. Each service has an ID, type, and endpoint.

When to use: Add services when you want to expose APIs, messaging endpoints, or other functionality through your Domain.

Important considerations:

Service endpoints should be secure and reliable
Service types should follow standards for interoperability
Services can be discovered through the IID Document

interface Service {
  id: string;
  type: string;
  serviceEndpoint: string;
}

async function addService(
  id: string,
  service: Service
): Promise<void> {
  const msg = {
    typeUrl: "/ixo.iid.v1beta1.MsgAddService",
    value: {
      id,
      serviceData: service
    }
  };
  
  await signAndBroadcast(msg);
}

async function deleteService(
  id: string,
  serviceId: string
): Promise<void> {
  const msg = {
    typeUrl: "/ixo.iid.v1beta1.MsgDeleteService",
    value: {
      id,
      serviceId
    }
  };
  
  await signAndBroadcast(msg);
}

Controllers & Resources

Controllers determine who can modify the Domain’s IID Document, while linked resources and accorded rights define what resources and rights are associated with the Domain.

When to use: Add controllers when delegating management permissions, and add resources or rights when declaring assets or capabilities associated with your Domain.

Important considerations:

Controllers have full management capabilities over the Domain
Linked resources can reference any external asset related to the Domain
Accorded rights represent permissions or capabilities granted by the Domain

async function addController(
  id: string,
  controllerDid: string
): Promise<void> {
  const msg = {
    typeUrl: "/ixo.iid.v1beta1.MsgAddController",
    value: {
      id,
      controller: controllerDid
    }
  };
  
  await signAndBroadcast(msg);
}

async function addLinkedResource(
  id: string,
  resource: LinkedResource
): Promise<void> {
  const msg = {
    typeUrl: "/ixo.iid.v1beta1.MsgAddLinkedResource",
    value: {
      id,
      resource
    }
  };
  
  await signAndBroadcast(msg);
}

async function addAccordedRight(
  id: string,
  right: AccordedRight
): Promise<void> {
  const msg = {
    typeUrl: "/ixo.iid.v1beta1.MsgAddAccordedRight",
    value: {
      id,
      right
    }
  };
  
  await signAndBroadcast(msg);
}

Context & Deactivation

Context provides semantic meaning to your Domain document, while deactivation allows you to temporarily disable your Domain.

When to use: Add context to improve interoperability with systems that understand specific vocabularies. Deactivate a Domain when you want to temporarily suspend its operations.

Important considerations:

Contexts should reference well-known semantic vocabularies
Deactivating a Domain doesn’t delete it but prevents its use
Deactivation can be reversed by setting state to false

async function addContext(
  id: string,
  context: string
): Promise<void> {
  const msg = {
    typeUrl: "/ixo.iid.v1beta1.MsgAddIidContext",
    value: {
      id,
      context
    }
  };
  
  await signAndBroadcast(msg);
}

async function deactivateIID(
  id: string,
  state: boolean
): Promise<void> {
  const msg = {
    typeUrl: "/ixo.iid.v1beta1.MsgDeactivateIID",
    value: {
      id,
      state
    }
  };
  
  await signAndBroadcast(msg);
}

Domain Management Workflow

Following these steps will help you effectively manage your Domain settings on IXO blockchains.

Update Document Structure

Update your Domain’s IID Document structure by:

Modifying verification methods
Updating service endpoints
Adding or removing controllers
Managing linked resources

Manage Verification

Handle verification methods and relationships:

Add new verification methods
Set verification relationships
Handle method revocation
Update verification proofs

Service Management

Configure and manage Domain services:

Add new service endpoints
Update existing services
Remove deprecated services
Configure service mediators

Access Control

Manage Domain access and permissions:

Add Domain controllers
Grant specific rights
Set capability invocations
Configure capability delegation

Implementation Guide

Each step in the process above corresponds to specific API calls in the IXO SDK. Expand the accordions above to see the code examples for each operation, or follow the detailed guides below for common domain management tasks.

Common Domain Management Tasks

Example: Creating a Service-Oriented Domain

Create the Domain IID Document

First, initialize a basic Domain document with a controller:

// Example of IID Document creation
const domain = await createIidDocument({
  controllers: [myWalletAddress],
  // other initial properties
});

Add Service Endpoints

Add service endpoints to make your Domain functional:

await addService(
  domain.id,
  {
    id: `${domain.id}#messaging`,
    type: "MessagingService",
    serviceEndpoint: "https://messaging.example.com"
  }
);

Set Up Verification Methods

Add verification methods to enable authentication:

const verificationMethod = {
  id: `${domain.id}#keys-1`,
  type: "Ed25519VerificationKey2020",
  controller: domain.id,
  publicKeyMultibase: "z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
};

await addVerificationMethod(
  domain.id,
  verificationMethod,
  ["authentication", "assertionMethod"]
);

Example: Updating Domain Controllers

Retrieve Current Controllers

First, get the current list of controllers:

const document = await queryIidDocument(domainId);
const currentControllers = document.controller;

Add New Controller

Add a new controller to the Domain:

await addController(
  domainId,
  "did:ixo:123456789abcdefghi"
);

Update Verification Relationships

Ensure the new controller has appropriate verification relationships:

await setVerificationRelationships(
  domainId,
  `${domainId}#keys-1`,
  ["authentication", "capabilityInvocation"]
);

Troubleshooting

Transaction Failed: Unauthorized

Invalid Verification Method

Service Endpoint Unreachable

IXO Identity

Learn about the IXO identity system and how Domains fit into the broader identity framework.

Verification Methods

Explore different verification method types and their cryptographic properties.

Service Types

Discover standard service types and how to implement custom services for your Domain.

W3C DID Specification

Review the W3C standard that defines the Decentralized Identifier specification.

IXO SDK Reference

Access comprehensive API documentation for the IXO SDK.

Domain Examples

See real-world examples of Domains in action with sample code.

On this page

IID Document Management
Prerequisites
Domain Management Operations
Domain Management Workflow
Implementation Guide
Common Domain Management Tasks
Example: Creating a Service-Oriented Domain
Example: Updating Domain Controllers
Troubleshooting
Related Resources

IID Document Management

Key differences from standard DIDs:

Cross-chain resolution through IBC (Inter-Blockchain Communication)
Native integration with Cosmos SDK modules
Extended verification methods for blockchain-specific operations
Built-in support for IXO’s domain-specific digital twin features, such as Linked Resources, Linked Entities, Linked Claims, Accorded Rights, and Accounts

Prerequisites

Before managing Domain settings, ensure you have:

An IXO wallet with sufficient tokens for transaction fees
The Domain’s IID (identifier)
Appropriate signing authority (you must be a controller of the Domain)
The IXO SDK installed (if using programmatically)

npm install @ixo/sdk

Domain Management Operations

The following sections outline the key operations you can perform on your Domain’s IID Document.

Document Updates

Document updates allow you to modify multiple properties of your Domain’s IID Document in a single transaction.

When to use: When you need to make multiple changes to your Domain document at once, such as updating verification methods, controllers, and services simultaneously.

Important considerations:

Updates replace existing properties, so include all current values you wish to keep
Fields not included in the update will remain unchanged
Document updates are atomic - they either succeed completely or fail

interface IIDDocumentUpdate {
  context?: string[];
  controller?: string[];
  verificationMethod?: VerificationMethod[];
  authentication?: string[];
  assertionMethod?: string[];
  keyAgreement?: string[];
  capabilityInvocation?: string[];
  capabilityDelegation?: string[];
  service?: Service[];
}

async function updateIIDDocument(
  id: string,
  update: IIDDocumentUpdate
): Promise<void> {
  const msg = {
    typeUrl: "/ixo.iid.v1beta1.MsgUpdateIidDocument",
    value: {
      id,
      controller: update.controller,
      verificationMethod: update.verificationMethod,
      authentication: update.authentication,
      assertionMethod: update.assertionMethod,
      keyAgreement: update.keyAgreement,
      capabilityInvocation: update.capabilityInvocation,
      capabilityDelegation: update.capabilityDelegation,
      service: update.service
    }
  };
  
  await signAndBroadcast(msg);
}

Verification Methods

Verification methods define the cryptographic keys and proofs your Domain can use for authentication, authorization, and secure communication.

When to use: Add verification methods when you need to enable specific cryptographic operations for your Domain, such as digital signatures or key exchange.

Important considerations:

Each verification method must have a unique ID within the Domain
Different verification types support different cryptographic algorithms
Relationships determine what operations a verification method can be used for

interface VerificationMethod {
  id: string;
  type: string;
  controller: string;
  publicKeyMultibase: string;
}

async function addVerificationMethod(
  id: string,
  method: VerificationMethod,
  relationships: string[]
): Promise<void> {
  const msg = {
    typeUrl: "/ixo.iid.v1beta1.MsgAddVerification",
    value: {
      id,
      verification: method,
      relationships // e.g. ["authentication", "keyAgreement"]
    }
  };
  
  await signAndBroadcast(msg);
}

async function setVerificationRelationships(
  id: string,
  methodId: string,
  relationships: string[]
): Promise<void> {
  const msg = {
    typeUrl: "/ixo.iid.v1beta1.MsgSetVerificationRelationships",
    value: {
      id,
      methodId,
      relationships
    }
  };
  
  await signAndBroadcast(msg);
}

async function revokeVerification(
  id: string,
  methodId: string
): Promise<void> {
  const msg = {
    typeUrl: "/ixo.iid.v1beta1.MsgRevokeVerification",
    value: {
      id,
      methodId
    }
  };
  
  await signAndBroadcast(msg);
}

Services

Services allow your Domain to expose functionality to other entities. Each service has an ID, type, and endpoint.

When to use: Add services when you want to expose APIs, messaging endpoints, or other functionality through your Domain.

Important considerations:

Service endpoints should be secure and reliable
Service types should follow standards for interoperability
Services can be discovered through the IID Document

interface Service {
  id: string;
  type: string;
  serviceEndpoint: string;
}

async function addService(
  id: string,
  service: Service
): Promise<void> {
  const msg = {
    typeUrl: "/ixo.iid.v1beta1.MsgAddService",
    value: {
      id,
      serviceData: service
    }
  };
  
  await signAndBroadcast(msg);
}

async function deleteService(
  id: string,
  serviceId: string
): Promise<void> {
  const msg = {
    typeUrl: "/ixo.iid.v1beta1.MsgDeleteService",
    value: {
      id,
      serviceId
    }
  };
  
  await signAndBroadcast(msg);
}

Controllers & Resources

Controllers determine who can modify the Domain’s IID Document, while linked resources and accorded rights define what resources and rights are associated with the Domain.

When to use: Add controllers when delegating management permissions, and add resources or rights when declaring assets or capabilities associated with your Domain.

Important considerations:

Controllers have full management capabilities over the Domain
Linked resources can reference any external asset related to the Domain
Accorded rights represent permissions or capabilities granted by the Domain

async function addController(
  id: string,
  controllerDid: string
): Promise<void> {
  const msg = {
    typeUrl: "/ixo.iid.v1beta1.MsgAddController",
    value: {
      id,
      controller: controllerDid
    }
  };
  
  await signAndBroadcast(msg);
}

async function addLinkedResource(
  id: string,
  resource: LinkedResource
): Promise<void> {
  const msg = {
    typeUrl: "/ixo.iid.v1beta1.MsgAddLinkedResource",
    value: {
      id,
      resource
    }
  };
  
  await signAndBroadcast(msg);
}

async function addAccordedRight(
  id: string,
  right: AccordedRight
): Promise<void> {
  const msg = {
    typeUrl: "/ixo.iid.v1beta1.MsgAddAccordedRight",
    value: {
      id,
      right
    }
  };
  
  await signAndBroadcast(msg);
}

Context & Deactivation

Context provides semantic meaning to your Domain document, while deactivation allows you to temporarily disable your Domain.

When to use: Add context to improve interoperability with systems that understand specific vocabularies. Deactivate a Domain when you want to temporarily suspend its operations.

Important considerations:

Contexts should reference well-known semantic vocabularies
Deactivating a Domain doesn’t delete it but prevents its use
Deactivation can be reversed by setting state to false

async function addContext(
  id: string,
  context: string
): Promise<void> {
  const msg = {
    typeUrl: "/ixo.iid.v1beta1.MsgAddIidContext",
    value: {
      id,
      context
    }
  };
  
  await signAndBroadcast(msg);
}

async function deactivateIID(
  id: string,
  state: boolean
): Promise<void> {
  const msg = {
    typeUrl: "/ixo.iid.v1beta1.MsgDeactivateIID",
    value: {
      id,
      state
    }
  };
  
  await signAndBroadcast(msg);
}

Domain Management Workflow

Following these steps will help you effectively manage your Domain settings on IXO blockchains.

Update Document Structure

Update your Domain’s IID Document structure by:

Modifying verification methods
Updating service endpoints
Adding or removing controllers
Managing linked resources

Manage Verification

Handle verification methods and relationships:

Add new verification methods
Set verification relationships
Handle method revocation
Update verification proofs

Service Management

Configure and manage Domain services:

Add new service endpoints
Update existing services
Remove deprecated services
Configure service mediators

Access Control

Manage Domain access and permissions:

Add Domain controllers
Grant specific rights
Set capability invocations
Configure capability delegation

Implementation Guide

Common Domain Management Tasks

Example: Creating a Service-Oriented Domain

Create the Domain IID Document

First, initialize a basic Domain document with a controller:

// Example of IID Document creation
const domain = await createIidDocument({
  controllers: [myWalletAddress],
  // other initial properties
});

Add Service Endpoints

Add service endpoints to make your Domain functional:

await addService(
  domain.id,
  {
    id: `${domain.id}#messaging`,
    type: "MessagingService",
    serviceEndpoint: "https://messaging.example.com"
  }
);

Set Up Verification Methods

Add verification methods to enable authentication:

const verificationMethod = {
  id: `${domain.id}#keys-1`,
  type: "Ed25519VerificationKey2020",
  controller: domain.id,
  publicKeyMultibase: "z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
};

await addVerificationMethod(
  domain.id,
  verificationMethod,
  ["authentication", "assertionMethod"]
);

Example: Updating Domain Controllers

Retrieve Current Controllers

First, get the current list of controllers:

const document = await queryIidDocument(domainId);
const currentControllers = document.controller;

Add New Controller

Add a new controller to the Domain:

await addController(
  domainId,
  "did:ixo:123456789abcdefghi"
);

Update Verification Relationships

Ensure the new controller has appropriate verification relationships:

await setVerificationRelationships(
  domainId,
  `${domainId}#keys-1`,
  ["authentication", "capabilityInvocation"]
);

Troubleshooting

Transaction Failed: Unauthorized

Invalid Verification Method

Service Endpoint Unreachable

IXO Identity

Learn about the IXO identity system and how Domains fit into the broader identity framework.

Verification Methods

Explore different verification method types and their cryptographic properties.

Service Types

Discover standard service types and how to implement custom services for your Domain.

W3C DID Specification

Review the W3C standard that defines the Decentralized Identifier specification.

IXO SDK Reference

Access comprehensive API documentation for the IXO SDK.

Domain Examples

See real-world examples of Domains in action with sample code.

On this page

IID Document Management
Prerequisites
Domain Management Operations
Domain Management Workflow
Implementation Guide
Common Domain Management Tasks
Example: Creating a Service-Oriented Domain
Example: Updating Domain Controllers
Troubleshooting
Related Resources

​IID Document Management

​Prerequisites

​Domain Management Operations

​Domain Management Workflow

​Implementation Guide

​Common Domain Management Tasks

​Example: Creating a Service-Oriented Domain

​Example: Updating Domain Controllers

​Troubleshooting

​Related Resources

IXO Identity

Verification Methods

Service Types

W3C DID Specification

IXO SDK Reference

Domain Examples

​IID Document Management

​Prerequisites

​Domain Management Operations

​Domain Management Workflow

​Implementation Guide

​Common Domain Management Tasks

​Example: Creating a Service-Oriented Domain

​Example: Updating Domain Controllers

​Troubleshooting

​Related Resources

IXO Identity

Verification Methods

Service Types

W3C DID Specification

IXO SDK Reference

Domain Examples

IID Document Management

Prerequisites

Domain Management Operations

Domain Management Workflow

Implementation Guide

Common Domain Management Tasks

Example: Creating a Service-Oriented Domain

Example: Updating Domain Controllers

Troubleshooting

Related Resources

IID Document Management

Prerequisites

Domain Management Operations

Domain Management Workflow

Implementation Guide

Common Domain Management Tasks

Example: Creating a Service-Oriented Domain

Example: Updating Domain Controllers

Troubleshooting

Related Resources