---
# System prepended metadata

title: 'Summary of MR https://gitlab.com/tezos/tezos/-/merge_requests/2291'

---

# Summary of MR https://gitlab.com/tezos/tezos/-/merge_requests/2291

- Make traces abstract
    - prevents empty traces from every being created
    - paves the way to more structured traces (to `error trace ≠ error list`)
    - paves the way to never-matching on traces (see long-term goals in conclusion)
- Introduce recovery primitives
    - only matches on top error (in current implementation, may match on all top errors of parallel traces in the future)
    - `salvage`: partial recovery via a partial function over errors (function returns option)
    - `recover`: total recovery via a partial function over errors (same as salvage) and a fallback/wildcard function over traces
    - `_s`, `_e`, and `_es` variants for lwt and error-monad integration
- Adapt the parts of the code that matched on traces to use the primitives

# Typical use

Code that used to look like

```ocaml 
match foo x y with
| Ok v -> Ok v
| Error (E1 :: _) -> Ok w
| Error (E2 :: _) -> Ok vv
| Error trace -> Error trace
```

is now written

```ocaml 
foo x y |> salvage
(function
| E1 -> Some w
| E2 -> Some vv
| _ -> None)
```

and code that looked like

```ocaml 
match foo x y with
| Ok v -> Ok v
| Error (E1 :: _) -> Ok w
| Error (E2 :: _) -> Ok vv
| Error trace -> emit trace; Ok u
```

is now written

```ocaml 
foo x y |> recover
(function
| E1 -> Some w
| E2 -> Some vv
| _ -> None)
(fun trace -> emit trace; Ok u)
```

More advanced uses are also possible but the correspondence is less trivial. E.g., when the full trace is also used within an error-specific recovery.


# Ideas & Discussions

- introduce `salvage` and `recover` already deprecated
    - to indicate that they are meant to disappear eventually
    - to encourage people not to use them

- order of arguments? labels?


# Aims

- long term: no matching on tzresult at all
    - tzresult is fully abstract, not even the `Ok`/`Error` destruction is possible
    - functions return concrete values for anything that is recoverable
    - most functions use `trace`/`record_trace` in order to make the eventual dumping of trace more informative
- medium term: use the `recover` / `salvage` approach
    - find a way to heavily discourage their use
        - via naming (`unsafe_recover`, `do_not_use_recover`)?
        - via deprecation? (disable warning locally when we use it for now)
    - add the "proper way" i.e. fully abstract tzresult and new code uses it
    - organise a "remove your error matching" sprint/hackaton/whatever
- short term: improve design of `recover`/`salvage`
    - naming, parameter order, etc.
    - more primitives? fewer primitives?