macula_bolt4 (macula v3.13.0)

View Source

BOLT#4-style error taxonomy for CALL failures (Part 4 §6.1).

Adapted from Lightning Network's BOLT#4 onion-failure codes, which have proven in adversarial conditions that a small, specific taxonomy prevents retry loops and enables post-mortem. Every CALL ERROR frame carries one of these 16 codes plus the reporting station's signature so downstream hops cannot forge "not my fault".

The retry policy column is advisory — the caller's CALL state machine (Phase 4 §6.2 / §6.4) is the actual decision point. Codes are stable across V2 minor versions; new codes append at the next free integer.

Reference: plans/PLAN_MACULA_V2_PART4_LIFECYCLE.md §6.1; plans/PLAN_MACULA_V2_PART6_PROTOCOL.md §13.

Summary

Types

code/0
info/0
name/0
retry_policy/0

Functions

code(Name)

Resolve a name to its integer code.

info(NameOrCode)

Full info entry for a given name or code.

is_retryable(NameOrCode)

Whether the spec's recommended retry policy permits a retry at all. none (success), application (handler-level remedy), and crypto_drop (security-critical) are all non-retryable.

name(Code)

Resolve an integer code to its symbolic name.

table()

The complete 16-entry table. Order is by code.

Types

code/0

-type code() :: 0..15.

info/0

-type info() :: #{code := code(), name := name(), retry := retry_policy()}.

name/0

-type name() ::
          ok | unknown_next_peer | temporary_relay_failure | relay_disabled |
          node_not_found_at_target_relay | target_realm_refused | loop_detected | expiry_too_soon |
          upstream_congestion | invalid_path_header | crypto_puzzle_invalid |
          realm_not_authoritative_here | tombstoned | payload_too_large | signature_invalid |
          unknown_error.

retry_policy/0

-type retry_policy() ::
          none | different_path | same_path_after_backoff | application | crypto_drop |
          caller_recompute | caller_recompute_with_lookup | caller_extends_deadline |
          exponential_backoff | log_and_caution.

Functions

code(Name)

-spec code(name()) -> code().

Resolve a name to its integer code.

info(NameOrCode)

-spec info(name() | code()) -> info().

Full info entry for a given name or code.

is_retryable(NameOrCode)

-spec is_retryable(name() | code()) -> boolean().

Whether the spec's recommended retry policy permits a retry at all. none (success), application (handler-level remedy), and crypto_drop (security-critical) are all non-retryable.

name(Code)

-spec name(code()) -> name().

Resolve an integer code to its symbolic name.

table()

-spec table() -> [info()].

The complete 16-entry table. Order is by code.