Go-Ethereum Node Architecture: Initialization & Service Registration

cmd/geth/main.go
     │
     ▼
makeFullNode(ctx)
     │
     ├── node.New(cfg) → creates *node.Node
     ├── utils.RegisterEthService(stack, &cfg.Eth)
     │         └── eth.New(stack, cfg)
     │               └── stack.RegisterLifecycle(eth)
     ▼
startNode(ctx, stack)
     │
     └── stack.Start()
             ├── n.openEndpoints()
             └── invoke lifecycle.Start() for all lifecycles

// New creates a new P2P node, ready for protocol registration.
func New(conf *Config) (*Node, error) {
	// ...
	node := &Node{
		config:        conf,
		inprocHandler: rpc.NewServer(),
		eventmux:      new(event.TypeMux),
		log:           conf.Logger,
		stop:          make(chan struct{}),
		server:        &p2p.Server{Config: conf.P2P},
		databases:     make(map[*closeTrackingDB]struct{}),
	}
	// ...
	return node, nil
}

// RegisterLifecycle registers the given Lifecycle on the node.
func (n *Node) RegisterLifecycle(lifecycle Lifecycle) {
	n.lock.Lock()
	defer n.lock.Unlock()

	if n.state != initializingState {
		panic("can't register lifecycle on running/stopped node")
	}
	if slices.Contains(n.lifecycles, lifecycle) {
		panic(fmt.Sprintf("attempt to register lifecycle %T more than once", lifecycle))
	}
	n.lifecycles = append(n.lifecycles, lifecycle)
}

// Start starts all registered lifecycles, RPC services and p2p networking.
func (n *Node) Start() error {
	// ...
	// Start all registered lifecycles.
	var started []Lifecycle
	for _, lifecycle := range lifecycles {
		if err = lifecycle.Start(); err != nil {
			break
		}
		started = append(started, lifecycle)
	}
	// ...
	return err
}

// Lifecycle encompasses the behavior of services that can be started and stopped
// on the node.
type Lifecycle interface {
	Start() error
	Stop() error
}

// Protocols returns all the currently configured network protocols to start.
func (s *Ethereum) Protocols() []p2p.Protocol { ... }

// APIs return the collection of RPC services the ethereum package offers.
func (s *Ethereum) APIs() []rpc.API { ... }

// New creates a new Ethereum object...
func New(stack *node.Node, config *ethconfig.Config) (*Ethereum, error) {
    // ...
    eth := &Ethereum{
		//...
    }
    // ...
	// Register the backend on the node
	stack.RegisterAPIs(eth.APIs())
	stack.RegisterProtocols(eth.Protocols())
	stack.RegisterLifecycle(eth)

    return eth, nil
}

┌────────────────────────────┐
│         cmd/geth           │
│  - CLI parsing             │
│  - makeFullNode()          │
│  - startNode()             │
└────────────┬───────────────┘
             │
             ▼
┌────────────────────────────┐
│         node.Node          │
│  - Config load             │
│  - Lifecycle registry      │
│  - P2P config prep         │
└────────────┬───────────────┘
             │ RegisterLifecycle(service)
             ▼
┌────────────────────────────┐
│      eth.Ethereum          │
│  - Chain DB init           │
│  - TxPool, Miner, Sync     │
│  - RPC exposure            │
└────────────┬───────────────┘
             │
             ▼
┌────────────────────────────┐
│       p2p.Server           │
│  - Peer discovery          │
│  - Handshake protocols     │
│  - Dispatch messages       │
└────────────────────────────┘

package node

// Lifecycle encompasses the behavior of services that can be started and stopped
// on the node. Lifecycle management is delegated to the node, but it is the
// responsibility of the service-specific package to configure and register the
// service on the node using the `RegisterLifecycle` method.
type Lifecycle interface {
	// Start is called after all services have been constructed and the networking
	// layer was also initialized to spawn any goroutines required by the service.
	Start() error

	// Stop terminates all goroutines belonging to the service, blocking until they
	// are all terminated.
	Stop() error
}

