identity

Look up a VerusID by name or i-address. Returns the identity's current state including primary addresses, signing authorities, content data (contentmultimap), revocation/recovery authorities, and wallet relationship (canspendfor/cansignfor). Optionally retrieve the identity as it existed at a specific block height. Use this to check if an identity exists, inspect its configuration, or verify wallet authority before performing write operations.

Get identity content/data with optional VDXF key filter and height range. Returns the cumulative content state — all content across all updates within the specified range. Unlike getidentityhistory, this does not return per-revision snapshots. Use this to read structured data stored on an identity (profiles, timestamps, application data) without needing to process the full revision history.

Get the full revision history of a VerusID. Returns an array of identity snapshots, one per update transaction. Each entry shows the identity state as it was set in that specific transaction, along with the block hash, height, and transaction details. Use this to audit changes to an identity over time — primary address changes (transfers), content updates, authority changes, etc. Note: each history entry's contentmultimap shows only the content set in that specific update, not the cumulative state.

Get the VDXF key ID from a URI string. Converts a human-readable VDXF URI (e.g., "vrsc::system.currency.export") into its on-chain i-address representation. Optionally combine with additional data (another VDXF key, a 256-bit hash, or an index number) to derive bound keys. Use this to resolve VDXF key names to i-addresses before querying getidentitycontent with a vdxfkey filter.

List VerusIDs in the local wallet. Returns all identities that this wallet can spend for, sign for, or watch. Use this to discover which identities are available before performing identity operations. By default includes identities we can spend for and sign for, but not watch-only.

Recover a revoked or compromised identity. Only the recovery authority (or token recovery authority) can perform this. Typically used to set new primary addresses after a key compromise, effectively transferring control to new keys. Pass the full identity definition with the desired recovery state (new primary addresses, etc.). Always include "parent" in the identity definition. PRIVATEADDRESS BEHAVIOR: Omit privateaddress entirely to preserve the existing one (carried over). Pass null to clear/remove it. Include a new zs1... address to change it. Empty string "" does NOT clear — daemon treats it the same as omitting. TIMELOCK: Do NOT include timelock in the identity JSON unless you deliberately intend to set an absolute block height lock or clear an existing one. Omitting timelock resets it to 0 (unlocked) — timelock does NOT carry over like privateaddress does. To clear a timelock via recovery, simply omit the timelock field. If setting a timelock value, ensure revocationauthority and recoveryauthority are set to identities that can perform a future revoke+recover to remove it, since absolute locks CANNOT be removed by updateidentity. Use setidentitytimelock after recovery for safe timelock configuration. SAFETY: When setting new authorities during recovery, NEVER set revocationauthority to another identity while leaving recoveryauthority as self — if later revoked by the external authority, the identity cannot recover itself. This bricks the identity. If delegating revocation, always also delegate recovery to a different identity.

Step 2 of identity registration. Uses a confirmed name commitment to register the identity on-chain. The commitment must have been mined (wait 1 block after registernamecommitment). The tool checks for saved commitment data from a previous registernamecommitment call — if available, the agent does not need to pass the commitment details manually. On successful registration, the saved commitment file is cleaned up. IDENTITY DEFINITION: Keep it minimal — only include fields you are explicitly setting to non-default values. Omit revocationauthority/recoveryauthority to default to self. TIMELOCK: Do NOT include timelock in the identity JSON unless you deliberately intend to set an absolute block height lock. Omitting timelock defaults to 0 (unlocked). To configure timelocks safely after registration, use setidentitytimelock which provides setunlockdelay and unlockatblock controls. Setting a timelock value here creates an absolute block height lock that CANNOT be removed by updateidentity — only by revoke+recover. Omit privateaddress unless explicitly assigning one. SAFETY: NEVER set revocationauthority to another identity while leaving recoveryauthority as self — if the identity is revoked by the external authority, it cannot recover itself (recovery requires the recovery authority to act, and a revoked identity cannot authorize its own recovery). This bricks the identity. If delegating revocation, always also delegate recovery to a different identity. POSITIONAL PARAMS: The daemon RPC is positional: registeridentity jsonidregistration (returntx) (feeoffer) (sourceoffunds). If passing sourceoffunds, you must also fill returntx and feeoffer. FEE DISCOVERY: Call getcurrency (chain-mcp) on the parent currency to find idregistrationfees. For basket currencies, if idimportfees is a satoshi-scale value it encodes a reserve currency index: 0.00000000 = first reserve (index 0), 0.00000001 = second reserve (index 1), etc. The idregistrationfees amount is then denominated in that reserve currency — calculate how much of the basket currency equals that amount at current conversion prices. Example: idregistrationfees=15 + idimportfees=0.00000001 (index 1=USD) means 15 USD worth of the basket currency. Default idimportfees (e.g., 0.02) means the fee is in the basket currency itself, but defaults may differ per chain — check getcurrency to verify. FEE SHORTCUT: If unsure of the exact fee (especially with reserve-denominated fees and referral discounts), pass feeoffer=0.00000001 — the daemon will reject and return the minimum required fee in the error message, then retry with that amount.

