# Introducing %fund A sovereign tool for crypto-economic activity in the world of atoms Welcome to the `%fund` application documentation. While we aim for the initial experience with `%fund` to be self-explanatory through intuitive UX flows and an informative UI, `%fund` is not just a doomscrolling consumer product, but a powerful tool for sovereign crypto-economic activity. Depending on how you want to make use of this tool we are providing, it may serve you well to read this documentation and become a proper power user. In short, there are three roles you may play in the `%fund` product: * [Project funder](/user-guides/project-funders) * [Project worker](/user-guides/project-workers-wip) * [Trusted oracle](/user-guides/trusted-oracles-wip) Each of these roles come with with their own benefits and obligations. If you have any questions not answered in this documentation, feel free to reach out at or [join our group on urbit](https://tlon.network/lure/~tocwex/syndicate-public). ### Installing %fund If you already have an urbit, it is straight-forward to install `%fund` for the first time. Just login to your urbit and on your homepage (aka `%landscape`) click the top navigation where it says "Get Apps". Where it says "Browse by Developer ID or Shortcode", type in `~tocwex`, wait a moment for your urbit to connect to our distribution point, and then click the entry for "Fund." The application will download and you should have the app tile available on your homepage shortly. Or, if you are comfortable in the dojo, just run: ``` |install ~tocwex %fund ``` If you don't have an urbit yet, see our page on [getting an urbit](/system-guides/getting-an-urbit) or visit the homepage of [tocwexsyndicate.com](https://tocwexsyndicate.com) and sign up your email. > **NOTICE:** `%fund` is currently in mainnet beta. We will continue rolling out additional features over the coming weeks and months. If you encounter an issue, first "give it a second" and then refresh the page. If that doesn't properly update your state, please let us know and we will help you fix your issue. If you are so inclined, please also feel free to [submit an issue on GitHub](https://github.com/tocwex/fund/issues). For details about the smart contracts backing this application, read the this page [on security and sovereignty](/system-guides/on-security-and-sovereignty-wip). # Project Discovery Finding and sharing projects with peers While `%fund` offers many standard affordances of centralized crowdfunding platforms (comments with your contributions, refunds for non-completed work, etc), the decentralized nature of the system means that discovery of project campaigns occurs from *your peers*, not from a centralized repository controlled by `~tocwex.syndicate`. The basic mechanic for discovering projects is to have one of your `%pals` share it with you. Or of course for you to share it with your `%pals`. ### Sharing projects as a project worker If you are the project worker, the visibility of the project is up to you. When a project is first released, by sending a service request to your desired trusted oracle, it's visibility set as "unlisted". In this state, your trusted oracle can view it on their urbit from within %fund, and you can share the URL to any other viewers you may want to see or contribute to the project. Someone with the URL can view, login to (using eAuth), and follow your project's funding campaign, but it will not be easily gossiped across the network. If you want it to be discoverable throughout the Urbit Network, by other users of `%fund`, you must "publicize" it. To do that, go to the project page and search for the "eye" icon in the action bar (next to the big "Contribute" button). Click the eye, read the confirmation message and press "publicize".

The "Publicize" button and confrimation in the action bar

