---
id: teal-source-map-decoder
title: TEAL source-map decoder
abstract: Add a parser for the source-map produced by algod TEAL compile with sourcemap=true to satisfy sourcemap.feature.
status: accepted
date: 2026-05-18
deciders: []
tags: []
---
# TEAL source-map decoder
## Status
Accepted
## Context
Algod's `POST /v2/teal/compile?sourcemap=true` response includes a
`sourcemap` object using the V3 Source Map format (the same shape as
JavaScript source maps: `version`, `sources`, `names`, `mappings`,
`sourceRoot`, `file`). The features that rely on this are:
- `tests/features/unit/sourcemap.feature` — six scenarios that parse a
fixture and assert line-by-line mappings, including reverse lookups
(PC → source line, source line → PC).
- `tests/features/integration/compile.feature` (one scenario:
*"I compile a teal program with mapping enabled"* — followed by
*"the resulting source map is the same as the json `<sourcemap>`"*).
- `tests/features/unit/dryrun_trace.feature` — overlays source-map
positions onto dryrun trace results.
The Rust SDK does not currently expose a source-map type. The
autogenerated `TealCompile200Response` includes the raw `sourcemap`
field as `serde_json::Value`, leaving parsing entirely to the caller.
## Decision
1. Introduce `algonaut_abi::sourcemap` (or a new tiny crate
`algonaut_sourcemap` if cross-cutting feels cleaner) with:
- `SourceMap` struct mirroring the V3 spec.
- `SourceMap::from_json(&str)` / `::from_value(serde_json::Value)`.
- `pc_to_line(pc: usize) -> Option<usize>` and
`line_to_pcs(line: usize) -> Vec<usize>` accessors.
- VLQ decoding for the `mappings` string (each segment is `[generated
column, source index, source line, source column, name index?]`).
2. Update `Algod::teal_compile` to expose a typed
`CompiledTealWithMap` when callers opt in, while preserving the
existing `CompiledTeal` shape for the default case.
3. Cover the parser with the algorand-sdk-testing fixtures shipped in
`tests/features/resources/`.
## Consequences
- `sourcemap.feature`, the mapping-enabled `compile.feature` scenario,
and `dryrun_trace.feature` become runnable.
- The SDK gains a small, broadly useful primitive — TEAL source maps
are also handy for downstream tooling (debuggers, IDE plugins).
- Adds one new module / crate to maintain; the VLQ decoder is small
(well under 200 LOC) so the maintenance cost is modest.