Ownership Changes Overview

Two operations move ownership of a deployment, and both are scoped to one setup (one deployment of a node on one network):

Operation	What changes on-chain	Shape	Endpoints
Node ownership change	Every tokenized asset deployed under the setup is transferred to a new wallet of the node, then the owner address on the setup's diamond is changed	Multi-step process that can be paused, resumed, retried and cancelled	/v2/admin/nodes/{node_id}/change-owner-processes/**
Platform owner change	The platform owner address on the setup's diamond	One on-chain transaction	/v2/admin/nodes/{node_id}/platform-owner-changes

Rules that apply to both

• The caller picks the setup and the wallet. setup_id and new_wallet_id are required body fields. The setup must belong to the node in the path, and the wallet must be on the chain of the setup's network. Nothing is resolved on the caller's behalf.
• Only the platform owner may start or drive a change. Every write (start, pause, resume, retry, cancel) checks that the API key belongs to the platform owner node (the platform root). Any other key gets 403 with code 10005, even when its token carries the route's permission.
• Reads follow the node hierarchy. Listing and reading are open to any key whose node is the node in the path or one of its ancestors. A node outside that subtree gets 403 with code 10005.
• One change at a time per setup. A second node ownership change on a setup is refused with 20002 while one is started, in_progress or paused. A second platform owner change is refused with 21002 while one is started or in_progress.

Node ownership change process

Start Change Owner Process builds the step list and answers 201 with the process in status started. The steps then run in the background, one at a time, in order:

Step type	How many	On-chain action
transfer_tokenized_assets	One per token deployed under the setup (token_id names it)	Transfers the token's ownership to the new owner address. Recorded as a node transaction of type 36 (TransferTokenizedAssetOwnership) on the setup's node.
change_node_owner	One, always last	Changes the owner address on the setup's diamond. Recorded as a node transaction of type 34 (ChangeNodeOwnerAddress) on the platform owner node, carrying the setup's platform owner wallet.

Every step is an on-chain transaction. A step is completed once its transaction is confirmed (its hash is then in transaction_hash), and only then is the next step sent. A setup with no deployed tokens has a single change_node_owner step. When the last step completes, the process becomes completed and the setup's node fee-recipient wallet is moved to the new wallet.

Poll Get Change Owner Process to follow it. Each step's transaction also appears in Get Node Transactions by ID.

Process status

status	Meaning
started	Created; the first step has not been sent yet.
in_progress	A step is being executed.
paused	Stopped: either paused by the caller, or a step failed. No further step is sent until it is resumed.
completed	Every step completed. Terminal.
failed	Terminal status in the vocabulary. A failing step does not set it: the step becomes failed and the process paused.
cancelled	Cancelled by the caller. Terminal.

Step status

status	Meaning
pending	Not sent yet.
in_progress	Its transaction has been sent and is not settled yet.
completed	Its transaction was confirmed.
failed	Its transaction failed, or it could not be sent. The reason is in the step's error.
skipped	Treated like completed when the process advances and when progress is computed.

progress is the share of completed and skipped steps, from 0 to 100.

Lifecycle

Action	Allowed from	Effect	Refused with
Pause	started, in_progress	Process becomes paused.	20005
Resume	paused	Process becomes in_progress and continues from current_step_order; a step that already completed is not sent again. A failed step is not re-run: use Retry for it.	20003
Retry	A failed step of a paused process	The step goes back to pending, its retry_count grows by one, and the process resumes from it. A step can be retried max_retries (3) times.	20003, 20004, 20006
Cancel	started, in_progress, paused	Process becomes cancelled.	20003

Pause and cancel stop the process from sending the next step; they do not recall a transaction that was already sent. That transaction still settles and its step is recorded as completed or failed. If the final step confirms while the process is paused, the process still becomes completed. Cancelling does not undo transfers that already completed.

Platform owner change

Start Platform Owner Change sends one transaction that replaces the platform owner address on the setup's diamond, recorded as a node transaction of type 35 (ChangePlatformOwnerAddress) on the platform owner node. There are no steps, and it cannot be paused, retried or cancelled.

• The new wallet must be one of the platform owner's own wallets, on the setup's chain.
• The setup must allow it. Whether the platform owner may change its own wallet is the platform setting platform_owner_can_change_wallet, copied onto each setup when the setup is created (the diamond is deployed with it). The start endpoint reads the setup's copy, so turning the setting on later does not enable older setups. See Update Platform Owner Can Change Wallet.

The change is answered with status in_progress. Poll List Platform Owner Changes until it reads done (the transaction hash is in hash, and the setup's platform owner fee-recipient wallet now points at the new wallet) or error (the reason is in error).