DOCS / REFERENCE / UPDATES
Updates
COPIED FROM chimpdao-contracts/docs/UPGRADES.md · REVISION 6fd752349933
·
Repository ↗
How a purse or a Main account moves to new code after it is deployed: the policy, the fleet record and the keepalive. The mechanism is in ARCHITECTURE.md (§ Pocket, § Chimp account), the authority in AUTH.md, the operator procedure in RELEASE.md and what a client does in CLIENT-INTEGRATION.md § 6.
Who decides
A purse and a Main account hold their code the same way and are moved the same way. One policy decides it:
Manual (default) |
Managed (the holder’s signed opt-in) |
|
|---|---|---|
| Executable | a pinned wasm hash | a CAP-85 reference to the factory’s "pocket" or "account" entry |
| Moves when | a signer signs an update | the admin pins a new hash on the factory; nobody signs |
upgrade(hash) |
allowed | refused (UpgradeIsManaged: #403 Pocket, #511 account) |
| Who signs | the purse’s card; for an account, any signer, card or passkey | nobody |
Nobody is enrolled in Managed by default. It lets the factory’s admin key change the code
that guards the holder’s funds (a purse’s float and positions, or a Main’s primary funds and
signer sets), so a client must say that plainly before it asks for the signature
(“ChimpDAO will be able to change this account’s code”). The one safety argument for it is
recovery: a Managed contract that took a bad head is fixed by a re-pin, whatever its
__check_auth does; a Manual one on a broken __check_auth cannot sign its way out
(RELEASE.md).
Changing the policy is two steps, forced by the host (a custom-account frame holding
require_auth cannot also switch its executable to a reference): the holder signs
set_upgrade_policy, then anyone calls apply_upgrade_policy. Only a change of policy owes
an apply, and an apply is single-shot (NothingToApply, #405 Pocket, #512 account), so the
permissionless call is never a re-pin. Manual adopts the hash the fleet is on at the moment of
the apply. An apply that switches the executable emits apply_upgrade_policy
(ARCHITECTURE.md), so a service that follows a holder’s events sees the
switch; a refused apply emits nothing.
Neither route to new code needs a signer to be left. An apply is permissionless and a Managed
contract follows its factory, so both still work on an account whose signer sets abandon() has
emptied: an apply that was owed is carried out once, and an applied Managed account keeps moving
with the fleet. An abandoned account is unusable, not a burn address; nothing in this system treats
it as one.
An owed apply is a standing permission. Until it is carried out or cancelled, anyone can spend
it, once, when they choose: a Manual holder is then pinned to the head the factory reports at
that moment, not to the one it reported when the signer decided. upgrade and update cancel it.
The Pocket wasm the first mainnet purses were minted on is looser on both counts: every signed
set_upgrade_policy owes an apply, also one that changes nothing, and its upgrade cancels
none, so a purse can carry an owed apply from that code onto this one. A client therefore applies
right after every decision and right after every purse update
(CLIENT-INTEGRATION.md § 6.7), and the mainnet rollout settles every purse
before its first pin.
The fleet record
The factory is where the latest code is written down. fleet() returns it in one read:
Fleet { epoch: u32,
pocket: Option<hash>, pocket_history: Vec<hash>,
account: Option<hash>, account_history: Vec<hash> }
- Head:
pocket/account, the hash the fleet is on. Written byset_pocket_wasm_hashandset_account_wasm_hash(admin), which also write the CAP-85 entry"pocket"/"account"thatManagedcontracts follow. Both panic unless the wasm is already uploaded. - History: oldest first, the head last, at most 16 (the oldest is dropped). A hash is
appended when it becomes the head; re-pinning the head records nothing; pinning a hash the
history already holds moves it to the end, so a rollback reads
[B, A], not[A, B, A]. - Epoch: a counter that moves when a pin changes a head and when a seed adds a hash. It is the one value a client needs to read to learn whether anything it cached is stale. A head “changes” when it goes from none to some or to a different hash, judged against the stored head and never against the history’s last entry: after a seed on a kind with no head, pinning the hash that was seeded last is still a head moving from none, and counts. Re-pinning the identical head changes nothing recorded.
- Seed:
seed_history(kind, hashes)(admin) adds older hashes, oldest first, skipping known ones and putting them before the existing entries. It is idempotent and works in any order relative to a pin. A head with no recorded history reads as a history of itself, so a factory upgraded in place knows the release it replaces and nothing older.
An in-place factory upgrade needs seeding. Its histories start empty. Without the older
hashes, every contract still running them is “unknown”, is never offered an update, and the
update path silently never fires. Seed every factory once
(make contract_seed_history, RELEASE.md).
It also needs its Pocket head pinned again. A head written by a factory that kept no fleet
entry has no "pocket" entry behind it, and only a pin writes one. Until then a purse cannot
apply Managed, a Managed mint traps and refresh() skips the tag. make contract_upgrade_factory
and make contract_upgrade pin the same hash once with set_pocket_wasm_hash after the upgrade: an
identical head records nothing and moves no purse.
A factory that predates fleet() answers only pocket_wasm_hash(): the Pocket head, no history,
no account record, no epoch.
Keeping Managed holders alive
A Managed purse or account resolves its code through the factory’s "pocket" or "account"
entry, so those entries and the wasm code behind them must stay alive for it to be callable at
all. Each admin push extends only its own tag, which would leave a Managed holder depending on
how often the admin pushes. refresh() removes that dependency:
- Anyone may call it, with no authorization. It reads no argument and writes no head, history, epoch or authorization; it emits no event, because no recorded state moves.
- It extends, to the target the setters use (90 days, when under 30), the factory instance (and
its own code) and each of the
"pocket"and"account"entries that exists. A tag that was never pinned has no entry and is skipped, so it is safe on a fresh factory and on one upgraded in place. A second call right after the first changes nothing. - It cannot extend the wasm code entries behind the heads: the host extends a code entry only
through the address of a contract that runs it, never by hash, and
refreshtakes no address to run it from. Those are extended from outside,stellar contract extend --wasm-hashfor each head. make contract_refresh_fleetdoes both halves on a network:refreshon the recorded factory, then a code-entry extension for the heads the factory pins on the chain (code_ledgers, default 500000). Run it on a schedule, about every 30 days. An entry that has already been archived must be restored first; the RPC simulation says so.
An in-place factory upgrade is what adds refresh; before it a factory answers a call to it with
a missing-function error, and the target stops there.
What a client does
Reading a contract’s executable, judging it against fleet() (managed, upToDate, available,
custom), the update routes for a purse and a Main, the idempotent update, and what a client may
cache are in CLIENT-INTEGRATION.md § 6, and the order of signing for a
Managed Main in § 7. In short: a client reads the executable from the ledger, never from a cache,
and asks for no signature when the target is already running.
Operator procedure
Publish, canary, pin, read back, seed an in-place factory upgrade, roll back and keep alive: the steps and their order are RELEASE.md.