plugin-usage

The following part contains both cURL requests and CLI commands to communicate with vault server. If you have used docker for vault setup, then use cURL requests.

Login as the application server#

Log-in into the vault as application server using the following command:

  $ vault login -method=userpass username=appserver password=secret

API call

  $ curl \    --request POST \    --data '{"password": "secret"}' \    http://127.0.0.1:8200/v1/auth/userpass/login/appserver

The command will return a token which will be used to keep the application server authenticated.

Plugin Usage#

Once we are logged in as an application server, we can use our API plugin to store mnemonic of HD wallet keys and also to sign raw transactions using those keys.

Register user#

Registers a user and stores the corresponding user's mnemonic in the vault. The request returns a unique id(UUID) of the user which will be later used to access the user's keys stored in the vault.

Method	Path	Produces
`POST`	`/api/register`	`200 (application/json)`

Parameters#

username (string) optional - Specifies the user-name of the user being registered.
mnemonic (string) optional - Specifies the mnemonic to be stored. If not provided, a random mnemonic will be generated and stored.
passphrase (string) optional - Specifies the passphrase.

CLI#

  $ vault write api/register username=user
  Key     Value  ---     -----  uuid    c3f394de-919d-4a66-a1b3-7686642be430

API call#

  $ cat payload.json  {    "username": "user",    "mnemonic": "",    "passphrase": ""  }
  $ curl \    --header "X-Vault-Token: ..." \    --request POST \    --data @payload.json \    http://127.0.0.1:8200/v1/api/register

info

The X-Vault-Token being passed in the header is the token received when the application server logged in. For API calls, the token has to be always passed in the header for authentication.

  Response:
  {    "request_id":"03cf1ec0-dbd3-9ce8-1663-067e91d680ab",    "lease_id":"",    "renewable":false,"lease_duration":0,    "data":{      "uuid":"9af93fcc-c41f-4c30-828f-c4b774573205"      },    "wrap_info":null,    "warnings":null,    "auth":null  }

Obtain user address and public key#

Once a user is registered, we can obtain the address and public key of that corresponding user.

Method	Path	Produces
`POST`	`/api/address`	`200 (application/json)`

Parameters#

uuid (string) required - Specifies the uuid of the user who will sign a transaction.
path (string) required - Specifies the HD-wallet path.
coinType (uint16) required - Specifies the coin-type Value of the coin to be used.

coinType#

  - Bitcoin:0  - Bitcoin Testnet:1  - Ethereum:60

CLI#

  $ vault write api/address uuid="214b8190-f9f5-4cf8-a4f1-3874ed5b05d0" path="m/44'/0'/0'/0/0" coinType=0
  Key          Value  ---          -----  address      1Ax1vX6dASU35gqyPDzX16np4rifvm8oF2  publicKey    030df204bde019cbbe79bec99aecfacd3c5f321f404d2df47b42573c987393df80  uuid         214b8190-f9f5-4cf8-a4f1-3874ed5b05d0

API call#

  $ cat payload.json  {    "uuid": "9af93fcc-c41f-4c30-828f-c4b774573205",    "path": "m/44'/0'/0'/0/0",    "coinType": 0  }
  $ curl \    --header "X-Vault-Token: ..." \    --request POST \    --data @payload.json \    http://127.0.0.1:8200/v1/api/address

  Response:
  {    "request_id": "a98b3299-9b03-e730-eae4-6a0f727816aa",    "lease_id": "",    "renewable": false,    "lease_duration": 0,    "data": {        "address": "1Ax1vX6dASU35gqyPDzX16np4rifvm8oF2",        "publicKey": "030df204bde019cbbe79bec99aecfacd3c5f321f404d2df47b42573c987393df80",        "uuid": "214b8190-f9f5-4cf8-a4f1-3874ed5b05d0"    },    "wrap_info": null,    "warnings": null,    "auth": null  }

Create signature#

Once a user is registered, we can now sign raw transactions just by using the user's UUID(which accesses the stored keys). As of now Bitcoin, Bitcoin Testnet and Ethereum transactions are supported.

Method	Path	Produces
`POST`	`/api/signature`	`200 (application/json)`

Parameters#

