Extract standalone arkd-signer + shared txsigner lib (BREAKING: ARKD_SIGNER_ADDR required)

Makefile

@@ -1,5 +1,5 @@
 .PHONY: \
-	build build-all build-cli build-wallet clean cov \
+	build build-all build-cli build-signer build-wallet clean cov \
 	docker-run docker-run-light docker-stop droppg droppgtest \
 	help integrationtest lint migrate pg pgmigrate pgsqlc pgtest \
 	pprof proto proto-lint psql \
@@ -42,6 +42,11 @@ build-wallet:
 	@echo "Building arkd wallet binary..."
 	@bash ./scripts/build-arkd-wallet
 
+## build-signer: build arkd signer for your platforms
+build-signer:
+	@echo "Building arkd signer binary..."
+	@bash ./scripts/build-arkd-signer
+
 ## clean: run go clean
 clean:
 	@echo "Cleaning..."
@@ -173,12 +178,11 @@ run-light: clean
 	$(call setup_env, envs/arkd.light.env)
 	@go run ./cmd/arkd
 
-## run-signer: run arkd wallet as signer without a wallet
+## run-signer: run arkd-signer in dev mode
 run-signer:
-	@echo "Running signer in dev mode"
-	@docker compose -f docker-compose.regtest.yml up -d pg nbxplorer
+	@echo "Running arkd-signer in dev mode"
 	$(call setup_env, envs/signer.dev.env)
-	@go run ./cmd/arkd-wallet
+	@go run ./cmd/arkd-signer
 
 ## run-simulation: run the multi-VTXO batch settlement test
 ## Usage: make run-simulation [CLIENTS=n]

README.md

@@ -33,7 +33,7 @@ The Operator's role is designed with strict boundaries that ensure users always
 * mutinynet
 * mainnet
 
-and makes use of [arkd-wallet](./pkg/arkd-wallet/), an on-chain wallet based on NBXplorer, as liquidity provider and optionally also as signer.
+and makes use of [arkd-wallet](./pkg/arkd-wallet/), an on-chain wallet based on NBXplorer, as liquidity provider, and [arkd-signer](./pkg/arkd-signer/) as the transaction signer.
 
 ## Usage Documentation
 
@@ -81,7 +81,7 @@ The `arkd` server can be configured using environment variables and the admin se
 | `ARKD_REDIS_NUM_OF_RETRIES`         | Maximum number of retries for Redis write operations in case of conflicts       | -                              |
 | `ARKD_ESPLORA_URL`                  | Esplora API URL                                                                 | `https://blockstream.info/api` |
 | `ARKD_WALLET_ADDR`                  | The arkd wallet address to connect to in the form `host:port`                   | -                              |
-| `ARKD_SIGNER_ADDR`                  | The signer address to connect to in the form `host:port`                        | value of `ARKD_WALLET_ADDR`    |
+| `ARKD_SIGNER_ADDR`                  | The signer address to connect to in the form `host:port` (required)             | -                              |
 | `ARKD_NO_MACAROONS`                 | Disable macaroon authentication                                                 | `false`                        |
 | `ARKD_NO_TLS`                       | Disable TLS                                                                     | `true`                         |
 | `ARKD_UNLOCKER_TYPE`                | Wallet unlocker type (env, file) to enable auto-unlock                          | -                              |
@@ -162,13 +162,17 @@ export ARKD_WALLET_NBXPLORER_URL=http://localhost:32838
 
 ### Configure signer
 
