Versioning

Date: 2026-07-11
Authority: docs/00-product-constitution.md (UpgradeCap burn = launch gate)
Brand: DAY · Features: Auto Yield · Auto Pay · Vaults

---

0. Current operator stance (2026-07-11)

Do not lock contracts yet. Until mav says lock packages:

• Keep UpgradeCap held (never burn)
• Prefer unpublished or upgradeable test publishes only
• Do not treat any deploy as immutable launch-gate v1
• Off-chain *.v1 schemas can evolve carefully; on-chain freeze is a later explicit go

---

1. Why versioning is the whole game

Superform did not ship one forever-repo:

Generation	Repo	License	Shape
v1	superform-core	BSL 1.1 → GPL after 2y	Router + Forms + SuperPositions + xchain messaging
v2	v2-core	Apache 2.0	ERC-7579 executors, hooks, SuperLedger accounting

Lessons:

1. Major version = new package identity, not “edit main forever.”
2. Core freezes early so users can trust fee/withdraw/custody invariants.
3. Periphery evolves (adapters, hooks, keepers, UI) without rewriting core.
4. License can open over time (BSL → permissive) once product/moat is proven.
5. Audits + SECURITY.md attach to a version, not “the monorepo generally.”

On Sui, this is even stricter: packages are content-addressed. You don’t “patch v1” — you publish v2 package id and migrate.

---

2. DAY package map (versioned)

On-chain (Sui Move) — versioned packages

Package	Version policy	Immutable?	Contents
day_core (today: open_yield / XEL treasury)	v1, v2, v3… each a new package id	Yes after launch gate	Fee skim (500 bps yield-only), withdraw rules, harvest accounting, survival unstake, owner authority
day_adapters	Semver per adapter, independent	Optional / replaceable	Suilend, NAVI, Scallop, … thin wrappers; not custody
day_registry	Slow cadence	Config-gated, not full upgrade of money math	Venue allowlist, readiness flags

Hard rules (non-negotiable across versions):

• Stake OFF default
• Fee only on harvested yield (never deposit/withdraw/principal)
• Agent cannot withdraw principal
• Owner can always withdraw
• No team custody of principal

If a change violates any of the above → it is not a patch; it is a new major and needs explicit migration + owner approval.

Off-chain — semver surfaces

Surface	Version	Notes
HTTP API	auto-yield-plan.v1, day-api.v1	Schema version in payload (Superform StateRequest energy)
SDK	@dayprotocol/sdk@0.x → 1.x	Breaking = major
Keepers	harvest-plan.v1	Keepers process payloads; amounts from venue, not request body
Bridge	mayan-plan.v1	actualReceived vs minOut (Superform S7/S8)

---

3. Core vs periphery (steal Superform’s split)

┌─────────────────────────────────────────────┐
│ PUBLIC · dayprotocol/day (or day-core)      │
│  Move packages (versioned, audited)         │
│  Schemas · constitution · basic SDK         │
│  Adapter INTERFACES + mock adapters         │
└─────────────────────────────────────────────┘
                    ▲
                    │ calls / plans
┌─────────────────────────────────────────────┐
│ PRIVATE · XEL / GEN                         │
│  Hosted wallets · Infisical · keepers keys  │
│  Character mint · persona · ranking models  │
│  Live mainnet signer wiring                 │
└─────────────────────────────────────────────┘

Layer	Open (OSS)	Closed
Money invariants	Yes — Move sources + tests	Deploy keys
Venue adapters	Interface + mocks OSS; live roots optional	Signer + Infisical
Orchestrator	Reference scorer (TVL floor, fee net)	Advanced multi-goal agent
UI	App open or product-closed (choice)	—

---

4. Version lifecycle (how we ship like Superform)

Phase A — Pre-launch (now)

1. Develop under day repo (dayprotocol/day private until open).
2. Keep UpgradeCap on core package (XEL pattern: hard-pause capability before burn).
3. Version schemas as .v1 from day one.
4. Tag releases: contracts-v0.1.0-alpha, sdk-v0.1.0.

