Reason codes Configuración Eventos de share Límites de seguridad

VELDRA · REFERENCIA PARA OPERADORES

Documentación

Cada reason code, cada parámetro de configuración, cada campo de evento que cruza un límite de Veldra. Una sola página. Extraído de los tipos de autoridad en Rust de reservegrid-common.

Reason codes

91 Phase 1 · 4 Phase 2

Claves de config

policy.toml + gateway.toml

Categorías

verifier · gateway · share · …

Eventos de share

share_accepted · forward_result

§ 1 · Reason codes

95 códigos que la pasarela puede emitir.

Cada rechazo, cada degradación, cada fallo interno lleva un identificador estable en snake_case. Son la unión de ReasonCode del verificador, la pasarela, el transporte, la ruta de shares y el Invariant Shield. Estables entre versiones menores; los códigos nuevos solo se añaden en versiones aditivas.

95 CODES

protocol_version_mismatch

Template protocol version does not match expected

Policy de templates

invalid_prev_hash

Template prev_hash is not 32 bytes or does not parse

Policy de templates

prev_hash_len_mismatch

Wire prev_hash length differs from header expectation

Policy de templates

coinbase_value_zero_rejected

Coinbase output value is zero and policy rejects it

Policy de templates

empty_template_rejected

Template contains zero non-coinbase transactions

Policy de templates

tx_count_exceeded

Template tx count exceeds policy maximum

Policy de templates

total_fees_below_minimum

Sum of fees below configured minimum

Policy de templates

avg_fee_below_minimum

Average fee per vByte below configured minimum

Policy de templates

policy_load_error

policy.toml could not be parsed or violates schema

Policy de templates

mempool_backend_unavailable

Phase 2 RPC backend unreachable; verifier degrades to Phase 1

Policy de templates

weight_ratio_exceeded

Template weight ratio exceeds policy maximum

Policy de templates

template_stale

Template age exceeds max_template_age_ms

Policy de templates

sigops_budget_warning

Sigops within block budget but ratio above warn threshold

Policy de templates

coinbase_sigops_abnormal

Coinbase script sigops count is abnormally high

Policy de templates

v2_invariant_coinbase_value_mismatch

Re-derived coinbase value disagrees with declared total

Fase 1 (S+D)

v2_invariant_template_weight_mismatch

Re-derived template weight differs from declared

Fase 1 (S+D)

v2_invariant_merkle_root_mismatch

Re-derived merkle root does not match block header

Fase 1 (S+D)

v2_invariant_witness_commitment_missing

Block has segwit txs but no witness commitment output

Fase 1 (S+D)

v2_invariant_witness_commitment_mismatch

Witness commitment output does not match witness root

Fase 1 (S+D)

v2_invariant_sigops_mismatch

Re-derived total sigops disagrees with declared

Fase 1 (S+D)

v2_invariant_coinbase_sigops_mismatch

Re-derived coinbase sigops disagrees with declared

Fase 1 (S+D)

v2_invariant_tx_count_mismatch

Re-counted txs disagrees with declared count

Fase 1 (S+D)

v2_invariant_coinbase_script_length

Coinbase script length outside protocol bounds (2..=100 bytes)

Fase 1 (S+D)

v2_invariant_coinbase_output_count

Coinbase output count is zero

Fase 1 (S+D)

v2_invariant_coinbase_bip34_missing

Coinbase script lacks BIP-34 height push

Fase 1 (S+D)

v2_invariant_coinbase_height_mismatch

BIP-34 height in coinbase ≠ declared template height

Fase 1 (S+D)

v2_invariant_weight_exceeds_max

Template weight exceeds 4 000 000 (consensus max)

Fase 1 (S+D)

v2_invariant_sigops_exceed_max

Template sigops exceed 80 000 (consensus max)

Fase 1 (S+D)

v2_invariant_nontcb_null_prevout

Non-coinbase transaction has a null prevout

Fase 1 (S+D)

v2_invariant_header_version_low

Block header version below BIP-34 minimum (2)

Fase 1 (S+D)

v2_invariant_duplicate_tx

Duplicate txid present in template

Fase 1 (S+D)

v2_invariant_decode_failed

Could not decode raw transaction bytes

Fase 1 (S+D)

v2_invariant_mempool_tx_unknown

