xaya cli

Getting Started with xaya-cli

The XAYA Command Line Interface (xaya-cli) program is a CLI for interacting with the XAYA daemon and XAYA wallets through JSON-RPC.

Much of what can be done in xaya-cli can also be done in the XAYA QT wallet's console. However, there are advantages to using xaya-cli instead of the QT console. As such, much of the XAYA documentation uses xaya-cli.

The following is to help you get up to speed on how to use xaya-cli. If you are already comfortable with CLIs, then you can simply run it with the -? or --help parameters to get the information you need and skip this tutorial. That help is the official reference material.

This tutorial is designed as a relaxing walk through that you can follow along with and experiment with as you read. Take time to run some of the commands and see how they work for you. Experience is a great teacher.

Additional Documentation from Bitcoin

Much of what you will need to know about commands and JSON-RPC methods is already documented in Bitcoin documentation. This tutorial is not a substitute for upstream documentation.

Getting Ready...

If you haven't already, download the XAYA QT wallet software here and extract the contents of the ZIP file.

• xaya-cli
• xaya-hash
• xaya-qt
• xaya-tx
• xayad

On Linux you'll need to chmod +x them to make them executable.

Start Your Wallet or xayad

Here we'll run xayad instead of one of the wallet software packages. Run it with the server command.

xayad -server=1

For more information about options, see Running xayad for Games here and Daemon Options.

Let's Get Started!

Open a console (command prompt in Windows or terminal in Linux) and navigate to the xaya-cli folder.

You can get help for xaya-cli options with this command:

xaya-cli -?

Run that now and have a quick glance.

At the top of the help you'll see some usage cases. Here we'll only examine the first one:

xaya-cli [options] <command> [params]

The [options] are from the help that you just viewed. (The list of commands is available from the XAYA QT or Electron wallet console by typing "help".) For many commands we don't need to specify any options and can simply send a command with parameters. Here are some examples. They are all are perfectly safe to use, so feel free to try them right now.

xaya-cli getblockcount
xaya-cli getdifficulty
xaya-cli getblockchaininfo
xaya-cli getblockhash 123
xaya-cli gettxoutsetinfo
xaya-cli uptime
xaya-cli game_sendupdates "g/mv" "2aed5640a3be8a2f32cdea68c3d72d7196a7efbfe2cbace34435a3eef97561f2" "3b365d712d87e354a36a6b0445fd022322e559bb9b4dc493f8eea3328d670197"
xaya-cli trackedgames
xaya-cli trackedgames "add" "mv"

Playing Safely

As above, these are safe commands and you won't do any damage by using them. We'll warn you for commands that have real consequences.

To interact with XAYA with zero fear, you can run regtest. See the Regtestnet tutorial for information about that. For now, we return back to the real world mainnet.

Options vs. Commands

The options we saw above are for xaya-cli. It passes those options on to the XAYA daemon. Some of the options that you will need most include:

• -testnet
• -regtest
• -rpcwallet=<walletname>
• -rpcuser=<user>
• -rpcpassword=<pw>

Commands

Commands are JSON-RPC methods defined in xayad. You can get a complete list of commands from the console in either the XAYA QT or Electron wallet by typing "help".

Commands "do things".

Commands can put data onto the blockchain, get data from the blockchain, manage wallets, and much more. Skim through the xayad-help.txt file to get a feel for the kinds of commands that are available to you. Most are the same as those in bitcoind.

Also consult XAYA RPC Methods for XAYA-specific RPC methods.

For more in-depth information on specific methods, you must use the XAYA QT or Electron wallet console. Run "help <command name>". So, for example, if you want information about creating new addresses, use this:

help getnewaddress

You can also check the Bitcoin documentation for commands as much of it is the same.

Continuing on...

Whether or not you need options depends upon what starting options were passed to the wallet software when it started up, or any options that were set inside the xaya.conf file in the data directory. You can find xaya.conf in the data directory here on Windows, Linux, and Mac OS X, respectively:

%appdata%\Xaya\xaya.conf
~/.xaya/xaya.conf
~/Library/Application Support/Xaya/xaya.conf

