### Clone and start Teranode quickstart

Source: https://github.com/bsv-blockchain/teranode/blob/main/deploy/docker/README.md

Use these commands to initialize and launch the Teranode environment via the quickstart repository.

```bash
git clone https://github.com/bsv-blockchain/teranode-quickstart.git
cd teranode-quickstart
./setup.sh
./start.sh
```

--------------------------------

### Initialize and start the local Teranode network

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/howto/locallyRunningServices.md

Clones the quickstart repository and executes the setup and start scripts to launch the network.

```bash
git clone https://github.com/bsv-blockchain/teranode-quickstart.git
cd teranode-quickstart
./setup.sh
./start.sh
./status.sh
```

--------------------------------

### Start development server

Source: https://github.com/bsv-blockchain/teranode/blob/main/ui/dashboard/svelte.md

Launches the development server after installing project dependencies.

```bash
npm run dev

# or start the server and open the app in a new browser tab
npm run dev -- --open
```

--------------------------------

### Start Development Server

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/topics/dashboard.md

Commands to install dependencies and launch the dashboard in development mode.

```bash
# Install dependencies
npm install --prefix ./ui/dashboard

# Run development server
npm run dev --prefix ./ui/dashboard
```

--------------------------------

### Clone and setup Teranode

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/howto/miners/docker/minersHowToInstallation.md

Initializes the deployment environment by cloning the quickstart repository and running the interactive configuration script.

```bash
git clone https://github.com/bsv-blockchain/teranode-quickstart.git
cd teranode-quickstart
./setup.sh
```

--------------------------------

### Initialize Teranode Configuration

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/howto/miners/docker/minersHowToConfigureTheNode.md

Run the setup script from the quickstart repository root to generate initial configuration and secrets.

```bash
./setup.sh
```

--------------------------------

### Install bsvjson

Source: https://github.com/bsv-blockchain/teranode/blob/main/services/rpc/bsvjson/README.md

Use the go get command to download and install the package.

```bash
$ go get -u github.com/bitcoinsv/bsvd/bsvjson
```

--------------------------------

### Development Configuration Example

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/references/settings/services/alert_settings.md

Minimal configuration example for local development using SQLite.

```bash
alert_store=sqlite:///alert
alert_genesis_keys=devkey1
```

--------------------------------

### Log Viewer Usage Examples

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/howto/miners/minersHowToTeranodeCLI.md

Examples for launching the log viewer with default or custom file paths and buffer sizes.

```bash
# View logs from default location
teranode-cli logs

# View logs from a specific file with larger buffer
teranode-cli logs --file=/var/log/teranode/teranode.log --buffer=50000
```

--------------------------------

### Start Daemon Services

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/references/teranodeDaemonReference.md

Initializes and starts services based on provided settings and command line arguments.

```go
func (d *Daemon) Start(logger ulogger.Logger, args []string, appSettings *settings.Settings, readyChannel ...chan struct{})
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/howto/developerSetup.md

Navigate to the project directory and execute the make command to install required dependencies.

```bash
cd teranode