Phase 2: template tx not present in operator mempool snapshot

Fase 2 (M)

v2_invariant_mempool_tolerance_exceeded

Phase 2: unknown-tx ratio exceeds [policy.mempool] tolerance_pct

Fase 2 (M)

v2_invariant_mempool_unavailable

Phase 2: bitcoind RPC unavailable; degraded to Phase 1

Fase 2 (M)

v2_invariant_mempool_view_stale

Phase 2: mempool snapshot age exceeds max_stale_secs

Fase 2 (M)

auth_failed

API key or HMAC signature did not validate

Operacional

unsupported_algorithm

Auth or signing algorithm unknown to this build

Operacional

rate_limited

Caller exceeded RPS quota for this endpoint

Operacional

payload_too_large

Body exceeds max_payload_bytes

Operacional

invalid_content_type

Content-Type does not match expected media

Operacional

payload_unknown_field

JSON payload contains an unknown field (strict deserializer)

Operacional

payload_field_out_of_range

Numeric field outside accepted bounds

Operacional

payload_malformed

Body could not be parsed as JSON

Operacional

payload_nesting_exceeded

JSON nesting exceeds the parser ceiling

Operacional

request_expired

Signed request timestamp outside replay window

Operacional

request_replayed

Request HMAC matches a previously-seen one

Operacional

handler_timeout

Handler exceeded handler_timeout_ms before responding

Operacional

config_invalid

Config file failed validation at startup

Operacional

internal_line_too_large

Internal NDJSON message exceeded MAX_INTERNAL_LINE_BYTES (1 MiB)

Operacional

internal_framing_error

Internal NDJSON message could not be parsed

Operacional

internal_version_mismatch

Internal msg_type version not supported

Operacional

internal_unknown_msg_flood

Unknown msg_type exceeded MAX_UNKNOWN_MSG_TYPE_PER_MINUTE

Operacional

noise_handshake_failed

Noise NX handshake did not complete

SV2 + Conexión

noise_handshake_timeout

Handshake exceeded handshake_timeout_ms

SV2 + Conexión

unsupported_protocol_version

Miner offered unsupported SV2 protocol version

SV2 + Conexión

frame_decode_error

SV2 binary frame could not be decoded

SV2 + Conexión

frame_too_large

Frame exceeded maximum allowed size

SV2 + Conexión

connection_rate_limited

Inbound connections exceeded per-IP rate limit

SV2 + Conexión

peer_quota_exceeded

Peer exceeded rate_limit_messages_per_sec or _bytes_per_sec

SV2 + Conexión

miner_unauthorized

Miner credentials did not validate against whitelist

Autorización de mineros

identity_prefix_unmatched

Worker identity prefix not in pool's expected list

Autorización de mineros

identity_too_long

Worker identity longer than max_worker_id_bytes

Autorización de mineros

channel_open_rejected

OpenMiningChannel denied (mapped to SV2 error)

Ciclo de vida

channel_limit_exceeded

Connection exceeded max_channels_per_connection

Ciclo de vida

invalid_channel_id

Channel ID not recognized for this connection

Ciclo de vida

extended_channel_unsupported

Extended channel requested; this build only supports standard channels

Ciclo de vida

prevhash_switch_timeout

Prevhash verdict not received within prevhash_verdict_timeout_ms

Template + Prevhash

prevhash_verdict_rejected

Prevhash verdict was 'reject'; gateway fail-closed

Template + Prevhash

template_cache_miss

Job references a template the gateway no longer has

Template + Prevhash

stale_job_submission

Submission references a job from a prior prevhash epoch

Template + Prevhash

upstream_unavailable

Template source (template-manager) not reachable

Template + Prevhash

missing_gateway_signature

Share posted without HMAC header

HMAC

malformed_gateway_signature

HMAC header could not be decoded

HMAC

malformed_event_id

Event ID is not a valid v7 ULID/UUID

HMAC

invalid_gateway_signature

HMAC signature did not validate against gateway key

HMAC

share_replay_detected

Share event_id matches a recently-seen one (dedup window)

Validación de share

share_difficulty_below_target

Submitted difficulty below configured minimum

Validación de share

share_invalid_job_id

Submission references unknown job ID

Validación de share

share_invalid_nonce

