Overview

Scenario. You are building a regulated custody product — institutional treasury, exchange custody backend, asset-management wallet, or compliance-grade self-custody for high-net-worth clients. You need three wallet tiers operating side-by-side:

• A hot wallet that signs at high throughput, cluster-managed, with no host holding a share — for operations where every microsecond matters and share-holding is delegated entirely to the cluster.
• A warm wallet that signs continuously online from a server-side host inside your custody backend — your standard operating-volume tier. The host is one of the threshold parties, so a cluster compromise alone cannot move funds.
• A cold wallet that holds reserves, signs rarely, and only after multi-party witnessed approval. The cold device produces a partial signature that's ferried via QR / USB to the online side, which combines it with the cluster's partial and broadcasts.

All three need a complete audit trail, role-based approval flows, and the ability to demonstrate to a regulator that no single party — including you — can move funds unilaterally.

This is the overview page. The sub-pages drill into each operational dimension with runnable code:

The recommended stack

• @zafeguard/mpc-sdk → ClusterAgent. Cluster client for the hot tier. Cluster nodes hold all shares; your backend drives ceremonies and combines partials via Scheme.finalizeSignature locally.
• @zafeguard/mpc-sdk → EmbeddedAgent. The warm tier. Your server-side host holds one share, the cluster cohort holds the rest; loaded.sign(...) runs the round-trip and returns a final signature locally.
• @zafeguard/mpc-sdk → the cold-wallet flow + agent.exportSignPack(...) + Scheme.finalizeSignature(...). The cold tier. Hot side exports a sealed key-share blob + per-message presignature packs; cold device produces a partial via Utils.unwrap + Utils.computePartialSignature flow; online operator combines.
• Zafeguard workflows. Every signing operation across all three tiers runs inside a workflow that enforces the policy your compliance team designed, captures the audit trail your auditor needs, and orchestrates the multi-party approvals your operating manual requires.
• Self-hosted MPC nodes when sovereign custody is required. The same SDK surface against a cluster running entirely inside your environment — no party outside your perimeter ever participates in any signing operation.

This combination — cluster-managed hot, host-as-threshold-party warm, partial-ferry cold, all on top of one workflow canvas that enforces policy and emits audit — is what lets your team ship a regulated-grade custody product in weeks instead of the 12–18 months a from-scratch crypto-engineering project takes.

Architecture

                          +----------------------+
                          |  Treasury operator   |
                          +----------+-----------+
                                     |
            request signing          |       approval (cold only)
                                     v
+------------------------------------------------------------------+
|  Zafeguard workflow canvas                                       |
|                                                                  |
|  Hot path  -> policy -> ClusterAgent ceremony -> Scheme.finalize     |
|  Warm path -> policy -> loaded.sign(...) on warm host (final)    |
|  Cold path -> policy -> quorum -> ferry pack -> partial -> combine|
+----------------+----------------------------------+--------------+
                 |                                  |
                 v                                  v
       Hot: MPC cluster                Warm: EmbeddedAgent host
       (cluster-only, no host)         (1 share on host + cohort)
                 |                                  |
                 v                                  v
                  ----------- shared cohort --------
                                  |
                                  v
       Cold: the cold-wallet flow + cluster (partial-ferry)
       (air-gapped device + per-message presig packs)
                                  |
                                  v
                        EVM · Solana · Bitcoin

Hot, warm, and cold all produce standard ECDSA (r, s, v) signatures externally indistinguishable from any single-signer transaction. The difference is operational: where the share-holding lives, where the final combine happens, and how the device participates.

When this design fits

Use the custody-whitelabel pattern when:

• You are building for institutions, not end consumers. Operators authenticate to your platform, sign on behalf of clients, and answer to compliance — there is no end-user device in the signing loop.
• You need tiered custody by design. Working capital must move quickly; reserves must move slowly and with witnesses. The regulatory shape demands the separation, and the operating model takes advantage of it.
• You need audit and right-to-revoke as platform features, not custom code. Regulators will examine the controls. The execution log of every workflow is the evidence.
• You may need to satisfy sovereignty requirements. Some jurisdictions or some clients require key material to never leave your perimeter — self-hosted MPC delivers that without changing your application code.

If your product is instead a consumer-facing embedded wallet where each end user holds a share on their own device, see the Embedded Wallet Solution.

Choosing a tier per operation

Most custody whitelabels run hot + warm + cold concurrently, with each tier holding a different key share and a different topology. The workflow canvas routes between them based on amount and policy.

Five-minute primer

Each tier uses a different combination of @zafeguard/mpc-sdk primitives:

import {
  ClusterAgent, EmbeddedAgent, the cold-wallet flow,
  Scheme, Curve, RecoveryKind,
} from '@zafeguard/mpc-sdk';

// ─── Hot tier — cluster-driven, partials combined off-line ────────────────
const hot = ClusterAgent.connect('hot-cluster.your-custody.com', 443, process.env.ZG_HOT!, true);
// agent.sessions.createSignMessage(...) → collect partials → Scheme.finalizeSignature(...)
// See: examples/custody-whitelabel-solution/hot-wallet

// ─── Warm tier — server-side EmbeddedAgent, online, local reconstruction ─
const warm = new EmbeddedAgent({ agent: warmCohort, threshold: 3, curve: Curve.Secp256k1 });
const warmLoaded = await warm.create({
  signerId: 'warm-treasury-vault',
  recovery: { kind: RecoveryKind.Custodial, custodialPublicKeyPem: hsmPubPem },
  passphrase: hostSealingPassphrase,    // seals warmLoaded.exportedBlob
});
// loaded.sign returns the threshold-many partials; combine them locally
// via loaded.finalizeSignature — no extra cohort round-trip.
const partials = await warmLoaded.sign({ messageHash });
const sig = await warmLoaded.finalizeSignature({
  messageHash: partials.messageHash,
  partials: partials.partials,
  derivationPath: partials.derivationPath,
});

// ─── Cold tier — the cold-wallet flow partial-ferry, online combines ─────────────
// Hot side: agent.exportSignPack(coldKeyShareId, [presigId], { publicKeyPem: coldRsaPub, delete: true })
// Cold device: the cold-wallet flow({ keyShareBlob, presignatureBlob, rsaPrivateKey, ... }).partialSignatureB64
// Online operator: Scheme.finalizeSignature(messageHash, [coldPartial, hotPartial], rootPub) → final
// See: examples/custody-whitelabel-solution/cold-wallet

The sub-pages cover what production operations require around each tier — the topology choices that match your risk model, the policy enforcement that satisfies your auditor, the multi-party approval flows for cold, and the runtime configuration patterns that let one platform serve many clients.

→ Canonical SDK references: MPC Agent, Embedded Agent, the cold-wallet flow and Scheme.finalizeSignature.

→ Continue with Hot Wallet.

Chain support

Both tiers sign on every supported network from the same key infrastructure.

Adding chain coverage to a custody product is adding the relevant chain component to the signing workflow. The MPC infrastructure is unchanged.

→ EVM components · Solana components · Bitcoin components

Where to read deeper

• Hot Wallet — cluster, topology, policy, audit.
• Cold Wallet — air-gapped ceremony, presignature pool under quorum, broadcast handoff.
• Regulated Design — compliance mapping, segregation of duties, sovereignty.
• Dynamic Configuration — per-client policy, multi-tenancy, runtime reconfiguration.
• Embedded Wallet Solution — the consumer-facing counterpart for the wallet tier you may layer above.
• MPC Agent reference — the full surface for the hot-tier cluster client.
• Embedded Agent reference — the cold-tier device + cohort facade.