# This will install all required dependencies (protobuf, golangci-lint, etc.)
make install
```

```bash
PYTHONPATH=$HOME/Library/Python/3.9/lib/python/site-packages make install  #Make sure the path is correct for your own python version
```

--------------------------------

### Start HTTP server

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/references/services/asset_reference.md

Starts the HTTP server listening on the specified address.

```go
func (h *HTTP) Start(ctx context.Context, addr string) error
```

--------------------------------

### Perform Network Sync

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/howto/miners/docker/minersHowToSyncTheNode.md

Initialize and start a fresh Teranode installation using the network sync method.

```bash
./setup.sh
./start.sh
```

--------------------------------

### Production Configuration Example

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/references/settings/services/alert_settings.md

Example environment variable configuration for a production environment using PostgreSQL.

```bash
alert_store=postgres://user:pass@host:5432/alert_db?sslmode=require
alert_genesis_keys=key1|key2|key3
alert_p2p_port=4001
alert_protocol_id=/bitcoin/alert-system/1.0.0
alert_topic_name=bitcoin_alert_system
```

--------------------------------

### Start Services with Replicas

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/staging/operations/ClusterManagementAndOperations.md

Start specific services with a defined number of replicas using the ksd command.

```bash
ksd coinbase1 --replicas=1
```

```bash
ksd propagation1 --replicas=13
```

```bash
ksd tx-blaster1 --replicas=11
```

--------------------------------

### Start HTTP server

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/references/services/propagation_reference.md

Initializes and starts the HTTP server for transaction processing on specified addresses.

```go
func (ps *PropagationServer) startHTTPServer(ctx context.Context, httpAddresses string) error
```

--------------------------------

### Manage Server Lifecycle

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/references/services/legacy_reference.md

Methods for initializing, starting, and stopping the server. Start blocks until the gRPC service completes.

```go
func (s *Server) Init(ctx context.Context) error
```

```go
func (s *Server) Start(ctx context.Context, readyCh chan<- struct{}) error
```

```go
func (s *Server) Stop(_ context.Context) error
```

--------------------------------

### Update Quickstart Repository

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/howto/miners/docker/minersUpdatingTeranode.md

Updates the local quickstart scripts and Compose files.

```bash
git pull
```

--------------------------------

### Verify Go Installation

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/howto/developerSetup.md

Check the installed version of Go to ensure it meets the minimum requirement.

```bash
go version
```

--------------------------------

### Execute Specific Test Examples

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/topics/functionalRequirementTests.md

Concrete examples of running a suite-based test and a standalone test file.

```bash
# Suite-based test (TNA)
go test -v -run "^TestTNA1TestSuite$/TestBroadcastNewTxAllNodes$" -tags test_tna ./test/tna/tna1_test.go

# Standalone test (TNC in e2e/daemon)
go test -v -run "^TestCoinbaseTXAmount$" ./test/e2e/daemon/tnc1_3_test.go
```

--------------------------------

### Initialize HTTP server

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/references/services/asset_reference.md

Performs necessary setup for the HTTP server instance.

```go
func (h *HTTP) Init(_ context.Context) error
```

--------------------------------

### Get block headers from height

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/references/services/blockchain_reference.md

Fetches headers starting from a specific block height.

```go
func (b *Blockchain) GetBlockHeadersFromHeight(ctx context.Context, req *blockchain_api.GetBlockHeadersFromHeightRequest) (*blockchain_api.GetBlockHeadersFromHeightResponse, error)
```

--------------------------------

### Get Block RPC call

Source: https://github.com/bsv-blockchain/teranode/blob/main/test/utils/explorer/scripts/teranode.ipynb

Example usage of the CallRPC function to retrieve block information.

```go
hashStr := ""
getBlock, err := CallRPC("http://host.docker.internal:19292", "getblock", []interface{}{hashStr})
if err != nil {
    fmt.Printf("error getting block: %v", err)
}
fmt.Println(getBlock)
```

--------------------------------

### Get block header IDs

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/references/services/blockchain_reference.md

Retrieves only the identifiers for block headers starting from a specific hash.

```go
func (b *Blockchain) GetBlockHeaderIDs(ctx context.Context, request *blockchain_api.GetBlockHeadersRequest) (*blockchain_api.GetBlockHeaderIDsResponse, error)
```

--------------------------------

### Get multiple block headers

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/references/services/blockchain_reference.md

Retrieves a sequence of block headers starting from a specific hash.

```go
func (b *Blockchain) GetBlockHeaders(ctx context.Context, request *blockchain_api.GetBlockHeadersRequest) (*blockchain_api.GetBlockHeadersResponse, error)
```

--------------------------------

### Get FSM State Response

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/howto/miners/minersHowToInteractWithAssetServer.md

Example JSON response for the current blockchain FSM state.

```json
{
  "state": "Running",
  "metadata": {
    "syncedHeight": 700001,
    "bestHeight": 700001,
    "isSynchronized": true
  },
  "allowedTransitions": ["stop", "pause"]
}
```

--------------------------------

### Client Setup Methods

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/references/testingTechnicalReference.md

Methods for initializing gRPC clients and configuring storage access for Teranode test clients.

```go
// Sets up HTTP stores for blocks and subtrees
func (t *TeranodeTestEnv) setupBlobStores() error {
    // Create HTTP clients for blob stores
    // Configure block and subtree storage access
}

