Giveth Entities and Roles

Giveth TRACE has officially been deprecated. After 5 years of faithful service, Giveth and its platform, services and products have fully migrated to Giveth.io. With the deprecation of the Rinkeby network and low user activity, the Giveth DAO decided to sunset its original dApp in Q3 of 2022. The code has and will forever be open-source, and you can find it in Giveth's Github repositories.

This documentation will remain available for historical reference.

---

Content and ideas have been modified from this excellent article “An Overview of the Giveth Donation Application” authored by Kris Decoodt in 2017. Many things have been revised and modified since 2017. Here we breakdown the DApp as it is in 2022.

This document explains how different interactions within the Giveth DApp can be made. The goal is to provide a clear outline of the entities and roles within the Giveth TRACE DApp. This document has been tailored for several audiences and use cases as follows:

• Developers: can use this document as part of System Requirements.
• Testers: can use this document to understand how the DApp should work in order to determine what behaviour is wrong and should be reported as a bug. This document is not a formal Test Case in SDLC (Software Development Life Cycle) but can still be used for guidance.
• The Support Team: can use this document as a refererence to help new users who experience difficulties with the DApp.
• The End User: can use this document to gain a greater understanding of how the DApp works. However, foundational knowledge of Blockchain, Ethereum and Giveth is recommended.

Roles

We have eight roles in Giveth TRACE. In this section we explain in-depth each role, their function, how to become one and the power each role has.

1. Giver
2. Community Manager
3. Campaign Manager
4. Campaign Reviewer
5. Trace Manager
6. Trace Reviewer
7. Recipient
8. Website User

Website User

This refers to any person who visits our website. Without registering as a user on Rinkeby they cannot interact with any Giveth entity nor make donations on Giveth TRACE.

How to become a Website User

• Anyone with the address of the Giveth TRACE website can become a User.

Power of a Website User

• Browse through Communities, Campaigns and Traces.
• Register a profile.
• Edit their profile.
• View someones else's profile.
• Subscribe to a Community, Campaign or Trace.

Note: Most site actions require authentication through an Ethereum web wallet; currently Giveth TRACE only supports MetaMask.

Giver

The term Giver describes anyone who uses our platform to give donations to a Community, Campaign or Trace. Givers can interact with all 3 entities but are not explicitly part of any unless they choose to join a Community or assume another role as well.

How to become a Giver

• Anyone with an Ethereum wallet can donate to a Community, Campaign, or Trace in the DApp and become a Giver.

Power of a Giver

• Accept or reject a delayed delegation from a Community or Campaign.

Note: Givers can veto or "reject" a proposed Delegation within 3 days of the delegation proposal. This is referred to as a delegation "delay". After 3 days, the delayed delegation will be accepted by the DApp automatically.

Community Manager (formerly Delegate)

A Community Manager is the registered user owning a Community. They can delegate the funds donated to their Communities. A delegation is a process, where the donation pledged to a Community is transferred to a Campaign or Trace. Once delegated, the Giver has 3 days to reject (or approve) the delegation. After that time, the money is auto-approved and locked in the Campaign or Trace to which the money was delegated.

How to become a Community Manager

• A user can create a Community and become the Community Manager after being whitelisted by a DApp Admin.

Power of a Community Manager

• Edit the name, description, image, and link of their Community.
• Give Community funds (via delayed delegation) to Campaigns, and Traces.

Note: In order to initiate a delayed delegation, the Community Manager should go to the Traces or Campaign page, and click the Delegate Funds button.

Campaign Manager

Campaign Managers are Giveth.io users who have chosen to make their project traceable and have passed the project verification process. The role of the Campaign Manager is to create Traces through which they can fund the work of people and the cost of resources behind the project.

How to become a Campaign Manager

• Verify their Giveth.io project and request to become traceable, upgrading to a Campaign on TRACE and becoming the Campaign Manager of said Campaign.

Power of a Campaign Manager

• Edit their Campaign.
• Send Campaign funds (via delegation) to Traces within their Campaign.
• Reject or accept proposed Traces to their Campaign.
• Create or edit Traces in their own Campaign.

