# Identity Commands

Placeholder convention: Examples in this reference use myid@ as your own identity, recovery@ / revocation@ as authority-role identities, yourapp@ as an application namespace, i... to mark a placeholder i-address (substitute your own from getidentity), <R-address> / <your-R-address> for transparent R-addresses, and <block-height> for a placeholder block number. Commands shown were tested on VRSCTEST — only these project-specific values have been genericized.

Category: Identity | Version: v1.2.x+

Returns all identities that contain a specified address in their primary addresses. Requires the daemon to be started with -idindex=1.

Syntax

verus getidentitieswithaddress '{"address":"validprimaryaddress","fromheight":height,"toheight":height,"unspent":false}'

Result

[
  {
    "identity": { ... },
    "txout": { "txhash": "...", "index": 0 }
  }
]

An array of matching identity objects, each with an additional txout field containing the transaction hash and output index.

Examples

Basic Usage

./verus -testnet getidentitieswithaddress '{"address":"<your-R-address>"}'

## Actual Output (tested on VRSCTEST)
## ERROR: requires -idindex=1 when starting the daemon

⚠️ This command requires the daemon to be started with -idindex=1. Without this flag, the command returns an error. The identity index is not enabled by default because it increases disk usage and sync time.

With Height Range and Unspent Filter

./verus -testnet getidentitieswithaddress '{"address":"<your-R-address>","fromheight":920000,"toheight":930000,"unspent":true}'

RPC (curl)

curl -s -u user1445741888:pass2f0dc70dded67b9f392c0f3950a547bc6ef4d1edfa78da3a7da5b78113def067b6 \
  -X POST http://localhost:18843 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"1.0","id":"wiki","method":"getidentitieswithaddress","params":[{"address":"<your-R-address>"}]}'

Common Use Cases

• Reverse lookup: Find which identities are controlled by a specific address
• Audit: Discover all identities a particular key controls
• Multi-sig investigation: Find identities that include a specific co-signer address

Related Commands

• getidentitieswithrecovery — Find identities by recovery authority
• getidentitieswithrevocation — Find identities by revocation authority
• getidentity — Look up a specific identity by name or i-address

Notes

• Requires -idindex=1 daemon flag. This builds an address-to-identity index on disk. Without it, the command cannot function.
• To enable: stop the daemon, restart with verusd -testnet -idindex=1. This may require a reindex on first run.
• The unspent parameter is useful for filtering out historical (spent) identity UTXOs and showing only the current active state.
• This is a "reverse lookup" — instead of looking up an identity by name, you find identities by one of their constituent addresses.

Tested On

• VRSCTEST block height: 926957
• Verus version: 1.2.14-2
• Note: Testing returned error because daemon was not started with -idindex=1

Category: Identity | Version: v1.2.x+

Returns all identities where a specified identity is set as the recovery authority. Requires the daemon to be started with -idindex=1.

Syntax

verus getidentitieswithrecovery '{"identityid":"idori-address","fromheight":height,"toheight":height,"unspent":false}'

Result

[
  {
    "identity": { ... },
    "txout": { "txhash": "...", "index": 0 }
  }
]

An array of identity objects where the specified ID is the recovery authority.

Examples

Basic Usage

./verus -testnet getidentitieswithrecovery '{"identityid":"recovery@"}'

## Actual Output (tested on VRSCTEST)
## ERROR: requires -idindex=1 when starting the daemon

⚠️ Requires -idindex=1 daemon flag.

Only Active Identities

./verus -testnet getidentitieswithrecovery '{"identityid":"recovery@","unspent":true}'

RPC (curl)

curl -s -u user1445741888:pass2f0dc70dded67b9f392c0f3950a547bc6ef4d1edfa78da3a7da5b78113def067b6 \
  -X POST http://localhost:18843 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"1.0","id":"wiki","method":"getidentitieswithrecovery","params":[{"identityid":"recovery@"}]}'

Common Use Cases

• Recovery authority audit: Find all identities you are responsible for recovering
• Security review: Check which identities depend on a specific recovery authority
• Identity management: Inventory all IDs under your recovery umbrella

Related Commands

• getidentitieswithrevocation — Find identities by revocation authority
• getidentitieswithaddress — Find identities by primary address
• getidentity — Look up a specific identity

Notes

• Requires -idindex=1 daemon flag. See getidentitieswithaddress for details.
• By default, an identity's recovery authority is set to itself. This means querying an identity like "recovery@" will return that identity itself, plus any others that have explicitly set it as their recovery authority.
• Recovery authority is the identity that can recover (regain control of) an identity if primary keys are compromised.

Tested On

• VRSCTEST block height: 926957
• Verus version: 1.2.14-2
• Note: Testing returned error because daemon was not started with -idindex=1

Category: Identity | Version: v1.2.x+

Returns all identities where a specified identity is set as the revocation authority. Requires the daemon to be started with -idindex=1.

Syntax

verus getidentitieswithrevocation '{"identityid":"idori-address","fromheight":height,"toheight":height,"unspent":false}'

Result

[
  {
    "identity": { ... },
    "txout": { "txhash": "...", "index": 0 }
  }
]

An array of identity objects where the specified ID is the revocation authority.

Examples

Basic Usage

./verus -testnet getidentitieswithrevocation '{"identityid":"revocation@"}'

## Actual Output (tested on VRSCTEST)
## ERROR: requires -idindex=1 when starting the daemon

⚠️ Requires -idindex=1 daemon flag.

Only Active Identities

./verus -testnet getidentitieswithrevocation '{"identityid":"revocation@","unspent":true}'

RPC (curl)

curl -s -u user1445741888:pass2f0dc70dded67b9f392c0f3950a547bc6ef4d1edfa78da3a7da5b78113def067b6 \
  -X POST http://localhost:18843 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"1.0","id":"wiki","method":"getidentitieswithrevocation","params":[{"identityid":"revocation@"}]}'

Common Use Cases

• Revocation authority audit: Find all identities you can revoke
• Security review: Understand the scope of a revocation authority's power
• Key rotation planning: Before changing a revocation authority, identify all affected identities

Related Commands

• getidentitieswithrecovery — Find identities by recovery authority
• getidentitieswithaddress — Find identities by primary address
• getidentity — Look up a specific identity

Notes

• Requires -idindex=1 daemon flag.
• Revocation authority is the identity that can revoke (disable) an identity. This is a critical security role.
• By default, an identity's revocation authority is set to itself. This means querying an identity like "revocation@" will return that identity itself, plus any others that have explicitly set it as their revocation authority.
• Revoking an identity prevents it from being used for signing or spending until it is recovered by the recovery authority.

Tested On

• VRSCTEST block height: 926957
• Verus version: 1.2.14-2
• Note: Testing returned error because daemon was not started with -idindex=1

Category: Identity | Version: v1.2.x+

Retrieves the full identity object for a given VerusID name or i-address, optionally at a specific block height and with transaction proof.

Syntax

verus getidentity "name@ || iid" (height) (txproof) (txproofheight)

Result Returns a JSON object containing the full identity definition, status, and metadata.

