Skip to main content
A work session is a discrete, measurable unit of delivery on an Aven stream. Each session has a precise start and stop time, a record of active vs idle seconds, and a snapshot of Git activity that occurred during that period. The session data is compiled into a structured work report that the Aven verifier uses to compute the exact payment amount — and that the employer reviews before approving release. Every work session is linked to a specific stream by its stream_id. A worker can run multiple sessions against the same stream over the life of the project.

​
Session Lifecycle

1

Recording

The worker runs aven-stellar start inside the project Git repository. The CLI launches a lightweight background activity watcher that tracks active seconds and monitors the repository for changes.
2

Stopped

The worker runs aven-stellar stop. The CLI calculates Git change statistics since the session started, compiles the full report, previews it, and asks for submission confirmation. The original stop time is preserved — if submission fails and the worker re-runs stop, no extra time is counted.
3

Submitted

The report is sent to the Aven dashboard and appears under Work Sessions on the stream page. The verifier processes it and reserves the calculated payment amount in the smart contract escrow.
4

Under Review

The worker clicks Request Review, which notifies the employer that the session is ready for approval. The session moves into the review queue.
5

Approved or Disputed

The employer reviews the work record and either approves or disputes it. Approved sessions proceed to payment release. Disputed sessions freeze the reserved amount pending resolution.
6

Released

The worker calls withdraw_approved (via the dashboard Withdraw button), which transfers the reserved tokens from the contract directly to the recipient’s Stellar wallet address.

​
What the CLI Records

The aven-stellar CLI records the following information during a session: The CLI also categorises each changed file (source, test, documentation, configuration, asset, generated, dependency, unknown) and marks whether it was included in the verification payload. Files excluded by .gitignore or .avenignore are noted with an excludedReason.
The CLI never uploads complete source files, executes project code, records keystrokes or screenshots, or reads Stellar secret keys. Only metadata about what changed is included in the report.

​
What a Work Report Contains

The submitted work report (WorkSessionReport) is a structured JSON document containing all of the above session data, plus:
  • The worker’s delivery statement (workerStatement.message) — a summary the worker provides with --message
  • Local verification metadata — verifier version, work type classification, and a human-readable summary
  • Payment request — the calculated requestedAmount, the asset (XLM or USDC), the ratePerSecond, and billableSeconds used in the calculation
  • Privacy profile — counts of excluded files, secret warnings, and confirmation that no full source files were included
  • Delivery data (final sessions only) — selected branches, their head commits, and remote verification status
The report is reviewable by the employer on the stream page and forms the evidence record that backs the on-chain attestation when payment is released.

​
Verified vs Unverified Sessions

A submitted session is unverified until the Aven server-side verifier processes it. The verifier:
  1. Reads the session report from the Aven dashboard
  2. Independently calculates the payment as active_seconds × rate_per_second, capped by unreserved escrow
  3. Calls verify_work on the stream contract, passing the calculated amount and an evidence_hash (SHA-256 of the report)
  4. The contract re-validates the amount — if it does not match the contract’s own calculation, the transaction is rejected
Once verify_work succeeds, the session is verified: the payment amount is reserved in escrow and the evidence_hash is stored on-chain. The worker can then request employer review.

​
Normal Sessions vs Final Sessions

Normal sessions (aven-stellar stop) record a measured work period against a stream that will continue to accept future sessions. Final sessions (aven-stellar stop --ended) mark the end of the project. The worker is prompted to specify the delivery branches. The CLI verifies those branch head commits against the connected GitHub repository and includes delivery metadata in the report.
For a final session, the server uses ceil(remaining escrow ÷ rate) as the contract’s duration argument so the contract caps the verified amount to the exact remaining escrow. The real npm-tracked active seconds are still preserved in the report and displayed in the dashboard. Any pending or reserved payments must be resolved before a final session can be submitted.

​
Session ID

Each session is assigned a UUID (sessionId) at the moment aven-stellar start runs. This UUID is the request_id used in the contract’s WithdrawalRecord and propagated through to the on-chain AttestationRecord. It provides an unambiguous link between the off-chain report and the on-chain payment record.

​
The .aven/ Directory

The CLI stores recoverable local session state in a .aven/ directory at the root of the project repository. This includes:
  • The active session file (LocalSession) tracking start time, activity counters, and watcher PID
  • The Aven configuration file (AvenConfig) with dashboard URL, stream ID, worker address, cached rate, and authorization token
Do not commit .aven/ to version control. It contains a scoped CLI authorization token and local session state. Add it to your .gitignore.