Vault Raw Signing Overview

Overview

Raw Signing presents inherent security risks, as it involves signing transactions without contextual validation. However, with great power comes great responsibility. This document outlines best practices to ensure the secure and effective use of the raw signing feature.

Consequently, Raw Signing is considered a specialized feature, not included by default in your workspace, and is only accessible upon request for specific use cases. If you're interested in this feature and want to see if your use case is eligible for it, please contact your Technical Account Manager (TAM).

Raw Signing is a very powerful feature to be used within the Vault. As the Web3 world continues to rapidly evolve, LES provides an option to sign digests using the Vault infrastructure in order to support chains and actions that the Vault does not natively support.

Use Cases

• When you want to sign a transaction or a digest on a blockchain that the Vault does not currently support.

• When you want to perform an action that we don’t currently support (for example staking on a protocol where we don’t support staking) on a blockchain we do actively support.

• When you want to prove messages on-chain (that are not supported by our Proof of Reserver feature with Message Signing).

How to enable Raw Signing ?

By default, Raw Signing is not available on your workspace. Contact your Technical Account Manager (TAM) Customer Success team to enable Raw Signing.

You need to have created a Raw Signing Account before being able to use this feature. Navigate to the Account Creation page for more details.

Raw Signing Example

Creating a request

It uses the same flow as creating a request from an API Operator: see here

First, let’s look at the schema for this request:

DigestToSign {
  digest: str,
  derivation_path: str
}

SignedDigest {
  digest: str,
  signature: str,
  pub_key: str,
  derivation_path: str
}

The request is built as follows:

1. Add digests_data

2. Within this object, add account_name and digests

   {
   "data": {
   "account_id": number,
   "digests_data": {
    "account_name": "...",
    "digests": DigestToSign[]  // allow the customer to sign multiple transaction in one request
   }
   },
   "type": "SIGN_DIGESTS"
   }

DigestToSign

Parameter	Type	Description
digest	string	A HexString digests. For currencies that use secp256K1, string must be 32 bytes long
derivation_path	string

Approving a request

GET /requests/:id/challenge
{
  "challenge": "eyJhbnRpcmVwbGF5IjogIi4uLiIsICJkYXRhIjogeyJ0cmFuc2FjdGlvbl9kYXRh
  IjogeyJhY2NvdW50X25hbWUiOiAiLi4uIiwgInJhd190eHMiOiBbIi4uLiIsICIuLi4iXX19LCAidHl
  wZSI6ICJSQVdfVFJBTlNBQ1RJT05fU0lHTklORyJ9"
}
// this can be decoded into
{
  "antireplay": "...",
  "data": {
    "digests_data": {
      "account_name": "...",
      "digests": DigestToSign[]
    },
  },
  "type": "SIGN_DIGESTS"
}
POST /requests/:id/approve
{
  "jws": <signed challenge>
}

How to retrieve the Account Public Key ?

As a first iteration, you cannot directly get the account address or Public Key (pub_key) from a HSM-secured channel.

Instead you need to sign a first message from the account: As a first iteration, you cannot directly get the account address or Public Key (pub_key) from a HSM-secured channel. Instead you need to sign a first message from the account:

1. Sign any message using the Raw Signing Request (it can be message signing)

2. Get the Digest via GET /digests/:id to retrieve the pub_key in the payload

3. You can derive addresses from the pub key

GET /digests/:id

Digest {
  id: number,
  created_by: number,
  created_on: datetime,
  last_request: number,
  account_id: number,
  status: string,
  digests_data: SignedDigest[] | ToSignDigest[],
  notes: Note[]
}


ToSignDigest {
  digest: string,
  derivation_path: string
}


SignedDigest extend ToSignDigest {
  signature: string,
  pub_key: string
}


Note {
  title: string,
  content: string
}