{
  "friendlyname": "myid.VRSCTEST@",
  "fullyqualifiedname": "myid.VRSCTEST@",
  "identity": {
    "version": 3,
    "flags": 0,
    "primaryaddresses": [
      "<R-address>"
    ],
    "minimumsignatures": 1,
    "name": "myid",
    "identityaddress": "i...",
    "parent": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
    "systemid": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
    "contentmap": {},
    "contentmultimap": { ... },
    "revocationauthority": "i...",
    "recoveryauthority": "i...",
    "timelock": 0
  },
  "status": "active",
  "canspendfor": true,
  "cansignfor": true,
  "blockheight": <block-height>,
  "txid": "51e1261ab8f5899dc7480b9b546f0b03a9c054fb160fd9f9dbdfec62d954379c",
  "vout": 0
}

Examples

Basic Usage — Lookup by Name

./verus -testnet getidentity "myid@"

Lookup by i-Address

./verus -testnet getidentity "i..."

Lookup at a Specific Block Height

## Get identity as it was at a specific block height (before any updates)
./verus -testnet getidentity "myid@" <block-height>

## Output shows empty contentmultimap (identity was freshly registered)
{
  "friendlyname": "myid.VRSCTEST@",
  "identity": {
    "version": 3,
    "primaryaddresses": ["<R-address>"],
    "name": "myid",
    "contentmultimap": {},
    ...
  },
  "blockheight": <block-height>,
  ...
}

Include Mempool (Unconfirmed Updates)

./verus -testnet getidentity "myid@" -1

With Transaction Proof

./verus -testnet getidentity "myid@" <block-height> true

Lookup a SubID

./verus -testnet getidentity "alice.yourapp@"

RPC (curl)

curl -s -u user1445741888:pass2f0dc70dded67b9f392c0f3950a547bc6ef4d1edfa78da3a7da5b78113def067b6 \
  -X POST http://localhost:18843 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"1.0","id":"wiki","method":"getidentity","params":["myid@"]}'

Common Use Cases

• Verify an identity exists before sending funds
• Check primary addresses to confirm ownership
• Inspect contentmultimap for on-chain metadata (e.g., agent profiles, VDXF data)
• Historical lookups to see an identity's state at a past block height
• Proof generation for cross-chain or SPV verification

Related Commands

• getidentityhistory — Get all historical versions of an identity
• getidentitycontent — Get aggregated content across identity history
• listidentities — List identities in the local wallet
• registernamecommitment — First step to registering a new identity

Name Qualification

Be careful with name qualification — it's the most common source of "Identity not found" errors:

• "alice@" → looks for a top-level identity called "alice"
• "alice.yourapp@" → looks for a SubID "alice" under the "yourapp" namespace
• "alice.VRSCTEST@" → fully qualified top-level name on testnet

These are different identities! If alice only exists as a SubID under yourapp, then getidentity "alice@" will return "Identity not found" while getidentity "alice.yourapp@" succeeds.

Notes

• The @ suffix is required when looking up by name (e.g., "myid@" not "myid").
• On VRSCTEST, names are displayed as name.VRSCTEST@ in fullyqualifiedname.
• The contentmultimap stores hex-encoded data keyed by VDXF i-addresses. Decode the hex to see the actual content.
• When flags = 1, the identity can issue subIDs (has the activecurrency flag set).
• canspendfor and cansignfor are wallet-relative — they indicate whether the current wallet has the keys.

Tested On

• VRSCTEST block height: 926957
• Verus version: 1.2.14-2

Category: Identity | Version: v1.2.x+

Retrieves the aggregated content stored on an identity across all its historical updates, combining contentmap and contentmultimap values within a specified block range.

Syntax

verus getidentitycontent "name@ || iid" (heightstart) (heightend) (txproofs) (txproofheight) (vdxfkey) (keepdeleted)

Result Returns identity metadata plus a combined contentmultimap aggregated from all identity updates in the specified range. Unlike getidentity which shows only the latest state, this command collects all content values ever written across updates.

{
  "fullyqualifiedname": "myid.VRSCTEST@",
  "status": "active",
  "canspendfor": true,
  "cansignfor": true,
  "blockheight": <block-height>,
  "fromheight": 0,
  "toheight": 926957,
  "txid": "51e1261ab8f5899dc7480b9b546f0b03a9c054fb160fd9f9dbdfec62d954379c",
  "vout": 0,
  "identity": {
    "version": 3,
    "name": "myid",
    "identityaddress": "i...",
    "contentmultimap": {
      "iKLo9XnNwzec2dj92kX9QQpng5EfU8XHxo": [
        "7b2276657273696f6e223a22312e30222c2274797065223a224149204167656e74227d",
        "7b2276657273696f6e223a22312e30222c2274797065223a224149204167656e74227d",
        "..."
      ]
    },
    "..."
  }
}

Important: The contentmultimap in this response aggregates values from every identity update in the height range. This means duplicate entries appear if the same key was included in multiple updates. The fromheight and toheight fields confirm the search range.

Examples

Basic Usage

./verus -testnet getidentitycontent "myid@"

Content from a Specific Height Range

## Only get content added between blocks 925000 and 926000
./verus -testnet getidentitycontent "myid@" 925000 926000

Include Mempool Content

./verus -testnet getidentitycontent "myid@" 0 -1

Filter by VDXF Key

## iKLo9XnNwzec2dj92kX9QQpng5EfU8XHxo is the i-address of `vrsc::system.agent.profile`, a built-in Verus system VDXF key — `getvdxfid` produces the same hash for everyone
./verus -testnet getidentitycontent "myid@" 0 0 false 0 "iKLo9XnNwzec2dj92kX9QQpng5EfU8XHxo"

Include Deleted Content

./verus -testnet getidentitycontent "myid@" 0 0 false 0 "*" true

RPC (curl)

curl -s -u user1445741888:pass2f0dc70dded67b9f392c0f3950a547bc6ef4d1edfa78da3a7da5b78113def067b6 \
  -X POST http://localhost:18843 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"1.0","id":"wiki","method":"getidentitycontent","params":["myid@"]}'

Common Use Cases

• Audit trail: See all content ever written to an identity across all updates
• Content aggregation: Collect all service listings, profile data, or VDXF records
• Selective queries: Use vdxfkey to search for specific content types
• Forensic analysis: Use keepdeleted to recover removed content

Related Commands

• getidentity — Get current state of an identity (latest update only)
• getidentityhistory — Get full identity objects at each update point

Notes

• Unlike getidentity which returns only the current content, getidentitycontent aggregates across all updates. This means you'll see duplicate entries for content that was present in multiple updates.
• Content values are hex-encoded. Decode with standard hex-to-string conversion.
• The vdxfkey parameter is useful for efficiently querying a specific data type without downloading all content.
• keepdeleted is valuable for auditing — content that was removed in a later update can still be retrieved.

Tested On

• VRSCTEST block height: 926957
• Verus version: 1.2.14-2

Category: Identity | Version: v1.2.x+

Retrieves the complete history of an identity, returning the full identity object at each update point within a specified block range.

Syntax

verus getidentityhistory "name@ || iid" (heightstart) (heightend) (txproofs) (txproofheight)

Result Returns identity metadata plus a history array containing the full identity object at each update, in chronological order.

