Documentation
¶
Overview ¶
Package husd is the ONE place that configures on-chain HUSD (Hanzo USD stablecoin, ERC-20 on the Hanzo EVM) operations and converts USD cents to and from the token's base units.
It is a leaf package (stdlib only): no datastore, no gin, no geth. Both the OSS-contributor payout executor (cron/payout/contributor) and the chain-backed credit ledger (treasury, billing/husdindex) source their HUSD configuration and cent↔wei math from here, so there is exactly one definition of what "HUSD" means and how a USD amount maps to the chain — never a second, drifting copy.
TreasuryKey is held in memory only — never persisted, never logged.
Index ¶
Constants ¶
const ( // DefaultChainID is the Hanzo EVM mainnet chain id (36963). Testnet (36962) // and devnet (36964) are selected by setting HUSD_CHAIN_ID + HUSD_RPC_URL // from KMS. DefaultChainID int64 = 36963 // DefaultRPCURL is the Hanzo EVM mainnet C-chain JSON-RPC endpoint. DefaultRPCURL = "https://api.hanzo.network/ext/bc/C/rpc" // DefaultDecimals is the HUSD token's decimals (18, standard ERC-20). DefaultDecimals = 18 )
Variables ¶
var ErrNotConfigured = errors.New(
"husd: on-chain HUSD not configured (set HUSD_TOKEN_ADDRESS + HUSD_TREASURY_KEY in KMS)")
ErrNotConfigured is returned when the HUSD token address or treasury key is missing. Operations fail closed: with no token address (mainnet has no default) an unset deploy can never mis-target or mint against the wrong chain.
Functions ¶
func CentsToWei ¶
CentsToWei converts USD cents into HUSD base units for a token with the given decimals: wei = cents * 10^(decimals-2). e.g. 18 decimals, 100 cents ($1.00) → 1e18. Decimals must be >= 2 (a stablecoin never has fewer than 2) and cents must be non-negative.
func SettlementDrift ¶
SettlementDrift computes how much HUSD to sweep from an org's on-chain address back to the treasury so its on-chain balance tracks its off-chain ledger.
drift = onChainCents − max(0, spendableCents)
i.e. the value drawn down by off-chain metered usage (and any reclaimed/expired grants) that the chain has not yet reflected (mints put HUSD on the org address; usage happens off-chain, so the chain over-states the balance until settled). settle is true only when drift ≥ max(1, thresholdCents), so dust never churns gas. A non-positive drift — the ledger is level with, or AHEAD of, the chain (an un-projected mint) — never settles: settling then would over-sweep, so the indexer must catch up first.
func WeiToCents ¶
WeiToCents converts HUSD base units back to whole USD cents, truncating any sub-cent remainder (which is returned separately). It is the inverse of CentsToWei for exact multiples: cents = wei / 10^(decimals-2). The remainder is reported so callers indexing on-chain balances can assert no dust is lost silently. Decimals must be >= 2; wei must be non-negative.
Types ¶
type Config ¶
type Config struct {
ChainID int64
RPCURL string
TokenAddress string
Decimals int
TreasuryKey string
GasLimit uint64
}
Config configures on-chain HUSD stablecoin operations. Values are sourced from the environment, which is populated from KMS (KMSSecret CRD → k8s Secret → env). TreasuryKey is held in memory only — never persisted, never logged.
func (*Config) Configured ¶
Configured reports whether the on-chain path can execute: a token contract and a treasury signing key are both present.
func (*Config) LoadFromEnv ¶
func (c *Config) LoadFromEnv()
LoadFromEnv fills any unset field from the environment (KMS-injected). Already-set fields are preserved, so callers (and tests) may supply values directly. The token address has NO default (greenfield, KMS-only) so an unset HUSD_TOKEN_ADDRESS fails closed instead of silently targeting mainnet.
Source Files