API

Customer API for on-prem ZeKnow Solv product

Sequence Diagram

API Endpoints

Upload Snapshot

POST /upload_snapshot

Upload the latest snapshot of the relevant blockchains from which the balance of a blockchain address can be retrieved. To retrieve the latest snapshot:

• Daily snapshots of the blockchain are available on our website at the following url: https://artifacts.proven.tools/snapshots/YYYY-MM-DD/snapshots.tar

• The snapshot includes two directories, snapshot_v1 and snapshot_v2, each of which contains four files:

  • btc_pubkeyhash_public_addrs.csv

    • The top 32767 BTC addresses that are either P2PKH or P2WPKH format.

  • btc_scripthash_public_addrs.csv

    • The top 32767 BTC addresses that are either P2SH or P2WSH format. (Multisig BTC addresses will live in this snapshot file).

  • eth_public_addrs.csv

    • The top 32767 ETH addresses.

  • xrp_public_addrs.csv

    • Dummy snapshot until full XRP support.

List Proofs

GET /list_proofs

Retrieve a list of all proofs that have been submitted to the API, and relevant metadata for the proof including whether or not the proof computation is finished.

Get Proof Data

GET /get_proof_data/<proof_id>

Returns a JSON object with all relevant metadata for a given proof ID, including whether or not the proof computation is finished.

Get Receipt Data

GET /get_receipt_data/<proof_id>

Returns a list of JSON objects specifying the receipts generated for each user in the specified proof ID.

Get Smart Contract Transaction

GET /get_smart_contract_transaction/<proof_id>

Retrieve a formatted transaction payload which can be sent to the ZeKnow Solv smart contract for checking and validation.

Run Proof

POST /run_proof

Submit a new proof for the API to compute. The proof uses the most recent uploaded snapshot. At least one snapshot must be uploaded before a proof can be generated. Takes the following arguments via POST request:

• accounts: a file containing a list of JSON objects, where each object specifies a user and their account balances. Currently our protocol supports ETH and BTC account balances. Each JSON object in the list should have the following key/value pairs:

  • username The username / unique identifier for the account

  • balances A dictionary of the form [ {”token”: “BTC”, “balance”: 1000 } ] specified in the coin’s smallest denomination (satoshis, wei, etc).

• addrs: a file containing a JSON object specifying the blockchain addresses owned by the exchange. The JSON object in the addrs file should be a list of sub-JSON objects, where each inner JSON object corresponds to a specific address. An inner JSON object has the following key-value pairs:

  • chain: References the L1 chain for the address of the wallet (e.g. ‘BTC’, ‘ETH’, ‘XRP’)

  • address: The address of the wallet (in the case of BTC assets this is specified in base52, in the case of ETH assets this is specified in hex)

  • EITHER

    • signature: This is a signature of the message body “zeknow solv owner” from this address.

  • OR

    • script This is the script in the case of a k-of-n multisig BTC script. It should start something like 5X21…

    • signatures This is a list of k valid signatures of the message body“zeknow solv owner” from this wallet. See below for details

The post request returns { “proof_id”: <proof_id> } if the inputs are formatted properly and if the computation for a new proof is successfully initiated. Otherwise, the return value is an error message.

The above information is also available in an OpenAPI 3.0 specification and associated Postman collection.

Signature Specifications:

The message body to sign is: “zeknow solv owner”

• For Ethereum: Follow the EIP 191 spec to sign the message body

• For Bitcoin:

  • Apply msg magic "\\x18Bitcoin Signed Message:\\n" + chr( len(msg_body) ) + msg_body

  • Take this result and hash it twice with SHA-256

  • ECDSA sign this msgHash (from at least k of the n private keys if this is a k-of-n address)