APIs

List of Challenge Coordinator APIs

The GitBook API is currently in alpha. It's not opened to developers just yet.

Following are the list of Challenge Coordinator APIs that the PoB client (prover or challenger) uses to

• Authenticate

• Get the list of Provers

• Request a Challenge

• Get the Challenge Status

• Publish the results of the challenge

---

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://pob.witnesschain.com/api/pre-login

Body

application/json

publicKey*string

---

The key used for login

proof_type*string

---

The kind of proof the user wishes to participate in.
Valid values are : "pob" and "pol"

walletPublicKeyWalletPublicKey (object)

keyType*enum

---

The key-type of publicKey.

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

solana

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.

Response

200400

200 response

Headers

Body

application/json

result*object

Request

JavaScriptCurl

const response = await fetch('https://pob.witnesschain.com/api/pre-login', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "publicKey": "text",
      "proof_type": "text",
      "keyType": "solana",
      "role": "prover",
      "claims": {
        "bandwidth": 0
      }
    }),
});
const data = await response.json();

Response

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

---

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://pob.witnesschain.com/api/login

Header parameters

Body

application/json

message*string

---

The 'message' received in the '/pre-login' API.

signature*string

---

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

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

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

		3. Python
			(solana   : https://pypi.org/project/solana)

Response

200400401402

200 response

Headers

Body

application/json

result*object

---

Successful response always has a valid 'result'.

Request

JavaScriptCurl

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

Response

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

---

Get logged in user information.

POSThttps://pob.witnesschain.com/api/user-info

Header parameters

Response

200

200 response

Body

application/json

result*object

Request

JavaScriptCurl

const response = await fetch('https://pob.witnesschain.com/api/user-info', {
    method: 'POST',
    headers: {},
});
const data = await response.json();

Response

{
  "result": {
    "publicKey": "text"
  }
}

---

Logs out the user.

POSThttps://pob.witnesschain.com/api/logout

Response

200

200 response

Body

application/json

result*object

---

Successful response always has a valid 'result'.

Request

JavaScriptCurl

const response = await fetch('https://pob.witnesschain.com/api/logout', {
    method: 'POST',
    headers: {},
});
const data = await response.json();

Response

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

---

Get information about a prover.

POSThttps://pob.witnesschain.com/api/prover

Header parameters

Body

application/json

id*string

---

The 'id' of the prover.

Response

200400401

200 response

Body

application/json

result*ProverDetails (object)

Request

JavaScriptCurl

const response = await fetch('https://pob.witnesschain.com/api/prover', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "id": "text"
    }),
});
const data = await response.json();

Response

{
  "result": {
    "id": "text",
    "geoip": {
      "range": [],
      "country": "text",
      "region": "text",
      "eu": "0",
      "timezone": "text",
      "city": "text",
      "ll": [
        0
      ]
    },
    "last_alive": "2024-07-27T08:36:34.675Z",
    "bandwidth_claimed": 0,
    "results": [
      {
        "result": [
          {
            "bandwidth": 0,
            "latency": 0
          }
        ],
        "message": "text",
        "signature": "text",
        "challenger": "text",
        "challenge_start_time": "2024-07-27T08:36:34.675Z"
      }
    ]
  }
}

---

Get all provers info.

POSThttps://pob.witnesschain.com/api/provers

Header parameters

Response

200401

200 response

Body

application/json

result*object

Request

JavaScriptCurl

const response = await fetch('https://pob.witnesschain.com/api/provers', {
    method: 'POST',
    headers: {},
});
const data = await response.json();

Response

[
  {
    "result": {
      "provers": [
        {
          "id": "text",
          "geoip": {
            "range": [],
            "country": "text",
            "region": "text",
            "eu": "0",
            "timezone": "text",
            "city": "text",
            "ll": [
              0
            ]
          },
          "last_alive": "2024-07-27T08:36:34.675Z",
          "bandwidth_claimed": 0,
          "results": [
            {
              "result": [
                {
                  "bandwidth": 0,
                  "latency": 0
                }
              ],
              "message": "text",
              "signature": "text",
              "challenger": "text",
              "challenge_start_time": "2024-07-27T08:36:34.675Z"
            }
          ]
        }
      ]
    }
  }
]

