NAV
protobuf

Introduction

API status: DRAFT - breaking changes are possible

Sirius is a Digital Assets custody and a blockchain infrastructure. Validator API allows consumers to programmatically validate, approve or reject: transactions, custody initialization and custody root key rotation. This API allows implementing functionality similar to Swisschain Validator mobile app.

For more information about Sirius, please contact us info@swisschain.io.

Feedback

In case if you have found an issue in API or in this documentation, please give us your feedback by submitting a GitHub issue. Thank you!

API usage

Sirius Validator API is a gRPC API. To get proto files please follow our GitHub

To learn more about gRPC please follow grpc.io

Authentication

Sirius Validator API uses Bearer authentication. Authorization token that a client needs to send with a request is a JWT token. The token can be obtained during the Validator registration process that can be initiated via Universe portal. See Invites section to get more details.

All API endpoints marked with

Authorization required

require authorization token to be passed as a gRPC metadata item with the key Authorization and value prefix Bearer:

name type placement description example
Authorization string metadata API key of the validator returned by the Accept method prepended with Bearer prefix Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ2YWxpZGF0b3ItaWQiOiI3MDEwMDAwMTUiLCJuYmYiOjE2NjcyNDQyNzEsImV4cCI6MTY5ODc4MDI3MSwiaWF0IjoxNjY3MjQ0MjcxLCJhdWQiOiJzaXJpdXMuc3dpc3NjaGFpbi5pbyJ9.QkhXNhb3EVyoO7KRb2jiWDQV0gWjASCyhMXsPl5i9g8

For simplicity this metadata item is not shown in every request that requires authorization.

Guid

Some API objects have string fields that in fact contain Guid. Exact format is xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx

JSON string

Although given API is a gRPC API, some gRPC objects may have string fields that contain some data serialized in the JSON format. Mainly such JSON strings are used to represent data that should be signed. Data can be serialized to JSON using any serialization options, the only requirement - JSON should follow RFC 8259

JSON string timestamp

Since timestamp representation is not fixed in the RFC 8259, given API uses textual representation following ISO 8601. Exact format is yyyy-MM-ddThh:mm:ss.ffffffZ. Timestamps are always in UTC time zone

Data encryption

Some data is passed in encrypted form. For symmetrical encryption AES algorithm is used. For asymetrical encryption RSA-PKCS1 algorithm is used.

Parameters of AES algorithm are:

Parameters of RSA-PKCS1 algorithm are:

Invites

Invitation allows to register a validator on a Universe Subscription. Invitation can be generated on the Universe portal.

Before a validator can accept an invitation it needs to generate its keys pair and validator ID. Keys pair is RSA-PKCS1 keys:

Validator ID is a SHA256Digest hash of the validator public key.

The private key should be kept in secret by the validator. The public key and validator ID should be submitted to the Accept method of API.

Accept an invitation

swisschain.sirius.validator_api.invites.Invites/Accept

Accepts a validator invitation generated via Universe portal.

Request

swisschain.sirius.validator_api.invites.Invites/Accept

> Requets: (application/grpc)

message AcceptInviteRequest {
  string invite_id = 1;
  string validator_id = 2;
  string public_key = 3;
}
name type description example
invite_id string Invitation ID to accept 3d44bfc617164889b21928ac2c256ffcdead0e33918f4f27a333c2025b8f4447b6b313241ebc4a0e8133c7479337f9ed
validator_id string ID of the validator. Base64 encoded string of the SHA256Digest hash of the public_key iPC78NoD2KpFFig8FHR7Pg403d+FCKwMorjaEBXn5PY=
public_key string Single-line RSA-PKCS1 public key of the validator -----BEGIN PUBLIC KEY-----
MIGdMA0GCSqGSIb3DQEBAQUAA4GLADCBhwKBgQCQN1JrAyX/FsP3v4vmE9aA/95N7EpwKSDujcsJRwttVlT803vU8DSsLAGDAlnb0YqeEhYaaDaGTTeOERitvt9QMnOoLwCuX7Fncp0RYclktjb9yLOl6zxEM5g57bVlCqv78AFfxKwHpt535hMg/bKG1rrNZR9NHh0GACdgsuV8GQIBAw==
-----END PUBLIC KEY-----

Response

swisschain.sirius.validator_api.invites.Invites/Accept

> Response: (application/grpc) - success response

message AcceptInviteResponse {
  oneof body {
    AcceptInviteResponseBody response = 1;
    .swisschain.sirius.validator_api.common.Error error = 2;
  }
}

message AcceptInviteResponseBody {
  string name = 1;
  string position = 2;
  string description = 3;
  string api_key = 4;
}

AcceptInviteResponse

name type description
response oneof body, AcceptInviteResponseBody Response payload
error oneof body, Error Response error

AcceptInviteResponseBody

name type description example
name string Name of the validator specified on the Universe portal Jhon Doe
position optional, string Position of the validator specified on the Universe portal Risk manager
description optional, string Description of the validator specified on the Universe portal Very important guy
api_key string API key of the validator to be used to authenticate further API requests eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ2YWxpZGF0b3ItaWQiOiI3MDEwMDAwMTUiLCJuYmYiOjE2NjcyNDQyNzEsImV4cCI6MTY5ODc4MDI3MSwiaWF0IjoxNjY3MjQ0MjcxLCJhdWQiOiJzaXJpdXMuc3dpc3NjaGFpbi5pbyJ9.QkhXNhb3EVyoO7KRb2jiWDQV0gWjASCyhMXsPl5i9g8

Revoke an invitation

