SUBFROST Methods

SUBFROST provides threshold signature wallet functionality for regtest environments using FROST (Flexible Round-Optimized Schnorr Threshold signatures).

Overview

The SUBFROST RPC service implements a 9-of-6 threshold multisig wallet system where:

  • 9 signers participate in the protocol
  • 6 signatures are required to authorize transactions
  • Native SegWit (P2WPKH) addresses are derived from the FROST public key

These methods are primarily useful for regtest development and testing.

subfrost_getpublic

Returns the FROST public key and derived Bitcoin address.

Request

{
  "jsonrpc": "2.0",
  "method": "subfrost_getpublic",
  "params": [],
  "id": 1
}

Response

{
  "jsonrpc": "2.0",
  "result": {
    "frostPublicKey": "026e5f...",
    "address": "bcrt1q..."
  },
  "id": 1
}

Returns

  • frostPublicKey (string) - Hex-encoded FROST public key
  • address (string) - Native SegWit address (P2WPKH) derived from the FROST public key

subfrost_reset

Resets the regtest environment by deleting blockchain and indexer data while preserving the FROST wallet keystore.

Request

{
  "jsonrpc": "2.0",
  "method": "subfrost_reset",
  "params": [],
  "id": 1
}

Response

{
  "jsonrpc": "2.0",
  "result": {
    "status": "success",
    "message": "Reset regtest environment, deleted PVCs: [bitcoin-regtest-data, metashrew-regtest-data]",
    "deletedPVCs": ["bitcoin-regtest-data", "metashrew-regtest-data"]
  },
  "id": 1
}

Returns

  • status (string) - "success" if reset completed
  • message (string) - Description of actions taken
  • deletedPVCs (array) - List of Kubernetes PersistentVolumeClaims that were deleted

Behavior

  1. Deletes blockchain data (bitcoin-regtest-data PVC)
  2. Deletes indexer data (metashrew-regtest-data PVC)
  3. Preserves FROST wallet keystore (subfrost-wallet-data PVC)
  4. Pods automatically restart with fresh blockchain state
  5. FROST wallet retains the same address after reset

Use Cases

  • Start fresh regtest environment without changing wallet address
  • Clear blockchain state during testing
  • Reset indexer data without regenerating wallet

subfrost_thieve

Sends Bitcoin from the FROST wallet to a specified address on regtest. Mines 1 confirmation block automatically.

Request

{
  "jsonrpc": "2.0",
  "method": "subfrost_thieve",
  "params": {
    "address": "bcrt1q...",
    "amount_sats": 100000000
  },
  "id": 1
}

Parameters

  • address (string, required) - Recipient Bitcoin address
  • amount_sats (number, required) - Amount in satoshis (max: 1,000,000 = 0.01 BTC)

Response

{
  "jsonrpc": "2.0",
  "result": {
    "txid": "abc123...",
    "amount_sats": 100000000,
    "recipient": "bcrt1q...",
    "confirmations": 1
  },
  "id": 1
}

Returns

  • txid (string) - Transaction ID of the sent transaction
  • amount_sats (number) - Amount sent in satoshis
  • recipient (string) - Recipient address
  • confirmations (number) - Number of confirmations (always 1)

Limits

  • Maximum amount: 1,000,000 satoshis (0.01 BTC)
  • Automatically mines 1 block for confirmation
  • Rate limited by generatetoaddress guard (max 1 block per call)

Example

curl -X POST https://regtest.subfrost.io/v4/jsonrpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "subfrost_thieve",
    "params": {
      "address": "bcrt1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
      "amount_sats": 500000
    },
    "id": 1
  }'

Use Cases

  • Fund test addresses during development
  • Test transaction flows without mining rewards
  • Quick regtest wallet operations

Error Handling

Common Errors

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32603,
    "message": "Wallet not loaded or keystore not found"
  },
  "id": 1
}

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Amount exceeds maximum of 1000000 satoshis"
  },
  "id": 1
}

FROST Wallet Architecture

The SUBFROST implementation uses:

  • FROST Protocol: Flexible Round-Optimized Schnorr Threshold signatures
  • 9-of-6 Configuration: 9 total signers, 6 required for valid signature
  • P2WPKH Addresses: Native SegWit addresses for lower fees
  • Persistent Keystore: Wallet survives pod restarts and environment resets

Security Considerations

  • These methods are designed for regtest only and should never be exposed on mainnet
  • The subfrost_thieve method has amount limits to prevent accidental large transfers
  • Rate limiting prevents excessive block generation via automatic confirmation mining

Next Steps