Create & Manage Instructions
Instructions are the starting point for executing financial operations within the ledger. They act as containers that hold multiple activities, such as fund transfers or account updates.
An instruction itself does not move funds—it simply defines the operations that need to be executed. Once an instruction is processed, it generates movements, which update wallet balances.
How Instructions Work
Add activities to an instruction: Define fund transfers, allocations, or other operations.
Write the instruction: Once all activities are added, submit the instruction for processing.
Instruction is processed: The system generates movements based on activities.
Movements update wallet balances: Once finalized, the transaction is complete.
Creating Instructions Using the CLI
Step 1: Add Activities to an Instruction
Each activity within an instruction defines a specific action (e.g., debiting and crediting wallets). Multiple activities can be added before finalizing an instruction.
Example CLI Command
./luca add-activity - /chart/company/revenue/default/USD \
/group/customers/customer123/default/USD 100
./luca add-activity - /chart/company/revenue/default/USD \
/chart/company/fees/default/USD 5/chart/company/revenue/default/USD → Source wallet (Revenue Account).
/group/customers/customer123/default/USD → Customer’s wallet.
100 → Amount being transferred.
Second activity: Transfers $5 as a fee deduction.
Note: You can add multiple activities before finalizing an instruction. This ensures that all related transactions (e.g., main payment + fees) are processed together.
Step 2: Write the Instruction
Once all activities are added, execute:
./luca write-instructionThis submits the instruction to the ledger.
Movements are not created yet—they will be generated once the instruction is processed.
Creating Instructions Using the API
For system integrations, instructions can be created programmatically via API.
API Endpoint
POST /api/v1/instruction/Updated API Payload Example
{
"id": "instruction-123",
"activities": [
{
"debit_wallet_address": "/chart/company/revenue/default/USD",
"credit_wallet_address": "/group/customers/customer123/default/USD",
"amount": 100,
"decimal_places": 2,
"attributes": {
"transaction-id": "9d8eb5af-b758-4237-9da6-435c2555790e"
}
},
{
"debit_wallet_address": "/chart/company/revenue/default/USD",
"credit_wallet_address": "/chart/company/fees/default/USD",
"amount": 5,
"decimal_places": 2
}
],
"state": "ACTIVE"
}Key Parameters
id → Unique instruction identifier.
debit_wallet_address → The source wallet for the transaction.
credit_wallet_address → The destination wallet.
amount → Value to transfer.
decimal_places → Number of decimal places for precision.
attributes → Metadata for tracking (
transaction-id).state → The current instruction state (
PASSIVE,ACTIVE).
Finalizing Instructions and Generating Movements
CLI Finalization
If activities were added without --finalize, finalize them manually after writing the instruction:
./luca finalize-instruction instruction-123This triggers movement creation based on the activities.
Finalizing an Instruction via API
If "state": "ACTIVE", finalize it by calling:
POST /api/v1/instruction/finalize{
"instruction_id": "instruction-123"
}This ensures all included activities are processed together.
Retrieving the Generated Movements
Once finalized, movements can be retrieved using:
GET /api/v1/movement?instruction_id=instruction-123This confirms which movements were created from the instruction.
Best Practices for Managing Instructions
1. Validate Chart and Wallet Structure
Ensure that all wallet paths are correctly mapped to avoid processing errors.
2. Use Finalization Carefully
The --finalize flag (CLI) or finalize parameter (API) locks the activity, preventing further edits.
3. Audit Instructions Regularly
Periodically review instructions to ensure business rules and ledger integrity.
Example Use Cases
1. Processing Customer Payments
Scenario: A customer makes a $100 payment.
Example: The instruction contains one activity to debit the customer’s wallet and credit the company’s revenue account.
2. Handling Multi-Step Transactions
Scenario: A payment includes a service fee.
Example:
Activity 1: $100 to the company’s revenue wallet.
Activity 2: $5 deducted as a service fee.
3. Automating Fund Transfers via API
Scenario: Automating internal fund allocations.
Example: Move funds from a revenue wallet to an expense wallet on a scheduled basis.
Key Takeaways
Instructions act as containers for multiple activities.
Activities define individual operations (debiting and crediting wallets).
Writing an instruction does not update balances—it queues activities for processing.
Movements are generated from instructions after processing.
Finalizing an instruction creates movements that update wallet balances.
Last updated