This action does two things: 1. It shares the project to all of *your* `%pals` so it will show up in the "Discover" tab of their `%fund` application. 2. It adds the project to *your* profile, indicating to any other ships that come across the project that you are ok with it being re-publicized to *their* `%pals`. Note, this doesn't automagically propogate your project across the *entire* network. Why? Because the best way to crowdfund is through the implied recommendations and explicit word-of-mouth of your community. Want your campaign to get more visibility? Talk to your `%pals`. Ask them what they think. Ask them to fund your project. And of course ask them to re-publicize it—if they think it is deserving of the honor. ### Re-publicizing a project you follow While the project worker may be the primary party responsible for publicizing their project, they aren't the only ones that can share opportunities across the network. If a project worker has "publicized" their campaign, any follower of the project can re-publicize it to the follower's respective set of %pals. If a project you are following (either as a viewer, funder, or oracle) has been publicized, you will find the "eye" icon in the action bar; after clicking you will get the chance to confirm you want to to share. ### The %pals dependency This project discovery feature relies on the `%pals` application in order to function. If you onboarded via [tocwexsyndicate.com](https://tocwexsyndicate.com) you already have `%pals` and do not need to take additional action. If some some reason you do not have `%pals`, it can be downloaded from `~paldev.` To install from the dojo, just run: `|install ~paldev %pals` In the event you have connectivity issues with `~paldev,` the original distributor of the application, we maintain a distribution version on `~tocwex` that mirrors that of `~paldev`. Just swap the Urbit IDs in the command and re-run it. # Project funders Tips for being a project funder financially backing projects. Project funders are able to pledge support and settle outstanding pledges on proposals for human action they wish to see in the world, as well as receive refunds for fulfilled pledges associated with work that was not completed according to the project terms. ## Funding a project Most users first experience with `%fund` will be in contributing funds to a project that they would like to see completed. There are three main ways for you, as a project funder, to interact with these projects: directly [from the clearweb](#from-the-clearweb), [using "eAuth"](#using-eauth) login functionality, or [via your urbit](#from-your-own-urbit)'s sovereign instance of `%fund`. ### From the clearweb Whether you find the project via an urbit group, an X (fka Twitter) thread, or get it emailed to you by your boomer uncle, the core interface for interacting with `%fund` as a project funder is via a "project page" that provides details about the project scope, worker, oracle, and milestones, as well as a front end interface for interacting with the escrow contract. The most 'lightweight' way to access a project page is to visit a url hosted by the project worker's urbit. This requires nothing more than a web browser, so *anyone on the internet* can see a publicly published project. > If you are interested in running private campaigns, restricted either by password, or Urbit ID please contact `~tocwex` on the network and we'll see what we can do for you. #### On-chain contributions Any ethereum wallet—including those without a running urbit, or even an Urbit ID—can interact with the base features of a project page. In this capacity, the page is tremendously simple: * Read the project description and milestones, assess whether you think the project is worthy of funding * Connect your ethereum wallet to the page using the "Connect" button * Fill out the form with your desired contribution amount and message * Select "send funds" to prompt your MetaMask wallet transaction execution modal * Sign the transaction. Interacting with the contract in this way is not fundamentally linked to your identity beyond the publicity of your chosen Ethereum address. It gives no way for you to contact the project worker or the trusted oracle, and gives you no mechanisms for verifiable discovery of those parties' reputation. [Refunds](#getting-a-refund) are returned to the Ethereum address that contributed them, and for many this may be sufficient. Contributions can be directly made to a project, and aside from the basic action of connecting your MetaMask wallet, no novel interaction types are required. > It is important to note the "from the clearweb" and "[using eAuth](#using-eauth)" methods of interaction implicitly mean you are trusting the page host to be telling the truth about facts such as: who else has contributed funds to the project, who the trusted oracle identity is, and what other urbit IDs have pledged future funding. This is generally the same way you put trust in other crypto front ends, but where `%fund` is different is in offering a "trust but verify" model. To operate on the verification model, just get your own urbit and run your own self-sovereign instance of the software and access the project page [from your own urbit](#from-your-own-urbit). ### Using eAuth If you have a running urbit, you can click the "login with urbit \~" button in the top navigation bar of a `%fund` project page hosted by an urbit peer. This will trigger a sign-in flow where you: * Provide your urbit ID in the login form * Get redirected to the public domain at which your urbit is hosted * If your browser is not already authenticated, you will be asked to sign in with your `+code` * After signing in on your personal domain, your urbit will ask you to approve access * After approving access you will be redirected back to the project page where the "login with urbit \~" button will be replaced with your `@p`. Following successful authentication, you will be able to access additional functionality without needing to download a dedicated application, or in urbit parlance, a `%desk`. The actions of these features will be linked to your underlying urbit ID: * [Pledge future commitment](#off-chain-pledges) without needing to execute an ethereum transaction, so you can signal your support even if you don't have your wallet on you at the time * Get instructions for application download to fulfill pledges * Fulfill previously committed pledges made to the the project Critical among these features are the ability to make off-chain pledges. #### Off-chain pledges Urbit offers something unique to crypto: a pseudonymous identity *inextricably linked to a Turing complete virtual machine that runs as a node in a peer-to-peer network*. This allows for off-chain promises of future funding contributions; one might even consider this the beginning of a sovereign credit network. There are a few things to consider about this functionality: * Pledging is only accessible to authenticated users; this works by linking the promises made to your urbit ID either by [using eAuth](#using-eauth), or by interacting with the project [from your own urbit](#from-your-own-urbit). * Pledges are made purely as a function of verifiable claims and social signaling. A pledge recipient can prove that you made the promise, but nothing more. Enforcement is purely social, with knowledge of your credibility propagating through the network in the same way social credibility does in the real world. * To fulfill your pledges, you will need return to the project page hosted by the project worker, or to access `%fund` [from your own urbit](#from-your-own-urbit). Curious to learn more about the technical details of how pledges work? Read the [developer docs](/developer-documentation/read-the-source). ### From your own urbit Accessing `%fund` from the application running on your urbit gives you all the above functionality and more. As a project funder you will need to access projects from your urbit to track and fulfill your pledges and if you want to dip your toe into running a `%fund` for your own project work—or put your reputation behind being the judge of the work of others—you will need to download the `%fund` desk directly. If you don't already have it installed, [follow the instructions here](/#installing-fund) to do so. After downloading the desk, go to the `%fund` app and click "View dashboard ->" on the "Project funder" card to discover projects that you know about via pledging or funding contributions. > Additional discovery features such as "projects from your `%pals`" to follow after the initial beta release. #### Fulfilling your pledges Fulfilling your pledges is a critical step to how project funders interact with funding campaigns. Remember, the project worker you are promising funds to might really be counting on you following through on your word. While it is possible to fulfill pledges using eAuth, we recommend [installing `%fund`](/#installing-fund) as it makes it much easier to track your pledge commitments, and offers you a chance to verify the details of the funding campaign via your own urbit. To fulfill a pledge: * Click the `%fund` app tile * Navigate to the project funder dashboard * See the list of projects under the header "My Open Pledges" * View the project. You will see the contribution card has the title "Fulfill Pledge" and that it is already pre-populated with the contribution amount. * Click "send funds" and use MetaMask to execute the resulting ethereum transaction. You should see the "Proposal funders" section of the page update your entry from `pledged` to `fulfilled` and find that random people on the network are now nicer to you and somehow perceive you as more credible in applications having nothing to do with `%fund`. Congratulations, that is the feeling of a cohesive digital identity! ## Getting a refund Refunding is simple; if a project is terminated, either by the project worker or the trusted oracle, the funds sent from your address will be returned to that address. No action is required (or possible) on your end, technically. If a project has been partially completed and paid out to the worker, your refund will be proportional to the remaining funds unpaid to the worker. For example: * You contribute $250 to a project with a $10,000 goal in 2 milestones, each of $5,000 * The project raises $8,000 in funding to it's contract, and $1,000 in additional pledges * The project worker delivers on the first milestone and gets paid $5,000 * The project is cancelled after that first payout, so you will receive a partial refund from the available $3,000: * $3,000/$8,000 = 37.5 % * 37.5% of $250 = $93.75 Socially, if you are on the urbit network, you have the ability to exert soft power both on the project worker and the trusted oracle. Because identities bridge across all of the applications in the ecosystem, the mechanisms of influence are not purely limited to the affordances we provide directly in `%fund`. For example, project workers may run a `%tlon` group in which they provide project announcements, or where community members can discuss the project (or otherwise just build p2p relationships!). It is through these 'out-of-band' social channels that you have the opportunity to do things like voicing your discontent with work quality or timeliness, potentially influencing the worker or oracle to cancel the project and issue a refund to their funders. Also, as a funding contributor to a project you automagically have a way to contact other project funders! So even if a malicious party kicks you out of an 'official' space for a project, you can reach out directly to other contributors. Who knows, maybe you'll unionize or something? ## Getting your own urbit If you've read this far, you probably want access to some of the features listed above. Great. You will find built into the clearweb UX flow, if you do not have an urbit, we provide an integrated way to get a ship hosted by Red Horizon. For other options for acquiring both an identity and a way to run it, visit our page on [getting an urbit](/system-guides/getting-an-urbit). We highly recommend getting your own urbit at this stage. It will be necessary in order to access the functionality of the next role, that of the project worker. # Project workers How to operate as a project worker is running your own funding campaigns Using `%fund`, project workers are able to draft and present proposals to the world with human readable milestone descriptions and funding targets, raising funding for projects of arbitrary scope and budget amounts, without needing to create custom smart contracts. In this section, we assume you have an urbit. If you don't, follow these instructions on [getting an urbit](/system-guides/getting-an-urbit). We also assume you already have `%fund` installed. If you don't, read *this* *section* on [installing `%fund`](/#installing-fund). ## Creating a project To create a project, open `%fund` from the application tile and click the "View Dashboard ->" button under "project worker". This will take you to a dashboard view of all your draft, open, and archived projects. In the top right, click the button that says "New Project +" and you will find a straightforward form to complete. ### Drafting the project overview At the top of the form, in the "Project Overview" section, provide a project title and description that is informative to your potential project funders, and which provides clear work terms that can be assessed by a trusted oracle. There is also a field for providing a header image url. While this field is technically optional, we definitely suggest using an image as it will help capture the interest of potential funders. You may link to any image of your choosing, but we recommend an image in the 16:9 aspect ratio. This section also includes the "Funding Goal" value, which is automatically calculated based on your provided milestone amounts. After you have completed the project overview, you can proceed to adding more detailed milestones. At any point in drafting your project, as long as you have given it a title, you can scroll to the bottom of the page and click "save draft \~". This will save (and update) the contents of your project draft and send you to a confirmation page. #### Chain & Token Selection Support for both Ethereum Mainnet and Sepolia Testnet are available in `%fund`. If you would like to experiment with the project setup flow, we recommend selecting "Sepolia" in the Blockchain dropdown. Currently, for Mainnet deployments, we ### Adding project milestones By default, the form starts with one milestone form field but you may add as many milestones as you need. We recommend projects with something between two and five milestones as the difficulty of accurately projecting work is increasingly challenging as you get further from your starting milestone. To add an additional milestone, simply click the "New Milestone +" button the the bottom of the "Milestones" section. Each milestone has the following form fields: * **Milestone title**: We recommend a short and descriptive title for the work you will do in this milestone * **Milestone budget ($)**: The milestone budget is denominated in USD and represents the target amount of funding you are seeking to get paid for successful completion of the milestone * **Milestone description:** The milestone description is your opportunity to document what you will do in order to get paid the budgeted amount The milestone description field is deliberately open ended for you to explain in human language what work will be completed. This may include: * Estimated milestone completion dates * Promises to ship widgets to funders of certain amount thresholds (i.e. We will send all funders who contribute >$20 a hand printed zine) * Descriptions of application functionality or users stories to be satisfied by the milestone's work > Currently the rendering of the milestone description is limited to plaintext. Future releases will aim to support formats such as Markdown. Most critically, these descriptions should be clear to both your oracle and your funders because the accuracy with which you complete the specified work will impact your social and professional reputation as a quality project worker (and thus your ability to get *paid*). ### Choosing a trusted oracle One of the unique mechanics of `%fund` is the ability to chose your own "trusted oracle" who will be the arbiter of whether the terms of your project are successfully completed. We have architected the system this way because we believe that sovereign communities–not megacorp platforms or software developers–should be the judges of whether work should be funded and similarly enabled to handle their own disputes. Mechanically, choosing a trusted oracle is incredibly simple. In the "Chose a trusted oracle" section, enter an Urbit ID (star-level or higher), propose a fee percentage, and then hit "save draft \~". If your project scope is complete, the following confirmation screen will give you the option to "request oracle ✔". By clicking this button, you will send a peer-to-peer request over the Urbit network to your selected oracle, providing them with a copy of the project scope and the opportunity to accept your service request and fee offer. Once you have requested an oracle you will see a project page that has a disabled "finalize oracle ✔" button. Coordinate with your requested oracle to help them through the [process of accepting your request](/user-guides/trusted-oracles-wip#accepting-a-request). While the mechanics of choosing an oracle are trivial, we also recommend that you do a few other things in order to have the oracle accept your service request and serve as a quality trusted oracle. Remember, these are social and human dynamics. Primarily, we recommend that you reach out to your desired oracle in advance of sending the formal request to discuss if they are interested in the work, their qualifications for judging work completion, and agreeing in advance on a fee percentage for their services. Using `%tlon` groups or direct messages are a great way to do this coordination work because the entity that you interact with via those chat channels is cryptographically guaranteed to be the same as that which receives your `%fund` service requests. ### Finalizing the proposal While the request is open with your proposed oracle, you will find that the contents of the project are not available for editing. This is to ensure the oracle doesn't unintentionally agree to a surreptitiously or accidentally modified version of a project. If changes are required, the oracle can reject the project request and you can make edits and resubmit your request. Until the oracle accepts your request, or if for some reason they are not responding, you can always retract your offer. Do this by going into the edit project page and clicking "retract proposal \~" at the bottom of the page. This will allow you to further edit the project or chose a different trusted oracle. Submitting the request will have your project appear in their trusted oracle dashboard, but we advise you also reach out directly to them to answer any questions or concerns they may have about the project terms. In order to accept your request, the trusted oracle will need to cryptographically sign a message containing the contents of the project proposal. This helps ensure they have the private keys for their owner address of the escrow contract, without requiring them to pay gas for any transaction execution in order to create the contract itself. Once the trusted oracle signs this message, their urbit will pass the signed message across the Urbit network and enable you to finalize the escrow. As this process happens on human-scale timeframes (generally between hours and days), you may need to reload the project creation page in order to see the updated "Finalize Proposal ✔" button. To fully launch your project, click this button and execute the prompted MetaMask transaction. #### Smart Contract Escrow The beta version of `%fund` uses a contract ecosystem based on Gnosis Safe multisig contracts. As a project worker, there are a few things to understand about this version of the system: * The contract is initialized as a 2-of-3 multisig where the signers are: * The keys used by the trusted oracle to sign the message containing the project details * The keys used by the project worker to initialize the multisig escrow contract * `ceo.tocwex.eth` which will validate and sign refund transactions in the event a worker or oracle counterparty is unable or unwilling to process a project cancellation * The contract has all the typical features of a Safe multisig, enabling transfer of assets to any address agreed upon by the signers * The `%fund` interface only supports USDC contributions; funders will not be able to *accidentally* contribute other tokens or assets * If other tokens are sent to the contract address, contact `~tocwex` on urbit and we will walk you through retrieving them The construction of the contract ecosystem beta is for purposes of iteration and handling of edge cases by trusted counterparties with persistent identities, while reducing the total amount of trust required for critical path actions (i.e. parties cannot unilaterally run off with funds). Future versions of the contract ecosystem will refine the interfaces between identities, on- and off-chain reputation data, and transaction-type authorization permissions. If there is a particular feature you would like to see, please don't hesitate to let us know via email at or [on urbit](https://tlon.network/lure/~tocwex/syndicate-public). ## Running your project You now have a live project to which any ethereum wallet holder can contribute USDC, and with an uncensorable front end. What you use that for, how you deliver on your promises, and who you raise money from is totally up to you. When it comes to the `%fund` aspect of running your project, there are essentially two mechanics to know about: [statuses](#project-and-milestone-statuses) and [actions](#project-worker-actions). ### Project and milestone statuses The status of any given project or milestone is critical for informing project funders and trusted oracles about how to interact with your funding campaign. Possible statuses are as follows: * Draft: A project proposal saved to your personal urbit, available for you to edit and modify * Proposed: A locked project that has been shared to a trusted oracle for acceptance or rejection of a service request * Launched: A project that has been initialized with an on-chain escrow contract to which project funders can contribute cryptocurrency * In-progress: A milestone has been designated as 'in-progress' by the project worker * In-review: The worker has requested the oracle to provide a signed message approving completion of a milestone and a related withdrawal transaction * Completed: A milestone that has been approved by the project's trusted oracle * Cancelled: A milestone that has been cancelled by either the project worker or trusted oracle While different communities may interpret the concepts of 'Launched', and 'In-progress' in their own way, this status definition mechanism enables humans to have a tractable interface between the world of atoms (which has more 'grey areas') and the world of bits (computers understand binary; raw black and white). The top-level project status is inherited from the status of the most active milestone; i.e. if any milestone is in-progress, the whole project will be marked in progress, but if a project has a milestone in-progress and another in-review, the project will be marked as in-review as that status is presumptively the most prominent state of the project. ### Project worker actions As the project worker, you have access to four primary actions within `%fund`: * **Mark in-progress \~** : Urbit-side action that changes the milestone status from `launched` to `in-progress` * **Request review \~** : Urbit-side action that changes the milestone status from `in-progress` to `in-review` and enables the `approve milestone` action for the trusted oracle to approve a withdrawal transaction * **Claim funds** ✔: Ethereum action that exists only if the trusted oracle has marked the milestone complete and provided a signed message releasing funds; clicking will prompt an ethereum wallet to execute a withdrawal transaction * **Cancel Project** ✘: Changes project status to `cancelled` and prompting your ethereum wallet to provide a signed message for the refund transaction which will be validated approved by your trusted oracle or `ceo.tocwex.eth` Aside from the "Cancel project" action, which appears in the project overview section of the project page, all of these actions appear as buttons in their respective milestone cards when a milestone is eligible for that particular action. #### Getting Paid for your work The "claim funds ✔" action will execute an ethereum transaction that sends the claimed funds for the completed milestone to your urbit's ownership address. The claim transaction will send funds to: * Your trusted oracle will receive a percentage fee as mutually agreed in the setup process * The protocol treasury, `treasury.tocwex.eth`, will receive a 1% protocol fee * Your payment address will receive the remainder of the funds You now have custody of a cryptographic bearer asset, congratulations! Shoot us a DM at `~tocwex` to tell us how it feels to conduct sovereign crypto-economic activity. > **IMPORTANT:** Please take a moment to read the page on [Ethereum key management](/system-guides/ethereum-key-management) to learn more about managing the cryptographic keys relating to your Urbit. ## Sharing your project Of course, these statuses and actions don't matter if you don't have anyone funding your project. Lucky for you, your newly created project page is accessible to the clearweb and can be shared around like any other website or dApp! Click the "Share 🔗" icon to copy the project page's URL to your clipboard and then share the project on Farcaster, Twitter, via email, or in any other channels where you think your project funding community might find it. Getting people to visit your project page is just the beginning though. Don't forget to communicate with your funders and your oracle. Building a community around your project(s) can help to drive more interest and funding, as well as smooth over the handling of unforeseen edge cases. To this end, we recommend spinning up a `%tlon` group (or set of channels + roles in an existing group) where you can provide project updates, invite new funding contributors, and even have open discussions with your trusted oracle about any work review efforts. You can even use access/roles within this group as an incentive for people to fund your project! # Trusted oracles Providing project work assessment services as a trusted identity The `%fund` application is an open system where cryptographically secure identity and trusted relationships enable Urbit IDs to serve as effective oracles for economic activity occuring in the world of atoms but settling in the world of bits. To this end, the role of the "trusted oracle" is to provide the valuable service of reviewing project deliverables against the human-legible project terms, determining for the project—and balancing the interests of both the worker and the funders—whether a given project milestone has been satisfactory completed, or not. ## Basic Setup There are essentially only two basic requirements in order to serve as a trusted oracle: 1. Be an Urbit Star or Galaxy-level identity 2. [Install `%fund` on your urbit ](/#installing-fund) From there, open the `%fund` application and visit the "Trusted oracle" dashboard page to take action on any incoming service requests from project workers or to take review actions on presently active projects. If you run into issues, check out the [Operating as a trusted oracle](#operating-as-a-trusted-oracle) section of this page. ### Why do we only support stars as escrow providers? Currently, `%fund` restricts the trusted oracle functionality to star and galaxy-level Urbit IDs. We do this for three main reasons: * **'Skin in the game'**: Urbit stars and galaxies have material economic value as ERC721 tokens on the ethereum blockchain. By restricting to these identity types, we can set a baseline expectation for project workers and funders that a potential trusted oracle doesn't want to immediately torpedo the value of their cryptographic asset by operating as a bad actor. In a stark contrast to planet or comet level identities, this helps to incentivize a game theoretic model of iterative games by increasing the cost of burning an identity over that which could be gained by malicious action. * **Sovereignty signaling**: The role of a trusted oracle is one of a sovereign. The buck stops with them on the topic of whether work meets the terms of the project specification. This power is a pairing of freedom and duty, which the responsibility of running a star suggests is something with which the owner is both comfortable and actively interested. * **Institutional ambitions**: We expect that the best experience for creating new crypto-economies and managing the dispute resolution protocols within them will be crafted by the individuals and groups who have signaled an interest in running urbit stars, which come with other similar opportunities (such as [running `%chain` validators](https://tlon.network/lure/~tiller-tolbus/token)). These new institutions are necessary elements, or artifacts, of human organization across the world of atoms and the world of bits. Transience may be *allowed*, but it isn't exactly *encouraged*. At this stage these dynamics lean towards the social, but as `%fund` evolves the star-level identities and their on-chain interactions with other Urbit IDs offer opportunities for increased functionality around relationships and reputation. #### Getting a star In spite of restricting the trusted oracle role to specific costly NFT holders, it is not our intent to build a *permissioned* system, but rather leverage an opportunity for economic signaling and on-chain interaction. Acquisition of an Urbit star is possible through a variety of channels: * [Opensea](https://opensea.io/collection/urbit-id-star): A general purpose NFT marketplace * [urbitex.io](https://urbitex.io): A marketplace dedicated to trading Urbit Stars and Planets * [Urbitswap](https://github.com/urbitswap/urbitswap): An urbit application for trading NFTs. Download it on your planet and use it to buy a star in a p2p transaction * [Urbit Foundation](https://urbit.org/grants): If you would prefer to *earn* a star, rather than purchase one, the Urbit Foundation's grants program regularly distributes stars as a reward for contributing to the urbit ecosystem. There also exist an array of OTC sellers and p2p mechanisms of exchange. You could probably even use `%fund` as a way to settle the trade of a star for USDC... Definitely let us know if you pull this one off! ## Operating as a trusted oracle Of course, getting a star-level identity and installing `%fund` are just the beginning of running a *trusted* oracle. You will need to build relationships with project workers, recruit potential project funders, review/approve work product, and figure out how to best handle disputes within your community. This is on you! Of course, we don't know your audience as well as you do, but perhaps you want to publicize your availability on twitter, host a `%tlon` group, or otherwise signal to the world that you are a credible source of trusted oracle services. ### Service fee negotiation After finding a project worker who thinks that your reputation brings enough clout to their project, and who trusts you to be a fair judge of project completion, you will need to negotiate specific deal terms. Currently, the compensation model for trusted oracles is a fee percentage of successfully completed and paid out project milestones. This specific fee-percentage is expected to be negotiated out-of-band from `%fund` (i.e. via `%tlon` direct messages), and will be formally noted by the project worker when they send their service request to you. ### **Accepting a request** Formal requests will appear in your trusted oracle dashboard under "Requests for my services." Projects in this "Proposed" stage will be locked for editing and include an "Review Request" card that outlines the proposed fees and the project details for your review. If, in your judgement, the scope looks well-specified enough you can click "Accept". You will be prompted to sign a message with your ethereum keys. You will not be asked to execute a transaction, but rather you are signing the contents of the proposal, so the project worker cannot surreptitiously change the terms of the deal. A secondary reason for requiring this message signing is to ensure you have access to the private keys that are being assigned payment approval permissions so that funds don't get stranded and need to be unnecessarily refunded. The signed message is passed from your urbit to the project worker for final transaction execution, thus saving you the need to pay any gas fees. Transaction execution and final instantiation of the escrow contract is the responsibility of the project worker. And of course if the project is not well specified enough (yet), or the fee offer is insufficient, you can click "Reject" which will send it back to the project worker and allow them to make further edits. If you reject a request for your services, we recommend also sending the worker a DM to explain why. ### Trusted Oracle actions Once the escrow contract is instantiated, the project will receive the "Launched" status, until the [project worker takes action to update a milestone](/user-guides/project-workers-wip#project-worker-actions) to "In-progress". For more on status definitions, [check out this section here](/user-guides/project-workers-wip#project-and-milestone-statuses). Otherwise, the primary items of consideration as a trusted oracle are the review actions or project cancellation. As the trusted oracle, you have access to three primary actions within `%fund`: * **Changes Required \~** : Urbit-side action that changes the milestone status from `launched` to `in-progress`. Hitting this button will suggest to the worker that more work needs to be done in order to satisfy the milestone terms. We strongly suggest sending them a DM as well to clarify exactly what needs to change. * **Approve**: Urbit-side action that changes the milestone status from `in-review` to `completed` and prompts your ethereum wallet to sign a message approving a withdrawal transaction. Providing this signed message enables a transaction of the milestone amount to the project worker's payment address. * **Cancel Project**: Changes project status to `cancelled` and prompting your ethereum wallet to provide a signed message for the refund transaction which will be validated and approved by either your project worker, or `ceo.tocwex.eth`. Aside from the "Cancel project" action, which appears in the project overview section of the project page, all of these actions appear as buttons in their respective milestone cards when a milestone is eligible for that particular action. ## Frequently Asked Questions #### What is a sufficient project specification? it's up to you! It might might make sense to go back and forth with the project worker on the details of the project, as currently our interface only allows for acceptance and rejection of a service request. Depending on how you expect to run your oracle service, you may want to offer a standard deal, or otherwise publish your expectations for what it means to assess successful milestone/project completion so that both workers and funders know the standards and protocols which will need to be followed. #### Can I contribute to a project for which I am the oracle? Yes! After accepting the request and following the instantiation of the contract by the project worker, the action modal will change to a contribution modal. Contributing to a project you are adjudicating is allowed; it is up to you whether that is compelling to your audience or if they may perceive it poorly. You decide. # Getting an urbit Opportunities for getting your own Urbit Getting your own urbit requires that you both acquire an Urbit ID, *and* a way to run the urbit node. A wide array of options exist for satisfying both of these requirements, and in this section we will outline the main pathways for onboarding to the network and operating your urbit. ## Hosting providers Urbit hosting providers are by far the easiest way to get an Urbit ID and a running node on the network. The big providers all offer free co-custodial urbit IDs with email signup and onboarding, as well as a guarantee to let you leave their services with your identity and your data. Currently this *guarantee* is enforced just through convention and is not a technical affordance, although Tlon Corporation has implemented interface options for retrieving your data and claiming unilateral control of your Urbit ID. ### Red Horizon [Red Horizon](https://redhorizon.com) is designed by [Chorus One](https://chorus.one) with a mission to expand the freedom and sovereignty that human beings experience in their digital lives. They offer free hosted urbits and enable developers to provide a pre-defined set of applications and group memberships to help new users more quickly get their bearings. If you sign up for urbit hosting via the new user flow on [tocwexsyndicate.com](https://tocwexsyndicate.com), or that is built into `%fund`, you will find yourself hosted by Red Horizon with a few applications we think are useful, including `%fund` and membership in the \~tocwex.syndicate public group in the Tlon social app. If you have onboarded to a Red Horizon hosted Urbit via [tocwexsyndicate.com](https://tocwexsyndicate.com) and need to get access to your ownership keys, please contact us at or send a DM to `~sarlev-sarsen` and we can assist. ### Tlon Corporation [Tlon](https://tlon.io) is the original incubator of the Urbit project, and following the growth of the ecosystem has evolved towards developing the Tlon suite of apps. They maintain the most mature mobile app in the ecosystem, available for download on [iOS](https://apps.apple.com/us/app/tlon-the-urbit-app/id6451392109) or [Android](https://play.google.com/store/apps/details?id=io.tlon.groups\&hl=en_US\&gl=US), and offer streamlined mobile onboarding. If you have onboarded to Urbit via Tlon, you are able to view and download your cryptographic keys directly from the web UI. For more details on how to do this, check out the ["Tlon hosting" section of the Ethereum key management](/system-guides/ethereum-key-management) page. ## Self-Hosting Working with Urbit hosting providers is by far the easiest way to get on the network, but it comes with some drawbacks. For example, in order to run your urbit, the hosting provider has control of and access to your data. For many, this is a non-issue as it is essentially the same as any existing social network and many web2 applications. For others, more sovereign control of their data is desirable. There are two primary paths for self-hosting: Orchestration software for running an urbit at home, or using developer-friendly virtual private servers. ### Native Planet [Native Planet](https://nativeplanet.io) is an urbit company that builds hardware and software for easy at-home urbit hosting. Specifically, they build urbit orchestration software called [Groundseg](#groundseg) that helps non-technical users to run and maintain their own urbits, and provide a networking services called [StarTram](#startram) that protects your privacy and ensures you can access to your urbit from any of your devices. And it does this all while giving you more sovereign control of you data by keeping you in physical control of the device that holds your urbit. Groundseg is expected to be run on a dedicated device, but you don't have an extra computer laying around, Native Planet makes [Urbit dedicated devices](https://www.nativeplanet.io/hardware) with GroundSeg pre-installed, and that comes with a free year of StarTram. #### Groundseg Turn nearly any device into a dedicated Urbit Server! Native Planet has released Groundseg as open-source software to make self-hosting Urbit easy and convenient, so you can own your data and keep the network decentralized. The default password for all Native Planet software is **“nativeplanet”**. You can find more documentation and instructions in the [GroundSeg manual](https://manual.groundseg.app/), but the 'quickstart' is as follows: ***Linux*** Install GroundSeg on an existing Linux machine by copying this into a command line:\ `sudo wget -O - get.groundseg.app|bash` ***Colony OS*** Create a dedicated Urbit hosting device by flashing Native Planet’s Colony OS to any x86 machine capable of running Linux. Download: [Colony OS ISO](https://colony.groundseg.app/) #### Startram [StarTram](https://www.nativeplanet.io/startram) is Native Planet's purpose-built networking backend for home-hosted Urbit ships. As a subscription service paired with GroundSeg, StarTram makes it trivially easy to access your ship from anywhere. They also offer [Anchor](https://github.com/Native-Planet/anchor), an open-source single tenant version of StarTram that can be self-hosted if you are so inclined. ### Virtual Private Servers > **There be dragons here**. Manually hosting your own urbit comes with a wide array of responsibilities. Of course, we believe in you if you believe in yourself, but consider yourself warned that this is an undertaking. Expect to encounter challenges, but also to find a helpful community and maybe even make some friends. While the `urbit` program most definitely can run on your local computer and it will "work", running an urbit on your home network and getting it to reliably and performantly communicate with the external world is a technically advanced undertaking. Unless you are a networking professional, we strongly recommend self-hosting on a Virtual Private Server (VPS) from a service provider like Digital Ocean (great ux, moderate cost), or SSDNodes (powerful machines for cheap). Various urbit contributors have written guides over the years on how to get up and running; here are a few of our favorites: * [Official Urbit guide to cloud hosting](https://docs.urbit.org/manual/getting-started/self-hosted/cloud-hosting) by The Urbit Foundation * [Free Self-Hosting with Oracle Cloud](https://subject.network/posts/free-cloud-oracle/) by \~sitful-hatred * [Comprehensive guide to Urbit on the Cloud](https://zalberico.com/essay/2020/06/06/urbit-on-the-cloud.html) by \~dovsem-bornyl All of these guides will get you to the same place: A running urbit on a virtual server, but with potentially different flavors of implementation. If the words `tmux`, `caddy`, `nginx`, `screen` or `sysadmin` mean anything to you, you'll probably be at home here so can through the guides and pick your favorite. If they don't, seriously consider going the [Groundseg](#groundseg) route. ### Acquiring a Urbit ID In addition to an internet connected, always-on computer on which to run the `urbit` program, if you chose to self-host you will need to acquire an Urbit ID. There are two decisions you will need to make in this domain: layer one vs layer 2, and planet vs star. #### Layer one or layer two? We will make a controversial claim here: Layer 1 (L1) and Layer 2 (L2) Urbit IDs grant different affordances to their owners. While both are cryptographically owned, L2 ships and their ownership are opaque to the outside world, while L1 ships are legible to the broader Ethereum ecosystem but come with greater cost burdens for some administrative operations. Once on the network, both types of identity function the same; it is only with the external world that you may experience different featuresets. If you are going down the self-hosting path and expect to be a deeply engaged `%fund` user, we recommend acquiring an L1 Urbit ID to ensure access to all the best upcoming features. For more on why we think this way, read this blog post. Of course, we will also always support L2 identities for the core feature set. #### Planet or star-level identity? As it relates to `%fund`, the important decision to make to answer this questions is whether or not you would like to serve as a [trusted oracle](/user-guides/trusted-oracles-wip). If yes, you need a star. If not, you will be well-served by a planet-level identity. If you would like to learn more, read on! Urbit ID and the associated "public key infrastructure" (PKI) uses a hierarchical sponsorship model for distributing address space, managing peer discovery, and network packet routing. To learn more about the PKI design and implementation (aka Azimuth), you can read the urbit.org documentation [here](https://docs.urbit.org/glossary/azimuth). In short, there is a layered hierarchy of identities, represented as Ethereum ERC-721 NFTs: * **Galaxies** are the 256 (2^8) network governance nodes and have a single syllable handles, or "`@p`s", such as \~zod * **Stars** are a set of 65,536 (2^16) infrastructure and services nodes and have a double syllable `@p`s such as \~tocwex * **Planets** are 4,294,967,296 (2^32) individual user nodes and have a quadruple syllable `@p` such as \~sarlev-sarsen To learn more about why we have this restriction in place, read this section on [why we only support stars and galaxies as trusted oracles](/user-guides/trusted-oracles-wip#why-do-we-only-support-stars-as-escrow-providers). #### Where to buy an Urbit ID Given that Urbit is a decentralized network, there are a broad array of providers who can sell (or give) you an Urbit ID. Of course, we aim to be your first stop so if you would like to buy an L1 planet under \~tocwex, just email and we'll get you set up. But if you would like a broader selection of handles (aka `@p`s), we can also point you to any of the following providers: * [Networked Subject](https://subject.network) to buy L2 planets with BTC * [Urbit Live](https://urbit.live) to buy L1 planets with ETH * OpenSea to buy L1 [planets](https://opensea.io/collection/urbit-id-planet) *or* [*stars*](https://opensea.io/collection/urbit-id-star) with ETH * [Escape Pod Store](https://escapepod.store) to buy L2 planets Want to serve as a trusted oracle but don't have the capital to purchase a star? Check out the [Urbit Foundation Grants program](https://urbit.org/grants) to earn one for contributing to the network. # Application Architecture 1-part Urbit, 1-part DeFi, 2-parts human interaction. The underlying architecture of `%fund` is somewhat novel to the world of bits, most notably in how it puts control back into the hands of it's users. It is partially a DeFi front end, partially a peer-to-peer social reputation system, and partially a project scope management tool. While some crypto "dApps" have started to have tripartite design it will typically be in the form of a centralized front end and database layer, with a decentralized global consensus layer. We find this lacking. Instead, we believe in putting practical sovereignty back into the hands of our users. To achieve these ends, instead of a traditional 2-party front- and backend or more recent dApp architectures, the stack bridges across three underlying systems: * Ethereum, as the *decentralized* global consensus and smart contracting layer * Urbit, as the *distributed* backend for handling business logic and off-chain messaging * A browser based webapp for the front end interface, with public and private access mechanisms controlled by your urbit Because you own your urbit, nobody but you can shut down your access to `%fund` and only the peers with whom *you* chose to share data can have access to it. Even as the developers of the code, we have no insight into the nature of your deals, or even the capacity to shut them down. > Note: At present, all crowdfunds are "Public" and can be discovered exclusively via a clearweb link. Future updates will include usage of the %pals gossip protocol for sharing funds across the network, as well as supporting private campaigns. We share this explanation because the nature of `%fund` is fundamentally one of sovereignty, and the network within which you now operate is not controlled—or otherwise governed—by us. It will be up to you to make judgement calls on the credibility of your counterparties promises. To explore other applications on the network for insights into the people and groups with whom you chose to interact. To take the tools we give you, and chose how to use them. > "Caveat emptor, let the buyer beware, has been the rule of the marketplace for centuries." - Suze Orman # Ethereum key management Not your keys, not your coins Currently, `%fund` associates ethereum wallets for workers and oracles by the on-chain instantiation of the escrow contract, or in the case of project funding transactions, a trust but verify model. This linkage of Ethereum address and Urbit ID is straightforward, but is likely to expand in the future to enable additional features such as "Refund to my Urbit" or "Verified Project History". In the current implementation, our main statement is relatively typical of crypto: * **Not your keys, not your coins**. So keep your keys private and secure. If you are interested in utilizing more complex mechanisms of associating your urbit ID, your ethereum keys, and your work or contribution history with each other—either on- or off-chain—let us know! # On security and sovereignty "Expect to self-rescue" As with Urbit, and the rest of 'crypto', `%fund` is a tool for sovereignty. Not only does this mean you can have the relationships you want, it also means you have the responsibility for managing your own security. ### Privacy on the internet When you first open `%fund` you will encounter an option to share usage data with us. Sharing this data helps us understand if you are using the off-chain elements of the application. Choosing not to share this usage data will not impact the functionality of your application, but we find it worthwhile to note that your on-chain activity is still publicly visible (due to the nature of the Ethereum blockchain), even if you opt-out of our data sharing request. ### Wallet Support Due to the current affordances of Urbit on security, resilience, and recoverability, we have chosen offload wallet security to 3rd party wallets for the time being, so the security of your funds is dependent on your overarching security practices. Currently `%fund` supports MetaMask wallet connections for all message signing and transaction execution. A tangential benefit of this is being able to support legacy (non-urbit) ethereum wallet users with a unified user experience. As Urbit matures, we expect to use some of it's unique benefits to improve the `%fund` user experience with things like storing private keys in your urbit and making transaction signing an integrated function of actions and state changes occurring on the Urbit network. ### Security Warning The current release uses the Gnosis Safe Contracts which are heavily audited and the industry standard for multisigs. **That said, our interfaces are beta software and we make no warranty as to their security properties.** More importantly, though, an Urbit security audit has not been conducted. This includes both the implementation of Urbit OS (aka `%arvo`) and the runtime (aka `%vere`). It is possible that a malicious actor could hack your urbit and change the contract address contained in the `%fund` desk code, tricking you or your users into interacting with a malicious contract. While not perfect solutions, we recommend 2 things to reduce this risk: 1. Regularly check the desk hash against a known credible source. We publish the most current hash here on the documentation site. If you hash is different from one provided here, please proceed with extreme caution. * The current desk hash from `+vats %fund`for v1.5.0 is: `kkssa` 2. When signing transactions in MetaMask, double check the contract address with which you are interacting! This is something you should do anyways, but we strongly encourage you don't skip this step: remember, crypto is a bearer asset! * Here is the deployment proxy contract, if the contract you are sending funds to was not constructed from this address, do not interact with it. * [0xCE13EC86BD8b88279ec63eb9F1aed96759Ce5063](https://etherscan.io/address/0xce13ec86bd8b88279ec63eb9f1aed96759ce5063) # Read the source `%fund` is open source software that you run on your own urbit. As the codebase matures, we will produce documentation about the possible pokes, scrys, and subscriptions. In the meantime, install the app and read the source code: ``` |install ~tocwex %fund ``` You can then open and review the code in the file explorer `%cliff` or `%eyas` text editor. If you don't know how to do that, we recommend getting in touch with the Urbit Foundation and signing up for [Hoon Academy](https://docs.urbit.org/courses/urbit-academy/ha). If you have read the source and have further questions, join our `%tlon` group at `/1/group/~tocwex/syndicate-public`. We'd love to help! If you would like to review the code prior to installing on your ship, or make contributions to the project, it is available on [GitHub](https://github.com/tocwex/fund). The current smart contract code uses a [dedicated deployment of GnosisSafeProxyFactory](https://etherscan.io/address/0xce13ec86bd8b88279ec63eb9f1aed96759ce5063#code), and the official Gnosis Safe deployments of the rest of the contract ecosystem.