uuid (string) required - Specifies the uuid of the user who will sign a transaction.
path (string) required - Specifies the HD-wallet path.
coinType (uint16) required - Specifies the coin-type Value of the coin to be used.
payload (string) required - Contains the raw transaction to be signed in JSON format.

coinType#

  - Bitcoin:0  - Bitcoin Testnet:1  - Ethereum:60  - Bitshares:240

Payload#

Since payload contains the raw transaction, it's structure differs for Bitcoin and ethereum. For, Bitshares, however only the transaction digest is used to generate the signatures.

Bitcoin#

  {    inputs: [] of {txhash: string, vout: uint32}    outputs: [] of {address: string, amount: int 64}  }

txhash refers to the txid containing the UTXO and vout points to the index of that UTXO.
address refers to the payee address and amount refers to the amount of BTC you want to send.

Example payload:

  {    "inputs":[{        "txhash":"81b4c832d70cb56ff957589752eb412a4cab78a25a8fc52d6a09e5bd4404d48a",        "vout":0      },{          "txhash":"9dd5264b09bd4aebc1d74b776e6669ba3f0e381ef2992c9434e4d0bee3068edb",          "vout":0        }],
    "outputs":[{        "address":"1KKKK6N21XKo48zWKuQKXdvSsCf95ibHFa",        "amount":91234      },{          "address":"1HPvK7CAYeHzCdBMBkuXeEsXdvX64yMkoE",          "amount":91234        }]  }

Ethereum#

  {    Nonce : uint64    Value: uint64    GasLimit: uint64    GasPrice: uint64    To: string    Data: string    ChainID: int64  }

Example payload:

  {    "nonce":0,    "value":1000000000,    "gasLimit":21000,    "gasPrice":30000000000,    "to":"0x4592d8f8d7b001e72cb26a73e4fa1806a51ac79d",    "data":"",    "chainId":1  }

The request finally returns a signature of a raw transaction which was signed inside vault using the following things:

uuid of the user proposing the transaction.
Stored mnemonic corresponding to the provided uuid.
HD wallet path.

Bitshares#

  {    transactionDigest : string  }

Example payload:

  {    "transactionDigest":"3aef3997194701308d57a65214a7a015d98382ab66a9bc0d655de80842b6bfc5aede09dd6e161ca9095c0105d1d8070000000000001111050007616e6b69743131010000000001021500e918e7ca8c63e40472c9a2ab28665d06a41e78d034ee1b2ff2b3635d02e5010000010000000001021500e918e7ca8c63e40472c9a2ab28665d06a41e78d034ee1b2ff2b3635d02e5010000021500e918e7ca8c63e40472c9a2ab28665d06a41e78d034ee1b2ff2b3635d02e5050000000000000000"  }

The request finally returns a signature of a raw transaction which was signed inside vault using the following things:

CLI#

BTC:

  $ vault write api/signature uuid="c3f394de-919d-4a66-a1b3-7686642be430" \    path="m/0/0" \    payload="{\"inputs\":[{\"txhash\":\"b31695ff693b196d41600266d82bdf1092a4a55be608f41e1bde985408b16774\",\"vout\":0}],\"outputs\":[{\"address\":\"3BGgKxAsqoFyouTgUJGW3TAJdvYrk43Jr5\",\"amount\":91234}]}" \    coinType=0
  Key          Value  ---          -----  signature    01000000017467b1085498de1b1ef408e65ba5a49210df2bd8660260416d193b69ff9516b3000000006a47304402200cd2c06db98cb1a71cbb7558506815d20933e4451ffda2760971b5e477c7766902206dc6aa33f3c05305a992fcf3f19d58953b55398f8052a0ae1f061ad8b38b3135012103e1a150d41f5d6871da8310e5ea8226f105716639483e3e2c79981d65392ce499ffffffff01626401000000000017a9146916ea9f8135de454ecb1c22ade111ff48fb7c9f8700000000

