ns

The did:ixo DID Method

The did:ixo DID method defines Decentralized Identifiers for IXO Impact Hub domains, accounts, and CosmWasm contracts used by IXO applications. This document is the canonical reference for the did:ixo method. It reconciles the IXO Interchain Identifiers source material with the implemented Impact Hub ixo.iid.v1beta1, ixo.entity.v1beta1, and claims-module identifier conventions.

This document provides the canonical DID Method specification URL and W3C DID Method Registry entry for the method name ixo.

1. Conformance

The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, and MAY in this document are to be interpreted as described in BCP 14.

Conforming did:ixo implementations MUST conform to:

Resolvers for did:ixo SHOULD follow the DID Resolution interface, architecture, error, caching, security, and privacy guidance.

The pinned Interchain Identifiers document stored at interchain-identifiers/v1.md is source material and implementation history, not a second normative DID method definition. If that document, a JSON-LD context, or any other IXO namespace document conflicts with this specification for did:ixo syntax, operations, resolution, or method-specific semantics, this specification controls.

The canonical Verifiable Data Registry (VDR) for this method is IXO Impact Hub mainnet. Testnet, devnet, and private deployments MAY implement compatible resolution for development, but they are not the canonical VDR for did:ixo.

2. Method Syntax

The DID method name is:

ixo

A did:ixo DID has one of three canonical method-specific identifier forms:

did:ixo:<account>
did:ixo:entity:<id>
did:ixo:wasm:<contract-address>

Where:

The method-specific identifier syntax is:

ixo-did        = "did:ixo:" (account-id / entity-id / wasm-id)
account-id     = ixo-address
entity-id      = "entity:" 32lowerhex
wasm-id        = "wasm:" ixo-address
ixo-address    = "ixo1" 1*bech32char
lowerhex       = %x30-39 / %x61-66
bech32char     = "q" / "p" / "z" / "r" / "y" / "9" / "x" / "8" /
                 "g" / "f" / "2" / "t" / "v" / "d" / "w" / "0" /
                 "s" / "3" / "j" / "n" / "5" / "4" / "k" / "h" /
                 "c" / "e" / "6" / "m" / "u" / "a" / "7" / "l"

3. Identifier Generation

3.1 Account DIDs

An account DID is derived from an IXO blockchain account address:

did:ixo:<ixo bech32 account address>

Example:

did:ixo:ixo1pu0z60zttf5h3puk5k6v85hp7qq3yge5eagwxc

The account address is generated by client-side wallet software according to the IXO blockchain account and key derivation rules. The DID is not considered created until an IID document for the DID has been successfully registered on Impact Hub through ixo.iid.v1beta1.MsgCreateIidDocument.

Account DID creation MUST be signed by the account named in the DID and the created DID document MUST include an authentication verification method controlled by that DID. This rule binds DID creation to control of the underlying Impact Hub account.

3.2 Entity DIDs

An entity DID is generated automatically by the Impact Hub Entity module:

did:ixo:entity:<id>

Example:

did:ixo:entity:4c73552dbf8a4343016e7f7952836014

Entity DID identifiers are opaque to DID consumers. Implementations MUST NOT infer semantics from the entity identifier beyond the entity namespace segment. The current Impact Hub implementation generates the entity identifier inside ixo.entity.v1beta1.MsgCreateEntity; DID consumers only rely on the returned DID string.

Entity DID creation is controlled by the owner DID supplied in MsgCreateEntity. The transaction MUST be signed by an Impact Hub account authorized by ownerDid. The resulting IID document includes the generated entity DID and the owner DID as controllers.

3.3 CosmWasm Contract DIDs

A CosmWasm contract DID identifies an Impact Hub CosmWasm contract used by IXO applications, including claims-module contract adjudicators:

did:ixo:wasm:<ixo bech32 contract address>

Example:

did:ixo:wasm:ixo1pu0z60zttf5h3puk5k6v85hp7qq3yge5eagwxc

The identifier is generated from the contract address. A conforming resolver MUST resolve a did:ixo:wasm DID only when an authoritative DID document or contract-backed DID document mapping exists, and MUST otherwise return DID resolution metadata error: "notFound". Resolvers MUST NOT synthesize verification methods or controllers for a contract DID without an authoritative on-chain source.

4. DID Documents

The authoritative on-chain object is ixo.iid.v1beta1.IidDocument. A resolver MUST transform that object into a DID Core compatible DID document.

The resolver MUST include:

The resolver MUST serialize DID Core property names using canonical DID JSON and JSON-LD names. Where chain proto names differ from DID ecosystem naming, the resolver MUST map them to the DID-compatible JSON representation. For example, chain blockchainAccountID verification material is serialized as blockchainAccountId in resolved DID documents.

