Skip to main content
Soran separates protocol coordination from namespace operation. Protocol governance manages the shared contracts and approves Registrar and Resolver implementations. Each namespace owner chooses whether to install an approved implementation and enable its optional features. Registry, Primary, Allocator and Universal Lookup support authorized code upgrades at the same address. Namespace Registrar and Resolver upgrades also require the current namespace owner. The separate Funding contract has its own governance-authorized upgrade path. The governed testnet does not permit new irreversible code locks. The current testnet Allocator also has no mandatory code-upgrade wait. This policy was activated on 8 September 2026; see release status. Namespace claim, objection and reopening windows still apply.

​
Universal Lookup upgrade flow

  1. Governance authorizes propose_upgrade(wasm_hash) for one exact code hash.
  2. The proposal records the current ledger timestamp as execute_after, making it immediately eligible.
  3. Anyone may call execute_upgrade(expected_hash). The hash must equal the pending proposal.
  4. A successful execution replaces the contract’s Wasm at the same contract address and consumes the proposal. A failed replacement rolls back the transaction.
Governance can call cancel_upgrade() before execution, but zero delay leaves no guaranteed cancellation or review window. Read governance(), upgrade_delay() and pending_upgrade() to inspect a deployment. An upgrade keeps the Lookup address stable. Registry and version checks verify the reported connections and interface compatibility; they do not pin its executable code. If your integration requires a specific reviewed implementation, verify the current code too.

​
Allocator upgrade flow

  1. Governance authorizes propose_upgrade(new_wasm_hash) for one exact Wasm hash. The proposal stores eta as the current ledger timestamp.
  2. Anyone may call execute_upgrade_for(expected_wasm_hash) immediately. The supplied hash must still match the pending proposal.
  3. Successful execution replaces the Wasm at the same Allocator address and consumes the proposal. A failed replacement rolls back the transaction.
Only one proposal can be pending. Governance uses cancel_upgrade_for(expected_wasm_hash) to cancel the exact reviewed proposal before proposing another hash. Both bound methods reject a changed hash with UpgradeChanged (43). As with Lookup, immediate execution leaves no guaranteed review or cancellation window. The older execute_upgrade() and cancel_upgrade() remain available for compatibility. They act on whichever proposal is pending at execution time. New integrations should use the methods that bind the expected hash; their arguments use BytesN<32>. The stored eta still applies. The upgrade timing is separate from allocation rules. Claim windows and objection rules remain in place, and governance reopening proposals still wait one full allocation window.

​
Other contracts

Replacing a Resolver creates separate storage; its records do not move automatically. An upgrade at the same address still needs compatible storage and authorization rules. Allocator upgrades must preserve existing claims, fees and credits. The governed testnet rejects new permanent code locks. Historical locked contracts retain their original restrictions. Use the matching Registry, Lookup and G/C Primary addresses from release status. A familiar address or unchanged version number alone does not establish which code is running.

​
Registry, Primary and namespace upgrades

Registry and Primary accept upgrade(expected_hash, new_hash). The configured governance account must authorize the call, and the running Wasm must match expected_hash. These upgrades have no mandatory delay and retain the contract address and storage. For namespace contracts, governance first calls Registry’s approve_implementation(role, hash, true): role 0 is Registrar and role 1 is Resolver. The current namespace owner then authorizes the child’s upgrade(new_wasm_hash). Registry checks the current native pair and approved role/hash, then updates that namespace’s recorded executable pin and upgrade counter atomically. native_code(node) exposes the expected Registrar and Resolver hashes for an existing namespace. template_hashes() describes defaults for new deployments. Changing factory defaults does not upgrade existing namespace contracts. The 1 October release installed shared Lookup and Primary support and approved new namespace templates; existing owners still choose when to upgrade. Network-address permissions and subname creation must also be enabled separately. Revoking an implementation approval blocks future use; it does not undo a completed upgrade. Approval alone does not establish that a downgrade preserves every feature or stored record. Use the console or matching Owner SDK to review the current and proposed implementations before signing. Address stability does not remove governance trust or make every future storage change compatible. Inspect current code and read live payment instructions when using a name.