Implementation

Internal architecture and execution model across contract logic, typed SDK paths, and browser wallet orchestration.

System Layers

flowvault-contracts  ->  flowvault-sdk  ->  frontend/demo app
(Clarity)               (typed interface)   (wallet UX)

The architecture intentionally keeps business rules on-chain and leaves client layers responsible for validation, UX, and retries.

State Shape

Per-principal state in FlowVault tracks at minimum unlocked balance, locked balance, and routing configuration values for split + lock.

  • unlocked: immediately withdrawable amount.
  • locked: amount subject to lockUntilBlock.
  • splitAddress: optional recipient for per-deposit split.
  • splitAmount and lockAmount: deterministic transfer values.

Write Path

  1. SDK validates amount/address/routing input.
  2. SDK builds Clarity function arguments.
  3. SDK executes via senderKey mode or wallet executor mode.
  4. SDK normalizes tx id and returns TransactionResult.

Wallet mode is recommended for web clients because private keys never enter browser runtime.

Read Path

  1. SDK validates target principal address.
  2. SDK calls read-only contract function.
  3. SDK parses Clarity values into typed objects.
  4. Application renders state with clear locked/unlocked values.

This parsing layer prevents UI teams from handling low-level Clarity tuple parsing directly.

Amount Precision

tokenToMicro and microToToken use deterministic string parsing and bigint math to avoid floating-point rounding errors in financial flows.

Reliability Notes

  • Use idempotent UI actions with disabled submit during pending tx.
  • Handle explorer latency by polling read state after write confirmation.
  • Capture tx ids in logs for support and incident debugging.
  • Validate STX address selection to avoid accidental BTC-address usage.