Vaults, signers, and thresholds

Understand how signer weights combine to control an io.sign vault

In io.sign, no one holds a whole private key. Each key is split into key shares, and each share is held by a different signer. To sign, enough signers must approve to meet the vault's threshold.

Core concepts

Vault

A vault is an ECDSA and EdDSA key pair, split between the vault's signers according to their weights. It records the public keys, the signers, each signer's weight, and the threshold needed to sign.

A vault doesn't store a complete private key. Its signers hold key shares and use Multi-Party Computation (MPC) to create signatures together.

Signer

A signer is a device or service that holds a key share and can participate in an MPC operation:

  • A Mobile Signer lets a person review and approve requests in the io.sign mobile app.
  • A Virtual Signer runs as a service and evaluates requests with Open Policy Agent (OPA) or a custom policy server.

A vault can use either type or combine both types.

Weight

A signer's weight is its contribution toward the vault threshold. Weight represents signing power, not the number of devices or approvals.

Threshold

The threshold is the minimum combined signer weight required to perform a signing operation.

valid signing set: sum(participating signer weights) >= vault threshold

The number of participating signers alone doesn't determine whether a set can sign.

Worked example

A threshold-4 vault contains three signers with weights 2, 2, and 4:

Signing setCombined weightCan sign?
First weight-2 signer2No
Both weight-2 signers4Yes
Weight-4 signer4Yes
Any weight-2 signer plus the weight-4 signer6Yes

This arrangement provides two paths: two lower-weight signers can collaborate, or the weight-4 signer can act independently.

🚧

A threshold doesn't guarantee multiple participants. If one signer has weight equal to or greater than the threshold, that signer can meet the threshold alone. To require collaboration, keep every individual signer below the threshold.

Approval and signing

An approval records a signer's decision to participate in a requested operation. A Mobile Signer can obtain a decision from a person; a Virtual Signer obtains a policy decision from OPA or a custom policy server.

Signing begins after an eligible set of approved signers is available. Those signers run the MPC protocol and jointly produce the signature without reconstructing the complete private key.

For how threshold signatures (TSS) use MPC to produce a standard digital signature, see Digital signature algorithms.

Rejecting or abstaining means that signer does not contribute its weight to that operation. The operation can still proceed if another set of participating signers reaches the threshold.

Key generation and resharing

  • Key generation creates a new vault. Each of its initial signers ends up holding its own key share.
  • Resharing changes signer membership or weights while retaining the vault's public key. See Reshare a vault.

Treat changes to membership, weight, and threshold as security-policy changes. Review which signer combinations can meet the threshold before creating or resharing a vault.

Next steps


Did this page help you?