Getting Started

Step 1: Pre-login and login

The pre-login and login APIs are crucial for the security and functionality of the Proof of Bandwidth or Proof of Location system. The APIs handles initial authentication steps, like generating session tokens and validating access. These APIs are foundational for safeguarding the prover's information and controlling system access, ensuring only authenticated users can interact with critical resources

Start the process by performing a pre-login and login request

Note: The {proof_type} parameter is crucial in all API requests and must be set to one of the following values:

• pol (Proof of Location)

• pob (Proof of Bandwidth)

Be sure to specify the appropriate value based on the context of your proof request.

Pre-login

---

This API is to be called before logging in.

It will return a 'message' that has to be signed and sent to '/login' API.

This will also create a cookie;

hence the '/login' API must be called in a session.

POSThttps://api.witnesschain.com//proof/v1/{proof_type}/pre-login

Path parameters

proof_type*string

Body

application/json

publicKey*string

---

The key used for login
NOTE: when using 'ethereum' the 'publicKey = Address'

walletPublicKeyWalletPublicKey (object)

keyType*enum

---

The key-type of publicKey.

As of now these are supported keyTypes:
	1. solana
	2. ethereum

ethereumsolana

role*enum

---

The role the user intends to play after login:

	1. prover
		User who wants to prove what it offers to the network.

		Example: 'bandwidth', 'latency', 'disk', 'cpu' etc.

	2. challenger
		User who wants to challenge a 'prover'
		and earn rewards.

	3. payer
		An abstract entity/user who pays
		and requests for a challenge.

		A payer could be:
		the 'prover' itself, other users, or the blockchain.

proverchallengerpayer

projectNamestring

---

If the user is also part of another blockchain project/app,

then the project-name/app-name can be provided here.

	e.g. "filecoin", "filecoin-station", "oort", etc.

projectPublicKeystring

---

publicKey of the user associated with the

'projectName' blockchain project/app.

claims*object

---

All claims.
claims is dependent on proof_type,

Example:
	For pob it is:
	{
		uplink_bandwidth	: Float; // The upload bandwidth in Mbps
		downlink_bandwidth	: Float; // The downlink bandwidth in Mbps
	}

	for pol it is:
	{
		country		: String;	// The 2 letter country code : e.g. US
		city		: String;	// e.g. Austin 
		region		: String;	// e.g. Texas

		latitude	: Float,
		longitude	: Float,
		radius		: Float,	// in KMs - with latitude, longitude as the center
	}

Response

200400

200 response

Headers

Body

application/json

result*object

Request

JavaScriptCurlPython

const response = await fetch('https://api.witnesschain.com//proof/v1/{proof_type}/pre-login', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "publicKey": "text",
      "keyType": "ethereum",
      "role": "prover",
      "claims": {
        "{claim-parameter-1}": "text",
        "{claim-parameter-2}": "text",
        "{claim-parameter-3}": "text",
        "{claim-parameter-N}": "text"
      }
    }),
});
const data = await response.json();

Response

200400

{
  "result": {
    "message": "text"
  }
}

Login

After the result is obtained, the /login api needs to be invoked

---

This API logs in the user.

The user should send the 'message' that was received during the '/pre-login';

and must sign the 'message' using privateKey.

And send it in the 'signature' field.

POSThttps://api.witnesschain.com//proof/v1/{proof_type}/login

Path parameters

proof_type*string

Header parameters

Body

application/json

signature*string

---

The signature afer signing the 'message' with the 'privateKey'.

The signature can be created using MetaMask/Phantom wallet.