BTC testnet:

  $ vault write api/signature uuid="c3f394de-919d-4a66-a1b3-7686642be430" \    path="m/0/0" \    payload="{\"inputs\":[{\"txhash\":\"b31695ff693b196d41600266d82bdf1092a4a55be608f41e1bde985408b16774\",\"vout\":0}],\"outputs\":[{\"address\":\"3BGgKxAsqoFyouTgUJGW3TAJdvYrk43Jr5\",\"amount\":91234}]}" \    coinType=1
  Key          Value  ---          -----  signature    01000000017467b1085498de1b1ef408e65ba5a49210df2bd8660260416d193b69ff9516b3000000006b483045022100d3323c41f117c4c1ef3e52fde37bc01b24fc6090de8dbeb6918a494bfea21ef602206ee496d9933eb5a9246808b96cbad4c8b84b9b5ad7a66afe045acc72f033e2d6012103c023b44933371f7d208bc0ff8a65505d67bf8750de913d21af8d194585ac7af0ffffffff01626401000000000017a9146916ea9f8135de454ecb1c22ade111ff48fb7c9f8700000000

ETH:

  $ vault write api/signature uuid="c3f394de-919d-4a66-a1b3-7686642be430" \  path="m/0/0" \  payload="{\"nonce\":0,\"value\":1000000000,\"gasLimit\":21000,\"gasPrice\":30000000000,\"to\":\"0x4592d8f8d7b001e72cb26a73e4fa1806a51ac79d\",\"data\":\"\",\"chainId\":1}" \  coinType=60
  Key          Value  ---          -----  signature    0xf868808506fc23ac00825208944592d8f8d7b001e72cb26a73e4fa1806a51ac79d843b9aca008026a08a465e9d1c707d02f72360ab21d1a1be5faf84671413e7df0402e954a666cd79a04ab6481295d13f31fc4265888e8bd9962e200062889f162b320caf4c697f96c4

BTS:

  $ vault write api/signature uuid="bgnkf4dgouhsb9enplqg" \  path="" \  payload="{\"transactionDigest\":\"3aef3997194701308d57a65214a7a015d98382ab66a9bc0d655de80842b6bfc5aede09dd6e161ca9095c0105d1d8070000000000001111050007616e6b69743131010000000001021500e918e7ca8c63e40472c9a2ab28665d06a41e78d034ee1b2ff2b3635d02e5010000010000000001021500e918e7ca8c63e40472c9a2ab28665d06a41e78d034ee1b2ff2b3635d02e5010000021500e918e7ca8c63e40472c9a2ab28665d06a41e78d034ee1b2ff2b3635d02e5050000000000000000\"}" \  coinType=240
  Key          Value  ---          -----  signature    1f2e6532af53fa5703780c31b94ff99ba375a8f131e9137c53d42e5512ab86ba80180ba87cfc519aba5ec80c00070fa1bf32c47cf4b594766c651fdacdeb59e18b

API call#

BTC:

  $ cat payload.json  {    "uuid": "9af93fcc-c41f-4c30-828f-c4b774573205",    "path": "m/0/0",    "payload": "{\"inputs\":[{\"txhash\":\"b31695ff693b196d41600266d82bdf1092a4a55be608f41e1bde985408b16774\",\"vout\":0}],\"outputs\":[{\"address\":\"3BGgKxAsqoFyouTgUJGW3TAJdvYrk43Jr5\",\"amount\":91234}]}",    "coinType": 0  }
  $ curl \    --header "X-Vault-Token: ..." \    --request POST \    --data @payload.json \    http://127.0.0.1:8200/v1/api/signature

  Response:
  {    "request_id":"c9f6916d-5985-6320-770b-cc3fb22b0b37",    "lease_id":"",    "renewable":false,    "lease_duration":0,    "data":{      "signature":"01000000017467b1085498de1b1ef408e65ba5a49210df2bd8660260416d193b69ff9516b3000000006a47304402204355e8a9cd9f2e4cac867c8ab55a63f020404249051385f4170788b35d246d9602201b2ff4bbc7a9dd9eb5ebbfcffeed3de0a9138ca1606d302b407d3e99c092ac1e0121027276b9edee40a02957f237d79536205524c3864d0d351909cdf519adc60de6d4ffffffff01626401000000000017a9146916ea9f8135de454ecb1c22ade111ff48fb7c9f8700000000"      },    "wrap_info":null,    "warnings":null,    "auth":null  }

