spec/api: Document client RPC server http methods.

[JoeGruffins]

@vctt94 for one was asking how to communicate with core using Decrediton. Hopefully this opens up the rpcserver to be used by consumers other than dexcctl.

While writing this out I noticed a few things I would like input on.

• The rpcserver accepts all arguments in a string array. That was done for ease of implementation but I think we could use an array of interfaces if it is wierd. I think it's fine.
• You can't send various http requests to the websocket server. So you can't get an elevated connection and then trade with that. The consumer needs to keep up with the http client and the websocket client to get the full monty. I think the webserver also juggles those two, but everything is internal so it's not a problem.
• @buck54321 was talking about notifications from core. I don't guess the rpcserver can do that right now? What notifications?

[buck54321]

We actually don't specify client implementation, but this is all good info. Let's make it a wiki page or the readme for the client/rpcserver package.

[JoeGruffins]

@buck54321 Where should I put it exactly? In spec folder? Thanks for reviewing.

[vctt94]

Great! This will be very helpful. I think we can add it to dex's docs folder.

One good example of docs is the one from dcrd: https://github.com/decred/dcrd/tree/master/docs

but anyway, I think that's a good start

[buck54321]

Where should I put it exactly? In spec folder? Thanks for reviewing.

So if you make it a readme for rpcserver, you'd put it at client/rpcserver/README.mediawiki. To make it a wiki page, see https://github.com/decred/dcrdex/wiki.

The specification document just doesn't describe the client. Or the server, for that matter. Just the API and protocols.

[JoeGruffins]

Moved to the wiki. Not sure at all to pr this. Changes can be seen here:
https://github.com/JoeGruffins/dcrdex/wiki

This is the diff:

diff

commit ce478c568bbd9ba0bf562c8dece89c7e5f9a04aa
Author: JoeGruff <joegruffins@gmail.com>
Date:   Tue Sep 29 10:14:34 2020 +0900

    wiki: Add client rpcserver.

