Security and signing

Private-key design is a product and operational decision, not only a cryptographic one. The correct profile depends on who must be able to sign, how recovery works, and the acceptable blast radius.

From entropy to a private key

An EVM private key can be generated directly from cryptographically secure randomness as a valid 256-bit scalar. User wallets often start from entropy represented as a BIP-39 mnemonic; mnemonic plus optional passphrase is processed through PBKDF2-HMAC-SHA512 to produce a seed, then an HD tree derives account keys.

A BIP-39 passphrase is not a resettable server password. Every passphrase produces a valid seed; forgetting the exact passphrase can make the original wallet inaccessible unless another recovery mechanism was designed in advance.

Initial Partner-managed baseline

Initial baseline

1. one high-entropy master key per deployment/environment;
2. stored/versioned in a protected secret store readable only by the Signer Gateway — a Partner-controlled vault in a production deployment;
3. never made available to the B2B API process;
4. versioned, domain-separated derivation by deployment/tenant, chain, wallet/account, role and keyVersion;
5. B2B API stores only keyReference, public address and version metadata;
6. every signing request produces durable audit evidence.

flowchart LR
    API[B2B API / worker] -->|1| SG[Partner Signer Gateway]
    SG -->|2| V[Sandbox secret file / Partner vault]
    V -->|3| SG
    SG -->|4| K[KDF + versioned domain]
    K -->|5| E[Ephemeral derived key]
    E -->|6| S[Signature]
    S -->|7| API

What each step does

1. B2B API / worker → Partner Signer Gateway. The request carries a keyReference, the exact digest, an idempotency key, the tenant, wallet and chain context, the capability, the policy version, a nonce and a deadline. That reference is what names the key.
2. Gateway → sandbox secret file or Partner vault. The gateway is the one workload authorized to read the master secret: a protected local file in the sandbox, the Partner's own secret service in a real deployment.
3. Vault → gateway. The master secret reaches the signer alone. Each environment holds its own, and an environment with real funds gets a master key of its own.
4. Gateway → versioned derivation. A KDF with explicit domain separation combines the master secret with the tenant or deployment, the chain family, the wallet, the role and the key version.
5. Derivation → ephemeral derived key. The derived key exists for the cryptographic operation and stays out of business data. Reproducing it later takes the same master secret, the same domain and the same version, which is what makes recovery possible.
6. Derived key → signature. The gateway applies policy, limits and replay checks, and then signs the digest it received.
7. Signature → B2B API. Back come the signature, the address, an audit reference and the key version. The API verifies the signature against the digest and the expected address before anything is broadcast.

The protected sandbox file validates the same signing boundary without pretending to be a production vault. In a real Partner environment, a vault protects storage, IAM and auditing, but a software signer still handles exportable key material in memory. This is not equivalent to a non-exportable HSM key.

Sandbox as the first signing consumer

Current Implementation The Partner Signer Gateway starts independently, and the B2B API only receives its URL.

EVM wallet authorities use versioned references such as wallet-eoa:<chainId>:<walletId>:v1, and native EIP-7702 authorization digests are signed through the gateway instead of deriving the wallet private key inside the API.

EVM, Bitcoin and LI.FI transfers cross the same boundary with operation-scoped digests. Bitcoin additionally derives its P2WPKH address from the gateway's public key.

This is the same SigningProvider boundary every Partner deployment uses.

Trade-offs

Custody implications

In the partner_managed profile the Partner has technical signing authority under its policies and can therefore move funds if those controls authorize it. That is custodial from the end user's perspective. Self-custody requires a different authority model in which the Partner cannot unilaterally sign.

EIP-7702-specific authority

The native EOA key can authorize redelegation or clear the EIP-7702 delegation even when daily operations use a separate validator. It therefore receives its own logical role, key reference and recovery controls.

Recovery

Losing an operational validator can be handled by rotation if higher authority remains. Losing the master key without a usable backup can affect every wallet derived from that master. A user who loses a mnemonic/passphrase cannot rely on ChatterPay to mathematically recreate it. Recovery must be designed before loss occurs.

Capabilities in this area

This area covers the capabilities below. The Roadmap states the current availability of each one.

• Separate Signer Gateway — Signing runs in a separate service, inside the Partner's environment. The API sends a digest and a key reference and receives the signature; it never reads the private key.

• Validator, admin, recovery and Bootstrap signing — Each of those roles signs through the gateway or a keystore, and every signature records which role produced it. The API asks for the signature of the role the operation requires.

• Security analysis across the suite — The build runs static analysis over the contracts, the application code and the repositories, plus a scan for exposed secrets. A finding stops the build.

• Vulnerable dependency remediation — Dependencies with known vulnerabilities are updated or replaced, and the audit runs as part of the build so a new one is detected the moment it is introduced.

• EIP-7702, Bitcoin and relayer keys outside the API — The signing keys the API can still reach move behind the gateway, so the API is left holding only public addresses and key references.

• KMS, HSM or MPC signing backend — A backend where the private key is generated and used inside the service and cannot be exported. The gateway asks it for the signature and receives the result.