Co-Signer

What the Co-Signer does

The BroSettlement Co-Signer is an open-source service that runs on infrastructure you control. It:

• polls BroSettlement for pending DKG and signing intents;
• authenticates requests with your Ed25519 API key;
• claims work through signed HTTPS requests;
• exchanges MPC protocol messages through BroSettlement;
• stores your MPC key share as an encrypted local file;
• participates in transaction signing without reconstructing a complete private key;
• reports the final result to BroSettlement.

Repository: BroLabel/brosettlement-mpc-co-signer

Trust boundary

BroSettlement and your Co-Signer each control separate MPC signing material. BroSettlement cannot complete an MPC signature without the client-controlled Co-Signer participating.

The Co-Signer uses a pull model. It initiates outbound HTTPS connections to BroSettlement; you do not need to expose the Co-Signer's local health port to the public internet.

Required configuration

Secret handling

Follow these rules for every environment:

• never commit private.pem, the share-encryption key, or the shares directory;
• never send secrets through command-line arguments, query strings, tickets, or chat;
• inject secrets at runtime through a secret manager or protected files;
• restrict the API key using the required scopes and access settings shown on the API-key page;
• bind the health endpoint to 127.0.0.1 unless a private monitoring network requires otherwise;
• restrict the shares directory to the operating-system user that runs the Co-Signer;
• disable core dumps and prevent secrets or share contents from entering logs.

Persistent storage and backup

The Co-Signer writes one encrypted JSON file per MPC key to CO_SIGNER_SHARES_DIR. Files use AES-256-GCM encryption and are created with restricted permissions.

Protect and back up:

1. the complete persistent shares directory;
2. the matching share-encryption key;
3. the Ed25519 API private key or a documented API-key rotation procedure.

Store backups of encrypted shares and their encryption key in separate protected locations. Test restoration procedures before relying on them. A share file is not usable without the matching encryption key.

Do not delete, replace, or manually edit share files after MPC initialization. Do not copy share files between organizations.

Runtime and monitoring

The service writes structured JSON logs to standard output. Send stdout and stderr to your normal centralized logging system, but configure redaction and access controls appropriate for cryptographic infrastructure.

Monitor:

• process availability;
• /health response status;
• ready value;
• reported version;
• shares-directory check;
• Co-Signer status and last heartbeat in the BroSettlement Console;
• authentication, polling, DKG, and signing errors.

Updates

Before updating:

1. back up the encrypted shares directory;
2. verify that the matching share-encryption key is available;
3. read the release notes;
4. build and test the target version;
5. stop the old process cleanly;
6. start the new version with the same persistent shares directory and secrets;
7. verify local health and the BroSettlement heartbeat;
8. run a testnet signing check before returning the service to production use.

Do not start two Co-Signer processes against the same organization and shares directory unless the release documentation explicitly supports that deployment model.

Troubleshooting

The Co-Signer does not start

Check that all required variables are set and that:

• the private key is a valid Ed25519 key;
• CO_SIGNER_SHARES_DIR exists or can be created;
• the service user can read and write the shares directory;
• the local health port is available.

Local health returns ready: false

Inspect the checks.shares_dir result. Confirm that the configured directory exists and that the service user has permission to access it.

The Console shows the Co-Signer as offline

Check:

• CO_SIGNER_MONOLITH_URL matches the environment; staging uses https://brosettlement-staging-api.brolabel.io/;
• API Key ID;
• private key and uploaded public key match;
• all three MPC scopes are enabled;
• the network and allow-list settings on the API-key page are complete;
• outbound HTTPS access is available;
• the API key is active and has not expired or been revoked.

MPC remains not configured

An online Co-Signer does not automatically initialize MPC. Open Multi-Party Computation and explicitly select Initialize MPC.

MPC initialization fails

Keep the Co-Signer running and inspect its JSON logs. Resolve authentication, IP allow-list, connectivity, version, or storage errors before retrying. Retry only after the previous initialization attempt reaches a terminal failed or expired state.

Wallet creation is unavailable

Confirm that:

• the MPC key is Active or Ready;
• the Co-Signer is Online;
• the selected chain is Ready;
• the organization's plan permits another wallet.