> ## Documentation Index
> Fetch the complete documentation index at: https://aven-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# How Aven Calculates and Enforces Payments On-Chain

> Aven derives every payment from verified active seconds and the stream rate, then enforces the calculation inside the Soroban smart contract on Stellar.

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:

```
payment amount = active_seconds × rate_per_second
```

This is then capped by the stream's current unreserved escrow balance:

```
final amount = min(active_seconds × rate_per_second, unreserved_escrow)
```

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.

> [!NOTE]
>
> **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

```
Stream rate:          0.0001 XLM per second
Active seconds:       3,600  (1 hour)
──────────────────────────────────────────
Calculated amount:    0.36 XLM

Unreserved escrow:    10 XLM
→ amount is NOT capped (0.36 < 10)

Reserved for session: 0.36 XLM
Remaining unreserved: 9.64 XLM
```

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:

```
settlement_seconds = ceil(remaining_escrow ÷ rate_per_second)
```

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.

> [!TIP]
>
> 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:

```mermaid theme={null}
flowchart TD
  A[Session submitted] --> B[Verifier runs verify_work]
  B --> C[Amount reserved in escrow]
  C --> D{Employer decision}
  D -->|Approve| E[withdraw_approved called]
  E --> F[Payment released to freelancer]
  D -->|Dispute| G[Reservation frozen]
  D -->|Timeout| H[finalize_timeout called]
  H --> F
```

| Stage | Contract action | Effect |
| - | - | - |
| **Reserved** | `verify_work` | Amount subtracted from `compute_available`; added to reserved total |
| **Approved** | `approve_withdrawal` | Withdrawal record status set to `Approved` |
| **Released** | `withdraw_approved` | Tokens transferred from contract to recipient; `total_withdrawn` incremented |
| **Disputed** | `dispute_withdrawal` | Reservation cleared; amount returned to unreserved pool pending resolution |
| **Timeout** | `withdraw_approved` after `deadline_ledger` | Contract auto-releases without employer action |

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):

```
1 XLM = 10,000,000 stroops
```

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.