blockd uses named collections of ScriptPubKeys. A single collection is called a pubkeys_set — used for tracking transaction history, subscriptions, and cached UTXO state. See Wallets & ScriptPubKeys for the underlying model.

Each pubkeys_set receives a user-defined name when it’s created.

Naming

A pubkeys_set name is a plain string — something like hot-wallet or cold/vault. Names are stable identifiers: they appear in workflow submissions, REST requests, and WebSocket subscriptions. Your application defines them; blockd stores and references them.

Slashes enable hierarchical organization:

hot/daily-spend
cold/long-term
hardware/vault
exchange/withdrawals

The hierarchy is purely logical — blockd does not interpret or enforce it. There is no API mechanism to enumerate names by prefix. A pubkeys_set is accessible only to clients that know its exact name.

Naming patterns

Names only need to be meaningful to your application — choose whatever makes sets easy to identify and avoids collisions as your deployment grows.

Simple names

For most deployments, simple descriptive names are sufficient:

hot-wallet
cold-storage
hardware-vault

By use-case or custody model

When managing funds across multiple purposes or custody arrangements, encoding the use-case keeps sets unambiguous:

hot/daily-spend
cold/long-term
hardware/vault
exchange/withdrawals

Ephemeral workflows

For applications that query wallet data periodically without requiring ongoing monitoring — accounting systems, reporting tools — consider using names with timestamps or operation identifiers:

report/2024-q4/temp
audit/2024-annual/temp

Validation rules

pubkeys_set names must conform to the following:

Rule	Detail
Length	1–255 characters
Reserved names	Cannot be . or ..
Slashes	Cannot start or end with /, cannot contain consecutive //
Trailing dot	Cannot end with .
Allowed characters	Alphanumeric, -, _, /, .
Control characters	Not permitted

Lifecycle

Deleting a pubkeys_set

To fully remove a pubkeys_set from blockd and Fulcrum, subscriptions must be explicitly cancelled before deletion. If pubkeys.scripthash.subscribe was previously run, pubkeys.scripthash.unsubscribe must precede pubkeys.set.delete — otherwise orphaned script hash subscriptions remain active in Fulcrum:

{
  "workflow": {
    "args": {"pubkeys_set": "cold/long-term"},
    "steps": [
      {"step": "pubkeys.scripthash.unsubscribe"},
      {"step": "pubkeys.set.delete"}
    ]
  }
}

If the pubkeys_set was never subscribed — for example, a workflow that imported addresses but omitted pubkeys.scripthash.subscribe — pubkeys.set.delete alone is sufficient.

Extended public key privacy

Importing a wallet via xpub has additional privacy implications beyond pubkeys_set naming — address linkage, cache persistence, and hardened derivation paths. See Extended Public Keys for details.