// Sets up blockchain client for a node
func (t *TeranodeTestEnv) setupBlockchainClient(node *TeranodeTestClient) error {
    // Initialize gRPC connection to blockchain service
    // Create and configure blockchain client
}

// Sets up block assembly client for a node
func (t *TeranodeTestEnv) setupBlockassemblyClient(node *TeranodeTestClient) error {
    // Initialize gRPC connection to block assembly service
    // Create and configure block assembly client
}

// Sets up propagation client for a node
func (t *TeranodeTestEnv) setupPropagationClient(node *TeranodeTestClient) error {
    // Initialize gRPC connection to propagation service
    // Create and configure propagation client
}

// GetMappedPort retrieves the mapped port for a service running in Docker Compose
func (t *TeranodeTestEnv) GetMappedPort(nodeName string, port nat.Port) (nat.Port, error) {
    // Find the exposed port mapping for a container service
}
```

--------------------------------

### Start Infrastructure Dependencies

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/howto/developerSetup.md

Launch required services like PostgreSQL and Aerospike using provided scripts.

```bash
# Start PostgreSQL in Docker
./scripts/postgres.sh
```

```bash
# Start Aerospike in Docker
./scripts/aerospike.sh
```

--------------------------------

### GET /api/v1/blocks/:hash/json

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/howto/miners/minersHowToInteractWithAssetServer.md

Retrieves multiple consecutive blocks starting with the specified hash as a JSON array.

```APIDOC
## GET /api/v1/blocks/:hash/json

### Description
Retrieves multiple consecutive blocks starting with the specified hash as a JSON array.

### Method
GET

### Endpoint
/api/v1/blocks/:hash/json

### Parameters
#### Path Parameters
- **hash** (string) - Required - Starting block hash (hex string)
#### Query Parameters
- **n** (integer) - Optional - Number of blocks to retrieve (default: 100, max: 1000)

### Response
- JSON array containing parsed block objects
```

--------------------------------

### Implement suite setup and teardown

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/references/testingTechnicalReference.md

Use these methods to automate environment lifecycle management, including Docker node orchestration and resource cleanup.

```go
// SetupTest runs before each test
func (suite *TeranodeTestSuite) SetupTest() {
    // Initialize test environment
    // Set up Docker nodes if configured
    // Initialize node clients
    // Send initial RUN event to blockchain
    // Wait for all nodes to be healthy
    // Optionally generate initial blocks based on InitBlockHeight
}

// TearDownTest runs after each test
func (suite *TeranodeTestSuite) TearDownTest() {
    // Stop Docker nodes
    // Clean up resources
    // Cancel context
}
```

--------------------------------

### Complete Tracing Implementation Example

Source: https://github.com/bsv-blockchain/teranode/blob/main/util/tracing/README.html

A full service implementation demonstrating span initialization, child spans, attribute setting, and error handling.

```go
package myservice

import (
    "context"
    "fmt"

    "github.com/bsv-blockchain/teranode/util/tracing"
    "go.opentelemetry.io/otel/attribute"
)

type Service struct {
    tracer *tracing.UTracer
}

func NewService() *Service {
    return &Service{
        tracer: tracing.Tracer("myservice"),
    }
}

