Policies
Policy language
This page provides an overview of how to author policies using our policy language. To begin, we’ll need to get familiar with the language’s grammar, keywords, and types.
Grammar
The grammar has been designed for flexibility and expressiveness. We currently support the following operations:
| Operation | Operators | Example | Types |
|---|---|---|---|
| logical | &&, || | “true && false” | (bool, bool) -> bool |
| comparison | ==, !=, <, >, <=, >= | “1 < 2” | (int, int) -> bool |
| comparison | ==, != | “‘a’ != ‘b’“ | (string, string) -> bool |
| comparison | in | ”1 in [1, 2, 3]“ | (T, list<T>) -> bool |
| access | x[<index>] | [1,2,3][0] | (list<T>) -> T |
| access | x[<index>] | “‘abc’[0]“ | (string) -> string |
| access | x[<start>..<end>] | [1,2,3][0..2] | (list<T>) -> (list<T>) |
| access | x[<start>..<end>] | “‘abc’[0..2]“ | (string) -> string |
| access | x.<field> | “user.tags” | (struct) -> T |
| function | x.all(item, <predicate>) | “[1,1,1].all(x, x == 1)“ | (list<T>) -> bool |
| function | x.any(item, <predicate>) | “[1,2,3].any(x, x == 1)“ | (list<T>) -> bool |
| function | x.contains(<value>) | “[1,2,3].contains(1)“ | (list<T>) -> bool |
| function | x.count() | “[1,2,3].count()“ | (list<T>) -> int |
| function | x.filter(item, <predicate>) | “[1,2,3].filter(x, x == 1)“ | (list<T>) -> (list<T>) |
Keywords
Keywords are reserved words that are dynamically interchanged for real values at evaluation time. Each field supports a different set of keywords.
Consensus
| Keyword | Type | Description |
|---|---|---|
| approvers | list<User> | The users that have approved an activity |
Condition
| Keyword | Type | Description |
|---|---|---|
| activity | Activity | The activity metadata of the request |
| eth.tx | EthereumTransaction | The parsed Ethereum transaction payload (see Appendix below) |
| solana.tx | SolanaTransaction | The parsed Solana transaction payload (see Appendix below) |
| tron.tx | TronTransaction | The parsed Tron transaction payload (see Appendix below) |
| wallet | Wallet | The target wallet used in sign requests |
| private_key | PrivateKey | The target private key used in sign requests |
Types
The language is strongly typed which makes policies easy to author and maintain.
Primitive
| Type | Example | Notes |
|---|---|---|
| bool | true | |
| int | 256 | i128 |
| string | ’a’ | only single quotes are supported |
| list<T> | [1, 2, 3] | a list of type T |
| struct | { id: ‘abc’ } | a key-value map of { field:T } (defined below) |
Struct
| Struct | Field | Type | Description |
|---|---|---|---|
| User | id | string | The identifier of the user |
| tags | list<string> | The collection of tags for the user | |
| string | The email address of the user | ||
| alias | string | The alias of the user | |
| Activity | type | string | The type of the activity (e.g. ACTIVITY_TYPE_SIGN_TRANSACTION_V2) |
| resource | string | The resource type the activity targets: USER, PRIVATE_KEY, POLICY, WALLET, ORGANIZATION, INVITATION, CREDENTIAL, CONFIG, RECOVERY, AUTH, OTP, PAYMENT_METHOD, SUBSCRIPTION | |
| action | string | The action of the activity: CREATE, UPDATE, DELETE, SIGN, EXPORT, IMPORT | |
| Wallet | id | string | The identifier of the wallet |
| imported | bool | Boolean indicating whether or not this wallet has been imported | |
| exported | bool | Boolean indicating whether or not this wallet has been exported | |
| label | string | The label of this wallet | |
| Wallet Account | address | string | The wallet account address |
| PrivateKey | id | string | The identifier of the private key |
| tags | list<string> | The collection of tags for the private key | |
| imported | bool | Boolean indicating whether or not this private key has been imported | |
| exported | bool | Boolean indicating whether or not this private key has been exported | |
| label | string | The label of this private key | |
| EthereumTransaction | from | string | The sender address of the transaction |
| to | string | The receiver address of the transaction (can be an EOA or smart contract) | |
| data | string | The arbitrary calldata of the transaction (hex-encoded) | |
| value | int | The amount being sent (in wei) | |
| gas | int | The maximum allowed gas for the transaction | |
| gas_price | int | The price of gas for the transaction (Note: this field was used in legacy transactions and was replaced with max_fee_per_gas in EIP 1559 transactions, however when evaluating policies on EIP 1559 transactions, this field will be populated with the same value as max_fee_per_gas) | |
| chain_id | int | The chain identifier for the transaction | |
| nonce | int | The nonce for the transaction | |
| max_fee_per_gas | int | EIP 1559 field specifying the max amount to pay per unit of gas for the transaction (Note: This is the sum of the gas for the transaction and the priority fee described below) | |
| max_priority_fee_per_gas | int | EIP 1559 field specifying the max amount of the tip to be paid to miners for the transaction | |
| max_fee_per_blob_gas | int | EIP 4844 field specifying the maximum fee users are willing to pay per unit of blob gas, akin to the tip in EIP 1559 | |
| type | string | The EVM transaction type. This should be one of the following: “LEGACY”, “TYPE_1” (EIP 2930), “TYPE_2” (EIP 1559), “TYPE_3” (EIP 4844), “TYPE_4” (EIP 7702) | |
| SolanaTransaction | account_keys | list<string> | The accounts (public keys) involved in the transaction |
| program_keys | list<string> | The programs (public keys) involved in the transaction | |
| instructions | list<Instruction> | A list of Instructions (see below) | |
| transfers | list<Transfer> | A list of Transfers (see below) | |
| recent_blockhash | string | The recent blockhash specified in a transaction | |
| spl_transfers | list<SPLTransfer> | A list of SPLTransfers (see below) | |
| address_table_lookups | list<AddressTableLookup> | A list of AddressTableLookups (see below) | |
| TronTransaction | ref_block_bytes | string | The height of the transaction reference block |
| ref_block_hash | string | The hash of the transaction reference block | |
| expiration | int | Transaction expiration time in milliseconds | |
| timestamp | int | Transaction timestamp in milliseconds | |
| data | string | Transaction memo (not the call data!) | |
| fee_limit | int | The maximum energy cost allowed for the execution of smart contract transactions | |
| contract | list<TronContract> | A list of TronContract. This is the main content of a Tron transaction. This determines the type of transaction being executed and its parameters (see below) |
Nested Structs
| Struct | Field | Type | Description |
|---|---|---|---|
| Instruction | program_key | string | The program (public key) involved in the instruction |
| accounts | list<Account> | A list of Accounts involved in the instruction | |
| instruction_data_hex | string | Raw hex bytes corresponding to instruction data | |
| address_table_lookups | list<AddressTableLookup> | A list of AddressTableLookups used in the instruction. Learn more here | |
| Transfer | from | string | A Solana account (public key) representing the sender of the transfer |
| to | string | A Solana account (public key) representing the recipient of the transfer | |
| amount | int | The native SOL amount for the transfer (lamports) | |
| SPLTransfer | from | string | A Solana account (public key) representing the token account that is sending tokens in this SPL transfer |
| to | string | A Solana account (public key) representing the token account that is receiving tokens in this SPL transfer | |
| amount | int | The amount (noted in raw atomic units) of this SPL transfer | |
| owner | string | A Solana account (public key) representing the owner of the sending token account for this SPL transfer | |
| signers | list<string> | A list of Solana accounts (public keys) representing the multisig signers (if they exist) for this SPL transfer | |
| token_mint | string | A Solana account (public key) representing the token mint of the token being transferred in this SPL transfer | |
| Account | account_key | string | A Solana account (public key) |
| signer | boolean | An indicator of whether or not the account is a signer | |
| writable | boolean | An indicator of whether or not the account can perform a write operation | |
| AddressTableLookup | address_table_key | string | A Solana address (public key) corresponding to the address table |
| writable_indexes | list<int> | Indexes corresponding to accounts that can perform writes | |
| readonly_indexes | list<int> | Indexes corresponding to accounts that can only perform reads | |
| TronContract | type | string | The contract type, a complete list can be found in the Tron Protocol Documentation |
| permission_id | int | The transaction permission type | |
| owner_address | string | The address of the caller of the transaction | |
| to_address | string | The address of the recipient (Only available for TransferContract’s) | |
| amount | int | The amount of TRX to send (Only available for TransferContract’s) | |
| contract_address | string | The address of the contract being called (Only available for TriggerSmartContract’s) | |
| call_value | int | The amount of TRX passed to the contract (Only available for TriggerSmartContract’s) | |
| data | string | The function selector, and the functions parameters of the contract (Only available for TriggerSmartContract’s) | |
| call_token_value | int | The amount of a TRC-10 token passed to the contract (Only available for TriggerSmartContract’s) | |
| token_id | int | The TRC-10 token id (Only available for TriggerSmartContract’s) | |
| resource | string | The resource to delegate/undelegate will be “ENERGY” or “BANDWIDTH” (Only available for Delegate, UnDelegate, FreezeBalanceV2, UnfreezeBalanceV2 contract’s) | |
| balance | int | The amount of sun (1,000,000 sun = 1 TRX) staked for resources to be delegated (Only available for DelegateContract and UnDelegateContract) | |
| receiver_address | string | The resource receiver address (Only available for DelegateContract and UnDelegateContract) | |
| lock | bool | Indicates if the delegated resources are locked or not. If true resources cannot be undelegated within the lock_period (Only available for DelegateContract’s) | |
| lock_period | int | The time, in blocks, of how long the delegation is locked, only valid when lock is true (Only available for DelegateContract’s) | |
| frozen_balance | int | The amount of sun (1,000,000 sun = 1 TRX) to be frozen (Only available for FreezeBalanceV2Contract’s) | |
| unfreeze_balance | int | The amount of sun (1,000,000 sun = 1 TRX) to unfreeze (Only available for UnfreezeBalanceV2Contract’s) | |
| owner | TronPermission | The owner permission of the account (Only available for AccountPermissionUpdateContract’s) | |
| witness | TronPermission | The witness permission of the account (Only available for AccountPermissionUpdateContract’s) | |
| actives | list<TronPermission> | A list of active permissions for the account (Only available for AccountPermissionUpdateContract’s) | |
| TronPermission | type | string | The permission type either “Owner”, “Witness”, or “Active” |
| id | int | The permission id Owner = 0, Witness = 1, Active = 2+n where n is the 0 indexed active permission number | |
| permission_name | string | The name of the permission | |
| threshold | int | The operation is allowed only when the sum of the weights of the participating signatures exceeds the domain value. Requires a maximum value less than the Long type (int64). | |
| parent_id | int | The parent id, currently always 0 | |
| operations | String | Hex encoded 32 bytes (256 bits), each bit represents the authority of a contract, a 1 means the authority to own the contract | |
| keys | TronKey | A list of address’s and weight’s that jointly own the permission can be up to 5 keys. | |
| TronKey | address | string | The address authorized for a specific TronPermission |
| weight | int | The weight of this address’s signature for this permission, used to reach “threshold” in a TronPermission |
Activity Breakdown
| Resource Type | Action | Activity Type |
|---|---|---|
| ORGANIZATION | CREATE | ACTIVITY_TYPE_CREATE_SUB_ORGANIZATION_V7 |
| DELETE | ACTIVITY_TYPE_DELETE_ORGANIZATION | |
| DELETE | ACTIVITY_TYPE_DELETE_SUB_ORGANIZATION | |
| INVITATION | CREATE | ACTIVITY_TYPE_CREATE_INVITATIONS |
| DELETE | ACTIVITY_TYPE_DELETE_INVITATION | |
| POLICY | CREATE | ACTIVITY_TYPE_CREATE_POLICY_V3 |
| CREATE | ACTIVITY_TYPE_CREATE_POLICIES | |
| UPDATE | ACTIVITY_TYPE_UPDATE_POLICY_V2 | |
| DELETE | ACTIVITY_TYPE_DELETE_POLICY | |
| WALLET | CREATE | ACTIVITY_TYPE_CREATE_WALLET |
| CREATE | ACTIVITY_TYPE_CREATE_WALLET_ACCOUNTS | |
| EXPORT | ACTIVITY_TYPE_EXPORT_WALLET | |
| EXPORT | ACTIVITY_TYPE_EXPORT_WALLET_ACCOUNT | |
| IMPORT | ACTIVITY_TYPE_INIT_IMPORT_WALLET | |
| IMPORT | ACTIVITY_TYPE_IMPORT_WALLET | |
| DELETE | ACTIVITY_TYPE_DELETE_WALLETS | |
| UPDATE | ACTIVITY_TYPE_UPDATE_WALLET | |
| PRIVATE_KEY | CREATE | ACTIVITY_TYPE_CREATE_PRIVATE_KEYS_V2 |
| CREATE | ACTIVITY_TYPE_CREATE_PRIVATE_KEY_TAG | |
| UPDATE | ACTIVITY_TYPE_UPDATE_PRIVATE_KEY_TAG | |
| DELETE | ACTIVITY_TYPE_DISABLE_PRIVATE_KEY | |
| DELETE | ACTIVITY_TYPE_DELETE_PRIVATE_KEY_TAGS | |
| DELETE | ACTIVITY_TYPE_DELETE_PRIVATE_KEYS | |
| EXPORT | ACTIVITY_TYPE_EXPORT_PRIVATE_KEY | |
| IMPORT | ACTIVITY_TYPE_INIT_IMPORT_PRIVATE_KEY | |
| IMPORT | ACTIVITY_TYPE_IMPORT_PRIVATE_KEY | |
| SIGN | ACTIVITY_TYPE_SIGN_RAW_PAYLOAD_V2 | |
| SIGN | ACTIVITY_TYPE_SIGN_RAW_PAYLOADS | |
| SIGN | ACTIVITY_TYPE_SIGN_TRANSACTION_V2 | |
| USER | CREATE | ACTIVITY_TYPE_CREATE_USERS_V2 |
| CREATE | ACTIVITY_TYPE_CREATE_USER_TAG | |
| CREATE | ACTIVITY_TYPE_CREATE_API_ONLY_USERS | |
| UPDATE | ACTIVITY_TYPE_UPDATE_USER | |
| UPDATE | ACTIVITY_TYPE_UPDATE_USER_TAG | |
| DELETE | ACTIVITY_TYPE_DELETE_USERS | |
| DELETE | ACTIVITY_TYPE_DELETE_USER_TAGS | |
| CREDENTIAL | CREATE | ACTIVITY_TYPE_CREATE_API_KEYS_V2 |
| CREATE | ACTIVITY_TYPE_CREATE_AUTHENTICATORS_V2 | |
| DELETE | ACTIVITY_TYPE_DELETE_API_KEYS | |
| DELETE | ACTIVITY_TYPE_DELETE_AUTHENTICATORS | |
| CREATE | ACTIVITY_TYPE_CREATE_OAUTH_PROVIDERS | |
| DELETE | ACTIVITY_TYPE_DELETE_OAUTH_PROVIDERS | |
| PAYMENT_METHOD | UPDATE | ACTIVITY_TYPE_SET_PAYMENT_METHOD_V2 |
| DELETE | ACTIVITY_TYPE_DELETE_PAYMENT_METHOD | |
| SUBSCRIPTION | CREATE | ACTIVITY_TYPE_ACTIVATE_BILLING_TIER |
| CONFIG | UPDATE | ACTIVITY_TYPE_UPDATE_ALLOWED_ORIGINS |
| RECOVERY | CREATE | ACTIVITY_TYPE_INIT_USER_EMAIL_RECOVERY |
| AUTH | CREATE | ACTIVITY_TYPE_EMAIL_AUTH_V2 |
| CREATE | ACTIVITY_TYPE_INIT_OTP_AUTH | |
| CREATE | ACTIVITY_TYPE_OTP_AUTH | |
| CREATE | ACTIVITY_TYPE_OAUTH | |
| CREATE | ACTIVITY_TYPE_CREATE_READ_WRITE_SESSION_V2 | |
| OTP | CREATE | ACTIVITY_TYPE_INIT_OTP |
| VERIFY | ACTIVITY_TYPE_VERIFY_OTP |
Appendix
Root quorum activities
There are a select few activities that are not governed by policies, but rather by an organization’s root quorum. These activities are: ACTIVITY\_TYPE\_UPDATE\_ROOT\_QUORUM, ACTIVITY\_TYPE\_SET\_ORGANIZATION\_FEATURE, ACTIVITY\_TYPE\_REMOVE\_ORGANIZATION\_FEATURE. For example, if a policy is added that allows a specific non-root user to perform ACTIVITY\_TYPE\_SET\_ORGANIZATION\_FEATURE activities, these requests will still fail as they are subject specifically to root quorum.
Ethereum
Our Ethereum policy language (accessible via eth.tx) allows for the granular governance of signing Ethereum (EVM-compatible) transactions. Our policy engine exposes a fairly standard set of properties belonging to a transaction.
See the Ethereum policy examples for sample scenarios.
Solana
Similarly, our Solana policy language (accessible via solana.tx) allows for control over signing Solana transactions. Note that there are some fundamental differences between the architecture of the two types of transactions, hence the resulting differences in policy structure. Notably, within our policy engine, a Solana transaction contains a list of Transfers, currently corresponding to native SOL transfers. Each transfer within a transaction is considered a separate entity. Here are some approaches you might take to govern native SOL transfers:
- All transfers need to match the policy condition. Useful for allowlists (example)
- Just one transfer needs to match the policy condition. Useful for blocklists (example)
- Only match if there is a single transfer in the transaction, and that transfer meets the criteria (example). This is the most secure approach, and thus most restrictive.
See the Solana policy examples for sample scenarios.
Tron
Our Tron policy language (accessible via tron.tx) allows for policy control over signing Tron transactions. Our policy language supports the standard fields in a Tron transaction: https://developers.tron.network/docs/tron-protocol-transaction. To reference a Contract within a Transaction you should use tron.tx.contract[0].field_name in your policy where field_name is some field of the contract used in your transaction. While Tron only currently supports 1 contract per transaction this could change in the future, and were ready for it if it does! The policy engine currently supports the following Tron contract types:
- TransferContract (TRX transfers)
- TriggerSmartContract (Smart contract, including, but not limited to TRC-20, invocations)
See the Tron policy examples for sample scenarios.