Komodo Docs
GitHub

Task: Z Coin Activation

task::enable_z_coin::initAPI-v2task::enable_z_coin::init

ZHTLC coins, like Pirate (ARRR) and the test coin ZOMBIE take a little longer to enable, and use a new two step method to enable. Activation can take a little while the first time, as we need to download some block cache data, and build a wallet database. Subsequent enabling will be faster, but still take a bit longer than other coins. The second step for activation is optional, but allows us to check the status of the activation process.

Refer to the task managed activation overview for activation of other coin types.

To withdraw ZHTLC coins, you need to use the task::withdraw methods:

ZHTLC coins are not compatible with the v2 my_tx_history and legacy my_tx_history methods. To get the transaction history for ZHTLC coins, you need to use the z_coin_tx_history method.

Arguments

Parameter Type Required Description
ticker string ✓ Ticker of coin to activate
activation_params object ✓ A standard ActivationRpcData object.

Response

Parameter Type Required Description
task_id integer ✓ An identifying number which is used to query task status.

📌 Examples

Enable Z coin without any optional parameters

POST task::enable_z_coin::init 
{
  "userpass": "RPC_UserP@SSW0RD",
  "method": "task::enable_z_coin::init",
  "mmrpc": "2.0",
  "params": {
    "ticker": "ZOMBIE",
    "activation_params": {
      "mode": {
        "rpc": "Light",
        "rpc_data": {
          "electrum_servers": [
            {
              "url": "zombie.dragonhound.info:10133",
              "protocol": "TCP"
            },
            {
              "url": "zombie.dragonhound.info:20133",
              "protocol": "SSL"
            },
            {
              "url": "zombie.dragonhound.info:30059",
              "protocol": "WSS"
            }
          ],
          "light_wallet_d_servers": [
            "https://zombie.dragonhound.info:1443"
          ]
        }
      },
      "zcash_params_path": "/home/username/path_to/.zcash-params",
      "scan_blocks_per_iteration": 100,
      "scan_interval_ms": 200
    }
  }
}

Sync from block 2528700, with custom .zcash-params path and scan params

POST task::enable_z_coin::init 
{
  "userpass": "RPC_UserP@SSW0RD",
  "method": "task::enable_z_coin::init",
  "mmrpc": "2.0",
  "params": {
    "ticker": "ZOMBIE",
    "activation_params": {
      "mode": {
        "rpc": "Light",
        "rpc_data": {
          "electrum_servers": [
            {
              "url": "zombie.dragonhound.info:10133",
              "protocol": "TCP"
            },
            {
              "url": "zombie.dragonhound.info:20133",
              "protocol": "SSL"
            },
            {
              "url": "zombie.dragonhound.info:30059",
              "protocol": "WSS"
            }
          ],
          "light_wallet_d_servers": [
            "https://zombie.dragonhound.info:1443"
          ],
          "sync_params": {
            "height": 2528700
          }
        }
      },
      "zcash_params_path": "/home/username/path_to/.zcash-params",
      "scan_blocks_per_iteration": 100,
      "scan_interval_ms": 200
    }
  }
}

Sync from sapling activation height (earliest)

The Z coin lightwallet client only supports blocks that are post-sapling. The sapling activation height for Z coins can be found in the coins file

POST task::enable_z_coin::init 
{
  "userpass": "RPC_UserP@SSW0RD",
  "method": "task::enable_z_coin::init",
  "mmrpc": "2.0",
  "params": {
    "ticker": "ZOMBIE",
    "activation_params": {
      "mode": {
        "rpc": "Light",
        "rpc_data": {
          "electrum_servers": [
            {
              "url": "zombie.dragonhound.info:10133"
            },
            {
              "url": "zombie.dragonhound.info:20133",
              "protocol": "SSL",
              "ws_url": "zombie.dragonhound.info:30059"
            }
          ],
          "light_wallet_d_servers": [
            "http://zombie.dragonhound.info:1443"
          ],
          "sync_params": "earliest"
        }
      },
      "zcash_params_path": "/home/username/path_to/.zcash-params",
      "scan_blocks_per_iteration": 100,
      "scan_interval_ms": 200
    }
  }
}

Using websockets to sync from Proof of Keys Day, 2023.

