multiversx-vault-pattern_skill

Overview

This skill implements an in-memory token ledger pattern for tracking intermediate balances during multi-step operations inside a single transaction. It avoids storage writes by using a fast map for lookups and a vector for ordered iteration and settlement. Use it to safely aggregate, transform, and return token payments within atomic flows like swaps, batch processors, or multi-step DeFi logic.

How this skill works

The ledger pairs a ManagedMapEncoded for O(1) balance lookups with a ManagedVec that records insertion order for efficient settlement. You initialize the ledger from incoming payments, deposit and withdraw precise or percentage amounts, and remove zero balances to keep the set compact. At the end of the transaction the ledger converts non-zero balances into payment objects for transfer back to the caller or protocol.

When to use it

• Building multi-step token flows executed in a single transaction (swaps, routing)
• Aggregators or batch processors that transform tokens sequentially
• Atomic swaps or cross-token operations where intermediate state must be tracked
• When you need temporary balances only for the duration of one call (avoid storage)
• When you want deterministic ordered settlement of remaining tokens

Best practices

• Initialize ledger from call_value payments to capture all incoming tokens
• Use ManagedMapEncoded for constant-time updates and ManagedVec for ordered settlement
• Always remove zero balances when withdrawing to avoid gas waste during settle_all
• Use NonZeroBigUint/Payment types for settlement to skip zero-amount transfers
• Keep token sets small (typically < 10) to make O(N) removal acceptable

Example use cases

• A DEX route executor: swap A→B→C in a single endpoint, tracking intermediate B without storage writes
• A batch processor that collects many token payments, runs transformations, and returns leftovers atomically
• An atomic swap contract that debits inputs, runs verification and conversion steps, then settles outputs to participants
• A multi-step yield flow that stakes, harvests, and rebalances tokens inside one transaction