Token Math Refactor — Closure Note

--- ring: token-math-refactor onyx: token-math-refactor-doc pearl: DRY refactor of .coin token math — superseded by things-economy architecture citrine: state: complete ---

# Token Math Refactor — Closure Note

The `token-math-refactor` FID addressed duplicated .coin token math across 10+ Vending Machine shell scripts. The solution was `sacred_token_math.sh` — a shared library providing common arithmetic for balance, transaction, and exchange operations.

## What Was Done

- `sacred_token_math.sh` extracted as shared library - Common operations: `add_tokens`, `subtract_tokens`, `validate_balance`, `format_coin` - Wallet scripts refactored to source the shared library instead of duplicating logic

## Superseded By

This FID is superseded by **things-economy** (`tec-008`), which moves .coin math entirely into the Things/Gems architecture and Portal Rust backend. The shell script layer becomes a thin wrapper.

The refactor was a necessary DRY pass on the legacy layer. As the things-economy architecture matures, `sacred_token_math.sh` itself becomes legacy.

## Status

Implementation complete for the shell script era. Ongoing coin math now targets the Portal API. Shell scripts remain for backwards compatibility and edge cases not yet migrated to things-economy.