Support child key derivation (#113)

* Merge pull request #122 from fystack/update-readme

Update readme

* WIP: Add CKD implementation and integrate derivation path in signing sessions

use consulKV for store ckd seed

* Update .gitignore to exclude node modules and modify CKD example

* chore: fix lint error

* feat: support eddsa ckd

* CKD struct refactor: rename chain code field to masterChainCode and adjust constructor/accessor

* Enable wallet-scoped derivation: add walletID to Derive and wire through HMAC-SHA512

* Add chain_code setup instructions and integrate chain_code into configuration

* Enhance setup scripts: distribute event initiator public key to node configs and add build step in setup.sh

* Update dependencies: replace bnb-chain/tss-lib with fystack/tss-lib and add btcec v2.3.2

* Fix reshare event handling: ensure successEvent.PubKey is non-empty before send result

* Add chain_code config and integration CKD sign into e2e

* Update e2e test matrix to include TestCKDSigning

* Remove unused functions

* Update derivatoin logic

* Add hd wallet examples for both ecdsa and eddsa

* Fix lint issue

---------

Co-authored-by: vietddude <imrbdnv@gmail.com>

Author: anhthii

.github/workflows/e2e-tests.yml

@@ -54,7 +54,7 @@ jobs:
     needs: build
     strategy:
       matrix:
-        testcase: [TestKeyGeneration, TestSigning, TestResharing]
+        testcase: [TestKeyGeneration, TestSigning, TestResharing, TestCKDSigning]
     steps:
       - uses: actions/checkout@v4
 

.gitignore

@@ -6,6 +6,7 @@ event_initiator.key
 event_initiator.key.age
 coverage.out
 coverage.html
+node*/
 peers.json
 
 # E2E test artifacts
@@ -23,3 +24,4 @@ node2
 config.yaml
 .vscode
 .vagrant
+.chain_code

INSTALLATION.md

@@ -56,6 +56,29 @@ Detailed steps can be found in [SETUP.md](SETUP.md).
 
 ---
 
+## chain_code setup (required)
+
+Generate one 32-byte hex chain code and set it in all configs:
+
+```bash
+cd /home/carmy/Documents/works/mpcium
+CC=$(openssl rand -hex 32) && echo "$CC" > .chain_code
+sed -i -E "s|^([[:space:]]*chain_code:).*|\1 \"$CC\"|" config.yaml
+for n in node0 node1 node2; do
+  sed -i -E "s|^([[:space:]]*chain_code:).*|\1 \"$CC\"|" "$n/config.yaml"
+done
+```
+
+Start nodes normally (no env export needed):
+
+```bash
+cd node0 && mpcium start -n node0
+```
+
+Repeat for `node1` and `node2`. The value must be exactly 64 hex chars (32 bytes).
+
+---
+
 ## Production Deployment (High Security)
 
 1. Use production-grade **NATS** and **Consul** clusters.

README.md

@@ -133,6 +133,18 @@ The application uses a YAML configuration file (`config.yaml`) with the followin
 - `event_initiator_pubkey`: Public key of the event initiator
 - `max_concurrent_keygen`: Maximum concurrent key generation operations
 
+#### chain_code (required)
+- Mpcium derives child keys using a master chain code.
+- Provide a single 32-byte hex value in `config.yaml` under `chain_code`, and use the same value for all nodes.
+- Example to generate once and set:
+```bash
+CC=$(openssl rand -hex 32)
+sed -i -E "s|^([[:space:]]*chain_code:).*|\1 \"$CC\"|" config.yaml
+for n in node0 node1 node2; do
+  sed -i -E "s|^([[:space:]]*chain_code:).*|\1 \"$CC\"|" "$n/config.yaml"
+done
+```
+
 ## Installation
 
 - **Local Development**: For quick setup and testing, see [INSTALLATION.md](./INSTALLATION.md)

cmd/mpcium/main.go

@@ -203,6 +203,12 @@ func runNode(ctx context.Context, c *cli.Command) error {
 	peerNodeIDs := GetPeerIDs(peers)
 	peerRegistry := mpc.NewRegistry(nodeID, peerNodeIDs, consulClient.KV(), directMessaging, pubsub, identityStore)
 
+	chainCodeHex := viper.GetString("chain_code")
+	ckd, err := mpc.NewCKDFromHex(chainCodeHex)
+	if err != nil {
+		logger.Fatal("Failed to create ckd store", err)
+	}
+
 	mpcNode := mpc.NewNode(
 		nodeID,
 		peerNodeIDs,
@@ -212,6 +218,7 @@ func runNode(ctx context.Context, c *cli.Command) error {
 		keyinfoStore,
 		peerRegistry,
 		identityStore,
+		ckd,
 	)
 	defer mpcNode.Close()
 
@@ -443,6 +450,14 @@ func checkRequiredConfigValues(appConfig *config.AppConfig) {
 	if viper.GetString("event_initiator_pubkey") == "" {
 		logger.Fatal("Event initiator public key is required", nil)
 	}
+
+	chainCode := strings.TrimSpace(viper.GetString("chain_code"))
+	if chainCode == "" {
+		logger.Fatal("chain_code is required in config.yaml", nil)
+	}
+	if len(chainCode) != 64 { // 32 bytes hex
+		logger.Fatal("chain_code must be 32-byte hex (64 chars)", nil)
+	}
 }
 
 func NewConsulClient(addr string) *api.Client {

e2e/config.test.yaml.template

@@ -11,3 +11,4 @@ nats:
 max_concurrent_keygen: 1
 max_concurrent_signing: 10
 session_warm_up_delay_ms: 500
+chain_code: "{{.CKDChainCode}}"

e2e/go.mod

@@ -106,3 +106,5 @@ require (
 replace github.com/fystack/mpcium => ../
 
 replace github.com/agl/ed25519 => github.com/binance-chain/edwards25519 v0.0.0-20200305024217-f36fc4b53d43
+
+replace github.com/bnb-chain/tss-lib/v2 => github.com/fystack/tss-lib/v2 v2.0.1

e2e/go.sum

@@ -53,8 +53,6 @@ github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6r
 github.com/bgentry/speakeasy v0.1.0/go.mod h1:+zsyZBPWlz7T6j88CTgSN5bM796AkVf0kBD4zp0CCIs=
 github.com/binance-chain/edwards25519 v0.0.0-20200305024217-f36fc4b53d43 h1:Vkf7rtHx8uHx8gDfkQaCdVfc+gfrF9v6sR6xJy7RXNg=
 github.com/binance-chain/edwards25519 v0.0.0-20200305024217-f36fc4b53d43/go.mod h1:TnVqVdGEK8b6erOMkcyYGWzCQMw7HEMCOw3BgFYCFWs=
-github.com/bnb-chain/tss-lib/v2 v2.0.2 h1:dL2GJFCSYsYQ0bHkGll+hNM2JWsC1rxDmJJJQEmUy9g=
-github.com/bnb-chain/tss-lib/v2 v2.0.2/go.mod h1:s4LRfEqj89DhfNb+oraW0dURt5LtOHWXb9Gtkghn0L8=
 github.com/btcsuite/btcd v0.20.1-beta/go.mod h1:wVuoA8VJLEcwgqHBwHmzLRazpKxTv13Px/pDuV7OomQ=
 github.com/btcsuite/btcd v0.22.0-beta.0.20220111032746-97732e52810c/go.mod h1:tjmYdS6MLJ5/s0Fj4DbLgSbDHbEqLJrtnHecBFkdz5M=
 github.com/btcsuite/btcd v0.23.4/go.mod h1:0QJIIN1wwIXF/3G/m87gIwGniDMDQqjVn4SZgnFpsYY=
@@ -118,6 +116,8 @@ github.com/fsnotify/fsnotify v1.4.7/go.mod h1:jwhsz4b93w/PPRr/qN1Yymfu8t87LnFCMo
 github.com/fsnotify/fsnotify v1.4.9/go.mod h1:znqG4EE+3YCdAaPaxE2ZRY/06pZUdp0tY4IgpuI1SZQ=
 github.com/fsnotify/fsnotify v1.7.0 h1:8JEhPFa5W2WU7YfeZzPNqzMP6Lwt7L2715Ggo0nosvA=
 github.com/fsnotify/fsnotify v1.7.0/go.mod h1:40Bi/Hjc2AVfZrqy+aj+yEI+/bRxZnMJyTJwOpGvigM=
+github.com/fystack/tss-lib/v2 v2.0.1 h1:xnC2+DYShoVWco1geliW0km9IvGD7T2FqFOeXM3/7K0=
+github.com/fystack/tss-lib/v2 v2.0.1/go.mod h1:s4LRfEqj89DhfNb+oraW0dURt5LtOHWXb9Gtkghn0L8=
 github.com/go-kit/kit v0.8.0/go.mod h1:xBxKIO96dXMWWy0MnWVtmwkA9/13aqxPnvrjFYMA2as=
 github.com/go-kit/kit v0.9.0/go.mod h1:xBxKIO96dXMWWy0MnWVtmwkA9/13aqxPnvrjFYMA2as=
 github.com/go-logfmt/logfmt v0.3.0/go.mod h1:Qt1PoO58o5twSAckw1HlFXLmHsOX5/0LbT9GBnD5lWE=

e2e/setup_test_identities.sh

@@ -28,6 +28,11 @@ echo "🔐 Generating random password for badger encryption..."
 BADGER_PASSWORD=$(< /dev/urandom tr -dc 'A-Za-z0-9' | head -c 32)
 echo "✅ Generated password: $BADGER_PASSWORD"
 
+# Generate chain_code (32-byte hex value, 64 hex characters)
+echo "🔐 Generating chain_code (32-byte hex)..."
+CHAIN_CODE=$(openssl rand -hex 32)
+echo "✅ Generated chain_code: $CHAIN_CODE"
+
 # Generate config.test.yaml from template
 echo "📝 Generating config.test.yaml from template..."
 if [ ! -f "config.test.yaml.template" ]; then
@@ -43,6 +48,7 @@ ESCAPED_PASSWORD=$(printf '%s\n' "$BADGER_PASSWORD" | sed 's/[[\.*^$()+?{|]/\\&/
 
 sed -e "s/{{\.BadgerPassword}}/$ESCAPED_PASSWORD/g" \
     -e "s/{{\.EventInitiatorPubkey}}/$TEMP_PUBKEY/g" \
+    -e "s/{{\.CKDChainCode}}/$CHAIN_CODE/g" \
     config.test.yaml.template > config.test.yaml
 
 echo "✅ Generated config.test.yaml from template"
@@ -106,20 +112,35 @@ if [ -f "test_event_initiator.identity.json" ]; then
     PUBKEY=$(cat test_event_initiator.identity.json | jq -r '.public_key')
     echo "📝 Updating config files with event initiator public key and password..."
 
-    # Update all test node config files with the actual public key and password
+    # Update all test node config files with the actual public key, password, and chain_code
     for i in $(seq 0 $((NUM_NODES-1))); do
         # Update public key using sed with | as delimiter (safer than /)
         sed_inplace "s|event_initiator_pubkey:.*|event_initiator_pubkey: $PUBKEY|g" "$BASE_DIR/test_node$i/config.yaml"
         # Update password using sed with | as delimiter and escaped password
         sed_inplace "s|badger_password:.*|badger_password: $ESCAPED_PASSWORD|g" "$BASE_DIR/test_node$i/config.yaml"
+        # Update chain_code
+        if grep -q '^\s*chain_code:' "$BASE_DIR/test_node$i/config.yaml"; then
+            sed_inplace "s|chain_code:.*|chain_code: \"$CHAIN_CODE\"|g" "$BASE_DIR/test_node$i/config.yaml"
+        else
+            printf '\nchain_code: "%s"\n' "$CHAIN_CODE" >> "$BASE_DIR/test_node$i/config.yaml"
+        fi
     done
 
     # Also update the main config.test.yaml
     sed_inplace "s|event_initiator_pubkey:.*|event_initiator_pubkey: $PUBKEY|g" "$BASE_DIR/config.test.yaml"
     sed_inplace "s|badger_password:.*|badger_password: $ESCAPED_PASSWORD|g" "$BASE_DIR/config.test.yaml"
+    # Update chain_code in config.test.yaml if it was replaced with placeholder
+    if grep -q '{{\.CKDChainCode}}' "$BASE_DIR/config.test.yaml" 2>/dev/null; then
+        sed_inplace "s|{{\.CKDChainCode}}|$CHAIN_CODE|g" "$BASE_DIR/config.test.yaml"
+    elif grep -q '^\s*chain_code:' "$BASE_DIR/config.test.yaml"; then
+        sed_inplace "s|chain_code:.*|chain_code: \"$CHAIN_CODE\"|g" "$BASE_DIR/config.test.yaml"
+    else
+        printf '\nchain_code: "%s"\n' "$CHAIN_CODE" >> "$BASE_DIR/config.test.yaml"
+    fi
 
     echo "✅ Event initiator public key updated: $PUBKEY"
     echo "✅ Badger password updated: $BADGER_PASSWORD"
+    echo "✅ Chain code updated: $CHAIN_CODE"
 else
     echo "❌ Failed to generate event initiator identity"
     exit 1