Docs
Virtual environmentsLocalnet

How to edit localnet account state

Apply administrative account changes through Studio and the localnet control API

Available since: Acton 1.2

Administrative actions create controlled account states for localnet tests. They can set balances, replace code or data, freeze accounts, make them uninitialized, delete them, or replace a complete ShardAccount.

Administrative edits replace account state across the localnet and may invalidate ongoing scenarios. Restore the prerequisite snapshot to recover. If automatic recovery fails, preserve the reported recovery files and logs.

Prerequisites

  • A localnet with all nodes running under NetworkNodes.
  • The target address and any replacement balance, code, data, or complete account bag of cells (BoC).
  • A snapshot of the original state.

Apply an account change

  1. Open Admin actions in the localnet workspace.
  2. Select an Action, such as Set balance, and enter the Account address.
  3. Enter the replacement value. Balance uses GRAM; code and data and complete account replacements accept a BoC in hex or base64.
  4. Select Apply changes and wait for completion. Studio pauses the network, saves recovery snapshots, applies the change on every node, and resumes it.

Freeze account, Make account uninitialized, and Delete account change account status rather than sending ordinary contract messages. To copy state from another network, use Import accounts.

There is no dedicated administrative subcommand. Prepare account-edit.json, replacing <OPERATION_UUID> with a fresh universally unique identifier (UUID) and <ADDRESS> with the target's raw address. This example sets its balance to 10 GRAM, expressed as a decimal string of nanograms:

account-edit.json
{
  "kind": "accounts",
  "id": "<OPERATION_UUID>",
  "edits": [{"address": "<ADDRESS>", "type": "balance", "balance": "10000000000"}]
}

Use the control connection, replacing <CONTROL_URL> and <CONTROL_TOKEN> with the service values:

curl --fail '<CONTROL_URL>/v1/network/admin' \
  -H 'Authorization: Bearer <CONTROL_TOKEN>' \
  -H 'content-type: application/json' --data-binary @account-edit.json

Poll the same operation UUID until finishedAt is non-null and error is null:

curl --fail '<CONTROL_URL>/v1/network/admin?id=<OPERATION_UUID>' \
  -H 'Authorization: Bearer <CONTROL_TOKEN>'

After a lost response, reuse the same UUID and identical payload to retry. Do not generate a new UUID until the previous operation's outcome is known. Reusing an ID with different edits is rejected.

Verify the changed state

Open the account in Explorer and inspect its balance, code, storage, and status. Administrative edits are hardforks, not normal contract transactions. Test normal message behavior separately.

Last updated on

On this page