> For the complete documentation index, see [llms.txt](https://docs.interestprotocol.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.interestprotocol.com/overview/deprecated/sui-tears/governance/dao.md).

# DAO

It allows anyone to create a DAO, submit proposals, and execute actions on-chain.

* Proposals are voted by depositing coins. 1 Coin is 1 Vote.
* DAOs only supports 1 Coin type

The idea is to send capabilities to the DAO via `sui::transfer::transfer`.

* Users can borrow the capabilities via successful proposals.
* Developers must write custom modules that pass the `AuthorizedWitness` to borrow the capability when executing proposals.
* DAO relies on open-source code to make sure the Modules that are executing proposals do what they agreed to do.

<img src="/files/lSouHjU8Xq3Pf30TTtly" alt="Proposal Life Cycle" class="gitbook-drawing">

A Successful Proposal requires:

* for\_votes > agaisnt\_votes
* for\_votes / total\_votes > quorum rate
* for\_votes >= min\_quorum\_votes

<img src="/files/a6akANdHviIqgeXMLXB7" alt="Vote Life Cycle" class="gitbook-drawing">

Each Vote struct belongs to a specific Proposal via the `vote.proposal_id` field.&#x20;

* A voter can revoke his vote and recover his `sui::coin::Coin` if the Proposal is active.
* A voter can recover his coins once the voting period ends.
* A Vote created from ProposalA cannot be used in ProposalB.

## Proposal States

### <mark style="color:blue;">**Pending:**</mark>**&#x20;Newly created proposal**<mark style="color:blue;">**.**</mark>

### <mark style="color:blue;">**Active:**</mark>**&#x20;Proposal is open for voting.**&#x20;

### <mark style="color:blue;">**Defeated:**</mark>**&#x20;The proposal did not pass.**&#x20;

### <mark style="color:blue;">**Agree:**</mark>**&#x20;The proposal passed**<mark style="color:blue;">**.**</mark>

### <mark style="color:blue;">**Queued:**</mark> The proposal was successful and now it is in a queue to be executed if it is executable. This gives time for people to adjust to the upcoming change.

### <mark style="color:blue;">**Executable:**</mark>**&#x20;It can be executed.**

### <mark style="color:blue;">**Finished:**</mark>**&#x20;The proposal has been executed.**

## Structs

### <mark style="color:blue;">**DAO**</mark>

```rust
struct Dao<phantom OTW> has key, store {
    id: UID,
    voting_delay: u64, 
    voting_period: u64,
    voting_quorum_rate: u64,
    min_action_delay: u64, 
    min_quorum_votes: u64,
    treasury: ID,
    coin_type: TypeName,
    admin_id: ID
 }
```

* **voting\_delay** - Voters must wait \`voting\_delay\` in milliseconds to start voting on new proposals.
* **voting\_period**- The voting duration of a proposal.
* **voting\_quorum\_rate**&#x20;
  * The minimum quorum rate to pass a proposal.&#x20;
  * If 50% votes are needed, then the voting\_quorum\_rate should be 5\_00\_000\_000.
  * It should be between (0, 1e9].
* **min\_action\_delay -** How long the proposal should wait before it can be executed (in milliseconds).
* **min\_quorum\_votes -** Minimum amount of votes for a Proposal to be successful even if it is higher than the against votes and the quorum rate.
* **treasury** - The \`sui::object::ID\` of the Treasury.
* **coin\_type -** The CoinType that can vote on this DAO's proposal.
* **admin\_id -** The DaoAdmin.

### <mark style="color:blue;">**Proposal**</mark>

```rust
  struct Proposal<phantom DaoWitness: drop> has key, store {
    id: UID,
    proposer: address,
    start_time: u64,
    end_time: u64,
    for_votes: u64,
    against_votes: u64,
    eta: u64,  
    action_delay: u64, 
    quorum_votes: u64, 
    voting_quorum_rate: u64, 
    hash: String,
    authorized_witness: Option<TypeName>, 
    capability_id: Option<ID>,
    coin_type: TypeName
  }
```

* **proposer -** The user who created the proposal.
* **start\_time -** When the users can start voting.
* **end\_time -** Users can no longer vote after the `end_time`.
* **for\_votes-** How many votes support the Proposal.
* **agaisnt\_votes-** How many votes disagree with the Proposal.
* **eta**
  * It is calculated by adding `end_time` and `action_delay`. It assumes the Proposal will be executed as soon as possible.
  * Estimated Time of Arrival.
* **action\_delay**
  * Time Delay between a successful Proposal `end_time` and when it is allowed to be executed.
  * It allows users who disagree with the proposal to make changes.
* **quorum\_votes -** The minimum amount of `for_votes` for a Proposal to pass.
* **voting\_quorum\_rate -** The minimum support rate for a Proposal to pass.
* **hash -** The hash of the description of this proposal.&#x20;
* **authorized\_witness**
  * The Witness that is allowed to call execute.
  * Not executable proposals do not have an authorized\_witness.
* **capability\_id**
  * The `sui::object::ID` that this proposal needs to execute.
  * Not all proposals are executable.
* **coin\_type -** The CoinType of the DAO

### <mark style="color:blue;">**Capability Request - Hot Potato**</mark>

```rust
  struct CapabilityRequest {  
    capability_id: ID,
    dao_id: ID
  }
```

* **capability\_id -** The `sui::object::ID` of the borrowed Capability.
* **dao\_id:** The DAO that owns said Capability.

### <mark style="color:blue;">**Vote**</mark>

```rust
  struct Vote<phantom DaoWitness: drop, phantom CoinType> has  key, store {
    id: UID,
    balance: Balance<CoinType>,
    proposal_id: ID,
    end_time: u64,
    agree: bool
  } 
```

* **balance -** The amount of Coin the user has used to vote for the Proposal.
* **proposal\_id:** The `sui::object::ID` of the Proposal.
* **end\_time:**
  * The end\_time of the Proposal.
  * User can redeem back his `balance` after this timestamp.
* **agree -** If it is a for or against vote.

## Interface

### <mark style="color:blue;">new</mark>

**It creates a DAO with Treasury.**&#x20;

```rust
public fun new<OTW: drop, CoinType: drop>(
    otw: OTW, 
    voting_delay: u64, 
    voting_period: u64, 
    voting_quorum_rate: u64, 
    min_action_delay: u64, 
    min_quorum_votes: u64,
    ctx: &mut TxContext
): (Dao<OTW>, DaoTreasury<OTW>)
```

* **@param otw:** A One Time Witness to ensure that the Dao is unique.
* **@param voting\_delay:** The minimum waiting period between the creation of a proposal and the voting period.
* **@param voting\_period:** The duration of the voting period.
* **@param voting\_quorum\_rate:** The minimum percentage of votes to pass a proposal. E.g. for\_votes / total\_votes. keep in mind (0, 1\_000\_000\_000]
* **@param min\_action\_delay:** The minimum delay required to execute a proposal after it passes.
* **@param min\_quorum\_votes:** The minimum votes required for a Proposal to be successful.
* **@return** Dao\<OTW>
* **@return** Treasury\<OTW>

**Aborts**

* `otw` is not a One Time Witness.
* `voting_quorum_rate` is larger than 1\_000\_000\_000
* `voting_quorum_rate` is zero.

### <mark style="color:blue;">voting\_delay</mark>

**Returns the minimum voting delay of the Dao.**

```rust
public fun voting_delay<DaoWitness>(self: &Dao<DaoWitness>): u64
```

* **@param self:** a Dao
* **@return** u64

### <mark style="color:blue;">voting\_period</mark>

**Returns the minimum voting period of the Dao.**

```rust
public fun voting_period<DaoWitness>(self: &Dao<DaoWitness>): u64
```

* **@param self:** a Dao
* **@return** u64

### <mark style="color:blue;">dao\_voting\_quorum\_rate</mark>

**Returns the minimum voting quorum rate of the Dao.**

```rust
public fun dao_voting_quorum_rate<DaoWitness>(self: &Dao<DaoWitness>): u64
```

* **@param self:** a Dao
* **@return** u64

### <mark style="color:blue;">min\_action\_delay</mark>

**Returns the minimum action delay of the Dao.**

```rust
public fun min_action_delay<DaoWitness>(self: &Dao<DaoWitness>): u64
```

* **@param self:** a Dao
* **@return** u64

### <mark style="color:blue;">min\_quorum\_votes</mark>

**Returns the minimum votes required to pass a proposal.**

```rust
public fun min_quorum_votes<DaoWitness>(self: &Dao<DaoWitness>): u64
```

* **@param self:** a Dao
* **@return** u64

### <mark style="color:blue;">treasury</mark>

**Returns the `sui::object::id` of the Dao wrapped in an `std::option`.**

```rust
public fun treasury<DaoWitness>(self: &Dao<DaoWitness>): ID
```

* **@param self:** a Dao
* **@return** ID

### <mark style="color:blue;">dao\_coin\_type</mark>

**Returns the `std::type_name` of the Dao's coin type. This is the Coin that can be used to vote on proposals.**

```rust
public fun dao_coin_type<DaoWitness>(self: &Dao<DaoWitness>): TypeName
```

* **@param self:** a Dao
* **@return** TypeName

### <mark style="color:blue;">admin</mark>

**Returns the `sui::object::ID` of Dao's admin capability. It is used to update the Dao's settings and transfer coins from the treasury.**

```rust
public fun admin<DaoWitness>(self: &Dao<DaoWitness>): ID
```

* **@param self:** a Dao
* **@return** ID

### <mark style="color:blue;">proposer</mark>

**Returns the address of the user who created the proposal.**

```rust
public fun proposer<DaoWitness: drop>(proposal: &Proposal<DaoWitness>): address
```

* **@param proposal:** The Proposal
* **@return** address

### <mark style="color:blue;">start\_time</mark>

**Returns start timestamp of the `proposal`.**

```rust
public fun start_time<DaoWitness: drop>(proposal: &Proposal<DaoWitness>): u64
```

* **@param proposal:** The Proposal.
* **@return** u64

### <mark style="color:blue;">end\_time</mark>

**Returns end timestamp of the `proposal`.**

```rust
public fun end_time<DaoWitness: drop>(proposal: &Proposal<DaoWitness>): u64
```

* **@param proposal:** The Proposal.
* **@return** u64

### <mark style="color:blue;">for\_votes</mark>

**Returns the number of votes that support this `proposal`.**

```rust
public fun for_votes<DaoWitness: drop>(proposal: &Proposal<DaoWitness>): u64
```

* **@param proposal:** The Proposal.
* **@return** u64

### <mark style="color:blue;">agaisnt\_votes</mark>

**Returns the number of votes against this `proposal`.**

```rust
public fun against_votes<DaoWitness: drop>(proposal: &Proposal<DaoWitness>): u64
```

* **@param proposal:** The {Proposal}.
* **@return** u64

### <mark style="color:blue;">eta</mark>

**Returns an estimation of when a successful proposal  will be executed.**

```rust
public fun eta<DaoWitness: drop>(proposal: &Proposal<DaoWitness>): u64
```

* **@param proposal:** The Proposal.
* **@return** u64

### <mark style="color:blue;">action\_delay</mark>

**Returns the minimum time a successful `proposal` has to wait before it can be executed.**

```rust
public fun action_delay<DaoWitness: drop>(proposal: &Proposal<DaoWitness>): u64
```

* **@param proposal:** The Proposal.
* **@return** u64

### <mark style="color:blue;">quorum\_votes</mark>

**Returns the minimum number of votes required for a successful `proposal`.**

```rust
public fun quorum_votes<DaoWitness: drop>(proposal: &Proposal<DaoWitness>): u64
```

* **@param proposal:** The Proposal.
* **@return** u64

### <mark style="color:blue;">voting\_quorum\_rate</mark>

**Returns the minimum rate for a `proposal` to pass. Formula: for\_votes / total\_votes. 100% is represented by 1\_000\_000\_000.**

```rust
public fun voting_quorum_rate<DaoWitness: drop>(proposal: &Proposal<DaoWitness>): u64
```

* **@param proposal:** The Proposal.
* **@return** u64

### <mark style="color:blue;">hash</mark>

**Returns the hash of the description of the `proposal`.**

```rust
public fun hash<DaoWitness: drop>(proposal: &Proposal<DaoWitness>): String
```

* **@param proposal:** The Proposal.
* **@return** vector\<u8>

### <mark style="color:blue;">authorized\_witness</mark>

**Returns the `std::type_name::TypeName` of the Witness that can execute the `proposal`.**

```rust
public fun authorized_witness<DaoWitness: drop>(proposal: &Proposal<DaoWitness>): Option<TypeName>
```

* **@param proposal:** The Proposal.
* **@return** TypeName

### <mark style="color:blue;">capability\_id</mark>

**Returns the `sui::object::ID` of the Capability that the `proposal` requires to execute.**

```rust
public fun capability_id<DaoWitness: drop>(proposal: &Proposal<DaoWitness>): Option<ID>
```

* **@param proposal:** The Proposal.
* **@return** Option\<ID>

### <mark style="color:blue;">coin\_type</mark>

**Returns the CoinType of the proposal. Votes must use this CoinType.**

```rust
public fun coin_type<DaoWitness: drop>(proposal: &Proposal<DaoWitness>): TypeName
```

* **@param proposal:** The Proposal.
* **@return** TypeName

### <mark style="color:blue;">balance</mark>

**Returns the number of votes.**

```rust
public fun balance<DaoWitness: drop, CoinType>(vote: &Vote<DaoWitness,  CoinType>): u64
```

* **@param vote:** The Vote\<DaoWitness, CoinType>.
* **@return** u64

### <mark style="color:blue;">proposal\_id</mark>

**Returns the Proposal `sui::object::ID`.**

```rust
public fun proposal_id<DaoWitness: drop, CoinType>(vote: &Vote<DaoWitness,  CoinType>): ID
```

* **@param vote:** The Vote\<DaoWitness, CoinType>.
* **@return** ID

### <mark style="color:blue;">vote\_end\_time</mark>

**Returns the ending timestamp of the proposal. Users can withdraw their deposited coins afterward.**

```rust
public fun vote_end_time<DaoWitness: drop, CoinType>(vote: &Vote<DaoWitness,  CoinType>): u64
```

* **@param vote:** The Vote\<DaoWitness, CoinType>.
* **@return** u64

### <mark style="color:blue;">agree</mark>

**Returns if it is a for or against vote.**

```rust
public fun agree<DaoWitness: drop, CoinType>(vote: &Vote<DaoWitness,  CoinType>): bool
```

* **@param vote:** The Vote\<DaoWitness, CoinType>.
* **@return** bool

### <mark style="color:blue;">state</mark>

**Returns the `proposal` state.**

```rust
public fun agree<DaoWitness: drop, CoinType>(vote: &Vote<DaoWitness,  CoinType>): bool
```

* **@param vote:** The Vote\<DaoWitness, CoinType>.
* **@return** u8

### <mark style="color:blue;">propose</mark>

**Creates a Proposal.**

```rust
public fun propose<DaoWitness: drop>(
    dao: &mut Dao<DaoWitness>,
    c: &Clock,
    authorized_witness: Option<TypeName>,
    capability_id: Option<ID>,
    action_delay: u64,
    quorum_votes: u64,
    hash: String,
    ctx: &mut TxContext    
 ): Proposal<DaoWitness>
```

* **@param** dao: The Dao.
* **@param c:** The shared `sui::clock::Clock` object.
* **@param authorized\_witness:** The Witness required to execute this proposal.
* **@param capability\_id:** The `sui::object::ID` of the Capability that this proposal needs to be executed. If a proposal is not executable pass `option::none()`
* **@param action\_delay:** The minimum waiting period for a successful Proposal to be executed.
* **@param quorum\_votes:** The minimum waiting period for a successful Proposal to be executed.
* **@param hash:** The hash of the proposal's description.
* **@return** Proposal\<DaoWitness>

**Abort**

* `action_delay` < `dao.min_action_delay`.
* `quorum_votes` < `dao.min_quorum_votes`.
* `hash` is empty.

### <mark style="color:blue;">cast\_vote</mark>

**Allows a user to use coins to vote for a `proposal`, either against or for depending on `agree`.**

```rust
  public fun cast_vote<DaoWitness: drop, CoinType>(
    proposal: &mut Proposal<DaoWitness>,
    c: &Clock,
    stake: Coin<CoinType>,
    agree: bool,
    ctx: &mut TxContext
  ): Vote<DaoWitness, CoinType>
```

* **@param proposal:** The proposal the user is voting for.
* **@param c:** The shared `sui::clock::Clock` object.
* **@param stake:** The coin that the user will deposit to vote.
* **@param agree:** Determines if the vote is for or against..
* **@return** Vote\<DaoWitness, CoinType>

**Aborts**

* if the proposal is not `ACTIVE`
* if the `stake` type does not match the `proposal.coin_type`
* if a user tries to vote with a zero coin `stake`.

### <mark style="color:blue;">change\_vote</mark>

**Allows a user to change his vote for a `proposal`.**

```rust
public fun change_vote<DaoWitness: drop, CoinType>(
    proposal: &mut Proposal<DaoWitness>,
    vote: &mut Vote<DaoWitness,  CoinType>,
    c: &Clock,
    ctx: &mut TxContext
 )
```

* **@param proposal:** The proposal the user is voting for.
* **@param vote:** The vote that will be changed.
* **@param c:** The shared `sui::clock::Clock` object.

**Aborts**

* if the proposal is not `ACTIVE`
* if the `vote` does not belong to the `proposal`.

### <mark style="color:blue;">revoke\_vote</mark>

**Allows a user to revoke his vote for a `proposal` and get his coin back.**

```rust
public fun revoke_vote<DaoWitness: drop, CoinType>(
    proposal: &mut Proposal<DaoWitness>,
    vote: Vote<DaoWitness, CoinType>,
    c: &Clock,
    ctx: &mut TxContext    
 ): Coin<CoinType>
```

* **@param proposal:** The proposal the user is voting for.
* **@param vote:** The vote that will be destroyed.
* **@param c:** The shared `sui::clock::Clock` object.
* **@return** Coin\<CoinType>

**Aborts**

* if the proposal is not `ACTIVE`
* if the `vote` does not belong to the `proposal`.

### <mark style="color:blue;">unstake\_vote</mark>

**Allows a user to unstake his vote to get his coins back after the `proposal` has ended.**

```rust
public fun unstake_vote<DaoWitness: drop, CoinType>(
    proposal: &Proposal<DaoWitness>,
    vote: Vote<DaoWitness, CoinType>,
    c: &Clock,
    ctx: &mut TxContext      
): Coin<CoinType>
```

* **@param proposal:** The proposal the user is voting for.
* **@param vote:** The vote that will be destroyed.
* **@param c:** The shared `sui::clock::Clock` object.
* **@return** Coin\<CoinType>

**Aborts**

* if the proposal has not ended.
* if the `vote` type does not match the `proposal.id`

### <mark style="color:blue;">queue</mark>

**Allows a successful `proposal` to be queued.**

```rust
public fun queue<DaoWitness: drop>(
    proposal: &mut Proposal<DaoWitness>, 
    c: &Clock
 )
```

* **@param proposal:** The proposal the user is voting for.
* **@param c:** The shared `sui::clock::Clock` object.

**Aborts**

* if the `proposal` state is not AGREED.

### <mark style="color:blue;">execute</mark>

**Executes a `proposal`.**

```rust
public fun execute<DaoWitness: drop, AuhorizedWitness: drop, Capability: key + store>(
    dao: &mut Dao<DaoWitness>,
    proposal: &mut Proposal<DaoWitness>, 
    _: AuhorizedWitness,
    receive_ticket: Receiving<Capability>,
    c: &Clock
): (Capability, CapabilityRequest)
```

* **@param dao:** The Dao.
* **@param proposal:** The proposal that will be executed.
* **@param \_:** The witness that is authorized to borrow the Capability.
* **@param receive\_ticket:** A receipt struct to borrow the Capability.
* **@param c:** The shared `sui::clock::Clock` object.
* **@return Capability** required to execute the proposal.
* **@return CapabilityRequest** A hot potato to ensure that the borrower returns the Capability to the `dao`.

**Aborts**

* if the `proposal` state is not EXECUTABLE
* if there has not passed enough time since the `end_time`
* if the Authorized Witness does not match the `proposal.authorized_witness`.
* if the borrowed capability does not match the `proposal.capability_id`.

### <mark style="color:blue;">return\_capability</mark>

**Returns the borrowed `cap` to the `dao`.**

```rust
public fun return_capability<DaoWitness: drop, Capability: key + store>(dao: &Dao<DaoWitness>, cap: Capability, receipt: CapabilityRequest)
```

* **@param dao:** The Dao.
* **@param cap:** The capability that will be returned to the `dao`.
* **@param receipt:** The request hot potato.

**Aborts**

* if the user tries to return the `cap` to the wrong `dao`
* if there user tries to return the wrong `cap`

### <mark style="color:blue;">update\_dao\_config</mark>

**Updates the configuration settings of the `dao`.**

```rust
public fun update_dao_config<DaoWitness: drop>(
    dao: &mut Dao<DaoWitness>,
    _: &DaoAdmin<DaoWitness>,
    voting_delay: Option<u64>, 
    voting_period: Option<u64>, 
    voting_quorum_rate: Option<u64>, 
    min_action_delay: Option<u64>, 
    min_quorum_votes: Option<u64>
)
```

* **@param dao:** The Dao.
* **@param \_:** Immutable reference to the DaoAdmin.
* **@param voting\_delay:** The minimum waiting period between the creation of a proposal and the voting period.
* **@param voting\_period:** The duration of the voting period.
* **@param voting\_quorum\_rate:** The minimum percentage of votes. E.g. for\_votes / total\_votes. Range = (0, 1\_000\_000\_000]
* **@param min\_action\_delay:** The delay required to execute a proposal after it passes.
* **@param min\_quorum\_votes:** The minimum votes required for a {Proposal} to be successful.

**Aborts**

* if the user tries to return the `cap` to the wrong `dao`
* if there user tries to return the wrong `cap`