4.1 IXO Extension Terms

The IXO DID method uses the DID-specific JSON-LD context https://w3id.org/ixo/ns/did/v1 for method-specific terms in resolved DID JSON-LD documents. This context is a vocabulary expansion document only; it is not the authoritative DID method specification.

linkedClaim identifies a collection of claims, attestations, or credentials associated with the DID subject. A linked claim entry can include:

linkedEntity identifies another DID subject associated with the DID subject. A linked entity entry can include:

The DID-specific IXO context MUST provide machine-readable JSON-LD definitions for these terms before W3C DID Extensions submission. The context MUST also define any IXO-specific verification method type used by resolved documents, including CosmosAccountAddress when that type is used with blockchainAccountId verification material.

4.2 Example Account DID Document

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/ixo/ns/did/v1"
  ],
  "id": "did:ixo:ixo1pu0z60zttf5h3puk5k6v85hp7qq3yge5eagwxc",
  "controller": [
    "did:ixo:ixo1pu0z60zttf5h3puk5k6v85hp7qq3yge5eagwxc"
  ],
  "verificationMethod": [
    {
      "id": "did:ixo:ixo1pu0z60zttf5h3puk5k6v85hp7qq3yge5eagwxc#account",
      "type": "CosmosAccountAddress",
      "controller": "did:ixo:ixo1pu0z60zttf5h3puk5k6v85hp7qq3yge5eagwxc",
      "blockchainAccountId": "ixo1pu0z60zttf5h3puk5k6v85hp7qq3yge5eagwxc"
    }
  ],
  "authentication": [
    "did:ixo:ixo1pu0z60zttf5h3puk5k6v85hp7qq3yge5eagwxc#account"
  ]
}

4.3 Example Entity DID Document

{
  "@context": [
    "https://www.w3.org/ns/did/v1",
    "https://w3id.org/ixo/ns/did/v1"
  ],
  "id": "did:ixo:entity:4c73552dbf8a4343016e7f7952836014",
  "controller": [
    "did:ixo:entity:4c73552dbf8a4343016e7f7952836014",
    "did:ixo:ixo1pu0z60zttf5h3puk5k6v85hp7qq3yge5eagwxc"
  ],
  "verificationMethod": [
    {
      "id": "did:ixo:entity:4c73552dbf8a4343016e7f7952836014#owner",
      "type": "CosmosAccountAddress",
      "controller": "did:ixo:ixo1pu0z60zttf5h3puk5k6v85hp7qq3yge5eagwxc",
      "blockchainAccountId": "ixo1pu0z60zttf5h3puk5k6v85hp7qq3yge5eagwxc"
    }
  ],
  "authentication": [
    "did:ixo:entity:4c73552dbf8a4343016e7f7952836014#owner"
  ],
  "linkedClaim": [
    {
      "id": "did:ixo:entity:4c73552dbf8a4343016e7f7952836014#projectCredential",
      "type": "VerifiableCredential",
      "description": "Project credential associated with the entity",
      "serviceEndpoint": "ipfs://bafybeigdyrzt5sfp7udm7hu76woil2q3vu6x27prqtb6cwm7nq5x2m5kxu",
      "proof": "bafybeigdyrzt5sfp7udm7hu76woil2q3vu6x27prqtb6cwm7nq5x2m5kxu"
    }
  ],
  "linkedEntity": [
    {
      "id": "did:ixo:entity:32a5a11ebf1ce614a6eb8ef874898eee",
      "type": "Protocol",
      "relationship": "conformsTo",
      "service": "did:ixo:entity:4c73552dbf8a4343016e7f7952836014#protocol"
    }
  ]
}

5. DID Operations

5.1 Create

Account DIDs are created with:

ixo.iid.v1beta1.MsgCreateIidDocument

The message registers a new IID document under the supplied DID. Creation MUST fail if an IID document already exists for the DID. The message requires at least one verification method and a valid Impact Hub signer address.

Entity DIDs are created with:

ixo.entity.v1beta1.MsgCreateEntity

The Entity module creates an IID document with the generated entity DID, creates the corresponding entity record, and mints the associated entity NFT. Creation MUST fail if the generated DID already exists.

5.2 Read

Resolvers read DID documents from the IID module:

ixo.iid.v1beta1.Query/IidDocument

A canonical did:ixo read is performed directly against Impact Hub chain state through an RPC, gRPC, or gRPC-gateway endpoint exposed by any Impact Hub node that provides read access to the IID query service. The node does not need to participate in the validator or delegator set. Independent operators MAY run read-only Impact Hub nodes for resolution without participating in consensus, provided the node follows the canonical Impact Hub mainnet chain.

The gRPC-gateway REST shape for the IID query is:

GET /ixo/did/dids/{id}

