Managing Movements in the Ledger

Movements are the fundamental units of financial operations in the ledger, representing the transfer of funds between wallets. They track value flow between debit and credit wallets, ensuring accurate financial records and transaction integrity.

States of a Movement

Movements transition through distinct states during their lifecycle:

• PASSIVE: The movement is created but does not yet have an assigned amount. It serves as a placeholder.

• ACTIVE: An amount has been assigned, but the movement has not been finalized. Funds are reserved but not committed.

• COMPLETE: The movement is finalized, and balances are updated accordingly. This state is irreversible.

• CANCELLED: The movement is voided without affecting balances. This is used for invalid or erroneous transactions.

Executing Movements

Executing a movement involves defining the transaction details and transitioning through the lifecycle.

Step 1: Create a Movement

Define the movement by specifying the source and destination wallets, the amount, and other parameters. Use the following command:

luca add-activity - /chart/company/expenses/default/USD /chart/company/revenue/default/USD 50 --finalize

• /chart/company/expenses/default/USD: Source wallet (debit).

• /chart/company/revenue/default/USD: Destination wallet (credit).

• 50: Amount being transferred.

• --finalize: Directly finalizes the movement, transitioning it to COMPLETE.

Step 2: Finalize the Movement

Movements created without the --finalize flag remain in an ACTIVE state and must be explicitly finalized using:

luca write-instruction

This command commits the movement, updating the relevant wallet balances.

API-Based Movements

Movements can also be managed programmatically via the API.

API Endpoint

POST /api/v1/movement/

Payload Example

{
  "id": "548133b4-8067-44f6-ba67-e864c089bb8d",
  "debit_wallet_address": "/chart/primary/nostro/default/GBP",
  "credit_wallet_address": "/group/eu/customer7331/default/GBP",
  "amount": 150,
  "decimal_places": 2,
  "attributes": {
    "payment-id": "9d8eb5af-b758-4237-9da6-435c2555790e"
  },
  "state": "ACTIVE",
  "value_date": "2022-10-13T09:30:55.000893Z"
}

• debit_wallet_address: Source wallet.

• credit_wallet_address: Destination wallet.

• amount: Transfer amount.

• decimal_places: Precision for the transaction.

• state: Current state (e.g., ACTIVE or PASSIVE).

• value_date: The date when the transaction takes effect.

A separate API call is required to finalize the movement.

Best Practices for Managing Movements

• Track Movement States: Regularly monitor movement states to ensure transactions progress as expected. Movements stuck in PASSIVE or ACTIVE states should be reviewed.

• Cancel Unneeded Movements: If a movement is no longer required, cancel it to prevent unnecessary ledger entries.

• Use Finalization Wisely: Directly finalizing a movement (--finalize) is efficient but should only be used when all details are confirmed.

Example Use Cases

1. Expense Tracking: Debit an expense account and credit a revenue account to record operational costs.

2. Revenue Allocation: Move funds from a revenue wallet to a designated expense or salary wallet.

3. Multi-Activity Transactions: Multiple activities (e.g., salary payment and fee deduction) can be grouped into a single instruction before execution.

---