{
  "fullyqualifiedname": "myid.VRSCTEST@",
  "status": "active",
  "canspendfor": true,
  "cansignfor": true,
  "blockheight": <block-height>,
  "txid": "51e1261ab8f5899dc7480b9b546f0b03a9c054fb160fd9f9dbdfec62d954379c",
  "vout": 0,
  "history": [
    {
      "identity": {
        "version": 3,
        "name": "myid",
        "contentmultimap": {}
      },
      "blockhash": "208172af9b283a1f06e5775f532134d6858393b076808fe415ea960dcca74125",
      "height": <block-height>,
      "output": {
        "txid": "b4af174d4bee117a8f6bd4fa47e5f0195d1409302aca4aeba08acd391e5c9954",
        "voutnum": 0
      }
    },
    {
      "identity": {
        "version": 3,
        "name": "myid",
        "contentmultimap": {
          "iKLo9XnNwzec2dj92kX9QQpng5EfU8XHxo": ["..."]
        }
      },
      "blockhash": "00000000e60e18baa0daa50c6d55186face08c2f6d39ddc2557021cef7ef1130",
      "height": <block-height>,
      "output": { "txid": "edcfe0a06a...", "voutnum": 0 }
    }
  ]
}

(Output truncated — example identity had multiple historical updates across a range of blocks)

Examples

Full History

./verus -testnet getidentityhistory "myid@"

History in a Block Range

## Only show updates between blocks 925000 and 926000
./verus -testnet getidentityhistory "myid@" 925000 926000

Include Mempool

./verus -testnet getidentityhistory "myid@" 0 -1

RPC (curl)

curl -s -u user1445741888:pass2f0dc70dded67b9f392c0f3950a547bc6ef4d1edfa78da3a7da5b78113def067b6 \
  -X POST http://localhost:18843 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"1.0","id":"wiki","method":"getidentityhistory","params":["myid@"]}'

Common Use Cases

• Track identity changes over time (address changes, content updates, authority changes)
• Audit revocation/recovery authority changes for security analysis
• Reconstruct timeline of content updates to an identity
• Detect unauthorized modifications by comparing expected vs. actual state at each point

Related Commands

• getidentity — Get current identity state only
• getidentitycontent — Get aggregated content across updates

Notes

• Each entry in the history array represents a complete snapshot of the identity at that block height. You can see exactly what changed between updates by diffing consecutive entries.
• The first entry is always the identity registration (creation) transaction.
• Multiple updates can occur at the same block height — for example, if an identity has a key rotation and a content update in the same block.
• For identities with many updates, the response can be large. Use heightstart/heightend to limit scope.

Tested On

• VRSCTEST block height: 926957
• Verus version: 1.2.14-2

Category: Identity | Version: v1.2.x+

Retrieves identity trust/rating settings for the local node. These settings control which identities the node will sync data for, acting as a local allowlist/blocklist system.

Syntax

verus getidentitytrust '["id",...]'

Result

{
  "setratings": { "id": JSONRatingObject, ... },
  "identitytrustmode": 0
}

Examples

Get All Trust Settings

./verus -testnet getidentitytrust '[]'

## Actual Output (tested on VRSCTEST)
## (empty output — no trust ratings configured on this node)

Query Specific Identity

./verus -testnet getidentitytrust '["myid@"]'

## Actual Output (tested on VRSCTEST)
## (empty output — no rating set for myid@)

RPC (curl)

curl -s -u user1445741888:pass2f0dc70dded67b9f392c0f3950a547bc6ef4d1edfa78da3a7da5b78113def067b6 \
  -X POST http://localhost:18843 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"1.0","id":"wiki","method":"getidentitytrust","params":[["myid@"]]}'

Common Use Cases

• Check trust configuration: See which identities are allowed/blocked for sync
• Audit node settings: Verify trust mode before deploying
• Content filtering: Use in conjunction with setidentitytrust to control what data your node syncs

Related Commands

• setidentitytrust — Set trust ratings for identities
• getidentity — Look up an identity

Notes

• When no trust ratings are configured and identitytrustmode is 0, the node syncs all identity data without restriction.
• Trust mode 1 (allowlist) is the most restrictive — only explicitly approved IDs sync.
• Trust mode 2 (blocklist) syncs everything except blocked IDs.
• This is a local node setting — it does not affect the blockchain or other nodes.
• The command returns empty output (not an error) when no ratings are set.

Tested On

• VRSCTEST block height: 926957
• Verus version: 1.2.14-2

Category: Identity | Version: v1.2.x+

Lists all identities in the local wallet, with options to filter by spending, signing, or watch-only capability.

Syntax

verus listidentities (includecanspend) (includecansign) (includewatchonly)

Result Returns an array of identity objects with wallet-specific status fields.

[
  {
    "identity": {
      "version": 3,
      "flags": 0,
      "primaryaddresses": ["<R-address>"],
      "minimumsignatures": 1,
      "name": "myid",
      "identityaddress": "i...",
      "parent": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
      "systemid": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
      "contentmap": {},
      "contentmultimap": { "..." },
      "revocationauthority": "i...",
      "recoveryauthority": "i...",
      "timelock": 0
    },
    "blockheight": <block-height>,
    "txid": "51e1261ab8f5899dc7480b9b546f0b03a9c054fb160fd9f9dbdfec62d954379c",
    "status": "active",
    "canspendfor": true,
    "cansignfor": true
  },
  {
    "identity": {
      "name": "yourapp",
      "flags": 1,
      "identityaddress": "i...",
      "..."
    },
    "blockheight": 926587,
    "status": "active",
    "canspendfor": true,
    "cansignfor": true
  },
  {
    "identity": {
      "name": "mymultisig",
      "primaryaddresses": [
        "<R-address-1>",
        "<R-address-2>"
      ],
      "minimumsignatures": 2,
      "..."
    },
    "status": "active",
    "canspendfor": false,
    "cansignfor": true
  }
]

(Output truncated — test wallet contained 10 identities including myid@, yourapp@, alice.yourapp@, bob.yourapp@, and others)

Notable Observations from Testing

• canspendfor: true — wallet has enough keys to meet minimumsignatures
• canspendfor: false, cansignfor: true — wallet has some keys but not enough (e.g., mymultisig@ requires 2 of 2 sigs, wallet only has 1 key)
• SubIDs (like alice.yourapp@) appear alongside top-level IDs

Examples

List All Spendable Identities (Default)

./verus -testnet listidentities

Only Signable (Not Spendable)

./verus -testnet listidentities false true false

Include Watch-Only

./verus -testnet listidentities true true true

RPC (curl)

curl -s -u user1445741888:pass2f0dc70dded67b9f392c0f3950a547bc6ef4d1edfa78da3a7da5b78113def067b6 \
  -X POST http://localhost:18843 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"1.0","id":"wiki","method":"listidentities","params":[true]}'

Common Use Cases

• Wallet inventory: See all identities controlled by this wallet
• Multi-sig audit: Identify which identities the wallet can sign for but not fully spend
• Application startup: Enumerate available identities for a user interface

Related Commands

• getidentity — Get details for a specific identity
• registernamecommitment — Begin registering a new identity
• registeridentity — Complete identity registration

