v0

api version 0

The 0 version of the API is considered unstable alpha API, in use for pilot projects. Messages targetting v0 need to contain the header based on the following protocol buffer definition:

message Header {
    string ApiVersion = 1;
    string Kind = 2;
    google.protobuf.Any Metadata = 4; // optional, still undefined
}

in yaml this would look something like this:

apiVersion: "v0"
kind: "walletSet" // depending on the objective, this might differ.
metadata: 
    labels: 
        - "myWallet"
        - "savingsAccount" 

Kinds

v0 defines the following kinds:

• ownerSet: sets initial configurations and determine owners
• userSet: defines users, sets access levels, removes users
• walletSet: creates a new wallet, sets priviliges/auth level, deletes the wallet

When using the v0 API, ensure the exact same casing is used as described here. (it should return an error if deviating, however the exact response is still undefined)

ownerSet

ownerSet is the first and required configuration when setting up a carapace node. Owners are root level administrators. In an organization, the owners might be the executive team, or in very large organisations, a combination of technical leads and 3rd party mediators.

structure:

apiVersion: "v0"
kind: "ownerSet" 
owners:
    - name
      email 
      primary public key
      recovery public key
      weight (int)
quorum: int

The owner is identified by the primary public key.

email does not serve authentication purposes, but is used to set notifications.

name is used for readability in logs.

recovery public keys may be used when the primary public key is lost. Read more on the recovery protocol for their use.

weight refers to the quorum. If a node has a quorum of 3/5 owners, but one owner has a weight of 2, only a single other owner is needed for root level operations. By default an owner has a weight of 1.

quorum refers to the total weight needed to execute root level operations.

When setting up a carapace node, the first operation is providing an ownerSet, which must be signed by all defined owners. At this moment the node is ready for further operations.

ownerSet recovery protocol

If an owner loses their primary key, a new ownerSet may be submitted. This claim must be signed by a quorum of current owners (this is a rootLevel operation ), by either their primary or recovery keys. This allows for removing owners, setting new keys and updating recovery keys.

userSet

Adding the first new user is a rootLevel operation. userSet allows for creating new users with a custom authorization level. A user may create more users with equal or lesser authorization levels, meaning that only the first user must be created by the owners, and then may maintain the node.

example

Your organization sets the owners to the CEO, COO and the three largest stakeholders. These 5 parties then create the first user using userSet, which grants the CTO access to the node. The CTO then creates new users; the actual operators of the node.

structure:

apiVersion: "v0"
kind: "userSet" 
users:
    - name
      email 
      primary public key
      recovery public key
      authorizationLevel (int)

users defines an array of new users to be created.

name is used for readability in logs.

primary public key is used by the user when executing operations

recovery public keys are akin to ownerSet keys, however the recovery protocol is slightly different

userSet recovery protocol

As opposed to the ownerSet recovery protocol; the userSet recovery protocol is simpler. A user must simply provide a new userSet signed by one of their recovery keys. This immediately invalidates the existing keys.