BTC Testnet:

  $ cat payload.json  {    "uuid": "9af93fcc-c41f-4c30-828f-c4b774573205",    "path": "m/0/0",    "payload": "{\"inputs\":[{\"txhash\":\"b31695ff693b196d41600266d82bdf1092a4a55be608f41e1bde985408b16774\",\"vout\":0}],\"outputs\":[{\"address\":\"3BGgKxAsqoFyouTgUJGW3TAJdvYrk43Jr5\",\"amount\":91234}]}",    "coinType": 1  }
  $ curl \    --header "X-Vault-Token: ..." \    --request POST \    --data @payload.json \    http://127.0.0.1:8200/v1/api/signature

  Response:
  {    "request_id":"c9f6916d-5985-6320-770b-cc3fb22b0b37",    "lease_id":"",    "renewable":false,    "lease_duration":0,    "data":{      "signature":"01000000017467b1085498de1b1ef408e65ba5a49210df2bd8660260416d193b69ff9516b3000000006b483045022100d3323c41f117c4c1ef3e52fde37bc01b24fc6090de8dbeb6918a494bfea21ef602206ee496d9933eb5a9246808b96cbad4c8b84b9b5ad7a66afe045acc72f033e2d6012103c023b44933371f7d208bc0ff8a65505d67bf8750de913d21af8d194585ac7af0ffffffff01626401000000000017a9146916ea9f8135de454ecb1c22ade111ff48fb7c9f8700000000"      },    "wrap_info":null,    "warnings":null,    "auth":null  }

ETH:

  $ cat payload.json  {    "uuid": "9af93fcc-c41f-4c30-828f-c4b774573205",    "path": "m/0/0",    "payload": "{\"nonce\":0,\"value\":1000000000,\"gasLimit\":21000,\"gasPrice\":30000000000,\"to\":\"0x4592d8f8d7b001e72cb26a73e4fa1806a51ac79d\",\"data\":\"\",\"chainId\":1}",    "coinType": 60  }
  $ curl \    --header "X-Vault-Token: ..." \    --request POST \    --data @payload.json \    http://127.0.0.1:8200/v1/api/signature

  Response:
  {    "request_id":"c9f6916d-5985-6320-770b-cc3fb22b0b37",    "lease_id":"",    "renewable":false,    "lease_duration":0,    "data":{      "signature":"0xf868808506fc23ac00825208944592d8f8d7b001e72cb26a73e4fa1806a51ac79d843b9aca008026a08a465e9d1c707d02f72360ab21d1a1be5faf84671413e7df0402e954a666cd79a04ab6481295d13f31fc4265888e8bd9962e200062889f162b320caf4c697f96c4"      },    "wrap_info":null,    "warnings":null,    "auth":null  }

BTS:

  $ cat payload.json  {    "uuid": "bgnkf4dgouhsb9enplqg,    "path": "",    "payload": "{\"transactionDigest\":\"3aef3997194701308d57a65214a7a015d98382ab66a9bc0d655de80842b6bfc5aede09dd6e161ca9095c0105d1d8070000000000001111050007616e6b69743131010000000001021500e918e7ca8c63e40472c9a2ab28665d06a41e78d034ee1b2ff2b3635d02e5010000010000000001021500e918e7ca8c63e40472c9a2ab28665d06a41e78d034ee1b2ff2b3635d02e5010000021500e918e7ca8c63e40472c9a2ab28665d06a41e78d034ee1b2ff2b3635d02e5050000000000000000\"}",    "coinType": 240  }
  $ curl \    --header "X-Vault-Token: ..." \    --request POST \    --data @payload.json \    http://127.0.0.1:8200/v1/api/signature

  Response:
 {    "request_id": "ee20193d-48bd-1f97-e407-a9f376075cb3",    "lease_id": "",    "renewable": false,    "lease_duration": 0,    "data": {        "signature": "1f2e6532af53fa5703780c31b94ff99ba375a8f131e9137c53d42e5512ab86ba80180ba87cfc519aba5ec80c00070fa1bf32c47cf4b594766c651fdacdeb59e18b"    },    "wrap_info": null,    "warnings": null,    "auth": null}

cURL requests for all of the above commands can be imported to postman via vault_postman_collection.json.

Note: If using postman, replace the existing token with yours in the header section of each request.