---

Request to create a new challenge.

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

And the 'transaction' after calling the 'startChallenge' must be provided.

POSThttps://pob.witnesschain.com/api/pob/challenge-request

Header parameters

Body

application/json

prover*string

---

The 'id' of the prover.

transaction*string

---

The transaction that was generated after calling the
'startChallenge' smart contract.

Response

200400401

200 response

Body

application/json

result*object

Request

JavaScriptCurl

const response = await fetch('https://pob.witnesschain.com/api/pob/challenge-request', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "prover": "text",
      "transaction": "text"
    }),
});
const data = await response.json();

Response

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

---

Get the status of a given challenge.

POSThttps://pob.witnesschain.com/api/pob/challenge-status

Header parameters

Body

application/json

transaction*string

---

The transaction that was generated after calling the
'startChallenge' smart contract.

Response

200400401

200 response

Body

application/json

result*object

Request

JavaScriptCurl

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

Response

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

---

Post the results of a challenge.

POSThttps://pob.witnesschain.com/api/pob/challenge-result

Header parameters

Body

application/json

message_type*enum

challenge_result

message*string

---

The result of a challenge - a JSON converted to a string.

e.g. in JavaScript:

	message = JSON.stringify ({
		challenge_id,
		result,
	});

The result contains fields that have been measured

by the challenger:

	like "bandwidth" and "latency".

signature*string

---

The 'message' string signed using privateKey.

Response

200400401

200 response

Body

application/json

result*object

---

Successful response always has a valid 'result'.

Request

JavaScriptCurl

const response = await fetch('https://pob.witnesschain.com/api/pob/challenge-result', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "message_type": "challenge_result",
      "message": "text",
      "signature": "text"
    }),
});
const data = await response.json();

Response

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

---

Claim that the 'user' has certain bandwidth in Mbps.

POSThttps://pob.witnesschain.com/api/pob/claims

Header parameters

Body

application/json

bandwidth*number (float)

---

The amount of bandwidth in Mbps the user has
	OR
wants to claim.

Response

200400401

200 response

Body

application/json

result*object

---

Successful response always has a valid 'result'.

Request

JavaScriptCurl

const response = await fetch('https://pob.witnesschain.com/api/pob/claims', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "bandwidth": 0
    }),
});
const data = await response.json();

Response

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

---

A websocket connection for:

	1. Sending heartbeat (websocket ping).
	2. Receiving notification regarding challenges.

GEThttps://pob.witnesschain.com/api/ws

Header parameters

Response

101201202401

---

This opens up a websocket connection.

This response is the successful response.

Headers

Request

JavaScriptCurl

const response = await fetch('https://pob.witnesschain.com/api/ws', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

---

Get user's IP addresses as seen by the challenge co-ordinator

POSThttps://pob.witnesschain.com/api/ip-info

Header parameters

Response

200

200 response

Body

application/json

result*object

Request

JavaScriptCurl

const response = await fetch('https://pob.witnesschain.com/api/ip-info', {
    method: 'POST',
    headers: {},
});
const data = await response.json();

Response

{
  "result": {
    "IPv4": "text",
    "IPv6": "text"
  }
}

---

Get PoB statistics on 'provers' and 'challengers'.

POSThttps://pob.witnesschain.com/api/pob/statistics

Header parameters

Response

200

200 response

Body

application/json

result*object

Request

JavaScriptCurl

const response = await fetch('https://pob.witnesschain.com/api/pob/statistics', {
    method: 'POST',
    headers: {},
});
const data = await response.json();

Response

{
  "result": {}
}

---

Get the latest released version information on various software

POSThttps://pob.witnesschain.com/api/release-info

Header parameters

Response

200

200 response

Body

application/json

result*object

Request

JavaScriptCurl

const response = await fetch('https://pob.witnesschain.com/api/release-info', {
    method: 'POST',
    headers: {},
});
const data = await response.json();

Response

{
  "result": {
    "pob_prover_client": "text",
    "pob_challenger_client": "text"
  }
}