POST task::enable_z_coin::init 
{
  "userpass": "RPC_UserP@SSW0RD",
  "method": "task::enable_z_coin::init",
  "mmrpc": "2.0",
  "params": {
    "ticker": "ZOMBIE",
    "activation_params": {
      "mode": {
        "rpc": "Light",
        "rpc_data": {
          "electrum_servers": [
            {
              "protocol": "SSL",
              "url": "zombie.dragonhound.info:20133",
              "ws_url": "zombie.dragonhound.info:30059"
            }
          ],
          "light_wallet_d_servers": [
            "http://zombie.dragonhound.info:1443"
          ],
          "sync_params": {
            "date": 1672704000
          }
        }
      }
    }
  }
}
Show Response

Response

{
  "mmrpc": "2.0",
  "result": {
    "task_id": 0
  },
  "id": null
}

task::enable_z_coin::statusAPI-v2task::enable_z_coin::status

Z coins need to build sync a local block cache and wallet database before they can be used. Using task_id as an input, this method will return the current status of the activation process.

Arguments

Parameter Type Required Default Description
task_id integer ✓ The identifying number returned when initiating the initialisation process.
forget_if_finished boolean – true If false, will return final response for completed tasks.

Response

Parameter Type Required Description
status string ✓ A short indication of how the enabling is progressing.
details object ✓ Depending on the state of enabling progress, this will contain different information as shown in the responses below.

Possible status values while activation is in progress:

  • ActivatingCoin: The first step of activation. It does not require any action from the user.
  • RequestingWalletBalance: The first step of activation, while initial balances info is being requested. It does not require any action from the user.
  • Finishing: Activation process completed
  • WaitingForTrezorToConnect: Waiting for the user to plugin a Trezor device
  • FollowHwDeviceInstructions: Waiting for the user to follow the instructions on the device

Once complete, status will be Ok, and the details object will have the following structure:

ParameterTypeDescription
current_blockintegerBlock height of the coin being activated
tickerstringTicker of the coin being activated.
wallet_balanceobjectA standard WalletBalanceInfo object. Note: the structure may vary based on the get_balances parameter value in the activation request.

📌 Examples

Status of Z coin activation

POST task::enable_z_coin::status 
{
  "userpass": "RPC_UserP@SSW0RD",
  "method": "task::enable_z_coin::status",
  "mmrpc": "2.0",
  "params": {
    "task_id": 0,
    "forget_if_finished": false
  }
}
Show Response

Response (ActivatingCoin - enabling has started)

{
  "mmrpc": "2.0",
  "result": {
    "status": "InProgress",
    "details": "ActivatingCoin"
  },
  "id": null
}

Response (UpdatingBlocksCache)

{
  "mmrpc": "2.0",
  "result": {
    "status": "InProgress",
    "details": {
      "UpdatingBlocksCache": {
        "current_scanned_block": 265930,
        "latest_block": 269656
      }
    }
  },
  "id": null
}

Response (BuildingWalletDb)

{
  "mmrpc": "2.0",
  "result": {
    "status": "InProgress",
    "details": {
      "BuildingWalletDb": {
        "current_scanned_block": 265311,
        "latest_block": 269656
      }
    }
  },
"id": null
}

Response (Enabling complete)

{
  "mmrpc": "2.0",
  "result": {
    "status": "Ok",
    "details": {
      "ticker": "ZOMBIE",
      "current_block": 269657,
      "wallet_balance": {
        "wallet_type": "Iguana",
        "address": "zs1e3puxpnal8ljjrqlxv4jctlyndxnm5a3mj5rarjvp0qv72hmm9caduxk9asu9kyc6erfx4zsauj",
        "balance": {
          "spendable": "29.99989008",
          "unspendable": "0"
        }
      }
    }
  },
  "id": null
}
Show Error Responses

Response (CoinCreationError - no Zcash Params)

{
	"error": "Error on platform coin ZOMBIE creation: ZCashParamsNotFound",
	"error_path": "lib.z_coin_activation.z_coin",
	"error_trace": "lib:104] z_coin_activation:218] z_coin:1007]",
	"error_type": "CoinCreationError",
	"error_data": {
		"ticker": "ZOMBIE",
		"error": "ZCashParamsNotFound"
	}
}

Response (error - NoSuchTask)

