Skip to content

Step 3: Create a fund

A fund is the sub-entity to the company that contains one or more wallets and defines the custodial policies for transfers and withdrawals of assets out of these wallets. With Qredo, a wallet always belongs to a fund and any transaction that moves assets out of a given Qredo wallet, undergoes custody.

Custody on Qredo

  • On the Qredo Network, when assets move out of a wallet, they undergo custody. This includes assets that move within the Qredo L2 Network (defined as Transfers) and assets that move out of the Qredo Network (defined as Withdrawals).
  • Custody applies according to the applicable custodial policies, configured either at the Fund level (also called a global policy), or per a wallet in that fund (a custom policy).
  • Custody on Qredo means that a minimum of enlisted approvers must provide their approval for a transaction to go through.

Fund definition

In terms of the Partner API, a fund definition contains:

  • a custodial policy for approving withdrawals: custodygroup_withdraw. The policy consists of its own list of appointed approvers and a threshold value: the number of required approvals.
  • a custodial policy for approving transfer transactions: custodygroup_tx. The policy consists of its own list of appointed approvers and a threshold value: the number of required approvals.
  • one or more wallets (per asset, such as BTC or ETH). Your wallet definition can optionally include custom custodial policies that override the fund custodial policies.

If a wallet does not have (one or both) custodial policies defined, the global one(s) apply. In other words, a wallet with no custom custodial policies inherits the fund custodial policies. You are not required to add custom (per wallet) custodial policies.

To be able to to perform transactions on the Qredo network, a company must have at least one fund with at least one wallet per asset type (BTC or ETH, etc.).

Your company can have multiple funds and each has its own policy. There is no limitation to use the same trusted parties across different funds.

A fund can have multiple wallets. It is up to you to define a structure that suits your purposes and use cases.

Your fund and wallets are not visible in Web app

Similar to the company and trusted parties, the funds (and wallets) you create in the API will not be visible in the Web app.

Create a fund

To complete this step, you must use the POST /fund to create your fund. Along with a fund name, you will add custodial policies and wallets to your fund.

Example request: POST /fund

This example creates a fund named "Awesome fund" that contains the following definitions:

  • a custodygroup_withdraw policy with threshold set to 2 and 3 specified trusted network members.
  • a custodygroup_tx policy with threshold set to 3 and 4 specified trusted network members.
  • two wallets: one with global custodial policies and and one with custom custodial policies.

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}/fund" 

Request body

The following top-level parameters are required: name, description, custodygroup_withdraw, custodygroup_tx. You can add more wallets at a later stage but, once created, you cannot remove wallets.

{
  "name": "Awesome fund",
  "description": "A demo fund",
  "custodygroup_withdraw": {
    "threshold": 3,
    "members": [
      "<withdrawal trusted party01 id>",
      "<withdrawal trusted party02 id>",
      "<withdrawal trusted party03 id>"
    ]
  },
  "custodygroup_tx": {
    "threshold": 2,
    "members": [
      "<tx trusted party 01 id>",
      "<tx trusted party 02 id>",
      "<tx trusted party 03 id>",
      "<tx trusted party 04 id>"
    ]
  },
  "wallets": [
    {
      "name": "Demo ETH-TESTNET wallet that uses global custodian policies",
      "asset": "<asset type: BTC, ETH, etc.>",
    },
    {
      "name": "Demo ETH-TESTNET wallet with custom custodian policies",
      "asset": "<asset type: BTC, ETH, etc.>",
      "custodygroup_withdraw": {
        "threshold": 2,
        "members": [
          "<withdrawal trusted party01 id>",
          "<withdrawal trusted party02 id>"
        ]
      },
      "custodygroup_tx": {
        "threshold": 1,
        "members": [
          "<tx trusted party 01 id>",
          "<tx trusted party 02 id>"
        ]
      }
    }
  ]
}

You cannot update the custodian policies of a fund!

Once you create a fund, you cannot update the custodian policies. However, you can create new wallets and set custom custodian policies with each.

Custodial policies explained

The custodygroup_withdraw on top level is the global (per fund) withdrawal custodian policy definition. The custodygroup_withdraw, part of the "Demo ETH-TESTNET wallet with custom custodian policies" is the definition the overriding policy.

It is the same with the global vs custom transfer policies.

Both with transfers and withdrawals, a custody policy includes:

  • threshold: this value defines how many approvals are required for a transaction to go through. In this case it is set to 2
  • members: this list includes IDs of members of your trusted network. In this case, three members are listed and at least two approvals are required.

Obviously, for transactions to pass through custody, the threshold value must be less than or equal to the number of specified members.

The custodygroup_tx is configured similarly to custodygroup_withdraw and in this case is set to require 3 approvals (threshold set to 3) from three of the four specified members.

Always define custodian policies per fund!

If you create a fund without custodian policies and you add wallets without custodian policies, transactions using these addresses may get stuck in the custodial approval process.

Definitions of per wallet custodian policies have the exact same structure.

Wallet definitions explained

  • A wallet on the Qredochain is not merely an address per asset type: it is rather a definition, that may or may not include custodial policies and dedicated approvers.
  • A wallet on the Qredochain always belongs to the fund it was created in: with Qredo, there are no wallets outside a fund.

The wallets object lists two wallets: one that uses the global custodian policies (has no custom policy definitions) and another that uses custom ones.

Example response: POST /fund

Upon success, the response returns the fund_id hash as a string value plus policies, assets, trusted network members and wallets.

{
  "fund id": "<ID of your fund>",
  "name": "<name of your fund>",
  "description": "<description of your fund>",
  "custodygroup withdraw": "<fund custodial policy ID for withdrawals>",
  "custodygroup tx": "<fund custodial policy ID for transactions>",
  "policy withdraw": "<object containing withdraw policy info>",
  "policy tx": "<object containing withdraw policy info>",
  "members": "<list of fund member objects and permissions of each>",
  "assets": "<list of supported assets in your fund>",
  "wallets": "<list of wallet objects with info like addresses and balances>"
}

The response, as shown, is significantly shortened: objects are presented as "collapsed". This is intentional and aims to keep things simple. Future updates of the "API developer docs" will include more details on these objects.

Pass fund_id with deposits, withdrawals, wallets, ledger, etc.

Save the fund_id value to perform different fund-specific actions, such as deposit and withdrawal transactions, creation of additional wallets and retrieving ledger tx history. Transfer transactions do not require fund_id.


Last update: 2022-05-03