Vault Raw Signing 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.

Prerequisites

• Create a Raw Signing Account

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
   Copy

   Copied

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

DigestToSign

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 Extended Public Key ?

As a first iteration, you cannot directly get the account address or Extended 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 the address from the pub key using derivation path

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
}