FKMS: Falcon Key Management Service

Overview

fkms is a Key Management Service (KMS) written in Rust, designed to sign transactions originating from Falcon. It provides secure key management and signing capabilities for EVM-compatible blockchains and XRPL (secp256k1), supporting both local and AWS KMS-backed signers. The service exposes a gRPC API for signing and key management operations, and is designed to be easily configurable and extensible with middleware (e.g., authentication).

Prerequisites

Before building and running fkms, ensure the following dependency is installed:

• Rust

Installation

1. Clone the repository:

   git clone https://github.com/bandprotocol/fkms.git
   cd fkms

2. Build and install the binary:

   By default, the fkms binary is compiled with the local feature enabled, supporting local key management. If you wish to enable additional features (such as AWS KMS integration), you can specify them explicitly during installation:

   • Default (local signer only)

     cargo install --path .

   • With AWS KMS support:

     cargo install --path . --features aws

   • Both Local and AWS KMS support:

     cargo install --path . --features local,aws

   This will compile and install the fkms executable

Configuration

The default configuration file is located at $HOME/.fkms/config.toml. You can generate a default config with:

fkms config init

Example config.toml

[server]
host = "127.0.0.1"
port = 50051

[logging]
log_level = ""

[signer_config]

# Local signers using various sources
[[signer_config.local_signer_configs]]
type = "private_key"
env_variable = "PRIVATE_KEY_1"
encoding = "hex"
chain_type = "evm"

[[signer_config.local_signer_configs]]
type         = "mnemonic"
env_variable = "MNEMONIC_1"
coin_type = 60
account = 0
index = 0

[tss]
enable_verify = true

[[tss.groups]]
public_key = "0232a786de4c99679f10fb9a1c94d17737739e413bef385a2f8a26f901a40fdc8b"
expired_time = 1234567890

Supported Local Signer Types

Type	Description	Required Fields
private_key	Load private key from an environment variable (Currently support only EVM)	env_variable, encoding
mnemonic	Load mnemonic from an environment variable	env_variable, coin_type, account, index

Encoding Options

• hex: The key is encoded in hexadecimal (0-9, a-f)
• base64: The key is base64-encoded

Environment variable must be defined in a .env file or via shell environment. Example .env file:

PRIVATE_KEY_1=abc123456789deadbeef...
MNEMONIC="test test test test test test test test test test test junk"

Usage

CLI Commands

• Initialize config:

  fkms config init [--path <config-path>] [--override]

• Validate config:

  fkms config validate [--path <config-path>]

• List keys:

  fkms key list [--path <config-path>]

• Start server:

  fkms start [--path <config-path>]

API

Generate protobufs (Rust)

The Rust server uses tonic-build. Rebuilding the project regenerates server/client code:

cargo clean
cargo build

The gRPC API is defined in proto/fkms/v1/signer.proto:

• SignEvm(SignEvmRequest): Sign a message with a given address (EVM)
• SignXrpl(SignXrplRequest): Sign a message with a given address (XRPL)
• GetSignerAddresses(GetSignerAddressesRequest): List available signer addresses

Example: SignEvmRequest

message SignEvmRequest {
  string address = 1;
  bytes message = 2;
}

Example: SignEvmResponse

message SignEvmResponse {
  bytes signature = 1;
}

Example: SignXrplRequest

message SignXrplRequest {
  XrplSignerPayload signer_payload = 1;
  Tss tss = 2;
}

Example: SignXrplResponse

message SignXrplResponse {
  bytes tx_blob = 1;
}

Example: GetSignerAddressesRequest

message GetSignerAddressesRequest {}

Example: GetSignerAddressesResponse

message GetSignerAddressesResponse {
  repeated string addresses = 1;
}

Example: XrplSignerPayload

message XrplSignerPayload {
  string account = 1;
  uint64 oracle_id = 2;
  string fee = 3;
  uint64 sequence = 4;
}

Example: Tss

message Tss {
  bytes message = 1;
  bytes random_addr = 2;
  bytes signature_s = 3;
}

Example: Signers

message Signers {
  ChainType chain_type = 1;
  repeated string addresses = 2;
}

Example: ChainType

enum ChainType {
  EVM = 0;
  XRPL = 1;
}

XRPL Signing Notes

• The server constructs an XRPL transaction from the XrplSignerPayload, encodes it using XRPL's encode_for_signing, and computes the XRPL-standard SHA512Half digest of those encoded transaction bytes (SHA-512, then taking the first 32 bytes) before signing.
• Signatures are returned as DER-encoded ECDSA bytes.

Extending

• Middleware: Add authentication or other middleware by enabling the middleware feature and configuring as needed.
• AWS KMS: Enable the aws feature and configure AWS signers in the config.