Dealing with Wallets

When working with real wallets, such as the Electron game wallet, we must specify which wallet to use with the -rpcwallet=<walletname> option.

To load a wallet.dat file, specify which one similar to any of the following commands.

xaya-cli loadwallet "wallet.dat"
xaya-cli loadwallet "game.dat"
xaya-cli loadwallet "vault.dat"

The following command gets the balance from the game wallet and vault wallet, respectively.

xaya-cli -rpcwallet=game.dat getbalance
xaya-cli -rpcwallet=vault.dat getbalance

This will not cause the wallet to appear in the Electron UI, but it will make the wallet available to the XAYA daemon, which is what xaya-cli is querying.

You can get a list of currently loaded wallets using the following command:

xaya-cli listwallets

The result after having loaded the 3 wallets above would be as follows.

[
  "vault.dat",
  "game.dat",
  "wallet.dat"
]

You can unload a wallet as shown below:

xaya-cli unloadwallet "wallet.dat"

Some Cooler Stuff You Can Do

Now that we've looked a bit at wallets, let's do some cooler stuff starting with backing up a wallet. For this, we must specify the wallet to back up with a xaya-cli option, e.g. "-rpcwallet=game.dat". We must also specify a complete path, e.g. "C:\XAYA Backups\MyFirstBackup.dat". Make certain that the folder exists.

xaya-cli -rpcwallet=game.dat backupwallet "C:\XAYA Backups\MyFirstBackup.dat"

Creating a CHI Address

Now that we have a backup of our game wallet, let's do some more cool stuff like creating a new address.

xaya-cli -rpcwallet=game.dat getnewaddress "This is my new address!"

The command will run and then return an address, e.g. "CXTdDBYrZEmSHWrsq8hFv5R78NrH8Q2Bxd".

You can now load your Electron wallet and verify that the address is in there. Check the Receive tab and scroll down. Addresses are listed alphabetically by label. (You'll need to shut down xayad, start Electron, check, close Electron, then run xayad as above if you decide to check and then continue on in this tutorial.)

Any cryptocurrency will let you do that; it's very basic. However, there are methods that you won't find in any other cryptocurrencies, other than perhaps some in Namecoin and Huntercoin. But even those don't have all the options you have in XAYA.

Registering a Name

NOTE: This operation costs CHI and is permanent on the blockchain.

If your or your user don't already have a name, you can register one for them. For users, you would normally do this inside of your game through the RPC interface. Let's get you a new name! Replace "Bugs Bunny" with the name you'd like to have.

xaya-cli -rpcwallet=game.dat name_register "p/Bugs Bunny" "{}"

The parameters are:

• Name: "p/Bugs Bunny"
• Value: "{}"

The name must have a namespace. For player accounts this is "p/". Everything after that is the "name" per se. Refer to Name and Value Restrictions for more information.

The value must be valid JSON. In this case we simply send an empty value. There's no reason to do more than that if the goal is to simply register a name. However, it could include an initial move in a game. (Refer to Moves for the "move" specification.)

The return value for that command was "1e57a1136711e008f5046025613c1835515eb7adf175a15bab8a52b3eec28e5f". You can verify this on the XAYA blockchain by using xaya-cli, or you can check the XAYA blockchain explorer here.

As mentioned above, you can get more help on the name_register operation with help name_register in the QT or Electron console.

List your names

To see all the names in your wallet, use the name_list RPC method. Make sure to specify which wallet you want to check.

xaya-cli -rpcwallet=game.dat name_list

Summary

We've taken a leisurely journey into examining xaya-cli. We walked through different kinds of examples. In some examples we used options for xaya-cli and in others we didn't need any options. We looked at several generic commands that are also found in Bitcoin. We also looked at some commands that are specific to XAYA.

The techniques you learned above through examples can be applied more generally. Check the documentation for the options and commands as shown above.

Remember to check the regtestnet tutorial to find out how you can experiment in a private blockchain without fear of making a mistake.

See Also

See more information about XAYA RPC methods here.

See more information about daemon options for xayad here.

See more information about running xayad for games here.

See more information about xaya.conf here.