π Propagation Service
Index
- Description
- Functionality
- gRPC Protobuf Definitions
- Data Model
- Technology
- Directory Structure and Main Files
- How to run
- Configuration options (settings flags)
- Other Resources
1. Description
The Propagation Service is designed to handle the propagation of transactions across a peer-to-peer Teranode network.
At a glance, the Propagation service:
- Receives new transactions through various communication methods.
- Stores transactions in the tx store.
- Sends the transaction to the Validator service for further processing.

The gRPC protocol is the primary communication method, although HTTP is also accepted.
The service accepts transactions on three ingress transports. Start (services/propagation/Server.go) starts each one from its own setting:
| Transport | Setting | Code default | settings.conf | Access controls |
|---|---|---|---|---|
| gRPC | propagation_grpcListenAddress | empty | :${PROPAGATION_GRPC_PORT} | Ban list interceptor; gRPC security level (security_level_grpc) |
HTTP (/tx, /txs) | propagation_httpListenAddress | empty (off) | :${PROPAGATION_HTTP_PORT} (on) | Ban list middleware; rate limit (propagation_httpRateLimit, default 1024 per second); body limit (propagation_httpBodyLimit, default 100MB) |
| UDP6 multicast | ipv6_addresses, on the interface in ipv6_interface (default en0) | empty (off) | not set (off) | Source allowlist only (propagation_ipv6_allowed_sources; empty accepts every source) |
The gRPC server is the call that holds the service open, so the service always starts it. HTTP and UDP6 start only when their setting is not empty. The UDP6 listener binds port 9999 on each configured multicast address and reads datagrams of at most 512 bytes. It has no ban list and no rate limit. Its only control is the source allowlist, so set propagation_ipv6_allowed_sources when UDP6 is on.
startHTTPServer: This function is designed to start a network listener for the HTTP protocol. Each function configures and starts a server to listen for incoming connections and requests on specific network addresses and ports. For example, the HTTP endpoints are/tx,/txs, and/health.
A node can start multiple parallel instances of the Propagation service. This translates into multiple pods within a Kubernetes cluster. Each instance will have its own gRPC server, and will be able to receive and propagate transactions independently. GRPC load balancing allows to distribute the load across the multiple instances.

