diff --git a/docs/rest/API_draft.md b/docs/rest/API_draft.md index 5309b0d0fd..0721c1a99d 100644 --- a/docs/rest/API_draft.md +++ b/docs/rest/API_draft.md @@ -1,50 +1,38 @@ # API -Serve on `http://localhost:2024` +In order to allow for quick client development, with the security +of the light-client and ease of use the cli (embedding go-wire and +go-crypto), we will provide a REST API, which can run on localhost +as part of `basecli`, securely managing your keys, signing transactions, +and validating queries. It will be exposed for a locally deployed +application to make use of (eg. electron app, web server...) -Don't allow cors +By default we will serve on `http://localhost:2024`. CORS will be disabled by default. Potentially we can add a flag to enable it for one domain. -## Create Tx +## MVP -`POST /tx` +The MVP will allow us to move around money. This involves the +following functions: -Input: signed tx as json, just like --prepare... -Goes to the node, and returns result: +## Construct an unsigned tx -``` -{ - "check_tx": { - "code": 0, - "data": "", - "log": "" - }, - "deliver_tx": { - "code": 0, - "data": "", - "log": "" - }, - "hash": "4D0EB7853E71AB6E3021990CF733F70F4CC2E001", - "height": 1494 -} -``` - -`POST /sign` +`POST /build/send` Input: - +``` { - "name": "matt", - "password": "1234567890", - "tx": { - // just like prepare, tx (with sigs/multi but no sigs) - } + "to": {"app": "role", "addr": "62616E6B32" }, + "from": {"app": "sigs", "addr": "BDADF167E6CF2CDF2D621E590FF1FED2787A40E0" }, + "amount": { "denom": "mycoin", "amount": 900000 }, + "sequence": 1, + "multi": true, } +``` -Example tx: +Output (a json encoding of basecoin.Tx): -wrappers = combine(feeWrap, nonceWrap, chainWrap, sigWrap) +`basecli tx send --to=role:62616E6B32 --from=sigs:91C959ADE03D8973E8F2FBA9FD2EED327DCE2B0A --amount=900000mycoin --sequence=1 --multi --prepare=- --no-sign` -UI will have to know about feeWrap to pass info in ``` { @@ -58,7 +46,7 @@ UI will have to know about feeWrap to pass info in "tx": { "type": "nonce", "data": { - "sequence": 3, + "sequence": 1, "signers": [ { "chain": "", @@ -105,44 +93,97 @@ UI will have to know about feeWrap to pass info in } } }, - "signatures": [] + "signatures": null } } ``` -Matt's proposal: +## Sign a Tx -`POST /build/send` +Once you construct a proper json-encoded `basecoin.Tx`, you can sign it once, or (if you constructed it with `multi=true`), multiple times. + + +`POST /sign` Input: + ``` { - "fees": {"denom": "atom", "amount": 23}, - "to": {"app": "role", "addr": "62616E6B32" }, - "from": {"app": "sigs", "addr": "BDADF167E6CF2CDF2D621E590FF1FED2787A40E0" }, - "amount": { "denom": "mycoin", "amount": 900000 }, - "multi": true, + "name": "matt", + "password": "1234567890", + "tx": { + "type": "sigs/multi", + "data": { + "tx": // see output of /build/send, + "signatures": nil, + } + } } ``` -Output: the input for /sign +Output: -`POST /build/create-role` +`basecli tx send --to=role:62616E6B32 --from=sigs:91C959ADE03D8973E8F2FBA9FD2EED327DCE2B0A --amount=900000mycoin --sequence=1 --multi --no-sign --prepare=unsigned.json` + +`echo 1234567890 | basecli tx --in=unsigned.json --prepare=- --name=matt` -Input: ``` { - "name": "trduvtqicrtqvrqy", - "min_sigs": 2, - "members": [ - {"app": "sigs", "addr": "BDADF167E6CF2CDF2D621E590FF1FED2787A40E0" }, - {"app": "sigs", "addr": "91C959ADE03D8973E8F2FBA9FD2EED327DCE2B0A" } - ] + "type": "sigs/multi", + "data": { + "tx": // see output of /build/send, + "signatures": [ + { + "Sig": { + "type": "ed25519", + "data": "436188FAC4668DDF6729022454AFBA5DA0B44E516C4EC7013C6B00BD877F255CDE0355F3FBFE9CCF88C9F519C192D498BF087AFE0D531351813432A100857803" + }, + "Pubkey": { + "type": "ed25519", + "data": "B01508EB073C0823E2CE6ABF4538BA02EAEC39B02113290BBFCEC7E1B07F575A" + } + } + ] + } } ``` +## Send Tx to the Blockchain -## Query: +This will encode the transaction as binary and post it to the tendermint node, waiting until it is committed to the blockchain. +(TODO: make this async? return when recevied, notify when committed?) + +`POST /tx` + +Input: + +Signed tx as json, directly copy output of `/sign` + +Output: + + +`echo 1234567890 | basecli tx send --to=role:62616E6B32 --from=sigs:91C959ADE03D8973E8F2FBA9FD2EED327DCE2B0A --amount=900000mycoin --sequence=1 --multi --name=matt --prepare=signed.json` + +`basecli tx --in=signed.json --no-sign` + +``` +{ + "check_tx": { + "code": 0, + "data": "", + "log": "" + }, + "deliver_tx": { + "code": 0, + "data": "", + "log": "" + }, + "hash": "4D0EB7853E71AB6E3021990CF733F70F4CC2E001", + "height": 1494 +} +``` + +## Query account balance `GET /query/account/sigs:BDADF167E6CF2CDF2D621E590FF1FED2787A40E0` @@ -160,14 +201,15 @@ Input: } ``` +## Other stuff for MVP -## Other stuff +You must run `basecli init` int he cli to set things up. -`init` / `serve` on cli +When you run `basecli serve`, it will start the local rest api server, with the above endpoints. -keys management under `/keys`: +Also, support keys endpoints from go-crypto as they currently are and mount them under `/keys`. -List, get, create (delete + update)? +## Future Stuff proxy mounted as well under `/tendermint`