Ethlance V.2 (Newlance)

Ethlance Version 2 is Currently in Development and is subject to change before final release

Development

Prerequisites

1. Node.js >= 20.18.1 (it's defined in .tool-versions and asdf is a good way to install it)
2. Java JDK >= 18 (for Clojure)
3. Babashka
4. PostgreSQL (tested with 17.3)
5. IPFS daemon
6. Ethereum testnet (e.g. ganache)

Running the system

Clojure gets its missing dependencies automatically during compilation. Node.js dependencies need to be installed manually. There are 3 places for it:

1. Testnet & smart contract node deps at the project root:

• yarn install

2. UI node dependencies

• cd ui && yarn install

3. Server node dependencies

• cd server && yarn install

Also a database needs to exist (configured in config/server-config-dev.edn under :district/db key). Here's some SQL to do it (via the psql command)

CREATE DATABASE ethlance_new;
CREATE USER ethlanceuser_new WITH PASSWORD 'pass_new';
GRANT ALL PRIVILEGES ON DATABASE ethlance_new TO ethlanceuser_new;
\c ethlance_new
GRANT ALL ON SCHEMA public TO ethlanceuser_new;
ALTER DATABASE ethlance_new OWNER TO ethlanceuser_new; -- Optional

The database schema gets created automatically when server is started.

After this you can start all necessary services at once from the terminal with overmind start

• the processes to be started are defined in Procfile
• Overmind
• TIP for development it's better to run the bb run-server separately because although shadow-cljs recompiles the code on file saves, the node process doesn't reload it and for that manual restart is required to reload the updated code.

Or you can start them one by one (check the Procfile for respective commands):

1. Start IPFS

• this is optional if the :ipfs config points to external node

2. Start ganache bb testnet-dev
3. Migrate Solidity contracts to testnet: npx truffle migrate --network ganache --reset
4. Start server build bb watch-server
5. Start server (to serve the API) bb run-server
6. Start UI build bb watch-ui

• this also starts serving the UI assets & smart contract assets on port 6500

IPFS Server

Might require additional configuration for CORS if IPFS is running on a different host

ipfs config --json Gateway.HTTPHeaders.Access-Control-Allow-Methods '["PUT", "GET", "POST", "OPTIONS"]'
ipfs config --json Gateway.HTTPHeaders.Access-Control-Allow-Origin '["*"]'
ipfs config --json Gateway.HTTPHeaders.Access-Control-Allow-Headers '["X-Requested-With"]'
ipfs config --json Gateway.Writable true

Building & deployment

1. Smart contracts

The ethlance smart contracts should (for now) be deployed manually. As a result of the compilation process, the environment specific clojure files with contract addresses get written (e.g. shared/src/ethlance/shared/smart_contracts_qa.cljs for QA) and must be committed to git to make them available for deployment of browser & server applications.

During clojure application deployment (browser, server), the contracts must only be compiled, which will generate JSON ABI files under <ethlance-root>/resources/public/contracts/build/

Compilation:

1. ETHLANCE_ENV=qa npx truffle compile (replacing the network with one suitable for the env)
2. This generates ABI JSON files under <ethlance-root>/resources/public/contracts/build/
3. Server app needs to access them during runtime:

• configured via [:smart-contracts :contracts-build-path]

4. UI (browser app) needs them available: should be served by Nginx (or your web server of choice)

• get loaded from urls like http://d0x-vm:6500/contracts/build/TestToken.json

2. Server (/server)

To build Server (consists mainly of graphql API):

1. The following ENV variables need to be set:

• export ETHLANCE_ENV=qa

2. Compile with clj -A:dev:shadow-clj release dev-server

• will result a single file in out/ethlance_server.js (and accompanying ethlance_server.js.map source map)

3. Before running it the smart contract ABI JSON files need to be in a location defined in the EDN file ETHLNCE_CONFIG_PATH at EDN path [:smart-contracts :contracts-build-path]

• if it's a relative path, it gets resolved in relation to where the server process gets started

Running server:

1. Earlier the server config was compiled into the generated JS file. Now it will be loaded during runtime (at application startup) from the variable specified under :config :env-name. As for now it is ETHLANCE_CONFIG_PATH.
2. Also earlier the UI (browser app) config was baked into the compiled JS file for the UI. Now it gets served via /config endpoint from a location pointed to ENV variable UI_CONFIG_PATH (contents loaded at run time from the file system). Thus, starting the server:

• export ETHLANCE_ENV=qa
• export SERVER_CONFIG_PATH=/path/to/server-config-qa.edn
• export UI_CONFIG_PATH=/path/to/ui-config-qa.edn
• node out/ethlance_server.js

3. Browser (/ui)

1. The following ENV variables need to be set:

• export ETHLANCE_ENV=qa

2. Compile with clj -A:dev:shadow-clj release dev-ui

• the generated JS file (single) will be under <ethlance-root>/ui/resources/public/main.js

3. To serve the web page, configure the web server to serve the files under <ethlance-root>/ui/resources/public

• there are some other files, like CSS, JS and index.html that the web server needs to serve too

4. The web server must also serve the ABI JSON files generated in 1. Smart contracts

• for that, they can be copied from the build step or re-compiled and moved to where the web server can serve them
• the expected HTTP path will be /contracts/build/<ABI JSON FILE>.json (e.g. /contracts/build/Ethlance.json)

Contributing

Anyone is welcome to contribute to the ethlance project, here are some brief guidelines:

• Make sure to squash your commits
• Reference issue numbers in your pull request
• Rebase your changes on upstream (git remote add upstream https://github.com/madvas/ethlance.git) master before pushing (git pull --rebase upstream master)
• Make changes in a separate well-named branch in your forked repo like improve-readme

Overview of workflows

Here's a brief overview of the sequence of actions that different user types can take to create, find and arbiter jobs.

1. User arrives to the home page

• http://d0x-vm:6500
• picks which profile to create (freelancer = candidate, employer, arbiter)

2. This takes the user to the sign-up page

• http://d0x-vm:6500/me/sign-up?tab=candidate
• user fills in details for the roles they want to participate (candidate, employer, arbiter)

3. Employer (having first filled in employer data)

• http://d0x-vm:6500/jobs/new
• user can create new job by filling in the form
• creating a new job requires sending a signed transaction together with the initial funds
• smart contract method Ethlance#createJob is called and a new copy of Job contract gets deployed

4. In case the employer invited arbiters during job creation /jobs/new

• First: arbiter must send their quote (how much they want for their service for this job)
  • ... where can they do it (one or more pages)?
  • script helper: tx-workflow-fns-server-repl/set-quote-for-arbitration
• Second: employer must accept the quote
  • ... where can they do it (one or more pages)?
  • script helper: tx-workflow-fns-server-repl/accept-quote-for-arbitration

5. Employer can now invite candidates to participate in the new job

• NB! implement & provide link
• results in Job#addCandidate contract send
  • script helper: tx-workflow-fns-server-repl/add-candidate

6. Candidate can search for available jobs

• http://d0x-vm:6500/jobs

7. Candidate chooses a job of interest from search results. To work on it, needs to send proposal

• http://d0x-vm:6500/jobs/detail/0x1A2f3f7739A52F5bDCc909A8d42e96Cd8f9f4D30
• as a result JobStory is created (DB model to track this user's interaction with this job)

8. All users can view job contract page at

• http://d0x-vm:6500/jobs/contract/1
• send messages(all), raise disputes(candidate), resolve disputes(arbiter), leave feedback(all)

9. Candidate can create invoices (for any of their jobs)

• http://d0x-vm:6500/invoices/new

10. Candidate can then raise dispute

• after raising dispute, arbiter can resolve it on the same page (http://d0x-vm:6500/invoices/new)
  • resolving dispute results in tokens getting transferred according to the resolution amount

11. Employer can pay invoices

• ... (add link, implement if needed)