Authentication

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 requesttart 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) -> Currently supported

• pob (Proof of Bandwidth)

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.

post

/proof/v1/{proof_type}/pre-login

Authorizations

Path parameters

proof_typestringrequired

Body

publicKeystringrequired

---

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

walletPublicKeyobject

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.

keyTypestring · enumrequired

---

The key-type of publicKey.

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

Options: ethereum, solana

rolestring · enumrequired

---

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.

Options: prover, challenger, payer

claimsobjectrequired

---

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
	}

Responses

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.witnesschain.com//proof/v1/{proof_type}/pre-login' \
  --header 'Cookie: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"publicKey":"text","walletPublicKey":{"solana":"text","ethereum":"text"},"keyType":"ethereum","role":"prover","claims":{}}'

200

400

200

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

200 response

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.

post

/proof/v1/{proof_type}/login

Authorizations

Path parameters

proof_typestringrequired

Header parameters

Cookiestringrequired

---

The cookies that were received after calling '/pre-login' API.

Body

signaturestringrequired

---

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()
	#

Responses

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api.witnesschain.com//proof/v1/{proof_type}/login' \
  --header 'Cookie: text' \
  --header 'Content-Type: application/json' \
  --data '{"signature":"text"}'

200

400

401

402

200

{
  "result": {
    "success": true
  }
}

200 response