# Intents

Executive summary
**An *intent* is a cryptographically signed proposal to change the system. Every modification must go through the intent workflow before execution.**

- Intents are immutable once submitted and create a tamper-evident audit trail.
- The *maker-checker* model ensures no single person can unilaterally make changes.
- Policies determine how many approvals are required and from which roles.
- Intents can be rejected by any authorized checker, halting the change.


Why this matters
Intents are the enforcement mechanism for your governance policies. Every transfer, policy change, user creation, and configuration update flows through this system. This means you have a complete, cryptographically-secured record of every decision made on the platform — critical for regulatory audits, internal investigations, and demonstrating control over digital assets.

**For architects and operators**: Monitor intent approval queues and set appropriate expiry times. Stale intents indicate operational bottlenecks. Consider webhook integrations to notify approvers of pending intents.

## What is an intent?

An intent represents a proposed change that:

- **Is signed**: The proposer cryptographically signs the intent, proving their identity
- **Is immutable**: Once submitted, the intent content cannot be modified
- **Requires approval**: Policies determine which roles must approve before execution
- **Is auditable**: Every intent is recorded in the system's tamper-evident audit trail


Intents ensure that all changes follow your governance rules and create a complete record of who did what and when.

## Intent lifecycle

Every intent progresses through a defined set of states:


```mermaid
stateDiagram-v2
    [*] --> Proposed: User submits intent
    Proposed --> PendingApproval: Policy matched
    PendingApproval --> Approved: All approvals received
    PendingApproval --> Rejected: Approver rejects
    Approved --> Executed: System executes
    Executed --> [*]
    Rejected --> [*]
```

### Intent states

| State | Description |
|  --- | --- |
| **Proposed** | Intent has been created and signed by the proposer. The proposer's signature counts as the first approval. |
| **Pending Approval** | Intent is awaiting additional approvals as defined by the applicable policy workflow. |
| **Approved** | All required approvals have been received. The intent is ready for execution. |
| **Executed** | The change has been applied to the system. The intent is complete. |
| **Rejected** | An approver has rejected the intent, or the intent has expired. No changes are made. |
| **Expired** | The intent's expiry time has passed without sufficient approvals. Treated as rejected. |


### State transitions

| Transition | Trigger |
|  --- | --- |
| Proposed → Pending Approval | Automatic after proposal (if additional approvals needed) |
| Pending Approval → Approved | Final required approval received |
| Pending Approval → Rejected | Any authorized user rejects the intent |
| Pending Approval → Expired | Intent expiry time passes |
| Approved → Executed | System executes the change |


## Maker-checker model

Intents follow a *maker-checker* pattern that enforces segregation of duties:

### Makers

- Create and sign intents (propose changes)
- Must have a role that matches the first step of the policy workflow
- Their proposal counts as the first approval
- Cannot approve their own intent again in subsequent workflow steps


### Checkers

- Review pending intents
- Provide approvals or rejections
- Must have roles matching subsequent workflow steps
- Multiple checkers may be required based on the policy


### Example flow


```mermaid
sequenceDiagram
    participant Op as Operator (Maker)
    participant Sup as Supervisor (Checker)
    participant Comp as Compliance (Checker)
    participant Sys as System

    Op->>Sys: Propose transfer intent<br/>(1st approval)
    Sup->>Sys: Review & approve<br/>(2nd approval)
    Comp->>Sys: Review & approve<br/>(3rd approval)
    Sys->>Sys: Execute intent
```

This separation ensures no single user can both propose and fully approve a change.

## Intent types

Intents are categorized by the type of operation they perform:

| Category | Example Intent Types | Description |
|  --- | --- | --- |
| **Domain management** | `v0_CreateDomain`, `v0_LockDomain` | Create and manage organizational units |
| **User management** | `v0_CreateUser`, `v0_UpdateUser` | Manage users and their roles |
| **Asset management** | `v0_CreateAccount`, `v0_CreateVault` | Create accounts and vaults |
| **Transactions** | `v0_CreateTransferOrder`, `v0_CreateTransactionOrder` | Execute blockchain operations |
| **Policy management** | `v0_CreatePolicy`, `v0_UpdatePolicy` | Define governance rules |
| **Endpoint management** | `v0_CreateEndpoint` | Manage external addresses |


For details on intent structure, see [Intent structure reference](/products/custody/v1.34/api/reference/intent-structure).

## Intent expiry

Every intent has an expiry time. If the required approvals are not received before this time:

- The intent transitions to **Expired** state
- No changes are made to the system
- A new intent must be created if the change is still needed


Expiry times prevent stale intents from being approved long after they were proposed, when circumstances may have changed.

## Intent targeting

When creating an intent, users specify:

- **Author**: The user creating the intent (automatically set)
- **Target domain**: The domain where the change will be applied
- **Payload**: The specific change details (e.g., new user properties, transfer amount)


Users can only target:

- Their own domain
- Subdomains of their domain (if policies permit)


Users **cannot** target parent domains or sibling domains.

## Next steps

- [Governance framework](/products/custody/v1.34/overview/governance): Return to the governance overview
- [Domains](/products/custody/v1.34/concepts/governance/domains): Learn about domain hierarchy
- [Policies](/products/custody/v1.34/concepts/governance/policies): Understand how policies control intent approval
- [Users and roles](/products/custody/v1.34/concepts/governance/users-roles): Learn how users participate in governance