claim-backend

Claim Backend

This package supplies Leaf details to frontend by providing an endpoint that responds with details necessary for the claim. It also stores partial signatures of claims from multisig addresses. Details of Leaf can be obtained from Tech Design.

Additional Requirement

Apart from Node version 18, Claim Backend also requires:

1. Docker (Latest Version Recommended) or
2. PostgreSQL (Latest Version Recommended)

.env Params

param	Description	Required
BACKEND_HOST	IP used by backend (Default: 127.0.0.1)	false
BACKEND_PORT	Port used by backend (Default: 3000)	false
BACKEND_LOGGER_LEVEL	Logger level in backend (trace/debug/info/warn/error/fatal) (Default: info)	false
DB_PORT	Port used by PostgreSQL DB (Default: 5432)	false
DB_HOST	Host used by PostgreSQL DB (Default: 127.0.0.1)	false
DB_DATABASE	Name of Database of PostgreSQL DB (Default: claim-backend)	false
DB_USERNAME	Username of PostgreSQL DB (Default: claim-backend)	false
DB_PASSWORD_PATH	Absolute file path or file path relative to docker-compose.yaml that stores the password of database of PostgreSQL DB (Default: ./db_password.txt)	false
DB_SSLMODE	A flag to turn on SSL Connection on DB (Default: false)	false
DB_SSL_CERT_PATH	Path to SSL Certificate (.crt or .pem) (Default: null)	When DB_SSLMODE is True
DB_LOGGING	A flag to turn on verbose logging of DB (Default: true)	false
CORS_ORIGIN	Accepted Origin, can be string or Regex (Default: *)	false
MERKLE_TREE_PATH	Path merkle-tree-details.json, generated by Tree Builder	true

Run

# Enter claim-backend package
cd packages/claim-backend

# Install dependencies
yarn

# Make a copy of .env.example
cp .env.example .env

# Edit .env regarding to ".env Params"
(nano|vim|emacs) .env

# Create secret for Docker DB Password
echo -n $(openssl rand -hex 16) > db_password.txt

# Start postgres locally
docker-compose up -d

# Start Claim Backend
yarn server

Endpoints

/checkEligibility

It accepts POST request with param lskAddress. If the address is eligible for claiming some LSK, it will return the amount of tokens (under account), proof and, should this address match to any public key of a multisignature account, it will also be displayed here (under multisigAccounts).

signatures field stores valid signatures of addresses in multiAccounts, which are previously submitted by /submitMultisig.

For multisig addresses, there is a ready flag to determine if the claim is ready.

Sample Request

curl --location 'http://127.0.0.1:3000/rpc' \
--header 'Content-Type: application/json' \
--data '{
    "jsonrpc": "2.0",
    "method": "checkEligibility",
    "params": {
        "lskAddress": "lskfcu7z7sch46o67sq24v9h9df2h5o2juvjp3fjj"
    },
    "id": 1
}'

Sample Response

{
  "account": {
    "lskAddress": "lskfcu7z7sch46o67sq24v9h9df2h5o2juvjp3fjj",
    "address": "0xf0e0e03b63ea54c53b75c244deb75ec756cc7202",
    "balanceBeddows": "865518296094",
    "numberOfSignatures": 0,
    "mandatoryKeys": [],
    "optionalKeys": [],
    "hash": "0x99ceb57a2b44f7788e14f147f6bce45b4b59ac778467e4234a090289e4e1be95",
    "proof": [
      ...
    ]
  },
  "multisigAccounts": [{
    "lskAddress": "lskf9t4eho3cayhhp7k5rruu4g7gr8yzo9b6yg4s4",
    "address": "0xf3669b75881e63de91d45ca50827eefc9f1031a6",
    "balanceBeddows": "551573764672",
    "numberOfSignatures": 2,
    "mandatoryKeys": [
      "0x83eac294606806e0f4125203e2d0dac5ef1fc8730d5ec12e77e94f823f2262fa"
    ],
    "optionalKeys": [
      "0xc75fd8d6cdb26f53f1fc9d16b5361099ae73907dfbfba112c6dcc94b5afbb600",
      "0x0824f95c67a1bf7726a928db60d9966ad644d3a50f135d8c2bc7862cf08ea5b1"
    ],
    "hash": "0x99ceb57a2b44f7788e14f147f6bce45b4b59ac778467e4234a090289e4e1be95",
    "proof": [
        ...
    ],
    "ready": false
  }],
  "signatures": []
}

/submitMultisig

After the user has signed a claim message for a multisignature account, this API will be called to store the signature at the backend DB.

If this endpoint is submitted by the last signer of the multisig account, the 200 response will show "ready": true. In that case the UI could call /checkEligibility again to obtain all signatures and submit the claim transaction.

Sample Request

curl --location 'http://127.0.0.1:3000/rpc' \
--header 'Content-Type: application/json' \
--data '{
    "jsonrpc": "2.0",
    "method": "submitMultisig",
    "params": {
        "lskAddress": "lskfcu7z7sch46o67sq24v9h9df2h5o2juvjp3fjj",
        "destination": "0x34A1D3fff3958843C43aD80F30b94c510645C316",
        "publicKey": "0x83eac294606806e0f4125203e2d0dac5ef1fc8730d5ec12e77e94f823f2262fa",
        "r": "0xeb7bae6ec3996e38c159e37ad270088d06b19642ea1a7112cc21a6e06b0e756a",
        "s": "0x165ee91a3a7e66a1abae1721e80105329922f7e8621bbd382c4d1e95365eeb02"
    },
    "id": 1
}'

Sample Response

{
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
      "success": true,
      "ready": true
    }
}

Logging

Claim Backend uses log4js to record API call logs. 3 categories of logs will be used:

• default
  • INFO: General logging during the start of backend.
• RPC
  • INFO: When sending success RPC response to client.
  • WARN: When sending an Error RPC response to client, e.g. Invalid LSK address is queried.
• HTTP
  • DEBUG: When there is a valid incoming HTTP request.
  • WARN: When there is an error in clients' incoming HTTP request, e.g. Incorrect Json format.
  • ERROR: When there is uncaught error on backend side.

By setting BACKEND_LOGGER_LEVEL, it is possible to adjust which level of logging should be recorded.