Client Signer Setup

Skip this page if you only need manual transaction approval via the MPCVault app. The client signer is only required for automated signing.

The client signer is a Docker container that:

Maintains a secure connection to MPCVault
Receives signing callbacks when you call ExecuteSigningRequests
Approves transactions based on your callback server’s response

Prerequisites

Docker (or Docker Compose) installed
A server with a stable internet connection
A callback endpoint on your backend to receive and approve signing requests
An API user already created

Step 1: Generate an Ed25519 Key Pair

The client signer authenticates with MPCVault using an Ed25519 key pair. Generate one locally:

# Generate the key pair
ssh-keygen -t ed25519 -C "mpcvault-client-signer" -f ./client-signer-key -N ""

# View the public key (you'll need this for MPCVault console)
cat ./client-signer-key.pub

# View the private key (you'll need this for config.yml)
cat ./client-signer-key

The public key looks like:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIK0wmN/Cr3JXqmLW7u+g9pTh+wyqDHpSQEIQczXkVx9q mpcvault-client-signer

No password: The key must not have a passphrase for the client signer to use it automatically.

Step 2: Register the Client Signer in Your Vault

Go to console.mpcvault.com
Navigate to your vault’s Team & policies page
Click + New Client Signer

Enter the information:

Field	Description
Name	Identifier for this signer (e.g., `production-signer`)
Public key	Paste the contents of `client-signer-key.pub`
IP Whitelist	(Optional) Your server’s IP addresses

Click Continue → Confirm to create a signing request
Approve the Vault setting update request in the MPCVault app

Step 3: Grant Key Access

After creating the client signer, MPCVault automatically creates a Key grant access signing request. This grants the client signer permission to participate in MPC signing. Approve this request in the MPCVault app to complete setup.

One signer per vault: Each vault requires its own client signer. You cannot reuse the same signer across multiple vaults.

Step 4: Create the Configuration File

Create config.yml with your settings:

# Health check endpoint for monitoring
http-health:
  listening-addr: 0.0.0.0:8080

# Your vault's UUID (find in vault settings)
vault-uuid: "350063e9-xxxx-xxxx-xxxx-aaf939821815"

# Authentication
ssh:
  private-key: |
    -----BEGIN OPENSSH PRIVATE KEY-----
    b3BlbnNzaC1rZXktdjEAAAAABG5vbmUAAAAEbm9uZQAAAAAAAAABAAAAMwAAAAtz
    c2gtZWQyNTUxOQAAACCtMJjfwq9yV6pi1u7voPaU4fsMqgx6UkBCEHM15FcfagAA
    AJgPBwb8DwcG/AAAAAtzc2gtZWQyNTUxOQAAACCtMJjfwq9yV6pi1u7voPaU4fsM
    qgx6UkBCEHM15FcfagAAAEBKbCX7sP2Y3yL4H8Mz220wK0wmN/Cr3JXqmLW7u+g9
    pTh+wyqDHpSQEIQczXkVx9qAAAAFW1wY3ZhdWx0LWNsaWVudC1zaWduZXI=
    -----END OPENSSH PRIVATE KEY-----
  password: ""

# Your callback endpoint
callback-url: "http://host.docker.internal:8088/api/mpcvault/callback"

Configuration reference:

Field	Description	Example
`http-health.listening-addr`	Health check endpoint	`0.0.0.0:8080`
`vault-uuid`	UUID from vault settings page	`350063e9-...`
`ssh.private-key`	Full private key content	`-----BEGIN OPENSSH...`
`ssh.password`	Key passphrase (empty if none)	`""`
`callback-url`	Your backend endpoint for approvals	`http://your-server:8088/callback`

Step 5: Run the Client Signer

Option A: Docker Run (Development)

docker run -d \
  --name mpcvault-signer \
  --restart unless-stopped \
  -p 8080:8080 \
  -v $(pwd)/config.yml:/config.yml:ro \
  ghcr.io/mpcvault/client-signer:latest \
  --config-path=/config.yml

Option B: Docker Compose (Recommended for Production)

Create docker-compose.yml:

version: '3.8'

services:
  mpcvault-signer:
    image: ghcr.io/mpcvault/client-signer:latest
    container_name: mpcvault-signer
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - ./config.yml:/config.yml:ro
    command: ["--config-path=/config.yml"]
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

Start with:

docker-compose up -d

Running on macOS (Apple Silicon)

The Client Signer image currently supports linux/amd64 only. Docker Desktop can run the image on Apple Silicon Macs using amd64 emulation. You may see the platform mismatch warning below. The warning itself does not prevent the container from running.

WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested

If the container does not run correctly, try enabling Use Rosetta for x86_64/amd64 emulation on Apple Silicon in Docker Desktop → Settings → General, then run it again. You can also explicitly specify the platform if needed:

docker run -d \
  --platform linux/amd64 \
  --name mpcvault-signer \
  --restart unless-stopped \
  -p 8080:8080 \
  -v $(pwd)/config.yml:/config.yml:ro \
  ghcr.io/mpcvault/client-signer:latest \
  --config-path=/config.yml

