# Overview

*Ripple Custody* exposes a complete set of APIs to administer and operate the system programmatically. The below entities are at the core of the system:
- **intents** represent requests to execute an action within the system that may eventually be executed if fully approved;
- **domains** define segregated sets of entities (e.g., users, policies and accounts) with guaranteed isolation from each other;
- **users** are human or technical consumers of the service;
- **policies** are operational rules defining the required (multi-)approval workflow for the execution of particular intents;
- **vaults** are logical key stores responsible for the building and signing of outgoing transactions;
- **accounts** are particular sets of addresses within a vault for which balance(s) and transactions are tracked;
- **transaction orders** are orders to transfer digital assets or request an operation on the ledger;
- **transactions** are incoming or outgoing ledger transactions that have been detected on the ledger or shall be broadcast;
- **transfers** are the financial representation of their corresponding **transactions**;
- **endpoints** associate ledger addresses with human-readable aliases to keep track of whitelisted and blacklisted addresses;
- **ledgers** are accounting systems that are supported and tracked;
- **tickers** define the detected currencies and their respective symbols and parameters;
- **events** are the notification payloads generated through user actions, system signals, and ledger updates.
- **requests** allow to follow the progress of a user request and identify a possible failure.

Because the security of digital assets is paramount, *Harmonize* leverages multiple security protocols ensuring a proper management of the keys, of the signature process, of user authentication, of the application of governance policies and overall of data integrity system-wide. Notably, 
- every request to mutate the system, as modelled through an **intent**, must be signed by all parties involved, such that an end-to-end secure link is set between the API consumer and the core of *Harmonize*;
- every request to mutate the system is subject to programmable **policies** that regulate the exact quorum of users being authorized to approve and execute the **intent**;
- every critical entity is protected by a data integrity protocol. Entities are versioned and stored as part of a Merkle tree whose root is signed for any mutation of the data. Any data tampering attempt at the database level or in transit is identified and fails at runtime. All such protected entites are wrapped into a `data` envelope and augmented with a `signature` field at the API level to allow a validation of the data integrity from the outside the system. This is particularly relevant to validate, for instance, the integrity of deposit addresses of a given account.

Most entity types rely on a common pattern exposing the following fields:
 - `id`: a user-defined unique identifier (UUID); once defined, an id cannot be modified
 - `metadata.revision`: a system-enforced revision number set to 1 for the creation of the entity, and incremented at every entity update
 - `metadata.description`: an optional user-defined description of the entity
 - `metadata.createdAt`: a system-enforced timestamp marking the creation time of the entity
 - `metadata.createdBy`: a system-enforced reference to the creator of the entity
 - `metadata.lastModifiedAt`: a system-enforced timestamp marking the last update time of the entity
 - `metadata.lastModifiedBy`: a system-enforced reference to the last updater of the entity
 - `metadata.customProperties`: a user-defined key-value store to attach arbitrary data to the entity, such as a correlation identifier; customProperties are part of the evaluation context of policies conditions and may be used to trigger particular approval workflows

Together, `id` and `metadata.revision` are the basis of the anti-replay model in *Harmonize*.

Most entities also expose a `lock` flag to make the entity read-only and prevent its use during runtime:
- `lock`: lock status of an entity, which may be `Locked` or `Unlocked`; an `Unlocked` entity inherits the lock of its hierarchical parent and a `Locked` entity (with its dependent entities) may not be used at runtime.

Locking a **domain** will lock all its inner entities as well as subdomains; locking a **user** will prevent it from submitting any request to the system or to access the service; locking a **policy** will ignore it entirely in the context of the policy selection; locking a **vault** will lock all its related **accounts**; locking an **account** will prevent the execution of transactional operations; locking an **endpoint** will prevent its use as a transaction order destination.

For requests returning a list of entities, pagination is enabled by default. The request may include a `limit` parameter to properly quantify the size of the response, a `startingAfter` parameter to define the anchor point, `sortBy` to define a possible sorting property, `sortOrder` to specify the direction of the sorting (resp. "ASC", "DESC") and possibly filtering criterions that may be entity-specific.

Responses are packaged within a list of `items` and a pointer to the next page is exposed as property `nextStartingAfter`.