func (s *Service) ProcessBatch(ctx context.Context, items []Item) (err error) {
    // Start tracing with comprehensive options
    ctx, span, endSpan := s.tracer.Start(ctx, "ProcessBatch",
        tracing.WithTag("batch.size", fmt.Sprintf("%d", len(items))),
        tracing.WithLogMessage(logger, "Processing batch of %d items", len(items)),
    )
    defer endSpan(err) // Ensures span is ended with final error state

    // Add runtime attributes
    span.SetAttribute("service.version", "1.0.0")
    span.AddEvent("processing_started")

    // Process items
    var processed, failed int
    for i, item := range items {
        // Create child span for each item
        _, itemSpan, endItemSpan := s.tracer.Start(ctx, "ProcessItem",
            tracing.WithTag("item.id", item.ID),
            tracing.WithTag("item.index", fmt.Sprintf("%d", i)),
        )

        if err := s.processItem(item); err != nil {
            // Record item error
            itemSpan.RecordError(err)
            endItemSpan(err)
            failed++
            continue
        }

        endItemSpan() // Success - no error
        processed++
    }

    // Record final metrics
    span.SetAttribute("batch.processed", processed)
    span.SetAttribute("batch.failed", failed)
    span.AddEvent("processing_completed")

    if failed > 0 {
        err = fmt.Errorf("failed to process %d out of %d items", failed, len(items))
        return err
    }

    return nil
}
```

--------------------------------

### GET /api/v1/blocks/:hash/hex

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/howto/miners/minersHowToInteractWithAssetServer.md

Retrieves multiple consecutive blocks starting with the specified hash as a hexadecimal string.

```APIDOC
## GET /api/v1/blocks/:hash/hex

### Description
Retrieves multiple consecutive blocks starting with the specified hash as a hexadecimal string.

### Method
GET

### Endpoint
/api/v1/blocks/:hash/hex

### Parameters
#### Path Parameters
- **hash** (string) - Required - Starting block hash (hex string)
#### Query Parameters
- **n** (integer) - Optional - Number of blocks to retrieve (default: 100, max: 1000)

### Response
- Hex string of concatenated block bytes (text/plain)
```

--------------------------------

### Initialize Settings Instance

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/references/settings.md

Create a new Settings instance to load configuration values based on the defined priority system.

```go
settings := settings.NewSettings()
```

--------------------------------

### Get Peer Information Request and Response

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/references/services/rpc_reference.md

Example request and response for retrieving connected network node data.

```json
{
    "jsonrpc": "1.0",
    "id": "curltest",
    "method": "getpeerinfo",
    "params": []
}
```

```json
{
    "result": [
        {
            "id": 1,
            "addr": "192.168.1.123:8333",
            "addrlocal": "192.168.1.100:8333",
            "services": "000000000000040d",
            "lastsend": 1657123456,
            "lastrecv": 1657123455,
            "bytessent": 123456,
            "bytesrecv": 234567,
            "conntime": 1657120000,
            "pingtime": 0.001,
            "version": 70015,
            "subver": "/Bitcoin SV:1.0.0/",
            "inbound": false,
            "startingheight": 750000,
            "banscore": 0,
            "synced_headers": 750000,
            "synced_blocks": 750000
        }
    ],
    "error": null,
    "id": "curltest"
}
```

--------------------------------

### GET /api/v1/blocks/:hash

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/howto/miners/minersHowToInteractWithAssetServer.md

Retrieves multiple consecutive blocks starting with the specified hash, traversing backward through the chain.

```APIDOC
## GET /api/v1/blocks/:hash

### Description
Retrieves multiple consecutive blocks starting with the specified hash, traversing backward through the chain.

### Method
GET

### Endpoint
/api/v1/blocks/:hash

### Parameters
#### Path Parameters
- **hash** (string) - Required - Starting block hash (hex string)
#### Query Parameters
- **n** (integer) - Optional - Number of blocks to retrieve (default: 100, max: 1000)

