How gridcoin pool works (if you want to write or own yours)

Some notes I found when developing my own pool.

Common

There are three sides: user side (BOINC manager software), pool side (your software) and BOINC project side.

User has account in pool (I'll call this "user account"), pool has account in every BOINC projects (I'll call that "pool account").

When attaching to the pool, user get from pool auth key. With that key user can add his host to BOINC project under pool account. After that all communication occurs between user side and project side. So you don't need powerful hardware to start pool. Mine works on my old eee netbook.

When host is attached pool can get host stats from projects. These stats, combined with Gridcoin team stats, used to calculating rewards. Rewards are sent via gridcoin research wallet RPC.

Pool main parts and details:

1. Instructions

You need instructions. They should be very understandable, clear, single-valued (is it correct word?) How to join pool. How to change pool. How to attach to project. Currently only one user from three attached correctly. Only because because I sent him instructions what to do. (yes, I have only three users for now, and only one is active except me)

Do video instructions. Do text instructions. Be prepared to send instructions to users and be techsupport.

Everything that can go wrong will go wrong.

2. Web interface

Where you can register, login, attach and detach projects, view your stats. That is something that ordinary users see. Nothing intersting here.

3. BOINC projects registering, interface and reward calculation

You should register to all whitelisted project with the same mail. It is important. And join gridcoin team. Wait some time until your projects CPID become same.

Some projects has unusual features:

1. World Community Grid uses your username to login instead of mail.
2. Yoyo@home has no weak account key. So if you send full access key, user can obtain too much access to your yoyo@home account. Use it only when you trust your users, for example you doing pool for your friends.
3. Some projects has invitation codes, you can found them in their main project page.
4. You can register in project with BOINC manager when you add project.

Also, you need project stats for reward calculation. This information you can obtain via BOINC project RPC.

1. You need "Gridcoin" team expavg_credit.
2. You need expavg_credit for every pool's user host.

If you staking time is big enough (more than 1 day) , you should using stats instead of instant value. Otherwise rewarding could be unfair.

Reward calculation:

1. Divide all pool's income between projects according to project's proportion in gridcoin team.
2. Then divide project's income between pool users, attached to this project according to their contribution.

Math:

1. Your pool's contribution to project X = (Pool's account stats for project X) / (Gridcoin team stats for project X)
2. Total reward for project X = (Total reward for all projects) / (Whitelisted projects count)
3. Pool reward for project X = (Total reward for project X) * (Your pool's contribution to project X)
4. User Y contribution = (This user stats) / (All pool users in project X contribution)
5. User Y reward = (Project X reward) * (User Y contribution)

How to obtain data from projects: https://boinc.berkeley.edu/trac/wiki/WebRpc

4. Beacon.

You should have BOINC manager on the same computer, where you start your wallet (it could be different computer if you want some security). Sync wallet with network, attach to any BOINC project with pool account and restart wallet. If gridcoin research wallet don't show your CPID, check your mail in gridcoinresearch.conf. Try restart wallet, it helps me. Check that CPID in wallet is your CPID. Then send beacon. It doesn't matter which project you see in wallet.

5. Interface for BOINC manager (get_project_config.php and rpc.php)

Something to communicate with user side. Serves for sending information about attaching and detaching projects to user.

How it works:
When user click "Synchronize with AM" synchronizations starts. It has three phases:

1. BOINC manager (user side) checks get_project_config.php
2. BOINC manager (user side) send his config in xml to rpc.php
3. BOINC account manager (server side) send new settings to user (in xml too)

As you see, after one sync pool cannot check is user host attached to projects. So user need 2-3 synchronizations to attach to projects correctly.

Also pool should sign projects URLs with BOINC crypt_prog key. You should download BOINC sources, make crypt_prog, generate your own keys and sign each URL. So you can't just change URL, you also should resign that URL.

You should think about security here. Some advices that I received (thanks for @bgb) or found by myself:

• Host CPIDs are not unique.
• Host send you internal CPID, but when you lookup stats, you see external CPID - md5(internal_cpid.lowercase(password)). But sometimes you see internal CPID.
• host_id are not unique between projects (as I understand) but unique inside one project.
• There are exists XML attacks, read about them.

Setup instructions for crypt_prog: https://boinc.berkeley.edu/trac/wiki/KeySetup
How account management works: https://boinc.berkeley.edu/trac/wiki/AccountManagement

6. Gridcoin research API

gridcoinresearchd has API, settings are in gridcoinresearch.conf. Your wallet for API can be different from staking wallet, if you want more security.

You need these settings (you should use other values for username, password and port):

rpcuser=username
rpcpassword=password
rpcallowip=127.0.0.1/255.255.255.255
rpcport=64223

API Works via HTTP POST. So you can check these settings with curl:

curl --user username:password --data-binary '{"method":"getbalance","params":[]}' localhost:64223

Note, when wallet works in GUI mode it don't handle RPC. At least mine didn't. Close wallet and run it from command line:

gridcoinresearchd &

You can send rewards with sendtoaddress or sendmany. Don't forget to unlock wallet before sending. And lock after.

Gridcoin research API: https://wiki.gridcoin.us/RPC_commands
Also you could check commands for bitcoin client RPC: https://en.bitcoin.it/wiki/API_reference_%28JSON-RPC%29

That's all

Just combine that into working pool :)

All links one more time

How to obtain data from projects: https://boinc.berkeley.edu/trac/wiki/WebRpc
Setup instructions for crypt_prog: https://boinc.berkeley.edu/trac/wiki/KeySetup
How account management works: https://boinc.berkeley.edu/trac/wiki/AccountManagement
Gridcoin research API: https://wiki.gridcoin.us/RPC_commands
Also you could check commands for bitcoin client RPC: https://en.bitcoin.it/wiki/API_reference_%28JSON-RPC%29
Github of grcpool: https://github.com/bryhardt/grcpool/
One more github of grcpool: https://github.com/gustav1976/grcpool
Github of arikado pool: https://github.com/sau412/arikado_gridcoin_pool

Thanks

Thanks for @bgb for advices.

Gridcoin is an open source cryptocurrency (Ticker: GRC) which securely rewards volunteer computing performed upon the BOINC platform in a decentralized manner on top of proof of stake.

BOINC (Berkeley Open Infrastructure for Network Computing) is a distributed Internet platform and was launched beginning of 2002 and it rewards participants with credits for performed work. BOINC is an application available for multiple Operating Systems and uses the unused CPU and GPU cycles on computers to perform scientific work.