LAUNCHING FSM state #462

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open

freemans13 wants to merge 6 commits into bsv-blockchain:main from freemans13:stu/launching-fsm-state

.markdownlint.yml

-Original file line number
+Diff line change
@@ Expand Up / @@ -5,6 +5,7 @@ @@
     MD013: false  # Line length (Material MkDocs handles this)
     MD033: false  # Allow inline HTML (needed for admonitions)
     MD041: false  # First line in file should be a top level header
+    MD060: false  # Table column style (existing tables use various styles)
     # Configure list formatting rules (these would have caught our issues!)
     MD004:
@@ Expand Down @@

daemon/daemon_test.go

-Original file line number
+Diff line change
@@ Expand Up / @@ -232,7 +232,7 @@ func TestDaemon_Start_AllServices(t *testing.T) { @@
     	// Configure settings - this will now pick up KAFKA_PORT and persister URLs from gocore.Config
     	appSettings := settings.NewSettings()
-    	appSettings.LocalTestStartFromState = "RUNNING"
+    	appSettings.LocalTestStartFromState = "LAUNCHING"
     	appSettings.P2P.Port = p2pPort
     	appSettings.Asset.HTTPPort = assetPort
     	appSettings.Asset.HTTPListenAddress = fmt.Sprintf(":%d", assetPort)
@@ Expand Down @@

daemon/test_daemon.go

-Original file line number
+Diff line change
@@ Expand Up @@
     	require.NoError(t, err)
     	appSettings.Asset.CentrifugeDisable = true
     	appSettings.UtxoStore.DBTimeout = 500 * time.Second
-    	appSettings.LocalTestStartFromState = "RUNNING"
+    	appSettings.LocalTestStartFromState = "LAUNCHING"
     	appSettings.SubtreeValidation.TxMetaCacheEnabled = false
     	appSettings.ProfilerAddr = ""
     	appSettings.RPC.CacheEnabled = false
@@ Expand Down @@

docs/howto/developersHowToTeranodeCLI.md

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -68,22 +68,27 @@ SETTINGS_CONTEXT=dev.[YOUR_CONTEXT] ./teranode-cli setfsmstate --fsmstate <state
  
    Valid states you can issue are:

    - `launching` - Performs sync check before starting operations (recommended from IDLE)

    - `running` - Normal operation mode (processes transactions and creates blocks)

    - `idle` - Idle mode (default startup state)

    - `catchingblocks` - Catching up blocks from peers

    - `legacysyncing` - Legacy sync mode (for syncing from legacy BSV nodes)

    Example to switch to RUNNING state:

    Example to launch the node (recommended from IDLE):

    ```bash

    SETTINGS_CONTEXT=dev.[YOUR_CONTEXT] ./teranode-cli setfsmstate --fsmstate running

    SETTINGS_CONTEXT=dev.[YOUR_CONTEXT] ./teranode-cli setfsmstate --fsmstate launching

    ```

    Expected output:

    ```text

    Setting FSM state to: running

    FSM state successfully set to: RUNNING

    Setting FSM state to: launching

    FSM state successfully set to: LAUNCHING

    ```

    The node will automatically transition to RUNNING (if synced) or CATCHINGBLOCKS (if behind peers).

    ### View System Configuration

    To inspect your current system settings:

    @@ -253,10 +258,10 @@ Press `r` to refresh manually or `q` to quit.
  
        SETTINGS_CONTEXT=dev.[YOUR_CONTEXT] ./teranode-cli getfsmstate

        ```

    3. Transition to RUNNING state:

    3. Launch the node (performs sync check before running):

        ```bash

        SETTINGS_CONTEXT=dev.[YOUR_CONTEXT] ./teranode-cli setfsmstate --fsmstate running

        SETTINGS_CONTEXT=dev.[YOUR_CONTEXT] ./teranode-cli setfsmstate --fsmstate launching

        ```

    4. Verify the FSM state change:

docs/howto/miners/docker/minersHowToInstallation.md

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -265,20 +265,22 @@ docker compose up -d
  
    Force the node to transition to Run mode:

    **Option 1: Using Admin Dashboard (Easiest)**

    ##### Option 1: Using Admin Dashboard (Easiest)

    Access the dashboard at <http://localhost:8090/admin> and use the FSM State controls to transition to **RUNNING** or **LEGACYSYNCING**.

    Access the dashboard at <http://localhost:8090/admin> and use the FSM State controls to **LAUNCH** the node or transition to **LEGACYSYNCING**.

    **Option 2: Using teranode-cli**

    ##### Option 2: Using teranode-cli

    ```bash

    # Transition to Run mode

    docker exec -it blockchain teranode-cli setfsmstate --fsmstate running

    # Launch the node (recommended - performs sync check before running)

    docker exec -it blockchain teranode-cli setfsmstate --fsmstate launching

    # Or transition to LegacySync mode

    # Or transition to LegacySync mode (for syncing from legacy BSV nodes)

    docker exec -it blockchain teranode-cli setfsmstate --fsmstate legacysyncing

    ```

    > **Note:** The LAUNCHING state performs a sync check and will automatically transition to RUNNING (if synced) or CATCHINGBLOCKS (if behind peers).

    You can verify the current state with:

    ```bash

    @@ -589,11 +591,11 @@ docker exec -it blockchain teranode-cli setfsmstate --fsmstate LEGACYSYNCING
  
    # Or via Admin Dashboard at http://localhost:8090/admin

    ```

    **Set FSM State to Running**:

    **Launch the Node** (recommended from IDLE):

    ```bash

    # Via teranode-cli

    docker exec -it blockchain teranode-cli setfsmstate --fsmstate RUNNING

    # Via teranode-cli (performs sync check before running)

    docker exec -it blockchain teranode-cli setfsmstate --fsmstate LAUNCHING

    # Or via Admin Dashboard at http://localhost:8090/admin

    ```

docs/howto/miners/docker/minersHowToResetTeranode.md

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -160,8 +160,8 @@ Teranode starts in IDLE state. You need to transition to the appropriate state:
  
    # Or via teranode-cli

    docker exec -it blockchain teranode-cli setfsmstate --fsmstate LEGACYSYNCING

    # Or for direct operation:

    docker exec -it blockchain teranode-cli setfsmstate --fsmstate RUNNING

    # Or launch the node (performs sync check before running):

    docker exec -it blockchain teranode-cli setfsmstate --fsmstate LAUNCHING

    ```

    ### Monitor Synchronization

docs/howto/miners/kubernetes/minersHowToInstallation.md

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -208,12 +208,14 @@ By default, this configuration deploys Teranode to connect to the **teratestnet*
  
    #### Start Syncing Process

    A fresh Teranode starts up in IDLE state by default. To start syncing from the network, you can run:

    A fresh Teranode starts up in IDLE state by default. To launch the node and start syncing from the network, run:

    ```bash

    kubectl exec -it $(kubectl get pods -n teranode-operator -l app=blockchain -o jsonpath='{.items[0].metadata.name}') -n teranode-operator -- teranode-cli setfsmstate -fsmstate running

    kubectl exec -it $(kubectl get pods -n teranode-operator -l app=blockchain -o jsonpath='{.items[0].metadata.name}') -n teranode-operator -- teranode-cli setfsmstate -fsmstate launching

    ```

    > **Note:** The LAUNCHING state performs a sync check and will automatically transition to RUNNING (if synced) or CATCHINGBLOCKS (if behind peers).

    To know more about the syncing process, please refer to the [Teranode Sync Guide](minersHowToSyncTheNode.md)

    ## Verifying the Deployment

docs/howto/miners/kubernetes/minersHowToInstallationDeprecated.md

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -2,21 +2,21 @@
  
    Last modified: 29-January-2025

    # Index

    ## Index

    - [Introduction](#introduction)

    - [Prerequisites](#prerequisites)

    - [Hardware Requirements](#hardware-requirements)

    - [Software Requirements](#software-requirements)

    - [Network Considerations](#network-considerations)

    - [Installation Process](#installation-process)

      - [Teranode Initial Synchronization](#teranode-initial-synchronization)

        - [Full P2P Download](#full-p2p-download)

        - [Initial Data Set Installation](#initial-data-set-installation)

      - [Teranode Installation - Introduction to the Kubernetes Operator](#teranode-installation-introduction-to-the-kubernetes-operator)

      - [Installing Teranode with the Custom Kubernetes Operator](#installing-teranode-with-the-custom-kubernetes-operator)

        - [Teranode Initial Synchronization](#teranode-initial-synchronization)

            - [Full P2P Download](#full-p2p-download)

            - [Initial Data Set Installation](#initial-data-set-installation)

        - [Teranode Installation - Introduction to the Kubernetes Operator](#teranode-installation---introduction-to-the-kubernetes-operator)

        - [Installing Teranode with the Custom Kubernetes Operator](#installing-teranode-with-the-custom-kubernetes-operator)

    - [Optimizations](#optimizations)

    - [Reference - Settings](#reference-settings)

    - [Reference - Settings](#reference---settings)

    ## Introduction

    @@ -153,7 +153,7 @@ data:
  
      utxostore: 'aerospike://...'

    ```

    To review the list of settings you could configure in the ConfigMap, please refer to the list [here](https://github.com/bsv-blockchain/teranode/blob/main/settings.conf).

    To review the list of settings you could configure in the ConfigMap, please refer to [the settings configuration file](https://github.com/bsv-blockchain/teranode/blob/main/settings.conf).

    #### Storage Requirements

    @@ -300,15 +300,17 @@ Standard Kubernetes logging and troubleshooting approaches apply. Users can use
  
    - The various Teranode services will be accessible through the configured ingress or service endpoints.

    - Refer to your specific ingress or network configuration for exact URLs and ports.

    ### Step 9: Change the node status to Run or LegacySync

    ### Step 9: Launch the Node or Enter LegacySync

    1. **Force the node to transition to Run mode:**

    1. **Launch the node (recommended - performs sync check before running):**

        ```bash

        kubectl exec -it $(kubectl get pods -n teranode-operator -l app=blockchain -o jsonpath='{.items[0].metadata.name}') -n teranode-operator -- teranode-cli setfsmstate --fsmstate RUNNING

        kubectl exec -it $(kubectl get pods -n teranode-operator -l app=blockchain -o jsonpath='{.items[0].metadata.name}') -n teranode-operator -- teranode-cli setfsmstate --fsmstate LAUNCHING

        ```

    2. **Or LegacySync mode:**

        > **Note:** The LAUNCHING state performs a sync check and will automatically transition to RUNNING (if synced) or CATCHINGBLOCKS (if behind peers).

    2. **Or LegacySync mode (for syncing from legacy BSV nodes):**

        ```bash

        kubectl exec -it $(kubectl get pods -n teranode-operator -l app=blockchain -o jsonpath='{.items[0].metadata.name}') -n teranode-operator -- teranode-cli setfsmstate --fsmstate LEGACYSYNCING

    @@ -371,4 +373,4 @@ If you have local access to SV Nodes, you can use them to speed up the initial b
  
    ## Reference - Settings

    You can find the pre-configured settings file [here](https://github.com/bsv-blockchain/teranode/blob/main/settings.conf). You can refer to this document in order to identify the current system behaviour and in order to override desired settings in your `settings_local.conf`.

    You can find the [pre-configured settings file](https://github.com/bsv-blockchain/teranode/blob/main/settings.conf) in the repository. You can refer to this document in order to identify the current system behaviour and in order to override desired settings in your `settings_local.conf`.

docs/howto/miners/kubernetes/minersHowToStopStartKubernetesTeranode.md

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -41,12 +41,14 @@ kubectl wait --for=condition=ready pod -l app=blockchain -n teranode-operator --
  
    kubectl logs -n teranode-operator -l app=blockchain -f

    ```

    ### 3. Start Syncing (if needed)

    ### 3. Launch the Node (if needed)

    ```bash

    kubectl exec -it $(kubectl get pods -n teranode-operator -l app=blockchain -o jsonpath='{.items[0].metadata.name}') -n teranode-operator -- teranode-cli setfsmstate -fsmstate running

    kubectl exec -it $(kubectl get pods -n teranode-operator -l app=blockchain -o jsonpath='{.items[0].metadata.name}') -n teranode-operator -- teranode-cli setfsmstate -fsmstate launching

    ```

    > **Note:** The LAUNCHING state performs a sync check and will automatically transition to RUNNING (if synced) or CATCHINGBLOCKS (if behind peers).

    ## Stopping Teranode

    ### 1. Graceful Shutdown

docs/howto/miners/minersHowToInteractWithFSM.md

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -48,14 +48,16 @@ The `teranode-cli` is recommended for scripting and automation. It provides a co
  
    ### Docker Compose Environment

    #### 1. Check Current State

    ```bash

    docker exec -it blockchain teranode-cli getfsmstate

    ```

    #### 2. Set New State

    ```bash

    docker exec -it blockchain teranode-cli setfsmstate --fsmstate RUNNING

    # Launch the node (recommended from IDLE - performs sync check)

    docker exec -it blockchain teranode-cli setfsmstate --fsmstate LAUNCHING

    ```

    ### Kubernetes Environment

    @@ -78,18 +80,31 @@ kubectl exec -it $(kubectl get pods -n teranode-operator -l app=blockchain -o js
  
    #### 2. Set New State

    ```bash

    # Change state to RUNNING

    kubectl exec -it $(kubectl get pods -n teranode-operator -l app=blockchain -o jsonpath='{.items[0].metadata.name}') -n teranode-operator -- teranode-cli setfsmstate --fsmstate RUNNING

    # Launch the node (recommended from IDLE - performs sync check)

    kubectl exec -it $(kubectl get pods -n teranode-operator -l app=blockchain -o jsonpath='{.items[0].metadata.name}') -n teranode-operator -- teranode-cli setfsmstate --fsmstate LAUNCHING

    ```

    ## Valid FSM States

    The following states are valid for all environments:

    - IDLE

    - RUNNING

    - LEGACYSYNCING

    - CATCHINGBLOCKS

    - **IDLE** - Node is stopped and not processing

    - **LAUNCHING** - Node is performing initial sync check (auto-transitions to RUNNING or CATCHINGBLOCKS)

    - **RUNNING** - Node is fully operational

    - **CATCHINGBLOCKS** - Node is catching up with the network

    - **LEGACYSYNCING** - Node is syncing using legacy Bitcoin protocol

    ## State Transitions

    **Starting the node (from IDLE):**

    - Use `LAUNCH` event to transition IDLE → LAUNCHING

    - The node will automatically transition to RUNNING (if synced) or CATCHINGBLOCKS (if behind peers)

    - **Note:** The `RUN` event is NOT valid from IDLE state. You must use `LAUNCH`.

    **Legacy sync mode:**

    - Use `LEGACYSYNC` event to transition IDLE → LEGACYSYNCING (bypasses LAUNCHING state)

    ## Validation

    @@ -118,16 +133,20 @@ grpcurl -plaintext blockchain:18087 blockchain_api.BlockchainAPI.GetFSMCurrentSt
  
    **Trigger State Transitions:**

    ```bash

    # Transition to RUNNING state

    # Start the node (IDLE -> LAUNCHING -> RUNNING/CATCHINGBLOCKS)

    # This is the recommended way to start the node

    grpcurl -plaintext blockchain:18087 blockchain_api.BlockchainAPI.Launch

    # Transition to RUNNING state (only valid from LAUNCHING, LEGACYSYNCING, or CATCHINGBLOCKS)

    grpcurl -plaintext blockchain:18087 blockchain_api.BlockchainAPI.Run

    # Transition to LEGACYSYNCING state

    # Transition to LEGACYSYNCING state (from IDLE)

    grpcurl -plaintext blockchain:18087 blockchain_api.BlockchainAPI.LegacySync

    # Transition to CATCHINGBLOCKS state

    # Transition to CATCHINGBLOCKS state (from RUNNING or LAUNCHING)

    grpcurl -plaintext blockchain:18087 blockchain_api.BlockchainAPI.CatchUpBlocks

    # Transition to IDLE state

    # Transition to IDLE state (from RUNNING or LEGACYSYNCING)

    grpcurl -plaintext blockchain:18087 blockchain_api.BlockchainAPI.Idle

    ```

    @@ -157,16 +176,20 @@ Expected output:
  
    **Trigger State Transitions:**

    ```bash

    # Transition to RUNNING state

    # Start the node (IDLE -> LAUNCHING -> RUNNING/CATCHINGBLOCKS)

    # This is the recommended way to start the node

    grpcurl -plaintext localhost:18087 blockchain_api.BlockchainAPI.Launch

    # Transition to RUNNING state (only valid from LAUNCHING, LEGACYSYNCING, or CATCHINGBLOCKS)

    grpcurl -plaintext localhost:18087 blockchain_api.BlockchainAPI.Run

    # Transition to LEGACYSYNCING state

    # Transition to LEGACYSYNCING state (from IDLE)

    grpcurl -plaintext localhost:18087 blockchain_api.BlockchainAPI.LegacySync

    # Transition to CATCHINGBLOCKS state

    # Transition to CATCHINGBLOCKS state (from RUNNING or LAUNCHING)

    grpcurl -plaintext localhost:18087 blockchain_api.BlockchainAPI.CatchUpBlocks

    # Transition to IDLE state

    # Transition to IDLE state (from RUNNING or LEGACYSYNCING)

    grpcurl -plaintext localhost:18087 blockchain_api.BlockchainAPI.Idle

    ```

docs/references/services/blockchain_reference.md

-Original file line number
+Diff line change
@@ Expand Up @@
     Sends an event to the finite state machine.
+    ### Launch
+    ```go
+    func (b *Blockchain) Launch(ctx context.Context, _ *emptypb.Empty) (*emptypb.Empty, error)
+    ```
+    Transitions the FSM from IDLE to the LAUNCHING state. This is the **recommended way to start the node** as it performs an initial sync check before processing transactions. The P2P sync coordinator will automatically transition the node to RUNNING (if synced) or CATCHINGBLOCKS (if behind peers).
     ### Run
     ```go
     func (b *Blockchain) Run(ctx context.Context, _ *emptypb.Empty) (*emptypb.Empty, error)
     ```
-    Transitions the FSM to the RUNNING state.
+    Transitions the FSM to the RUNNING state. **Note:** This is only valid from LAUNCHING, LEGACYSYNCING, or CATCHINGBLOCKS states - not from IDLE. Use Launch() to start the node from IDLE.
     ### CatchUpBlocks
@@ Expand Down @@

docs/state-machine.diagram.md

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -7,11 +7,21 @@ The mermaid diagram outlined below represents the various states and events that
  
    ```mermaid

    stateDiagram-v2

        [*] --> IDLE

        CATCHINGBLOCKS --> RUNNING: RUN

        IDLE --> LAUNCHING: LAUNCH

        IDLE --> LEGACYSYNCING: LEGACYSYNC

        IDLE --> RUNNING: RUN

        LAUNCHING --> RUNNING: RUN

        LAUNCHING --> CATCHINGBLOCKS: CATCHUPBLOCKS

        CATCHINGBLOCKS --> RUNNING: RUN

        LEGACYSYNCING --> RUNNING: RUN

        LEGACYSYNCING --> IDLE: STOP

        RUNNING --> CATCHINGBLOCKS: CATCHUPBLOCKS

        RUNNING --> IDLE: STOP

    ```

    ## States

    - **IDLE**: Node is stopped and not processing. Operator must trigger LAUNCH to start.

    - **LAUNCHING**: Node is performing initial sync check before processing. Auto-transitions to RUNNING (if synced) or CATCHINGBLOCKS (if behind peers).

    - **RUNNING**: Node is fully operational and processing transactions/blocks.

    - **CATCHINGBLOCKS**: Node is catching up with the network by downloading blocks from peers.

    - **LEGACYSYNCING**: Node is syncing using the legacy Bitcoin protocol (for connecting to legacy nodes).

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

LAUNCHING FSM state #462

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

Uh oh!

LAUNCHING FSM state #462

Are you sure you want to change the base?

Uh oh!

LAUNCHING FSM state #462

Uh oh!

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

Uh oh!