Prosopo Provider

NOTE: For a development environment, the easiest way to deploy the Prosopo contract and run the Provider node is via the integration repository. The following instructions explain how to set up the repositories manually.

Prerequisites

nodejs
npm
A connection to a substrate node
A deployed Prosopo Protocol contract

Development Environment

Setup a contract node

If you are setting up a development environment, run a development node. For example, the Substrate Contracts Node

Deploy the Prosopo Protocol contract

See protocol instructions

Live environment

If you are running in a test or live environment, use a node endpoint of your choice. Make sure you know the contract account of the Prosopo Protocol contract.

Running a Prosopo Provider Node

The following instructions apply to the provider repo.

Install packages

npm install

Populate the Prosopo Provider Config

Place the required variables in the prosopo.config.ts file in the root of the provider repo.

Param	Description
PROTOCOL_CONTRACT_JSON_ABI_PATH	The path to the protocol JSON file
SUBSTATE_NODE_ENDPOINT	The substrate node endpoint, e.g. ws://localhost:9944
PROTOCOL_CONTRACT_ADDRESS	The protocol contract address
CAPTCHA_SOLVED_COUNT	The number of solved captchas to send to the captcha frontend client
CAPTCHA_UNSOLVED_COUNT	The number of unsolved captchas to send to the captcha frontend client
CAPTCHA_SOLUTION_REQUIRED_SOLUTION_COUNT	The number of captchas required to calculate a solution to an unsolved captcha
CAPTCHA_SOLUTION_WINNING_PERCENTAGE	The threshold percentage that determines whether a solution is found
CAPTCHA_FILE_PATH	The path to the captcha dataset
MONGO_USERNAME	MongoDB username
MONGO_PASSWORD	MongoDB password
MONGO_HOST	MongoDB host
MONGO_PORT	MongoDB port
DATABASE_NAME	Database name
API_BASE_URL	Base URL for API, e.g. http://localhost:3000

Config

const config = {
  contract: {
    abi: '<PROTOCOL_CONTRACT_JSON_ABI_PATH>'
  },
  networks: {
    development: {
      endpoint: '<SUBSTATE_NODE_ENDPOINT>', // e.g. ws://127.0.0.1:9944
      contract: {
        address: '<PROTOCOL_CONTRACT_ADDRESS>',
        name: 'prosopo'
      }
    }
  },
  captchas: {
    solved: {
      count: '<CAPTCHA_SOLVED_COUNT>'
    },
    unsolved: {
      count: '<CAPTCHA_UNSOLVED_COUNT>'
    }
  },
  captchaSolutions: {
    requiredNumberOfSolutions: '<CAPTCHA_SOLUTION_REQUIRED_SOLUTION_COUNT>',
    solutionWinningPercentage: '<CAPTCHA_SOLUTION_WINNING_PERCENTAGE>',
    captchaFilePath: '<CAPTCHA_FILE_PATH>',
  },
  database: {
    development: {
      type: 'mongo',
      endpoint: `mongodb://<MONGO_USERNAME>:<MONGO_PASSWORD>@<MONGO_HOST>:<MONGO_PORT>`,
      dbname: '<DATABASE_NAME>',
    }
  },
  assets : {
    absolutePath: '',
    basePath: ''
  },
  server : {
    baseURL: '<API_BASE_URL>',
  }
}

Run the Provider server

Set a provider mnemonic in prosopo.config.js

Please note your PROVIDER_MNEMONIC environment variable must be set. You can check this with echo $PROVIDER_MNEMONIC

In a development environment, it's easiest to use a development mnemonic as they already have funds. So choose one of //Alice, //Bob, //Ferdie, etc.

    export PROVIDER_MNEMONIC=//Ferdie

You can now register as a Provider in the protocol contract either via the command line.

Register using the Command Line

Try registering a provider on the command line.

npm run cli provider_register -- \
--fee 10 \
--origin https://localhost:8282 \
--payee Provider \
--address YOUR_PROVIDER_ADDRESS

Send a stake (value) and/or update one of the values previously set when registering (fee, origin. payee).

npm run cli provider_update -- \
--fee 10 \
--origin https://localhost:8282 \
--payee Provider \
--address YOUR_PROVIDER_ADDRESS \
--value 10

Verify that your provider was registered by calling the /v1/prosopo/providers/ endpoint or by checking in Polkadot Apps local node.

Curl

curl --location --request GET '127.0.0.1:3000/v1/prosopo/providers/'
{"accounts":["YOUR PROVIDER ADDRESS"]}

Polkadot Apps

Using Polkadot apps

Click Add an existing contract
Enter the contract address and click to select the prosopo.json file in the artifacts folder as the contract ABI
Expand the contract to see the current value of getProviders. It should be ["YOUR PROVIDER ADDRESS"].

Command Line Interface

Please note your PROVIDER_MNEMONIC environment variable must be set. You can check this with echo $PROVIDER_MNEMONIC

Register a provider

npm run cli -- provider_register --fee=10 --origin=https://localhost:8282 --payee=Provider --address ADDRESS

Param	Description
fee	The amount the Provider charges or pays per captcha approval / disapproval
origin	The location of the Provider's service
payee	Who is paid on successful captcha completion (`Provider` or `Dapp`)
address	Address of the Provider

Update a provider and optionally stake

npm run cli -- provider_update --fee=10 --origin=https://localhost:8282 --payee=Provider --address ADDRESS --value STAKE_VALUE

Params are the same as provider_register with the addition of value

Param	Description
value	The amount of funds to stake in the contract

Add a dataset for a Provider

npm run cli -- provider_add_data_set --file /usr/src/data/captchas.json

Param	Description
file	JSON file containing captchas

File format can be viewed here.

De-register a Provider

npm run cli -- provider_deregister --address ADDRESS

Param	Description
address	Address of the Provider

Unstake funds

npm run cli -- provider_unstake --value VALUE

Param	Description
value	The amount of funds to unstake from the contract

List Provider accounts in contract

npm run cli -- provider_accounts

Other commands

A full list of CLI commands can be viewed by running

npm run cli -- --help

API

Run the Provider API server and image server

npm run start

The API contains methods required by the frontend captcha interface.

API Resource	Function	Type	Parameters
`/v1/prosopo/random_provider/:userAccount/:dappContractAccount`	Get a random provider based on AccountId	GET	userAccount, dappContractAccount
`/v1/prosopo/providers/`	Get list of all provider IDs	GET
`/v1/prosopo/dapps/`	Get list of all dapp IDs	GET
`/v1/prosopo/provider/:providerAccount`	Get details of a specific Provider account	GET	providerAccount
`/v1/prosopo/provider/captcha/:datasetId/:userAccount/:dappContractAccount/:blockNumber`	Get captchas to solve	GET	datasetId, userAccount, dappContractAccount, blockNumber
`/v1/prosopo/provider/solution`	Submit captcha solutions	POST	userAccount, dappAccount, requestHash, captchas, blockHash, txHash

Tests

You can run the Provider integration tests using the command npm run test. This will start a substrate container containing a predeployed prosopo protocol contract and dapp-example contract. An in-memory mongo database will be used.

To run the tests with coverage stats use:

npx c8 npm run test