Entities
In the context of the Armory Policy Engine, entities represent the various individuals, systems, or components that interact with or are governed by policy rules. These entities form the basis of modeling organizational structures commonly found in web3 ecosystems.
On this page, you will learn about the various entity types available and how to effectively utilize them.
Common Base Entities
Users: Individual participants within the organization.
User Groups: Collections of users organized by common attributes or purposes.
User Accounts: Accounts assigned to users.
Credentials: Public keys in JWK format used to authenticate users.
Accounts: Digital accounts used for managing blockchain transactions.
Account Groups: Groups categorized by account types or usage.
Tokens: Digital assets managed within the organization.
Address Book: A directory of important addresses and their classifications.
What Entities Are Not
Entities do not serve as the primary source of truth about the structure of your organization. Instead, they provide a structured representation of the organizational layout within the policy engine.
Types
In the following sections, we will define the JSON schema and document for Entities elements. At every step, we have a schema that explains how entities work.
You can go to a validator playground and paste in schema and document at any step to try it out, or check the full definition right away.
Cross-Cutting Enums
{
"$id": "UserRole",
"type": "string",
"enum": ["root", "admin", "member", "manager"]
}
{
"$id": "AccountClassification",
"type": "string",
"enum": ["external", "counterparty", "internal", "managed"]
}
{
"$id": "AccountType",
"type": "string",
"enum": ["eoa"]
}User
Represents an organizational participant with a specific role, such as root, admin, manager, or member.
schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "entities",
"type": "object",
"properties": {
"users": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the user"
},
"role": {
"type": "string",
"enum": ["root", "admin", "member", "manager"],
"description": "Role of the user within the organization"
}
},
"required": ["id", "role"],
"additionalProperties": false
}
}
},
"required": ["users"],
"additionalProperties": false
}example
{
"users": [
{
"id": "alice-user-id",
"role": "admin"
},
{
"id": "bob-user-id",
"role": "member"
}
]
}Roles are flexible and are defined according to the organization's specific hierarchy and access management policies.
User Group
A logical grouping of users within the organization, which can be associated with specific rules and permissions.
schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "Entities",
"type": "object",
"properties": {
"users": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"role": {
"type": "string",
"enum": ["root", "admin", "member", "manager"]
}
},
"required": ["id", "role"],
"additionalProperties": false
}
},
"userGroups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" }
},
"required": ["id"],
"additionalProperties": false
}
},
"userGroupMembers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"userId": { "type": "string" },
"groupId": { "type": "string" }
},
"required": ["userId", "groupId"],
"additionalProperties": false
}
}
},
"required": ["users", "userGroups", "userGroupMembers"],
"additionalProperties": false
}example
{
"users": [
{
"id": "alice-user-id",
"role": "admin"
},
{
"id": "bob-user-id",
"role": "member"
}
],
"userGroups": [
{
"id": "treasury-group-id",
},
{
"id": "development-group-id",
}
],
"userGroupMembers": [
{
"userId": "alice-user-id",
"groupId": "treasury-group-id"
},
{
"userId": "bob-user-id",
"groupId": "development-group-id"
}
]
}
Credential
Stores users credentials used for strong authentication – anything a user can use to sign a message.
PublicKey schema follows the Json Web Key standard. Schema does not define it here to be easier to read
schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"User": {
"type": "object",
"properties": {
"id": { "type": "string" },
"role": { "type": "string", "enum": ["root", "admin", "member", "manager"] }
},
"required": ["id", "role"]
},
"Credential": {
"type": "object",
"properties": {
"id": { "type": "string" },
"userId": { "type": "string" },
"publicKey": {
"type": "object",
"additionalProperties": true
}
},
"required": ["id", "userId", "publicKey"]
}
},
"type": "object",
"properties": {
"users": {
"type": "array",
"items": { "$ref": "#/definitions/User" }
},
"credentials": {
"type": "array",
"items": { "$ref": "#/definitions/Credential" }
}
},
"required": ["users", "credentials"],
"additionalProperty": false
}
example
{
"users": [
{
"id": "alice-user-id",
"role": "admin"
},
{
"id": "bob-user-id",
"role": "member"
}
],
"credentials": [
{
"userId": "alice-user-uid",
"id": "alice-private-metamask",
"key": {
"kty": "EC",
"alg": "ES256K",
"kid": "0x4fca4ebdd44d54a470a273cb6c131303892cb754f0d374a860fab7936bb95d66",
"crv": "secp256k1",
"x": "zb-LwlHDtp5sV8E33k3H2TCm-LNTGIcFjODNWI4gHRZ",
"y": "6Pbt6dwxAeS7yHp7YV2GbXs_Px0tWrTfeTv9erjC7zz"
}
},
{
"userId": "bob-user-uid",
"id": "bob-private-",
"key": {
"kty": "EC",
"alg": "ES256K",
"kid": "0x7e431d5b570ba38e2e036387a596219ae9076e8a488a6149b491892b03582166",
"crv": "secp256k1",
"x": "m5zj9v8I_UvB-15y7t7RmQXmyNmPuvAQPDdU71LRkUB",
"y": "Az5R7PGJbmKdPpK2-jmUh7xyuaOZlCIFNU4I83xy5lC"
}
}
]
}Account
Tracks the organization's existing accounts.
schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "Entities",
"type": "object",
"properties": {
"accounts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"address": { "type": "string" },
"accountType": { "type": "string", "enum": ["eoa", "4337"] },
"chainId": { "type": "number" }
},
"required": ["id", "address", "accountType"],
"additionalProperties": false
}
}
},
"required": ["accounts"],
"additionalProperties": false
}example
{
"accounts": [
{
"id": "alice-account-id",
"address": "0xc0ffee254729296a45a3885639AC7E10F9d54979",
"accountType": "eoa"
},
{
"id": "bob-account-id",
"address": "0x999999cf1046e68e36E1aA2E0E07105eDDD1f08E",
"accountType": "eoa"
}
]
}
User Account
Links users to their respective accounts, which are associated with specific rules and permissions.
schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "entities",
"type": "object",
"properties": {
"users": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Unique identifier for the user"
},
"role": {
"type": "string",
"enum": [
"root",
"admin",
"member",
"manager"
],
"description": "Role of the user within the organization"
}
},
"required": [
"id",
"role"
],
"additionalProperties": false
}
},
"accounts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"address": {
"type": "string"
},
"accountType": {
"type": "string",
"enum": [
"eoa",
"4337"
]
},
"chainId": {
"type": "number"
}
},
"required": [
"id",
"address",
"accountType"
],
"additionalProperties": false
}
},
"userAccounts": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"address": {
"type": "string"
},
"accountType": {
"$ref": "AccountType"
},
"chainId": {
"type": "number"
}
},
"required": [
"id",
"address",
"accountType"
],
"additionalProperties": false
}
},
"required": [
"users",
"accounts",
"userAccounts"
],
"additionalProperties": false
}example
{
"users": [
{
"id": "alice-user-id",
"role": "admin"
},
{
"id": "bob-user-id",
"role": "member"
}
],
"accounts": [
{
"id": "treasury-account-id",
"address": "0xc0ffee254729296a45a3885639AC7E10F9d54979",
"accountType": "eoa"
},
{
"id": "dev-account-id",
"address": "0x999999cf1046e68e36E1aA2E0E07105eDDD1f08E",
"accountType": "eoa"
}
],
"userAccounts": [
{
"userId": "alice-user-id",
"accountId": "treasury-account-id"
},
{
"userId": "bob-user-id",
"accountId": "dev-account-id"
}
]
}Account Group
A logical grouping of accounts within the organization, which can be associated with specific rules and permissions.
schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "Entities",
"type": "object",
"properties": {
"accounts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"address": {
"type": "string"
},
"accountType": {
"type": "string",
"enum": [
"eoa",
"4337"
]
},
"chainId": {
"type": "number"
}
},
"required": [
"id",
"address",
"accountType"
],
"additionalProperties": false
}
},
"accountGroupMembers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"accountId": {
"type": "string"
},
"groupId": {
"type": "string"
}
},
"required": [
"accountId",
"groupId"
],
"additionalProperties": false
}
},
"accountGroups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
}
},
"required": [
"id"
],
"additionalProperties": false
}
}
},
"required": [
"accounts",
"accountGroups",
"accountGroupMembers"
],
"additionalProperties": false
}example
{
"accounts": [
{
"id": "treasury-1",
"address": "0xc0ffee254729296a45a3885639AC7E10F9d54979",
"accountType": "eoa"
},
{
"id": "treasury-2",
"address": "0xc111ee254729296a45a3885639AC7E10F9d54979",
"accountType": "eoa"
},
{
"id": "dev-test-1",
"address": "0x999999cf1046e68e36E1aA2E0E07105eDDD1f08E",
"accountType": "eoa"
}
],
"accountGroups": [
{
"id": "treasury-group-id"
},
{
"id": "development-group-id"
}
],
"accountGroupMembers": [
{
"accountId": "treasury-1",
"groupId": "treasury-group-id"
},
{
"accountId": "treasury-2",
"groupId": "treasury-group-id"
},
{
"accountId": "dev-test-1",
"groupId": "development-group-id"
}
]
}Token
Stores tokens which can be used to build granular transaction permissions.
Token 'id' property conforms to the CAIP-19 standard.
schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "Entities",
"type": "object",
"properties": {
"tokens": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"address": { "type": "string" },
"symbol": { "type": ["string", "null"] },
"chainId": { "type": "number" },
"decimals": { "type": "number" }
},
"required": ["id", "address", "chainId", "decimals"],
"additionalProperties": false
}
}
},
"required": ["tokens"],
"additionalProperties": false
}example
{
"tokens": [
{
"id": "eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7",
"address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
"symbol": "USDT",
"chainId": 1,
"decimals": 18
},
{
"id": "eip155:137/erc20:0xb33EaAd8d922B1083446DC23f610c2567fB5180f",
"address": "0xb33EaAd8d922B1083446DC23f610c2567fB5180f",
"symbol": "UNI",
"chainId": 137,
"decimals": 18
}
]
}Address Book
Maintains a list of significant accounts and their details categorized by their function within or outside the organization.
schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"accounts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"address": { "type": "string" },
"accountType": {
"type": "string",
"enum": ["eoa", "4337"]
},
"chainId": { "type": "number" }
},
"required": ["id", "address", "accountType", "chainId"],
"additionalProperties": false
}
},
"addressBook": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"address": { "type": "string" },
"chainId": { "type": "number" },
"classification": {
"type": "string",
"enum": ["external", "counterparty", "internal", "managed"]
}
},
"required": ["id", "address", "chainId", "classification"],
"additionalProperties": false
}
}
},
"required": ["accounts", "addressBook"],
"additionalProperties": false
}
example
{
"accounts": [
{
"id": "treasury-account",
"address": "0x1234567890abcdef1234567890abcdef12345678",
"accountType": "eoa",
"chainId": 1
},
],
"addressBook": [
{
"id": "main-treasury",
"address": "0x1234567890abcdef1234567890abcdef12345678",
"chainId": 1,
"classification": "managed"
},
{
"id": "external-partner",
"address": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
"chainId": 1,
"classification": "counterparty"
}
]
}Entities Type
The Entities type is a comprehensive data structure that plays a crucial role in both the core operations of the Policy Engine and the management within the Entity Store
schema
{
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"UserRole": {
"type": "string",
"enum": ["root", "admin", "member", "manager"]
},
"AccountClassification": {
"type": "string",
"enum": ["external", "counterparty", "internal", "managed"]
},
"AccountType": {
"type": "string",
"enum": ["eoa", "4337"]
}
},
"type": "object",
"properties": {
"users": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"role": { "$ref": "#/definitions/UserRole" }
},
"required": ["id", "role"],
"additionalProperties": false
}
},
"userGroups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"name": { "type": "string" }
},
"required": ["id", "name"],
"additionalProperties": false
}
},
"userGroupMembers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"userId": { "type": "string" },
"groupId": { "type": "string" }
},
"required": ["userId", "groupId"],
"additionalProperties": false
}
},
"userAccounts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"userId": { "type": "string" },
"accountId": { "type": "string" }
},
"required": ["userId", "accountId"],
"additionalProperties": false
}
},
"credentials": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"userId": { "type": "string" },
"key": {
"type": "object",
"additionalProperties": true
}
},
"required": ["id", "userId", "key"],
"additionalProperties": false
}
},
"accounts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"address": { "type": "string" },
"accountType": { "$ref": "#/definitions/AccountType" },
"chainId": { "type": "number" }
},
"required": ["id", "address", "accountType", "chainId"],
"additionalProperties": false
}
},
"accountGroupMembers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"accountId": {
"type": "string"
},
"groupId": {
"type": "string"
}
},
"required": [
"accountId",
"groupId"
],
"additionalProperties": false
}
},
"accountGroups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
}
},
"required": [
"id"
],
"additionalProperties": false
}
},
"tokens": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"address": { "type": "string" },
"symbol": { "type": ["string", "null"] },
"chainId": { "type": "number" },
"decimals": { "type": "number" }
},
"required": ["id", "address", "chainId", "decimals"],
"additionalProperties": false
}
},
"addressBook": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"address": { "type": "string" },
"chainId": { "type": "number" },
"classification": { "$ref": "#/definitions/AccountClassification" }
},
"required": ["id", "address", "chainId", "classification"],
"additionalProperties": false
}
}
},
"required": [
"users",
"userGroups",
"userGroupMembers",
"userAccounts",
"credentials",
"accounts",
"accountGroups",
"accountGroupMembers",
"tokens",
"addressBook"
],
"additionalProperties": false
}
example
{
"users": [
{
"id": "alice-user-id",
"role": "admin"
},
{
"id": "bob-user-id",
"role": "member"
}
],
"credentials": [
{
"userId": "alice-user-uid",
"id": "alice-private-metamask",
"key": {
"kty": "EC",
"alg": "ES256K",
"kid": "0x4fca4ebdd44d54a470a273cb6c131303892cb754f0d374a860fab7936bb95d66",
"crv": "secp256k1",
"x": "zb-LwlHDtp5sV8E33k3H2TCm-LNTGIcFjODNWI4gHRZ",
"y": "6Pbt6dwxAeS7yHp7YV2GbXs_Px0tWrTfeTv9erjC7zz"
}
},
{
"userId": "bob-user-uid",
"id": "bob-private-metamask",
"key": {
"kty": "EC",
"alg": "ES256K",
"kid": "0x7e431d5b570ba38e2e036387a596219ae9076e8a488a6149b491892b03582166",
"crv": "secp256k1",
"x": "m5zj9v8I_UvB-15y7t7RmQXmyNmPuvAQPDdU71LRkUB",
"y": "Az5R7PGJbmKdPpK2-jmUh7xyuaOZlCIFNU4I83xy5lC"
}
}
],
"userGroups": [
{
"id": "treasury-group-id",
"name": "Treasury"
},
{
"id": "development-group-id",
"name": "Development"
}
],
"userGroupMembers": [
{
"userId": "alice-user-id",
"groupId": "treasury-group-id"
},
{
"userId": "bob-user-id",
"groupId": "development-group-id"
}
],
"accounts": [
{
"id": "treasury-account",
"address": "0x1234567890abcdef1234567890abcdef12345678",
"accountType": "eoa",
"chainId": 1
},
{
"id": "operations-account",
"address": "0x0987654321abcdef1234567890abcdef12345678",
"accountType": "4337",
"chainId": 1
}
],
"accountGroups": [
{
"id": "treasury-group-id"
},
{
"id": "development-group-id"
}
],
"accountGroupMembers": [
{
"accountId": "treasury-account",
"groupId": "treasury-group-id"
},
{
"accountId": "operations-account",
"groupId": "development-group-id"
}
],
"userAccounts": [
{
"userId": "alice-user-id",
"accountId": "treasury-account"
},
{
"userId": "bob-user-id",
"accountId": "operations-account"
}
],
"tokens": [
{
"id": "eip155:1/erc20:0xdAC17F958D2ee523a2206206994597C13D831ec7",
"address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
"symbol": "USDT",
"chainId": 1,
"decimals": 18
},
{
"id": "eip155:137/erc20:0xb33EaAd8d922B1083446DC23f610c2567fB5180f",
"address": "0xb33EaAd8d922B1083446DC23f610c2567fB5180f",
"symbol": "UNI",
"chainId": 137,
"decimals": 18
}
],
"addressBook": [
{
"id": "main-treasury",
"address": "0x1234567890abcdef1234567890abcdef12345678",
"chainId": 1,
"classification": "managed"
},
{
"id": "external-partner",
"address": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcd",
"chainId": 1,
"classification": "counterparty"
}
]
}Last updated