Notes

• This command only shows identities for which the local wallet has relevant keys. It does not search the entire blockchain.
• The distinction between canspendfor and cansignfor matters for multi-sig identities. A wallet might hold 1 of 2 required keys — it can sign but not spend alone.
• SubIDs (e.g., alice.yourapp@) appear in the list if the wallet holds their keys, even if the parent identity is a different wallet.
• The flags field value of 1 indicates the identity has the activecurrency flag (can issue subIDs).

Tested On

• VRSCTEST block height: 926957
• Verus version: 1.2.14-2

Category: Identity | Version: v1.2.x+

⚠️ SENSITIVE — Recover a revoked VerusID by providing a new identity definition with updated keys.

Syntax

verus recoveridentity "jsonidentity" (returntx) (tokenrecover) (feeoffer) (sourceoffunds)

Result

transactionid    (string) txid if returntx is false, or hex transaction if returntx is true

Examples

⚠️ UNTESTED — Recovery is only possible on revoked identities

Basic Usage

## Recover a revoked identity with new primary addresses
./verus -testnet recoveridentity '{"name":"myname", "primaryaddresses":["RNewAddressHere"], "minimumsignatures":1}'

Full Recovery with New Authorities

./verus -testnet recoveridentity '{
  "name": "myname",
  "primaryaddresses": ["RNewAddress1"],
  "minimumsignatures": 1,
  "revocationauthority": "newrevoker@",
  "recoveryauthority": "newrecoverer@"
}'

RPC (curl)

curl --user user:pass --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"recoveridentity","params":[{"name":"myname","primaryaddresses":["RNewAddr"],"minimumsignatures":1}]}' -H 'content-type: text/plain;' http://127.0.0.1:27486/

Common Use Cases

• Key compromise recovery — revoke the identity, then recover with fresh keys
• Key rotation — revoke + recover as a way to completely rotate all identity keys
• Regain access — recover an identity that was revoked (intentionally or by revocation authority)

Related Commands

• revokeidentity — Revoke an identity (required before recovery)
• updateidentity — Update identity (for non-revoked IDs)
• getidentity — Check current identity status

Notes

• Recovery requires the recovery authority keys — not the primary keys or revocation authority
• The identity must be in a revoked state before it can be recovered
• Recovery lets you set completely new primary addresses, effectively rotating all keys
• You can also change the revocation and recovery authorities during recovery
• This is the last line of defense — if both primary keys AND recovery authority are compromised, the identity is lost
• Best practice: set recovery authority to a cold-storage identity or a trusted multisig
• For subIDs, include the parent field (same gotcha as updateidentity)

Tested On

• ⚠️ Not tested (requires a revoked identity)
• VRSCTEST block height: 926957
• Verus version: 2000753

Category: Identity | Version: v1.2.x+

Register a new VerusID identity on-chain using a prior name commitment.

Syntax

verus registeridentity "jsonidregistration" (returntx) (feeoffer) (sourceoffunds)

jsonidregistration Structure

{
  "txid": "hexid",
  "namereservation": {
    "name": "namestr",
    "salt": "hexstr",
    "referral": "identityID",
    "parent": "",
    "nameid": "iAddress",
    "version": 1
  },
  "identity": {
    "name": "namestr",
    "primaryaddresses": ["Raddress"],
    "minimumsignatures": 1,
    "revocationauthority": "nameorID",
    "recoveryauthority": "nameorID",
    "privateaddress": "zs-address"
  }
}

Result

transactionid    (string) The transaction ID of the registration

Examples

⚠️ UNTESTED — Registration requires a prior registernamecommitment and costs VRSC

Two-Step Registration Process

## Step 1: Create a name commitment (returns txid, salt, etc.)
./verus -testnet registernamecommitment "myname" "controladdress" "referralID"

## Step 2: Register using the commitment output
./verus -testnet registeridentity '{
  "txid": "commitment_txid_hex",
  "namereservation": {
    "name": "myname",
    "salt": "salt_from_commitment",
    "referral": "referralID@",
    "parent": "",
    "nameid": "nameid_from_commitment",
    "version": 1
  },
  "identity": {
    "name": "myname",
    "primaryaddresses": ["<your-R-address>"],
    "minimumsignatures": 1,
    "version": 3
  }
}'

RPC (curl)

curl --user user:pass --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"registeridentity","params":[{"txid":"hexid","namereservation":{"name":"myname","salt":"hexsalt","referral":""},"identity":{"name":"myname","primaryaddresses":["Raddr"],"minimumsignatures":1}}]}' -H 'content-type: text/plain;' http://127.0.0.1:27486/

Common Use Cases

• Creating a new VerusID — the standard way to register an identity after name commitment
• Multisig identity — specify multiple primaryaddresses and set minimumsignatures > 1
• With referral — include a referral identity for fee discount

Related Commands

• registernamecommitment — Step 1: create a name commitment (required before registeridentity)
• getidentity — Look up a registered identity
• updateidentity — Modify an existing identity
• listidentities — List identities in wallet

Notes

• Registration is a two-step process: first registernamecommitment, then registeridentity
• The name commitment must be mined (1 confirmation) before registration
• Name commitments expire — register promptly after commitment confirms
• Registration fee varies by chain; use feeoffer to override
• Identity names are case-insensitive and unique per parent chain
• Once registered, an identity cannot be deleted, only revoked/recovered

Tested On

• ⚠️ Not directly tested (destructive/costly operation)
• VRSCTEST block height: 926957
• Verus version: 2000753

Category: Identity | Version: v1.2.x+

Registers a name commitment, which is the required first step for registering a new VerusID. The commitment hides the desired name in a hash to prevent front-running by miners, while ensuring fair name registration.

Syntax

verus registernamecommitment "name" "controladdress" ("referralidentity") ("parentnameorid") ("sourceoffunds")

Result

{
  "txid": "hexid",
  "namereservation": {
    "name": "namestr",
    "salt": "hexstr",
    "referral": "identityaddress",
    "parent": "namestr",
    "nameid": "address"
  }
}

Examples

Basic Name Commitment

./verus -testnet registernamecommitment "mynewid" "<your-R-address>"

With Referral Identity

./verus -testnet registernamecommitment "mynewid" "<your-R-address>" "myid@"

SubID Under a Parent Namespace

./verus -testnet registernamecommitment "newname" "<your-R-address>" "" "yourapp@"

RPC (curl)

curl -s -u user1445741888:pass2f0dc70dded67b9f392c0f3950a547bc6ef4d1edfa78da3a7da5b78113def067b6 \
  -X POST http://localhost:18843 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"1.0","id":"wiki","method":"registernamecommitment","params":["mynewid","<your-R-address>"]}'

Common Use Cases

• Step 1 of identity registration: Always required before registeridentity
• Name squatting prevention: The commitment-reveal scheme prevents miners from stealing names
• SubID creation: Use parentnameorid to create identities under a namespace you control

Two-Step Registration Process

1. registernamecommitment — Creates a hidden commitment (this command)
2. Wait for the commitment to be mined (at least 1 confirmation)
3. registeridentity — Reveals the name and completes registration using the commitment output

## Step 1: Commit
./verus -testnet registernamecommitment "myname" "RMyAddress..."

