> 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/integrate-with-xyb-ledger/understanding-the-ledger-structure-charts-accounts-wallets/create-and-manage-rules.md).

# Create and Manage Rules

### **1. Create and Manage Rules**

Rules define how the ledger operates under specific conditions, preventing unauthorized or undesired actions. These rules help enforce organizational policies and workflows.

The ledger system supports the following types of rules:

#### **Rule Categories**

* **Intrinsic (Built-in) Rules**: Hardcoded into the ledger, cannot be modified but can be enabled or disabled.
* **Predefined (Configurable) Rules**: Provided by the system, but users can configure parameters.
* **Custom (User-Defined) Rules**: Created entirely by users, allowing for tailored enforcement.

Rules are managed through the **Luca CLI commands** or **APIs**.

***

### **2. Rulebooks and Rules**

* **Rulebooks**: A collection of rules grouped together for specific use cases.
  * Example: `common_rulebook` for balance checks and currency validation.
* **Rules**: Individual policies within a rulebook.
  * Example: `Min Wallet Balance Limit` prevents wallets from going negative.

***

### **3. Rule Statuses**

Rules have three possible statuses:

* **Enabled (Active)**: The rule is currently enforced.
* **Disabling (Transitional State)**: The rule is in the process of being disabled.
* **Disabled (Inactive)**: The rule exists but is not applied.

Rules are tied to **specific triggers** in the ledger workflow, such as:

* **Wallet creation**
* **Account operations**
* **Fund transfers and payments**

***

### **4. Steps to Implement Rules**

#### **1. Identify Needs**

* Use built-in or predefined rules when possible.
* Create custom rules for unique cases.

#### **2. Leverage Tools**

* Manage rules efficiently using the **Luca CLI** or APIs.

#### **3. Test and Validate**

* Ensure rules function correctly before deployment.
* Use logs and test transactions to verify enforcement.

***

### **5. Implementing Rules Using CLI Commands**

#### **1. Create a Rulebook**

```sh
luca write-rulebook <rulebook_name>
luca write-rulebook common_rulebook
```

#### **2. Define a Rule**

```sh
luca write-rule <rulebook_name> <rule_name>
luca write-rule common_rulebook min_wallet_balance_limit
```

#### **3. Enable a Rule**

```sh
luca transition "/rulebook/<rulebook_name>/<rule_name>" ENABLED
```

#### **4. Verify Rule Activation**

```sh
luca read-rules <rulebook_name>
```

#### **5. Test Rules**

```sh
luca add-activity /chart/CHART_NAME/ACCOUNT
```

#### **6. Disable a Rule**

```sh
luca transition "/rulebook/<rulebook_name>/<rule_name>" DISABLED
```

#### **7. Modify a Rule**&#x20;

```sh
luca write-script <rulebook_name> <rule_name> --language=INTRINSIC
```

#### **8. Delete a Rule**

```sh
luca delete-rule <rulebook_name> <rule_name>
```

***

### **6. Troubleshooting**

#### **Rule Not Being Enforced**

* Ensure the rule is **ENABLED**.
* Verify **script logic and parameters**.

#### **Errors During Testing**

* Ensure **rule conditions match the ledger environment**.
* Verify **any required datasheets or parameters**.

***

### **7. Ledger Rules Glossary**

This glossary provides a detailed list of all rules, their purposes, and categories.

#### **Intrinsic (Built-in) Rules**

| **Rule Name**                   | **Purpose**                                                  |
| ------------------------------- | ------------------------------------------------------------ |
| **Currency Match Check**        | Ensures source and target wallet currencies match.           |
| **Max Wallet Balance Limit**    | Prevents outgoing payments if the balance would be negative. |
| **Min Wallet Balance Limit**    | Blocks payments if the balance is below zero.                |
| **Global Consolidated Balance** | Ensures multi-currency compliance.                           |

#### **Predefined (Configurable) Rules**

| **Rule Name**                   | **Purpose**                                     | **Customizable Parameters** |
| ------------------------------- | ----------------------------------------------- | --------------------------- |
| **Wallet Currency Restriction** | Ensures wallet currency is in the allowed list. | Allowed currencies list     |
| **Max Account Balance Limit**   | Restricts the max balance an account can hold.  | Currency-based limits       |
| **Min Wallet Balance Limit**    | Ensures transactions meet a minimum threshold.  | Threshold value             |
| **Reject on Closed Wallet**     | Blocks transactions to/from closed wallets.     | Configurable exceptions     |
| **Reject on Suspended Wallet**  | Blocks payments involving suspended wallets.    | Allow exceptions            |
| **Reject on Pending Wallet**    | Blocks transactions from pending wallets.       | Allow exceptions            |
| **Reject on Terminated Wallet** | Stops payments involving terminated wallets.    | Allow exceptions            |

#### **Transaction-Specific Rules**

| **Rule Name**               | **Purpose**                                                   |
| --------------------------- | ------------------------------------------------------------- |
| **Future Value Date Limit** | Restricts setting value dates too far in the future.          |
| **Past Value Date Limit**   | Prevents transactions with excessively old value dates.       |
| **Max Movement Limit**      | Ensures transactions do not exceed a defined upper threshold. |
| **Min Movement Limit**      | Enforces a minimum transaction amount.                        |

***

### **8. Best Practices for Ledger Rules**

* **Plan Ahead**: Understand rule impacts before enabling them.
* **Use Logs**: Track rule enforcement and troubleshooting.
* **Test Thoroughly**: Always validate new rules in a testing environment.
* **Stay Updated**: Monitor product updates for rule enhancements.


---

# 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/integrate-with-xyb-ledger/understanding-the-ledger-structure-charts-accounts-wallets/create-and-manage-rules.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.