diff --git a/docs/rest/API_draft.md b/docs/rest/API_draft.md new file mode 100644 index 0000000000..0721c1a99d --- /dev/null +++ b/docs/rest/API_draft.md @@ -0,0 +1,249 @@ +# API + +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...) + +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. + +## MVP + +The MVP will allow us to move around money. This involves the +following functions: + +## Construct an unsigned tx + +`POST /build/send` + +Input: +``` +{ + "to": {"app": "role", "addr": "62616E6B32" }, + "from": {"app": "sigs", "addr": "BDADF167E6CF2CDF2D621E590FF1FED2787A40E0" }, + "amount": { "denom": "mycoin", "amount": 900000 }, + "sequence": 1, + "multi": true, +} +``` + +Output (a json encoding of basecoin.Tx): + +`basecli tx send --to=role:62616E6B32 --from=sigs:91C959ADE03D8973E8F2FBA9FD2EED327DCE2B0A --amount=900000mycoin --sequence=1 --multi --prepare=- --no-sign` + + +``` +{ + "type": "sigs/multi", + "data": { + "tx": { + "type": "chain/tx", + "data": { + "chain_id": "lakeshore", + "expires_at": 0, + "tx": { + "type": "nonce", + "data": { + "sequence": 1, + "signers": [ + { + "chain": "", + "app": "sigs", + "addr": "91C959ADE03D8973E8F2FBA9FD2EED327DCE2B0A" + } + ], + "tx": { + "type": "coin/send", + "data": { + "inputs": [ + { + "address": { + "chain": "", + "app": "role", + "addr": "62616E6B32" + }, + "coins": [ + { + "denom": "mycoin", + "amount": 900000 + } + ] + } + ], + "outputs": [ + { + "address": { + "chain": "", + "app": "sigs", + "addr": "BDADF167E6CF2CDF2D621E590FF1FED2787A40E0" + }, + "coins": [ + { + "denom": "mycoin", + "amount": 900000 + } + ] + } + ] + } + } + } + } + } + }, + "signatures": null + } +} +``` + +## Sign a Tx + +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: + +``` +{ + "name": "matt", + "password": "1234567890", + "tx": { + "type": "sigs/multi", + "data": { + "tx": // see output of /build/send, + "signatures": nil, + } + } +} +``` + +Output: + +`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` + +``` +{ + "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 + +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` + +``` +{ + "height": 1170, + "data": { + "coins": [ + { + "denom": "mycoin", + "amount": 12345 + } + ] + } +} +``` + +## Other stuff for MVP + +You must run `basecli init` int he cli to set things up. + +When you run `basecli serve`, it will start the local rest api server, with the above endpoints. + +Also, support keys endpoints from go-crypto as they currently are and mount them under `/keys`. + +## Future Stuff + +proxy mounted as well under `/tendermint` + +`/tendermint/status` +`/tendermint/block` + +info about self... + +`/` + +``` +{ + "app": "basecli", + "version": "0.7.1", // of client, server???? + "modules": { + "chain": "0.1.0", + "fees": "0.2.1", + "coin": "0.3.2", + "stake": "0.1.2" + }, + "nodes": [ + "localhost:46657", + "mercury.interchain.io:443" + ] +} +``` + +`/seeds` + +``` +{ + "last_height": 4555, + "update_problems": "too much change" +} +``` + +info on last seed