> For the complete documentation index, see [llms.txt](https://docs.xyb.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xyb.co/xyb-platform-1/xyb-ledger/getting-started/ledger-service-configuration.md).

# Ledger Service Configuration

Ledger service configuration lets administrators define the behavior, constraints, and validations applied to transactions and wallets at the service level. These settings are not specific to any individual product, they act as global enforcement rules applied uniformly across every product built on this ledger service instance.

The rules are modular. Each one can be toggled on or off independently, and where the rule supports it, its parameters can be customized before the configuration is saved.

### Accessing the Ledger Service Configuration

1. Log in to Console.
2. Navigate to **Product configuration → Services**.
3. Select the ledger service (`cac-ledger-svc`), then the version you want to review or edit.

This opens a structured view of rule groups, each representing a different class of logic applied to transactions, wallets, or balances. As with other configuration surfaces on the platform, changes are made against a version — review the version's status before editing, since an active version may already be in effect for every product using this service.

### Understanding Rulebooks

Each rule is defined by a small, consistent set of fields:

<table><thead><tr><th width="255.6640625">Field</th><th>Description</th></tr></thead><tbody><tr><td>Rulebook name</td><td>The rulebook the rule belongs to. Every predefined rule observed uses <code>BUILT-IN</code>.</td></tr><tr><td>Trigger</td><td>The event that activates the rule — typically <code>Instruction</code>, or <code>Wallet created</code> for rules that fire at wallet-creation time rather than on a transaction.</td></tr><tr><td>Script language</td><td>The underlying implementation: <code>INTRINSIC</code> (platform-native logic) or <code>JS</code> (JavaScript-based, used for more advanced rules).</td></tr><tr><td>Script source</td><td>An internal, encoded reference to the rule's actual implementation. Not human-readable and not intended to be edited directly.</td></tr><tr><td>Enabled</td><td>Whether the rule is currently active.</td></tr><tr><td>Parameters</td><td>Editable fields that fine-tune the rule's behavior, where the rule supports them.</td></tr></tbody></table>

Rulebooks themselves are not edited directly from this interface — a rule's logic is fixed; what's configurable per rule is whether it's enabled and, where applicable, its parameters.

### Categories of Rules

The configuration interface organizes rules into logical groups, each addressing a different operational or compliance objective.

#### Wallet Balance Limit Rules

Constraints on how much value a wallet or account can hold, or must maintain.

| Rule                                    | What it does                                                                                                      | Parameter                                                  |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| Minimum wallet balance limit            | Prevents a wallet's available balance from falling negative                                                       | —                                                          |
| Maximum wallet balance limit            | Prevents a wallet's available balance from exceeding a specified value                                            | Balance limit                                              |
| Minimum wallet balance limit (advanced) | Same purpose as the basic version, with additional logic covering movement states, wallet types, and fee handling | Minimum threshold                                          |
| Maximum account balance limit           | Prevents an account's balance from exceeding a threshold defined by account type and currency                     | — (scoped via script basis rather than a simple parameter) |

#### Wallet Status Enforcement Rules

Control behavior based on a wallet's current lifecycle status, preventing operations against wallets that aren't in a valid state.

| Rule                           | Status blocked  | Applies to                       |
| ------------------------------ | --------------- | -------------------------------- |
| Reject on pending wallet       | `PENDING`       | Either wallet in the transaction |
| Reject on suspended wallet     | `SUSPENDED`     | Either wallet                    |
| Reject on suspended in wallet  | `SUSPENDED_IN`  | Target wallet only               |
| Reject on suspended out wallet | `SUSPENDED_OUT` | Source wallet only               |
| Reject on terminated wallet    | `TERMINATED`    | Either wallet                    |
| Reject on closed wallet        | `CLOSED`        | Either wallet                    |

Every rule in this group includes the same exception: it blocks the transaction *unless an explicit override is present*.

#### Wallet Restriction Rules

A related but distinct group, governing wallets flagged with a restriction type rather than a lifecycle status.

| Rule                            | Restriction blocked             | Direction                  |
| ------------------------------- | ------------------------------- | -------------------------- |
| Reject on block all wallet      | `BLOCK_ALL`                     | Both incoming and outgoing |
| Reject on block incoming wallet | `BLOCK_ALL` or `BLOCK_INCOMING` | Incoming only              |
| Reject on block outgoing wallet | `BLOCK_ALL` or `BLOCK_OUTGOING` | Outgoing only              |

#### Currency Rules

Ensure transactions align with wallet-defined currencies, or restrict which currencies a wallet can be created in.

| Rule                        | What it does                                                                  |
| --------------------------- | ----------------------------------------------------------------------------- |
| Currency match check        | Blocks a transaction when the source and target wallet currencies don't match |
| Wallet currency restriction | Restricts wallet creation to a defined set of currencies                      |

The currency match check is generally treated as mandatory in multi-currency environments, to avoid cross-currency mismatches. Wallet currency restriction is used to enforce a product-level currency policy at the point a wallet is created — for example, restricting new wallets to EUR, GBP, or USD only.

#### Data and Control Rules

Rules aimed at observability and extensibility rather than blocking behavior.

| Rule               | What it does                                                                                                                      |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| Echo movement data | Echoes key movement attributes — group ID, payment ID, execution ID, and command — commonly used for audit or debugging pipelines |

### Using the Enablement Toggles

Each rule is independently toggleable. Enabling a rule includes its logic in the ledger's runtime behavior; disabling it excludes that rule entirely. Because these rules live at the service level, changes apply across every product built on this service version — not to a single product in isolation.

Not all rules are meant to be used together. Enabling overlapping rules — for example, more than one balance-limit rule with conflicting thresholds — can lead to redundant enforcement or unintended failures. Review the full set of enabled rules together, not just the one being changed.

### Saving

After rules are configured:

1. Review every toggled rule and its parameter values.
2. Click **Save** to persist the configuration to this version.

Because this is a versioned configuration, changes can be reviewed and tested against a specific version before it becomes the one every product actually relies on — the same controlled-rollout pattern used elsewhere in product configuration.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.xyb.co/xyb-platform-1/xyb-ledger/getting-started/ledger-service-configuration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.