SmartInvoiceXYZ · benedictvscriticus · Jan 13, 2025 · Jan 5, 2025 · Jan 5, 2025 · Jan 6, 2025
diff --git a/public/guides/escrowGuide/escrow_architecture.png b/public/guides/escrowGuide/escrow_architecture.png
diff --git a/public/guides/escrowGuide/escrow_milestones.png b/public/guides/escrowGuide/escrow_milestones.png
diff --git a/public/guides/escrowGuide/milestone_creation.gif b/public/guides/escrowGuide/milestone_creation.gif
diff --git a/public/guides/escrowGuide/release_milestone.gif b/public/guides/escrowGuide/release_milestone.gif
diff --git a/public/guides/escrowGuide/review_submit.png b/public/guides/escrowGuide/review_submit.png
diff --git a/public/guides/escrowGuide/safety_valve.png b/public/guides/escrowGuide/safety_valve.png
diff --git a/src/assets/images/escrow_architecture.png b/src/assets/images/escrow_architecture.png
diff --git a/src/assets/images/escrow_milestones.png b/src/assets/images/escrow_milestones.png
diff --git a/src/assets/images/milestone_creation.gif b/src/assets/images/milestone_creation.gif
diff --git a/src/assets/images/release_milestone.gif b/src/assets/images/release_milestone.gif
diff --git a/src/assets/images/review_submit.png b/src/assets/images/review_submit.png
diff --git a/src/assets/images/safety_valve.png b/src/assets/images/safety_valve.png
diff --git a/src/content/docs/guides/builder-escrow-proposal.mdx b/src/content/docs/guides/builder-escrow-proposal.mdx
@@ -0,0 +1,146 @@
+---
+id: builder-escrow-proposal
+title: How to Create an Escrow Proposal
+---
+
+## Overview
+
+The Escrow Builder Proposal enables Nouns Builders to create proposals for milestone-based grants that enhances accountability and transparency within Nouns Builder DAOs. This upgrade leverages Smart Invoice's escrow and arbitration features, empowering DAOs to proactively manage funds tied to deliverables.
+
+## Key Terms
+
+- **`Escrow Proposal`**: A proposal type allowing funds to be allocated and released based on defined milestones.
+- **`Safety Valve`**: Ensures funds are not stuck in escrow and can be withdrawn after the safety valve date passes.
+- **`Milestone`**: A defined deliverable or objective that triggers the release of a portion of escrowed funds.
+- **`Arbitration`**: The resolution process for disputes regarding milestones or fund releases.
+- **`Proposal Submission`**: The process of creating, reviewing, and submitting an Escrow Proposal.
+- **`Attestation`**: The process of formally verifying delegation authority using the Ethereum Attestation Service (EAS).
+- **`Delegation`**: The act of assigning fund release authority to a "Client" address that is different from the DAO address.
+- **`Release`**: The action of transferring funds from escrow upon the successful completion of a milestone.
+- **`Client`**: The entity responsible for managing and withdrawing funds from the escrow after milestones are met.
+- **`Recipient`**: The wallet address or entity receiving funds allocated for milestones.
+
+---
+
+## Creating an Escrow Proposal
+
+Functionality Funds are secured in escrow and released upon milestone completion. Milestone releases can be requested under the milestone management page.
+
+### Step 1: Select the Escrow Proposal Type
+
+1. Navigate to the **`Activity`** section in the Nouns Builder dashboard.
+2. Click **`Create Proposal`** and choose **`Escrow Milestones`** from the proposal type menu.
+
+![Activity Section Proposal Types](../../../assets/images/escrow_milestones.png)
+
+### Step 2: Add Recipient and Safety Valve
+
+1. Enter the recipient's wallet address (e.g., `vitalik.eth`).
+2. Set a **`safety valve date`** to ensure funds are locked for at least 30 days.
+   - Use the calendar picker to select the appropriate date.
+   - Ensures that funds are not stuck in escrow and can be withdrawn after the safety valve date passed. Once the selected Safety Valve Date is passed, the client can withdraw the funds out of the escrow and back into their own wallet. The safety valve must be a minimum of 30 days after invoice creation date or the last milestone date, whatever is later.
+
+![Safety Valve Date](../../../assets/images/safety_valve.png)
+
+### Step 3: Define Milestones
+
+1. User can add and configure as many milestones as needed by using the `Create Milestone` functionality. Configuration options include `amount`, `title`, `description`, `delivery date`, and optional `media uploads`. For each milestone, provide:
+   - **`Title`**: A descriptive name for the milestone (e.g., "Milestone 1").
+   - **`Description`**: Details about the milestone deliverables.
+   - **`Delivery Date`**: The expected completion date for the milestone.
+   - **`Amount`**: The allocated funds for the milestone.
+   - Optional: Upload media files to enhance milestone descriptions.
+2. Add additional milestones as needed. The **Total Escrow Amount** will automatically update.
+3. The appropriate arbitration provider is selected automatically and displayed in the top right corner of the proposal builder page.
+   - Internal arbitration by Smart Invoice for amounts below $1,000.
+   - Kleros arbitration for amounts exceeding $1,000.
+
+![Milestone Creation](../../../assets/images/milestone_creation.gif)
+
+### Step 4: Review and Submit
+
+1. Ensure the **`Safety Valve Date`** is at least 30 days after the final milestone.
+2. Scroll to the end of the page and select **`Add Transaction to Queue`** and wait for the confirmation **"`n` transactions queued"**.
+3. Once your transaction was queued, select **`Continue`**. You are being redirected to the next screen.
+4. Add a **`Proposal Title`** and **`Summary`** to add the actual proposal content.
+3. Click **`Submit Proposal`** to finalize the submission.
+
+Add a title and a proposal summary according to the Nouns Builder proposal template. Refer to the [proposal writing guide](https://paragraph.xyz/@nounishprof/howtoprop) and the [Nouns Builder proposal template](https://hackmd.io/@profwerder/builderdaotemplate) for further information.
+
+![Review and Submit Proposal](../../../assets/images/review_submit.png)
+
+### Release Milestone Flow
+
+Milestones can be released using the "Release Milestone" button. This action moves funds allocated to the milestone from escrow to the recipient's wallet. DAO members can vote on the milestone release proposal before execution.
+
+1. Navigate to the **Proposal Details** page to review the associated milestones.
+2. Select the milestone to release and click **"Release Milestone"**.
+3. You are being redirected to the proposal screen. Describe your deliverables and substantiate the release. Then submit the transaction.
+3. DAO voting or multisig approval is required before funds are transferred.
+
+![Milestone Release Flow](../../../assets/images/release_milestone.gif)
+
+---
+
+## Delegating Release Authority
+
+Delegation streamlines milestone management by allowing DAOs to assign fund release authority to specific entities. Attestation for this process occurs separately from the proposal builder, enabling predefined entities to securely confirm their roles and ensure transparent governance.
+
+Attestations can be made by the following entities in this order of priority
+
+1. **Builder DAO Governor (`0x6623d2a90429475ed9c8a4b613c4b5b4f8428cee`)**
+2. **Builder DAO Operations Multisig (`0x58eAEfBEd9EEFbC564E302D0AfAE0B113E42eAb3`)**
+3. **Smart Invoice Multisig (`0x503a5161D1c5D9d82BF35a4c80DA0C3Ad72d9244`)**
+
+### How Attestations Use EAS (Ethereum Attestation Service)
+
+This separate attestation flow ensures that all delegations are securely recorded, verifiable, and aligned with DAO governance protocols. If additional attestations or attesters are required for a DAO on Nouns.Builder, DAOs should contact Builder DAO or the SmartInvoice Team for assistance.
+
+#### Attestation Flow
+- Each attestation follows the schema ID `0x1289c5f988998891af7416d83820c40ba1c6f5ba31467f2e611172334dc53a0e`.
+- EAS verifies attestations to confirm delegation authority.
+- Users can query the EAS registry to view or verify attestations for a specific DAO address.
+
+---
+## Further Reading
+
+### FAQ
+
+#### Why is a safety valve required?
+
+The safety valve locks funds for a minimum of 30 days, ensuring sufficient time for review and dispute resolution.
+
+#### Can this proposal type handle non-milestone grants?
+
+While you can create proposals with only one milestone, for direct release proposals you should choose the appropriate proposal type.
+
+#### What happens during a dispute?
+
+- For amounts below $1,000, disputes are resolved internally by Smart Invoice.
+- For amounts exceeding $1,000, disputes are escalated to Kleros for arbitration.
+- To create a dispute, you first must locate the escrow using its address.
+    - Then visit `https://app.smartinvoice.xyz/invoice/base/ESCROW_ADDRESS`.
+    - Replace `ESCROW_ADDRESS` with the relevant escrow address.
+    - Connect your **Recipient** wallet and click **`Lock funds`**.
+
+---
+
+### Architecture
+
+![Escrow Architecture](../../../assets/images/escrow_architecture.png)
+
+---
+
+### Links
+
+- [Smart Invoice Documentation](https://www.smartinvoice.xyz/)
+- [Nouns Builder Documentation Repository](https://github.com/SmartInvoiceXYZ/nouns-builder-docs)
+- [Smart Invoice App](https://app.smartinvoice.xyz/)
+- [Kleros Arbitration Policy](https://docs.smartinvoice.xyz/arbitration/kleros-arbitration)
+- [Smart Invoice Arbitration Infrastructure](https://docs.smartinvoice.xyz/arbitration/arbitration-infra)
+
+### Support
+
+Smart Invoice provides dedicated support for Nouns Builder DAOs. Users can contact Smart Invoice via the support channel with a 24-hour response time for any issues related to escrow, arbitration, or proposal submission.
+
+For additional support, reach out via [Discord](https://discord.gg/eDb4frFuym) or email at [[email protected]](mailto:[email protected]).