Search documentation of macula

# macula_bolt4 (macula v4.4.9)

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.