[BFT-A][R8] Establish canonical CBE curve types and fixed-point state model

[umwelt]

Title

[BFT-A][R8] Establish canonical CBE curve types and fixed-point state model

Category

• R8 Invariants & Observability

Authoritative Inputs

• CBE Bonding Curve — Complete Formula Reference
• CBE Bonding Curve — Rust Implementation Specification
• Team decision: band storage uses p_start (price at band start), not algebraic signed intercept b

Problem

The current issue assumed a broader native economics model with approved assets, oracle price records, and treasury-valued SOV issuance. The new curve docs define a narrower and stricter consensus surface for the CBE bonding curve.

Current Behavior

There is no single canonical type layer for the exact curve-state model described by the new docs. The repo still spreads shape information across bonding-curve modules, pricing code, transaction code, and runtime assumptions.

Required Behavior

Create one canonical type layer in lib-types for the curve protocol described by the docs:

• BandConfig
• EconomicState
• AccountState
• fixed-width u48 nonce representation
• BuyCbeTx payload shape
• SellCbeTx payload shape
• immutable curve constants/config shape

Band storage must use positive p_start (price at s_start) rather than algebraic signed intercept b.

The canonical mutable curve state for this epic is:

• s_c: u128
• reserve_balance: u128
• treasury_balance: u128
• graduated: bool

The curve also integrates with an external SOV sink for fee collection (dao_treasury_sov in the execution spec), but that does not create a second authoritative curve-state model.

This issue is not about approved-asset registries, oracle price records, or treasury-valued BUY_SOV.

Safety Impact

Without a canonical type boundary, the implementation will drift away from the transaction layout, arithmetic rules, and state transition model required by the new spec.

Proposed Fix

Move pure curve protocol data types into lib-types. Keep behavior in domain crates through extension traits/helpers only.

Dependencies

None

Acceptance Criteria

• Canonical curve types exist in lib-types
• Canonical band record uses unsigned u128 p_start
• Canonical mutable state matches the new docs exactly
• u48 nonce representation is defined and serialization-stable
• No duplicate authoritative type definitions remain outside lib-types
• Type architecture rule is followed

Test Plan

• Type serialization round-trip tests
• u48 packing/unpacking tests
• Band record invariant tests
• State shape regression tests against the spec examples

Cleanup After

• Stop introducing new authoritative curve types in lib-blockchain
• Remove issue text and code comments that still describe the broader pre-doc native economics model or signed intercept storage

[github-actions]

The GitHub issue titled "[BFT-A][R8] Establish canonical native economics types and parameter bundle" addresses the need for a unified and authoritative data model for native economic structures in the project. Currently, economic-related data is fragmented across various components such as token contracts, bonding curves, oracle state, and runtime assumptions. This disorganization leads to ambiguity in consensus state authority and risks inconsistent behavior during replay or restart events. The proposed solution involves consolidating pure native economics data types into a central module (lib-types) while delegating behavior to domain-specific crates using extension traits and helpers. Acceptance criteria include eliminating duplicate structures, adhering to type architecture rules, and ensuring types are properly serialized and invariant-tested. Post-implementation cleanup involves halting the creation of new economic structs in lib-blockchain and marking legacy ones appropriately.

[umwelt]

Implemented on the bonding-curve rollout branch.

Delivered:

• canonical curve/state/tx data types in lib-types/src/bonding_curve.rs
• Nonce48
• canonical economic/account state shapes
• fixed-width BondingCurveBuyTx / BondingCurveSellTx
• branch curve representation locked to p_start instead of signed global intercepts

Primary foundation commit:

• c8b8a80d Implement canonical bonding curve math foundation

This issue is complete for the current curve rollout.