You’ll see this if the task number does not exist, or the task has already completed.

{
  "mmrpc": "2.0",
  "error": "No such task '1'",
  "error_path": "init_standalone_coin",
  "error_trace": "init_standalone_coin:119]",
  "error_type": "NoSuchTask",
  "error_data": 1,
  "id": null
}

Response (error - InvalidRequest)

{
  "mmrpc": "2.0",
  "error": "Error parsing request: invalid value: integer `-205`, expected u64",
  "error_path": "dispatcher",
  "error_trace": "dispatcher:109]",
  "error_type": "InvalidRequest",
  "error_data": "invalid value: integer `-205`, expected u64",
  "id": 42
}

Response (no Zcash Params)

{
  "mmrpc": "2.0",
  "result": {
    "status": "Error",
    "details": {
      "error": "Error on platform coin ZOMBIE creation: ZCashParamsNotFound",
      "error_path": "lib.z_coin_activation.z_coin",
      "error_trace": "lib:103] z_coin_activation:192] z_coin:761]",
      "error_type": "CoinCreationError",
      "error_data": {
        "ticker": "ZOMBIE",
        "error": "ZCashParamsNotFound"
      }
    }
  },
  "id": null
}

Response (error - no such task)

You’ll see this if the task number does not exist, or the task has already completed.

{
  "mmrpc": "2.0",
  "error": "No such task '1'",
  "error_path": "init_standalone_coin",
  "error_trace": "init_standalone_coin:119]",
  "error_type": "NoSuchTask",
  "error_data": 1,
  "id": null
}

task::enable_z_coin::user_actionAPI-v2task::enable_z_coin::user_action

If the task::enable_z_coin::status returns UserActionRequired, we need to use the task::enable_z_coin::user_action method to enter our PIN

Arguments

ParameterTypeDescription
task_idintegerThe identifying number returned when initiating the initialisation process.
user_actionobjectObject containing the params below
user_action.action_typestringWill be TrezorPin for this method
user_action.pinstring (number)When the Trezor device is displaying a grid of numbers for PIN entry, this param will contain your Trezor pin, as mapped through your keyboard numpad. See the image below for more information.
Trezor Pin

Response

ParameterTypeDescription
resultstringThe outcome of the request.
POST task::enable_z_coin::user_action 
{
  "userpass": "RPC_UserP@SSW0RD",
  "mmrpc": "2.0",
  "method": "task::enable_z_coin::user_action",
  "params": {
    "task_id": 3,
    "user_action": {
      "action_type": "TrezorPin",
      "pin": "862743"
    }
  }
}
Show Response

Response (success)

{
  "mmrpc": "2.0",
  "result": "success",
  "id": null
}

task::enable_z_coin::cancelAPI-v2task::enable_z_coin::cancel

If you want to cancel the enabling process before it has completed, you can use this method.

Arguments

StructureTypeDescription
task_idintegerThe identifying number returned when initiating the enabling process.

Response

StructureTypeDescription
resultstringIndicates task cancellation was succesful.
errorstringAn error message to explain what went wrong.
error_pathstringAn indicator of the class or function which reurned the error.
error_tracestringAn indicator of where in the source code the error was thrown.
error_typestringAn enumerated value for the returned error.
error_datastringThe input task ID which resulted in the error.

📌 Examples

Command

POST task::enable_z_coin::cancel 
{
  "userpass": "RPC_UserP@SSW0RD",
  "method": "task::enable_z_coin::cancel",
  "mmrpc": "2.0",
  "params": {
    "task_id": 3
  }
}
Show Response

Response (success)

{
  "mmrpc": "2.0",
  "result": "success",
  "id": null
}
Show Error Responses

Response (success - already finished)

{
  "mmrpc": "2.0",
  "error": "Task is finished already",
  "error_path": "init_standalone_coin.manager",
  "error_trace": "init_standalone_coin:144] manager:101]",
  "error_type": "TaskFinished",
  "error_data": 0,
  "id": null
}

Response (error - no such task)

{
  "mmrpc": "2.0",
  "error": "No such task '1'",
  "error_path": "init_standalone_coin",
  "error_trace": "init_standalone_coin:119]",
  "error_type": "NoSuchTask",
  "error_data": 1,
  "id": null
}