shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 效率与办公无需 API Key

Cobo TSS Node

管理 Cobo TSS 节点以进行 MPC 门限签名。适用于：设置新 TSS 节点、启动/停止节点服务、检查节点状态或健康状况等场景。

person作者: dinsteinhubclawhub
open_in_new仓库download下载资源包

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

| Script | Purpose | |--------|---------| | scripts/install.sh | Download binary from GitHub releases | | scripts/setup-keyfile.sh | Create .password key file (mode 600) | | scripts/init-node.sh | Initialize node keys and database | | scripts/node-info.sh | View Node ID and group info | | scripts/start-node.sh | Start node in foreground | | scripts/install-service.sh | Install as systemd (Linux) or launchd (macOS) service | | scripts/node-ctl.sh | Unified daily operations CLI |

Daily Operations

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

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

Service Management

| Command | Description | |---------|-------------| | status | Show service status (systemctl/launchctl) | | start | Start the TSS Node service | | stop | Stop the service | | restart | Restart the service | | logs | View recent logs (last 50 lines) | | logs -f | Tail logs in real time | | logs --lines=200 | View more log lines |

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

| Task | Frequency | Command | |------|-----------|---------| | Health check | Daily | node-ctl.sh health | | Key share checkup | Weekly | node-ctl.sh sign <group-id> | | Backup | Weekly | node-ctl.sh backup | | Log review | Weekly | node-ctl.sh logs --lines=500 | | Export shares | After keygen/reshare | node-ctl.sh export <group-ids> | | Update binary | On new release | node-ctl.sh update | | Password rotation | Quarterly | node-ctl.sh change-password |

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

| Symptom | Cause | Fix | |---------|-------|-----| | Service won't start | Missing config file | cp configs/*.template configs/cobo-tss-node-config.yaml | | "password" prompt on start | Missing --key-file | Reinstall service: install-service.sh linux | | Permission denied on .password | Wrong file mode | chmod 600 ~/.cobo-tss-node/.password | | Init fails | DB already exists | Check with node-info.sh; delete db/secrets.db only if intentional | | WebSocket connection failed | Wrong environment flag | Match --dev/--sandbox/--prod to your Cobo Portal environment | | Service exits immediately | Port or resource conflict | Check node-ctl.sh logs for error details | | Migration fails | Version incompatibility | Try migrate --dry-run first; contact Cobo support if persistent |