docs(milestone): complete OpenYield v0.3 (Bearers & Documentation)

Milestone v0.3 complete. Feature type, tags v0.2.x. Two work-streams
shipped under one feature milestone:

(A) Bearers skeleton + tests (D-020 pattern, 7 x/* packages, zero ext deps):
- x/bridge (NEW): BridgeStatus enum (4), BridgeRoute by-ID-string refs
- x/exit (NEW): ExitStatus enum (5), ExitRoute, DEXSwap (opaque venue)
- x/bearers (EXT): OYSATLink surveillance-resistant LOCKED, OYQRCode idempotent
- x/partner (EXT): AnchorCredential (custody-provider-id empty in skeleton)
- x/hub (NEW): HubService enum (3), LendingCouponCapBps=800 LOCAL const (A-304)
- x/services (NEW): ServiceKind enum (4), window-id by-ID-string ref (A-307)
- x/bond (EXT): GrowthBond, ClampGrowth G-012 underflow guard, secondary market
All packages >=93.3% coverage. Both lexicon firewalls green. G-003 intact.

(B) Documentation deliverable (REQ-027 complete, 26-page MkDocs Material site):
- README.md + mkdocs.yml + docs/index.md
- docs/shared/ (7 pages): Six Principles, Bread Scale, Storage Pools, Watchers/Mirror, Lexicon, Vision
- docs/nomads/ (8 pages): Reach, Stash, Bearers, Maps-Pay, Pacts, Standing, Window
- docs/freeholders/ (8 pages): Signals, Standing, Stands-Guilds, Councils-Voice, Bonds, Partner Spectrum, Anchor Preview
- docs/reference/ (2 pages): Architecture, Components
- REQ-028: lexicon firewall extended to docs/ + README.md (lexicon_meta_docs_test.go, 5 tests incl G-013 walk-coverage + G-014 shared self-test)

Phases: P0 -> v0.2.0, P1 -> v0.2.1, P2 -> v0.2.2, P3 -> v0.2.3, P4 -> v0.2.4, P5 -> v0.2.5, P6 -> v0.2.6 (milestone release).

Requirements covered: REQ-010, REQ-022, REQ-023, REQ-024, REQ-025, REQ-026 (skeleton), REQ-027, REQ-028 (complete).
IDEATE-01..08 ratified and delivered.

---ci---
project: oy
phase: 6
milestone: v0.3
status: complete
tag_base: v0.2.x
phase_role: final
milestone_complete: true
requirements:
  covered: [REQ-010, REQ-022, REQ-023, REQ-024, REQ-025, REQ-026, REQ-027, REQ-028]
  partial: []
---/ci---
This commit is contained in:
2026-08-17 22:35:36 +00:00
parent 47fa79148c
commit 82ae6cf5a2
58 changed files with 7115 additions and 170 deletions
+90
View File
@@ -52,3 +52,93 @@ func knownBondStatus(s BondStatus) bool {
}
return false
}
// --- v0.3 extension: GrowthBond + Order genesis helpers (REQ-026, G-008) --------
//
// genesis.go also holds the data-engineer's genesis schema helpers for the
// v0.3 GrowthBond + SecondaryOrder sets (G-008). ValidateGenesis in types.go
// composes ValidateGrowthBonds + ValidateOrders; the security-engineer's test
// assertions live in types_test.go / genesis_test.go.
// ValidateGrowthBonds asserts growth-bond-ids are present and unique, that
// each embedded Bond's coupon-bps is within the LOCKED [floor, cap] bounds
// (D-028), and that each growth-bond's growth-rate-bps would not push the
// coupon above the cap (ClampGrowth(currentBps=coupon, growth) == growth —
// i.e. the post-growth coupon stays <= cap). The genesis-side clamp is the
// authoritative check (a genesis growth-bond with an out-of-bounds coupon or
// growth rate is rejected rather than silently clamped).
func ValidateGrowthBonds(gbs []GrowthBond) error {
seen := make(map[string]bool, len(gbs))
for i, gb := range gbs {
if gb.BondID == "" {
return fmt.Errorf("growth bond [%d]: empty bond-id", i)
}
if seen[gb.BondID] {
return fmt.Errorf("growth bond: duplicate bond-id %q", gb.BondID)
}
seen[gb.BondID] = true
if !knownBondStatus(gb.Status) {
return fmt.Errorf("growth bond %q: unknown bond status %q", gb.BondID, gb.Status)
}
// D-028 clamp on the embedded Bond's coupon.
if gb.CouponBps < CouponFloorBps || gb.CouponBps > CouponCapBps {
return fmt.Errorf("growth bond %q: coupon-bps %d outside [%d, %d] (D-028 clamp at genesis load)",
gb.BondID, gb.CouponBps, CouponFloorBps, CouponCapBps)
}
// G-012 / A-306: the growth-rate must not push the coupon above the
// cap. ClampGrowth(coupon, growth) must equal growth (i.e. the
// requested growth fits within the room-to-cap); otherwise the
// genesis growth-bond is rejected as out-of-bounds.
if ClampGrowth(gb.CouponBps, gb.GrowthRateBps) != gb.GrowthRateBps {
return fmt.Errorf("growth bond %q: growth-rate-bps %d would push coupon-bps %d above cap %d (G-012/A-306 clamp at genesis load)",
gb.BondID, gb.GrowthRateBps, gb.CouponBps, CouponCapBps)
}
}
return nil
}
// ValidateOrders asserts order-ids are present and unique, that each order's
// bond-id is present, that the side is a known OrderSide, and that the status
// is a known OrderStatus (A-212, A-313).
func ValidateOrders(orders []SecondaryOrder) error {
seen := make(map[string]bool, len(orders))
for i, o := range orders {
if o.OrderID == "" {
return fmt.Errorf("order [%d]: empty order-id", i)
}
if seen[o.OrderID] {
return fmt.Errorf("order: duplicate order-id %q", o.OrderID)
}
seen[o.OrderID] = true
if o.BondID == "" {
return fmt.Errorf("order %q: empty bond-id", o.OrderID)
}
if !knownOrderSide(o.Side) {
return fmt.Errorf("order %q: unknown order side %q", o.OrderID, o.Side)
}
if !knownOrderStatus(o.Status) {
return fmt.Errorf("order %q: unknown order status %q", o.OrderID, o.Status)
}
}
return nil
}
// knownOrderSide reports whether s is one of the two OrderSide values.
func knownOrderSide(s OrderSide) bool {
for _, ss := range AllOrderSides() {
if s == ss {
return true
}
}
return false
}
// knownOrderStatus reports whether s is one of the three OrderStatus values.
func knownOrderStatus(s OrderStatus) bool {
for _, ss := range AllOrderStatuses() {
if s == ss {
return true
}
}
return false
}
+167 -11
View File
@@ -113,26 +113,33 @@ type Params struct{}
func DefaultParams() Params { return Params{} }
// GenesisState defines the bond module genesis state (REQ-021). Bonds is the
// top-level set of issued bonds. ValidateGenesis enforces bond-id uniqueness
// and the coupon clamp at genesis load (the data-engineer's genesis.go holds
// the schema helpers per G-008).
// GenesisState defines the bond module genesis state (REQ-021, REQ-026).
// Bonds is the top-level set of issued bonds (v0.2). GrowthBonds (v0.3) and
// Orders (v0.3) extend the genesis with growth bonds and secondary-market
// orders. ValidateGenesis enforces bond-id / growth-bond-id / order-id
// uniqueness and the coupon clamp at genesis load (the data-engineer's
// genesis.go holds the schema helpers per G-008).
type GenesisState struct {
Params Params `json:"params" yaml:"params"`
Bonds []Bond `json:"bonds" yaml:"bonds"`
Params Params `json:"params" yaml:"params"`
Bonds []Bond `json:"bonds" yaml:"bonds"`
GrowthBonds []GrowthBond `json:"growth_bonds" yaml:"growth_bonds"`
Orders []SecondaryOrder `json:"orders" yaml:"orders"`
}
func DefaultGenesisState() *GenesisState {
return &GenesisState{
Params: DefaultParams(),
Bonds: []Bond{},
Params: DefaultParams(),
Bonds: []Bond{},
GrowthBonds: []GrowthBond{},
Orders: []SecondaryOrder{},
}
}
// ValidateGenesis performs ID-uniqueness checks (A-212 upgrade from v0.1
// no-op): rejects duplicate bond-ids, and runs the coupon clamp at genesis
// load (each genesis bond's coupon-bps must be within [floor, cap]). Delegates
// to the data-engineer's genesis.go helpers (G-008).
// no-op): rejects duplicate bond-ids / growth-bond-ids / order-ids, and runs
// the coupon clamp at genesis load (each genesis bond's coupon-bps must be
// within [floor, cap]). Delegates to the data-engineer's genesis.go helpers
// (G-008).
func ValidateGenesis(bz json.RawMessage) error {
var gs GenesisState
if err := json.Unmarshal(bz, &gs); err != nil {
@@ -141,5 +148,154 @@ func ValidateGenesis(bz json.RawMessage) error {
if err := ValidateBonds(gs.Bonds); err != nil {
return fmt.Errorf("bond: %w", err)
}
if err := ValidateGrowthBonds(gs.GrowthBonds); err != nil {
return fmt.Errorf("bond: %w", err)
}
if err := ValidateOrders(gs.Orders); err != nil {
return fmt.Errorf("bond: %w", err)
}
return nil
}
// --- v0.3 extension: GrowthBond + secondary market (REQ-026, D-041, G-012) -------
//
// The v0.3 bond extension adds GrowthBond (a bond whose coupon grows with
// protocol health, vision §17) and secondary-market order types. The 8%/0%
// consts (D-028) are UNCHANGED — the regression firewall in types_test.go
// asserts CouponCapBps==800 and CouponFloorBps==0 are still the v0.2 values.
// Full secondary-market matching is deferred to v0.4.
// OrderSideCount is the locked count of OrderSide enum values (vision §17
// secondary market, A-313). A regression firewall: adding/removing/renaming
// an order side breaks this const's test.
const OrderSideCount = 2
// OrderStatusCount is the locked count of OrderStatus enum values (A-313).
const OrderStatusCount = 3
// OrderSide enumerates the two sides of a secondary-market order (vision §17,
// REQ-026, A-313): Buy (a bid for a bond), Sell (an ask for a bond).
type OrderSide string
const (
OrderBuy OrderSide = "Buy" // bid
OrderSell OrderSide = "Sell" // ask
)
// AllOrderSides returns both OrderSide values in vision-§17 order. Locked-
// const test asserts exactly 2 entries with these names (A-313).
func AllOrderSides() []OrderSide {
return []OrderSide{
OrderBuy,
OrderSell,
}
}
// OrderStatus enumerates the three lifecycle states of a secondary-market
// order (vision §17, REQ-026, A-313): Open (resting on the book), Filled
// (matched and settled), Cancelled (removed by the holder or expired). The
// matching engine is v0.4; v0.3 types the order shape only.
type OrderStatus string
const (
OrderOpen OrderStatus = "Open" // resting on the book
OrderFilled OrderStatus = "Filled" // matched and settled
OrderCancelled OrderStatus = "Cancelled" // removed by the holder or expired
)
// AllOrderStatuses returns all three OrderStatus values in A-313 order.
// Locked-const test asserts exactly 3 entries with these names.
func AllOrderStatuses() []OrderStatus {
return []OrderStatus{
OrderOpen,
OrderFilled,
OrderCancelled,
}
}
// ClampGrowth returns the additional bps a GrowthBond's coupon can grow so
// that the post-growth coupon (currentBps + additional) never exceeds
// CouponCapBps (D-028, A-306, G-012). The "post-growth coupon <= cap"
// invariant holds UNCONDITIONALLY.
//
// G-012 BINDING: ClampGrowth MUST guard currentBps > CouponCapBps BEFORE
// computing cap - current. The naive `min(cap - current, growth)` underflows
// uint32 when current > cap (cap - current wraps to a huge value, then min
// picks growthBps — the invariant is violated). This implementation guards
// explicitly:
// - If currentBps >= CouponCapBps: return 0 (no room to grow; the cap is
// already reached or exceeded — the post-growth coupon cannot grow
// without breaching the cap).
// - Otherwise: return min(CouponCapBps - currentBps, growthBps) (the room-
// to-cap, clamped by the requested growth).
//
// The two G-012-mandated test cases are: currentBps == CouponCapBps (return 0,
// the at-cap boundary) and currentBps > CouponCapBps (return 0, the guard
// against uint32 underflow — NOT a wrapped huge value).
func ClampGrowth(currentBps, growthBps uint32) uint32 {
// G-012 guard: at-or-above cap means no room to grow. This MUST be checked
// before the cap - current subtraction to avoid uint32 underflow when
// currentBps > cap.
if currentBps >= CouponCapBps {
return 0
}
// currentBps < cap is guaranteed here; cap - current does not underflow.
room := CouponCapBps - currentBps
if growthBps < room {
return growthBps
}
return room
}
// GrowthBond is a bond whose coupon grows with protocol health (vision §17,
// REQ-026, D-041, A-306). It embeds the v0.2 Bond (anonymous field) so it
// carries all Bond fields (bond-id, issuer-stand-id, principal-grain,
// coupon-bps, term-days, issued-at, maturity, status) PLUS a GrowthRateBps
// field (the per-period growth rate of the coupon, in bps). The growth rate
// is clamped at issuance so that the post-growth coupon never exceeds
// CouponCapBps (800 bps) — see IssueGrowth, which clamps couponBps via Clamp
// and growthRateBps via ClampGrowth (with currentBps=couponBps).
//
// The 8%/0% consts (D-028) apply to GrowthBonds too: the growth coupon is
// clamped to [0, 800] bps at any point. GrowthBond is in the same package as
// Bond (no G-003 concern for the Clamp/ClampGrowth reuse).
type GrowthBond struct {
Bond // anonymous embed — carries all v0.2 Bond fields
GrowthRateBps uint32 `json:"growth_rate_bps" yaml:"growth_rate_bps"`
}
// IssueGrowth is the GrowthBond issuance stub (REQ-026, D-041). It constructs a
// GrowthBond with the coupon clamped to [CouponFloorBps, CouponCapBps] via
// Clamp, and the growth-rate clamped so that coupon + growth never exceeds
// CouponCapBps via ClampGrowth (with currentBps=couponBps). The returned
// GrowthBond has status BondIssued (inherited from Issue's Bond construction).
// The stub does not persist or enforce referential integrity of issuer-stand-
// id (a v0.4 keeper concern); it only enforces the coupon + growth clamp
// invariants at construction time.
func IssueGrowth(bondID, issuerStandID string, principalGrain int64, couponBps, growthRateBps uint32, termDays uint32, issuedAt, maturity int64) GrowthBond {
clampedCoupon := Clamp(couponBps)
clampedGrowth := ClampGrowth(clampedCoupon, growthRateBps)
return GrowthBond{
Bond: Issue(bondID, issuerStandID, principalGrain, clampedCoupon, termDays, issuedAt, maturity),
GrowthRateBps: clampedGrowth,
}
}
// SecondaryOrder is a secondary-market order on an issued bond (vision §17,
// REQ-026, D-041, A-313). order-id is the unique identifier. bond-id references
// a Bond (by-ID-string ref to a Bond — same package, so this is an in-package
// ID-string ref, not a cross-module G-003 concern). side picks OrderSide
// (Buy/Sell). price-grain is the order price in Grain (fraction of principal,
// expressed in Grain for fixed-point precision). holder-reach-id references
// an x/identity Reach by ID-string (G-003 — use "holder-reach-id" not the
// banned Holder-identity term). status is the OrderStatus. created-at is the
// unix timestamp.
type SecondaryOrder struct {
OrderID string `json:"order_id" yaml:"order_id"`
BondID string `json:"bond_id" yaml:"bond_id"`
Side OrderSide `json:"side" yaml:"side"`
PriceGrain int64 `json:"price_grain" yaml:"price_grain"`
HolderReachID string `json:"holder_reach_id" yaml:"holder_reach_id"`
Status OrderStatus `json:"status" yaml:"status"`
CreatedAt int64 `json:"created_at" yaml:"created_at"`
}
+533
View File
@@ -416,6 +416,539 @@ func TestLexiconNoBannedTermsInBondTestFile(t *testing.T) {
}
}
// --- v0.3 extension: ClampGrowth (G-012 BINDING) ---------------------------------
// ClampGrowth is the G-012 binding decision: it MUST guard currentBps >
// CouponCapBps before computing cap - current, otherwise the uint32
// subtraction underflows (cap - current wraps to a huge value, then min picks
// growthBps — the post-growth coupon invariant is violated). These tests are
// written FIRST (TDD) to confirm the guard works before the function existed;
// they are the highest-severity v0.3 bond firewall.
//
// The five G-012-mandated test cases:
// 1. currentBps == 0 (full growth room)
// 2. currentBps == CouponCapBps (no room, return 0 — the at-cap boundary)
// 3. currentBps > CouponCapBps (the underflow GUARD — return 0, NOT a wrapped
// huge value)
// 4. growthBps larger than room (clamp to room)
// 5. growthBps smaller than room (return growthBps)
// TestClampGrowthCurrentZeroFullRoom asserts case 1: currentBps == 0 leaves
// the full room to the cap; the growth is clamped to min(cap, growth).
func TestClampGrowthCurrentZeroFullRoom(t *testing.T) {
// growth < cap (room) -> return growth
if got := btypes.ClampGrowth(0, 500); got != 500 {
t.Errorf("ClampGrowth(0, 500) = %d, expected 500 (full room, growth < cap)", got)
}
// growth == cap (room) -> return cap (room)
if got := btypes.ClampGrowth(0, btypes.CouponCapBps); got != btypes.CouponCapBps {
t.Errorf("ClampGrowth(0, cap) = %d, expected cap %d (full room, growth == cap)", got, btypes.CouponCapBps)
}
// growth > cap (room) -> return cap (room)
if got := btypes.ClampGrowth(0, 1000); got != btypes.CouponCapBps {
t.Errorf("ClampGrowth(0, 1000) = %d, expected cap %d (full room, growth > cap clamps to cap)", got, btypes.CouponCapBps)
}
}
// TestClampGrowthCurrentAtCapReturnsZero asserts case 2: currentBps ==
// CouponCapBps (the at-cap boundary). There is no room to grow; return 0.
// This is the G-012-mandated at-cap test.
func TestClampGrowthCurrentAtCapReturnsZero(t *testing.T) {
got := btypes.ClampGrowth(btypes.CouponCapBps, 100)
if got != 0 {
t.Errorf("ClampGrowth(cap, 100) = %d, expected 0 (at-cap boundary — no room to grow, G-012)", got)
}
}
// TestClampGrowthCurrentAboveCapReturnsZero asserts case 3: currentBps >
// CouponCapBps (the uint32 underflow GUARD). The naive min(cap-current,
// growth) would underflow uint32 (cap-current wraps to a huge value, then min
// picks growth — invariant violated). ClampGrowth MUST return 0, NOT a
// wrapped huge value. This is the G-012-mandated above-cap test.
func TestClampGrowthCurrentAboveCapReturnsZero(t *testing.T) {
cases := []struct {
current uint32
growth uint32
}{
{uint32(btypes.CouponCapBps) + 1, 100},
{uint32(btypes.CouponCapBps) + 100, 500},
{uint32(btypes.CouponCapBps) + 1000, 50},
{5000, 100},
{100_000, 1},
}
for _, c := range cases {
got := btypes.ClampGrowth(c.current, c.growth)
if got != 0 {
t.Errorf("ClampGrowth(%d, %d) = %d, expected 0 (above-cap GUARD — uint32 underflow must NOT happen, G-012)",
c.current, c.growth, got)
}
}
}
// TestClampGrowthGrowthLargerThanRoomClampsToRoom asserts case 4: growthBps
// larger than the room-to-cap is clamped to the room.
func TestClampGrowthGrowthLargerThanRoomClampsToRoom(t *testing.T) {
// current=500, cap=800, room=300. growth=400 > room -> return 300.
got := btypes.ClampGrowth(500, 400)
if got != 300 {
t.Errorf("ClampGrowth(500, 400) = %d, expected 300 (growth larger than room clamps to room)", got)
}
// current=799, cap=800, room=1. growth=50 > room -> return 1.
got = btypes.ClampGrowth(799, 50)
if got != 1 {
t.Errorf("ClampGrowth(799, 50) = %d, expected 1 (room=1, growth clamps to room)", got)
}
}
// TestClampGrowthGrowthSmallerThanRoomReturnsGrowth asserts case 5: growthBps
// smaller than the room-to-cap is returned unchanged.
func TestClampGrowthGrowthSmallerThanRoomReturnsGrowth(t *testing.T) {
// current=500, cap=800, room=300. growth=200 < room -> return 200.
got := btypes.ClampGrowth(500, 200)
if got != 200 {
t.Errorf("ClampGrowth(500, 200) = %d, expected 200 (growth < room, unchanged)", got)
}
// current=0, cap=800, room=800. growth=100 < room -> return 100.
got = btypes.ClampGrowth(0, 100)
if got != 100 {
t.Errorf("ClampGrowth(0, 100) = %d, expected 100 (growth < room, unchanged)", got)
}
}
// TestClampGrowthInvariantPostGrowthLeCap is the meta-assert: ClampGrowth
// never ADDS growth that would push the post-growth coupon past the cap. The
// invariant is: current + ClampGrowth(current, growth) <= max(current, cap).
// When current <= cap, this means post-growth <= cap (no growth past the
// cap). When current > cap (the G-012 misuse/guard case), ClampGrowth returns
// 0 (no additional growth), so post == current (the already-broken state is
// not made worse; the guard prevents the uint32 underflow from adding a
// wrapped-huge value as growth).
func TestClampGrowthInvariantPostGrowthLeCap(t *testing.T) {
cases := []struct {
current uint32
growth uint32
}{
{0, 0},
{0, 800},
{0, 1000},
{400, 400},
{400, 500},
{799, 1},
{799, 100},
{800, 100}, // at-cap
{801, 100}, // above-cap (guard)
{5000, 1000}, // way above-cap (guard)
}
for _, c := range cases {
got := btypes.ClampGrowth(c.current, c.growth)
post := c.current + got
// The bound: post <= max(current, cap). When current <= cap, this is
// post <= cap (no growth past the cap). When current > cap, this is
// post <= current (no additional growth — the guard returned 0).
upper := c.current
if uint32(btypes.CouponCapBps) > upper {
upper = btypes.CouponCapBps
}
if post > upper {
t.Errorf("ClampGrowth(%d, %d) = %d; post-growth coupon %d > %d (G-012 invariant violated)",
c.current, c.growth, got, post, upper)
}
// Stronger assert for the in-bounds case: when current <= cap, post
// must be <= cap exactly (no growth past the cap).
if c.current <= btypes.CouponCapBps && post > btypes.CouponCapBps {
t.Errorf("ClampGrowth(%d, %d) = %d; post-growth coupon %d > cap %d (in-bounds invariant violated)",
c.current, c.growth, got, post, btypes.CouponCapBps)
}
}
}
// --- D-028 regression: 8%/0% consts unchanged (v0.3 must not change v0.2) -------
// These tests are re-declared here in the v0.3 block to make the regression
// firewall explicit in the extension context. The v0.2 tests above
// (TestCouponCapBpsLockedConst / TestCouponFloorBpsLockedConst) are the
// primary firewall; this block re-asserts in the v0.3 extension context.
// TestD028RegressionCouponCapUnchanged asserts CouponCapBps is still 800
// after the v0.3 GrowthBond extension (D-028 regression firewall).
func TestD028RegressionCouponCapUnchanged(t *testing.T) {
if btypes.CouponCapBps != 800 {
t.Errorf("D-028 regression: CouponCapBps = %d, expected 800 (v0.3 must not change v0.2 const)", btypes.CouponCapBps)
}
}
// TestD028RegressionCouponFloorUnchanged asserts CouponFloorBps is still 0.
func TestD028RegressionCouponFloorUnchanged(t *testing.T) {
if btypes.CouponFloorBps != 0 {
t.Errorf("D-028 regression: CouponFloorBps = %d, expected 0 (v0.3 must not change v0.2 const)", btypes.CouponFloorBps)
}
}
// TestD028RegressionBondStatusCountUnchanged asserts BondStatusCount is still
// 5 (the v0.2 enum is unchanged by the v0.3 extension).
func TestD028RegressionBondStatusCountUnchanged(t *testing.T) {
if btypes.BondStatusCount != 5 {
t.Errorf("D-028 regression: BondStatusCount = %d, expected 5 (v0.2 enum unchanged)", btypes.BondStatusCount)
}
}
// --- OrderSide enum coverage (2) ----------------------------------------------
// TestOrderSideCountLockedConst asserts OrderSideCount == 2 and AllOrderSides()
// returns exactly 2 (A-313). A regression firewall.
func TestOrderSideCountLockedConst(t *testing.T) {
if btypes.OrderSideCount != 2 {
t.Errorf("OrderSideCount = %d, expected 2 (A-313 LOCKED)", btypes.OrderSideCount)
}
all := btypes.AllOrderSides()
if len(all) != 2 {
t.Errorf("AllOrderSides() len = %d, expected 2", len(all))
}
}
// TestAllOrderSidesNames asserts the 2 A-313 names in order with no extras, no
// dups, no renames.
func TestAllOrderSidesNames(t *testing.T) {
want := []string{"Buy", "Sell"}
all := btypes.AllOrderSides()
if len(all) != len(want) {
t.Fatalf("len = %d, want %d", len(all), len(want))
}
seen := map[string]bool{}
for i, s := range all {
if string(s) != want[i] {
t.Errorf("AllOrderSides()[%d] = %q, want %q", i, s, want[i])
}
if seen[string(s)] {
t.Errorf("duplicate OrderSide %q", s)
}
seen[string(s)] = true
}
}
// TestOrderSideValues asserts each named const matches its AllOrderSides entry.
func TestOrderSideValues(t *testing.T) {
if btypes.OrderBuy != "Buy" {
t.Errorf("OrderBuy = %q", btypes.OrderBuy)
}
if btypes.OrderSell != "Sell" {
t.Errorf("OrderSell = %q", btypes.OrderSell)
}
}
// --- OrderStatus enum coverage (3) -------------------------------------------
// TestOrderStatusCountLockedConst asserts OrderStatusCount == 3 and
// AllOrderStatuses() returns exactly 3 (A-313). A regression firewall.
func TestOrderStatusCountLockedConst(t *testing.T) {
if btypes.OrderStatusCount != 3 {
t.Errorf("OrderStatusCount = %d, expected 3 (A-313 LOCKED)", btypes.OrderStatusCount)
}
all := btypes.AllOrderStatuses()
if len(all) != 3 {
t.Errorf("AllOrderStatuses() len = %d, expected 3", len(all))
}
}
// TestAllOrderStatusesNames asserts the 3 A-313 names in order with no extras,
// no dups, no renames.
func TestAllOrderStatusesNames(t *testing.T) {
want := []string{"Open", "Filled", "Cancelled"}
all := btypes.AllOrderStatuses()
if len(all) != len(want) {
t.Fatalf("len = %d, want %d", len(all), len(want))
}
seen := map[string]bool{}
for i, s := range all {
if string(s) != want[i] {
t.Errorf("AllOrderStatuses()[%d] = %q, want %q", i, s, want[i])
}
if seen[string(s)] {
t.Errorf("duplicate OrderStatus %q", s)
}
seen[string(s)] = true
}
}
// TestOrderStatusValues asserts each named const matches its AllOrderStatuses
// entry.
func TestOrderStatusValues(t *testing.T) {
if btypes.OrderOpen != "Open" {
t.Errorf("OrderOpen = %q", btypes.OrderOpen)
}
if btypes.OrderFilled != "Filled" {
t.Errorf("OrderFilled = %q", btypes.OrderFilled)
}
if btypes.OrderCancelled != "Cancelled" {
t.Errorf("OrderCancelled = %q", btypes.OrderCancelled)
}
}
// --- GrowthBond + IssueGrowth --------------------------------------------------
// TestGrowthBondStructFields asserts GrowthBond embeds Bond and adds
// GrowthRateBps.
func TestGrowthBondStructFields(t *testing.T) {
gb := btypes.GrowthBond{
Bond: btypes.Bond{BondID: "gb-1", IssuerStandID: "stand-1", PrincipalGrain: 1_000_000, CouponBps: 500, TermDays: 365, IssuedAt: 1000, Maturity: 1365, Status: btypes.BondIssued},
GrowthRateBps: 200,
}
if gb.BondID != "gb-1" || gb.IssuerStandID != "stand-1" || gb.PrincipalGrain != 1_000_000 ||
gb.CouponBps != 500 || gb.TermDays != 365 || gb.IssuedAt != 1000 || gb.Maturity != 1365 ||
gb.Status != btypes.BondIssued || gb.GrowthRateBps != 200 {
t.Error("GrowthBond fields not set correctly")
}
// The embedded Bond is accessible via the anonymous field.
if gb.Bond.BondID != "gb-1" {
t.Errorf("embedded Bond.BondID = %q", gb.Bond.BondID)
}
}
// TestIssueGrowthConstruction asserts IssueGrowth clamps the coupon via Clamp
// and the growth-rate via ClampGrowth, and returns status BondIssued.
func TestIssueGrowthConstruction(t *testing.T) {
// In-range coupon and growth: both unchanged.
gb := btypes.IssueGrowth("gb-2", "stand-1", 1_000_000, 500, 200, 365, 1000, 1365)
if gb.BondID != "gb-2" {
t.Errorf("BondID = %q", gb.BondID)
}
if gb.CouponBps != 500 {
t.Errorf("CouponBps = %d, expected 500 (in-range, unchanged)", gb.CouponBps)
}
if gb.GrowthRateBps != 200 {
t.Errorf("GrowthRateBps = %d, expected 200 (in-range, growth < room)", gb.GrowthRateBps)
}
if gb.Status != btypes.BondIssued {
t.Errorf("Status = %q, expected BondIssued", gb.Status)
}
}
// TestIssueGrowthClampsAboveCapCoupon asserts IssueGrowth clamps an above-cap
// coupon down to the cap (via Clamp), and the growth-rate is then clamped
// against the clamped coupon (currentBps=cap -> growth returns 0, G-012).
func TestIssueGrowthClampsAboveCapCoupon(t *testing.T) {
gb := btypes.IssueGrowth("gb-3", "stand-1", 1_000_000, 1200, 100, 365, 1000, 1365)
if gb.CouponBps != btypes.CouponCapBps {
t.Errorf("CouponBps = %d, expected cap %d (IssueGrowth must clamp above-cap coupon)", gb.CouponBps, btypes.CouponCapBps)
}
// coupon clamped to cap -> ClampGrowth(cap, 100) == 0 (no room, G-012).
if gb.GrowthRateBps != 0 {
t.Errorf("GrowthRateBps = %d, expected 0 (coupon at cap -> no room, G-012)", gb.GrowthRateBps)
}
}
// TestIssueGrowthClampsGrowthToRoom asserts IssueGrowth clamps a growth-rate
// that would push the coupon above the cap down to the room-to-cap.
func TestIssueGrowthClampsGrowthToRoom(t *testing.T) {
// coupon=500, cap=800, room=300. growth=400 -> clamped to 300.
gb := btypes.IssueGrowth("gb-4", "stand-1", 1_000_000, 500, 400, 365, 1000, 1365)
if gb.CouponBps != 500 {
t.Errorf("CouponBps = %d, expected 500", gb.CouponBps)
}
if gb.GrowthRateBps != 300 {
t.Errorf("GrowthRateBps = %d, expected 300 (growth clamped to room, G-012)", gb.GrowthRateBps)
}
// post-growth coupon: 500 + 300 = 800 == cap (invariant holds).
if gb.CouponBps+gb.GrowthRateBps > btypes.CouponCapBps {
t.Errorf("post-growth coupon %d > cap %d (G-012 invariant)", gb.CouponBps+gb.GrowthRateBps, btypes.CouponCapBps)
}
}
// --- SecondaryOrder struct ----------------------------------------------------
// TestSecondaryOrderStructFields asserts SecondaryOrder carries order-id,
// bond-id (by-ID-string ref to a Bond — in-package), side, price-grain,
// holder-reach-id (by-ID-string ref to x/identity — G-003), status, created-at.
func TestSecondaryOrderStructFields(t *testing.T) {
o := btypes.SecondaryOrder{
OrderID: "order-1",
BondID: "bond-1",
Side: btypes.OrderBuy,
PriceGrain: 950_000,
HolderReachID: "reach-holder-1",
Status: btypes.OrderOpen,
CreatedAt: 5000,
}
if o.OrderID != "order-1" || o.BondID != "bond-1" || o.Side != btypes.OrderBuy ||
o.PriceGrain != 950_000 || o.HolderReachID != "reach-holder-1" ||
o.Status != btypes.OrderOpen || o.CreatedAt != 5000 {
t.Error("SecondaryOrder fields not set correctly")
}
}
// TestSecondaryOrderBondIDIsString asserts bond-id is string-typed (in-package
// by-ID-string ref to a Bond — same package, not a G-003 cross-module import).
func TestSecondaryOrderBondIDIsString(t *testing.T) {
o := btypes.SecondaryOrder{BondID: "bond-xyz"}
if o.BondID != "bond-xyz" {
t.Errorf("BondID = %q", o.BondID)
}
}
// TestSecondaryOrderHolderReachIDIsString asserts holder-reach-id is
// string-typed (G-003 by-ID-string ref to x/identity Reach — no struct import).
func TestSecondaryOrderHolderReachIDIsString(t *testing.T) {
o := btypes.SecondaryOrder{HolderReachID: "reach-abc"}
if o.HolderReachID != "reach-abc" {
t.Errorf("HolderReachID = %q", o.HolderReachID)
}
}
// --- Genesis v0.3 extension: GrowthBonds + Orders -----------------------------
// TestDefaultGenesisStateV3Empty asserts DefaultGenesisState returns non-nil
// empty slices for the v0.3 GrowthBonds and Orders sets.
func TestDefaultGenesisStateV3Empty(t *testing.T) {
gs := btypes.DefaultGenesisState()
if gs.GrowthBonds == nil || len(gs.GrowthBonds) != 0 {
t.Errorf("Default GrowthBonds should be non-nil empty slice; got len=%d nil=%v", len(gs.GrowthBonds), gs.GrowthBonds == nil)
}
if gs.Orders == nil || len(gs.Orders) != 0 {
t.Errorf("Default Orders should be non-nil empty slice; got len=%d nil=%v", len(gs.Orders), gs.Orders == nil)
}
}
// TestValidateGenesisRejectsDupGrowthBondIDs asserts A-212: duplicate
// growth-bond-ids are rejected.
func TestValidateGenesisRejectsDupGrowthBondIDs(t *testing.T) {
gs := btypes.GenesisState{
GrowthBonds: []btypes.GrowthBond{
{Bond: btypes.Bond{BondID: "gb1", IssuerStandID: "s1", CouponBps: 500, Status: btypes.BondIssued}, GrowthRateBps: 100},
{Bond: btypes.Bond{BondID: "gb1", IssuerStandID: "s2", CouponBps: 200, Status: btypes.BondActive}, GrowthRateBps: 50}, // dup
},
}
bz, _ := json.Marshal(gs)
if err := btypes.ValidateGenesis(bz); err == nil {
t.Error("ValidateGenesis should reject duplicate growth-bond-ids")
}
}
// TestValidateGenesisRejectsGrowthBondCouponAboveCap asserts a genesis
// GrowthBond with coupon-bps above the cap is rejected (D-028 at genesis).
func TestValidateGenesisRejectsGrowthBondCouponAboveCap(t *testing.T) {
gs := btypes.GenesisState{
GrowthBonds: []btypes.GrowthBond{
{Bond: btypes.Bond{BondID: "gb1", IssuerStandID: "s1", CouponBps: 900, Status: btypes.BondIssued}, GrowthRateBps: 0},
},
}
bz, _ := json.Marshal(gs)
if err := btypes.ValidateGenesis(bz); err == nil {
t.Error("ValidateGenesis should reject growth-bond coupon above cap (D-028)")
}
}
// TestValidateGenesisRejectsGrowthBondGrowthAboveRoom asserts a genesis
// GrowthBond whose growth-rate would push the coupon above the cap is
// rejected (G-012 / A-306 at genesis).
func TestValidateGenesisRejectsGrowthBondGrowthAboveRoom(t *testing.T) {
gs := btypes.GenesisState{
GrowthBonds: []btypes.GrowthBond{
// coupon=500, cap=800, room=300. growth=400 -> would push to 900 > cap.
{Bond: btypes.Bond{BondID: "gb1", IssuerStandID: "s1", CouponBps: 500, Status: btypes.BondIssued}, GrowthRateBps: 400},
},
}
bz, _ := json.Marshal(gs)
if err := btypes.ValidateGenesis(bz); err == nil {
t.Error("ValidateGenesis should reject growth-bond growth-rate above room (G-012/A-306)")
}
}
// TestValidateGenesisRejectsDupOrderIDs asserts A-212: duplicate order-ids are
// rejected.
func TestValidateGenesisRejectsDupOrderIDs(t *testing.T) {
gs := btypes.GenesisState{
Orders: []btypes.SecondaryOrder{
{OrderID: "o1", BondID: "b1", Side: btypes.OrderBuy, Status: btypes.OrderOpen},
{OrderID: "o1", BondID: "b2", Side: btypes.OrderSell, Status: btypes.OrderOpen}, // dup
},
}
bz, _ := json.Marshal(gs)
if err := btypes.ValidateGenesis(bz); err == nil {
t.Error("ValidateGenesis should reject duplicate order-ids")
}
}
// TestValidateGenesisRejectsEmptyOrderBondID asserts an order with an empty
// bond-id is rejected.
func TestValidateGenesisRejectsEmptyOrderBondID(t *testing.T) {
gs := btypes.GenesisState{
Orders: []btypes.SecondaryOrder{{OrderID: "o1", BondID: "", Side: btypes.OrderBuy, Status: btypes.OrderOpen}},
}
bz, _ := json.Marshal(gs)
if err := btypes.ValidateGenesis(bz); err == nil {
t.Error("ValidateGenesis should reject empty order bond-id")
}
}
// TestValidateGenesisRejectsUnknownOrderSide asserts an unknown OrderSide is
// rejected.
func TestValidateGenesisRejectsUnknownOrderSide(t *testing.T) {
gs := btypes.GenesisState{
Orders: []btypes.SecondaryOrder{{OrderID: "o1", BondID: "b1", Side: btypes.OrderSide("Bogus"), Status: btypes.OrderOpen}},
}
bz, _ := json.Marshal(gs)
if err := btypes.ValidateGenesis(bz); err == nil {
t.Error("ValidateGenesis should reject unknown order side")
}
}
// TestValidateGenesisRejectsUnknownOrderStatus asserts an unknown OrderStatus
// is rejected.
func TestValidateGenesisRejectsUnknownOrderStatus(t *testing.T) {
gs := btypes.GenesisState{
Orders: []btypes.SecondaryOrder{{OrderID: "o1", BondID: "b1", Side: btypes.OrderBuy, Status: btypes.OrderStatus("Bogus")}},
}
bz, _ := json.Marshal(gs)
if err := btypes.ValidateGenesis(bz); err == nil {
t.Error("ValidateGenesis should reject unknown order status")
}
}
// TestValidateGenesisAcceptsCleanV3 asserts a clean v0.3 genesis (bonds +
// growth bonds + orders) validates.
func TestValidateGenesisAcceptsCleanV3(t *testing.T) {
gs := btypes.GenesisState{
Bonds: []btypes.Bond{
{BondID: "b1", IssuerStandID: "s1", CouponBps: 100, Status: btypes.BondIssued},
},
GrowthBonds: []btypes.GrowthBond{
{Bond: btypes.Bond{BondID: "gb1", IssuerStandID: "s1", CouponBps: 500, Status: btypes.BondIssued}, GrowthRateBps: 200},
{Bond: btypes.Bond{BondID: "gb2", IssuerStandID: "s1", CouponBps: 800, Status: btypes.BondActive}, GrowthRateBps: 0},
},
Orders: []btypes.SecondaryOrder{
{OrderID: "o1", BondID: "b1", Side: btypes.OrderBuy, PriceGrain: 950_000, HolderReachID: "r1", Status: btypes.OrderOpen, CreatedAt: 1000},
{OrderID: "o2", BondID: "gb1", Side: btypes.OrderSell, PriceGrain: 1_050_000, HolderReachID: "r2", Status: btypes.OrderFilled, CreatedAt: 2000},
},
}
bz, _ := json.Marshal(gs)
if err := btypes.ValidateGenesis(bz); err != nil {
t.Errorf("ValidateGenesis should accept clean v0.3 genesis, got: %v", err)
}
}
// TestValidateGrowthBondsAcceptsClean asserts the data-engineer's
// ValidateGrowthBonds helper accepts a clean set.
func TestValidateGrowthBondsAcceptsClean(t *testing.T) {
gbs := []btypes.GrowthBond{
{Bond: btypes.Bond{BondID: "gb1", CouponBps: 0, Status: btypes.BondIssued}, GrowthRateBps: 800},
{Bond: btypes.Bond{BondID: "gb2", CouponBps: 500, Status: btypes.BondActive}, GrowthRateBps: 300},
{Bond: btypes.Bond{BondID: "gb3", CouponBps: 800, Status: btypes.BondMatured}, GrowthRateBps: 0},
}
if err := btypes.ValidateGrowthBonds(gbs); err != nil {
t.Errorf("ValidateGrowthBonds should accept clean set; got: %v", err)
}
}
// TestValidateOrdersAcceptsClean asserts ValidateOrders accepts a clean set.
func TestValidateOrdersAcceptsClean(t *testing.T) {
orders := []btypes.SecondaryOrder{
{OrderID: "o1", BondID: "b1", Side: btypes.OrderBuy, Status: btypes.OrderOpen},
{OrderID: "o2", BondID: "b1", Side: btypes.OrderSell, Status: btypes.OrderFilled},
{OrderID: "o3", BondID: "b2", Side: btypes.OrderBuy, Status: btypes.OrderCancelled},
}
if err := btypes.ValidateOrders(orders); err != nil {
t.Errorf("ValidateOrders should accept clean set; got: %v", err)
}
}
// packageDir resolves a Go import path to its filesystem directory by
// walking up from this test file (v0.2 skeleton has zero external deps).
func packageDir(t *testing.T, importPath string) string {