Cobo TSS Node

Manage a Cobo TSS Node — the client-side MPC signing component for Cobo's co-managed custody.

When to Use

✅ USE this skill when:

• Installing the Cobo TSS Node binary
• Initializing a new TSS Node (generating keys + Node ID)
• Starting/stopping/restarting the node service
• Installing as a system service (Linux systemd / macOS launchd)
• Checking node health, viewing groups, or reading logs
• Periodic key share checkup signing
• Exporting shares for disaster recovery
• Backing up or updating the node

❌ DON'T use this skill when:

• Interacting with Cobo WaaS REST API → use Cobo SDK
• Building on-chain transactions directly
• Managing Cobo Portal (web UI operations)

Quick Start

./scripts/install.sh                        # Download binary
./scripts/setup-keyfile.sh                  # Create password file
./scripts/init-node.sh                      # Initialize (outputs Node ID)
./scripts/install-service.sh linux          # Install systemd service
./scripts/node-ctl.sh start                 # Start

Scripts

Daily Operations

All post-install operations go through node-ctl.sh:

./scripts/node-ctl.sh <command> [--dir ~/.cobo-tss-node]

Service Management

Linux uses journalctl, macOS reads from ~/.cobo-tss-node/logs/launchd-stdout.log.

Health Check

./scripts/node-ctl.sh health

Checks in one command:

• ✅/❌ Service running status
• 📌 Binary version
• ✅/❌ Database exists + file size
• ✅/❌ Config file present
• ✅/⚠️ Key file permissions (must be 600)
• 💾 Available disk space
• 📋 Node ID and metadata

MPC Group Management

./scripts/node-ctl.sh groups              # List all MPC groups
./scripts/node-ctl.sh group <group-id>    # Inspect a specific group

Shows group details: participants, threshold, public key, protocol type.

Key Share Checkup (Periodic Signing)

./scripts/node-ctl.sh sign <group-id> [message]

• Signs a message using the local key share — proves share integrity without full MPC ceremony
• If no message given, auto-generates: checkup-YYYY-MM-DD
• Recommended: run weekly or after any infrastructure changes
• This is a local-only operation (no network/WebSocket needed)

Disaster Recovery Export

./scripts/node-ctl.sh export <group-id1,group-id2,...>

• Exports encrypted key share files to a timestamped directory: ~/.cobo-tss-node/recovery/YYYYMMDD-HHMMSS/
• Exported files are encrypted — need the database password to restore
• Recommended: export after every keygen or key reshare, store offsite

Backup

./scripts/node-ctl.sh backup

Creates a timestamped backup at ~/.cobo-tss-node/backups/YYYYMMDD-HHMMSS/ containing:

• secrets.db — encrypted database (key shares, session data)
• cobo-tss-node-config.yaml — configuration
• .password — key file
• SHA256SUMS — integrity checksums

⚠️ Store backups securely — contains everything needed to restore the node.

Update Binary

./scripts/node-ctl.sh update                    # Update to latest
./scripts/node-ctl.sh update --version=v0.13.0  # Update to specific version

What it does:

1. Stops the service
2. Backs up current binary as cobo-tss-node.bak
3. Downloads and installs new version
4. Runs database migration (if needed)
5. Restarts the service
6. Shows new version

Database Migration

./scripts/node-ctl.sh migrate              # Run migration
./scripts/node-ctl.sh migrate --dry-run    # Preview only

Run after binary updates. The update command does this automatically.

Change Password

./scripts/node-ctl.sh change-password

Changes the database encryption password. Also updates the key file.

Uninstall Service

./scripts/node-ctl.sh uninstall

Removes the systemd/launchd service but keeps all data in ~/.cobo-tss-node/. To fully remove: rm -rf ~/.cobo-tss-node.

Recommended Maintenance Schedule

Configuration Reference

Config file: ~/.cobo-tss-node/configs/cobo-tss-node-config.yaml

Key sections:

• env: development / production
• db.path: database file path
• callback.cb_server: risk control callback URL + public key (v1)
• callback.cb_server_v2: risk control callback URL + public key (v2)
• event.server: event publish endpoints (keygen/keysign/reshare notifications)
• embedded_risk_control_rules: local allow/reject rules for keygen, keysign, reshare
• log: stdout + file logging config
• metrics: InfluxDB monitoring endpoint

Directory Layout

~/.cobo-tss-node/
├── cobo-tss-node                    # binary
├── cobo-tss-node.bak               # previous binary (after update)
├── .password                        # key file (chmod 600)
├── configs/
│   ├── cobo-tss-node-config.yaml           # active config
│   └── cobo-tss-node-config.yaml.template  # template reference
├── db/
│   └── secrets.db                   # AES-GCM encrypted database
├── logs/                            # log files
├── recovery/                        # exported key shares
│   └── YYYYMMDD-HHMMSS/
└── backups/                         # full backups
    └── YYYYMMDD-HHMMSS/
        ├── secrets.db
        ├── cobo-tss-node-config.yaml
        ├── .password
        └── SHA256SUMS

Key Design Decisions

• --key-file used on all commands for non-interactive operation (required for service mode)
• Database is AES-GCM encrypted; .password file must be mode 600
• Linux service runs with NoNewPrivileges, ProtectSystem=strict, ReadWritePaths limited to db/logs/recovery
• macOS agent uses KeepAlive + ThrottleInterval for auto-restart on failure
• Backups include SHA256 checksums for integrity verification

Troubleshooting