## Step 2: Wait for confirmation, then register
./verus -testnet registeridentity '{"txid":"<txid>","namereservation":{"name":"myname","salt":"<salt>","nameid":"<nameid>"},"identity":{"name":"myname","primaryaddresses":["RMyAddress..."],"minimumsignatures":1}}'

Name Rules Names must not have:

• Leading, trailing, or multiple consecutive spaces
• Any of these characters: \ / : * ? " < > | @

Related Commands

• registeridentity — Step 2: Complete registration using the commitment
• getidentity — Check if a name is already taken
• listidentities — List identities in your wallet

Notes

• Save the output! The namereservation object (especially salt) is required for registeridentity. If lost, the commitment is wasted.
• The commitment must be mined before you can register. Wait for at least 1 block confirmation.
• Creating a commitment does not guarantee the name — someone else could register it first if they had an earlier commitment.
• The controladdress receives change from the commitment transaction. It does not need to be a primary address of the final identity.
• Commitments expire after a certain number of blocks if not used with registeridentity.
• On testnet, identity registration costs are minimal. On mainnet, costs vary and referrals can reduce fees.
• Did not run live test to avoid creating unnecessary commitments on testnet. The command structure and parameters are documented from help text and prior testing experience.

Tested On

• VRSCTEST block height: 926957
• Verus version: 1.2.14-2

Category: Identity | Version: v1.2.x+

⚠️ DESTRUCTIVE — Revoke a VerusID, disabling it from signing, spending, or being used for authentication until recovered.

Syntax

verus revokeidentity "nameorID" (returntx) (tokenrevoke) (feeoffer) (sourceoffunds)

Result

transactionid    (string) txid if returntx is false, or hex transaction if returntx is true

Examples

⚠️ UNTESTED — This is a destructive operation

Basic Usage

## Revoke an identity (CAUTION: identity becomes unusable until recovered)
./verus -testnet revokeidentity "myidentity@"

Dry Run (inspect before broadcasting)

## Return transaction hex without broadcasting
./verus -testnet revokeidentity "myidentity@" true

Token-Based Revocation

## Use tokenized control token for revocation authority
./verus -testnet revokeidentity "myidentity@" false true

RPC (curl)

curl --user user:pass --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"revokeidentity","params":["myidentity@"]}' -H 'content-type: text/plain;' http://127.0.0.1:27486/

Common Use Cases

• Compromised identity — immediately revoke if private keys are stolen
• Security lockdown — revoke to prevent any transactions while investigating a breach
• Pre-recovery — revoke before using recoveridentity to rotate keys

Related Commands

• recoveridentity — Recover a revoked identity with new keys
• updateidentity — Update identity (cannot be done while revoked)
• getidentity — Check identity status (flags will show revoked state)

Notes

• This is a destructive operation — a revoked identity cannot sign, spend funds, or authenticate
• Revocation requires the revocation authority keys, not the primary keys
• After revocation, only recoveridentity (using the recovery authority) can restore the identity
• It's good practice to set revocation and recovery authorities to different identities for security
• Use returntx true to inspect the transaction before committing
• Revocation is an on-chain transaction — it takes effect once mined
• The revocation and recovery authority design means even if primary keys are compromised, you can revoke and recover

Tested On

• ⚠️ Not tested (destructive operation)
• VRSCTEST block height: 926957
• Verus version: 2000753

Category: Identity | Version: v1.2.x+

Enable timelocking and unlocking of fund access for an on-chain VerusID. Provides time-delayed security against unauthorized spending.

Syntax

verus setidentitytimelock "id@" '{"unlockatblock": height}' (returntx) (feeoffer) (sourceoffunds)
verus setidentitytimelock "id@" '{"setunlockdelay": blocks}' (returntx) (feeoffer) (sourceoffunds)

*One of unlockatblock or setunlockdelay must be specified, but not both.

Result

hexstring    (string) txid if returntx is false, or hex serialized transaction if returntx is true

Examples

⚠️ UNTESTED — Timelocking is a sensitive operation that restricts fund access

Set an Unlock Delay (Recommended for Security)

## Require 100 blocks (~100 minutes) delay after unlock request before spending
./verus -testnet setidentitytimelock "myid@" '{"setunlockdelay": 100}'

Set Absolute Unlock Time

## Lock until block 1000000 — countdown starts immediately
./verus -testnet setidentitytimelock "myid@" '{"unlockatblock": 1000000}'

Unlock a Delayed Identity

## Set unlockatblock to current block to begin the unlock delay countdown
./verus -testnet setidentitytimelock "myid@" '{"unlockatblock": 926957}'

Dry Run

./verus -testnet setidentitytimelock "myid@" '{"setunlockdelay": 100}' true

RPC (curl)

curl --user user:pass --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"setidentitytimelock","params":["myid@",{"setunlockdelay":100}]}' -H 'content-type: text/plain;' http://127.0.0.1:18843/

Common Use Cases

• Cold storage security — lock an identity so funds can't be spent instantly even if keys are compromised
• Delayed withdrawal — give yourself a window to revoke if unauthorized unlock is detected
• Service integration — services can check lock status and refuse transfers when locked

Two Locking Modes

setunlockdelay (Relative Lock)

• Sets a delay period (in blocks) that must pass after an unlock request
• Unlock request = calling setidentitytimelock with unlockatblock set to current block
• The delay countdown only starts when you actively request unlock
• Best for: ongoing security (like a time-lock safe)

unlockatblock (Absolute Lock)

• Locks until a specific block height
• Countdown starts immediately when the transaction is mined
• Set to current block height to begin unlocking (still subject to any unlock delay)
• Best for: scheduled unlocks or initiating the unlock process

Related Commands

• getidentity — Check current timelock status in identity flags
• updateidentity — General identity updates
• revokeidentity — Revoke/recover can bypass timelock

Notes

• Timelocking is per-chain — it does not affect the same identity exported to other chains
• A timelocked identity prevents all updates (including contentmultimap changes) until unlocked
• Locked funds can still stake — timelocking does not prevent staking rewards
• The only way to remove a timelock is through revoke and recover — this is by design. Revoking and recovering a timelocked identity removes the timelock entirely
• There is no other mechanism to cancel or shorten a timelock once set
• Services supporting VerusID authentication may also honor the lock status for non-spending operations
• Average block time on Verus is ~60 seconds, so ~1440 blocks ≈ 1 day
• Use getidentity to check the current lock state and timelock parameters

Tested On

• ⚠️ Not directly tested (would lock fund access)
• VRSCTEST block height: 926957
• Verus version: 2000753

Category: Identity | Version: v1.2.x+

Set trust ratings for VerusIDs and configure identity trust mode for wallet sync filtering.

Syntax

verus setidentitytrust '{"clearall": bool, "setratings":{"id":JSONRatingObject,...}, "removeratings":["id",...], "identitytrustmode": n}'

Result

No return on success, error on failure.

Examples

Set Trust Rating for an Identity

## Set trust level for myid@
./verus -testnet setidentitytrust '{"setratings":{"myid@":{"trustlevel":2}}, "identitytrustmode":0}'

