Skip to main content

Setup and Register a Rule Server

The first step in setting up Policies for the Vertex is to set up a Rule Server.

Security Note

In order to maintain the distributed security guarantees of the system, it is recommended to have a dedicated instance of the Rule Server for each Vertex instance (running the same logic).

Securing the Connection​

The Rule Server will receive POST requests from the Vertex to the URL provided when defining the Rule in the Vertex. Each request will be a JWT that is signed by the Vertex.
In order to verify the JWT, the Rule Server must be configured with the Vertex public key, that can be retrieved in PEM format using:

curl -X GET 'https://<YOUR_VERTEX>/identity-pubkey' > vertex_public_key.pem

The public key can then be used to verify the JWT signature using the ES256 algorithm.

Generating a JWT Keypair​

The Vertex supports both the ES256 (our recommendation) and RS256 (RSA 2048-bit) algorithms for Rule Server JWTs. To generate a keypair for the Rule Server, you can use the following commands:

# Generating the private key
openssl ecparam -name prime256v1 -genkey -noout -out es256_private.pem
# Generating the public key in PEM format
openssl ec -in es256_private.pem -pubout -out es256_public.pem

Request Data Spec​

The JWT will contain a JSON structure that always includes an action field, each action has a different data structure:

{
  "action": "sign_ed25519",
  "request": {
    "msg": "1a2b3c4d5e6f", // The message to be signed in hex format
    "derived_pubkey": "04bd59...99ec", // The public key of the key to use for signing
    "key_name": "HUMAN-READABLE-KEY-NAME" // The name of the HMAC key to use for signing
  },
  "extra_data": "", // Any extra data (in hex format) that was sent with the original signing request to help the Rule Server validate the request
  "request_id": "f032f5c0-e69a-4f86-8ef9-9ac79e8fbc42" // A unique identifier for the request, must be included in the response.
}

Response Data Spec​

The Rule Server must respond with a JWT that is signed by the Rule Server's private key.
The structure of the response JWT must be one of the following:

{
  "result": "approved", // The result of the request, must be 'approved' to sign the message
  "request_id": "f032f5c0-e69a-4f86-8ef9-9ac79e8fbc42" // The request_id from the request
}

Rule Server Examples​

Whitelisting Withdrawal Addresses Policy​

An example Rule Server implementation for a policy that implements whitelisting for withdrawal addresses is found here (please contact the Sodot team in case you do not have access).
For instructions on how to set up and run the example Rule Server, please refer to the README.md file in the repository.

Minimal Rule Server Example​

Below is a minimal example of a Rule Server implemented in Node.js using the Express framework and the jsonwebtoken library. This example Rule Server approves all signing requests.

The flow is as follows:

  1. The Rule Server receives a POST request from the Vertex.
  2. The Rule Server validates the JWT signature using the Vertex public key.
  3. The Rule Server parses the request data and validates the message or transaction that is being signed.
  4. The Rule Server responds with a JWT indicating whether the request is approved.
rule_server.js
const express = require("express");
const jwt = require("jsonwebtoken");
const fs = require("fs");
// Load the Rule Server private key and the Vertex public key
const privateKey = fs.readFileSync("rule_private.pem");
const vertexPubkey = fs.readFileSync("vertex_public_key.pem");

const app = express();
const port = 80;

app.use(function (req) {
  req.decodedBody = "";
  req.setEncoding("utf8");
  req.on("data", function (chunk) {
    req.decodedBody += chunk;
  });
  req.on("end", function () {
    req.next();
  });
});

app.post("/validate_transaction", (req, res) => {
  let signRequest = "";
  try {
    signRequest = jwt.verify(req.decodedBody, vertexPubkey);
  } catch (error) {
    res.sendStatus(401); // Unauthorized
  }

  if (signRequest) {
    const { request_id } = signRequest; // request_id must be returned in the response
    console.log("Sign request data", signRequest); // For this example we only print the request
    let result = "approved"; // We will approve all requests in this example
    const jwtRes = jwt.sign(
      {
        result,
        request_id,
      },
      privateKey,
      { algorithm: "RS256" } // For this example we use RS256
    );
    res.send(jwtRes);
  }
});

app.listen(port, () => {
  console.log(`Server listening at http://0.0.0.0:${port}`);
});

Next Steps​

Once the Rule Server is set up, you can define the Rule in the Vertex and create a Policy that includes the Rule. Full details on setting up Policies on the Vertex can be found here.