Add CAP-0082 - checked 256-bit integer arithmetic

[jayz22]

Discussion: https://github.com/orgs/stellar/discussions/1834

[Copilot]

Pull request overview

This PR introduces CAP-0082, which proposes adding checked variants of the existing 256-bit integer arithmetic host functions in the Soroban smart contract environment. The CAP addresses a limitation where the current arithmetic functions trap on overflow, preventing contracts from gracefully handling arithmetic errors that are common in financial mathematics. The proposal adds eight new host functions that return Void on overflow instead of trapping, following the pattern of Rust's checked_* methods.

Changes:

• Adds CAP-0082 specification document proposing eight new checked arithmetic host functions for 256-bit integers
• Functions cover addition, subtraction, multiplication, and exponentiation for both unsigned (U256) and signed (I256) types
• Functions return Val (either the result or Void on overflow) instead of trapping, enabling graceful error handling

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[leighmcculloch]

Some clarification is needed inline in the env.json. See inline comment.

Can you update the readme as well?

Looks great otherwise 👍🏻

[jayz22]

Some clarification is needed inline in the env.json. See inline comment.

Can you update the readme as well?

Looks great otherwise 👍🏻

done!