Note: A Trace has to belong to at least one Campaign and needs to be approved by the Campaign Manager.

Campaign Reviewer

Because donations to a Campaign are locked, a Campaign Reviewer role is critical to review and track the Campaign's progress. Campaign Reviewers have the responsiblity of checking the legitimacy of a Campaign and its Traces. They also have considerable power within a Campaign.

How to become a Campaign Reviewer

• A Campaign Manager can assign a user to become a Campaign Reviewer.

Power of a Campaign Reviewer

• Reject or approve Completed Traces.
• Cancel Traces within their Campaign.
• Cancel a Campaign.

Trace Manager (formerly Milestone Manager)

Traces are the foundation of the Giveth system. Any registered user can propose a Trace to a Campaign. However, a Campaign Manager or Campaign Reviewer must approve the Trace proposed to their Campaign for it to become valid. Traces can represent several types of requests for funding. More info on types of Traces are detailed further in this document.

How to become a Trace Manager

• A user can propose a Trace to Campaign and become the Trace Manager.

Power of a Trace Manager

• Edit their Trace.
• In the case of creating a Bounty or Milestone, a Trace Manager can set a Trace Reviewer.
• Mark a Trace as complete.

Note: A Trace can no longer be edited once it has received a delegation or donation.

Trace Reviewer

• A Trace Reviewer can be assigned by a Trace Manager.

Power of a Trace Reviewer

• Reject or approve a completed Trace.
• Cancel a Trace.

Note: In the case that a Trace is cancelled, the currency returns to the source, i.e. to the Giver for a donation or to the Community/Campaign for a delegation.

Recipient

A Recipient is a registered user who will receive payment from their successfully completed Trace. In the majority of cases, the Recipient is also the Trace Manager as they are the one working on the Trace. However, in some cases the recipient is separate, such as for payments to a supplier or a Milestone for a Campaign.

How to become a Recipient

• A Recipient can be designated by a Trace Manager; it can be the Trace Manager or another user.

Power of a Recipient

• Mark a Trace as complete.
• Request payout of the Trace funds.

Note: In the case that the Trace has a Reviewer, collecting funds needs the Reviewer's approval.

Latency

Some actions need to be registered to the Ethereum blockchain network. Adding transactions to the blockchain does not happen immediately, so we observe a latency in some actions. This latency depends on the network conditions, for example traffic on the network.

Locality of Roles

All roles have a limited scope and once an entity ceases to exist, so do the connected roles. Every Community contains exactly one Manager. Every Campaign has one Campaign Manager and one Campaign Reviewer. Every Trace has one Trace Manager, one Recipient and potentially one Reviewer. The Giver is not explicitly associated with any entity but may interact with all of them.

Currency Flow

Giveth TRACE on a technical level is a system for managing currency. Terms referring to the movement of funds within the Giveth system are defined as follows:

• Donation: When a Giver sends funds from their wallet to a Trace, Campaign, or Community.
• Collecting: When the Recipient sends or "collects" funds from a Trace to their wallet.
• Disbursing: When a Trace Manager sends funds from a Trace account to the Recipient's wallet.
• Delegation: When a Campaign Manager or Community Manager sends money from the Campaign or Community account to Trace account on behalf of the original Giver. A Giver can reject Delegation within 72 hours, after which the Currency transfer becomes irreversible.
• Refund: A Giver who has contributed to a Community can withdraw their funds as long as they are not yet committed to a Campaign or Trace. A Giver contributing to a Campaign can withdraw their funds as long as they are not yet committed to a Trace.

Currency Flow on Giveth TRACE

Entities

Giveth TRACE, on a technical level, is a system for managing currency. The DApp’s entities are accounts to which people can deposit, transfer or withdraw currency. We have three entities on Giveth TRACE, Communities, Campaigns and Traces. The relationship between them are defined in the chart below. Each entitity corresponds to one or more smart contracts.