swisschain.sirius.validator_api.invites.Invites/Revoke

Authorization required

Revokes a previously accepted invitation.

Request

swisschain.sirius.validator_api.invites.Invites/Revoke

> Requets: (application/grpc)

message RevokeInviteRequest {
}

Empty

Response

swisschain.sirius.validator_api.invites.Invites/Revoke

> Response: (application/grpc) - success response

message RevokeInviteResponse {
    oneof body {
        RevokeInviteResponseBody response = 1;
        .swisschain.sirius.validator_api.common.Error error = 2;
    }
}

message RevokeInviteResponseBody {
}

RevokeInviteResponse

name type description
response oneof body, RevokeInviteResponseBody Response payload
error oneof body, Error Response error

RevokeInviteResponseBody

Empty

Blockchains

Blockchain is not just Bitcoin or Ethereum, it's a particular network. For example Bitcoin MainNet, Ethereum Goerli are blockchains, whilst Bitcoin and Ethereum are protocols which are used by these blockchains. A network can be one of the types - private, test, public.

Get blockchains

swisschain.sirius.validator_api.blockchains.Blockchains/Get

Authorization required

Returns a full list of the blockchains available for the validator.

Request

swisschain.sirius.validator_api.blockchains.Blockchains/Get

> Requets: (application/grpc)

message GetBlockchainsRequest {
}

Empty

Response

swisschain.sirius.validator_api.blockchains.Blockchains/Get

> Response: (application/grpc) - success response

message GetBlockchainsResponse {
    oneof body {
        GetBlockchainResponseBody response = 1;
        .swisschain.sirius.validator_api.common.Error error = 2;
    }
}

message GetBlockchainResponseBody {
    repeated Blockchain blockchains = 1;

    message Blockchain {
        string id = 1;
        string name = 2;
        NetworkType network_type = 3;
        google.protobuf.StringValue tenant_id = 4;
    };

    enum NetworkType {
        PRIVATE = 0;
        TEST = 1;
        PUBLIC = 2;
    };
}

GetBlockchainResponseBody

name type description
blockchains Blockchain[] List of the blockchains

Blockchain

name type description example
id string Sirius ID of the blockchain ethereum
name string Name of the blockchain Ethereum
network_type NetworkType Blockchain network type public
tenant_id optional, string ID of a tenant (subscription) to which is blockchain is dedicated to on Sirius <null>, 61a9d900-802b-4830-b741-d98c3204e0d8

NetworkType

Type of blockchain network

Approval requests

Approval requests is what this API all about. Whenever a custody needs an approval from validators it initiates an approval request. Each approval request object represents an overall process of approving of something. This object is a general one, and it fits all the different approval requests like root key initialization, transfer transaction, smart contract invocation and so on. This is achieved by having a string context field that contains an approval process type-specific data serialized as a JSON object. Each validator sees its own representation of an approval request where he sees its own approval status and approval statuses of all other validators separately. Once an approval request is approved or rejected it can not become a pending again.

Get list of approval requests

swisschain.sirius.keykeeperapi.approvalrequest.ApprovalRequests/List

Authorization required

Gets list of approval requests related to the current (authenticated) validator with pagination and filtering. This endpoint returns brief information about approval requests. To get detailed approval request information see Get approval request details.

Request

swisschain.sirius.keykeeperapi.approvalrequest.ApprovalRequests/List

> Requets: (application/grpc)

message ListApprovalRequestsRequest {
  swisschain.sirius.keykeeperapi.approvalprocess.common.Page page = 1;
  ListApprovalRequestsFilter filter = 2;  
}

message ListApprovalRequestsFilter {
  google.protobuf.BoolValue is_read = 1;
  google.protobuf.Int64Value custody_id = 2;
  google.protobuf.BoolValue is_processed = 3;
}

ListApprovalRequestsRequest (object)

name type description
page Page page selector
filter ListApprovalRequestsFilter filter parameters

ListApprovalRequestsFilter (object)

name type description example
is_read bool? If specified, indicates if API should return only read/not read (by the given validator) approval requests <null>, true, false
custody_id int64? If specified, indicates API to return only approval requests related to the specified custody <null>, 404000100
is_processed bool? If specified, indicates if API should return only processed/not processed approval requests. Processed means that an approval request is either approved or rejected <null>, true, false

Response

swisschain.sirius.keykeeperapi.approvalrequest.ApprovalRequests/List

> Response: (application/grpc) - success response

message ListApprovalRequestsResponse {
  oneof body {
    ListApprovalRequestsPayload payload = 1;
    ListApprovalRequestsError error = 2;
  }
}

message ListApprovalRequestsPayload {
  repeated ApprovalRequestListItem items = 1;
}

message ApprovalRequestListItem {
  int64 id = 1;
  ApprovalProcess approval_process = 2;
  string context = 3;
  Custody custody = 4;
  Subscription subscription = 5;
  ApproverResolution approver_resolution = 6;
  bool is_read = 7;
  google.protobuf.Timestamp read_at = 8;
  google.protobuf.Timestamp delivered_at = 9;
  google.protobuf.Timestamp created_at = 10;
}

message ListApprovalRequestsError {

  enum ErrorCode {
    UNKNOWN = 0;
    INVALID_PARAMETERS = 1;
    DOMAIN_PROBLEM = 2;
    TECHNICAL_PROBLEM = 3;
    UNAUTHORIZED = 4;
  }

  ErrorCode code = 1;
  string message = 2;
}

ListApprovalRequestsResponse (object)

name type description
payload oneof body, ListApprovalRequestsPayload Response payload
error oneof body, ListApprovalRequestsError Response error