These signatures are generated through certain wallets/APIs.
	e.g.
    	1. Wallets in browser (Metamask / Phantom)

    	2. Dart
        		(https://pub.dev/packages/eth_sig_util)

    	3. Python
        		(https://pypi.org/project/eth-account/)

in Python it can be created as:

	from eth_account.messages import encode_defunct
	from eth_account import Account

	msg="<Message received from the pre-login response>"
	signature = sign(msg)

	def sign(msg):
	#
		# Hexadecimal key (private key)
		key = "<Your-Private-Key>"

		# Create the message hash
		msghash = encode_defunct(text=msg)

		# Sign the message
		signature = Account.sign_message(msghash, key)
		return "0x" + signature.signature.hex()
	#

Response

200400401402

200 response

Headers

Body

application/json

result*object

---

Successful response always has a valid 'result'.

Request

JavaScriptCurlPython

const response = await fetch('https://api.witnesschain.com//proof/v1/{proof_type}/login', {
    method: 'POST',
    headers: {
      "Cookie": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "signature": "text"
    }),
});
const data = await response.json();

Response

200400401402

{
  "result": {
    "success": false
  }
}

Step 2: Submit an on-chain Challenge Request

Refer to the following chain parameters to trigger a on-chain submitRequest

Parameters	Values
Chain ID	1237146866
Chain Kind	Polygon CDK (Validium)
Chain RPC	https://blue-orangutan-rpc.eu-north-2.gateway.fm/
Chain Block Explorer	https://blue-orangutan-blockscout.eu-north-2.gateway.fm/txs
Contract Address Proxy to interact to initiate a on-chain challenge	0x8A02C91373929a4764F015309B072DC9C9Fabc49
Function to invoke	submitRequest
Parameters to pass to submitRequest - timeout - attributeIDs - challengeInfo	For PoB, https://github.com/witnesschain-com/pox-scheduler/blob/28b305c1faad39c47ae90e159303bc68695c09a1/src/run_challenge.py#L43 For PoL, https://github.com/witnesschain-com/pox-scheduler/blob/28b305c1faad39c47ae90e159303bc68695c09a1/src/run_challenge.py#L96
Contract ABI	https://blue-orangutan-blockscout.eu-north-2.gateway.fm/address/0x39B42E1CA5F34E989Df957f4D391996266a460bB?tab=contract

We also have a sample script written in Python, to trigger a PoL or a PoB challenge.

Step 3: Trigger a Challenge with the Witness Chain Broker

Pass the challenge-id obtained in the previous step to the challenge-request-dcl API

---

Request to create a new challenge using DCL contracts.

Before calling this api 'submitRequest()' smart contract must be called.

And the 'challenge_id' after calling the 'submitRequest' must be provided.

POSThttps://api.witnesschain.com//proof/v1/{proof_type}/challenge-request-dcl

Path parameters

proof_type*string

Header parameters

Body

application/json

challenge_id*string

---

The challenge_id that was generated after calling the
DCL 'submitRequest' smart contract.

Response

200400401

200 response

Body

application/json

result*object

Request

JavaScriptCurlPython

const response = await fetch('https://api.witnesschain.com//proof/v1/{proof_type}/challenge-request-dcl', {
    method: 'POST',
    headers: {
      "Cookie": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "challenge_id": "text"
    }),
});
const data = await response.json();

Response

200400401

{
  "result": {
    "challenge_id": "text",
    "challenge_status": "SUBMITTED_TO_CHALLENGE_COORDINATOR"
  }
}

Step 4: Monitor the status of the Challenge to obtain the results

One can monitor the status of the challenge to obtain the results using the challenge-status-dcl API

---

Get the status of a given DCL challenge.

POSThttps://api.witnesschain.com//proof/v1/{proof_type}/challenge-status-dcl

Path parameters

proof_type*string

Header parameters

Body

application/json

challenge_id*string

---

The challenge_id that was generated after calling the
DCL 'submitRequest' smart contract.

Response

200400401

200 response

Body

application/json

id*string

---

The challenge id

challenge_parameters*object

---

The parameters of this challenge

The other-challenge_parameters depend on proof_type.

For pob it is:

	rate_of_packets_mbps		: Integer, // rate at which packets will arrive from a challenger
	max_packets_per_challenger		: Integer, // max packets that a challenger can send
	total_num_packets_for_challenge	: Integer  // total packets that a prover should receive

challenge_start_time*string

challenge_end_time*string

consolidated_result*object

---

The result collected and consolidated from the challengers

The consolidated-result-parameters depend on on proof_type.

For pol it is:

 KnowLock	: boolean,	// (web3) if KnowLock was able to validate the location
	"ipapi.co"	: boolean,	// (web2) if ipapi.co api was able to validate the location
	ipregistry	: boolean,	// (web2) if ipregistry api was able to validate the location
	maxmind	: boolean 	// (web2) if maxmind api was able to validate the location

prover*object

---

Prover details

state*enum

---

The current state of the challenge

SUBMITTED_TO_CHALLENGE_COORDINATORACCEPTED_BY_CHALLENGE_COORDINATORERROR_NOT_ENOUGH_CHALLENGERSENDED_WITH_PARTIAL_SUCCESSERROR_ENDED_WITH_FAILUREENDED_SUCCESSFULLY

Request

JavaScriptCurlPython

const response = await fetch('https://api.witnesschain.com//proof/v1/{proof_type}/challenge-status-dcl', {
    method: 'POST',
    headers: {
      "Cookie": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "challenge_id": "text"
    }),
});
const data = await response.json();

Response

200400401

{
  "id": "text",
  "challenge_parameters": {
    "{other-challenge-parameter-1}": "text",
    "{other-challenge-parameter-2}": "text",
    "{other-challenge-parameter-3}": "text",
    "{other-challenge-parameter-N}": "text"
  },
  "challenge_start_time": "text",
  "challenge_end_time": "text",
  "consolidated_result": {
    "{consolidated-result-parameter-1}": "text",
    "{consolidated-result-parameter-2}": "text",
    "{consolidated-result-parameter-3}": "text",
    "{consolidated-result-parameter-N}": "text"
  },
  "prover": {
    "claims": {
      "{claim-parameter-1}": "text",
      "{claim-parameter-2}": "text",
      "{claim-parameter-N}": "text"
    }
  },
  "state": "SUBMITTED_TO_CHALLENGE_COORDINATOR"
}