Header bytes hash does not satisfy share difficulty

Validación de share

version_bit_violation

version_bits outside BIP-320 general purpose mask

Validación de share

ntime_out_of_range

Submitted ntime outside template-allowed window

Validación de share

share_forward_failed

Could not POST share to upstream within retry budget

Validación de share

share_upstream_rejected

Upstream (pool/template-manager) returned a non-2xx status

Validación de share

share_dropped_queue_full

Outbound share queue at capacity; backpressure policy = drop

Validación de share

share_evicted_from_queue

Share evicted by newer entry under FIFO eviction

Validación de share

share_rate_limited

Per-account share rate exceeded pool_account_rate_limit

Validación de share

process_crash_recovery

Synthetic forward result for shares orphaned by a crash

Recuperación tras crash

wal_write_failure

WAL append failed; gateway shutting down to preserve durability

Recuperación tras crash

peer_transport_error

Peer TCP connection dropped or transport I/O error

SV2 + Conexión

channel_open_timeout

Peer did not OpenMiningChannel within channel_open_timeout_ms

Ciclo de vida

setup_connection_rejected

SV2 SetupConnection exchange failed

SV2 + Conexión

shutdown_drain

Gateway is draining connections during graceful shutdown

Sonda de health

startup_pending

Gateway has not completed startup initialization

Sonda de health

internal_error

Catch-all for unexpected internal failures

Sistema

§ 2 · Configuración

69 claves repartidas entre policy.toml + gateway.toml.

Validadas en el arranque. Los valores inválidos provocan un fail-closed con config_invalid. El bloque mempool de la Fase 2 se activa de forma explícita; el despliegue por defecto solo ejecuta la Fase 1.

policy.toml · [policy] · 12

Clave	Tipo	Default	Descripción
protocol_version	u16	2	Highest accepted TemplatePropose protocol_version.
required_prevhash_len	usize	64	Required prev_hash length in hex characters.
min_total_fees	u64	0	Minimum sum of fees in a template (sats).
max_tx_count	u32	10000	Maximum non-coinbase transactions per template.
low_mempool_tx	u64	50	Below this mempool tx count the low fee tier applies.
high_mempool_tx	u64	500	At or above this mempool tx count the high fee tier applies.
min_avg_fee_lo	u64	0	Minimum average fee per tx, low tier (sats).
min_avg_fee_mid	u64	0	Minimum average fee per tx, mid tier (sats).
min_avg_fee_hi	u64	0	Minimum average fee per tx, high tier (sats).
reject_empty_templates	bool	true	Reject templates with zero non-coinbase transactions.
reject_coinbase_zero	bool	false	Reject templates whose coinbase value is zero.
unknown_mempool_as_high	bool	true	Treat an unknown mempool size as the high fee tier.

policy.toml · [policy.safety] · 6

Clave	Tipo	Default	Descripción
max_weight_ratio	f64	0.999	Maximum template weight as a fraction of the 4M weight cap.
enforce_weight_ratio	bool	false	Reject, not just warn, when the weight ratio is exceeded.
max_template_age_ms	u64?	unset	Reject templates older than this; unset disables the check.
enforce_template_age	bool	false	Reject, not just warn, when a template exceeds max_template_age_ms.
warn_sigops_ratio	f64	0.95	Warn above this fraction of the consensus sigops cap.
warn_coinbase_sigops_max	u32	400	Warn when coinbase sigops exceed this count.

policy.toml · [policy.mempool] · 8

Clave	Tipo	Default	Descripción
enforce	bool	false	Gate templates on the Class M mempool check (inline mode only).
tolerance_pct	f64	4.0	Max percent of template txs allowed to be unknown to the mempool view.
poll_interval_secs	u64	10	Interval between bitcoind getrawmempool polls.
max_stale_secs	u64	60	Mempool view age before it degrades and Class M abstains.
per_tx_detail	bool	false	Expand rejection detail to list every unknown txid.
rpc_url	string	—	bitcoind JSON-RPC URL.
rpc_user	string	—	bitcoind RPC username.
rpc_pass	string	—	bitcoind RPC password (prefer VELDRA_BITCOIND_RPC_PASS env).

gateway.toml · (root) · 1

Clave	Tipo	Default	Descripción
mode	enum	inline	Deployment mode: inline \| observe \| shadow.