## Actual Output (tested on VRSCTEST)
## (no output — success returns nothing)

Remove Trust Ratings

./verus -testnet setidentitytrust '{"removeratings":["myid@"]}'

Clear All and Set Fresh

./verus -testnet setidentitytrust '{"clearall":true, "setratings":{"myid@":{"trustlevel":1}}, "identitytrustmode":1}'

Read Trust Ratings

## Use getidentitytrust to read (separate command)
./verus -testnet getidentitytrust '["myid@"]'

RPC (curl)

curl --user user:pass --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"setidentitytrust","params":[{"setratings":{"myid@":{"trustlevel":2}},"identitytrustmode":0}]}' -H 'content-type: text/plain;' http://127.0.0.1:18843/

Common Use Cases

• Whitelist identities — approve specific IDs for sync in restrictive mode
• Block spam identities — add untrusted IDs to block list with mode 2
• Wallet sync optimization — limit which identities your wallet tracks

Related Commands

• getidentitytrust — Read current trust ratings and mode
• getidentity — Look up identity details

Notes

• Trust ratings are local to your wallet — they don't affect the blockchain
• Trust mode controls which identities your wallet syncs/tracks
• Mode 1 (approved only) is the most restrictive — useful for resource-constrained nodes
• The setratings and removeratings operations can be combined in a single call
• clearall is processed first, then setratings, then removeratings
• Success returns no output (null) — check with getidentitytrust to confirm

Tested On

• VRSCTEST block height: 926957
• Verus version: 2000753

Category: Identity | Version: v1.2.x+

Sign data with a VerusID or t-address using advanced options including VDXF keys, bound hashes, hash type selection, and MMR (Merkle Mountain Range) support.

Syntax

verus signdata '{"address":"id@", "message":"data", ...}'

*One data parameter is required.

Result

{
  "signaturedata": {
    "version": 1,
    "systemid": "iAddress",
    "hashtype": 5,
    "signaturehash": "hexhash",
    "identityid": "iAddress",
    "signaturetype": 1,
    "signature": "base64sig"
  },
  "system": "VRSCTEST",
  "systemid": "iAddress",
  "hashtype": "sha256",
  "hash": "hexhash",
  "identity": "name@",
  "canonicalname": "name@",
  "address": "iAddress",
  "signatureheight": 926957,
  "signatureversion": 2,
  "signature": "base64sig"
}

Examples

Basic Usage — Sign a Message

## Command
./verus -testnet signdata '{"address":"myid@", "message":"Hello from myid - testing signdata for wiki docs"}'

## Actual Output (tested on VRSCTEST)
{
  "signaturedata": {
    "version": 1,
    "systemid": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
    "hashtype": 5,
    "signaturehash": "6972221095db42a7c97bd325ab7b6c641d3372be2ae0b435f7696c90789260c6",
    "identityid": "i...",
    "signaturetype": 1,
    "signature": "AgXtJA4AAUEfK2i7aQevRK3PPJFttLTRk7bkXeKE8vMPd+KE3fobhnViIM496FCXFN4TN2Nh0iQ5fOlcc8VHJqCOTEDa03gvrQ=="
  },
  "system": "VRSCTEST",
  "systemid": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
  "hashtype": "sha256",
  "hash": "6972221095db42a7c97bd325ab7b6c641d3372be2ae0b435f7696c90789260c6",
  "identity": "myid.VRSCTEST@",
  "canonicalname": "myid.vrsctest@",
  "address": "i...",
  "signatureheight": 926957,
  "signatureversion": 2,
  "signature": "AgXtJA4AAUEfK2i7aQevRK3PPJFttLTRk7bkXeKE8vMPd+KE3fobhnViIM496FCXFN4TN2Nh0iQ5fOlcc8VHJqCOTEDa03gvrQ=="
}

RPC (curl)

curl --user user:pass --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"signdata","params":[{"address":"myid@","message":"hello world"}]}' -H 'content-type: text/plain;' http://127.0.0.1:18843/

Common Use Cases

• Data attestation — sign arbitrary data with a VerusID for provable authorship
• VDXF-bound signatures — bind signatures to specific VDXF data types
• Multi-object MMR — sign multiple pieces of data in a single Merkle Mountain Range
• Encrypted data — sign and encrypt data to a Sapling address

Related Commands

• verifysignature — Verify a signdata signature (use datahash from output)
• signmessage — Simpler message signing (v1 signatures)
• signfile — Simple file signing

Notes

• Returns signature version 2 which includes system context in the hash — this means the hash differs from a simple SHA256 of the message
• To verify with verifysignature, use the datahash field from signdata output, NOT the original message (the message-based verification won't match due to v2 hashing)
• The signaturedata field contains the raw serialized signature data
• signatureheight records the block height at signing time, used for identity state verification
• Supports multisig via the signature parameter — pass partial signatures for accumulation

Tested On

• VRSCTEST block height: 926957
• Verus version: 2000753

Category: Identity | Version: v1.2.x+

Generate a SHA256D hash of a file and sign it with a VerusID or t-address.

Syntax

verus signfile "address or identity" "filepath/filename" ("currentsig")

Result

{
  "hash": "hexhash",
  "signature": "base64sig"
}

Examples

Basic Usage

## Command
./verus -testnet signfile "myid@" "/tmp/verus_test_sign.txt"

## Actual Output (tested on VRSCTEST)
{
  "hash": "720949abdd085252234efa73c02059fdc876f3c2295dd413e020d04292620c5d",
  "signature": "Ae0kDgABQR+9rcThasA9w0KYb/90a4QGRWUKgt3WZnRZOE+YDvKXKVhWMKMT15PT2MkO+Ru4i9cnt/XsGO2pMyDo42VmQ186"
}

RPC (curl)

curl --user user:pass --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"signfile","params":["myid@","/tmp/verus_test_sign.txt"]}' -H 'content-type: text/plain;' http://127.0.0.1:18843/

Common Use Cases

• Document signing — prove authorship or approval of a file
• Software releases — sign binaries or archives for verification
• Audit trails — create verifiable signatures for compliance documents

Related Commands

• verifyfile — Verify a file signature
• signmessage — Sign a text message instead
• signdata — Advanced signing with VDXF keys, bound hashes, etc.

Notes

• The hash returned is SHA256 (not SHA256D, despite using SHA256D internally for signing)
• The file must be accessible to the daemon process, not just the CLI
• Use verifyfile with the same file path and signature to verify
• Supports multisig accumulation via the cursig parameter
• The signature encodes the block height at signing time for identity state verification

Tested On

• VRSCTEST block height: 926957
• Verus version: 2000753

Category: Identity | Version: v1.2.x+

Sign a message with the private key of a t-address or the authorities present in this wallet for a VerusID.

Syntax

verus signmessage "address or identity" "message" ("currentsig")

Result

{
  "hash": "hexhash",
  "signature": "base64sig"
}

Examples

Basic Usage

## Command
./verus -testnet signmessage "myid@" "Hello from myid - testing signmessage for wiki docs"