### Response
- Concatenated block data in binary format (application/octet-stream)
```

--------------------------------

### Initialize Server Instance

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/references/services/legacy_reference.md

Constructor for creating a new server instance with all required dependencies. Does not start network operations.

```go
func New(logger ulogger.Logger,
    tSettings *settings.Settings,
    blockchainClient blockchain.ClientI,
    validationClient validator.Interface,
    subtreeStore blob.Store,
    tempStore blob.Store,
    utxoStore utxo.Store,
    subtreeValidation subtreevalidation.Interface,
    blockValidation blockvalidation.Interface,
    blockAssemblyClient *blockassembly.Client,
) *Server
```

--------------------------------

### Start Teranode Services

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/howto/miners/docker/minersHowToStopStartDockerTeranode.md

Initializes the Teranode environment and performs the FSM startup transition.

```bash
./start.sh
```

--------------------------------

### Set up local test environment

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/howto/automatedTestingHowTo.md

Prerequisites and initial build commands for the Teranode test environment.

```bash
# Install required tools
docker compose
go 1.26 or higher
make
```

```bash
# Clone and build
git clone [repository]
cd teranode
docker compose build
```

```bash
# Run smoke tests
make smoketest
```

--------------------------------

### Configure Mining Pool Nodes

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/howto/miners/minersHowToUseListenMode.md

Example configuration for distinguishing between primary mining nodes and monitor nodes in a pool setup.

```conf
# Primary miner (full mode)
listen_mode = full
p2p_port = 9906

# Monitor nodes (listen only)
listen_mode = listen_only
p2p_port = 9907  # Different port for each monitor
```

--------------------------------

### Verify PyYAML Installation

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/howto/developerSetup.md

Check the installed version of PyYAML to confirm successful installation.

```bash
python -c "import yaml; print(yaml.__version__)"
```

--------------------------------

### Install Delve

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/howto/developerSetup.md

Installs the Delve debugger via Go.

```bash
go install github.com/go-delve/delve/cmd/dlv@latest
```

--------------------------------

### Install and Run Pre-commit Hooks

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/MARKDOWN_VALIDATION_GUIDE.md

Commands to initialize pre-commit hooks and execute markdownlint across all documentation files.

```bash
# Install pre-commit hooks
pre-commit install

# Run manually on all files
pre-commit run markdownlint --all-files
```

--------------------------------

### Verify Docker Installation

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/howto/developerSetup.md

Check that the Docker environment is correctly installed and accessible.

```bash
docker --version
```

--------------------------------

### Start RPC Server

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/references/services/rpc_reference.md

Initializes network listeners and begins accepting client connections. Signals readiness via the provided channel.

```go
func (s *RPCServer) Start(ctx context.Context, readyCh chan<- struct{}) error
```

--------------------------------

### Initialize teranode-dev

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/howto/developerSetup.md

Starts the interactive wizard to configure the local development environment.

```bash
./teranode-dev init
```

--------------------------------

### Install Python via Homebrew

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/howto/developerSetup.md

Install Python using Homebrew on macOS.

```bash
brew install python
```

--------------------------------

### Start Syncing Process

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/howto/miners/kubernetes/minersHowToInstallation.md

Executes the command to transition the Teranode state to running, initiating the synchronization process.

```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
```

--------------------------------

### Start Toxiproxy Infrastructure

Source: https://github.com/bsv-blockchain/teranode/blob/main/test/chaos/implementation_summary.md

Initializes the required Docker containers for chaos testing.

```bash
docker compose -f compose/docker-compose-ss.yml up -d
```

--------------------------------

### Stats Response Example

Source: https://github.com/bsv-blockchain/teranode/blob/main/ui/dashboard/docs/api/redoc-static.html

Example JSON response for the general network statistics endpoint.

```json
{  *   "tx_confirmed": 0,      *   "tx_mempool": 0,      *   "blocks_total": 0,      *   "block_latest_height": 0,      *   "avg_block_size": 0,      *   "avg_txs_per_block": 0       }
```

--------------------------------

### Start and Verify Minikube

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/howto/miners/kubernetes/minersHowToInstallation.md

Initialize a Minikube cluster with the recommended resource allocation and check its operational status.

```bash
# Start minikube with recommended resources
minikube start --cpus=4 --memory=8192 --disk-size=20gb

