Raid Ops Automation

--- tags: RIPs --- # Raid Ops Automation # Phase 1: Escrow This phase focuses on adding escrow capabilities to Raid Guild. - [Phase 1 RIP Proposal](https://github.com/raid-guild/RIPs/blob/master/PROPOSALS/rip-19-escrow.md) ## Objectives 1. Ensure that client money exists and is earmarked for payment to the Guild / Raid Parties 2. Formalize the process by which clients pay the Guild / Raid Parties for services 3. Give clients additional assurances that they will receive value for their payment 4. Formalize the process for beginning a raid, which will double as the creation event for the raid-specific Series LLC ## User Stories ### As a *Raid Party Member*, I want to: - Record the details of the raid - Formally initiate a raid so I can be protected by the Series LLC - Create a new escrow account for my raid - Have 10% of funds released by the client sent automatically to the Guild as spoils - Receive remaining released funds in the raid's multisig - View the current status of a raid / escrow - Be able to Lock funds if I have a disagreement with the client ### As a *Client*, I want to: - View the details of the raid agreement/plan I made with RG - Deposit full raid payment into escrow - Release payment(s) upon agreed-upon milestones - Be able to Lock funds for arbitration when I don't think I should pay for the most recent milestone - Withdraw funds from the escrow if a milestone hasn't been completed by the safety valve withdrawal date ## Implementation Overview ### Escrow Service Provided by the LexDAO LexGuildLocker contract ([current version](https://etherscan.io/address/0x7b8c16608ceb6aa62ffc2287cf6706c322c3f967#code)) ### Airtable Raid Central ##### As a *Raid Party Member*, I want to record the details of the raid Once initial contact has been made with the client and more information about the upcoming raid is known, the raid party will enter some additional info into the airtable entry for that raid (which was originally created from the client submission). The relevant fields are as follows (new fields to create in airtable are in **bold**): - Your Name - raid party should edit the `Your Name` field from the client submission to match the true client name - Name - name of the current raid / project - Brief Summary - short description of the current raid / project - **Start Date** - **Planned End Date** - not a binding commitment - **Proposal** - Once the client has agreed to the proposal: URL to proposal / client agreement document - **Escrow Index** - received from the LexGuildLocker contract after the escrow is created ### Raid Party Multisig The Raid Party will need to provide their own multisig (Phase 2 will add capability to create one automatically for them if needed) ### Raid Party Interface - Escrow Creation This is where the raid party will create the escrow in the LexGuildLocker contract - [Figma design](https://www.figma.com/file/RuYDEBiBKs8cnR8cCg3Nqz/Raid-Guild-Escrow?node-id=156%3A155) - [web3 notes](https://hackmd.io/P2oCKVEqQbm4GMWHvE369A) ##### As a *Raid Party Member*, I want to create a new escrow account for my raid submit a transaction to register a new escrow via LexGuildLocker, with the following parameters - `Client payment address` (raid party to get from Raid Central; assumes they've already added an entry in Raid Central) - hash of `Proposal` from Raid Central - raid party multisig address - spoils destination (default = RG dao address) - payment token (ideally display only dao whitelisted tokens) - total raid payment amount - per-milestone payment amount to raid party - per-milestone payment amount to spoils - number of milestones - `termination` date (should include buffer from expected project end date) ##### As a *Raid Party Member*, I want to have 10% of funds released by the client sent automatically to the Guild as spoils this will be accomplished by the new payment splitting functionality in the LexGuildLocker contract - this is established in the per-milestone payment amounts and destinations set above ##### As a *Raid Party Member*, I want to receive remaining released funds in the raid's multisig same as above ### Raid Party Interface - Raid Initialization Once the escrow has been created, the raid party will formally initialize the raid by submitting a dao proposal, with the following parameters: - Title: - some identifier that guild members can use to look up info about the raid (for proposal-voting purposes), but that non-guild members cannot use to see client or raid details - Description: - hash of the client agreement (from `Proposal` in airtable) - Applicant: - LexGuildLocker contract address ### Raid Party Interface - Escrow Management An interface for the Raid Party to view and manage an existing raid and its associated escrow account. - [Figma design](https://www.figma.com/file/RuYDEBiBKs8cnR8cCg3Nqz/Raid-Guild-Escrow?node-id=156%3A1) ##### As a *Raid Party Member*, I want to view the current status of a raid / escrow - Client Name - `Your Name`from Raid Central - Raid Name - `Name` from Raid Central - Raid begin and planned end date - `Start Date` from Raid Central - `Planned End Date` from Raid Central - Link to raid agreement/proposal document - `Proposal` - Arbitration provider (`resolver`) - default can be LexDAO (need to find their address) - Brief raid description - `Brief Summary` - Total project payment (and currency) - look up from LexGuildLocker escrow account with this `Escrow Index` - Payment per milestone (current assumption is that they are uniform payments) - look up from LexGuildLocker escrow account with this `Escrow Index` - Safety valve withdrawal date - `termination` from LexGuildLocker escrow account with this `Escrow Index` - Next milestone - look up from LexGuildLocker escrow account with this `Escrow Index` - Extra conditional info: - If no deposit yet: Total Due to Escrow Today - If deposited - Next Amount to be released - Total Amount Released to Date - If after safety valve date: Amount Available for Withdrawal - If client or raid party has Locked: Arbitration Status ##### As a *Raid Party Member*, I want to be able to Lock funds if I have a disagreement with the client - when the member clicks `Lock`, display a modal with the following info - replace `[address]` with the address of the LexGuildLocker contract on the current network - replace `[i]` with the index of this escrow (fetched from Airtable) ``` To Lock the funds in escrow, follow these steps: 1. Go to the Gnosis Safe for the raid 2. Click "Send" and then "Contract Interaction" 3. In the "Recipient" field, paste [address] -- the address of the LexGuildLocker contract. 4. The ABI from the contract should load into the "ABI" field. If it doesn't, go copy it from Etherscan and paste it in manually. 5. Select the `lock` function from the dropdown menu 6. In the "index" parameter field, input [i] -- the index for this escrow. 7. If you have an explanation or other details related to the Lock, paste a bytes32 compatible form (e.g. a hash) into the "details" parameter field. If you don't have anything, type `0x`. 8. Click "Review", and if everything looks good, click "Submit". 9. Have a quorum of your Gnosis Safe owners sign the transaction, then execute it. 10. You can check that the status is now "locked" by looking up index [i] in the [contract](etherscan-link) on Etherscan. ``` Note: in a future phase, this could be converted into a Gnosis Safe App so that the Raid Party can manage it collectively. ### Client Interface A new web app that, from the client's perspective, looks like part of raidguild.org. - [Figma design](https://www.figma.com/file/RuYDEBiBKs8cnR8cCg3Nqz/Raid-Guild-Escrow?node-id=69%3A4) ##### As a *Client*, I want to view the details of the raid agreement/plan I made with RG - Client Name (me) - Raid Name - Raid begin and planned end date - Link to raid agreement/proposal document - Brief raid description - Total project payment (and currency) - Payment per milestone (current assumption is that they are uniform payments) - Safety valve withdrawal date (see `termination` in the LexGuildLocker contract) - Arbitration Provider - Next milestone - Extra conditional info: - If no deposit yet: Total Due to Escrow Today - If deposited - Next Amount to Release - Total Amount Released to Date - If after safety valve date: Available for Withdrawal - If client or raid party has Locked: Arbitration Status ##### As a *Client*, I want to deposit full raid payment into escrow - initiate Deposit transaction to transfer `Total project payment` to LexGuildLocker escrow account with this raid ID ##### As a *Client*, I want to release payment(s) upon agreed-upon milestones - initiate transaction to release `Next Amount to Release` from escrow account with this raid ID. Should be displayed to client after deposit has been completed. ##### As a *Client*, I want to be able to Lock funds for arbitration when I don't think I should pay for the most recent milestone - initiate transaction to `Lock` funds in escrow account with this raid ID. This option should be displayed to client after deposit has been completed. ##### As a *Client*, I want to withdraw funds from the escrow if a milestone hasn't been completed by the safety valve withdrawal date - initiate transaction to withdraw remaining funds from escrow account with this raid ID. Option should be displayed to client after `termination` date has passed. ### 🚨 Client Privacy 🚨 To protect clients from having their budgets and projects leaked to the public, client names and client project names will never be used in on-chain transactions. Instead, we will generate a unique ID for each raid and pass that ID into... - The Minion proposal that initializes the raid/escrow - The LexGuildLocker escrow account for that raid - The raid entry in Raid Central (Airtable), where it will be mapped to the actual client and project name - The raid details or client agreement document - It may be difficult to avoid including the client or project name in this document. Phase 2 will add further privacy protections for this document. Additionally, neither the raid proposal / client agreement document nor a link to the document should ever be posted on-chain. We should uses hashes instead. # Phase 2: Factory and Safe App *Definition in progress* ### Create a factory contract that... - spins up a new Gnosis Safe with raid party as owners, if needed - creates a new escrow account in the LexGuildLocker contract, with the relevant raid details and setting the new Gnosis Safe as the `provider` - The Minion proposal would now include a call to that factory contract instead of directly calling LexGuildLocker ### Create a Gnosis Safe App for the raid party to Lock funds in escrow ### Additional client privacy protections - only clients and guild members can access raid pages - ideally, use distributed storage instead of Airtable for raid details and to store the raid proposal/agreement doc. Alternative to 3box that allows private storage for contract accounts? ### Extend LexGuildLocker - to allow clients to top up their deposit - for larger/longer raids, clients may not want to (or may not be able to!) deposit the entire payment up front. Topping up would allow them to add to the escrow as the project progresses. The Raid Party would stop working if the next milestone's payment was not covered in the escrow. - to allow for variable milestone payouts - could model a raid as a `schedule = uint256[]`, where the `schedule.length` is the number of milestones and `schedule[i]` is the payment for the ith milestone. # Next version of SmartInvoice (out of scope) - dedicated step for ADR selection - register and deposit in one step - abstract away