gateway.toml · [gateway] · 34

Clave	Tipo	Default	Descripción
listen_addr	string	0.0.0.0:3333	SV2 (Noise NX) miner-facing listener address.
health_addr	string	127.0.0.1:8080	HTTP health, metrics and events address.
noise_keypair_path	string	—	Path to the gateway Noise static keypair.
noise_cert_path	string	—	Path to the signed Noise certificate.
authority_pubkey	string	—	x-only authority public key miners verify.
max_connections	u32	1024	Global concurrent SV2 connection cap.
max_connections_per_ip	u32	16	Per-source-IP connection cap (0 = unlimited).
max_channels_per_conn	u32	256	Per-connection mining channel cap.
noise_cert_validity_secs	u32	3600	Noise certificate validity window.
noise_handshake_timeout_ms	u64	5000	Noise NX handshake timeout.
template_url	string	—	Template-manager base URL.
template_poll_interval_ms	u64	3000	Template-manager poll interval.
max_template_age_ms	u64	30000	Reject templates older than this at the gateway.
prevhash_verdict_timeout_ms	u64	2000	Max wait for a verifier verdict on a new block; warns below 1000.
prevhash_stale_hold_ms	u64	5000	Hold stale work this long before disconnecting miners.
upstream_stale_max_ms	u64	30000	Max upstream staleness before the fail policy acts.
upstream_failure_policy	enum	fail_closed	fail_closed \| fail_open on upstream loss.
job_retention_ms	u64	300000	How long jobs are retained for share validation.
ntime_elapsed_slack_seconds	u32	2	Tolerance for miner ntime drift (seconds).
max_shares_per_second_per_channel	u32	0	Per-channel share rate cap (0 = off).
channel_target_hex	string?	unset	Fixed channel difficulty target (regtest); unset = real difficulty.
extended_channels_enabled	bool	true	Accept OpenExtendedMiningChannel (0x13).
vardiff_enabled	bool	false	Enable variable-difficulty retargeting.
vardiff_target_shares_per_min	f64	20.0	Target share submission rate for vardiff.
vardiff_retarget_interval_secs	u64	90	Vardiff retarget interval.
vardiff_min_difficulty	u64	1	Vardiff difficulty floor.
vardiff_max_difficulty	u64	u64::MAX	Vardiff difficulty ceiling.
vardiff_max_adjustment_factor	f64	4.0	Max per-retarget vardiff change factor.
noise_keypair_reload_sighup	bool	true	Reload the Noise keypair on SIGHUP.
wal_path	string	—	Share write-ahead log path (empty = disabled).
wal_compaction_threshold	usize	1000	Completed-record count that triggers WAL compaction.
gateway_instance_id	string	$HOSTNAME	Stable instance ID for split-brain prevention and share tracing.
auto_degrade	bool	true	Auto inline-to-observe degradation on verifier heartbeat loss.
auto_degrade_after_ms	u64	10000	Heartbeat-loss window before auto-degrade.

gateway.toml · [verifier] · 4

Clave	Tipo	Default	Descripción
addr	string	—	Pool-verifier NDJSON TCP address.
health_probe_staleness_ms	u64	10000	Mark the verifier unhealthy after this silence.
reconnect_delay_ms	u64	2000	Delay between verifier reconnect attempts.
heartbeat_interval_ms	u64	5000	Verifier heartbeat interval.

gateway.toml · [share_upstream] · 4

Clave	Tipo	Default	Descripción
url	string	—	Upstream share-receiver endpoint.
retries	u32	2	Retry budget per share forward (5xx / timeout only).
forward_queue_size	usize	50000	Bounded outbound share-forward queue.
forward_max_in_flight	usize	256	Max concurrent in-flight share forwards.

§ 3 · Eventos de share

Dos eventos cruzan el límite de la pasarela.

La pasarela emite share_accepted en el momento en que un share se valida localmente, y share_forward_result cuando (y solo cuando) el pool aguas arriba lo confirma. Ambos van firmados con HMAC; ambos llevan un ULID v7 estable en event_id para deduplicar aguas abajo de forma segura frente a reenvíos.

share_accepted

v1 · EMITIDO locally after share passes nonce + difficulty + version-bits + ntime checks

Campo

Tipo

Descripción