services:
  mpcvault-signer:
    image: ghcr.io/mpcvault/client-signer:latest
    platform: linux/amd64
    # ...rest unchanged

For production, we recommend a native linux/amd64 host.

Verify it’s running

# Check container status
docker ps | grep mpcvault-signer

# Check health endpoint
curl http://localhost:8080/health

# View logs
docker logs -f mpcvault-signer

Docker image: ghcr.io/mpcvault/client-signer

Step 6: Implement Your Callback Handler

When you call ExecuteSigningRequests, MPCVault sends a callback to your callback-url. Your server must:

Receive the callback (POST request with protobuf body)
Validate the signing request against your business rules
Return HTTP 200 to approve, or 4xx/5xx to reject

Example callback handler (Node.js/Express):

const express = require('express');
const app = express();

// Parse raw protobuf body
app.use('/api/mpcvault/callback', express.raw({ type: '*/*' }));

app.post('/api/mpcvault/callback', async (req, res) => {
  try {
    // The body contains a serialized SigningRequest protobuf
    const signingRequestData = req.body;

    // Implement your validation logic here:
    // - Check amount limits
    // - Verify destination addresses
    // - Apply rate limiting
    // - Log for audit trail

    const shouldApprove = await validateSigningRequest(signingRequestData);

    if (shouldApprove) {
      // Return 200 to approve the transaction
      res.status(200).send('approved');
    } else {
      // Return 4xx to reject
      res.status(403).send('rejected');
    }
  } catch (error) {
    console.error('Callback error:', error);
    res.status(500).send('error');
  }
});

app.listen(8088, () => {
  console.log('Callback server running on port 8088');
});

Security: Your callback endpoint should validate requests and implement appropriate access controls. Consider using request signing or IP whitelisting.

Docker Networking

Your Setup	Callback URL Format
Callback server on same host as Docker	`http://host.docker.internal:PORT/path`
Callback server in same Docker network	`http://service-name:PORT/path`
Callback server on remote host	`http://your-server.com:PORT/path`

host.docker.internal is a special DNS name that resolves to the host machine from inside a Docker container. It works on Docker Desktop (Mac/Windows) and recent Docker Engine versions on Linux.

How Signing Works

When you call ExecuteSigningRequests:

Troubleshooting

Issue	Cause	Solution
Container won’t start	Invalid config.yml	Check YAML syntax and key format
Container doesn’t run correctly on Apple Silicon Mac	`amd64` image needs emulation	Try enabling Rosetta in Docker Desktop (see Running on macOS)
Platform mismatch warning on macOS	Image is `linux/amd64`, host is Apple Silicon	Safe to ignore; optionally add `--platform linux/amd64`
No callbacks received	Wrong callback URL	Use `host.docker.internal` for local
Connection refused	Port not exposed	Verify `-p 8080:8080` mapping
Auth failed	Key mismatch	Ensure public key matches private key
Key access denied	Missing approval	Approve Key grant access in app
Timeout	Callback too slow	Respond within 5 seconds
Transaction rejected	Non-200 response	Check your validation logic

Useful Commands

# Check signer logs
docker logs -f mpcvault-signer

# Restart signer
docker restart mpcvault-signer

# Check health
curl http://localhost:8080/health

# Test callback endpoint
curl -X POST http://localhost:8088/api/mpcvault/callback \
  -H "Content-Type: application/octet-stream" \
  -d "test"

Getting Started

Wallets

Signing Requests

Batch Payments

Deposit & Sweep

TRON Watch Address

Client Signer Setup

Prerequisites

Step 1: Generate an Ed25519 Key Pair

Step 2: Register the Client Signer in Your Vault

Step 3: Grant Key Access

Step 4: Create the Configuration File

Step 5: Run the Client Signer

Option A: Docker Run (Development)

Option B: Docker Compose (Recommended for Production)

Running on macOS (Apple Silicon)

Verify it’s running

Step 6: Implement Your Callback Handler

Docker Networking

How Signing Works

Troubleshooting

Useful Commands

​Prerequisites

​Step 1: Generate an Ed25519 Key Pair

​Step 2: Register the Client Signer in Your Vault

​Step 3: Grant Key Access

​Step 4: Create the Configuration File

​Step 5: Run the Client Signer

​Option A: Docker Run (Development)

​Option B: Docker Compose (Recommended for Production)

​Running on macOS (Apple Silicon)

​Verify it’s running

​Step 6: Implement Your Callback Handler

​Docker Networking

​How Signing Works

​Troubleshooting

​Useful Commands

Prerequisites

Step 1: Generate an Ed25519 Key Pair

Step 2: Register the Client Signer in Your Vault

Step 3: Grant Key Access

Step 4: Create the Configuration File

Step 5: Run the Client Signer

Option A: Docker Run (Development)

Option B: Docker Compose (Recommended for Production)

Running on macOS (Apple Silicon)

Verify it’s running

Step 6: Implement Your Callback Handler

Docker Networking

How Signing Works

Troubleshooting

Useful Commands