Welcome to Fireblocks Agent

Fireblocks Agent is an open-source on-prem service written in Typescript which is responsible for receiving new messages to sign from Fireblocks, relay these messages to the client's HSM and return the signed result back to Fireblocks.

Develop (Run Locally)

Prerequisites

• Make sure you have nvm on your machine. To check, run nvm in a terminal.   - To install nvm:     - On mac run brew install nvm     - Linux, follow these instructions

Installation

• git clone https://github.com/fireblocks/fireblocks-agent.git
• cd fireblocks-agent
• nvm use
• install dependencies npm i

Running

• Build and run example customer server docker:

  • cd examples/server
  • npm run build:docker
  • npm run start:docker

• Configure and run Fireblocks agent:

• Copy .env.prod and name it .env.{env-name} (e.g. .env.test)

• Edit your newly created .env.{env-name} file with the right configuration

• Build the Fireblocks agent:

  • npm run build

• Start the Fireblocks agent with your desired environment:

  • npm run start --env=env-name

Fireblocks Agent Environment Variables

The Fireblocks agent expect a configuration file (for production it's called .env.prod) with several parameters:

• MOBILE_GATEWAY_URL - In production this value should be https://mobile-api.fireblocks.io
• CUSTOMER_SERVER_URL - The client's custom server url
• CUSTOMER_SERVER_PULL_CADENCE_MS - Cadence of pulling messages status
• CUSTOMER_SERVER_AUTHORIZATION - If exists, the Fireblocks agent will send its value on the Authorization header for each request. The client can use it for authorizing the fireblocks agent or keep track on which agent is calling it
• SSL_CERT_PATH - If exists, a path to a self-signed SSL certificate which will be used to validate the server certificate

About the Fireblocks Key Link Workspace

Actors

The Fireblocks Key Link workspace consists of several components (aka actors). Each with its own responsibilities.

• Console - Fireblocks web console. Link
• Mobile App - Fireblocks mobile app.
• Mobile API Gateway - Fireblocks REST API Server. The Fireblocks agent communicates with this server in the registration flow and for receiving new messages.
• Developer API - Fireblocks back office server for workspace setup and configuration.
• Fireblocks Agent - An on-prem service written in Typescript which is responsible for receiving new messages to sign from Fireblocks, relay these messages to the client's HSM and return the signed result back to Fireblocks.
• Customer Server - The client's own server which receives messages to sign from the Fireblocks agent. Sign them via the client's HSM and provide the Fireblocks agent with the signed messages.
• HSM component - The actual HSM implementation. Can be on prem or a cloud based HSM, or a different Key Management System.

About the Customer Server

The customer server is a component that should be written by the client according to the client's connection to the HSM component. The server is expected to implement the following OpenAPI spec.

In general, it should support signing messages according to ECDSA and EdDSA algorithms and return the status for given messages.

We provide an example of such a server in examples/server with an integration to a software implementation of an HSM called softHSM

The entry point for the server can be found here

Main Flows

Create a New Fireblocks Agent API User

Pair the Fireblocks Agent Device

Add a Validator Key

This procedure should happen once. Fireblocks will need a validator key to approve new signing keys. This flow is done via the Fireblocks sdk and not via this program.

Add Signing Keys

Each signing key should be first converted into a certificate which should be signed by an active validator key. The signed certificates are then regsitered to Fireblocks via the API or the Console.

Fireblocks Agent & Customer Server with HSM - Main Flow