mirror of https://github.com/lukechilds/docs.git
Alexander Graebe
4 years ago
5 changed files with 197 additions and 20 deletions
@ -0,0 +1,10 @@ |
|||||
|
### Pagination |
||||
|
|
||||
|
To make API responses more compact, lists returned by the API are paginated. For lists, the response body includes: |
||||
|
|
||||
|
- `limit`: the number of list items return per response (max is `200`) |
||||
|
- `offset`: the number of elements to skip (starting from `0`) |
||||
|
- `total`: the number of all available list items |
||||
|
- `results`: the array of list items (length of array is between 0 and the set limit) |
||||
|
|
||||
|
Using the `limit` and `offset` properties, you can paginate through the entire list by increasing the offset by the limit until you reach the end of the list (as indicated by the `total` field). |
||||
@ -1,6 +1,143 @@ |
|||||
--- |
--- |
||||
title: Account management |
title: Accounts |
||||
description: Guide to Stacks 2.0 account management |
description: Guide to Stacks 2.0 accounts |
||||
--- |
--- |
||||
|
|
||||
## Introduction |
## Introduction |
||||
|
|
||||
|
Stacks 2.0 accounts are entities that own assets, like Stacks tokens. An account has an address, private key, nonce, and one or more asset balances. |
||||
|
|
||||
|
-> The public-key signature system used for Stacks 2.0 accounts is [Ed25519](https://ed25519.cr.yp.to/). |
||||
|
|
||||
|
## Creation |
||||
|
|
||||
|
When an account is created, a 24-phrase mnemonic is generated. This is often referred to as the **seed phrase**. The seed phrase provides access to Stacks 2.0 accounts. |
||||
|
|
||||
|
!> If the seed phrase is lost, access to the associated account cannot be restored. No person or organization, including Blockstack, can recover a lost seed phrase. |
||||
|
|
||||
|
The easiest way to generate a new Stacks 2.0 account is to use the [Stacks 2.0 CLI](https://github.com/blockstack/cli-blockstack/tree/feature/stacks-2.0-tx): |
||||
|
|
||||
|
```shell |
||||
|
# install CLI globally |
||||
|
sudo npm install -g "https://github.com/blockstack/cli-blockstack#feature/stacks-2.0-tx" |
||||
|
|
||||
|
# generate a new account and store details in a new file |
||||
|
# '-t' option makes this a testnet account |
||||
|
blockstack make_keychain -t > cli_keychain.json |
||||
|
``` |
||||
|
|
||||
|
The `make_keychain` command will create following file: |
||||
|
|
||||
|
```js |
||||
|
{ |
||||
|
"mnemonic": "aaa bbb ccc ddd ...", |
||||
|
"keyInfo": { |
||||
|
"address": "STJRM2AMVF90ER6G3RW1QTF85E3HZH37006D5ER1", |
||||
|
"privateKey": "5a3f1f15245bb3fb...", |
||||
|
"index": 0, |
||||
|
"btcAddress": "biwSd6KTEvJcyX2R8oyfgj5REuLzczMYC1" |
||||
|
} |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
| Field | Description | |
||||
|
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | |
||||
|
| `mnemonic` | A 24-word seed phrase used to access the account, generated using [BIP39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) with 256 bits of entropy | |
||||
|
| `keyInfo.address` | Stacks address for the account | |
||||
|
| `keyInfo.privateKey` | Private key for the account. Required for [token transfers](/stacks-blockchain/transactions#stacks-token-transfer) and often referred to as `senderKey` | |
||||
|
| `keyInfo.index` | Nonce for the account, starting at 0 | |
||||
|
| `keyInfo.btcAddress` | Corresponding BTC address for the account | |
||||
|
|
||||
|
Note that the new account is instantiated implicitly. There is no need to manually instantiate it on the Stacks 2.0 blockchain. |
||||
|
|
||||
|
-> Addresses are generated by hashing the public key and encoding it with [Base58Check](https://en.bitcoin.it/wiki/Base58Check_encoding) |
||||
|
|
||||
|
## Querying |
||||
|
|
||||
|
### Get STX balance and nonce |
||||
|
|
||||
|
STX balance and nonce can be obtained through the [`GET /v2/accounts/<stx_address>`](https://blockstack.github.io/stacks-blockchain-api/#operation/get_account_info) endpoint: |
||||
|
|
||||
|
```shell |
||||
|
curl 'https://stacks-node-api-latest.argon.blockstack.xyz/v2/accounts/<stx_address>' |
||||
|
``` |
||||
|
|
||||
|
Sample response: |
||||
|
|
||||
|
```js |
||||
|
{ |
||||
|
"balance": "0x0000000000000000002386f26f3f40ec", |
||||
|
"nonce": 17 |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
-> The balance string represents an unsigned 128-bit integer (big-endian) in hex encoding |
||||
|
|
||||
|
### Get all token balances |
||||
|
|
||||
|
All token balances can be obtained through the [`GET /extended/v1/address/<stx_address>/balances`](https://blockstack.github.io/stacks-blockchain-api/#operation/get_account_balance) endpoint: |
||||
|
|
||||
|
```shell |
||||
|
curl 'https://stacks-node-api-latest.argon.blockstack.xyz/extended/v1/address/<stx_address>/balances' |
||||
|
``` |
||||
|
|
||||
|
Sample response: |
||||
|
|
||||
|
```js |
||||
|
{ |
||||
|
"stx": { |
||||
|
"balance": "0", |
||||
|
"total_sent": "0", |
||||
|
"total_received": "0" |
||||
|
}, |
||||
|
"fungible_tokens": {}, |
||||
|
"non_fungible_tokens": {} |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
### Get all asset events |
||||
|
|
||||
|
All asset events associated with the account can be obtained through the [`GET /extended/v1/address/<stx_address>/assets`](https://blockstack.github.io/stacks-blockchain-api/#operation/get_account_balance) endpoint: |
||||
|
|
||||
|
```shell |
||||
|
curl 'https://stacks-node-api-latest.argon.blockstack.xyz/extended/v1/address/<stx_address>/assets' |
||||
|
``` |
||||
|
|
||||
|
Sample response: |
||||
|
|
||||
|
```js |
||||
|
{ |
||||
|
"limit": 20, |
||||
|
"offset": 0, |
||||
|
"total": 0, |
||||
|
"results": [ |
||||
|
{ |
||||
|
"event_index": 5, |
||||
|
"event_type": "non_fungible_token_asset", |
||||
|
"asset": { |
||||
|
"asset_event_type": "transfer", |
||||
|
"asset_id": "ST2W14YX9SFVDB1ZGHSH40CX1YQAP9XKRAYSSVYAG.hello_world::hello-nft", |
||||
|
"sender": "SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR", |
||||
|
"recipient": "SM2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQVX8X0G", |
||||
|
"value": { |
||||
|
"hex": "0x0100000000000000000000000000000001", |
||||
|
"repr": "u1" |
||||
|
} |
||||
|
} |
||||
|
}, |
||||
|
{ |
||||
|
"event_index": 3, |
||||
|
"event_type": "fungible_token_asset", |
||||
|
"asset": { |
||||
|
"asset_event_type": "mint", |
||||
|
"asset_id": "ST2W14YX9SFVDB1ZGHSH40CX1YQAP9XKRAYSSVYAG.hello_world::novel-token-19", |
||||
|
"sender": "", |
||||
|
"recipient": "SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR", |
||||
|
"amount": "12" |
||||
|
} |
||||
|
} |
||||
|
] |
||||
|
} |
||||
|
``` |
||||
|
|
||||
|
-> Read more about [pagination](/stacks-blockchain/transactions#pagination) to iterate through the entire result set of the asset events |
||||
|
|||||
Loading…
Reference in new issue