================================================================= Voucher Shell Command Line Client - rev 1.0.4 31st August, 2018 o Connect to a Jabber server (anonymous login to OFS): connect [xmppdomain] The and refer to the OFS. The optional [xmppdomain] should be specified whenever the XMPP domain of the OFS is not the same as the host. example: vsh> connect ofs.voucher-safe.org 5233 Note that this can also be specified via the -h, -p, and -x arguments passed to the CLI on the command line. Connection is automatic on startup; hence this command is meant for switching between OFSen. o Log in to a voucher safe: login [-a] [ -v -p -l -h ] example: vsh> login -v foobar-123 -p 0007 -l JamesBond -h LiveAndLetDie If the VS number does not contain a domain, the value of prefPublisher in the ~/.vouchers/.vshrc properties file is assumed. Anything not supplied will be prompted for; long-phrases may be specified in full using -l, else 3 specific characters will be requested rather than the full phrase. The -a flag indicates that the CLI should auto-login to the VS whose number and login credentials are specified in the properties file $HOME/.vouchers/.vshlogin. Any other arguments passed will override the corresponding setting in that file. (This mechanism is chiefly intended for use in cases where the CLI is invoked by a web server processing an incoming payment on a merchant website.) Note: a system file-locking mechanism is utilized as a semaphore to prevent simultaneous logins into the same VS, even by separate instances of the CLI. If a duplicate login is attempted, it will block waiting for the lock to be released. If this does not occur within 30 seconds, the waiting login will timeout and fail. o Log out of a voucher safe: vsh> logout Purges any tokens spent at the SDS or DHT, and destroys data structures. Releases system login lock on the VS. Does not disconnect from the OFS. o Disconnect from an OFS: vsh> disconnect Terminates the XMPP server connection. Performs implicit logout if presently logged in. o Terminate the voucher shell: quit|bye|exit Performs implicit logout and disconnect if needed, and exits the CLI. example: vsh> quit o Display the CLI build version and date: vsh> version o List voucher safe contents following login: For vouchers: ls vouchers [-t] [-s ] [-u ] [-a ] [-e ] [-i ] Retrieves, decodes, and displays vouchers in safe. The -t flag shows a value total in the user's currency preference. The -s flag lists only vouchers matching the indicated serial number. The -u and -a flags restrict the listing to vouchers denominated in the given units or asset type. The -e flag shows only vouchers expiring before a given date, which must be in yyyy-MM-dd format. The -i flag restricts the listing to vouchers from the particular Issuer. For tokens: ls tokens [-l] [-i ] The -l flag shows the actual tokens rather than just the count of tokens available. The -i flag restricts the count or listing to tokens from the particular Issuer. For receipts: ls receipts [-t ] [-f ] Retrieves, decodes, and displays receipts in safe. The -t flag restricts listing to receipts TO the indicated VS. The -f flag restricts listing to receipts FROM the indicated VS. For pending payments: ls pend[ing|pay] Retrieves, decodes, and displays payments outstanding (awaiting pickup) made to other safes. Examples: vsh> ls vouchers -a USV -e 2014-11-30 vsh> ls tokens -l vsh> ls receipts -f somebody-1234 vsh> ls pendpay o To make a payment: pay -v -q [-u ] [-a ] [-t ] [-b n1=v1 n2=v2 ...] [-B ] [serial#1 serial#2 ...] The payee VS and quantity (amount) are required. The payee must be in the same publisher domain. Optional arguments are as follows: -u specify the units of the quantity -a specify the asset type -b specify a count followed by a list of "baggage field" name=value pairs -t specify the number of days for payment pickup (integral 1-7) serial# stipulate which voucher(s) are to be used to fund payment (if none are specified, vouchers will be auto-selected oldest first) OR: -B filename read payees and amounts from an external file, and perform multiple payments examples: vsh> pay -v buddy-9876 -q 100 -a EUROS vsh> pay -v merchant-8765 -q 29.95 -u USD -t 4 -b 1 orderId:123456 vsh> pay -v buddy-9876 -q 1000 87384390 37483974 23237289 Note that asset types and units may imply one another, e.g. asset type of EUROS implies units=EUR. However, an asset may support multiple units, e.g. -a GOLD -u OUNCES can be valid even if vouchers are denominated in GRAMS. A payment operation automatically picks up the confirmation record off the DHT, and stores a pendpay record on the SDS. Note this operation performs implicit refreshes of vouchers and tokens. For batch payments, each line of the lines in the file must look like this: payeeVS::amount:units:asset[:message] subject to these rules: - If the payeeVS omits the @publisher, this will be inferred from login. All payments in the batch must utilize the same publisher, whether stated or implied. - The amount, units, and asset must all be provided explicitly. However, the units field may be a voucher unit, or any supported currency code. The units and asset fields are case-insensitive. - The -t flag, if provided together with -B, applies to all payments. - Only a single baggage field is supported, which will be used as Message. - All other "pay" options are ignored. Some sample batch file entries: bob-1234::1.0:GAU:GOLD alice-2345::0.5:GAU:gold:thanks joecustomer-3456::19.95:USD:USDOLLARS:"refund on order #54321" foobar-4567@vouchi.com::99.95:usd:EUROS:"purchase order ABC9876" IMPORTANT NOTE: while the above four lines are all valid examples of a payment batch file entry, it is not possible to perform payments involving vouchers from different Issuers, with differing asset types, in the same batch. Therefore, when doing batch payments, make sure that: 1. All payments in the file pertain to a single voucher asset type. 2. Your source voucher safe contains ONLY vouchers from an Issuer which supports that voucher asset type, of sufficient value to perform all of the indicated payments. o To perform housekeeping (pickup of payments and receipts): refresh|housekeeping|fetch This retrieves, decodes, and processes all unmarked records on the DHT. It also attempts to recover any outstanding payments whose TTL has expired. A non-automatic mode, where the user lists and specifies individual items to process, is possible but not yet implemented. Note this operation performs implicit refresh of vouchers, tokens, and pendpays. example: vsh> refresh o Receive an expected incoming voucher payment receive [-v VS# ] [-b field:value] This operation is a kind of special case for housekeeping, which will search for an incoming payment matching the search criteria and pick up that payment *only*, ignoring any other housekeeping tasks. It is intended for use when the CLI is being invoked by a webserver on a merchant web site. The payment search criteria can be specified as follows: -v retrieve the first payment found from the indicated VS -b retrieve the first payment found having a baggage field named whose value is (It is valid to specify both criteria.) example: receive -b orderId:123456 This command performs an implicit "login -a" if the CLI is not presently logged in when the receive is executed. Tokens will be auto-purchased as needed, in the lot size specified by the value of tokenLotSize in the properties file $HOME/.vouchers/.vshrc. The CLI will auto-logout, disconnect from the OFS, and exit following completion. One of the following will be returned, as the last line of CLI output: NOT FOUND - if no payment matching the search criteria was found on the DHT JSON string - if the payment was picked up successfully err message - if an error occurred The JSON string returned on successful pickup is of the following form: { "PAYER":"", "AMOUNT":, "UNITS":"", "ASSET":"", "ISSUER":"", "",, "",, "", } where the 0-3 baggage fields are optional, and will be included only if present in the voucher payment. By checking e.g. orderId value, a web server can parse the JSON output and determine what back-end processing should be done. A copy of the receipt sent to the payer is also stored in the VS. (Receipts contain copies of all baggage fields.) The CLI can be triggered to perform just a single receive operation by passing it the "-w" (or "--web") argument on the command line, immediately followed by the -v or -b flag search criteria. example: Following successful pickup, if the newly added voucher brings the total number of vouchers from that Issuer to 10 or more, an implicit merge will be performed before the CLI logs out. This is to ensure that processing time does not increase linearly with the number of successful payments received (since all vouchers must be decoded following each login). o Manual token purchase: buy -n [serial#1 serial#2 ...] This performs a purchase of the indicated number of tokens. The type of tokens is inferred either from defaults or from the payment voucher(s) whose serial number(s) were provided. Note that token purchases are always performed automatically on an as-needed basis, in a lot size specified in the preferences file (see below). The count must be between 10 and 200. example: vsh> buy -n 100 o Remove unwanted receipts: rm receipts [index#] [-a] This is meant to be used following a "ls receipts" command. An individual receipt may be deleted by specifying its index number in the listing. The -a flag purges all receipts in the safe at once. example: vsh> rm receipts -a o Purge an expired voucher: rm voucher The voucher to be removed must be past its expiration date. It would also be a good idea to attempt to redeem it first. example: vsh> rm voucher 8454973904 o Merge two or more vouchers together: merge -i [serial3 ... serial25] The vouchers designated must be of consistent Issuer and asset types. The maximum number of vouchers which can be merged in a single operation is 25. example: vsh> merge 234832 374830 293841 o Set the current Issuer: set issuer For certain operations (e.g. manually buying tokens, purging expired vouchers) it is necessary to specify a specific Issuer. Note too that the act of making or picking up a payment implicitly sets the default Issuer to that associated with the asset being transacted. example: vsh> set issuer SBC o Attempt to redeem an expired voucher: redeem [-r] The voucher to be redeemed/renewed must be past its expiration date. In addition, the Issuer of the voucher must support either renewal or redemption into an associated account. Issuers may support either, both, or neither of these policies for handling expired vouchers. To use redemption, the Issuer may require you to have an account which is associated with your VS number. Said account may be subject to KYC. The -r flag attempts a simple renewal (for a fresh voucher), similar to the validate command, except that it acts on expired vouchers (which cannot be revalidated). example: vsh> redeem 9454273904 -r ****The following commands are defined but not yet implemented:**** * Split a voucher into smaller vouchers: split val1 [val2 val3 ...] The given values must sum to an amount less than or equal to the value of the voucher. Any difference may be left implied as the value of the final voucher. * Revalidate a voucher nearing its expiration: validate * Verify the signature on a receipt using the signer's key: verify [-x] The index number refers to the receipt's label in the output of "ls receipts". The -x flag also causes the receipt's XML text to be emitted. * Manually pick up an incoming payment or receipt: pickup [-a] [-m "message"] The index number refers to the label in the housekeeping list. The -a flag triggers automatic processing of the entire list. The -m flag allows the user to specify a message to be sent back to the payer on an incoming payment (ignored for a receipt). * Manually recover an expired pending payment: recover The index number refers to the label of the payment in the output of "ls pending". * Show the current values of various settings: show [vs|sds|pks|dht|jid|pubkey|privkey|caps|all] vs - the VS# the shell is currently logged into sds - the hostname:port of the SDS pks - the hostname:port of the PKS dht - the hostname:port of the DHT jid - the JabberId of the user's anon login at the OFS pubkey - the safe's public key in PEM format privkey - the safe's private key in PEM format caps - the safe's folder hashes, read capability, and encrypted read-write capability all - all of the above * Obtain online help for a command: vsh> help [] Note that most commands display usage strings on entry of improper syntax. * Open a new voucher safe: create -v -p Generates and initializes a new VS. The user will be prompted for all other details, including recovery questions. (I.e. this is not meant to be used in a script.) * Close a voucher safe: close -v -p Close a safe, creating a successor safe for the vouchers and tokens if the safe is non-empty. The VS# and VP specified must match the ones the user is currently logged into. The user must manually confirm acceptance of the transfer agreement. * Recover a lost voucher safe: recovery -v The VS number must include the publisher domain. The user will be prompted for answers to the 5 recovery questions for that publisher. * Obtain the public key for another (or any) voucher safe: getkey Retrieves the public key for the indicated safe off of the PKS, and displays it in PEM format. The VS# must be in the same domain as the user's safe. * Display asset prices downloaded from the OFS: prices [-c ] [-a ] The -c flag causes pricing in the indicated currency (e.g. EUR, AUD, CAD). The -a flag allows stipulation of the asset type (only GOLD is supported presently, with relative fiat prices available by interpolation). Note that the CLI automatically maintains a current list of prices for the sake of performing payments, but the table is not shown. * Specify user defaults: set [ host | port | xmpp | pub | vs | asset | units | curr | issuer | mintokens ] Where: host - sets the default XMPP server (OFS) host port - sets the default XMPP server (OFS) port xmpp - sets the default XMPP server (OFS) domain pub - sets the default voucher publisher network vs - sets the default voucher safe for login asset - sets the default voucher asset type units - sets the default payment quantity units curr - sets the display currency preference mintokens - sets the token purchase lot size At present, these settings can be changed manually by editing the file $HOME/.vouchers/.vshrc. =========================== END ========================