# Verify minikube status
minikube status
```

--------------------------------

### RPC Response Example

Source: https://github.com/bsv-blockchain/teranode/blob/main/test/utils/explorer/scripts/teranode.ipynb

Example JSON response received from a Teranode RPC call.

```json
{"result":[{"addr":"teranode-2:8084","duration":11494750,"retries":0},{"addr":"teranode-1:8084","duration":12056250,"retries":0},{"addr":"teranode-3:8084","duration":14463250,"retries":0}],"error":null,"id":null}
```

--------------------------------

### Script Test JSON Format Example

Source: https://github.com/bsv-blockchain/teranode/blob/main/test/consensus/README.md

Example of the expected structure for entries in script_tests.json.

```json
["0x51", "0x5f ADD 0x60 EQUAL", "P2SH,STRICTENC", "OK", "0x51 through 0x60 push 1 through 16 onto stack"]
```

--------------------------------

### Initialize and Start HTTPBlobServer

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/topics/stores/blob.md

Sets up the HTTP server to handle blob storage operations and registers it with the standard library's HTTP handler.

```go
// Create HTTP blob server
httpServer := blob.NewHTTPBlobServer(blobStore, logger)

// Start HTTP server
http.Handle("/blob/", http.StripPrefix("/blob", httpServer))
log.Fatal(http.ListenAndServe(":8080", nil))
```

--------------------------------

### View network documentation

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/howto/miners/docker/minersHowToInstallation.md

Displays the network-specific configuration notes required before selecting a network during setup.

```bash
less docs/NETWORKS.md
```

--------------------------------

### Install GPG and Pinentry

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/references/gitCommitSigningSetupGuide.md

Installs the GPG suite and the pinentry-mac tool for macOS Keychain integration.

```bash
brew install gnupg
```

```bash
brew install pinentry-mac
echo "pinentry-program $(which pinentry-mac)" >> ~/.gnupg/gpg-agent.conf
```

--------------------------------

### Create new HTTP instance

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/references/services/asset_reference.md

Initializes a new HTTP server instance using the provided logger, settings, and repository.

```go
func New(logger ulogger.Logger, tSettings *settings.Settings, repo *repository.Repository) (*HTTP, error)
```

--------------------------------

### Initialize Service

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/references/services/blockvalidation_reference.md

Configures background processors, validation clients, and message queues.

```go
func (u *Server) Init(ctx context.Context) (err error)
```

--------------------------------

### Start Service Operations

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/references/services/blockassembly_reference.md

Starts concurrent processing and signals readiness via the provided channel.

```go
func (ba *BlockAssembly) Start(ctx context.Context, readyCh chan<- struct{}) (err error)
```

--------------------------------

### Start Teranode with Delve

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/howto/developerSetup.md

Starts the application in headless mode to allow remote debugger attachment.

```bash
dlv exec ./teranode.run --headless --listen=:2345 --api-version=2 --accept-multiclient
```

--------------------------------

### Search Item Response Example

Source: https://github.com/bsv-blockchain/teranode/blob/main/ui/dashboard/docs/api/redoc-static.html

Example JSON response for a successful search item query.

```json
{  *   "item": "block",      *   "hash": "002afb88f2d9d0d49e6d37c12f7cf88d26a7bdbcc024954ba80acb187206d1b0",      *   "blockHash": "002afb88f2d9d0d49e6d37c12f7cf88d26a7bdbcc024954ba80acb187206d1b0"       }
```

--------------------------------

### Start Toxiproxy Services

Source: https://github.com/bsv-blockchain/teranode/blob/main/test/chaos/README.md

Initializes the required infrastructure services using Docker Compose.

```bash
# Start services including toxiproxy
docker compose -f compose/docker-compose-ss.yml up -d
```

--------------------------------

### Define base and context-specific configuration settings

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/references/settings.md

Examples of base settings and their corresponding context-dependent overrides using the configuration file syntax.

```text
DATABASE_URL = "database-url-default.com"
```

```text
DATABASE_URL.dev.newenvironment1 = "database-url-environment1"
```

```text
DATABASE_URL.dev = "database-url-dev.com"
```

--------------------------------

### Install Dependencies in Virtual Environment

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/howto/developerSetup.md

Upgrade pip and install PyYAML within the active virtual environment.

```bash
python -m pip install --upgrade pip
pip install PyYAML
```

--------------------------------

### Setup Python Virtual Environment

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/howto/developerSetup.md

Create and activate a virtual environment to avoid system-wide package conflicts.

```bash
python3 -m venv ~/my_python_env     # choose any path you like
source ~/my_python_env/bin/activate
```

--------------------------------

### Manage Server Lifecycle

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/references/services/p2p_reference.md

Methods for initializing, starting, and gracefully stopping the server operations.

```go
func (s *Server) Init(ctx context.Context) (err error)
```

```go
func (s *Server) Start(ctx context.Context, readyCh chan<- struct{}) error
```

```go
func (s *Server) Stop(ctx context.Context) error
```

--------------------------------

### Initialize Default Settings

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/references/teranodeDaemonReference.md

Initializes settings with generic defaults, suitable for test environments.

```go
tSettings := settings.NewSettings() // This reads gocore.Config and applies sensible defaults
```

--------------------------------

### Start Service Operations

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/references/services/blockchain_reference.md

Launches core components including Kafka, HTTP, and gRPC servers, signaling readiness via the provided channel.

```go
func (b *Blockchain) Start(ctx context.Context, readyCh chan<- struct{}) error
```

--------------------------------

### Setup Docker Nodes for Testing

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/references/testingTechnicalReference.md

Initializes the Docker Compose environment and configures test-specific settings.

```go
func (t *TeranodeTestEnv) SetupDockerNodes() error {
    // Set up Docker Compose environment with provided settings
    // Create test directory for test-specific data
    // Configure environment settings including TEST_ID
    // Set up shared storage client for local docker compose
    // Initialize teranode and legacy node configurations
}
```

--------------------------------

### Install PyYAML via pipx

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/howto/developerSetup.md

Alternative method to install PyYAML using pipx for standalone CLI tools.

```bash
brew install pipx
pipx install PyYAML
```

--------------------------------

### Skip Services at Startup

Source: https://github.com/bsv-blockchain/teranode/blob/main/compose/MULTINODE.md

Commands to launch a multinode stack while omitting specific services, and how to materialize those services later.

```bash
# Node 2 comes up without block assembly; node 3 without validator
compose/multinode.sh up 3 -allinone=0 --skip 2:blockassembly --skip 3:validator