Phase B — Launch gate (public trust event)

1. Freeze core invariant surface (fee, withdraw, harvest order, default OFF).
2. External audit of that package id.
3. Burn UpgradeCap (or transfer to dead address) only when checklist green.
4. Publish package id + bytecode hash on docs.dayprotocol.com.
5. Open-source that tagged tree (or BSL-then-open if we want Superform-style delay).

Phase C — Post-launch evolution

1. Never mutate launched core package.
2. Ship v2 package for additive features (new fee modes, multi-venue receipts, etc.).
3. Migration = owner-signed move of positions / policy pointer to new package.
4. Adapters/keepers can ship weekly without new core major.

---

5. Concrete versioning rules for Day

5.1 Semantic versioning for releases

Bump	When
MAJOR (v1→v2)	Changes fee math, withdraw authority, custody model, default stake behavior, or breaks schema required fields
MINOR	New optional schema fields, new venue adapter, new plan kind (e.g. auto_pay)
PATCH	Bugfix that preserves invariants + schemas

5.2 Schema version never silent

Every plan/API response includes:

{ "schemaVersion": "auto-yield-plan.v1", ... }

Unknown schemaVersion → fail closed.

5.3 Adapter version independent of core

yield-venue:suilend@1.2.0
yield-venue:navi@1.0.3

Core v1 can talk to adapter 1.x; adapter 2.x only if core minor supports new action enum.

5.4 Git tags + package ids

git tag contracts/core-v1.0.0
# docs publish:
# package_id: 0x...
# digest: ...
# upgrade_cap: BURNED | 0x...

---

6. What to open-source, versioned

Publish first (OSS “core trust”)

1. docs/00 constitution + fee model
2. Move core fee/harvest/withdraw modules + tests
3. JSON schemas (*.v1.json)
4. @dayprotocol/sdk (typed client only)
5. Adapter interface + fixtures

Keep private until deliberate

• Hosted wallet key material / Infisical paths
• Live keeper signers
• Advanced opportunity ranking
• Character mint / persona pipeline

License options (pick before public core)

Option	Like Superform?	Use when
BSL 1.1 → Apache/GPL later	v1 Superform	Want OSS visibility without immediate competitive forks
Apache 2.0 from day 1	v2 Superform	Max ecosystem trust / agent adoption
MIT	—	Max simplicity

Recommendation: start private (now), launch with audited immutable core under Apache 2.0 or BSL-1.1 with 2-year flip — document the choice on docs.dayprotocol.com.

---

7. Superform patterns that require versions in our system

Superform idea	Day version surface
StateRequest	auto-yield-plan.v1
Forms (adapters)	venue-adapter.v1 interface
actual vs quoted bridge	bridge-receipt.v1 with actualReceived
rescue failed deposit	bridge-rescue.v1
SuperLedger cost basis / fees	harvest event schema YieldHarvested + fee bps in config
Core vs periphery	Move package freeze vs runtime keepers

---

8. Immediate checklist (actionable)

• Rename Move module brand path carefully: keep package version folders contracts/core/v1/ (not only open_yield forever)
• Every schema file ends in .v1.json; breaking change → .v2.json
• SDK exports SCHEMA_VERSION constants
• CI: refuse deploy if DEFAULT_PROTOCOL_YIELD_SKIM_BPS != 500 without major bump
• Docs page: Deployed package ids table (v1, v2, …)
• UpgradeCap burn runbook (XEL gate) linked from docs
• Public repo dayprotocol/core (or open day) only at tag, not floating main

---

9. Bottom line

Versioning is how we get Superform’s trust without copying EVM.

• Core money rules → immutable package versions (Sui-native).
• Adapters / keepers / UI → fast semver, replaceable.
• Schemas → explicit .v1 / .v2, never silent.
• Open source → publish a version, not a moving target.

DAY = versioned open execution + private intelligence. That is the system design.