// Node is a container on which services can be registered.
type Node struct {
	// ...
	lifecycles    []Lifecycle // All registered backends, services, and auxiliary services that have a lifecycle
	// ...
}

// RegisterLifecycle registers the given Lifecycle on the node.
func (n *Node) RegisterLifecycle(lifecycle Lifecycle) {
	n.lock.Lock()
	defer n.lock.Unlock()

	if n.state != initializingState {
		panic("can't register lifecycle on running/stopped node")
	}
	if slices.Contains(n.lifecycles, lifecycle) {
		panic(fmt.Sprintf("attempt to register lifecycle %T more than once", lifecycle))
	}
	n.lifecycles = append(n.lifecycles, lifecycle)
}

// Start starts all registered lifecycles, RPC services and p2p networking.
// Node can only be started once.
func (n *Node) Start() error {
	n.startStopLock.Lock()
	defer n.startStopLock.Unlock()

	n.lock.Lock()
	switch n.state {
	case runningState:
		n.lock.Unlock()
		return ErrNodeRunning
	case closedState:
		n.lock.Unlock()
		return ErrNodeStopped
	}
	n.state = runningState
	// open networking and RPC endpoints
	err := n.openEndpoints()
	lifecycles := make([]Lifecycle, len(n.lifecycles))
	copy(lifecycles, n.lifecycles)
	n.lock.Unlock()

	// Check if endpoint startup failed.
	if err != nil {
		n.doClose(nil)
		return err
	}
	// Start all registered lifecycles.
	var started []Lifecycle
	for _, lifecycle := range lifecycles {
		if err = lifecycle.Start(); err != nil {
			break
		}
		started = append(started, lifecycle)
	}
	// Check if any lifecycle failed to start.
	if err != nil {
		n.stopServices(started)
		n.doClose(nil)
	}
	return err
}

// New creates a new Ethereum object (including the initialisation of the common Ethereum object),
// whose lifecycle will be managed by the provided node.
func New(stack *node.Node, config *ethconfig.Config) (*Ethereum, error) {
	// ... (service initialization)

	eth := &Ethereum{
		// ...
	}

	// ... (more initialization)

	// Register the backend on the node
	stack.RegisterAPIs(eth.APIs())
	stack.RegisterProtocols(eth.Protocols())
	stack.RegisterLifecycle(eth)

	return eth, nil
}

// Start implements node.Lifecycle, starting all internal goroutines needed by the
// Ethereum protocol implementation.
func (s *Ethereum) Start() error {
	// ...
}

// Stop implements node.Lifecycle, terminating all internal goroutines used by the
// Ethereum protocol.
func (s *Ethereum) Stop() error {
	// ...
}

func main() {
	if err := app.Run(os.Args); err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}
}

func geth(ctx *cli.Context) error {
	if args := ctx.Args().Slice(); len(args) > 0 {
		return fmt.Errorf("invalid command: %q", args[0])
	}

	prepare(ctx)
	stack := makeFullNode(ctx)
	defer stack.Close()

	startNode(ctx, stack, false)
	stack.Wait()
	return nil
}

// makeFullNode loads geth configuration and creates the Ethereum backend.
func makeFullNode(ctx *cli.Context) *node.Node {
	stack, cfg := makeConfigNode(ctx)
    // ...
	backend, eth := utils.RegisterEthService(stack, &cfg.Eth)
    // ...
	return stack
}

// RegisterEthService registers the Ethereum service and its APIs.
// It returns the API backend and the service itself.
func RegisterEthService(stack *node.Node, cfg *ethconfig.Config) (*ethapi.PublicEthereumAPI, *eth.Ethereum) {
	backend, err := eth.New(stack, cfg)
	if err != nil {
		Fatalf("Failed to register the Ethereum service: %v", err)
	}
	// The eth service is not usable outside of this package, and we don't need it.
	// The API backend is what we need to start the GraphQL service.
	apiBackend := ethapi.New(backend)
	stack.RegisterAPIs(apiBackend.APIs())
	return apiBackend, backend
}