federated-signer-node

federated-signer-node is the listener / federated-signer-node service used by the current bridge-utexo federated signing stack.

The code still uses some old naming such as listener, tricorn, and FederatedSignerNode in proto packages. Treat that as protocol compatibility and legacy naming, not as a different product model.

Current role in the stack

One running instance of this repository represents one federation participant.

It sits between:

• the federated-signer orchestrator in bridge-utexo
• the local Parent Adapter
• the local Nitro Enclave
• optionally an EVM node
• optionally the rgb-multisig-bridge hub

Bridge
  |
  v
Federated-signer orchestrator
  |
  v
Federated-signer-node / listener
  |                  \
  |                   \
  v                    v
Parent Adapter      EVM node
  |
  v
Nitro Enclave

Optional on the same node:
  federated-signer-node <-> rgb-multisig-bridge

What the service actually does

This repository now contains three runtime capabilities that can be enabled independently by config.

1. EVM event indexing

Code:

• listener/evm_listener.go
• listener/finality_tracker.go

Role:

• polls the configured EVM bridge contract
• persists detected FundsIn events into SQLite
• tracks the last scanned block
• marks rows finalized using the chain finalized block

This is used by the signing path that must prove an EVM FundsIn really happened and is finalized before the enclave signs the outbound PSBT flow.

2. Orchestrator-facing gRPC node

Code:

• cmd/listener/main.go
• internal/federatedsignergrpc/service.go
• internal/federatedsignergrpc/grpc.go
• internal/listenerenclaveclient

Role:

• exposes FederatedSignerNode.Sign
• exposes FederatedSignerNode.PublicKey
• exposes ListenerHealth.Health on the same port
• validates and enriches orchestrator bootstrap payloads
• forwards the enriched request to the enclave through the Parent Adapter

This is the main runtime mode for the current bridge stack.

3. RGB multisig hub cosigner

Code:

• listener/rgbbridge/listener.go
• listener/microservice/attach_rgb.go

Role:

• connects to rgb-multisig-bridge
• syncs multisig operations from the hub
• responds as this cosigner
• stores RGB bridge audit state in SQLite
• can sign hub PSBTs either through rgb-lib-go or via the enclave

This path is compiled only with -tags rgb. The Docker build uses that tag by default.

Signing flows

The listener does not sign arbitrary opaque bytes. It validates bridge-specific context first, then sends an enriched payload to the enclave.

TRANSACTION flow: EVM -> RGB / PSBT signing

Input bootstrap:

• SignPsbtBootstrap

Flow:

1. The orchestrator calls FederatedSignerNode.Sign with data_type=TRANSACTION.
2. The listener reads tx_hash and operation_idx from the bootstrap payload.
3. The listener checks that the EVM event exists in evm_events and is finalized.
4. The listener rejects tx_hash values already present in processed_events.
5. The listener fetches the PSBT from rgb-multisig-bridge.
6. The listener builds EnrichedPsbtPayload.
7. The listener calls EnclaveService.Sign through the Parent Adapter.
8. On success, the listener records the EVM tx hash in processed_events.

SWAP flow: RGB -> EVM / calldata signing

Input bootstrap:

• SignEvmBootstrap

Flow:

1. The orchestrator calls FederatedSignerNode.Sign with data_type=SWAP.
2. The listener validates the consignment.
3. The listener parses fundsOut calldata and checks token, recipient, amount, and commission.
4. If ORCHESTRATOR_RGB_EVM_TRANSFER_DB_CHECK=true, the listener requires a matching rgb_bridge_events row by consignment hash and cross-checks the amount.
5. The listener injects chain ID, proxy contract, consignment hash, and validated amounts into EnrichedEvmPayload.
6. The listener calls EnclaveService.Sign.
7. The enclave returns the EVM signature.

PublicKey flow

FederatedSignerNode.PublicKey is just proxied to the enclave through the Parent Adapter.

Health flow

ListenerHealth.Health reports:

• geth syncing state
• current and highest block
• last finalized block
• whether the enclave is reachable

Persistence

The service uses SQLite, not PostgreSQL.

Code:

• listener/database
• listener/database/migrations

Main tables:

• evm_events: detected EVM bridge events
• listener_blocks: last scanned EVM block
• processed_events: EVM tx hashes already consumed by successful sign flow
• rgb_bridge_events: RGB hub operation audit trail and transfer linkage

Proto map

Proto file	Purpose
proto/signer/signer.proto	shared signing messages
proto/orchestrator-listener.proto	orchestrator -> listener RPC
proto/orchestrator-listener-health.proto	operational health RPC
proto/listener-enclave.proto	listener -> parent adapter -> enclave RPC
proto/enriched/enriched-payload.proto	bootstrap and enriched payload messages
proto/bridge-orchestrator.proto	bridge -> orchestrator RPC contract reference

Regenerate Go code after proto edits:

bash scripts/gen-proto.sh

Configuration

Current example files:

• configs/env_examples/.example.listener.env
• configs/env_examples/.example.listener.database.env

Important current envs:

• NODE_ADDRESS: EVM RPC endpoint
• CHAIN_ID: EVM chain ID used in enriched EVM signing payload
• BRIDGE_CONTRACT_ADDRESS: EVM bridge contract watched by the listener
• PROXY_CONTRACT_ADDRESS: proxy contract used in RGB -> EVM signing checks
• PARENT_ADAPTER_GRPC: TCP address of the Parent Adapter
• GRPC_LISTEN_ADDR: listener gRPC address exposed to the orchestrator
• EVM_LISTENER_ENABLED: enables EVM indexing/finality tracking
• ORCHESTRATOR_GRPC_ENABLED: enables the gRPC listener node API
• ORCHESTRATOR_RGB_EVM_TRANSFER_DB_CHECK: requires RGB hub DB correlation for SWAP signing
• RGB_MULTISIG_BRIDGE_ENABLED: enables RGB hub cosigner mode

Important note:

• the committed examples are single-node examples
• the multi-node compose setup expects per-node files such as .listener-node-1.env, .listener-node-2.env, .listener-node-3.env
• those per-node files are environment-specific derivatives of the example listener config

Running

Local manual run

Without RGB-specific runtime:

go run cmd/listener/main.go run -f

With RGB hub support:

go run -tags rgb cmd/listener/main.go run -f

Docker

Primary Dockerfile:

• deploy/listener.Dockerfile

Current multi-node stack reference:

• deploy/docker-compose.yml

That compose file models:

• 3 enclaves
• 3 parent adapters
• 3 listener nodes
• shared operational logging via Dozzle

Practical note:

• deploy/local/docker-compose.yml is an older single-listener setup and may need adjustments before use with the current runtime

Documentation stance

When updating docs for this repository, assume:

• this repo is the federated-signer-node / listener only
• the orchestrator lives in bridge-utexo
• the enclave and parent adapter are downstream dependencies, not implemented here
• the important current paths are:
  • orchestrator-facing gRPC signing
  • EVM event validation/finality
  • RGB multisig bridge synchronization