Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cowboy.inc/llms.txt

Use this file to discover all available pages before exploring further.

​
Synopsis

cowboy upgrade-actor --actor <address> --code <path> [--manifest-json <path>] [flags]

​
Behavior

  1. Load the private key using key auto-discovery. The sender address must appear in genesis.system_deployers; the chain rejects upgrades from other senders.
  2. Read the new actor source from --code.
  3. Optionally read a new ActorManifest from --manifest-json. The new manifest must be a subset of the current manifest — you can drop entitlements, never add them.
  4. Submit an UpgradeActor transaction carrying the new code hash and manifest.
  5. Print the transaction hash.
The upgrade replaces the actor’s code starting from the next block. State is preserved — only the code changes.

​
Flags

FlagDefaultDescription
--actorRequiredTarget actor address (hex)
--codeRequiredPath to the new Python source file
--manifest-jsonNoneOptional new ActorManifest JSON (must be a subset of current)
--private-keyAuto-discoveredPath to private key file. Sender must be a system deployer
--rpc-urlAuto-discoveredRPC endpoint

​
Example

$ cowboy upgrade-actor --actor 0xdef456... --code actors/counter/v2.py
Transaction: 0xabc123...
  Upgrade queued for 0xdef456...

​
Edge Cases

  • Non-deployer sender — The transaction is accepted by the mempool but reverts on execution. The receipt will contain UpgradeNotAuthorized.
  • Manifest widening — Any entitlement in the new manifest that is not in the current manifest fails validation and reverts with ManifestWideningNotAllowed.
  • Same code hash — An upgrade to identical code is a no-op but still costs gas.