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.

  • 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

The entity types are defined using Zod for runtime type safety.

You don't have to worry about Zod, we're using schemas here to express the data type with more clarity.

User

Represents an organizational participant with a specific role, such as root, admin, manager, or member.

const User = z.object({
  id: z.string(),
  role: UserRole 
})

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.

const UserGroup = z.object({
  id: z.string()
})

const UserGroupMember = z.object({
  userId: z.string(),
  groupId: z.string()
})

User Account

User Account

Links users to their respective accounts, which are associated with specific rules and permissions.

Links users to their respective accounts, which are associated with specific rules and permissions.

const UserAccount = z.object({
  userId: z.string(),
  accountId: z.string()
})
const UserAccount = z.object({
  userId: z.string(),
  accountId: z.string()
})

Credential

Stores users credentials used for strong authentication – anything a user can use to sign a message.

const Credential = z.object({
  id: z.string(),
  userId: z.string(),
  key: PublicKey
})

PublicKey is defined according to the Json Web Key standard.

Account

Account

Tracks the organization's existing accounts.

Tracks the organization's existing accounts.

const Account = z.object({
  id: z.string(),
  address: Address,
  accountType: AccountType,
  chainId: z.number().optional()
})
const Account = z.object({
  id: z.string(),
  address: Address,
  accountType: AccountType,
  chainId: z.number().optional()
})

Account Group

Account Group

A logical grouping of accounts within the organization, which can be associated with specific rules and permissions.

A logical grouping of accounts within the organization, which can be associated with specific rules and permissions.

const AccountGroup = z.object({
  accountId: z.string(),
  groupId: z.string()
})

const AccountGroupMember = z.object({
  accountId: z.string(),
  groupId: z.string()
})
const AccountGroup = z.object({
  accountId: z.string(),
  groupId: z.string()
})

const AccountGroupMember = z.object({
  accountId: z.string(),
  groupId: z.string()
})

Token

Stores tokens which can be used to build granular transaction permissions.

const Token = z.object({
  id: AssetId,
  address: Address,
  symbol: z.string().nullable(),
  chainId: z.number(),
  decimals: z.number()
})

AssetId conforms to the CAIP-19 standard.

Address Book

Maintains a list of significant accounts and their details categorized by their function within or outside the organization.

const AddressBookEntry = z.object({
  id: AccountId,
  address: Address,
  chainId: z.number(),
  classification: AccountClassification 
})

AccountId follows the CAIP-10 standard.

Cross-Cutting Types

const UserRole = z.nativeEnum({
  ROOT: 'root',
  ADMIN: 'admin',
  MEMBER: 'member',
  MANAGER: 'manager'
} as const)

const AccountClassification = z.nativeEnum({
  EXTERNAL: 'external',
  COUNTERPARTY: 'counterparty',
  INTERNAL: 'internal',
  MANAGED: 'managed'
} as const)

const AccountType = z.nativeEnum({
  EOA: 'eoa',
  AA: '4337'
} as const)
const UserRole = z.nativeEnum({
  ROOT: 'root',
  ADMIN: 'admin',
  MEMBER: 'member',
  MANAGER: 'manager'
} as const)

const AccountClassification = z.nativeEnum({
  EXTERNAL: 'external',
  COUNTERPARTY: 'counterparty',
  INTERNAL: 'internal'
} as const)

const AccountType = z.nativeEnum({
  EOA: 'eoa',
  AA: '4337'
} as const)

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

const Entities = z.object({
  addressBook: z.array(AddressBookEntry),
  credentials: z.array(Credential),
  tokens: z.array(Token),
  userGroupMembers: z.array(UserGroupMember),
  userGroups: z.array(UserGroup),
  userAccounts: z.array(UserAccount),
  users: z.array(User),
  accountGroupMembers: z.array(AccountGroupMember),
  accountGroups: z.array(AccountGroup),
  accounts: z.array(Account)
})
const Entities = z.object({
  addressBook: z.array(AddressBookEntry),
  credentials: z.array(Credential),
  tokens: z.array(Token),
  userGroupMembers: z.array(UserGroupMember),
  userGroups: z.array(UserGroup),
  userAccounts: z.array(UserAccount),
  users: z.array(User),
  accountGroupMembers: z.array(AccountGroupMember),
  accountGroups: z.array(AccountGroup),
  accounts: z.array(Account)
})

Last updated