Notice that the Validator, as shown in the diagram above, can be either a local validator or a remote validator service, depending on the Node configuration. To know more, please refer to the Transaction Validator documentation.
Also, note how the Blockchain client is used in order to wait for the node State to change to RUNNING state. For more information on this, please refer to the State Management documentation.
2. Functionality
2.1. Starting the Propagation Service
Upon startup, the Propagation service starts the relevant communication channels, as configured via settings.
2.1.1 Validator Integration
The Propagation service can work with the Validator in two different configurations:
-
Local Validator:
- When
useLocalValidator=true - The Validator is instantiated directly within the Propagation service
- Direct method calls are used without network overhead
- Recommended for single-machine deployments or development/testing
- When
-
Remote Validator Service:
- When
useLocalValidator=false - The Propagation service connects to a separate Validator service via gRPC
- Recommended for production distributed deployments (allows independent scaling)
- Has higher latency due to additional network calls
- When
This configuration is controlled by the settings passed to GetValidatorClient() in daemon.go.
Note: For detailed information about how services are initialized and connected during daemon startup, see the Teranode Daemon Reference.
2.2. Propagating Transactions
All communication channels receive txs and delegate them to the ProcessTransaction() function. The main communication channels are shown below.
HTTP:
gRPC:
2.3. Transaction Processing Workflow
The transaction processing involves several steps to ensure proper validation and propagation:
-
Initial Validation: Each transaction is validated for correct format and to ensure itβs not a coinbase transaction.
-
Storage: Valid transactions are stored in the transaction store using the transaction hash as the key.
-
Validation Submission: Transactions are submitted to the validator service through one of two channels:
- Kafka: Normal-sized transactions are sent to the validator through Kafka for asynchronous processing.
- HTTP Fallback: Large transactions exceeding Kafka message size limits are sent directly to the validatorβs HTTP endpoint.
Format Handling
The Propagation Service is format-agnostic and handles transaction formats flexibly:
- Accepts both formats: Standard Bitcoin format and Extended Format (BIP-239) transactions
- No format validation at ingress: Transactions are not rejected based on their format
- Storage preserves received format: Transactions are initially stored as received in the blob store
- Format handling delegation: The actual format conversion and extension is handled downstream by the Validator Service
This design ensures:
- Maximum compatibility with diverse wallet implementations (from legacy to modern)
- No format-based rejection at the network edge
- Flexible deployment supporting both traditional Bitcoin clients and BIP-239 aware applications
- Backward compatibility with the broader Bitcoin ecosystem
The Propagation Service focuses on efficient transaction ingress and distribution, delegating format-specific processing to the appropriate downstream services.
2.4. Error Handling
The Propagation Service implements comprehensive error handling:
- Transaction Format Errors: Malformed transactions are rejected with appropriate error messages.
- Storage Failures: If transaction storage fails, the error is logged and propagated to the client.
- Validation Errors: Errors during validation are captured and returned to the client.
- Batch Processing: When processing transaction batches, each transaction is handled independently, allowing some transactions to succeed even if others fail.
- Request Limiting: Implements limits on transaction size and batch counts to prevent resource exhaustion.
3. gRPC Protobuf Definitions
The Propagation Service uses gRPC for communication between nodes. The protobuf definitions used for defining the service methods and message formats can be seen in the propagationProto.md documentation.
4. Data Model
The Propagation Service accepts transactions in multiple formats:
- Transaction Data Model: Comprehensive guide covering both standard Bitcoin format and Extended Format (BIP-239), including how Teranode handles format conversion and storage.
5. Technology
Main technologies involved:
-
Go Programming Language (Golang):
- The entire service is written in Go.
-
Peer-to-Peer (P2P) Networking:
- The service is designed for a P2P network environment, where nodes (computers) in the network communicate directly with each other without central coordination.
- Transaction propagation uses gRPC (via protobuf API), HTTP (via Echo framework), and raw UDP for IPv6 multicast propagation.
-
Networking Protocols (HTTP)
-
Cryptography:
- The use of
cryptopackages for RSA key generation and TLS (Transport Layer Security) configuration for secure communication.
- The use of
-
gRPC and Protocol Buffers:
- gRPC, indicated by the use of
google.golang.org/grpc, is a high-performance, open-source universal RPC framework. It uses Protocol Buffers as its interface definition language.
- gRPC, indicated by the use of
6. Directory Structure and Main Files
./services/propagation
β
βββ Client.go - Contains the client-side logic for interacting with the propagation service.
βββ ClientInterface.go - Defines the client interface for the propagation service.
βββ Client_test.go - Unit tests for the Client.go functionality.
βββ Server.go - Contains the main server-side implementation for the propagation service.
βββ Server_test.go - Unit tests for the Server.go functionality.
βββ client_large_tx_fallback_test.go - Tests the large transaction fallback mechanism in the client.
βββ http_handlers_test.go - Unit tests for HTTP handler functions.
βββ large_tx_fallback_test.go - Tests for the large transaction fallback mechanism.
βββ metrics.go - Metrics collection and monitoring of the propagation service.
βββ propagation_error_test.go - Unit tests for error handling in the propagation service.
βββ propagation_api - Directory containing various files related to the API definition and implementation of the propagation service.
βββ propagation_api.pb.go - Auto-generated file from protobuf definitions, containing Go bindings for the API.
βββ propagation_api.proto - Protocol Buffers definition file for the propagation API.
βββ propagation_api_grpc.pb.go - gRPC (Google's RPC framework) specific implementation file for the propagation API.7. How to run
To run the Propagation Service locally, you can execute the following command:
SETTINGS_CONTEXT=dev.[YOUR_CONTEXT] go run . -propagation=1Please refer to the Locally Running Services Documentation document for more information on running the Propagation Service locally.
8. Configuration options (settings flags)
For comprehensive configuration documentation including all settings, defaults, and interactions, see the Propagation Settings Reference.