Skip to main content
Aven eliminates manual invoicing. Payment amounts are calculated from cryptographically verified session data and enforced directly in the Soroban smart contract on Stellar. Workers never enter their own payment figure. Employers never receive an invoice to negotiate. The contract independently recalculates every amount before accepting it — if the verifier’s submitted amount does not match the contract’s own computation, the transaction is rejected.

​
Payment Formula

​
Normal Sessions

For a standard work session, the verifier calculates:
This is then capped by the stream’s current unreserved escrow balance:
The contract performs the same calculation independently using rate_per_ledger / LEDGERS_PER_UNIT × active_duration_seconds and compares it to the submitted amount. A mismatch causes the verify_work call to fail with a PaymentMismatch error.
Workers never enter their own payment amount. The verifier derives it from the tracked active seconds and the stream’s on-chain rate. The contract re-validates before any reservation is made.

​
Worked Example

If the unreserved escrow had been 0.20 XLM, the final reserved amount would be capped to 0.20 XLM instead.

​
Final Session Formula (--ended)

When a worker submits a final session with aven-stellar stop --ended, the remaining unreserved escrow is intended to cover the last payment in full. The server converts the remaining escrow into a contract-compatible duration argument:
This value is passed as the active_duration_seconds argument to verify_work, ensuring the contract caps the verified amount to the exact remaining escrow — even if the worker’s real tracked active seconds were less. The worker’s real npm-tracked active seconds are preserved separately in the report and displayed on the dashboard. The settlement seconds are recorded in the paymentRequest.settlementSeconds field for transparency.
All pending or reserved session payments must be resolved before a final session can be submitted. Check the stream page for any open sessions in Pending or Approved state.

​
Reservation vs Release

Payment flows through three distinct on-chain stages: When the employer calls approve_withdrawal, no tokens move yet — they remain in the contract. The tokens are transferred only when the worker subsequently calls withdraw_approved. This two-step design keeps the worker in control of when the transfer occurs. A disputed session returns the reserved amount to the unreserved escrow pool. The worker and employer must resolve the dispute off-chain or through the dashboard before another session covering that work can be submitted.

​
Stellar Fixed-Point Amounts

All token amounts in Stellar are represented as 7-decimal fixed-point integers (stroops for XLM):
The stream’s rate_per_second, total_deposited, and payment amounts are all stored and calculated in this format on-chain. The Aven dashboard converts these values to human-readable decimals at the display boundary. When reading raw contract data or building integrations, always work in stroops and divide by 10,000,000 for display.