ListApprovalRequestsPayload (object)

name type description
items ApprovalRequestListItem[] Approval request items

ApprovalRequestListItem (object)

name type description example
id int64 ID of the approval request 702000453
approval_process ApprovalProcess Details of the approval process to which the approval request is related to
context string, JSON Approval request context. See *(Approval request context)[#data_structures-approval-request-context-JSON-string]
custody Custody Details of the custody to which the approval request is related to
subscription Subscription Details of the Universe portal subscription to which the approval request is related to
approver_resolution optional, ApproverResolution Details of the approver resolution related to the approval request. Can be null
is_read bool Indicates if the approval request was read by the validator (if Read endpoint was invoked) true, false
read_at optional, timestamp Timestamp when the approval request was read by the validator (when Read endpoint was invoked) <null>, 2022-11-25T11:49:03.456Z
delivered_at optional, timestamp Timestamp when the approval request was delivered to the validator (when Acknowledge endpoint was invoked) <null>, 2022-11-25T11:49:03.456Z
created_at timestamp Timestamp when the approval request was created 2022-11-25T11:49:03.456Z

ListApprovalRequestsError (object)

name type description example
code ListApprovalRequestsError.ErrorCode Error code INVALID_PARAMETERS
message string Error message Page size should be a positive number

ListApprovalRequestsError.ErrorCode (enum)

name value description
UNKNOWN 0 An unexpected error. This should not be returned normally
INVALID_PARAMETERS 1 Invalid request parameters
DOMAIN_PROBLEM 2 Operation can't be performed with the current server state and with the specified parameters
TECHNICAL_PROBLEM 3 A transient error or a program error
UNAUTHORIZED 4 Unauthorized request

Get approval request details

swisschain.sirius.keykeeperapi.approvalrequest.ApprovalRequests/Get

Authorization required

Gets detailed information about a specified approval request. This method is intended to be invoked only for a single approval request, do not use it for bulk information retrieval. If you need to get information about many approval requests, consider using Get list of approval requests.

Request

swisschain.sirius.keykeeperapi.approvalrequest.ApprovalRequests/Get

> Requets: (application/grpc)

message GetApprovalRequestRequest {
  int64 id = 1;
}
name type description example
id int64 Id of an approval request to get details 702000453

Response

swisschain.sirius.keykeeperapi.approvalrequest.ApprovalRequests/Get

> Response: (application/grpc) - success response

message GetApprovalRequestResponse {
  oneof body {
    GetApprovalRequestPayload payload = 1;
    GetApprovalRequestError error = 2;
  }
}

message GetApprovalRequestPayload {
  int64 id = 1;
  ApprovalProcess approval_process = 2;
  string context = 3;
  Custody custody = 4;
  Subscription subscription = 5;
  ApproverResolution approver_resolution = 6;
  repeated LinkedApprovalRequest linked_approval_requests = 7;
  bool is_read = 8;
  google.protobuf.Timestamp read_at = 9;
  google.protobuf.Timestamp delivered_at = 10;
  google.protobuf.Timestamp created_at = 11;
}

message GetApprovalRequestError {

  enum ErrorCode {
    UNKNOWN = 0;
    INVALID_PARAMETERS = 1;
    DOMAIN_PROBLEM = 2;
    TECHNICAL_PROBLEM = 3;
    UNAUTHORIZED = 4;
  }

  ErrorCode code = 1;
  string message = 2;
}

message LinkedApprovalRequest {
  Approver approver = 1;
  ApproverResolution approver_resolution = 2;
  bool is_read = 3;
  bool is_delivered = 4;
  google.protobuf.Timestamp read_at = 5;
  google.protobuf.Timestamp delivered_at = 6;
}

message Approver {
  string id = 1;
  string name = 2;
}

GetApprovalRequestResponse (object)

name type description
payload oneof body, GetApprovalRequestPayload Response payload
error oneof body, GetApprovalRequestError Response error

GetApprovalRequestPayload (object)

name type description example
id int64 ID of the approval request 702000453
approval_process ApprovalProcess Details of the approval process to which the approval request is related to
context string, JSON Approval request context. See *(Approval request context)[#data_structures-approval-request-context-JSON-string]
custody Custody Details of the custody to which the approval request is related to
subscription Subscription Details of the Universe portal subscription to which the approval request is related to
linked_approval_requests LinkedApprovalRequest[] List of approval requests send to other validators within given approval process
approver_resolution optional, ApproverResolution Details of the approver resolution related to the approval request. Can be null
is_read bool Indicates if the approval request was read by the validator (if Read endpoint was invoked) true, false
read_at optional, timestamp Timestamp when the approval request was read by the validator (when Read endpoint was invoked) <null>, 2022-11-25T11:49:03.456Z
delivered_at optional, timestamp Timestamp when the approval request was delivered to the validator (when Acknowledge endpoint was invoked) <null>, 2022-11-25T11:49:03.456Z
created_at timestamp Timestamp when the approval request was created 2022-11-25T11:49:03.456Z

LinkedApprovalRequest (object)

name type description example
approver Details of the validator to which given approval request is related to
approver_resolution optional, ApproverResolution Details of the approver resolution related to the approval request. Can be null
is_read bool Indicates if the approval request was read by the validator (if Read endpoint was invoked) true, false
is_delivered bool Indicates if the approval request was delivered to the validator (if Acknowledge endpoint was invoked) true, false
read_at optional, timestamp Timestamp when the approval request was read by the validator (when Read endpoint was invoked) <null>, 2022-11-25T11:49:03.456Z
delivered_at optional, timestamp Timestamp when the approval request was delivered to the validator (when Acknowledge endpoint was invoked) <null>, 2022-11-25T11:49:03.456Z

Approver (object)

name type description example
id string, Base64 ID of the approver iPC78NoD2KpFFig8FHR7Pg403d+FCKwMorjaEBXn5PY=
name string Name of the approver Jhon Doe

GetApprovalRequestError (object)

name type description example
code GetApprovalRequestError.ErrorCode Error code DOMAIN_PROBLEM
message string Error message Approval request not found.

GetApprovalRequestError.ErrorCode (enum)

name value description
UNKNOWN 0 An unexpected error. This should not be returned normally
INVALID_PARAMETERS 1 Invalid request parameters
DOMAIN_PROBLEM 2 Operation can't be performed with the current server state and with the specified parameters
TECHNICAL_PROBLEM 3 A transient error or a program error
UNAUTHORIZED 4 Unauthorized request

Acknowledge an approval request is received

swisschain.sirius.keykeeperapi.approvalrequest.ApprovalRequests/Acknowledge

Authorization required

Marks a specified approval request as received by the validator application.

Request

swisschain.sirius.keykeeperapi.approvalrequest.ApprovalRequests/Acknowledge

> Requets: (application/grpc)

message AcknowledgeApprovalRequestRequest {
  int64 id = 1;
}
name type description example
id int64 Id of an approval request will acknowledged as received 702000453

Response

swisschain.sirius.keykeeperapi.approvalrequest.ApprovalRequests/Acknowledge

> Response: (application/grpc) - success response

message AcknowledgeApprovalRequestResponse {
  oneof body {
    AcknowledgeApprovalRequestPayload payload = 1;
    AcknowledgeApprovalRequestError error = 2;
  }
}

message AcknowledgeApprovalRequestPayload {
}

message AcknowledgeApprovalRequestError {

  enum ErrorCode {
    UNKNOWN = 0;
    INVALID_PARAMETERS = 1;
    DOMAIN_PROBLEM = 2;
    TECHNICAL_PROBLEM = 3;
    UNAUTHORIZED = 4;
  }

  ErrorCode code = 1;
  string message = 2;
}

AcknowledgeApprovalRequestResponse (object)

name type description
payload oneof body, AcknowledgeApprovalRequestPayload Response payload
error oneof body, AcknowledgeApprovalRequestError Response error

AcknowledgeApprovalRequestPayload (object)

Empty

AcknowledgeApprovalRequestError (object)

name type description example
code AcknowledgeApprovalRequestError.ErrorCode Error code DOMAIN_PROBLEM
message string Error message Approval request not found.

AcknowledgeApprovalRequestError.ErrorCode (enum)

name value description
UNKNOWN 0 An unexpected error. This should not be returned normally
INVALID_PARAMETERS 1 Invalid request parameters
DOMAIN_PROBLEM 2 Operation can't be performed with the current server state and with the specified parameters
TECHNICAL_PROBLEM 3 A transient error or a program error
UNAUTHORIZED 4 Unauthorized request

Notify an approval request is read

swisschain.sirius.keykeeperapi.approvalrequest.ApprovalRequests/Read

Authorization required

Marks a specified approval request as read by the validation officer.

Request

swisschain.sirius.keykeeperapi.approvalrequest.ApprovalRequests/Read

> Requets: (application/grpc)

message ReadApprovalRequestRequest {
  int64 id = 1;
}
name type description example
id int64 Id of an approval request will be notified as read 702000453

Response

swisschain.sirius.keykeeperapi.approvalrequest.ApprovalRequests/Read

> Response: (application/grpc) - success response

message ReadApprovalRequestResponse {
  oneof body {
    ReadApprovalRequestPayload payload = 1;
    ReadApprovalRequestError error = 2;
  }
}

message ReadApprovalRequestPayload {
}

message ReadApprovalRequestError {

  enum ErrorCode {
    UNKNOWN = 0;
    INVALID_PARAMETERS = 1;
    DOMAIN_PROBLEM = 2;
    TECHNICAL_PROBLEM = 3;
    UNAUTHORIZED = 4;
  }

  ErrorCode code = 1;
  string message = 2;
}

ReadApprovalRequestResponse (object)

name type description
payload oneof body, ReadApprovalRequestPayload Response payload
error oneof body, ReadApprovalRequestError Response error

ReadApprovalRequestPayload (object)

Empty

ReadApprovalRequestError (object)

name type description example
code ReadApprovalRequestError.ErrorCode Error code DOMAIN_PROBLEM
message string Error message Approval request not found.

ReadApprovalRequestError.ErrorCode (enum)

name value description
UNKNOWN 0 An unexpected error. This should not be returned normally
INVALID_PARAMETERS 1 Invalid request parameters
DOMAIN_PROBLEM 2 Operation can't be performed with the current server state and with the specified parameters
TECHNICAL_PROBLEM 3 A transient error or a program error
UNAUTHORIZED 4 Unauthorized request

Approve an approval request

swisschain.sirius.keykeeperapi.approvalrequest.ApprovalRequests/Approve

Authorization required

Approves a specified approval request.

Request

swisschain.sirius.keykeeperapi.approvalrequest.ApprovalRequests/Approve

> Requets: (application/grpc)

message ApproveApprovalRequestRequest {
  int64 id = 1;
  string comment = 2;
  string context = 3;
  bytes signature = 4;
  string device_info = 5;
  string app_version = 6;
}
name type description example
id int64 Id of an approval request to approve 702000453
comment string Comment of the validator This transaction is correct
context string, JSON Approval request resolution context. See *(Approval request resolution context)[#data_structures-approval-request-resolution-context-JSON-string]
signature bytes SHA256Digest signature of the context, signed with the validator private key G3M7YVyBKrTBt8FyizW+UPnrg+lkNwlJNjAWUtK90GELylmHRqgbhcgZXM2iEpsFZNe3eT5F3H5hEBCu1+oQ4fDyuPgs9PGkul2oNnKnMBEtLoAak2gXBVtkF9J8pYqKmzMK/DVrwmUSIVxko8+EYAKrBqlGspy4DER2F4PvHbM=
device_info string Validator device info {"deviceUID":"6616c7824783d341","platform":"Android"}
app_version string Validator application version Sirius Validator 1.3.4

Response

swisschain.sirius.keykeeperapi.approvalrequest.ApprovalRequests/Approve

> Response: (application/grpc) - success response

message ApproveApprovalRequestResponse {
  oneof body {
    ApproveApprovalRequestPayload payload = 1;
    ApproveApprovalRequestError error = 2;
  }
}

message ApproveApprovalRequestPayload {
}

message ApproveApprovalRequestError {

  enum ErrorCode {
    UNKNOWN = 0;
    INVALID_PARAMETERS = 1;
    DOMAIN_PROBLEM = 2;
    TECHNICAL_PROBLEM = 3;
    UNAUTHORIZED = 4;
  }

  ErrorCode code = 1;
  string message = 2;
}

ApproveApprovalRequestResponse (object)

name type description
payload oneof body, ApproveApprovalRequestPayload Response payload
error oneof body, ApproveApprovalRequestError Response error

ApproveApprovalRequestPayload (object)

Empty

ApproveApprovalRequestError (object)

name type description example
code ApproveApprovalRequestError.ErrorCode Error code DOMAIN_PROBLEM
message string Error message Approval request not found.

ApproveApprovalRequestError.ErrorCode (enum)

name value description
UNKNOWN 0 An unexpected error. This should not be returned normally
INVALID_PARAMETERS 1 Invalid request parameters
DOMAIN_PROBLEM 2 Operation can't be performed with the current server state and with the specified parameters
TECHNICAL_PROBLEM 3 A transient error or a program error
UNAUTHORIZED 4 Unauthorized request

Reject an approval request

swisschain.sirius.keykeeperapi.approvalrequest.ApprovalRequests/Reject

Authorization required

Rejects a specified approval request.

Request

swisschain.sirius.keykeeperapi.approvalrequest.ApprovalRequests/Reject

> Requets: (application/grpc)

message RejectApprovalRequestRequest {
  int64 id = 1;
  string comment = 2;
  string context = 3;
  bytes signature = 4;
  string device_info = 5;
  string app_version = 6;
}
name type description example
id int64 Id of an approval request to reject 702000453
comment string Comment of the validator This transaction is not allowed
context string, JSON Approval request resolution context. See *(Approval request resolution context)[#data_structures-approval-request-resolution-context-JSON-string]
signature bytes SHA256Digest signature of the context, signed with the validator private key G3M7YVyBKrTBt8FyizW+UPnrg+lkNwlJNjAWUtK90GELylmHRqgbhcgZXM2iEpsFZNe3eT5F3H5hEBCu1+oQ4fDyuPgs9PGkul2oNnKnMBEtLoAak2gXBVtkF9J8pYqKmzMK/DVrwmUSIVxko8+EYAKrBqlGspy4DER2F4PvHbM=
device_info string Validator device info {"deviceUID":"6616c7824783d341","platform":"Android"}
app_version string Validator application version Sirius Validator 1.3.4

Response

swisschain.sirius.keykeeperapi.approvalrequest.ApprovalRequests/Reject

> Response: (application/grpc) - success response

message RejectApprovalRequestResponse {
  oneof body {
    RejectApprovalRequestPayload payload = 1;
    RejectApprovalRequestError error = 2;
  }
}

message RejectApprovalRequestPayload {
}

message RejectApprovalRequestError {

  enum ErrorCode {
    UNKNOWN = 0;
    INVALID_PARAMETERS = 1;
    DOMAIN_PROBLEM = 2;
    TECHNICAL_PROBLEM = 3;
    UNAUTHORIZED = 4;
  }

  ErrorCode code = 1;
  string message = 2;
}

RejectApprovalRequestResponse (object)

name type description
payload oneof body, RejectApprovalRequestPayload Response payload
error oneof body, RejectApprovalRequestError Response error

RejectApprovalRequestPayload (object)

Empty

RejectApprovalRequestError (object)

name type description example
code RejectApprovalRequestError.ErrorCode Error code DOMAIN_PROBLEM
message string Error message Approval request not found.

RejectApprovalRequestError.ErrorCode (enum)

name value description
UNKNOWN 0 An unexpected error. This should not be returned normally
INVALID_PARAMETERS 1 Invalid request parameters
DOMAIN_PROBLEM 2 Operation can't be performed with the current server state and with the specified parameters
TECHNICAL_PROBLEM 3 A transient error or a program error
UNAUTHORIZED 4 Unauthorized request

Data structures

Here you can see data structures used by different API endpoints grouped by protobuf packages

Error (object)

package swisschain.sirius.validator_api.common;

message Error {
  ErrorCode code = 1;
  string message = 2;
}
name type description example
code ErrorCode Error code
message string Error message API key is expired

ErrorCode (enum)

package swisschain.sirius.validator_api.common;

enum ErrorCode {
  UNKNOWN = 0;
  INVALID_PARAMETERS = 1;
  NOT_FOUND = 2;
  EXPIRED_API_KEY = 3;
  INVALID_API_KEY = 4;
}
name value description
UNKNOWN 0 Transient error or program error
INVALID_PARAMETERS 1 Invalid request parameters
NOT_FOUND 2 Object not found
EXPIRED_API_KEY 3 API key is expired
INVALID_API_KEY 4 API key is invalid

Page (object)

package swisschain.sirius.keykeeperapi.approvalprocess.common;

message Page {
  int32 index = 1;
  int32 size = 2;
}
name type description constraints example
index in32 Zero-based index of the page to query index >= 0 10
size int32 Maximum number of items to return in the results size >= 0 and size <= 100 50

ApprovalProcessType (enum)

package swisschain.sirius.keykeeperapi.approvalprocess.common;

enum ApprovalProcessType {
  APPROVAL_PROCESS_TYPE_UNKNOWN = 0;
  APPROVAL_PROCESS_TYPE_TRANSFER = 1;
  APPROVAL_PROCESS_TYPE_SMART_CONTRACT_DEPLOYMENT = 2;
  APPROVAL_PROCESS_TYPE_SMART_CONTRACT_INVOCATION = 3;
  APPROVAL_PROCESS_TYPE_ROOT_KEY_INITIALIZATION = 4;
  APPROVAL_PROCESS_TYPE_ROOT_KEY_ROTATION = 5;
}
name value description
APPROVAL_PROCESS_TYPE_UNKNOWN 0 Unexpected value. This should not be returned normally
APPROVAL_PROCESS_TYPE_TRANSFER 1 A transfer blockchain transaction
APPROVAL_PROCESS_TYPE_SMART_CONTRACT_DEPLOYMENT 2 A smart contract deployment blockchain transaction
APPROVAL_PROCESS_TYPE_SMART_CONTRACT_INVOCATION 3 A smart contract method invocation blockchain transaction
APPROVAL_PROCESS_TYPE_ROOT_KEY_INITIALIZATION 4 A custody root key initialization
APPROVAL_PROCESS_TYPE_ROOT_KEY_ROTATION 5 A custody root key rotation

ApprovalProcessStatus (enum)

package swisschain.sirius.keykeeperapi.approvalprocess.common;

enum ApprovalProcessStatus {
  APPROVAL_PROCESS_STATUS_UNKNOWN = 0;
  APPROVAL_PROCESS_STATUS_PENDING = 1;
  APPROVAL_PROCESS_STATUS_APPROVED = 2;
  APPROVAL_PROCESS_STATUS_REJECTED = 3;
}
name value description
APPROVAL_PROCESS_STATUS_UNKNOWN 0 Unexpected value. This should not be returned normally
APPROVAL_PROCESS_STATUS_PENDING 1 An approval process is pending for resolutions
APPROVAL_PROCESS_STATUS_APPROVED 2 An approval process is approved
APPROVAL_PROCESS_STATUS_REJECTED 3 An approval process is rejected

Decision (enum)

package swisschain.sirius.keykeeperapi.approvalprocess.common;

enum Decision {
  DECISION_UNKNOWN = 0;
  DECISION_APPROVED = 1;
  DECISION_REJECTED = 2;
}
name value description
DECISION_UNKNOWN 0 Unexpected value. This should not be returned normally
DECISION_APPROVED 1 A validator approved a validation request
DECISION_REJECTED 2 A validator rejected a validation request

ApprovalProcess (object)

package swisschain.sirius.keykeeperapi.approvalrequest;

message ApprovalProcess {
  string id = 1;
  swisschain.sirius.keykeeperapi.approvalprocess.common.ApprovalProcessType type = 2;
  swisschain.sirius.keykeeperapi.approvalprocess.common.ApprovalProcessStatus status = 3;
  string context = 4;
}
name type description example
id string, guid ID of the approval process 52635969-3c80-422a-bafc-7e5a6151bf85
type ApprovalProcessType Type of the approval process APPROVAL_PROCESS_TYPE_ROOT_KEY_INITIALIZATION
status *ApprovalProcessStatus Status of the approval process APPROVAL_PROCESS_STATUS_PENDING
context string, JSON Approval process context. It is a JSON string. Schema of JSON depends on the approval process type field value

ApproverResolution (object)

package swisschain.sirius.keykeeperapi.approvalrequest;

message ApproverResolution {
  swisschain.sirius.keykeeperapi.approvalprocess.common.Decision decision = 1;
  google.protobuf.StringValue comment = 2;
  google.protobuf.Timestamp created_at = 3;
}
name type description example
decision Decision Decision made by the approver
comment optional, string Comment made by the approver This transaction is not allowed
created_at timestamp When the approver resolution was made 2022-11-25T15:26:43.185

Custody (object)

package swisschain.sirius.keykeeperapi.approvalrequest;

message Custody {
  int64 id = 1;
  string name = 2;
}
name type description example
id int64 ID of the custody 404000019
name string Name of the custody Treasury custody

Subscription (object)

package swisschain.sirius.keykeeperapi.approvalrequest;

message Subscription {
  string name = 1;
  google.protobuf.StringValue color = 2;
}
name type description example
name string Name of the subscription Sandbox
color optional, string Color of associated with the subscription on the Universe portal #ff0000

Approval process context (JSON string)

Approval process context is a JSON string that contains approval process details specific for the type of the approval process. Thus, JSON schema depends on the Approval process type field value. Below you can find description of the context schema for each Approval process type

APPROVAL_PROCESS_TYPE_TRANSFER

Not available yet

APPROVAL_PROCESS_TYPE_SMART_CONTRACT_DEPLOYMENT

Not available yet

APPROVAL_PROCESS_TYPE_SMART_CONTRACT_INVOCATION

Not available yet

APPROVAL_PROCESS_TYPE_ROOT_KEY_INITIALIZATION

{
    "id": "44496481-4343-4d00-bdaf-29714c266a06",
    "instance": "Secure custody A",
    "ip": "234.125.135.334",
    "threshold": 3,
    "timestamp": "2022-11-25T16:22:23.832Z"
}
path type description example
id string, guid ID of the process 44496481-4343-4d00-bdaf-29714c266a06
instance string Custody instance name that initiated the process Secure custody A
ip string, ip IP address of the custody component that initiated the process 234.125.135.334
threshold int Threshold indicating how many approval are need to initialize the root key 3
timestamp timestamp, ISO 8601 When the process was started 2022-11-25T16:22:23.832Z

APPROVAL_PROCESS_TYPE_ROOT_KEY_ROTATION

{
    "id": "44496481-4343-4d00-bdaf-29714c266a06",
    "instance": "Secure custody A",
    "ip": "234.125.135.334",
    "threshold": 3,
    "timestamp": "2022-11-25T16:22:23.832Z"
}
path type description example
id string, guid ID of the process 44496481-4343-4d00-bdaf-29714c266a06
instance string Custody instance name that initiated the process Secure custody A
ip string, ip IP address of the custody component that initiated the process 234.125.135.334
threshold int Threshold indicating how many approval are need to rotate the root key 3
timestamp timestamp, ISO 8601 When the process was started 2022-11-25T16:22:23.832Z

Approval request context (JSON string)

Approval request context is a JSON string that contains approval request details specific for the type of the approval process and addressed to a certain validator. Thus, JSON schema depends on the Approval process type field value. Below you can find description of the context schema for each Approval process type

APPROVAL_PROCESS_TYPE_TRANSFER

Not available yet

APPROVAL_PROCESS_TYPE_SMART_CONTRACT_DEPLOYMENT

Not available yet

APPROVAL_PROCESS_TYPE_SMART_CONTRACT_INVOCATION

Not available yet

APPROVAL_PROCESS_TYPE_ROOT_KEY_INITIALIZATION

{
    "encryptedPart": "iGKvH2X6+Lr26PcPhIWK9vL+ofRS9Y/U64qgLDb2zHo356TtxqHgDXDEtI9FdwOYRTM/UOtnqV3Ol2Y7zpgGpUjXRVckmPTtwkEsmkPuPlpo1fYc6ktbSMA+K/lVRPZuYIw3x7p0hbKETtbe67gbKHgHb1CEk1Bc9/mQilLratXbVlKraSrc2bG4mBiUUzqY5f2Q/CZAWZPxcOZ5aOkrXn0adpRbQftUueouFZUWvTE=",
    "partKey": {
        "secret": "aZaG5g/GrqU1etwAzjMCtSz1vbzLNhcpBJdmwb7b6ZRyVBgEFZwMshdDZVBkygS9QfdvwgqfnHUj4QkaF6f1Ds1/+39oO0nk3J5ag5f1+/UqFFGKCQK3rekTCL5b9kzut24dD6wnz85q/XtvT7q5vq0+f5XChkFB6Bc+FiDUCoQ=",
        "nonce": "hd8XQDHjwaiht637yes6VQ=="
    },
    "responseKey": {
        "secret": "RS11UhzGJAGkMdvQ6kFPeI029WZH1y15vSfAQWQcQpCrnxkLKfMc0cB6Nh3/NpnAaad8MqCD65LoLAWQjNcPoYWuPMGOXF4LIao4eKw3K0yd8F7yEo0cswUUu7ma7/QK7BPPHZCRPGyLs8MAjCl58NijPLDJM9d6yPxl1Jr5M6U=",
        "nonce": "g0pukIMYQI9xnZg3alonDw=="
    }
}
path type description example
encryptedPart string, Base64 Part of the root key encrypted by the partKey AES key iGKvH2X6+Lr26PcPhIWK9vL+ofRS9Y/U64qgLDb2zHo356TtxqHgDXDEtI9FdwOYRTM/UOtnqV3Ol2Y7zpgGpUjXRVckmPTtwkEsmkPuPlpo1fYc6ktbSMA+K/lVRPZuYIw3x7p0hbKETtbe67gbKHgHb1CEk1Bc9/mQilLratXbVlKraSrc2bG4mBiUUzqY5f2Q/CZAWZPxcOZ5aOkrXn0adpRbQftUueouFZUWvTE=
partKey object AES key that encryptedPart is encrypted by
partKey.secret string, Base64 Secret part of the key encrypted by the RSA-PKCS1 public key of the validator aZaG5g/GrqU1etwAzjMCtSz1vbzLNhcpBJdmwb7b6ZRyVBgEFZwMshdDZVBkygS9QfdvwgqfnHUj4QkaF6f1Ds1/+39oO0nk3J5ag5f1+/UqFFGKCQK3rekTCL5b9kzut24dD6wnz85q/XtvT7q5vq0+f5XChkFB6Bc+FiDUCoQ=
partKey.nonce string, Base64 Nonce part of the key hd8XQDHjwaiht637yes6VQ==
responseKey object AES key that should be used to encrypt the root key part send by the validator back to the custody with the Approval request resolution context part field RS11UhzGJAGkMdvQ6kFPeI029WZH1y15vSfAQWQcQpCrnxkLKfMc0cB6Nh3/NpnAaad8MqCD65LoLAWQjNcPoYWuPMGOXF4LIao4eKw3K0yd8F7yEo0cswUUu7ma7/QK7BPPHZCRPGyLs8MAjCl58NijPLDJM9d6yPxl1Jr5M6U=
responseKey.secret string, Base64 Secret part of the key encrypted by the RSA-PKCS1 public key of the validator
responseKey.nonce string, Base64 Nonce part of the key g0pukIMYQI9xnZg3alonDw==

APPROVAL_PROCESS_TYPE_ROOT_KEY_ROTATION

{
}

Empty

Approval request resolution context (JSON string)

Approval request resolution context is a JSON string that contains approval request resolution details specific for the type of the approval process formed by a certain validator. Thus, JSON schema depends on the Approval process type field value. Below you can find description of the context schema for each Approval process type

APPROVAL_PROCESS_TYPE_TRANSFER

Not available yet

APPROVAL_PROCESS_TYPE_SMART_CONTRACT_DEPLOYMENT

Not available yet

APPROVAL_PROCESS_TYPE_SMART_CONTRACT_INVOCATION

Not available yet

APPROVAL_PROCESS_TYPE_ROOT_KEY_INITIALIZATION

{
    "part": "hDXP10Ey+WKYb42hfPb3z5I4RGpRN9ODzg1j0cMPq/fSEFnwVUOH5F2TRAya0SvSzinuD29dp/8loLEcws0zRL50+LsuhDUGw4Y2Yhr0r9cSmuPeCNInBAfHUwuV8XUeK7U+KcSQqF0vKAVCF5/RgOGeJjJWxm2eiHAi7w6x8sXwr991KhrMpQwtPeYtwGGPzSRBKkyJmvzlbTdyRDL7FersvWPz0r0hQMZTGjzv0SF4d4ys0UYYkXpFYKi0kVdj1xeUivPX4pgHQjNndZgtTB6AYZRI8hLTGSK5LfYoZQUnztQc8iO3Tyn7fOiC8YypniHKAYD6p4AdCWFdZ41iwwt6Y/2CLvh6PI4FXfbLyUGnpbgyjBTEobAYh+hV+qqCTZTN9bFxLq9pAj0mdImDe1UmnlBgVH2/5BGchAbD5lWxo/1NxOseTqiqtkElMwfiQvcVj2oZG5uOO/lBmjXbhhmO33+0womgSnL3HHqOlx3bDxsQUhDdD+uPITgzDoqQg2rS1y0Gg4o79iovLzrR0A==",
    "process": {
      "id": "44496481-4343-4d00-bdaf-29714c266a06",
      "instance": "Secure custody A",
      "ip": "234.125.135.334",
      "threshold": 3,
      "timestamp": "2022-11-25T16:22:23.832Z"
  }
}
path type description example
part string Root key part encrypted by the responseKey field of the Approval request context hDXP10Ey+WKYb42hfPb3z5I4RGpRN9ODzg1j0cMPq/fSEFnwVUOH5F2TRAya0SvSzinuD29dp/8loLEcws0zRL50+LsuhDUGw4Y2Yhr0r9cSmuPeCNInBAfHUwuV8XUeK7U+KcSQqF0vKAVCF5/RgOGeJjJWxm2eiHAi7w6x8sXwr991KhrMpQwtPeYtwGGPzSRBKkyJmvzlbTdyRDL7FersvWPz0r0hQMZTGjzv0SF4d4ys0UYYkXpFYKi0kVdj1xeUivPX4pgHQjNndZgtTB6AYZRI8hLTGSK5LfYoZQUnztQc8iO3Tyn7fOiC8YypniHKAYD6p4AdCWFdZ41iwwt6Y/2CLvh6PI4FXfbLyUGnpbgyjBTEobAYh+hV+qqCTZTN9bFxLq9pAj0mdImDe1UmnlBgVH2/5BGchAbD5lWxo/1NxOseTqiqtkElMwfiQvcVj2oZG5uOO/lBmjXbhhmO33+0womgSnL3HHqOlx3bDxsQUhDdD+uPITgzDoqQg2rS1y0Gg4o79iovLzrR0A==
process object Approval process context to which the resolution is related to. Just pass all process fields you've received in the Approval process context
process.id string, guid ID of the process 44496481-4343-4d00-bdaf-29714c266a06
process.instance string Custody instance name that initiated the process Secure custody A
process.ip string, ip IP address of the custody component that initiated the process 234.125.135.334
process.threshold int Threshold indicating how many approval are need to initialize the root key 3
process.timestamp timestamp, ISO 8601 When the process was started 2022-11-25T16:22:23.832Z

APPROVAL_PROCESS_TYPE_ROOT_KEY_ROTATION

{
    "process": {
      "id": "44496481-4343-4d00-bdaf-29714c266a06",
      "instance": "Secure custody A",
      "ip": "234.125.135.334",
      "threshold": 3,
      "timestamp": "2022-11-25T16:22:23.832Z"
  }
}
path type description example
process object Approval process context to which the resolution is related to. Just pass all process fields you've received in the Approval process context
process.id string, guid ID of the process 44496481-4343-4d00-bdaf-29714c266a06
process.instance string Custody instance name that initiated the process Secure custody A
process.ip string, ip IP address of the custody component that initiated the process 234.125.135.334
process.threshold int Threshold indicating how many approval are need to rotate the root key 3
process.timestamp timestamp, ISO 8601 When the process was started 2022-11-25T16:22:23.832Z
protobuf