# Materialise a skipped service later (uses `compose up -d` so it works even
# though the container was never created during the initial up)
compose/multinode.sh chaos start 2 blockassembly
```

--------------------------------

### Run

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/references/services/blockchain_reference.md

Transitions the FSM to the RUNNING state.

```go
func (b *Blockchain) Run(ctx context.Context, _ *emptypb.Empty) (*emptypb.Empty, error)
```

--------------------------------

### Quick Start Multinode Network

Source: https://github.com/bsv-blockchain/teranode/blob/main/compose/MULTINODE.md

Commands to build, start, interact with, and tear down a local multinode teranode network.

```bash
# Build the teranode image first (if not already built)
make build

# Start a 5-node network
compose/multinode.sh up 5

# Generate blocks
compose/multinode.sh generate 1,10    # 10 blocks on node 1
compose/multinode.sh generate 1,5 3,5 # 5 blocks on node 1, then 5 on node 3

# Open all dashboards
compose/multinode.sh dashboards

# Check status
compose/multinode.sh status

# Tail logs for a specific node
compose/multinode.sh logs 2

# Tear down
compose/multinode.sh down
```

--------------------------------

### Pruner Service Log Output Example

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/references/services/pruner_reference.md

Example log entries demonstrating service lifecycle, phase execution, and error reporting.

```text
INFO  [Pruner] Service initialized successfully
INFO  [Pruner] Subscribed to BlockPersisted notifications
INFO  [Pruner] Subscribed to Block notifications (fallback)
DEBUG [Pruner] Received BlockPersisted notification for height 12345
INFO  [PreserveParents] Starting parent preservation for height 12345
INFO  [PreserveParents] Preserved 42 parent transactions
INFO  [AerospikeCleanupService] Starting DAH pruning for height 12345
INFO  [AerospikeCleanupService] Deleted 1000 UTXO records
INFO  [Pruner] Pruning completed successfully for height 12345
WARN  [Pruner] Pruning skipped: Block Assembly not running
ERROR [PreserveParents] Failed to preserve parent transaction: CRITICAL - aborting pruning
```

--------------------------------

### Access store and client instances

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/references/teranodeDaemonReference.md

Methods for retrieving or initializing singleton stores and clients within the daemon.

```go
func (d *Stores) GetTxStore(logger ulogger.Logger, appSettings *settings.Settings) (blob.Store, error)
```

```go
func (d *Stores) GetUtxoStore(ctx context.Context, logger ulogger.Logger, appSettings *settings.Settings) (utxostore.Store, error)
```

```go
func (d *Stores) GetBlockStore(ctx context.Context, logger ulogger.Logger, appSettings *settings.Settings) (blob.Store, error)
```

```go
func (d *Stores) GetSubtreeStore(ctx context.Context, logger ulogger.Logger, appSettings *settings.Settings) (blob.Store, error)
```

```go
func (d *Stores) GetBlockPersisterStore(ctx context.Context, logger ulogger.Logger, appSettings *settings.Settings) (blob.Store, error)
```

```go
func (d *Stores) GetTempStore(ctx context.Context, logger ulogger.Logger, appSettings *settings.Settings) (blob.Store, error)
```

```go
func (d *Stores) GetBlockchainClient(ctx context.Context, logger ulogger.Logger, appSettings *settings.Settings, source string) (blockchain.ClientI, error)
```

```go
func (d *Stores) GetValidatorClient(ctx context.Context, logger ulogger.Logger, appSettings *settings.Settings) (validator.Interface, error)
```

--------------------------------

### Start SSH Agent

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/references/gitCommitSigningSetupGuide.md

Initializes the ssh-agent process.

```bash
ssh-agent
```

--------------------------------

### Start Teranode in development mode

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/howto/submitting_transactions.md

Use this command to initialize the Teranode environment for local development.

```bash
# Start Teranode in development mode
SETTINGS_CONTEXT=dev make dev-teranode
```

--------------------------------

### GET /stats

Source: https://github.com/bsv-blockchain/teranode/blob/main/ui/dashboard/docs/api/redoc-static.html

Request general network statistics.

```APIDOC
## GET /stats

### Description
Request general network stats.

### Method
GET

### Endpoint
/stats
```

--------------------------------

### Initialize Node Configuration

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/references/services/alert_reference.md

Creates a new instance of the Node interface with specified dependencies.

```go
func NewNodeConfig(logger ulogger.Logger, blockchainClient blockchain.ClientI, utxoStore utxo.Store, blockassemblyClient blockassembly.ClientI, peerClient peer.ClientI, p2pClient p2p.ClientI, tSettings *settings.Settings) config.NodeInterface
```

--------------------------------

### Initialize Service State

Source: https://github.com/bsv-blockchain/teranode/blob/main/docs/references/services/blockassembly_reference.md

Prepares the service by creating the assembler instance and subscribing to blockchain notifications.

```go
func (ba *BlockAssembly) Init(ctx context.Context) (err error)
```