Skip to content

Create and set up a core client

This section presents the Qredo Core Client and illustrates its intended use for automated custody.

The Core Client is a standalone custodian service. Every core client has a unique ID and uses a dedicated subset of the API to perform its functions. You can plug in with your client ID to a websocket feed that listens for transactions pending approvals. Also, you can create a programmable custodian bot that uses a core client instance to perform automated custody.

This topic covers the API custody on transfer out transactions. The Core Client must be appointed as a custodian of a wallet (or fund). You will learn how to fetch, approve or reject pending transactions out of such a wallet. Using core client instance for an exchange is described in the Get started with exchanges section.

The core client performs custody over transfer out transactions

The core client acts just like a human custodian, which means they approve or reject all transaction types that move assets out of a Qredo wallet:

  • transfer - (also transfer out) a transaction between wallets that both reside on the Qredo Network: a L2 to L2 transaction.
  • withdrawal - a transaction where assets in a Qredo wallet move to a wallet outside the Qredo Network (BTC, ETH, etc.): a L2 to L1 transaction).
  • atomic swap - a transfer out transaction where you offer a certain amount of an asset in exchange for a (transfer in) certain amount of another asset. (e.g. exchange 100000000 ETH qweis for 735601 satoshis). Both parties that participate have a transfer out transaction that undergoes custody with their custodians. This transaction type is discussed in more detail in the Atomic swaps section.

To complete this section, you must:

  1. Create a core client using the POST /coreclient Partner API resource.
  2. Add the core client as a trusted party of a company. You will use the POST /trustedparty to add the core client to the trusted network of your company, similar to Partner API quick start Step 2.
  3. Create a wallet (or a fund, as explained in the Partner API quick start walkthrough step 3. Create a fund) with the core client as a trusted party.

As you see, the core client undergoes a process very similar to that of the human custodian.

1. Create a Core Client

This step discusses the addition of a single core client but you can use the same API resource to add as many as you want to have.

Example request: POST /coreclient

This example creates a coreclient named "Custodian-Bot-01". The response returns the client id and the websocket feed. Note that you will need the id as a query parameter with custodial API endpoints.

curl -X POST "https://api.qredo.network/api/v1/p/coreclient"

Request body

Specify the name of your core client. This name is for human-readable info only: you identify your core client in the API using its only ID.

{
  "name": "Custodian-Bot-01"
}

Example response: POST /coreclient

Upon success, the response notably returns the core id and the unique websocket feed.

{
  "id": "9niR8TyupNQXXXXXXXXXXXXXXXXqiekNQCqkmHGRW3xu",
  "name": "Custodian-Bot-01",
  "feed": "wss://api.qredo.network/api/v1/p/coreclient/9niR8TyupNQXXXXXXXXXXXXXXXXqiekNQCqkmHGRW3xu/feed",
  "timestamp": "<Epoch timestamp when core client is created, e.g. '1635258443' >"
}

The example includes the suggested id and feed.

Use the id and feed URL to connect your websocket and perform custody

  • You identify your core client by its id to fetch pending transactions or perform custody. This is the same as the client_id with most API calls that are part of the /coreclient endpoint.
  • Save the feed URL to connect the core client.

2. Enlist the core client as a trusted party

You must follow a process very similar to Step 2: Add a trusted party of the Partner API quick start walkthrough.

Again, you will use the POST /trustedparty API resource. The difference here is that, this time, you will not submit a person's email address in the API call body, but the core id instead.

Example request: POST /trustedparty

This example submits an enrollment request to add as a custodian the core client with the id as returned from the previous step. With this API resource, you pass company_id as a URL parameter.

curl -X POST "https://api.qredo.network/api/v1/p/company/{company_id}/trustedparty"

Request body

Unlike when adding a human custodian, you obviously don't specify core client by an email address but with the core client id.

{"address": "9niR8TyupNQXXXXXXXXXXXXXXXXqiekNQCqkmHGRW3xu"}