## Actual Output (tested on VRSCTEST)
{
  "hash": "c7eb4997c9887fc59c2c02e397e44735f70a0173f547a1402170e120221bd48c",
  "signature": "Ae0kDgABQSDPV6z9gmeWVtGt6SaLiRk78JnsSf8LwCQjSeGj3Bja+WkFKg8jl0M1e+z/z6OzfQVjeW+rp26qg5mWxzrD1QAE"
}

Verify the Signed Message

./verus -testnet verifymessage "myid@" "Ae0kDgABQSDPV6z9gmeWVtGt6SaLiRk78JnsSf8LwCQjSeGj3Bja+WkFKg8jl0M1e+z/z6OzfQVjeW+rp26qg5mWxzrD1QAE" "Hello from myid - testing signmessage for wiki docs"
## Output: true

RPC (curl)

curl --user user:pass --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"signmessage","params":["myid@","Hello from myid"]}' -H 'content-type: text/plain;' http://127.0.0.1:18843/

Common Use Cases

• Authentication — prove you control a VerusID
• Message attestation — sign statements or agreements
• Off-chain verification — create portable proofs of identity

Related Commands

• verifymessage — Verify a signmessage signature
• verifyhash — Verify using the hash directly
• signdata — Advanced signing with VDXF keys, bound hashes, etc.
• signfile — Sign a file instead of a message

Notes

• Returns a v1 simple signature — use verifymessage (not verifysignature) to verify
• The hash is SHA256 of the message
• For advanced features (VDXF keys, bound hashes, hash type selection), use signdata instead
• Supports multisig accumulation — pass partial signatures via cursig
• The signature embeds the block height at signing time

Tested On

• VRSCTEST block height: 926957
• Verus version: 2000753

Category: Identity | Version: v1.2.x+

Update an existing VerusID's properties on-chain (primary addresses, authorities, content, flags, etc.).

Syntax

verus updateidentity "jsonidentity" (returntx) (tokenupdate) (feeoffer) (sourceoffunds)

jsonidentity Fields

{
  "name": "identityname",
  "parent": "iAddress",
  "primaryaddresses": ["Raddress", ...],
  "minimumsignatures": 1,
  "revocationauthority": "nameorID",
  "recoveryauthority": "nameorID",
  "privateaddress": "zs-address",
  "contentmultimap": { ... },
  "flags": 0
}

Result

hexstring    (string) txid if returntx is false, or hex serialized transaction if returntx is true

Examples

Basic Usage — Update a Root ID

## Update myid@ identity (root-level ID on VRSCTEST)
## (replace i... with a VDXF key from your namespace, e.g. yourapp::data.v1.owner)
./verus -testnet updateidentity '{"name":"myid", "contentmultimap":{"i...":["226172694022"]}}'

⚠️ CRITICAL: SubID Updates Require parent Field

## WRONG — This will fail silently or update the wrong identity:
./verus -testnet updateidentity '{"name":"alice.yourapp"}'

## CORRECT — SubIDs MUST include the parent field:
./verus -testnet updateidentity '{"name":"alice", "parent":"i..."}'

⚠️ SubID Gotcha: When updating a sub-identity (e.g., alice.yourapp@), you must include the "parent" field with the parent identity's i-address. Without it, the daemon will look for a root identity named "alice" instead of the subID "alice.yourapp". This is the most common source of errors with updateidentity.

Token-Based Update

## Use tokenized control token instead of key-based authority
./verus -testnet updateidentity '{"name":"myid"}' false true

RPC (curl)

curl --user user:pass --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"updateidentity","params":[{"name":"myid","contentmultimap":{"i...":["226172694022"]}}]}' -H 'content-type: text/plain;' http://127.0.0.1:18843/

Common Use Cases

• Rotate keys — change primaryaddresses to new addresses for security
• Add content — store data in contentmultimap using VDXF keys
• Change authorities — update revocationauthority or recoveryauthority
• Enable multisig — add multiple addresses and increase minimumsignatures
• Set private address — add a shielded privateaddress for receiving private funds

Related Commands

• getidentity — View current identity state before/after update
• registeridentity — Initial identity registration
• revokeidentity — Revoke an identity
• recoveridentity — Recover a revoked identity

Notes

• The name field is always required to identify which ID to update
• SubIDs require the parent field — this is the #1 gotcha
• Only fields you include will be changed; omitted fields retain their current values
• You must have signing authority (keys in wallet) or use tokenupdate
• tokenupdate allows holders of the tokenized ID control token to update without primary key authority, but cannot change revocation/recovery authorities
• Updates are on-chain transactions and require confirmation
• Use returntx to inspect the transaction before broadcasting in sensitive cases

Tested On

• VRSCTEST block height: 926957
• Verus version: 2000753

Category: Identity | Version: v1.2.x+

Verify a signed file against a VerusID or t-address.

Syntax

verus verifyfile "address or identity" "signature" "filepath/filename" (checklatest)

Result

true|false    (boolean) Whether the signature is valid

Examples

Basic Usage

## Command
./verus -testnet verifyfile "myid@" "Ae0kDgABQR+9rcThasA9w0KYb/90a4QGRWUKgt3WZnRZOE+YDvKXKVhWMKMT15PT2MkO+Ru4i9cnt/XsGO2pMyDo42VmQ186" "/tmp/verus_test_sign.txt"

## Actual Output (tested on VRSCTEST)
true

Check Against Latest Identity State

## Verify using the current identity keys (not the keys at signing time)
./verus -testnet verifyfile "myid@" "signature_base64" "/tmp/verus_test_sign.txt" true

RPC (curl)

curl --user user:pass --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"verifyfile","params":["myid@","Ae0kDgABQR+9rcThasA9w0KYb/90a4QGRWUKgt3WZnRZOE+YDvKXKVhWMKMT15PT2MkO+Ru4i9cnt/XsGO2pMyDo42VmQ186","/tmp/verus_test_sign.txt"]}' -H 'content-type: text/plain;' http://127.0.0.1:18843/

Common Use Cases

• Software verification — verify signed binaries or archives
• Document integrity — confirm a document hasn't been tampered with since signing
• Audit compliance — verify signed audit artifacts

Related Commands

• signfile — Sign a file (produces the signature to verify)
• verifymessage — Verify a message signature
• verifyhash — Verify using a hash directly

Notes

• The file must be accessible to the daemon process
• By default, verification checks against the identity state at the signing height (recorded in the signature)
• Use checklatest: true to verify against the current identity state — useful if keys have been rotated
• If the identity was updated (key rotation) after signing, default verification still succeeds (checks historical state)

Tested On

• VRSCTEST block height: 926957
• Verus version: 2000753

Category: Identity | Version: v1.2.x+

Verify a signature against a pre-computed hash and a VerusID or t-address.

Syntax

verus verifyhash "address or identity" "signature" "hexhash" (checklatest)

Result

true|false    (boolean) Whether the signature is valid

Examples

Basic Usage

## Using the hash from signmessage output to verify
./verus -testnet verifyhash "myid@" "Ae0kDgABQSDPV6z9gmeWVtGt6SaLiRk78JnsSf8LwCQjSeGj3Bja+WkFKg8jl0M1e+z/z6OzfQVjeW+rp26qg5mWxzrD1QAE" "c7eb4997c9887fc59c2c02e397e44735f70a0173f547a1402170e120221bd48c"

