Fathom-contracts NPM

About

This is an ethereum-based implementation of the fathom protocol, which defines a peer assessment protocol based on a participatory token economy: You get tokens through assessment, you pay them to get assessed. This system is an abstracted assessment framework capable of assessing anything: Anyone can create a credential, anyone to get assessed in it and anyone who passes can assess others. For more documentation see our documentation.

Contract Structure

Fathom credentials (or: concepts) are are ordered hierarchically from most general to most specific. For example, if you wanted to be assessed in creating a Hello World program in Python you would create that assessment on the Hello World concept, which would be a child of the Python concept, which would be a child of the Programming concept, et cetera. This allows us to assemble knowledgable assessors for new or young concepts by drawing them from their parents.

At the heart of the contract-system is the conceptRegistry-contract. Upon deployment, it creates the MEW-concept - a special concept at the root of the concept-ontology that has no parent and is associated to no particular skill or assessable quality. The conceptRegistry also manages the creation of new concepts and serves as a central point-of-reference for the other system contracts:

FathomToken: Manages account balances and, together with the 'Minter' periodically creates new tokens that are distributed in a lottery mechanism to successfull assessors.
'ProxyFactory': A factory-contract to create proxies for the many concepts and assessments. By changing the template of the proxy, it can also be used to introduce updates to the system, such as changing the assessment-rules.
'Distributor': A contract designed to be used for deploy-time only. It is used to directly add the initial members to the MEW-concept bypassing the need to complete an assessment, but will only do so a predefined number of times.

Then there are the two central contracts that define credentials and how they are issued:

'Concept': Defines what a credential is about, stores information about the credential-holders (aka concept-members) and creates new assessments.
'Assessment': Calls assessors, runs the assessment game and, upon a positive outcome, adds the assessee as a new member to the concept.

Dependencies

Install all dependencies by running

npm i

This will install

ganache-cli (formerly named testrpc), to run your private testnet,
truffle-hd-walletprovider to manage keys when deploying to rinkeby and
ethjs-abi and ethereumjs-abi, to be able to run all our tests.

Deployment

Deploying a fathom-network-instance will lead the following contracts being on-chain:

ConceptRegistry.sol, to manage creation of new concepts
FathomToken.sol, to manage payments
One instance of Concept.sol, being the root of the concept-tree (the MEW-concept)
Math.sol, a library to do scoring and clustering

Local Testnet

Open a console and run your private testnet with 30 accounts.

ganache-cli -a 30

In another console, run the migration:

'truffle migrate'

All address in the testnet will be funded with AHAs and the first six will be added to the Mew Concept.

Public Network

To deploy to a public network you need to supply a funded account. You can do this by creating a file called secrets.json in the root folder ('./'), containing seed words that have ETH on the network you want to deploy to.

Your secrets.json-file should look like this:

"baseball poet vague session shrimp humus embrace glare monkey donkey balony bread"

1) Specify the initial accounts

You need to provide at least one address for the initial accounts to the system. These will have tokens distributed them and will be entered into the mew concept. To do so, create a file ./initialMembers.json in the root-folder of the project.

Its content should look like this

'"0xaccount1...", "0xaccount2...", ... '

To modify the amount addresses are funded with , open /migrations/2_deploy_contracts.js and set the variable initialAmount to the desired value.

NOTE: If you DON'T want to the MEW-concept to have any initial members nor distribute tokens to them, remove the third and fourth migration-file and continue at step 3). (Be aware that this you'll have to manually call the distributor and add the first member to the MEW-concept before any assessment can be run in your system.)

If you DO want to seed the network with some initial users in the mew-concept add them to the list of initial accounts.

2) Configure token & member distribution

By default, all tokens will be distributed amongst all addresses in the initial-member list and all addresses will be added to MEW. If you want to change that play around with the parameters in getAccounts.js.

3) Deploy

Lastly, run

'truffle migrate --network rinkeby'

'truffle migrate --network kovan

4) Troubleshooting

If you encounter an error-message saying 'Unknown number of arguments to solidity-function' it sometimes helps to recompile everything:
rm -rf ./build
If you get any other issues feel free to open an issue or add to an existing one.

Tests

Most functionnalities are tested in the test files inside the 'test' folder. To run them, try:

truffle test

Also, there is a script 'create2concepts2assessmnets.js' that creates two new concepts and initiates an assessment on each. When deploying to a non-development testnet, supply the name of the net as argument:

node create2concepts2assessments.js rinkeby

For further tests, there also is a script that runs an assessment until a given stage, e.g.:

node completeAssessment.js -s commit 100,100,90,90,90,90

, which will create a concept, create an assessment of size 6 in it and will complete the stage commit (assessors logging in the given scores). More examples of how this script can be used are to be found in the comments inside of it. Note that this ONLY works on your local testnet, because you can not send the evmIncreaseTime-command to an actual testnet.

Coverage

We use solidity-coverage:

npm run coverage

You can find the current coverage here

Contributing

To contribute to this project...

check out our contribution guide to see how you we work together,
talk to us on gitter or
send an email to contact@fathom.network if you would like to get in contact.

This repo has two relevant branches: master and development. master holds the version of our protocol which will eventually be deployed on the main-net. On the development-branch, the protocol is modified to make testing and developing for it much easier. Therefore, several constants (e.g. minimum number of assessors) have been factored out into an extra-contract, so that it becomes possible to create and complete assessments without having to wait and whithout controlling many accounts.