event_id

string · v7 ULID

Stable identifier for dedup. Time-ordered.

account_id

string

Pool-side miner account.

worker_id

string

Sub-identity (e.g. rig name) ≤ max_worker_id_bytes.

channel_id

u32

SV2 channel ID this share arrived on.

job_id

u32

Template ID this share targets.

nonce

u32

Header nonce as submitted.

ntime

u32

Header ntime as submitted.

version_bits

u32

BIP-320 version-rolling bits.

share_difficulty

f64

Difficulty the share met.

template_difficulty

f64

Difficulty the underlying template targets.

block_solution

bool

True if this share also solves the block.

accepted_at

u64 · ms epoch

Gateway-side timestamp at validation.

template_height

u32

Block height of the template.

prev_hash

string · 64 hex

Header prev_hash; ties share to a chain epoch.

share_forward_result

v1 · EMITIDO after upstream accept/reject — or synthetically after crash recovery (process_crash_recovery)

Campo

Tipo

Descripción

event_id

string · v7 ULID

Same ULID as the original share_accepted.

forwarded_at

u64 · ms epoch

When the forward attempt completed.

status

enum

accepted | rejected | dropped | recovered

upstream_status_code

u16 · null

HTTP status from pool/template-manager.

upstream_reason

string · null

Pool-supplied reason (e.g. duplicate, low_diff).

reason_code

string · null

Veldra reason code if status ∈ {dropped, recovered}.

attempt_count

Number of upstream attempts (1..=forward_max_retries+1).

queue_age_ms

u64

Time the share spent in the outbound queue.

latency_ms

u64

Round-trip to upstream on the successful attempt.

TRANSPORT

Both events are POSTed as NDJSON over HTTPS to the configured [share].forward_url, with an HMAC-SHA256 signature in X-Veldra-Signature derived from the signing key at [hmac].share_signing_key_path. Missing or malformed signatures are rejected upstream with missing_gateway_signature / invalid_gateway_signature.

§ 4 · Límites de seguridad

En qué confía cada capa. Qué rechaza cada capa.

El argumento de seguridad de Veldra se construye capa por capa. Ninguna capa confía en la de abajo; cada una vuelve a derivar o a validar todo lo que reenvía. Esta página documenta el contrato; los modos de fallo en estos límites están catalogados en el Failure Atlas.

L0 · TRANSPORT

SV2 framing + Noise NX

Inbound peer is anonymous TCP until the Noise handshake completes. Until then, frames are size-capped, rate-limited per-IP, and subject to handshake timeout.

Rechaza:

Frames over max_frame_bytes
Handshakes past handshake_timeout_ms
Connections over connection_rate_per_ip_per_min
Unsupported SV2 protocol versions

L1 · GATEWAY

Authenticated channel + job routing

Past handshake, the miner authenticates via whitelist. Channels open subject to per-connection caps; each job is bound to a template ID and prevhash epoch.

Rechaza:

Unauthorized miners or stale identity prefixes
Channel-open requests for unsupported channel types
Submissions referencing unknown job_id
Submissions from prior prevhash epoch (past grace)

L2 · INVARIANT SHIELD

Re-derivation + cross-check

Every template — whether locally generated or upstream — is re-decoded and re-derived. Phase 1 checks structural invariants. Phase 2 (opt-in) cross-checks against bitcoind mempool.

Rechaza:

Mismatch on merkle root, witness commitment, sigops, weight
BIP-34 height mismatch or missing
Duplicate txids, null prevouts, undecodable txs
Phase 2: unknown-tx ratio over tolerance_pct

L3 · SHARE PATH

HMAC-signed, dedup'd, durable

Every share is locally validated, then signed with the gateway's HMAC key and queued to upstream. The WAL persists the queue across crashes; the dedup window catches replays.

Rechaza:

Shares below min_difficulty
Shares whose event_id matches one in the dedup window
Shares forwarded without an HMAC signature
Shares from accounts past pool_account_rate_limit

POSTURA POR DEFECTO

Todos los rechazos anteriores son fail-closed por defecto: el trabajo no se reenvía, el share no se acredita, el sistema aguas arriba nunca ve la entrada defectuosa. fail_closed = false solo está disponible en el Invariant Shield y está pensado para despliegues canary — no para producción.