Documentation
¶
Overview ¶
Package money is the ONE exact money value for the Hanzo cloud finance stack: a USD balance carried at 18-decimal (EVM/ERC-20) precision, so an off-chain ledger amount and an on-chain uint256 credit balance are THE SAME INTEGER — no conversion or rounding at the boundary. Every per-token AI price is represented and billed EXACTLY; there is no cent-flooring and no fractional-cent skim, at any scale.
The exact-number machinery (big.Int fixed-point, no float, no precision ceiling) is NOT reimplemented here — it lives ONCE in github.com/hanzoai/money + github.com/hanzoai/decimal, the shared money value for the whole stack. This package is the thin policy layer that pins the cloud's credit unit to 18-decimal USD and nothing else; it is the single place that decision lives.
An Amount is IMMUTABLE — every operation returns a new value — and the zero value is a valid 0.
Index ¶
- Constants
- type Amount
- func (a Amount) Add(b Amount) Amount
- func (a Amount) Atto() *big.Int
- func (a Amount) AttoString() string
- func (a Amount) Cents() int64
- func (a Amount) Cmp(b Amount) int
- func (a Amount) IsNeg() bool
- func (a Amount) IsZero() bool
- func (a Amount) MarshalJSON() ([]byte, error)
- func (a Amount) Neg() Amount
- func (a Amount) Sign() int
- func (a Amount) String() string
- func (a Amount) Sub(b Amount) Amount
- func (a *Amount) UnmarshalJSON(b []byte) error
Constants ¶
const Decimals = 18
Decimals is the fixed-point scale of the credit unit: 18 (the EVM/ERC-20 unit). The smallest representable amount is 10^-18 USD.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Amount ¶
type Amount struct {
// contains filtered or unexported fields
}
Amount is an exact USD credit value (18-decimal, big.Int-backed, immutable). It wraps the shared money.Amount, fixed to the credit unit.
func FromAtto ¶
FromAtto wraps a raw atto-USD magnitude — 18 decimals, the storage/on-chain form (the value an EVM uint256 credit balance holds). A nil magnitude is 0.
It is named for the UNIT it takes, not for its Go type. As FromInt it read as "make an Amount from an integer", and money.Amount.Minor() also returns an integer — so FromInt(x.Minor()) type-checked, read fine, and fed CENTS to an 18-decimal constructor, understating every zen debit by 10^16 until v1.801.44. FromAtto(x.Cents()) cannot read fine. A name that states the unit refuses the bug the type system cannot see.
func FromDecimal ¶
FromDecimal wraps an exact decimal USD value in the credit unit — the typed counterpart of ParseUSD, with no string round-trip. The decimal IS the value; the credit unit's 18 decimals are its storage scale, so nothing is rescaled and nothing is rounded here.
This is the ONE way to carry a value priced as a shared money.Amount (whose Currency may declare a COARSER minor unit — money.USD declares 2) into the credit unit. Take the decimal, never Amount.Minor(): Minor() rescales the value to the CURRENCY's minor unit, so an 18-dp value tagged money.USD comes back as CENTS, and cents fed to an 18-dp constructor understate by 10^16.
func ParseInt ¶
ParseInt parses a signed 18-decimal integer string (the storage/on-chain form). An empty string is 0.
func ParseUSD ¶
ParseUSD parses a decimal USD string ("6.60", "-0.00132", "100") to an EXACT Amount — no float. Up to 18 fractional digits are honored; more is an error rather than a silent truncation (we never quietly drop money).
func TokenCost ¶
TokenCost is the EXACT cost of n tokens at pricePerMillion USD/1M-tokens: n × price / 1e6, rounded half-away-from-zero at 10^-18 — so a bill is never floored to zero and never skims a fraction.
func (Amount) Add ¶
Add returns a + b. (The credit unit is fixed, so the shared add can never mismatch.)
func (Amount) Atto ¶
Atto returns a fresh big.Int of the atto-USD magnitude — 18 decimals, the on-chain uint256 value. The unit is in the name: this is NOT interchangeable with money.Amount.Minor(), which renders the CURRENCY's minor unit (money.USD declares 2, so it returns cents). Both are "an integer"; they differ by 10^16.
func (Amount) AttoString ¶
AttoString is the canonical STORAGE form: the signed atto-USD integer as a decimal string (exact, on-chain-identical, sortable at fixed width by the caller).
func (Amount) Cents ¶
Cents rounds the value to whole cents (half-away-from-zero) — a human/legacy display unit ONLY; never use it inside money math (it is lossy by construction).
func (Amount) MarshalJSON ¶
MarshalJSON emits the exact decimal USD string ("0.00132") — a STRING, never a JSON number, so no consumer can reintroduce a float rounding error.
func (Amount) String ¶
String renders the value as a trimmed decimal USD string ("6.6", "0.00132", "-0.5", "0") — the human/JSON form. Exact: derived from the integer coefficient, never a float.
func (*Amount) UnmarshalJSON ¶
UnmarshalJSON accepts either a quoted decimal USD string or a bare decimal number (parsed exactly, without float).
Source Files