This page explains the core architecture of TrustVault. Understanding these concepts is essential before working through any of the transaction or policy tutorials.
Wallets and sub-wallets#
A wallet in TrustVault is a BIP32 hierarchical deterministic (HD) key container. It holds the policy that governs who can sign from it — but it does not hold assets directly.A sub-wallet is a child derivation path within a wallet. Sub-wallets hold actual on-chain addresses and balances. A single wallet can contain many sub-wallets across different chains (e.g. one ETH sub-wallet, one BTC sub-wallet). All sub-wallets inherit the signing policy of their parent wallet.When you create a transaction, you specify the sub-wallet address to send from. The wallet's policy then determines what signatures are required before the transaction is submitted to the network.
Policies and M-of-N signing#
Each wallet has a policy made up of one or more schedules. A schedule is a set of clauses. Each clause defines a group of keys (Instruction Keys) and a quorumCount — the minimum number of those keys that must sign for the clause to be satisfied.Clauses within a schedule are AND'd: all clauses in a schedule must be satisfied.
Schedules are OR'd: any one satisfied schedule activates the policy.
Instruction Keys and signing paths#
Every wallet policy has an Instruction Key — the private/public key that must sign transactions. These are not the HSM secured keys but a set of delegation keys that customers hold to prove cryptographically the intent to send transactions. TrustVault supports two ways to hold this key:1.
iOS app — the Instruction Key lives in the secure enclave of an iPhone. Transactions appear in the TrustVault app for manual review and approval. No programmatic signing is needed.
2.
External (programmatic) key — you generate and hold your own key pair (on secp256r1 / P-256), typically stored in a service like AWS KMS. Transactions are signed automatically in your code via the API. No iPhone is ever required.
Provenance signatures#
When TrustVault returns transaction data or a new sub-wallet address, it includes a provenance signature — an ECDSA signature from the HSM that holds the wallet - over the returned data.Verifying this signature against the TrustVault public key proves the data originated from TrustVault and has not been tampered with in transit. For production integrations this verification is strongly recommended before signing any transaction.The public keys for each environment, and how to verify them via DNS, are listed on the Security page.
The HSM#
TrustVault uses a Hardware Security Module (HSM) — a tamper-resistant physical device — to hold the master signing key. The HSM:Generates and stores cryptographic keys that never leave the device in plaintext.
Signs the provenance signatures attached to every response.
Co-signs policy changes before they become active.
The TCSS co-signing service#
The Transaction Co-Signing Service (TCSS) is an additional layer of control that runs before a transaction is submitted to the network. It enforces rules defined at the wallet level — most commonly destination allowlisting.If your wallet is configured with an Address Book, TCSS will reject any transaction destined for an address not in that book, regardless of whether the Instruction Key has signed it.This means the address book and TCSS work together: the address book defines the allowed destinations, and TCSS enforces them at signing time. See Address Book V2 for how to manage allowed destinations.
Putting it together: a transaction flow#
1.
Your code calls createEthereumTransaction (or equivalent) via the GraphQL API.
2.
TrustVault validates the request and constructs the transaction data, including signData and unverifiedDigestData.
3.
The provenance signature on the response lets you verify the data came from TrustVault.
4.
You (or the iOS app) sign shaSignData with the Instruction Key and submit the signature via addSignature.
5.
TCSS checks the destination against any allowlist rules.
6.
Once all required signatures are collected (per the wallet policy), TrustVault submits the transaction to the network.
7.
Webhooks fire as the request progresses (e.g. transaction created, signed, and received). See Webhooks for the full list of events. Modified at 2026-10-29 12:49:32