Step 1 of identity registration. Creates a name commitment transaction that reserves a name without revealing it. The commitment hides the name itself while ensuring miners cannot front-run the registration. After this tool succeeds, wait 1 block before calling registeridentity (step 2). The commitment data is saved to disk so it persists across conversations — if a session ends before registration, the next session can pick up the commitment. Names must not have leading, trailing, or multiple consecutive spaces and must not include: \ / : * ? " < > | @

Revoke an identity, making it unable to spend funds or sign transactions. Only the revocation authority (or token revocation authority) can perform this action. A revoked identity can only be restored by the recovery authority using recoveridentity. This is a safety mechanism — use it if the identity's private keys are compromised.

Set or modify a timelock on a VerusID. Timelocking restricts when an identity can spend funds on this chain. This only affects the identity on the current chain. Two modes: - setunlockdelay: Set a delay (in blocks) that must pass after an unlock request. Sets flags=2 (delay lock active), timelock=N (the delay in blocks). The identity cannot spend until an unlock is triggered and the delay passes. - unlockatblock: Set an absolute block height at which the identity unlocks. When used with unlockatblock=0 on a delay-locked identity (flags=2), it TRIGGERS the unlock countdown — the daemon converts the delay into an absolute block height (approximately current_block + delay) and clears the delay flag. This is the standard way to initiate unlocking a delay-locked identity. unlockatblock=0 does NOT work on absolute block height locks (flags=0, timelock > 0) — those can only be removed by revoke+recover. Exactly one of unlockatblock or setunlockdelay must be specified. TIMELOCK WORKFLOW: 1) Set delay: setunlockdelay=N → identity locked with N-block delay. 2) Trigger unlock: unlockatblock=0 → countdown starts, identity unlocks at ~current_block+N. 3) Wait for block to pass. 4) Identity can spend again. To cancel a countdown (e.g., attacker triggered unlock), the revocation authority can revoke — revocation destroys the countdown entirely. Then recover to restore the identity with no timelock. REMOVING TIMELOCKS: Delay locks (flags=2) can be cleared by revoke+recover (omit timelock in recovery JSON). Absolute locks (flags=0, timelock > 0) can ONLY be cleared by revoke+recover. updateidentity CANNOT modify or remove any timelock once set.

Update an identity's fields — primary addresses, content, authorities, or any other mutable property. The wallet must hold authority to update (either primary authority, or token authority if tokenupdate is true). Pass the full identity definition with the desired changes. Fields not included revert to defaults — to preserve existing values, first read them with getidentity and include them in the update. Always include "parent" in the identity definition. PRIVATEADDRESS BEHAVIOR: Omit privateaddress entirely to preserve the existing one (carried over). Pass null to clear/remove it. Include a new zs1... address to change it. Empty string "" does NOT clear — daemon treats it the same as omitting. TIMELOCK: Do NOT include timelock in the identity JSON unless you deliberately intend to set an absolute block height lock. An absolute lock CANNOT be removed by updateidentity — only by revoke+recover. If setting a timelock, ensure revocationauthority and recoveryauthority are set to identities that can perform the revoke+recover to remove it. Omit timelock entirely to preserve the current value. Setting timelock to 0 is ONLY valid when there is no active timelock — it will be rejected if any timelock (delay or absolute) is currently set. Use setidentitytimelock for safe timelock configuration. SAFETY: NEVER set revocationauthority to another identity while leaving recoveryauthority as self — if revoked by the external authority, the identity cannot recover itself (a revoked identity cannot authorize its own recovery). This bricks the identity. If delegating revocation, always also delegate recovery to a different identity.