The {id} path value MUST be the URL-encoded DID.

If the DID syntax is invalid, the resolver MUST return DID resolution metadata:

{
  "error": "invalidDid"
}

If the DID is syntactically valid but no IID document exists, the resolver MUST return DID resolution metadata:

{
  "error": "notFound"
}

Resolvers MUST NOT synthesize DID documents for valid but unregistered IXO accounts.

5.3 Update

IID documents are updated by the following message family:

ixo.iid.v1beta1.MsgUpdateIidDocument
ixo.iid.v1beta1.MsgAddVerification
ixo.iid.v1beta1.MsgRevokeVerification
ixo.iid.v1beta1.MsgSetVerificationRelationships
ixo.iid.v1beta1.MsgAddService
ixo.iid.v1beta1.MsgDeleteService
ixo.iid.v1beta1.MsgAddController
ixo.iid.v1beta1.MsgDeleteController
ixo.iid.v1beta1.MsgAddLinkedResource
ixo.iid.v1beta1.MsgDeleteLinkedResource
ixo.iid.v1beta1.MsgAddLinkedClaim
ixo.iid.v1beta1.MsgDeleteLinkedClaim
ixo.iid.v1beta1.MsgAddLinkedEntity
ixo.iid.v1beta1.MsgDeleteLinkedEntity
ixo.iid.v1beta1.MsgAddAccordedRight
ixo.iid.v1beta1.MsgDeleteAccordedRight
ixo.iid.v1beta1.MsgAddIidContext
ixo.iid.v1beta1.MsgDeleteIidContext

Updates MUST be authorized by an account represented by a verification method in an allowed verification relationship for the DID document. The Impact Hub implementation uses authentication relationships for IID document updates.

MsgUpdateIidDocument replaces the mutable document field set. Callers that use it MUST submit any existing field values they intend to preserve.

Entity metadata is updated by ixo.entity.v1beta1.MsgUpdateEntity. Entity ownership is transferred by ixo.entity.v1beta1.MsgTransferEntity, which updates entity control and transfers the entity NFT.

5.4 Deactivate

DIDs are deactivated with:

ixo.iid.v1beta1.MsgDeactivateIID

Deactivation sets the IID document metadata flag deactivated to true. The on-chain IID document is retained. A resolver MUST expose deactivation through DID document metadata:

{
  "deactivated": true
}

For deactivated DIDs, a resolver MAY still return the retained DID document, but relying parties MUST treat didDocumentMetadata.deactivated=true as the authoritative deactivation signal.

6. DID Resolution

A conforming resolver accepts a DID or DID URL using the did:ixo method name and returns the DID Core resolution result:

For successful resolution, didDocument.id MUST exactly match the resolved DID.

Canonical direct resolution rules:

  1. Validate DID syntax against Section 2.
  2. Select an Impact Hub mainnet RPC, gRPC, or gRPC-gateway endpoint that exposes the IID query service.
  3. Verify that the endpoint is serving the canonical Impact Hub mainnet chain ID before accepting the response as did:ixo chain state.
  4. Query the Impact Hub IID module by the exact DID string.
  5. Return notFound if no document exists.
  6. Convert the IidDocument proto object into DID Core JSON or JSON-LD.
  7. Move document metadata into didDocumentMetadata, including:
    • versionId
    • created
    • updated
    • deactivated
  8. Move IXO method-specific resolution evidence into a method metadata object, including:
    • chainId
    • blockHeight
    • resolver mode, such as direct or verifiedDirect
    • RPC, gRPC, gRPC-gateway, or indexer source identifier when disclosed
  9. Include retrieval time in didResolutionMetadata when available.
  10. Preserve DID Core document fields and IXO extension fields when present.
  11. Dereference DID URL fragments against the resolved DID document.

Resolvers SHOULD support:

If a requested representation is not supported, the resolver MUST return DID resolution metadata error: "representationNotSupported".

Resolvers MAY support the W3C noCache resolution option. A resolver that accepts noCache=true MUST bypass local resolver caches and indexed intermediaries and retrieve fresh chain state from the canonical VDR, or return DID resolution metadata error: "featureNotSupported" or the equivalent W3C FEATURE_NOT_SUPPORTED error object if it cannot perform an uncached read.

6.1 Direct and Verified Direct Resolution

Direct resolution is the canonical did:ixo resolution architecture. A direct resolver obtains the DID document by querying Impact Hub IID state over RPC, gRPC, or gRPC-gateway through any read-access node following the canonical Impact Hub mainnet chain.

A direct resolver that trusts only the node endpoint is an unverifiable direct resolver. It is useful for ordinary application reads, but it inherits trust in the selected endpoint for the returned state.