-`arkd-wallet` can be used also as signer.
-
-The configuration can be done either via env vars or via API. To enable `arkd-wallet`'s signer mode use this environment variable:
+`arkd-signer` is a standalone service that holds the operator signing key and signs `arkd`'s protocol transactions. Configure its key via environment variable:
 
 ```sh
 # Make sure to use a random private key, this is just an example.
-export ARKD_WALLET_SIGNER_KEY=19422b10efd05403820ff6a3365422be2fc5f07f34a6d1603f7298328f0f80f6
+export ARKD_SIGNER_SECRET_KEY=19422b10efd05403820ff6a3365422be2fc5f07f34a6d1603f7298328f0f80f6
+```
+
+To rotate the signer key while still accepting coins locked to the old key, list deprecated keys as a comma-separated list of `hexkey[:cutoff_unix_timestamp]`:
+
+```sh
+export ARKD_SIGNER_DEPRECATED_KEYS=<old_hex_key>:<unix_cutoff>
 ```
 
 ### Connect to wallet
@@ -182,15 +186,11 @@ export ARKD_WALLET_ADDR=localhost:6060
 
 ### Connect to signer
 
-By default, `arkd` makes use of the provided `arkd-wallet` also as signer, but you can customize its url either via environment variable or via API.
-
-#### Connect to custom signer
-
-To connect `arkd` to a custom signer use this environment variable:
+`arkd` connects to `arkd-signer` via this environment variable (required):
 
 ```sh
 # Make sure to use the right URL in the form host:port, this is just an example.
-export ARKD_SIGNER_ADDR=localhost:7071
+export ARKD_SIGNER_ADDR=localhost:6061
 ```
 
 ### Setup arkd
@@ -200,12 +200,17 @@ export ARKD_SIGNER_ADDR=localhost:7071
    arkd-wallet
    ```
 
-2. Start arkd:
+2. Start the signer:
+   ```sh
+   arkd-signer
+   ```
+
+3. Start arkd (requires `ARKD_WALLET_ADDR` and `ARKD_SIGNER_ADDR`):
    ```sh
    arkd
    ```
 
-3. Create a new wallet:
+4. Create a new wallet:
    ```sh
    arkd wallet create --password <password>
    ```
@@ -214,14 +219,11 @@ export ARKD_SIGNER_ADDR=localhost:7071
    ```sh
    arkd wallet create --mnemonic "your twelve word mnemonic phrase here" --password <password>
    ```
-4. Only if you didn't configure either the wallet as signer, or a custom signer, you must load the signer before unlocking the wallet, or `arkd` will fail to start:
+
+   You can repoint `arkd` at a different signer URL at runtime if needed:
    ```sh
-   # If you configured a custom signer
-   arkd signer load --signer-url localhost:7071
-   # Or, if you want to configure the wallet as signer with a private key
-   arkd signer load --signer-prvkey 19422b10efd05403820ff6a3365422be2fc5f07f34a6d1603f7298328f0f80f6
+   arkd signer load --signer-url localhost:6061
    ```
-   Remember, if you use this command, you must use it at every restart unless you export the required environment variable(s).
 
 5. Unlock the wallet:
    ```sh
@@ -255,7 +257,8 @@ For a complete list of available commands and options:
 - [`api-spec`](./api-spec/): Ark Protocol Buffer API specification.
 - [`pkg`](./pkg/): collection of reusable packages and services.
   - [`ark-lib`](./pkg/ark-lib): collection of data structures and functions reusable by arkd and sdk.
-  - [`arkd-wallet`](./pkg/arkd-wallet): bitcoin wallet service used as liquidity provider and signer.
+  - [`arkd-wallet`](./pkg/arkd-wallet): bitcoin wallet service used as liquidity provider.
+  - [`arkd-signer`](./pkg/arkd-signer): standalone service that holds the operator key and signs arkd's protocol transactions.
   - [`ark-cli`](./pkg/ark-cli): ark offchain and onchain wallet as command line interface.
 - [`internal`](./internal): arkd implementation.
   - [`core`](./internal/core): contains the core business logic of arkd.
@@ -307,14 +310,10 @@ To compile the `arkd` binary from source, you can use the following Make command
    go mod download
    ```
 
-6. Run arkd wallet in dev mode:
+6. Run arkd wallet and signer in dev mode (each in its own tab):
 
    ```sh
