> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usmewe.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Proposals

> Creating and voting on governance proposals

# Proposals

Learn how to create, vote on, and execute governance proposals.

## Proposal Types

<CardGroup cols={2}>
  <Card title="Parameter Change" icon="sliders">
    Modify protocol settings like interest rates, fees, or limits
  </Card>

  <Card title="Contract Upgrade" icon="arrow-up">
    Upgrade smart contract implementations
  </Card>

  <Card title="Treasury Spend" icon="wallet">
    Allocate funds for development, marketing, or rewards
  </Card>

  <Card title="Emergency Action" icon="bolt">
    Critical fixes that bypass normal timelock
  </Card>
</CardGroup>

## Creating a Proposal

### Requirements

| Requirement          | Value                             |
| -------------------- | --------------------------------- |
| Minimum voting power | 1,000 effective votes             |
| Self-delegation      | Must be active                    |
| Cool-down            | 7 days between proposals per user |

### Step 1: Draft Your Proposal

Create a detailed proposal document:

```markdown theme={null}
# [Title]: Brief Description

## Summary
One paragraph explaining the change.

## Motivation
Why is this change needed? What problem does it solve?

## Specification
Technical details of the change:
- Contract: TrustVault
- Function: updateInterestRate(uint256)
- New value: 500 (5%)

## Security Considerations
Potential risks and mitigations.

## Timeline
When should this be implemented?
```

### Step 2: Community Discussion

1. Post on governance forum
2. Share in Discord #governance channel
3. Gather feedback for 3-7 days
4. Refine proposal based on input

### Step 3: Submit On-Chain

```typescript theme={null}
const governor = new ethers.Contract(GOVERNOR_ADDRESS, GovernorABI, signer);

// Prepare proposal
const targets = [TRUST_VAULT_ADDRESS];
const values = [0];
const calldatas = [
  trustVault.interface.encodeFunctionData('updateInterestRate', [500])
];
const description = "Proposal #5: Reduce base interest rate to 5%";

// Submit proposal
const tx = await governor.propose(
  targets,
  values,
  calldatas,
  description,
  0, // ProposalType.ParameterChange
  "QmIPFSHash..." // Link to full proposal
);

const receipt = await tx.wait();
const proposalId = receipt.events[0].args.proposalId;
```

## Voting

### Voting Period

| Phase         | Duration |
| ------------- | -------- |
| Voting delay  | 1 day    |
| Voting period | 7 days   |
| Timelock      | 48 hours |

### How to Vote

```typescript theme={null}
// Vote options: 0 = Against, 1 = For, 2 = Abstain
await governor.castVote(proposalId, 1); // Vote For

// Vote with reason
await governor.castVoteWithReason(
  proposalId,
  1,
  "This will improve capital efficiency"
);
```

### Via UI

1. Go to **Governance** in the app
2. Find the active proposal
3. Click **Vote**
4. Select For, Against, or Abstain
5. Confirm transaction

## Proposal States

```
┌─────────────────────────────────────────────────────────────────┐
│  PROPOSAL LIFECYCLE                                             │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Pending ──► Active ──► Succeeded ──► Queued ──► Executed      │
│     │          │            │                                   │
│     │          │            └──► Defeated (not enough votes)    │
│     │          │                                                │
│     │          └──► Defeated (quorum not met)                   │
│     │                                                           │
│     └──► Cancelled (by proposer)                                │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

| State         | Description                         |
| ------------- | ----------------------------------- |
| **Pending**   | Waiting for voting delay (1 day)    |
| **Active**    | Voting in progress (7 days)         |
| **Canceled**  | Cancelled by proposer               |
| **Defeated**  | Failed to reach quorum or majority  |
| **Succeeded** | Passed, ready for queue             |
| **Queued**    | In timelock (48 hours)              |
| **Executed**  | Successfully executed               |
| **Expired**   | Not executed within timelock window |

## Execution

After a proposal succeeds and the timelock passes:

```typescript theme={null}
// Execute the proposal
await governor.execute(
  targets,
  values,
  calldatas,
  ethers.id(description)
);
```

<Note>
  Anyone can execute a successful proposal after the timelock period.
</Note>

## Active Proposals

<Info>
  No active proposals. Be the first to shape usmewe's future!
</Info>

| ID | Title | Status | Votes For | Votes Against | Ends |
| -- | ----- | ------ | --------- | ------------- | ---- |
| -  | -     | -      | -         | -             | -    |

## Past Proposals

| ID | Title | Result | Date |
| -- | ----- | ------ | ---- |
| -  | -     | -      | -    |

## Best Practices

<AccordionGroup>
  <Accordion title="Clear Title" icon="heading">
    Use format: "\[Category] Brief Description"

    Good: "\[Parameter] Reduce base interest rate to 5%"
    Bad: "Interest rate change"
  </Accordion>

  <Accordion title="Detailed Specification" icon="list">
    Include exact function calls, parameters, and expected outcomes.
  </Accordion>

  <Accordion title="Community Discussion" icon="comments">
    Get feedback before submitting. Rushed proposals often fail.
  </Accordion>

  <Accordion title="Security Analysis" icon="shield">
    Consider attack vectors and edge cases. Get technical review.
  </Accordion>

  <Accordion title="Realistic Timeline" icon="calendar">
    Don't request emergency for non-emergencies.
  </Accordion>
</AccordionGroup>

## Cancelling a Proposal

Proposers can cancel their proposal before execution:

```typescript theme={null}
await governor.cancel(
  targets,
  values,
  calldatas,
  ethers.id(description)
);
```

<Warning>
  You cannot cancel after execution has started.
</Warning>

## API Reference

```bash theme={null}
# Get all proposals
curl -X GET "https://api.usmewe.com/v1/governance/proposals"

# Get specific proposal
curl -X GET "https://api.usmewe.com/v1/governance/proposals/{id}"

# Get user's votes
curl -X GET "https://api.usmewe.com/v1/governance/votes/me" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

## Related

<CardGroup cols={2}>
  <Card title="Voting Power" icon="bolt" href="/governance/voting-power">
    Calculate your voting power
  </Card>

  <Card title="Governance Contract" icon="file-contract" href="/smart-contracts/governance">
    Technical implementation
  </Card>
</CardGroup>