Manage entities

Create the entity at the core of a domain, transfer it, set its verified flag and manage its accounts with the IXO MultiClient SDK. The code is illustrative.

An entity is the ownable NFT at the core of a domain. This guide shows the messages of the IXO Protocol's entity module that create an entity, transfer it, set its verified flag and manage its accounts, using the IXO MultiClient SDK (@ixo/impactxclient-sdk).

This page covers that one part of a domain. A domain is the whole: the entity, its DID, its on-chain record (the IID document), its controllers and owners, its Matrix space, its file store and its links to other domains. Domains: where each part is documented says which page covers each part, and Domain configuration explains the data model.

Before you start

You need:

npm install @ixo/impactxclient-sdk

Every write follows the same three steps: compose a message, sign it, broadcast it. Create the signing client once.

import { ixo, createSigningClient } from "@ixo/impactxclient-sdk";

const signingClient = await createSigningClient(RPC_ENDPOINT, offlineSigner);

Create an entity

The message names the owner's address, the entity type and, as context, the protocol that defines the entity's class. Its other fields set the first contents of the domain's on-chain record: verification methods, controllers, services, linked resources, accorded rights, linked entities and linked claims.

const message = {
  typeUrl: "/ixo.entity.v1beta1.MsgCreateEntity",
  value: ixo.entity.v1beta1.MsgCreateEntity.fromPartial({
    ownerAddress: signerAddress,
    entityType: "asset",
    context: [
      ixo.iid.v1beta1.Context.fromPartial({
        key: "class",
        val: "did:ixo:entity:protocol123",
      }),
    ],
    verification: [],
    controller: [],
    service: [],
    linkedResource: [],
    accordedRight: [],
    linkedEntity: [],
    linkedClaim: [],
  }),
};

const response = await signingClient.signAndBroadcast(signerAddress, [message], "auto");

The chain returns a transaction whose events include the new entity DID.

Transfer entity ownership

MsgTransferEntity reassigns the entity NFT to a new controller account.

const transferMsg = {
  typeUrl: "/ixo.entity.v1beta1.MsgTransferEntity",
  value: ixo.entity.v1beta1.MsgTransferEntity.fromPartial({
    id: entityDid,
    ownerAddress: currentOwnerAddress,
    recipientDid: "did:ixo:recipient123",
  }),
};

await signingClient.signAndBroadcast(currentOwnerAddress, [transferMsg], "auto");

Update verification status

A verifying authority (an oracle, a registry or a DAO controller) calls MsgUpdateEntityVerified to set the verified flag for one or more entities it is permitted to attest.

const verifyMsg = {
  typeUrl: "/ixo.entity.v1beta1.MsgUpdateEntityVerified",
  value: ixo.entity.v1beta1.MsgUpdateEntityVerified.fromPartial({
    id: entityDid,
    relayerNode: relayerDid,
    entityVerified: true,
  }),
};

await signingClient.signAndBroadcast(signerAddress, [verifyMsg], "auto");

Manage entity accounts

An entity can hold named sub-accounts, for example treasury, payouts and operations. Each can transact on behalf of the entity under explicit authz grants. The three messages below create an account, grant another address authority over it, and revoke that authority.

const createAccountMsg = {
  typeUrl: "/ixo.entity.v1beta1.MsgCreateEntityAccount",
  value: ixo.entity.v1beta1.MsgCreateEntityAccount.fromPartial({
    id: entityDid,
    ownerAddress: signerAddress,
    name: "treasury",
  }),
};

const grantMsg = {
  typeUrl: "/ixo.entity.v1beta1.MsgGrantEntityAccountAuthz",
  value: ixo.entity.v1beta1.MsgGrantEntityAccountAuthz.fromPartial({
    id: entityDid,
    ownerAddress: signerAddress,
    name: "treasury",
    granteeAddress: granteeAddress,
    grant: /* cosmos.authz.v1beta1.Grant */ undefined,
  }),
};

const revokeMsg = {
  typeUrl: "/ixo.entity.v1beta1.MsgRevokeEntityAccountAuthz",
  value: ixo.entity.v1beta1.MsgRevokeEntityAccountAuthz.fromPartial({
    id: entityDid,
    ownerAddress: signerAddress,
    name: "treasury",
    granteeAddress: granteeAddress,
    msgTypeUrl: "/cosmos.bank.v1beta1.MsgSend",
  }),
};

Build the grant value with cosmos.authz.v1beta1.Grant.fromPartial({...}) and the matching authorization. See Authentication and authorization and Custom authorisations for IXO Claims.

Check the result

Query the entity through the Blocksync GraphQL API:

query GetEntity($did: String!) {
  entity(id: $did) {
    id
    type
    status
    relayerNode
    owner
    controller
    accounts {
      name
      address
    }
  }
}

You can also query the entity module directly. The gRPC gateway API lists its endpoints.

When something goes wrong

What you seeWhat to do
invalid entity typeThe entityType value must match a type the chain accepts. To confirm the types allowed on your network, inspect the module params through the gRPC gateway or query the EntityList endpoint.
unauthorizedThe signer must be a current controller, or a relayer with the right capability. Confirm that the signer address is in the entity's controller set or has an active authz grant.
account already existsAccount names are unique per entity. Pick a different name, or revoke and re-grant authz on the existing account.

Next steps