Work Sessions: Privacy-First Contribution Proof on Aven

A work session is a privacy-first record of Git activity tied to a stream — proving what changed during a work period without exposing your source code.

A work session is a recorded period of activity tied to a specific payment stream. When you run the aven-stellar CLI inside your Git repository, it tracks how long you were actively working and what changed in the codebase — then packages that evidence into a structured report that you can review before submitting to your client for approval.

What a Session Captures

Every work session report contains the following categories of data:

• Session timing — the wall-clock start and end times, total elapsed seconds, active seconds (time with detected activity), and idle seconds. Payment is calculated from active seconds only.
• Git repository state — the branch name at session start and end, the starting commit hash, and the ending commit hash. This anchors the session to an exact snapshot of the repository.
• File change summary — relative file paths, change type (created, modified, deleted, or renamed), line additions and deletions, and the file category (source, test, documentation, configuration, etc.). Files excluded by .gitignore or .avenignore are never included.
• Commit history — each commit made during the session, including its hash, message, timestamp, and diff size (additions/deletions). Full file contents are never uploaded.
• Worker statement — an optional plain-text summary you can provide with --message when stopping the session. This gives you space to explain decisions, blockers, or context that the Git data alone does not convey.
• Payment request — the amount you are requesting, calculated automatically as active_seconds × stream_rate_per_second, capped by the funds currently available in the stream.

Session Report Structure

The complete shape of a submitted report is defined by the WorkSessionReport type in the CLI package:

export type WorkSessionReport = {
  schemaVersion: 1;
  session: {
    sessionId: string;
    projectId: string;
    streamId: string;
    workerAddress: string;
    startedAt: string;
    endedAt: string;
    totalSeconds: number;
    activeSeconds: number;
    idleSeconds: number;
    packageVersion: string;
    ended?: boolean;
  };
  repository: {
    repositoryId: string;
    branchAtStart: string;
    branchAtEnd: string;
    startingCommit?: string;
    endingCommit?: string;
    dirtyAtStart: boolean;
    dirtyAtEnd: boolean;
  };
  changes: {
    changedFiles: FileChangeSummary[];
    additions: number;
    deletions: number;
    commits: CommitSummary[];
    testsChanged: number;
    documentationFilesChanged: number;
    generatedFilesExcluded: number;
  };
  workerStatement?: { message: string; providedAt: string };
  localVerification: {
    verifierVersion: string;
    workType: "code" | "writing" | "image" | "mixed";
    flags: string[];
    summary: string;
  };
  paymentRequest: {
    requestedAmount: string;
    asset: "USDC" | "XLM";
    calculation?: "active_time_x_stream_rate" | "flat_rate";
    ratePerSecond?: string;
    billableSeconds?: number;
  };
  privacy: {
    profile: "standard";
    excludedFileCount: number;
    secretWarnings: number;
    fullFilesIncluded: false;
  };
};

Session Lifecycle

The session does not submit anything automatically. You always see the full report and confirm before it is sent to the dashboard.

Work Session States

State	Description
Pending	The session has been submitted and is awaiting client review
Approved	The client has verified the session; payout and attestation are in progress
Disputed	The client has raised a dispute; no payment is released until resolved
Withdrawn	Payment has been successfully transferred and an attestation has been minted

Payment Calculation

The requested payment is calculated as:

payment = active_seconds × rate_per_second

The result is automatically capped by the amount of funds currently earned in the stream at the time of submission. You cannot request more than the stream has accrued, even if your active time technically entitles you to more. If the stream is nearly exhausted, the cap applies and a new stream may need to be created to cover additional work.

What the CLI collects: session timing, your active Git branch, commit metadata (hash, message, timestamp, and diff sizes), relative file paths, and additions/deletions counts.

What the CLI never collects: file contents, keystrokes, screenshots, your Stellar secret key, project dependencies, or any path excluded by .gitignore or .avenignore. Your intellectual property stays on your machine.