Skip to content

Commit f19e2f2

Browse files
whoabuddywhoabuddy
committed
docs: Add documentation for treasury and direct-execute traits
1 parent 0c711b1 commit f19e2f2

File tree

2 files changed

+251
-0
lines changed

2 files changed

+251
-0
lines changed

‎docs/dao/traits/direct-execute.md

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# Direct Execute Trait
2+
3+
The direct execute trait defines the interface for managing and executing arbitrary proposals through token-weighted voting.
4+
5+
## Interface
6+
7+
```clarity
8+
(define-trait direct-execute (
9+
(set-protocol-treasury (<treasury>) (response bool uint))
10+
(set-voting-token (<ft-trait>) (response bool uint))
11+
(create-proposal (<proposal> <ft-trait>) (response bool uint))
12+
(vote-on-proposal (<proposal> <ft-trait> bool) (response bool uint))
13+
(conclude-proposal (<proposal> <treasury> <ft-trait>) (response bool uint))
14+
))
15+
```
16+
17+
## Functions
18+
19+
### Configuration
20+
21+
#### set-protocol-treasury
22+
Sets the treasury contract for proposal execution.
23+
- Parameters:
24+
- `treasury`: Treasury contract implementing treasury trait
25+
- Access: DAO/extension only
26+
- Returns: Success/failure response
27+
28+
#### set-voting-token
29+
Sets the SIP-010 token used for voting.
30+
- Parameters:
31+
- `token`: SIP-010 token contract
32+
- Access: DAO/extension only
33+
- Returns: Success/failure response
34+
35+
### Proposal Management
36+
37+
#### create-proposal
38+
Creates new proposal for voting.
39+
- Parameters:
40+
- `proposal`: Proposal contract
41+
- `token`: Voting token contract
42+
- Access: Public
43+
- Returns: Success/failure response
44+
45+
#### vote-on-proposal
46+
Casts vote on proposal.
47+
- Parameters:
48+
- `proposal`: Proposal contract
49+
- `token`: Voting token contract
50+
- `vote`: True for yes, false for no
51+
- Access: Token holders
52+
- Returns: Success/failure response
53+
54+
#### conclude-proposal
55+
Concludes voting and executes if passed.
56+
- Parameters:
57+
- `proposal`: Proposal contract
58+
- `treasury`: Treasury contract
59+
- `token`: Voting token contract
60+
- Access: Public
61+
- Returns: Success/failure response
62+
63+
## Implementation Requirements
64+
65+
1. Track proposal status and votes
66+
2. Calculate voting power from token balances
67+
3. Enforce voting period
68+
4. Require minimum quorum
69+
5. Execute proposals atomically
70+
71+
## Usage Pattern
72+
73+
Implementations should:
74+
1. Verify proposal validity
75+
2. Track voting status
76+
3. Calculate results accurately
77+
4. Handle execution safely
78+
79+
Example implementation:
80+
```clarity
81+
(define-public (vote-on-proposal
82+
(proposal <proposal>)
83+
(token <ft-trait>)
84+
(vote bool)
85+
)
86+
(let (
87+
(voting-power (unwrap! (get-balance token tx-sender) ERR_ZERO_POWER))
88+
)
89+
;; Verify voting period
90+
(asserts! (is-voting-active proposal) ERR_VOTING_ENDED)
91+
92+
;; Record vote
93+
(try! (record-vote proposal tx-sender vote voting-power))
94+
95+
;; Log vote
96+
(print {
97+
notification: "vote-cast",
98+
payload: {
99+
proposal: proposal,
100+
voter: tx-sender,
101+
power: voting-power,
102+
vote: vote
103+
}
104+
})
105+
106+
(ok true)
107+
)
108+
)
109+
```