-   # run wallet with signer enabled
    make run-wallet
-   # or, run wallet with signer disabled...
-   make run-wallet-nosigner
-   # ... and in another tab run a custom signer
    make run-signer
    ```
 

arkdsigner.Dockerfile

@@ -0,0 +1,25 @@
+# First stage: build the arkd-signer binary
+FROM golang:1.26.4 AS builder
+
+ARG VERSION
+ARG TARGETOS
+ARG TARGETARCH
+
+WORKDIR /app
+
+COPY . .
+
+RUN CGO_ENABLED=0 GOOS=${TARGETOS} GOARCH=${TARGETARCH} go build -ldflags="-X 'main.Version=${VERSION}'" -o /app/bin/arkd-signer ./cmd/arkd-signer/main.go
+
+# Second stage: minimal runtime image
+FROM alpine:3.20
+
+RUN apk update && apk upgrade
+
+WORKDIR /app
+
+COPY --from=builder /app/bin/arkd-signer /app/
+
+ENV PATH="/app:${PATH}"
+
+ENTRYPOINT [ "arkd-signer" ]

cmd/arkd-signer/main.go

@@ -0,0 +1,44 @@
+package main
+
+import (
+	"os"
+	"os/signal"
+	"syscall"
+
+	"github.com/arkade-os/arkd/pkg/arkd-signer/config"
+	grpcservice "github.com/arkade-os/arkd/pkg/arkd-signer/interface/grpc"
+	log "github.com/sirupsen/logrus"
+)
+
+func main() {
+	cfg, err := config.LoadConfig()
+	if err != nil {
+		log.Fatalf("invalid config: %s", err)
+	}
+
+	log.SetLevel(log.Level(cfg.LogLevel))
+
+	svc, err := grpcservice.NewService(cfg)
+	if err != nil {
+		log.Fatalf("failed to create service: %s", err)
+	}
+
+	log.Infof("arkd signer config: %s", cfg)
+
+	log.Info("starting service...")
+	if err := svc.Start(); err != nil {
+		log.Fatalf("failed to start service: %s", err)
+	}
+	log.Infof("arkd signer listens on: %v", cfg.Port)
+
+	log.RegisterExitHandler(svc.Stop)
+
+	sigChan := make(chan os.Signal, 1)
+	signal.Notify(
+		sigChan, syscall.SIGTERM, syscall.SIGINT, syscall.SIGQUIT, syscall.SIGHUP, os.Interrupt,
+	)
+	<-sigChan
+
+	log.Info("shutting down service...")
+	log.Exit(0)
+}

cmd/arkd/commands.go

@@ -87,9 +87,9 @@ var (
 	}
 	signerLoadCmd = &cli.Command{
 		Name:   "load",
-		Usage:  "Load the ark signer address or private key",
+		Usage:  "Load the ark signer url",
 		Action: signerLoadAction,
-		Flags:  []cli.Flag{signerKeyFlag, signerUrlFlag},
+		Flags:  []cli.Flag{signerUrlFlag},
 	}
 	noteCmd = &cli.Command{
 		Name:   "note",
@@ -447,13 +447,9 @@ func walletWithdrawAction(ctx *cli.Context) error {
 
 func signerLoadAction(ctx *cli.Context) error {
 	baseURL := ctx.String(urlFlagName)
-	signerKey := ctx.String(signerKeyFlagName)
 	signerUrl := ctx.String(signerUrlFlagName)
-	if signerKey == "" && signerUrl == "" {
-		return fmt.Errorf("either private key or url must be provided")
-	}
-	if signerKey != "" && signerUrl != "" {
-		return fmt.Errorf("private key and url are mutually exclusive, only one must be provided")
+	if signerUrl == "" {
+		return fmt.Errorf("signer url must be provided")
 	}
 	macaroon, tlsConfig, err := getCredentials(ctx)
 	if err != nil {
@@ -462,9 +458,6 @@ func signerLoadAction(ctx *cli.Context) error {
 
 	url := fmt.Sprintf("%s/v1/admin/signer", baseURL)
 	body := fmt.Sprintf(`{"signerUrl": "%s"}`, signerUrl)
-	if signerKey != "" {
-		body = fmt.Sprintf(`{"signerPrivateKey": "%s"}`, signerKey)
-	}
 
 	if _, err := post[struct{}](url, body, "", macaroon, tlsConfig); err != nil {
 		return err

cmd/arkd/flags.go

@@ -30,7 +30,6 @@ const (
 	scheduledSessionPeriodFlagName    = "period"
 	roundMinParticipantsFlagName      = "round-min-participants"
 	roundMaxParticipantsFlagName      = "round-max-participants"
-	signerKeyFlagName                 = "signer-prvkey"
 	signerUrlFlagName                 = "signer-url"
 	tokenFlagName                     = "token"
 	convictionIdsFlagName             = "ids"
@@ -183,10 +182,6 @@ var (
 		Name:  roundMaxParticipantsFlagName,
 		Usage: "the max number of participants per round",
 	}
-	signerKeyFlag = &cli.StringFlag{
-		Name:  signerKeyFlagName,
-		Usage: "the private key to be loaded to arkd wallet and used as signer",
-	}
 	signerUrlFlag = &cli.StringFlag{
 		Name:  signerUrlFlagName,
 		Usage: "the url of the signer to connect to",

docker-compose.regtest.yml

@@ -57,10 +57,21 @@ services:
       - ARKD_WALLET_NBXPLORER_URL=http://nbxplorer:32838
       - ARKD_WALLET_DATADIR=./data/regtest
       - ARKD_WALLET_NETWORK=regtest
-      - ARKD_WALLET_SIGNER_KEY=${ARKD_WALLET_SIGNER_KEY:-afcd3fa10f82a05fddc9574fdb13b3991b568e89cc39a72ba4401df8abef35f0}
-      - ARKD_WALLET_DEPRECATED_SIGNER_KEYS=${ARKD_WALLET_DEPRECATED_SIGNER_KEYS:-}
     volumes:
       - arkd-wallet-volume:/app/data
+  arkd-signer:
+    restart: unless-stopped
+    build:
+      context: .
+      dockerfile: arkdsigner.Dockerfile
+    container_name: arkd-signer
+    ports:
+      - "6061:6061"
+    environment:
+      - ARKD_SIGNER_LOG_LEVEL=5
+      - ARKD_SIGNER_PORT=6061
+      - ARKD_SIGNER_SECRET_KEY=${ARKD_SIGNER_SECRET_KEY:-afcd3fa10f82a05fddc9574fdb13b3991b568e89cc39a72ba4401df8abef35f0}
+      - ARKD_SIGNER_DEPRECATED_KEYS=${ARKD_SIGNER_DEPRECATED_KEYS:-}
   redis:
     restart: unless-stopped
     image: redis:7-alpine
@@ -80,6 +91,7 @@ services:
     restart: unless-stopped
     depends_on:
       - arkd-wallet
+      - arkd-signer
       - pg
       - redis
     ports:
@@ -104,6 +116,7 @@ services:
       - ARKD_BAN_THRESHOLD=1
       - ARKD_DATADIR=./data/regtest
       - ARKD_WALLET_ADDR=arkd-wallet:6060
+      - ARKD_SIGNER_ADDR=arkd-signer:6061
       - ARKD_ESPLORA_URL=http://chopsticks:3000
       - ARKD_DB_TYPE=${ARKD_DB_TYPE:-sqlite}
       - ARKD_PG_DB_URL=${ARKD_PG_DB_URL:-}

envs/signer.dev.env

@@ -1,6 +1,3 @@
-ARKD_WALLET_LOG_LEVEL=5
-ARKD_WALLET_NBXPLORER_URL=http://localhost:32838
-ARKD_WALLET_DATADIR=./data/signer
-ARKD_WALLET_NETWORK=regtest
-ARKD_WALLET_SIGNER_KEY=19422b10efd05403820ff6a3365422be2fc5f07f34a6d1603f7298328f0f80f6
-ARKD_WALLET_PORT=6161
+ARKD_SIGNER_LOG_LEVEL=5
+ARKD_SIGNER_SECRET_KEY=19422b10efd05403820ff6a3365422be2fc5f07f34a6d1603f7298328f0f80f6
+ARKD_SIGNER_PORT=6061

go.mod

@@ -10,6 +10,8 @@ replace github.com/arkade-os/arkd/pkg/ark-lib => ./pkg/ark-lib
 
 replace github.com/arkade-os/arkd/pkg/arkd-wallet => ./pkg/arkd-wallet
 
+replace github.com/arkade-os/arkd/pkg/arkd-signer => ./pkg/arkd-signer
+
 replace github.com/arkade-os/arkd/pkg/macaroons => ./pkg/macaroons
 
 replace github.com/arkade-os/arkd/pkg/kvdb => ./pkg/kvdb
@@ -22,6 +24,7 @@ require (
 	github.com/ThreeDotsLabs/watermill-sql/v3 v3.1.0
 	github.com/arkade-os/arkd/api-spec v0.0.0-00010101000000-000000000000
 	github.com/arkade-os/arkd/pkg/ark-lib v0.8.1-0.20260210151408-67ee91bbd639
+	github.com/arkade-os/arkd/pkg/arkd-signer v0.0.0-00010101000000-000000000000
 	github.com/arkade-os/arkd/pkg/arkd-wallet v0.0.0-00010101000000-000000000000
 	github.com/arkade-os/arkd/pkg/client-lib v0.0.0-00010101000000-000000000000
 	github.com/arkade-os/arkd/pkg/errors v0.0.0-00010101000000-000000000000

internal/config/config.go

@@ -386,7 +386,7 @@ func LoadConfig() (*Config, error) {
 
 	signerAddr := viper.GetString(SignerAddr)
 	if signerAddr == "" {
-		signerAddr = viper.GetString(WalletAddr)
+		return nil, fmt.Errorf("ARKD_SIGNER_ADDR is required")
 	}
 
 	// In case the admin port is unset, fallback to service port.

internal/core/application/fraud.go

@@ -164,11 +164,19 @@ func (s *service) broadcastForfeitTx(ctx context.Context, vtxo domain.Vtxo) erro
 		return fmt.Errorf("failed to encode forfeit tx: %s", err)
 	}
 
+	// Sign the vtxo input (tapscript) with the operator signer.
 	signedForfeitTx, err := s.signer.SignTransactionTapscript(ctx, forfeitTxB64, nil)
 	if err != nil {
 		return fmt.Errorf("failed to sign forfeit tx: %s", err)
 	}
 
+	// Sign the connector input (a wallet-owned key-path output) with the wallet:
+	// the operator signer holds no wallet keys, so it cannot sign it.
+	signedForfeitTx, err = s.wallet.SignTransaction(ctx, signedForfeitTx, false)
+	if err != nil {
+		return fmt.Errorf("failed to sign forfeit connector input: %s", err)
+	}
+
 	forfeitTxHex, err := s.builder.FinalizeAndExtract(signedForfeitTx)
 	if err != nil {
 		return fmt.Errorf("failed to finalize forfeit tx: %s", err)

internal/core/ports/wallet.go

@@ -49,7 +49,6 @@ type WalletService interface {
 	GetOutpointStatus(ctx context.Context, outpoint domain.Outpoint) (spent bool, err error)
 	GetCurrentBlockTime(ctx context.Context) (*BlockTimestamp, error)
 	Withdraw(ctx context.Context, address string, amount uint64, all bool) (string, error)
-	LoadSignerKey(ctx context.Context, prvkey string) error
 	Close()
 }