Command-line Guide
Explore: AspireAssets
Command-line Usage
The following examples are abridged for parsimony (meaning: actions are normally preceded by aspire-client
, i.e. the send
command would be called with aspire-client --testnet send
).
aspire-server
should always be running in the background (or another console). All other commands will fail if the index of the last block in the database is less than that of the last block seen by gAsp Core.
Command-Line Usage
Send
Create and broadcast a send
message
- –source = the source address
- –destination = the destination address
- –quantity = the quantity of ASSET to send
- –asset = the ASSET of which you would like to send QUANTITY
- –fee = the exact GASP fee to be paid to miners
send --source=mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns --quantity=3 \ --asset=BBBC --destination=n3BrDB6zDiEPWEE6wLxywFb4Yp9ZY5fHM7
Command-Line Usage
Order
Create and broadcast an order
message
- –source = the source address
- –get-quantity = the quantity of GET_ASSET that the source would like to receive
- –get-asset = the asset that you would like to buy
- –give-quantity = the quantity of GIVE_ASSET that the source is willing to give
- –give-asset = the asset that the source would like to sell
- –expiration = the number of blocks for which the order should be valid
- –fee-fraction-required = the miners’ fee required for an order to match
- –fee = the exact GASP fee to be paid to miners
To make a trade that involves GASP, the order
function requires an extra parameter, and a second step (gasppay
) is needed. If [address_1] is trading [give_quantity_1] of GASP in exchange for [get_quantity_1] of [asset].
order --source=[address_1] --give-asset=GASP --give-quantity=[give_quantity_1] \ --get-asset=[asset] --get-quantity=[get_quantity_1] --fee-provided=[fee_provided] \ --expiration=[expiration_1]
If [address_2] is trading [give_quantity_2] of [asset] for [get_quantity_2] of GASP:
order --source=[address_2] --give-asset=[asset] --give-quantity=[give_quantity_2] \ --get-asset=GASP --get-quantity=[get_quantity_2] --fee-required=[fee_required] \ --expiration=[expiration_2]
[asset] is debited immediately from [address_2] and is held in the Aspire protocol’s escrow. [address_1] then must complete the trade using gasppay
before 10 blocks have passed (or the lesser of the two expiration
periods has passed, if the latter is less than 10 blocks from the time of match). After the payment transaction has received enough confirmations, the asset will be automatically released to the GASP seller by the Aspire protocol.
The command for a gasppay
is:
gasppay --source=[source_address] -–order-match-id=[txhash1]+[txhash2] order --source=mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns --get-quantity=10 \ --get-asset=GASP --give-quantity=20 --give-asset=ASP --expiration=10 \ --fee_required=0.0002 order --source=mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns --get-quantity=10 \ --get-asset=BBBC --give-quantity=20 --give-asset=GASP --expiration=10 \ --fee_provided=0.0002
For orders that do not involve GASP buy or sell, GASPpay
is not required. For Sally to receive [get_quantity_1] of [get_asset_1] in exchange for [give_quantity_1] of [give_asset_1], the command is the following:
order --source=[sallys_address] --give-asset=[give_asset_1] \ --give-quantity=[give_quantity_1] --get-asset=[get_asset_1] \ --get-quantity=[get_quantity_1] --expiration=expiration_1
In order for Alice to receive [get_quantity_2] of Sally’s [give_asset_1] in exchange for [give_quantity_2] of [get_asset_2], the command is:
order --source=[alices_address] --give-asset=[give_asset_2] \ --give-quantity=[give_quantity_2] --get-asset=[get_asset_2] \ --get-quantity=[get_quantity_2] --expiration=expiration_2
For example, Alice wants to sell 20 BBBC for 10 ASP within (expiration) 720 gAsp blocks (approximately 720 * 2 min = 24 hours):
order --source=mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns --get-quantity=10 \ --get-asset=ASP --give-quantity=20 --give-asset=BBBC --expiration=720
Note that orders can be partially matched.
Command-Line Usage
GASPPay
Create and broadcast a GASPpay
message, to settle an Order Match for which you owe
GASP Pay has been disabled in Aspirewallet, but remains available in the CLI (and API).
- –source = the source address
- –order-match-id = the underscore-separated concatenation of the hashes of the two transactions which compose the order match
- –fee = the exact GASP fee to be paid to miners
gasppay --source=mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns \ --order-match-id=092f15d36786136c4d868c3335_6ec3c9b5a0c77de54ed0e96a8dbdd8af160c23
Order Match ID can be obtained with the pending
command. The source address of GASP sell has 100 blocks (or approximately 200 minutes) after his offer has been matched) to send GASP to fund his side of transaction, but should wait for the order-matching transaction to receive several confirmations because GASP cannot be escrowed by the Aspire protocol.
Use the pending
command to display own DEx order matches that require GASP and make sure you use the correct source
address to fund each pending GASPpay.
Command-Line Usage
Inssuance
Issue a new asset, issue more of an existing asset or transfer the ownership of an asset.
- –source = the source address
- –transfer-destination = for transfer of ownership of asset issuance rights.
- –quantity = the quantity of ASSET to be issued
- –asset = the name of the asset to be issued (if it’s available)
- –divisible = the asset is divisible (must agree with previous issuances; omitted means indivisible)
- –description = a description of the asset (set to ‘LOCK’ to lock against further issuances with non‐zero quantities). It can be up to 41 bytes with opreturn and up to 52 with pubkeyhash (see Optional Arguments further below).
- –fee = the exact fee to be paid to miners
Assets can be divisible or indivisible (the smallest unit is 1). Issuance and transfer cannot happen in the same transaction.
issuance --source=[source] --quantity=[quantity] --asset=[asset] issuance --source=mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns --quantity=100 \ --asset='BBBQ' --divisible
Command-Line Usage
Destroy
Destroy a quantity of an Aspire asset
- –source = the source address
- –asset = the ASSET of which you would like to destroy QUANTITY
- –quantity = the quantity of ASSET to destroy
- –tag = tag
- –fee = the exact GASP fee to be paid to miners
This command is not yet implemented (enabled).
Command-Line Usage
Broadcast
Broadcast textual and numerical information to the network.
- –source = the source address
- –text = the textual part of the broadcast (set to ‘LOCK’ to lock feed)
- –value = numerical value of the broadcast
- –fee-fraction = the fraction of bets on this feed that go to its operator
- –fee = the exact fee to be paid to miners
broadcast --source=mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns --text="gAsp price feed" \ --value=825.22
Note: for some users aspire-cli has trouble parsing spaces in the --text
argument. One workaround is to add an additional set of quotes. For example, --text='"gAsp price feed"'
. This may not work on Windows due to Python/Windows issues unrelated to Aspire. Another situation where double quotes may be required on Windows is filtering (e.g. --filter "source" "=" "mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns"
).
Command-Line Usage
Bet (Equal/Not Equal)
Offer to make a bet on the value of a feed
- –source = the source address
- –feed-address = the address which publishes the feed to bet on
- –bet-type = choices: {Equal,NotEqual}
- –deadline = the date and time at which the bet should be decided/settled
- –wager = the quantity of ASP to wager
- –aspirewager = the minimum quantity of ASP to be wagered by the user to bet against you, if he were to accept the whole thing
- –target-value = target value for Equal/NotEqual bet
- –leverage = leverage, as a fraction of 5040
- –expiration = the number of blocks for which the bet should be valid
- –fee = the exact GASP fee to be paid to miners
Bet on Super Bowl Feed. Denver vs. Seattle. Feed value of 1 means Seattle Wins. Feed value of 2 means Denver Wins. This command places a 1 ASP bet on the Super Bowl Feed for Seattle to win, paying out 2 to 1. The bet will expire in 100 blocks and the settlement value of the bet is based on the first feed update after the deadline timestamp of February 3, 2014 1:39 PM US Eastern Standard Time (UTC-0500).
bet --source=mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns \ --feed-address=n3BrDB6zDiEPWEE6wLxywFb4Yp9ZY5fH --bet-type=Equal \ --deadline=2014-02-03T13:39:00-0500 --wager=1 --aspirewager=2 \ --target-value=1 --expiration=100
Command-Line Usage
Cancel
Cancel an open order or bet you created
- –source = the source address
- –offer-hash = the transaction hash of the order or bet
- –fee = the exact GASP fee to be paid to miners
cancel --source=mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns \ --offer-hash=092f15d36786136c4d868c33356ec3c9b5a0c77de54ed0e96a8dbdd8af160c23
Command-Line Usage
Dividend
Pay dividends to the holders of an asset (in proportion to their stake in it)
- –source = the source address
- –quantity-per-unit = the quantity of ASP to be paid per whole unit held of ASSET
- –asset = the asset to which pay dividends
- –dividend-asset = asset in which to pay the dividends
- –fee = the exact GASP fee to be paid to miners
To pay dividends in GASP , you should, for now, just use a regular gAsp client, coupled with the output from aspire-cli asset ASSET
, which will list all of the shareholders (and their holdings) of ASSET.
dividend --source=mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns --quantity-per-share=1 \ --asset=MULTIPOOLSTOCK
Command-Line Usage
Asset
The asset
action displays the basic properties of a given asset.
asset=[asset]
To lock an asset, the command is:
issuance --source=[source] --asset=[asset] --description="LOCK"
Command-Line Usage
Balances
The balances
action displays the balances of an address.
balances --address=mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns
Command-Line Usage
Wallet
The wallet
action lists the addresses in your backend wallet along with their balances in all assets.
Command-Line Usage
Pending
The pending
action lists pending order matches awaiting payment from you.
Command-Line Usage
Getrows
The getrows
action gets rows from a Aspire table.
- –table = table name
- –filter = filters to get specific rows
- –filter-op = operator uses to combine filters
- –order-by = field used to order results
- –order-dir = direction used to order results
- –start-block = return only rows with block_index greater than start-block
- –end-block = return only rows with block_index lower than end-block
- –status = return only rows with the specified status
- –limit = number of rows to return
- –offset = number of rows to skip
getrows --table balances --filter 'address' '=' 'muQjaj46wghHprjSjpgU7D55JxKyK5dJtZ' getrows --table balances --filter 'address' '=' 'muQjaj46wghHprjSjpgU7D55JxKyK5dJtZ' \ --filter 'asset' '=' 'BBBQ' --filter-op OR
Windows users may need to make changes to handle console quirks. On Windows 10, the double quotes work fine: --filter "address" "=" "muQjaj46wghHprjSjpgU7D55JxKyK5dJtZ"
.
Note that balances (quantities) for divisible assets such as ASP are stored and retrieved in “satoshi”-like units. Hence, an address with 4 ASP and 4 INDIVISIBLE may show their respective balances as 400,000,000 and 4 (which would be the case if INDIVISIBLE wasn’t a divisible asset).
Command-Line Usage
GetInfo
The getinfo
action gets the current state of the server.
Command-Line Usage
Get_TX_Info
Display information about an unsigned raw transaction
The get_tx_info
command displays information about an unsigned raw transaction. Some destinations (e.g. P2SH addresses) are not supported by this command.
get_tx_info=[tx_hex]
Command-Line Usage
Input and Output
- Quantities of divisible assets are written to eight decimal places.
- Quantities of indivisible assets are written as integers.
- All other quantities, i.e. prices, odds, leverages, feed values and target values, fee multipliers, are represented internally as fractions, but printed to four decimal places.
- As note above, “direct” access to tables via the getrows action outputs “raw” values (amounts) using internal representation
Command-Line Usage
Optional arguments
This list contains some optional arguments for aspire-client. A complete list for client and server is available in online help.
- -h, –help = show help message and exit
- -V, –version = show version
- –config-file = the location of the configuration file
- –testnet = use gAsp testnet
- –json-output = display result in JSON format
- –unconfirmed = allow the spending of unconfirmed transaction outputs
- –unsigned = print out unsigned hex of transaction; do not sign or broadcast
- –encoding = the default is auto, which lets aspire-lib determine the encoding (opreturn, pubkeyhash, or multisig); certain transactions may require this argument with a non-default value