‎docs/dao/traits/treasury.md

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
# Treasury Trait
2+
3+
The treasury trait defines the interface for managing multiple asset types including STX, SIP-009 NFTs, and SIP-010 FTs.
4+
5+
## Interface
6+
7+
```clarity
8+
(define-trait treasury (
9+
(allow-asset (principal bool) (response bool uint))
10+
(deposit-stx (uint) (response bool uint))
11+
(deposit-ft (<ft-trait> uint) (response bool uint))
12+
(deposit-nft (<nft-trait> uint) (response bool uint))
13+
(withdraw-stx (uint principal) (response bool uint))
14+
(withdraw-ft (<ft-trait> uint principal) (response bool uint))
15+
(withdraw-nft (<nft-trait> uint principal) (response bool uint))
16+
(delegate-stx (uint principal) (response bool uint))
17+
(revoke-delegate-stx () (response bool uint))
18+
))
19+
```
20+
21+
## Functions
22+
23+
### Asset Management
24+
25+
#### allow-asset
26+
Controls which assets can be deposited/withdrawn.
27+
- Parameters:
28+
- `token`: Asset contract principal
29+
- `enabled`: Whether to allow the asset
30+
- Access: DAO/extension only
31+
- Returns: Success/failure response
32+
33+
### Deposits
34+
35+
#### deposit-stx
36+
Deposits STX to treasury.
37+
- Parameters:
38+
- `amount`: Amount in microSTX
39+
- Access: Public
40+
- Returns: Success/failure response
41+
42+
#### deposit-ft
43+
Deposits SIP-010 tokens.
44+
- Parameters:
45+
- `ft`: Token contract
46+
- `amount`: Token amount
47+
- Access: Public
48+
- Returns: Success/failure response
49+
50+
#### deposit-nft
51+
Deposits SIP-009 NFT.
52+
- Parameters:
53+
- `nft`: NFT contract
54+
- `id`: Token ID
55+
- Access: Public
56+
- Returns: Success/failure response
57+
58+
### Withdrawals
59+
60+
#### withdraw-stx
61+
Withdraws STX from treasury.
62+
- Parameters:
63+
- `amount`: Amount in microSTX
64+
- `recipient`: Recipient address
65+
- Access: DAO/extension only
66+
- Returns: Success/failure response
67+
68+
#### withdraw-ft
69+
Withdraws SIP-010 tokens.
70+
- Parameters:
71+
- `ft`: Token contract
72+
- `amount`: Token amount
73+
- `recipient`: Recipient address
74+
- Access: DAO/extension only
75+
- Returns: Success/failure response
76+
77+
#### withdraw-nft
78+
Withdraws SIP-009 NFT.
79+
- Parameters:
80+
- `nft`: NFT contract
81+
- `id`: Token ID
82+
- `recipient`: Recipient address
83+
- Access: DAO/extension only
84+
- Returns: Success/failure response
85+
86+
### Stacking
87+
88+
#### delegate-stx
89+
Delegates STX for PoX stacking.
90+
- Parameters:
91+
- `amount`: Max amount to delegate
92+
- `to`: Delegate address
93+
- Access: DAO/extension only
94+
- Returns: Success/failure response
95+
96+
#### revoke-delegate-stx
97+
Revokes STX delegation.
98+
- Parameters: None
99+
- Access: DAO/extension only
100+
- Returns: Success/failure response
101+
102+
## Implementation Requirements
103+
104+
1. Maintain allowlist of accepted assets
105+
2. Verify asset transfers succeed
106+
3. Enforce DAO/extension-only access for protected functions
107+
4. Track asset balances accurately
108+
5. Handle PoX delegation safely
109+
110+
## Usage Pattern
111+
112+
Implementations should:
113+
1. Use allowlist for asset control
114+
2. Verify transfer success
115+
3. Emit comprehensive logs
116+
4. Handle errors gracefully
117+
118+
Example implementation:
119+
```clarity
120+
(define-public (deposit-ft (ft <ft-trait>) (amount uint))
121+
(begin
122+
;; Check allowlist
123+
(asserts! (is-allowed-asset (contract-of ft)) ERR_UNKNOWN_ASSET)
124+
125+
;; Transfer tokens
126+
(try! (contract-call? ft transfer
127+
amount tx-sender TREASURY none))
128+
129+
;; Log deposit
130+
(print {
131+
notification: "deposit-ft",
132+
payload: {
133+
token: (contract-of ft),
134+
amount: amount,
135+
sender: tx-sender
136+
}
137+
})
138+
139+
(ok true)
140+
)
141+
)
142+
```

0 commit comments

Comments
 (0)