diff --git a/Client.mediawiki b/Client.mediawiki
new file mode 100644
index 0000000..1ec4a06
--- /dev/null
+++ b/Client.mediawiki
@@ -0,0 +1,793 @@
+==Client==
+
+==RPC Server==
+
+==HTTPS==
+
+All http requests sent to the RPC server must contain basic auth with a
+user:password pair that the server will accept.
+
+Communication is done using [https://golang.org/pkg/crypto/tls/ tls].
+
+Requests must be constucted as specified in [https://github.com/decred/dcrdex/blob/master/spec/comm.mediawiki/#Message_Protocol Message Protocol]
+
+===Payload===
+
+All requests require the same payload. All individual arguments are strings.
+Return values vary.
+
+<code>payload</code>
+{|
+! field !! type   !! description
+|-
+| PWArgs  || &#91;string&#93; || An array of password arguments. Can be null.
+|-
+| args    || &#91;string&#93; || An array of arguments. Can be null.
+|}
+
+Arguments in arrays are positional and must be placed in the order they appear
+here. If an argument is optional, but a placeholder is needed, an empty
+string "" can be used. Arguments have a psuedo-type. For example,
+if bool, the argument must be the string representation of a truthy value. i.e.
+"true" or "1"
+
+Returns will come with an error if there was a problem. If arguments could not
+be parsed, a help message for that specific route/command is returned.
+
+
+===Help===
+
+Print a help message.
+
+'''Request route:''' <code>help</code>
+
+<code>args</code>
+{|
+! name !! psuedo-type !! description
+|-
+| cmd || string  || Optional. The command to print help for.
+|-
+| includePasswords || bool || Optional. Default is false. Whether to include password arguments in the returned help. Passwords are hidden when using dexcctl.
+|}
+
+'''Response'''
+
+The response will contain a help message based on the arguments.
+
+<code>payload</code>
+{|
+! type !! description
+|-
+| string ||  The help message for command.
+|}
+
+
+===Version===
+
+Print the DEX client rpcserver version. Accepts no arguments
+
+'''Request route:''' <code>version</code>
+
+'''Response'''
+
+The response will contain the semver as a string. i.e. "1.0.0"
+
+<code>payload</code>
+{|
+! type !! description
+|-
+| string || The DEX client rpcserver version.
+|}
+
+
+===Init===
+
+Initialize the client with a password.
+
+'''Request route:''' <code>init</code>
+
+<code>PWArgs</code>
+{|
+! name !! type !! description
+|-
+| appPass || string  || The DEX client password.
+|}
+
+'''Response'''
+
+The response will contain a message.
+
+<code>payload</code>
+{|
+! type !! description
+|-
+| string || The message "app initialized".
+|}
+
+
+===Get Fee===
+
+Print a help message.
+
+'''Request route:''' <code>getfee</code>
+
+<code>args</code>
+{|
+! name !! psuedo-type !! description
+|-
+| dex || string  || The dex address to get fee for.
+|-
+| cert || string || Optional. The TLS certificate path.
+|}
+
+'''Response'''
+
+The response will contain the fee.
+
+<code>payload</code>
+{|
+! type !! description
+|-
+| object || The getFee result.
+|}
+
+'''JSON GetFeeResult object'''
+
+{|
+! field   !! type   !! description
+|-
+| fee      || int   || The DEX registration fee.
+|}
+
+
+===New Wallet===
+
+Connect to a new wallet.
+
+'''Request route:''' <code>newwallet</code>
+
+<code>PWArgs</code>
+{|
+! name !! type !! description
+|-
+| appPass || string  || The DEX client password.
+|-
+| walletPass || string  || The wallet's password. The client will encrypt and store this.
+|}
+
+<code>args</code>
+{|
+! name !! psuedo-type !! description
+|-
+| cmd || string  || Optional. The command to print help for.
+|-
+| assetID  || int || The asset's BIP-44 registered coin index. e.g. 42 for DCR. See [https://github.com/satoshilabs/slips/blob/master/slip-0044.md slip0044]
+|-
+| path     || string  || Optional. Text from a configuration file.
+|-
+| settings || object  || Optional. A JSON-encoded string->string mapping of additional configuration settings. These settings take precedence over any settings parsed from file. e.g. '{"account":"default"}' for Decred accounts, and '{"walletname":""}' for the default Bitcoin wallet where bitcoind's listwallets RPC gives possible walletnames.
+|}
+
+'''Response'''
+
+The response will contain a message.
+
+<code>payload</code>
+{|
+! type !! description
+|-
+| string ||  The message "&#91;coin symbol&#93; wallet created and unlocked".
+|}
+
+
+===Open Wallet===
+
+Unlock an existing wallet for one year.
+
+'''Request route:''' <code>openwallet</code>
+
+<code>PWArgs</code>
+{|
+! name !! type !! description
+|-
+| appPass || string  || The DEX client password.
+|}
+
+<code>args</code>
+{|
+! name !! psuedo-type !! description
+|-
+| assetID  || int || The asset's BIP-44 registered coin index. e.g. 42 for DCR. See [https://github.com/satoshilabs/slips/blob/master/slip-0044.md slip0044]
+|}
+
+'''Response'''
+
+The response will contain a message.
+
+<code>payload</code>
+{|
+! type !! description
+|-
+| string ||  The message "&#91;coin symbol&#93; wallet unlocked".
+|}
+
+
+===Close Wallet===
+
+Lock an existing wallet.
+
+'''Request route:''' <code>lockwallet</code>
+
+<code>args</code>
+{|
+! name !! psuedo-type !! description
+|-
+| assetID  || int || The asset's BIP-44 registered coin index. e.g. 42 for DCR. See [https://github.com/satoshilabs/slips/blob/master/slip-0044.md slip0044]
+|}
+
+'''Response'''
+
+The response will contain a message.
+
+<code>payload</code>
+{|
+! type !! description
+|-
+| string ||  The message "&#91;coin symbol&#93; wallet locked".
+|}
+
+
+===Wallets===
+
+Get information about all wallets registered with the client. Accepts no arguments.
+
+'''Request route:''' <code>wallets</code>
+
+'''Response'''
+
+The response will contain an array of infomation for each wallet.
+
+<code>payload</code>
+{|
+! type !! description
+|-
+| &#91;object&#93; || A list of '''WalletInfo''' objects (described below).
+|}
+
+'''JSON WalletInfo object'''
+
+{|
+! field   !! type   !! description
+|-
+| symbol  || string || The coin symbol.
+|-
+| assetID || int    || The asset's BIP-44 registered coin index. e.g. 42 for DCR. See [https://github.com/satoshilabs/slips/blob/master/slip-0044.md slip0044]
+|-
+| open    || bool   || Whether the wallet is unlocked.
+|-
+| running || bool   || Whether the wallet is running.
+|-
+| updated || int    || Unix time of last balance update. Seconds since 00:00:00 Jan 1 1970.
+|-
+| balance || object || A Balance object (described below).
+|-
+| address || string || A wallet address.
+|-
+| feerate || int    || The fee rate.
+|-
+| units   || string || Unit of measure for amounts.
+|}
+
+'''JSON Balance object'''
+
+{|
+! field   !! type   !! description
+|-
+| available || int || The balance available for funding orders case.
+|-
+| immature  || int || Balance that requires confirmations before use.
+|-
+| locked    || int || The total locked balance.
+|-
+| stamp     || string || Time stamp.
+|}
+
+
+===Register===
+
+Register for a DEX. An ok response does not mean that registration is complete.
+Registration is complete after the fee transaction has been confirmed.
+
+'''Request route:''' <code>register</code>
+
+<code>PWArgs</code>
+{|
+! name !! type !! description
+|-
+| appPass || string  || The DEX client password.
+|}
+
+<code>args</code>
+{|
+! name !! psuedo-type !! description
+|-
+| addr || string  || The DEX address to register for.
+|-
+| fee  || int  || The DEX fee.
+|-
+| cert || string  || Optional. The TLS certificate.
+|}
+
+'''Response'''
+
+The response will contain a RegisterResult object.
+
+<code>payload</code>
+{|
+! type !! description
+|-
+| object ||  The RegisterResult (described below).
+|}
+
+'''JSON RegisterResult object'''
+
+{|
+! field   !! type   !! description
+|-
+| feeID       || string || The fee transactions's txid and output index.
+|-
+| reqConfirms || int || The number of confirmations required to start trading.
+|}
+
+
+===Exchanges===
+
+Detailed information about known exchanges and markets. Arguments not accepted.
+
+'''Request route:''' <code>exchanges</code>
+
+'''Response'''
+
+The response will contain an Exchanges object.
+
+<code>payload</code>
+{|
+! type !! description
+|-
+| object ||  An Exchanges object (described below).
+|}
+
+'''JSON Exchanges object'''
+
+{|
+! field   !! type   !! description
+|-
+| &#91;DEX host&#93; || object || Repeating. An Exchange object (described below)
+|}
+
+'''JSON Exchange object'''
+
+{|
+! field   !! type   !! description
+|-
+| markets       || object || A Markets object (described below).
+|-
+| assets        || object || An Assets object (described below).
+|-
+| confsrequired || int || The number of confirmations needed for the registration fee payment.
+|-
+| confs         || int || The current number of confirmations for the registration fee payment. This is only present during the registration process.
+|}
+
+'''JSON Markets object'''
+
+{|
+! field   !! type   !! description
+|-
+| &#91;assetID-assetID&#93; || object || Repeating. A Market object (described below)
+|}
+
+'''JSON Market object'''
+
+{|
+! field   !! type   !! description
+|-
+| baseid      || int || The base asset ID.
+|-
+| basesymbol  || string || The base ticker symbol.
+|-
+| quoteid     || int || The quote asset ID.
+|-
+| quotesymbol || string || The quote asset ID symbol,
+|-
+| epochlen    || int || Duration of a epoch in milliseconds.
+|-
+| startepoch  || int || Time of start of the last epoch in milliseconds since 00:00:00 Jan 1 1970.
+|-
+| buybuffer   || float || The minimum order size for a market buy order.
+|}
+
+'''JSON Assets object'''
+
+{|
+! field   !! type   !! description
+|-
+| &#91;assetID&#93; || object || Repeating. An Asset object (described below)
+|}
+
+'''JSON Asset object'''
+
+{|
+! field   !! type   !! description
+|-
+| symbol       || string || The asset's coin symbol.
+|-
+| lotSize      || int || The amount of units of a coin in one lot.
+|-
+| rateStep     || int || the price rate increment in atoms.
+|-
+| feeRate      || int || The transaction fee in atoms per byte.
+|-
+| swapSize     || int || The size of a swap transaction in bytes.
+|-
+| swapSizeBase || int || The size of a swap transaction minus inputs in bytes.
+|-
+| swapConf     || int || The number of confirmations needed to confirm trade transactions.
+|}
+
+
+===Login===
+
+Attempt to login to all registered DEX servers.
+
+'''Request route:''' <code>login</code>
+
+<code>PWArgs</code>
+{|
+! name !! type !! description
+|-
+| appPass || string  || The DEX client password.
+|}
+
+'''Response'''
+
+The response will contain a LoginResult.
+
+<code>payload</code>
+{|
+! type !! description
+|-
+| object ||  The LoginResult (described below).
+|}
+
+'''JSON LoginResult object'''
+
+{|
+! field   !! type   !! description
+|-
+| notification || &#91;object&#93; || A list of Notification objects (described below).
+|-
+| dexes        || &#91;object&#93; || A list of Dex objects (described below).
+|}
+
+'''JSON Notification object'''
+
+{|
+! field   !! type   !! description
+|-
+| type     || string || The notification type.
+|-
+| subject  || string || A clarification of type.
+|-
+| details  || string || The notification details.
+|-
+| severity || int || The importance of the notification on a scale of 0 through 5.
+|-
+| stamp    || int || Unix time of the notification. Seconds since 00:00:00 Jan 1 1970.
+|-
+| acked    || bool || Whether the notification was acknowledged.
+|-
+| id       || string || A unique hex ID.
+|}
+
+'''JSON DEX object'''
+
+{|
+! field   !! type   !! description
+|-
+| host     || string || The DEX address.
+|-
+| acctID   || string || A unique hex ID.
+|-
+| authed   || bool || Whether the dex has been successfully authed.
+|-
+| autherr  || string || Omitted if authed. If not authed, the reason.
+|-
+| tradeIDs || &#91;string&#93; || An array of active trade IDs.
+|}
+
+
+===Trade===
+
+Make an order to buy or sell an asset.
+
+'''Request route:''' <code>trade</code>
+
+<code>PWArgs</code>
+{|
+! name !! type !! description
+|-
+| appPass || string  || The DEX client password.
+|}
+
+<code>args</code>
+{|
+! name !! psuedo-type !! description
+|-
+| host      || string || The DEX to trade on.
+|-
+| isLimit   || bool || Whether the order is a limit order.
+|-
+| sell      || bool || Whether the order is selling.
+|-
+| base      || int || The BIP-44 coin index for the market's base asset.
+|-
+| quote     || int || The BIP-44 coin index for the market's quote asset.
+|-
+| qty       || int || The number of units to buy/sell. Must be a multiple of the lot size.
+|-
+| rate      || int || The atoms quote asset to pay/accept per unit base asset. e.g. 156000 satoshi/DCR for the DCR(base)_BTC(quote).
+|-
+| immediate || bool || Require immediate match. Do not book the order.
+|}
+
+'''Response'''
+
+The response will contain an OrderDetails.
+
+<code>payload</code>
+{|
+! type !! description
+|-
+| object ||  An OrderDetails object (describled below).
+|}
+
+'''JSON OrderDetails object'''
+
+{|
+! field   !! type   !! description
+|-
+| orderid || string || The order's unique hex identifier.
+|-
+| sig     || string || The DEX's signature of the order information.
+|-
+| stamp   || int || The time the order was signed in milliseconds since 00:00:00 Jan 1 1970.
+|}
+
+
+===Cancel===
+
+Cancel an order.
+
+'''Request route:''' <code>cancel</code>
+
+<code>PWArgs</code>
+{|
+! name !! type !! description
+|-
+| appPass || string  || The DEX client password.
+|}
+
+<code>args</code>
+{|
+! name !! psuedo-type !! description
+|-
+| orderID || string  || The hex ID of the order to cancel.
+|}
+
+'''Response'''
+
+The response will contain a message.
+
+<code>payload</code>
+{|
+! type !! description
+|-
+| string ||  The message "canceled order &#91;order ID&#93;".
+|}
+
+
+===Withdraw===
+
+Withdraw value from an exchange wallet to address.
+
+'''Request route:''' <code>withdraw</code>
+
+<code>PWArgs</code>
+{|
+! name !! type !! description
+|-
+| appPass || string  || The DEX client password.
+|}
+
+<code>args</code>
+{|
+! name !! psuedo-type !! description
+|-
+| assetID || int || The asset's BIP-44 registered coin index. Used to identify which wallet to withdraw from. e.g. 42 for DCR. See [https://github.com/satoshilabs/slips/blob/master/slip-0044.md slip0044]
+|-
+| value   || int || The amount to withdraw in units of the asset's smallest denomination (e.g. satoshis, atoms, etc.)
+|-
+| address || string || The address to which withdrawn funds are sent.
+|}
+
+'''Response'''
+
+The response will contain coin ID of the withdraw transaction.
+
+<code>payload</code>
+{|
+! type !! description
+|-
+| string ||  "&#91;coin ID&#93;".
+|}
+
+
+===Logout===
+
+Logout the DEX client. Accepts no arguments.
+
+'''Request route:''' <code>logout</code>
+
+'''Response'''
+
+The response will contain a message.
+
+<code>payload</code>
+{|
+! type !! description
+|-
+| string || The message "goodbye"
+|}
+
+
+===Order Book===
+
+Retrieve all orders for a market.
+
+'''Request route:''' <code>orderbook</code>
+
+<code>args</code>
+{|
+! name !! psuedo-type !! description
+|-
+| host    || string || The DEX to retrieve the order book from.
+|-
+| base    || int || The BIP-44 coin index for the market's base asset.
+|-
+| quote   || int || The BIP-44 coin index for the market's quote asset.
+|-
+| nOrders || int || Optional. Default is 0, which returns all orders. The number of orders from the top of buys and sells to return. Epoch orders are not truncated.
+|}
+
+'''Response'''
+
+The response will contain an OrderBook object.
+
+<code>payload</code>
+{|
+! type !! description
+|-
+| object ||  An OrderBook object (described below).
+|}
+
+'''JSON OrderBook object'''
+
+{|
+! field   !! type   !! description
+|-
+| sells || &#91;object&#93; || An array of booked MiniOrder objects (described below).
+|-
+| buys  || &#91;object&#93; || An array of booked buy MiniOrder objects.
+|-
+| epoch || &#91;object&#93; || An array of epoch MiniOrder objects. Epoch orders include all kinds of orders, even those that cannot or may not be booked. They are not truncated.
+|}
+
+'''JSON MiniOrder object'''
+
+{|
+! field   !! type   !! description
+|-
+| qty   || float || The number of coins base asset being bought or sold.
+|-
+| rate  || float || The coins quote asset to accept per coin base asset.
+|-
+| sell  || bool || Whether this order is a sell order.
+|-
+| token || string || The first 8 bytes of the order id, coded in hex.
+|-
+| epoch || int || Only present for epoch orders. The order's epoch.
+|}
+
+
+===My Orders===
+
+Fetch all active and recently executed orders belonging to the user.
+
+'''Request route:''' <code>myorders</code>
+
+<code>args</code>
+{|
+! name !! psuedo-type !! description
+|-
+| host  || string || Optional. The DEX to show orders from.
+|-
+| base  || int || Optional. The BIP-44 coin index for the market's base asset.
+|-
+| quote || int || Optional. The BIP-44 coin index for the market's quote asset.
+|}
+
+'''Response'''
+
+The response will contain a list of Order objects.
+
+<code>payload</code>
+{|
+! type !! description
+|-
+| &#91;object&#93; ||  A list of Order objects (described below).
+|}
+
+'''JSON Order object'''
+
+{|
+! field   !! type   !! description
+|-
+| host       || string || The DEX address.
+|-
+| marketName || string || The market's name. e.g. "DCR_BTC".
+|-
+| baseID     || int || The market's base asset BIP-44 coin index. e.g. 42 for DCR.
+|-
+| quoteID    || int || The market's quote asset BIP-44 coin index. e.g. 0 for BTC.
+|-
+| id         || string || The order's unique hex ID.
+|-
+| type       || string || The type of order. "limit", "market", or "cancel".
+|-
+| sell       || string || Whether this order is selling.
+|-
+| stamp      || int || Time the order was made in milliseconds since 00:00:00 Jan 1 1970.
+|-
+| age        || string || The time that this order has been active in human readable form.
+|-
+| rate       || int || The exchange rate limit. Limit orders only. Units: quote asset per unit base asset.
+|-
+| quantity   || int || The amount being traded.
+|-
+| filled     || int || The order quantity that has matched.
+|-
+| settled    || int || The sum quantity of all completed matches.
+|-
+| status     || string || The status of the order. "epoch", "booked", "executed", "canceled", or "revoked".
+|-
+| cancelling || bool || Whether this order is in the process of cancelling.
+|-
+| canceled   || bool || Whether this order has been canceled.
+|-
+| tif        || string || "immediate" if this limit order will only match for one epoch. "standing" if the order can continue matching until filled or cancelled.
+|}
+
+==Websocket==
+
+A connection to the websocket server can be made through the RPC server. The
+websocket server server allows for notifications from a market and other long
+running operations.
+
+Connect by providing proper credentials and a valid header when visiting
+"wss://&#91;RPC Server Address&#93;/ws".
+
+==Examples==
+
+An example of setting up both an https and wss connection to the RPC server can
+be found [https://github.com/decred/dcrdex/blob/master/docs/examples/rpcclient here]

[chappjc]

Sorry for the delay. Can you nuke the go.{mod,sum} files? We just have the one module for now.

I'll get your wiki diff committed to dcrdex.wiki master.

[chappjc]

Thanks. The wiki is updated BTW. I made some edits to clarify the page a bit.