MilestoneManager

File: MilestoneManager.sol

Things to know

1. This is a module to manage milestones for an orchestrator.
2. A milestone can exist in 4 different states:
   • added: The milestone got added to the contract.
   • active: When a milestone is started, it initiates payment orders to pay the orchestrator's contributors. A milestone is active, until either its duration is over or it's marked as completed.
   • submitted: An orchestrator contributor marks a milestone as submitted by submitting non-empty data that can be interpreted and evaluated by off-chain systems.
   • completed: After a milestone was submitted, it can be marked as completed. This marks the end of the milestone.

Modifier(s)

1. onlyContributor

modifier onlyContributorOf(uint milestoneId)

Modifier to ensure that the msg.sender is a valid contributor or not.

2. validDuration

modifier validDuration(uint duration)

Modifier to ensure that the duration is non-zero.

3. vaidMilestonePositionShift

modifier validMilestonePositionShift(uint id, uint idToPositionAfter)

Modifier to ensure that the position of the milestone (id) is valid after shifting its position to the new place in the linked list.

4. validSubmissionData

modifier validSubmissionData(bytes calldata submissionData)

Modifier to ensure that the submissionData is not empty.

5. validId

modifier validId(uint milestoneId)

Modifier to ensure that the milestoneId is not an existing milestone id.

6. validContributors

modifier validContributors(Contributor[] calldata contribs)

Modifier to ensure that the list of Contributor is not empty, has valid addresses, has valid salaries, are not duplicated and the sum of the salary percentages add up to the SALARY_PRECISION.

View Function(s)

1. getMilestoneInformation

function getMilestoneInformation(uint id) external view returns (Milestone memory);

This function returns the milestone instance with id id. Function reverts in case id is invalid.

Parameters

uint id -> The id of the milestone to return.

Return Data

1. Milestone with id id.

2. listMilestoneIds

function listMilestoneIds() external view returns (uint[] memory);

This function returns total list of milestone ids. The list is in ascending order.

Return Data

1. List of milestone ids.

3. getActiveMilestoneId

function getActiveMilestoneId() external view returns (unit);

This function returns the current active milestone's id. It will revert in case there is no active milestone.

Return Data

Current active milestone id.

4. hasActiveMilestone

function hasActiveMilestone() external view returns (bool);

This function returns whether there exists a current active milestone.

Return Data

True if the current active milestone exists, false otherwise.

5. isNextMilestoneActivatable

function isNextMilestoneActivatable() external view returns (bool);

This function returns whether the next milestone is activatable.

Return Data

True if the next milestone is activatable, false otherwise.

6. isExisitingMilestoneId

function isExistingMilestoneId(uint id) external view returns (bool);

This function returns whether a milestone with id id exists.

Return Data

True if milestone with id id exists, false otherwise.

7. getPreviousMilestoneId

function getPreviousMilestoneId(uint id) external view returns (uint prevId);

This function fetches the id of the previous milestone in the list and reverts if id invalid. This function should ideally be called from the front-end or from any off-chain source since running this on-chain would result in a lot of gas consumption owing to O(n) runtime.

Parameters

1. uint id -> The id of which the previous element in the list should be found.

Return Data

1. The id of the previous milestone.

8. isContributor

function isContributor(uint milestoneId, address who)
        public
        view
        returns (bool)

Returns whether an address is a contributor in one specific milestone.

Parameters

1. uint milestoneId: ID of the milestone for which who is being queried
2. address who: Address of the contributor

Return Data

bool: True if the address is a contributor, false otherwise.

Write Function(s)

1. addMilestone

function addMilestone(uint duration,uint budget,string memory title,string memory details) external returns (unit);

This function adds a new milestone and is only callable by authorized addresses. Reverts if an argument invalid.

Parameters

1. uint duration -> duration The duration of the milestone.
2. uint budget -> budget The budget for the milestone.
3. string title -> title The milestone's title.
4. string details -> details The milestone's details.

Return Data

The newly added milestone's id.

2. removeMilestone

function removeMilestone(uint prevId, uint id) external;

This function removes a milestone. Only callable by authorized addresses and reverts if id invalid, milestone is active, milestone already completed or milestone ids not consecutive in list.

Parameters

uint prevId -> The previous milestone's id in the milestone list uint id -> The milestone's id to remove.

3. startNextMilestone

function startNextMilestone() external;

The function starts the next milestones and creates the payment orders to pay contributors. It reverts if next milestone is not activatable or orchestrator's contributor list is empty or in case the token amount to pay the contributors can not be fetched from the orchestrator. Only callable by authorized addresses.

4. updateMilestone

function updateMilestone(uint id,uint duration,uint budget,string memory details) external;

This function updates a milestone's informations. Only callable by authorized addresses and reverts if an argument invalid or milestone already started.

NOTE: The manager can also update the milestone.

Parameters

1. uint id -> The milestone's id.
2. uint duration -> The duration of the milestone.
3. uint budget -> The budget for the milestone.
4. string details -> The milestone's details.

5. submitMilestone

function submitMilestone(uint id, bytes calldata submissionData) external;

This function submits a milestone. Only callable by addresses holding the contributor role and everts if id invalid, milestone not yet started, or milestone is already completed.

Parameters

1. uint id -> The milestone's id.
2. bytes submissionData -> Represents the data that is accompanied when a milestone is submitted. A Milestone is interpreted as being submitted when the submissionData bytes array is not empty. Note that only accounts holding the {CONTRIBUTOR_ROLE()} can set submittedData and therefore submit milestones.

6. completeMilestone

function completeMilestone(uint id) external;

This function helps complete a milestone. Only callable by authorized addresses. Reverts if id is invalid or milestone not yet submitted.

Parameters

1. uint id -> The milestone's id.

7. declineMilestone

function declineMilestone(uint id) external;

This function is used to decline a submitted milestone. Only callable by authorized addresses. Reverts if id invalid, milestone not yet submitted, or milestone already completed.

NOTE: This function deletes the existing submission and marks the milestone as unsubmitted again

Parameters

1. uint id -> The milestone's id.

8. updateMilestoneUpdateTimelock

function updateMilestoneUpdateTimelock(uint _newTimelock) external onlyAuthorized()

This function is used to update the _milestoneUpdateTimelock which is set to 3 days by default. The _milestoneUpdateTimelock is the allowed time gap between updating a milestone and starting it.

This function can only be called by authorized addresses.

Parameters

1. uint _newTimelock -> The new value for _milestoneUpdateTimelock