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. We also assume you already have %fund installed. If you don't, read this section on 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.

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 [e-mail] or on urbit.

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 and 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 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!