Milestone

I. What is a Milestone ?

A milestone in Algolancer represents a distinct phase of work within a milestone project. It serves as the primary unit for defining, tracking, reviewing, and validating deliverables that a freelancer is expected to complete in exchange for a predetermined payment amount. Throughout the milestone lifecycle, freelancers work toward the agreed objectives and may provide updates, supporting materials, and final deliverables demonstrating completion of the required work. Once submitted, the milestone enters the review process, where the client evaluates whether the deliverables satisfy the agreed requirements and acceptance criteria. All data associated with a milestone are fully decentralized on Algorand for immutability and transparency. Any update to a milestone requires a blockchain interaction, creating a permanent and verifiable record of all changes. A milestone is unique to each {project, freelancer} pair. This means it cannot be shared between multiple freelancers for the same project, nor can it be associated with multiple projects for the same freelancer.

II. Starting new Milestone

Rules :

  • Project global state == "running"
  • Freelancer local state == "hired"
  • Freelancer local project state == "waiting_to_start_new_milestone"

When starting a new milestone, the user is required to deposit a USDC amount equal to Milestone Amount + Protocol Fees.
Once the number of accomplished milestones reaches the total number of milestones defined for the project, the client can no longer start a new milestone.

All funds are locked in the smart contract escrow, we do not hold any money, and all transactions are automatically executed by the contract’s logic, ensuring instant and transparent peer-to-peer payouts.

Total Paid Amount = Milestone Amount + Protocol Fees

Protocol Fees = Milestone Amount * 3%

Example :

  • A client hires a freelancer for a milestone project with an agreed milestone budget of $300
  • Milestone Amount = $300
  • Protocol Fees = $300 * 3% = $9
  • Total Paid Amount = $300 + $9 = $309
  • The fate of the milestone amount highly depends on the next steps which are detailed in the following sections.

III. Freelancer - Submit Milestone

Rules :

  • Project global state == "running"
  • Freelancer local state == "hired"
  • Freelancer local project state == "running_milestone"

A freelancer can submit a milestone at any time, as long as the above conditions are satisfied.

IV. Client - Approve Milestone

Rules :

  • Project global state == "running"
  • Freelancer local state == "hired"
  • Freelancer local project state == "submitted_milestone"

A client can approve a submitted milestone at any time, as long as the above conditions are satisfied. Once approved, the freelancer receives their payment instantly. The client can now start a new milestone if desired.

Freelancer Amount = Milestone Amount - Protocol Fees

Previous Example :

  • Freelancer Amount = $300 - $9 = $291
  • Freelancer receives their amount immediately

V. Client - Cancel Milestone

Rules :

  • Project global state == "running"
  • Freelancer local state == "hired"
  • Freelancer local project state == "running_milestone"

A client can cancel a running milestone at any time, as long as the above conditions are satisfied.
The period between milestone creation and cancellation is known as the Cancellation Interval (CL). This interval plays a key role in determining the fate of the milestone amount. Below are the most common scenarios based on the cancellation interval:

CL < 1 Hour :

The client will recover 100% of the milestone amount, while freelancer receives nothing. In this particular case, the client has to cover the freelancer protocol fee (3%), which will be deducted from the refund. The remaining amount is immediately returned to the client

Previous Example :

  • Client Milestone Amount Refund = $300 - $9 = $291
  • Freelancer Amount = $0

CL >= 1 Hour and <= 4 Hours :

The client will recover 80% of the milestone amount, while freelancer receives 20% with protocol fees (3%) deducted from the payment.

Previous Example :

  • Client Milestone Amount Refund = $300 * 80% = $240
  • Freelancer Amount = ($300 * 20%) - $9 = $51

CL > 4 Hours and <= 24 Hours :

The client will recover 70% of the milestone amount, while freelancer receives 30% with protocol fees (3%) deducted from the payment.

Previous Example :

  • Client Milestone Amount Refund = $300 * 70% = $210
  • Freelancer Amount = ($300 * 30%) - $9 = $81

CL > 24 Hours and <= MAX_CL :

MAX_CL is the maximum cancellation interval allowed for a client to cancel a milestone. It is dynamic and calculated at runtime using an advanced strategy. Once exceeded, the milestone can no longer be cancelled.

The client will recover 55% of the milestone amount, while freelancer receives 45% with protocol fees (3%) deducted from the payment.

Previous Example :

  • Client Milestone Amount Refund = $300 * 55% = $165
  • Freelancer Amount = ($300 * 45%) - $9 = $126

VI. Freelancer - Cancel Milestone

Rules :

  • Project global state == "running"
  • Freelancer local state == "hired"
  • Freelancer local project state == "running_milestone"

A freelancer can cancel a running milestone at any time, as long as the above conditions are satisfied. Once cancelled, the client will recover 100% of the milestone amount, while freelancer receives nothing.
In this particular case, the client has to cover the freelancer protocol fee (3%), which will be deducted from the refund.

Previous Example :

  • Client Milestone Amount Refund = $300 - $9 = $291
  • Freelancer Amount = $0

VII. Client - Refund Milestone

Rules :

  • Project global state == "running"
  • Freelancer local state == "hired"
  • Freelancer local project state == "running_milestone"
  • milestone submission deadline has been reached

A client can request a full refund at any time, as long as the above conditions are satisfied. Client will recover 100% of the milestone amount, while freelancer receives nothing.
In this particular case, the client has to cover the freelancer protocol fee (3%), which will be deducted from the refund.

Previous Example :

  • Client Milestone Amount Refund = $300 - $9 = $291
  • Freelancer Amount = $0

VIII. Client - Burn Milestone

Rules :

  • Project global state == "running"
  • Freelancer local state == "hired"
  • Freelancer local project state == "submitted_milestone"

A client can burn a submitted milestone at any time if they are not satisfied with the freelancer’s work, as long as the above conditions are satisfied.
Neither the client nor the freelancer will receive any share of the milestone amount.

Burned Amount = Milestone Amount - Protocol Fees

The full burned amount will be transferred to a designated burn address. These funds will be allocated to build our dispute resolution system, which will replace the burn mechanism in the near future and will be used to resolve disputes between clients and freelancers when disagreements arise over submitted work.

Previous Example :

  • Client Milestone Amount Refund = $0
  • Freelancer Amount = $0
  • Burned Amount = $300 - $9 = $291