## Actual Output (tested on VRSCTEST)
true

RPC (curl)

curl --user user:pass --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"verifyhash","params":["myid@","Ae0kDgABQSDPV6z9gmeWVtGt6SaLiRk78JnsSf8LwCQjSeGj3Bja+WkFKg8jl0M1e+z/z6OzfQVjeW+rp26qg5mWxzrD1QAE","c7eb4997c9887fc59c2c02e397e44735f70a0173f547a1402170e120221bd48c"]}' -H 'content-type: text/plain;' http://127.0.0.1:18843/

Common Use Cases

• Hash-only verification — when you have the hash but not the original data
• Remote verification — verify without transmitting the original file/message
• Cross-system verification — verify signatures when only the hash was stored

Related Commands

• signmessage — Sign a message (output includes hash)
• signfile — Sign a file (output includes hash)
• verifymessage — Verify with the original message text
• verifyfile — Verify with the original file
• verifysignature — Advanced verification for signdata signatures

Notes

• The hash must be the SHA256 hash as returned by signmessage or signfile
• This is useful when you've stored the hash separately from the original data
• Works with signatures from both signmessage and signfile
• For signdata (v2) signatures, use verifysignature with datahash instead

Tested On

• VRSCTEST block height: 926957
• Verus version: 2000753

Category: Identity | Version: v1.2.x+

Verify a signed message against a VerusID or t-address.

Syntax

verus verifymessage "address or identity" "signature" "message" (checklatest)

Result

true|false    (boolean) Whether the signature is valid

Examples

Basic Usage

## Command
./verus -testnet verifymessage "myid@" "Ae0kDgABQSDPV6z9gmeWVtGt6SaLiRk78JnsSf8LwCQjSeGj3Bja+WkFKg8jl0M1e+z/z6OzfQVjeW+rp26qg5mWxzrD1QAE" "Hello from myid - testing signmessage for wiki docs"

## Actual Output (tested on VRSCTEST)
true

Verify with Latest Identity State

## Check against current keys (useful after key rotation)
./verus -testnet verifymessage "myid@" "signature_base64" "message" true

RPC (curl)

curl --user user:pass --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"verifymessage","params":["myid@","Ae0kDgABQSDPV6z9gmeWVtGt6SaLiRk78JnsSf8LwCQjSeGj3Bja+WkFKg8jl0M1e+z/z6OzfQVjeW+rp26qg5mWxzrD1QAE","Hello from myid - testing signmessage for wiki docs"]}' -H 'content-type: text/plain;' http://127.0.0.1:18843/

Common Use Cases

• Authentication proof — verify someone controls a VerusID
• Message integrity — confirm a message hasn't been altered
• Off-chain verification — verify VerusID signatures in external systems

Related Commands

• signmessage — Sign a message (produces the signature to verify)
• verifyhash — Verify using the hash instead of the message
• verifyfile — Verify a file signature
• verifysignature — Advanced verification for signdata signatures

Notes

• The message must match exactly — including whitespace and case
• Use this for signatures produced by signmessage. For signdata signatures, use verifysignature
• By default, checks against the identity state at the signing height (embedded in signature)
• checklatest: true verifies against current identity keys — will fail if keys were rotated after signing

Tested On

• VRSCTEST block height: 926957
• Verus version: 2000753

Category: Identity | Version: v1.2.x+

Verify a signature produced by signdata, supporting advanced features like VDXF keys, bound hashes, and hash type selection.

Syntax

verus verifysignature '{"address":"id@", "signature":"base64sig", ...}'

*One data parameter is required.

Result

{
  "signaturestatus": "verified",
  "system": "VRSCTEST",
  "systemid": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
  "identity": "myid.VRSCTEST@",
  "canonicalname": "myid.vrsctest@",
  "address": "i...",
  "hashtype": "sha256",
  "hash": "hexhash",
  "height": 926958,
  "signatureheight": 926957,
  "signature": "base64sig"
}

Examples

Verify Using datahash (Recommended for signdata signatures)

## Use the "hash" field from signdata output as "datahash"
./verus -testnet verifysignature '{"address":"myid@", "datahash":"ecd71870d1963316a97e3ac3408c9835ad8cf0f3c1bc703527c30265534f75ae", "signature":"AgXtJA4AAUEgXgBD28607ExvUtwYN788OyIboWOewNh5VS62b6iLhlM2fE1FFu3T793hVo4thSLPlDMLPjzyeZqQIgbafkrzGQ=="}'

## Actual Output (tested on VRSCTEST)
{
  "signaturestatus": "verified",
  "system": "VRSCTEST",
  "systemid": "iJhCezBExJHvtyH3fGhNnt2NhU4Ztkf2yq",
  "identity": "myid.VRSCTEST@",
  "canonicalname": "myid.vrsctest@",
  "address": "i...",
  "hashtype": "sha256",
  "hash": "ecd71870d1963316a97e3ac3408c9835ad8cf0f3c1bc703527c30265534f75ae",
  "height": 926958,
  "signatureheight": 926957,
  "signature": "AgXtJA4AAUEgXgBD28607ExvUtwYN788OyIboWOewNh5VS62b6iLhlM2fE1FFu3T793hVo4thSLPlDMLPjzyeZqQIgbafkrzGQ=="
}

⚠️ Important: Message-Based Verification with signdata

## This will NOT work — signdata v2 signatures include system context in the hash:
./verus -testnet verifysignature '{"address":"myid@", "message":"test123", "signature":"..."}'
## Result: signaturestatus: "invalid"

## Instead, use the "hash" from signdata output as "datahash":
./verus -testnet verifysignature '{"address":"myid@", "datahash":"hash_from_signdata", "signature":"..."}'
## Result: signaturestatus: "verified"

RPC (curl)

curl --user user:pass --data-binary '{"jsonrpc":"1.0","id":"curltest","method":"verifysignature","params":[{"address":"myid@","datahash":"ecd71870d1963316a97e3ac3408c9835ad8cf0f3c1bc703527c30265534f75ae","signature":"AgXtJA4AAUEgXgBD28607ExvUtwYN788OyIboWOewNh5VS62b6iLhlM2fE1FFu3T793hVo4thSLPlDMLPjzyeZqQIgbafkrzGQ=="}]}' -H 'content-type: text/plain;' http://127.0.0.1:18843/

Common Use Cases

• Verify signdata signatures — the counterpart to signdata
• VDXF-bound verification — verify signatures bound to specific VDXF data types
• Cross-system verification — verify with just the hash when original data isn't available

Related Commands

• signdata — Sign data (produces signatures verified by this command)
• verifymessage — Verify simple signmessage signatures
• verifyhash — Simple hash verification for signmessage/signfile

Notes

• Critical: signdata produces v2 signatures that include system context in the hash. Passing the original message to verifysignature will compute a different hash and return "invalid". Always use the datahash (the hash field from signdata output) for verification.
• Returns rich JSON with signaturestatus ("verified" or "invalid") instead of simple true/false
• Includes height (current block) and signatureheight (block at signing time)
• For simple signmessage/signfile signatures, use verifymessage/verifyfile/verifyhash instead

Tested On

• VRSCTEST block height: 926958
• Verus version: 2000753