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"
    }
  ]
}