Example response: POST /trustedparty

A successful response returns a HTTP 200 OK confirmation. The appointed user will receive a notification on their mobile device with the Qredo signing app installed. No JSON payload is passed with the response.

Unlike when adding a human user account, no confirmation is required and this step is already completed.

Verify that the Core Client is n enlisted custodian

You can verify this by using the familiar GET /trustedparty API resource to return all trusted parties with your company.

The response returns core id as a trusted_entity_id

The example response includes the human Qredo account custodian as "type":"user". The core client is represented as "type":"core-client" and its core id is the value for the trusted_entity_id and address parameters.

{
  "company_id": "1zgaeXXXXXXXXXXXXXXXX6YgVBl",
  "total_count": 2,
  "list": [
    {
      "trusted_entity_id": "13DCSmrasFk84U7QXXXXXXXXXXXXXXXXGuJXf4AvDiag",
      "name": "John Smith",
      "address": "[email protected]",
      "type": "user",
      "created": 1634727142
    },
    {
      "trusted_entity_id": "9niR8TyupNQXXXXXXXXXXXXXXXXqiekNQCqkmHGRW3xu",
      "name": "Demo Core Client",
      "address": "9niR8TyupNQXXXXXXXXXXXXXXXXqiekNQCqkmHGRW3xu",
      "type": "core-client",
      "created": 1635427044
    }
  ]
}   

3. Create a wallet with the core client as a trusted party

You can create a new fund (with one or more wallets) and appoint the core client as a trusted party member with global custodial policies. This example, however, creates a new wallet, part of an existing fund. The custodial policies of the new wallet appoint the core client as member, using its client id.

Example request: POST /wallet

This examples creates a ETH-Testnet wallet with custom custodial policies with the core client added as a member. With this API resource, you pass company_id and fund_id as URL parameters.

Request body

Specify the wallet name and asset, as well as the custodial policies. Each custodial policy in this example includes a core id and a trusted_party_id, with a threshold set to 1. In this way a single Core Client can approve transfers and withdrawals with this wallet.

This example adds a human custodian as well

To reduce the risk of getting your assets "stuck" in your wallet, Qredo recommends that you also appoint the necessary (threshold) number of human custodians ("type": "user"). Remember that a transaction on the Qredochain cannot be processed without undergoing custody.

{
  "wallets": [
    {
      "name": "Core Client custody wallet",
      "asset": "ETH-TESTNET",
      "custodygroup_withdraw": {
        "threshold": 1,
        "members": [
          "9niR8TyupNQXXXXXXXXXXXXXXXXqiekNQCqkmHGRW3xu",
          "13DCSmrasFk84U7QXXXXXXXXXXXXXXXXGuJXf4AvDiag"
        ]
      },
      "custodygroup_tx": {
        "threshold": 1,
        "members": [
          "9niR8TyupNQXXXXXXXXXXXXXXXXqiekNQCqkmHGRW3xu",
          "13DCSmrasFk84U7QXXXXXXXXXXXXXXXXGuJXf4AvDiag"
        ]
      }
    }
  ]
}

Example response: POST /wallet

The response returns the ID of the created wallet.

{
  "wallets": [    
    "GTci7tG5M9Cs8HXXXXXXXXXXXXXXXXokcn8dZs2tPc7i"
  ]
}

Wallet ID vs wallet address

Wallet ID is pertinent to Qredo network only. Do not mistake this ID with the wallet address. In terms of Qredo, a wallet address is used only when moving assets from L1 blockchain to Qredochain (deposits), or vice versa: from Qredochain to L1 blockchain (withdrawals). Only deposit wallets have addresses. In all API calls for moving assets within the Qredo Network, or query wallet details, use this wallet_id parameter.

From this point on, you need to deposit assets to your wallets, as described in step 4. Perform a deposit of the Partner API quick start walkthrough.

Next, you connect the core client to a websocket feed service and start listening for transaction requests pending custody.


Last update: 2021-12-17