Note: In Q1 2021 the Giveth team rebranded the entities DACs (Decentralized Altruistic Communities) to simply Communities, and Milestones to Traces.

Relationship between the DApp's Entities

Communities

Communities, formerly known as DACs, are the most general entity in the Giveth System. The purpose of a Community is to unite Givers around a cause and provide them with the possibility to give money to a cause without having to do the research involved in finding the exact Campaign to contribute to. Any money donated to a Community can be retrieved by the Giver, however we strongly discourage Givers to do so. The funds remain in the Community until they are delegated to a Campaign or a Trace, or withdrawn by the Giver. Community Managers can support any Campaign or Trace by sending currency to the account of the recipient.

State diagram for Community -> Campaign delegation flow, showing how donations made to a DAC are delegated to a Campaign.

State diagram for Community -> Trace delegation flow, showing how donations made to a Community are delegated directly to a Trace.

Campaigns

Campaigns are in the center of the Giveth donation system. They are effectively tools to steer money towards the smallest entities, Traces. A Campaign can be supported by more than one Community or by no Community at all. Campaign co-owners can only accept or reject proposed Traces. Campaign Reviewers can cancel the Campaign if the Campaign is bad or no longer active.

Donations made to a Campaign are locked, and unless the Campaign gets cancelled, the Giver no longer has control over the donation. The reason we lock the donations is to give the people behind the Campaign some level of certainty that they can count on getting the pledged donations and pledge them to one of their Traces.

State diagram for donations made to Campaign.

Traces

The main building blocks of the DApp are Traces, formerly known as Milestones. A Trace is the only way by which funds can exit the Giveth system. Traces must be created inside of a Campaign. Compared to a Community or Campaign, Traces are more complex because more roles can interact with them.

Trace Entities

To tailor Traces to meet the specific needs of Communities and Campaigns, there are certain rules that can be applied.

• Capped Traces: The maximum currency which can be given to to the Trace is set. This maximum is called the cap.
• Trace with Reviewer: The funds cannot be collected or disbursed from this Trace without confirmation by an assigned Trace Reviewer.
• Specify Currency Received: The Trace Creator is able to specify which of the whitelisted cryptocurrencies they would like to receive their funds in.

Based on these rules we can have four types of Traces with their own distinct properties: Milestones, Bounties, Expenses and Payments.

Milestones

Important goals or events for a Campaign. Any funds collected in Milestones go to the Campaign that it is a part of.

The Lifecycle of Milestones in the DApp is as follows:

Bounties

If a Campaign or Community needs to outsource work to be done, they can use a Bounty to compensate contributors for completing specific tasks.

The Lifecycle of Bounties is as follows:

Expenses

If there are recurring or singular expenses that were paid by a Campaign or Community Member, they can be tracked and reimbursed by this Trace.

The Lifecycle of Expenses is as follows:

Payments

Payments are compensation to Campaign members for the work they have done. Payments can be uncapped or capped for the funding they can receive.

The Lifecycle for Payments with NO cap is as follows:

The Lifecycle for Payments with a cap is as follows:

A breakdown of their functions can be summarized in the table below:

Trace Type	Funding is Capped	Specify Currency Received	Can Assign Reviewer	Currency Destination
Milestone	No	No	Yes	Campaign
Bounty	No	No	Yes	Any Address
Expense	Yes	Yes	No	Any Address
Payment NO Cap	No	Yes	No	Any Address
Payment with Cap	Yes	Yes	No	Any Address

Notes:

• In coding Entities are called projects.
• When money goes from a Community to a Trace or Campaign, Giveth then connects the Community with that Campaign or Trace. This means that you will see that Campaign or Trace represented on the Community page.
• If a Trace/Campaign/Community is canceled, the funds are returned to the source contributor automatically.
• Currency that goes to a Community is a loose commitment: at any point up until the moment funds are locked into a Campaign/Milestone, the Giver can decide to withdraw (refund) them.
• Currency that went to a Campaign/Trace is fully committed, because Trace Managers and Campaigns Manager take actions based on these funds.