# Andamio Smart Contracts

## Andamio Instances
Andamio is not a monolithic system like some of the "Web 2.0" social networks you might be accustomed to. In order to use it, an Organization must create a new, independent "Instance" of the Andamio Platform.

Andamio is built upon a set of ["parameterized" smart contracts](https://plutuspbl.io/modules/204/project-step-01). These Plutus smart contracts are used to manage treasury funds, track commitments from contributors, and to govern decision-making systems. Plutus contracts can be built with re-usable rules that remain constant with different parameters. The Andamio contracts define what an Organizational Administrator, Decision Maker or Contributor can do, but crucially, not who they must be. Unique Role-Based Access Tokens are minted uniquely for each role in every instance of the Andamio Platform.

Each instance runs independently on the Cardano blockchain, with unique access tokens, rules, and contract addresses. It is easy to make Andamio Instances interoperable, but by default they are independent. Organizations can opt into network participation when they are ready and at their own pace - for example, when collaboration across organizations is necessary for solving bigger problems.

---

## Roles
People participating in an Andamio Instance use on-chain, Role-Based Access Tokens to participate in the system. In Andamio, there are 4 role-based tokens:
1. Organization Admin
2. Decision Maker
3. Contributor
4. Learner

### Organization Admin
The Andamio Admin can add or remove tokens from the Andamio Treasury, and approves the list of valid Projects so that Contributors can make commitments.

### Decision-Maker
An Andamio Decision-Maker can approve that a "Commitment" is complete. In the Learning Management System, a Commitment can represent student completion of a Module, Project, or Student Learning Target. For organizations, a Commitment can also represent a project or task with token rewards. As we saw in [the previous section (Andamio PBL Framework)](/8qjZ6aAWROCRWlxGJr4azw), there is often overlap between "learning" and "contribution". Decision-Makers might be teachers and course instructors, or they might be project managers and development leaders. In great organizations, leaders often play a teaching role. The flexibility of the Andamio Decision-Maker role allows flexible, emergent leadership to develop across an organization.

### Contributor
An Andamio Contributor can make Commitments to Projects listed in an Andamio Instance. Projects can be for learning, as in a Project-Based Learning Course, or Projects can represent vital contributions to an organization. Commitments are tracked via the Contributor token, and over time can be used to build a track-record that be shared across organizations.

### Learner
There is overlap between Contributor and Learner tokens, and they work the same way. Often they are one and the same. When they want to, Organizations can create several different levels of contribution tokens. For example, they can allow anyone to mint an "Onboarding" token as they start to learn about the organization and its work, while setting some rules for how a Learner might earn a full-fledged Contributor token with access to more opportunities. In the rest of this paper, we will not distinguish between learners and contributors; we'll simply use the word "Contributors" to represent both.

### "Multi-Sig" Roles
Admin and Decision Maker roles can have multi-sig functionality. While it is possible to require just one signature to approve a Treasury Action or to unlock a Contributor's commitment, it is also possible to require multiple signatures to make these decisions. The Andamio Governance Contracts are used to customize and configure decision-making rules for an organization.

On the other hand, Contributor tokens are unique to each Contributor, and there is always a one-to-one mapping of a single wallet address to a Contributor Token.

### Connections to Identity
Each Andamio Role Token is an indentifier for participants in the platform. It can be connected to systems for Self-Sovereign Identity (SSID) and Decentralized Identity. Take a look at the [Development Roadmap](/JYev1qpYSj62fnrm3aRWCA) to see how we are connecting Andamio to new and existing identity systems.

---

## Contracts
A set of Plutus Smart Contracts is used in every an Andamio Instance:

1. Treasury
2. Escrows
3. Contributor Reference
4. Minting
5. Governance

Let's take a look at each one.

### Treasury Contract
The Andamio Treasury Contract locks Ada, and optionally any Cardano native asset, to be used as rewards for Contributors who make Commitments and complete Projects. In this way, the Treasury probably meets your expectations. However, this is not its most important function.

The Andamio Treasury also locks a list of Projects approved by the Organization. Once a Project is approved and listed in an Andamio Treasury, Contributors can commit to completing. Contributors can only commit to projects listed in the Treasury.

### Escrow Contracts
When a Contributor makes a Commitment to a Project, the rewards for the Project are locked in an Escrow Contract. When this happens, the Contributor's access token is also locked. This means that in a given Andamio instance, a Contributor can make only one Commitment at a time.

There can be one or many different Escrow Contracts in an Andamio Instance. There is one Escrow Contract for each unique Decision-Maker in an Andamio Instance. For example, teachers responsible for onboarding new contributors might be Decision-Makers for a PBL Course Project, while project managers might be responsible for approving contributions to an ongoing project. Across an organization, there might be many kinds of Decision Makers, each with the ability to approve the Distribution of project commitments for which they are responsible.

### Contributor Reference Contract
The Contributor Reference Contract holds a "Reference Token" for each Contributor Token. An on-chain record of contributions is stored with the Reference Token in the Contributor Reference Contract. Every time a Decision-Maker approves the completion of a commitment, the rewards are distributed to the Contributor. The Contributor Token is also unlocked and returned to the Contributor. When this happens, the data associated with the Contributor is updated.

### Minting Contracts
The rules for minting Admin, Decision-Maker, and Contributor tokens can be customized via the Andamio Minting Contracts. Organizations can choose from a set of options for minting new tokens for each Andamio Role.

### Governance Contracts
The Andamio Governance Contracts support the multi-sig capabilities of Admin and Decision Makers. Not only can Admins and Decision Makers be represented by multiple public keys, the rules for how decisions are made can be customized for each organization. This is the role of Andamio Governance Contracts. We will continue to roll out Governance Contracts over time. Please see the [Development Roadmap](/JYev1qpYSj62fnrm3aRWCA) for details.

---

## Key Andamio Interactions
Each interaction is defined by a Contract and a RBAT
1. Funding a Treasury (Treasury x Admin)
2. Governing a Treasury - Project List (Treasury x Admin)
3. Commitment (Treasury x Contributor/Learner)
4. Distribution (Escrow x Decision Maker)

### Funding a Treasury
- **Contract: Treasury**
- **Role: Admin**

The Admin can add and remove Ada and other Cardano native assets to a treasury.

### Treasury Governance: Defining the Approved Project List
- **Contract: Treasury and Escrow**
- **Role: Admin**

Organization Admins govern a Treasury by approving lists of Projects to which Contributors can Commit. For every Project, the Admins define:
1. Which Contributors can Commit to a Project
2. Which Decision-Makers will approve Project Completion

For each Decision-Maker, there is a different Escrow Contract. When a new Decision-Maker is specified, a new Escrow Contract is created.

### Commitment
- **Contracts: Treasury and Escrow**
- **Role: Contributor**

An approved Contributor can Commit to a Project listed in an Andamio Treasury. When they do, a UTxO is locked in an Escrow Contract instance corresponding to an approved Decision-Maker. The locked UTxO contains:
1. Ada rewards
2. Native asset rewards
3. The Contributor's Token

Because the Contributor token is locked, each Contributor can commit to only one project at a time.

When a Commitment is made, the rewards for the Project are locked, and can only be unlocked when they are sent to the Contributor who made the Commitment (or returned to the Treasury after a deadline passes). Note how this system is different from "bounty" architectures. In most Bounty systems, projects and tasks are publicly listed, and anyone can race to be the first to complete the work and earn a reward. This can lead to uncertainty for Contributors. What if someone spends hours working on a Project, only to find that someone else finished it first and earned the reward. With Andamio, Contributors can be certain that as long as they complete a commitment before a listed deadline, then they will earn the expected rewards. This one way that the Andamio architecture supports "People Positive" organizations.

### Distribution
- **Contracts: Escrow and Contributor Reference**
- **Role: Decision-Maker**

When a Project is complete, a Decision-Maker can approve the Distribution of rewards. When rewards are distributed, the Contributor token is also returned, and the Contributor is able to commit to the next project, continuing the process. Also at the time of distribution, the Contributor's Reference Datum is updated at the Contributor Reference Contract.

---

## All Andamio Endpoints:
Further detailed in Andamio Documentation (coming soon)

### Treasury
- `/Treasury/CommitToken`
- `/Treasury/CommitFunds`
- `/Treasury/Manage`
- `/Treasury/BurnContractToken`

### Escrow
- `Escrow/Deny`
- `Escrow/Distribute`

### Contributor Reference
- `ContribToken/AddCompletedTask`
- `ContribToken/UpdateAddress`
- `ContribToken/Use`
- `ContribToken/RemoveContributor`

### Governance
- Coming soon!

### Minting
- Coming soon!

---

## Summary
The Andamio Smart Contracts support people to become contributors to real projects, and to build a an on-chain track record along the way. Andamio is a Learning Management System (LMS) that specializes in Onboarding new contributors to an organization, but it is not limited to being an LMS. Organizations can make flexible use of Andamio to manage project contributions and to develop custom credentials for different stakeholders. To learn more, be sure to review our guide to [Andamio Use Cases](/xoRhONojQ1mbjXU1iF769A).