stake_lock

Stake lock service commands. Lock tokens for staking until a specified unlock date (hold), then reclaim them with take.

Supported networks on public nodes (for example rpc.cellframe.net): Backbone, KelVPN.

JSON-RPC request

Method name: stake_lock. Send a POST request to the node CLI server (for example http://rpc.cellframe.net/). Two request shapes are supported (see dap_json_rpc_params_create_from_subcmd_and_args).

Version 1 — `params` string

{
  "method": "stake_lock",
  "params": ["stake_lock;<subcommand>;...options..."],
  "id": 1,
  "version": 1
}

Version 2 — `subcommand` and `arguments`

Omit params. Provide subcommand ("hold" or "take") and arguments as a JSON object. Each key maps to a CLI flag -<key> (keys are written without the leading dash).

{
  "method": "stake_lock",
  "subcommand": "hold",
  "arguments": {
    "net": "Backbone",
    "w": "mywallet",
    "time_staking": "271231",
    "token": "CELL",
    "value": "1000000000000000000",
    "fee": "1000000000000000000"
  },
  "id": 1,
  "version": 2
}

{
  "method": "stake_lock",
  "subcommand": "take",
  "arguments": {
    "net": "Backbone",
    "w": "mywallet",
    "tx": "0xABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789",
    "fee": "1000000000000000000"
  },
  "id": 2,
  "version": 2
}

Optional keys: chain, reinvest (hold only), H (hex or base58). Amount alias: value or coins (hold).

hold and take are write operations — they require a wallet file on the node (w). On public nodes such as rpc.cellframe.net (no local wallets), requests reach parameter validation but fail at wallet open with can't open wallet. The v2 argument form is still accepted and validated the same way as v1 params (verified live: missing value/coins returns requires parameter -coins).

Params format (version 1)

params is an array with a single string. Tokens are separated by semicolons (;), matching CLI argv. The string must start with stake_lock, then the subcommand and options.

stake_lock;hold;-net;Backbone;-w;mywallet;-time_staking;271231;-token;CELL;-value;1000000000000000000;-fee;1000000000000000000
stake_lock;take;-net;Backbone;-w;mywallet;-tx;0xABCDEF...;-fee;1000000000000000000

Spaces are not used as separators — use semicolons between every token (command name, subcommand, flags, values).

Subcommands

Subcommand	Description	Access
`hold`	Create a stake-lock transaction and add it to the mempool.	Write — requires a wallet file on the node (`-w`).
`take`	Unlock and reclaim tokens from a prior `hold` transaction.	Write — requires a wallet file on the node (`-w`) that owns the stake-lock tx.

Both subcommands sign transactions with the node-local wallet and submit datums to the mempool. The wallet must exist in the node’s wallet directory and hold sufficient balance for the lock amount and fees.

hold

stake_lock hold -net <net_name> -w <wallet_name> -time_staking <YYMMDD> -token <ticker> -value <value> -fee <value>
    [-chain <chain_name>] [-reinvest <percentage>] [-H hex|base58]

Create a stake-lock transaction that locks tokens until the unlock date. On success the response status field contains the mempool datum hash — save it for take.

Parameters

Option	Required	Description
`-net <net_name>`	yes	Network name (e.g. `Backbone`, `KelVPN`).
`-w <wallet_name>`	yes	Wallet file on the node used to sign the transaction.
`-time_staking <YYMMDD>`	yes	Unlock date in simplified format. Example: `220610` = 10 June 2022 00:00. Must be 6 digits with valid month (01–12) and day (01–31), and must be in the future.
`-token <ticker>`	yes	Token ticker to lock (max 8 characters).
`-value <datoshi>`	yes	Amount to lock as a 256-bit integer in datoshi. Alias: `-coins`.
`-fee <datoshi>`	yes	Validator fee in datoshi (256-bit integer, must be non-zero).
`-chain <chain_name>`	no	Target chain; defaults to the network’s default TX chain.
`-reinvest <percentage>`	no	Reinvest percentage from 0 to 100.
`-H hex\|base58`	no	Hash output format for the created datum (default: `hex`).

Parameter validation order: -net → -token → -value/-coins → -w → -fee → -time_staking → wallet open and balance checks.

Example request (version 1)

{
  "method": "stake_lock",
  "params": ["stake_lock;hold;-net;Backbone;-w;mywallet;-time_staking;271231;-token;CELL;-value;1000000000000000000;-fee;1000000000000000000"],
  "id": 1,
  "version": 1
}

Example request (version 2)

{
  "method": "stake_lock",
  "subcommand": "hold",
  "arguments": {
    "net": "Backbone",
    "w": "mywallet",
    "time_staking": "271231",
    "token": "CELL",
    "value": "1000000000000000000",
    "fee": "1000000000000000000"
  },
  "id": 1,
  "version": 2
}

With optional reinvest and chain (version 1):

{
  "method": "stake_lock",
  "params": ["stake_lock;hold;-net;KelVPN;-w;mywallet;-time_staking;280101;-token;CELL;-value;5000000000000000000;-fee;500000000000000000;-chain;zerochain;-reinvest;50"],
  "id": 2,
  "version": 1
}

Version 2 equivalent:

{
  "method": "stake_lock",
  "subcommand": "hold",
  "arguments": {
    "net": "KelVPN",
    "w": "mywallet",
    "time_staking": "280101",
    "token": "CELL",
    "value": "5000000000000000000",
    "fee": "500000000000000000",
    "chain": "zerochain",
    "reinvest": "50"
  },
  "id": 2,
  "version": 2
}

take

stake_lock take -net <net_name> -w <wallet_name> -tx <transaction_hash> -fee <value>
    [-chain <chain_name>] [-H hex|base58]

Reclaim locked tokens from a stake-lock transaction created by hold. The wallet must own the original transaction (public key must match the stake-lock sign item). The stake-lock output must not already be spent. If the lock has a time-based flag, blockchain time must be past time_unlock.

Parameters

Option	Required	Description
`-net <net_name>`	yes	Network name (e.g. `Backbone`, `KelVPN`).
`-w <wallet_name>`	yes	Wallet file on the node; must own the stake-lock transaction.
`-tx <hash>`	yes	Hash of the original stake-lock transaction from `hold`. Use `0x` prefix for hex (64 hex digits) or base58.
`-fee <datoshi>`	yes	Validator fee in datoshi (256-bit integer, must be non-zero).
`-chain <chain_name>`	no	Target chain; defaults to the network’s default TX chain.
`-H hex\|base58`	no	Hash output format for the take datum (default: `hex`).

Parameter validation order: -net → -tx (hash parse and stake-lock lookup) → -w → -fee → wallet open and owner-key checks. Missing -w or -fee are reported only after a valid stake-lock transaction is found.

Example request (version 1)

{
  "method": "stake_lock",
  "params": ["stake_lock;take;-net;Backbone;-w;mywallet;-tx;0xABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789;-fee;1000000000000000000"],
  "id": 3,
  "version": 1
}

Example request (version 2)

{
  "method": "stake_lock",
  "subcommand": "take",
  "arguments": {
    "net": "Backbone",
    "w": "mywallet",
    "tx": "0xABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789",
    "fee": "1000000000000000000"
  },
  "id": 3,
  "version": 2
}

Response

stake_lock is a JSON-response command. The server returns type: 2 (TYPE_RESPONSE_JSON). The result field is a JSON array with one object containing a status string (multiline CLI-style text).

Success — hold

{
  "type": 2,
  "result": [
    {
      "status": "\n---> HOLD <---\nTX STAKE LOCK CREATED\nSuccessfully hash = 0xABCDEF...\nSave to take!\n\nContribution successfully made"
    }
  ],
  "id": 1,
  "version": 1
}

Success — take

{
  "type": 2,
  "result": [
    {
      "status": "\n---> TAKE <---\nTAKE_TX_DATUM_HASH = 0xABCDEF...\n\nContribution successfully made"
    }
  ],
  "id": 3,
  "version": 1
}

Subcommand error (unrecognized command)

When the subcommand is missing or not hold/take, the response uses an errors array instead of status:

{
  "type": 2,
  "result": [
    {
      "errors": [
        { "code": 1, "message": "Command foo not recognized" }
      ]
    }
  ],
  "id": 1,
  "version": 1
}

Parameter and validation errors

Operational errors return status with an ERROR! line and a descriptive message. Verified against rpc.cellframe.net:

// v2 hold — missing value/coins (verified live)
{ "type": 2, "result": [ { "status": "\n---> HOLD <---\nERROR!\nstake_lock command requires parameter -coins" } ], "id": 1, "version": 2 }

// stake_lock;hold — missing -net
{ "type": 2, "result": [ { "status": "\n---> HOLD <---\nERROR!\nstake_lock command requires parameter -net" } ], "id": 1, "version": 1 }

// stake_lock;hold;-net;Backbone — missing -token
{ "type": 2, "result": [ { "status": "\n---> HOLD <---\nERROR!\nstake_lock command requires parameter -token" } ], "id": 2, "version": 1 }

// stake_lock;hold;-net;Backbone;-token;CELL — missing -value/-coins
{ "type": 2, "result": [ { "status": "\n---> HOLD <---\nERROR!\nstake_lock command requires parameter -coins" } ], "id": 3, "version": 1 }

// ...;-value;1000000000000000000 — missing -w
{ "type": 2, "result": [ { "status": "\n---> HOLD <---\nERROR!\nstake_lock command requires parameter -w" } ], "id": 4, "version": 1 }

// ...;-w;mywallet — missing -fee
{ "type": 2, "result": [ { "status": "\n---> HOLD <---\nERROR!\nstake_lock command requires parameter -fee" } ], "id": 5, "version": 1 }

// ...;-fee;1000000000000000000 — missing -time_staking
{ "type": 2, "result": [ { "status": "\n---> HOLD <---\nERROR!\nstake_lock command requires parameter '-time_staking' in simplified format YYMMDD\nExample: \"220610\" == \"10 june 2022 00:00\"" } ], "id": 6, "version": 1 }

// ...;-time_staking;260101 — past date (same TIME_ERROR message)
{ "type": 2, "result": [ { "status": "\n---> HOLD <---\nERROR!\nstake_lock command requires parameter '-time_staking' in simplified format YYMMDD\nExample: \"220610\" == \"10 june 2022 00:00\"" } ], "id": 7, "version": 1 }

// -net;UnknownNetXYZ
{ "type": 2, "result": [ { "status": "\n---> HOLD <---\n'UnknownNetXYZ'ERROR!\n ^^^ network not found" } ], "id": 8, "version": 1 }

// -token;NOTOKEN
{ "type": 2, "result": [ { "status": "\n---> HOLD <---\n'NOTOKEN'ERROR!\n ^^^ token ticker not found" } ], "id": 9, "version": 1 }

// -value;0
{ "type": 2, "result": [ { "status": "\n---> HOLD <---\nERROR!\nFormat -coins <256 bit integer>" } ], "id": 10, "version": 1 }

// -fee;0
{ "type": 2, "result": [ { "status": "\n---> HOLD <---\nERROR!\nFormat -fee <256 bit integer>" } ], "id": 11, "version": 1 }

// -w;nonexistent_wallet_xyz (wallet not on node)
{ "type": 2, "result": [ { "status": "\n---> HOLD <---\n'nonexistent_wallet_xyz'ERROR!\n ^^^ can't open wallet" } ], "id": 12, "version": 1 }

// stake_lock;take — missing -net
{ "type": 2, "result": [ { "status": "\n---> TAKE <---\nERROR!\nstake_lock command requires parameter -net" } ], "id": 20, "version": 1 }

// stake_lock;take;-net;Backbone — missing -tx
{ "type": 2, "result": [ { "status": "\n---> TAKE <---\nERROR!\nstake_lock command requires parameter -tx" } ], "id": 21, "version": 1 }

// -tx;0000000000000000000000000000000000000000000000000000000000000000 (blank hash)
{ "type": 2, "result": [ { "status": "\n---> TAKE <---\nERROR!\ntx hash is blank" } ], "id": 22, "version": 1 }

// -tx;0x1111...1111 (valid format, tx not found)
{ "type": 2, "result": [ { "status": "\n---> TAKE <---\nERROR!\n ^^^ could not find transaction" } ], "id": 23, "version": 1 }

Additional errors (from source)

These messages appear when parameters are syntactically valid but business rules fail:

Not enough money — wallet balance insufficient for hold.
^^^ failed to get wallet address — wallet address derivation failed.
^^^ delegated token not found — delegated token for the ticker is missing.
reinvestment is set as a percentage from 0 to 100 — invalid -reinvest value.
wrong subtype for transaction — -tx is not a stake-lock conditional output.
tx hash is used out — stake-lock already spent.
wallet key is not equal tx owner key — -w does not own the stake-lock tx.
Not enough time has passed — unlock time not yet reached.
failed to add datum with take-transaction to mempool — mempool submission failed.
Total fee more than stake — fee exceeds stake value (printed before mempool error).

stake_lock

JSON-RPC request

Version 1 — params string

Version 2 — subcommand and arguments

Params format (version 1)

Subcommands

hold

Parameters

Example request (version 1)

Example request (version 2)

take

Parameters

Example request (version 1)

Example request (version 2)

Response

Success — hold

Success — take

Subcommand error (unrecognized command)

Parameter and validation errors

Additional errors (from source)

Version 1 — `params` string

Version 2 — `subcommand` and `arguments`