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.
Illustrative example. The snippets on this page show how each message is built. They are not a tested project you can run as written. You supply the signer and every identifier, and the package version is not pinned to a tested release. Build against a test network, never against mainnet.
Before you start
You need:
- A funded IXO account on the network you target. See Networks and endpoints.
- An offline signer: Cosmos-kit, Keplr, or
getOfflineSignerfromcosmjs-utils. See Creating signers in the SDK README. - The
@ixo/impactxclient-sdkpackage, installed.
npm install @ixo/impactxclient-sdkEvery 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.
Field names mirror the x/entity proto definitions. entity.proto has the authoritative field list and any changes between versions.
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 see | What to do |
|---|---|
| invalid entity type | The 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. |
| unauthorized | The 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 exists | Account names are unique per entity. Pick a different name, or revoke and re-grant authz on the existing account. |
Next steps
Change controllers, services, linked resources and accorded rights.
Design privacy for a domain's dataDecide what to keep on the protocol and what to keep in IXO Matrix.
IXO MultiClient SDKThe SDK reference and its list of modules.
Entity proto definitionsThe authoritative message shapes.
(opens in a new tab)