A verified direct resolver is the trustless high-assurance profile for did:ixo resolution. It can query any read-access node, but it does not trust the node operator for correctness. Instead, it verifies the endpoint chain ID and verifies the queried state against Impact Hub consensus, for example with Tendermint or CometBFT light-client verification and state proofs where supported by the queried interface. Resolvers that claim a trustless or verified profile MUST expose enough metadata for relying parties to audit the source of the result, including chain ID, block height, retrieval time, and whether light-client or equivalent verification was applied.

6.2 Intermediated and Indexed Resolution

Convenience services MAY provide intermediated did:ixo resolution by reading from an indexed copy of Impact Hub state rather than querying a chain node for each request. The IXO Blocksync service is one such centrally hosted intermediary. Blocksync-style services are not the canonical authority for the method; they are resolver infrastructure that synchronizes from the canonical VDR.

Intermediated resolvers MUST make their mode clear in resolver documentation and SHOULD include resolver metadata such as intermediary, sourceChainId, sourceBlockHeight, indexedAt, and syncStatus when returning DID resolution results. An intermediated resolver MUST NOT claim stronger freshness or authenticity than its indexer synchronization and verification process supports.

IXO Blocksync-compatible infrastructure MAY be independently hosted. An independent Blocksync deployment MUST sync from Impact Hub chain state and MUST preserve the canonical DID document transformation rules in this specification. If the indexed service is stale, unavailable, or unable to prove that it has processed the relevant block height, clients that require canonical freshness SHOULD use direct or verified direct resolution.

6.3 DID URL Dereferencing

Resolvers that support DID URL dereferencing MUST resolve the base did:ixo DID before dereferencing fragments, services, or relative references. Duplicate DID URL query parameters MUST be treated as invalid inputs. DID URL query parameters used for dereferencing MUST be normalized before caching, forwarding, or combining with service endpoints.

When using relativeRef, dereferencers MUST apply URI reference resolution after percent-decoding the parameter value, reject traversal above the selected service endpoint base path, and return an invalid DID URL error for unsafe relative references.

7. Security Considerations

7.1 Controller Binding

Account DID creation MUST prove control of the account named in the DID. This prevents one account from registering a DID for another account address.

Entity DID creation MUST be authorized by the supplied owner DID. Entity controllers SHOULD rotate or revoke verification methods when ownership or operational control changes.

7.2 Verification Method Rotation

Verification methods can be added, revoked, or assigned to new relationships through IID module update messages. Relying parties SHOULD resolve the current DID document before verifying a signature or capability invocation.

7.3 Registry Finality

The Impact Hub blockchain provides ordered transaction execution and consensus finality according to its consensus protocol. Resolvers SHOULD document the node endpoint, chain ID, and finality assumptions they use.

The canonical VDR for did:ixo is disambiguated by the Impact Hub mainnet chain ID. Resolvers MUST NOT treat state from a fork, testnet, devnet, private deployment, or stale index as canonical did:ixo state. Testnet, devnet, and private deployments MAY expose compatible DID resolution for development, but they MUST document their non-canonical chain ID and MUST NOT be advertised as the canonical W3C DID method registry target.

7.4 Resolver Trust

A direct resolver that queries an RPC, gRPC, or REST endpoint without independent verification inherits trust in that endpoint. High-assurance deployments SHOULD use the verified direct resolver profile with light-client state verification or equivalent proof verification.

An intermediated resolver inherits trust in its indexer, synchronization process, hosting operator, and upstream chain reads. Relying parties that need fresh canonical state SHOULD prefer direct or verified direct resolution, or require the intermediary to disclose source chain ID, source block height, and sync status.

Resolvers that cache DID documents SHOULD use normalized DID URLs and resolution options as cache keys. If noCache=true is accepted, a resolver MUST bypass cached or indexed data and query canonical chain state directly, or return an explicit feature-not-supported error.

7.5 Service Endpoints

Services, linked resources, linked claims, and linked entities can reveal relationships, locations, or application metadata. DID controllers SHOULD publish only endpoint and graph information they are willing to disclose.

8. Privacy Considerations

did:ixo DIDs are public on-chain identifiers. Registration, updates, controllers, verification methods, services, linked resources, linked claims, and linked entities can be visible to observers of Impact Hub state.

Controllers SHOULD:

Entity DIDs can be associated with public entity records and NFTs. Relying parties SHOULD assume entity DID activity is correlatable unless privacy preserving application patterns are used.

Network-based resolvers, including centrally hosted Blocksync-style services, can log requester IP addresses, queried DIDs, DID URLs, resolution options, and timing. Clients that want to reduce profiling risk SHOULD resolve through infrastructure they control, use independent read-only nodes where practical, or choose an intermediary they trust operationally.

9. Implementation References

This site is open source. Improve this page.