kilianmh/stacks-api: Stacks REST API Client in Common Lisp

Archived

Code Issues Pull requests Projects Releases Wiki Activity

Stacks REST API Client in Common Lisp

This repository has been archived on 2024年06月06日. You can view files and clone it, but you cannot make any changes to its state, such as pushing and creating new issues, pull requests or comments.

10 commits 1 branch 0 tags 77 KiB

Common Lisp 100%

Find a file

kilianmh 58e62ebd29 Remove check-standardized Use cl type system instead of customized assertion checking		2022年08月09日 23:25:30 +02:00
code	Remove check-standardized	2022年08月09日 23:25:30 +02:00
tests	Stacks API Version 0.2.0	2022年06月29日 23:55:31 +02:00
.gitignore	initial release version 0.1.0	2022年01月15日 00:40:16 +01:00
COPYING	initial release version 0.1.0	2022年01月15日 00:40:16 +01:00
README.org	fix: add ultralisp availability	2022年07月04日 20:54:55 +02:00
stacks-api.asd	Add mstrings readiness	2022年08月07日 23:45:46 +02:00

README.org

Common Lisp Stacks API Client (stacks-api)
- Documentation
- Main Features:
- Installation
- Usage
  - Naming
  - Types
  - Network
  - Output
- Example Queries
  - Accounts
  - Blocks
  - Faucets
  - Fees
  - Fungible Tokens
  - Info
  - Microblocks
  - Names
  - Non-Fungible Tokens
  - Search
  - Smart Contracts
  - Stacking Rewards
  - Transactions
- Not working
- Potential Future Ideas
- Call for collaboration
- Copyright
- License

Common Lisp Stacks API Client (stacks-api)

The main repository of this library is hosted on Codeberg. If you are viewing this anywhere else, it is just a mirror. Please use the Codeberg repository for collaboration. Thank you!

Documentation

This is a Common Lisp Client for the Stacks REST API, hosted by Hiro. The official Documentation can be found on here.

Main Features:

execute (almost) all GET requests and get-stx-testnet-tokens faucet.
network support: mainnet (default) and testnet
output types: hash-table (default), json, alist
static type checking & further input validation

https://raw.githubusercontent.com/hirosystems/stacks-blockchain-api/master/api-architecture.png

Installation

This library is now on Ultralisp (not yet on quicklisp). You can either set up Ultralisp or put it manually in the local-project folder (or any other folder visible to quicklisp) and then load it via:

 (ql:quickload :stacks-api)

Alternatively, you can load it with asdf:load-system. However then you need to manually make sure all dependencies are installed before.

Usage

Naming

Main package nickname is "stacks".

The API request-functions from the API references are transferred to names according to the Lisp Naming Guidelines: lowercase and separated by single dashes (-). The parameters are same as in the API reference: lower-case and with underscore. Only the array-parameter (type, tx_id, asset_identifiers) have a [] at the end: (tx_id[], type[] asset_identifiers[]).

Types

Inputs are statically type-checked at run time by default. Additional input validation is implemented for certain parameters. Array parameters need to be supplied as quoted list (see examples). All numbers are non-negative / positive integers. Boolean values are t or nil as usual in lisp.

Network

By default, functions query the mainnet (exemption: get-stx-testnet-tokens). You can change the network by setting the global variable *network/ast to "testnet" (or "mainnet").

 (setf *network* "testnet")

Output

Default output type is hash-table. Other options are alist, or (raw) json. The setting can be adjusted with the global variable *output/ast .

 (setf *output* :json)

Example Queries

 (in-package :stacks-api)

Accounts

 (get-account-balances "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info"
 :until_block "64500")

 (get-account-stx-balances "SP31DA6FTSJX2WGTZ69SFY11BH51NZMB0ZW97B5P0.get-info"
 :until_block "65000")

 (get-account-transactions "SP5C5J1AVSD63C0PEH965TGFDT1CQWFJY37DTZW5"
 :limit 10
 :offset 1
 :height 1000
 :unanchored nil)

 (get-account-transaction-information-for-specific-transaction
 "SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9.staking-helper"
 "0x0356c8a0662be5186652bcf70669471c65829400479caef769d5b2d0db871d31")

 (get-account-transactions-including-stx-transfers-for-each-transaction
 "SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9")

 (get-the-latest-nonce-used-by-an-account
 "SP3E1NPCV8QE4DXPC618VFW3ZFA8QPBD8HCS22KF2")

 (get-account-assets "SP1Z92MPDQEWZXW36VX71Q25HKF5K2EPCJ304F275")

 (get-inbound-stx-transfers "SP1Z92MPDQEWZXW36VX71Q25HKF5K2EPCJ304F275")

 (get-account-info "SP1TCA7QER9J9NKCKBB78K48TADDFC2GXYM3QQV3X")

 (get-mempool-transactions :recipient_address "SP5C5J1AVSD63C0PEH965TGFDT1CQWFJY37DTZW5")

Blocks

 (get-recent-blocks :offset 10)

 (get-block-by-hash "0x8c1100bc445873c53eeb5446946c97a70114c7fa8624aa7f8fd73cd3ebb51246")

 (get-block-by-height 1000)

 (get-block-by-burnchain-block-hash "0x0000000000000000000469320514f215cf176237696d0f8be97cad0a8de1b5d7")

 (get-block-by-burnchain-height 742673)

Faucets

 (get-stx-testnet-tokens :address "your-testnet-adddress")

Fees

 (get-estimated-fee)

Fungible Tokens

 (fungible-tokens-metadata-list)

 (fungible-tokens-metadata-for-contract-id "SP2C2YFP12AJZB4MABJBAJ55XECVS7E4PMMZ89YZR.usda-token")

Info

 (get-core-api-info)

 (api-status)

 (get-the-network-target-block-time)

 (get-a-given-network-target-block-time "mainnet")

 (get-total-and-unlocked-stx-supply :height 12000)

 (get-total-stx-supply-in-plain-text-format)

 (get-circulating-stx-supply-in-plain-text-format)

 (get-total-and-unlocked-stx-supply-legacy)

 (get-proof-of-transfer-details)

Microblocks

 (get-recent-microblocks)

 (get-microblock "0x72f05f5135caf2a17c8a993e7357072d7a91f1f74925543b12b93c22181b396d")

 (get-the-list-of-current-transactions-that-belong-to-unanchored-microblocks)

Names

 (get-namespace-price "app")

 (get-name-price "100.btc")

 (get-all-namespaces)

 (get-namespace-names "btc")

 (get-all-names)

 (get-name-details "100.btc")

 (get-zone-file "11street.btc")

 (get-names-owned-by-address "stacks" "SP3PW4MC0CZE0FY7MFTKGM7C2DCCXZ24SD0JWJTFT")

Non-Fungible Tokens

 (non-fungible-token-holdings
 :principal "SPNWZ5V2TPWGQGVDR6T7B6RQ4XMGZ4PXTEE0VQ0S.marketplace-v3"
 :asset_identifiers[] '("SPQZF23W7SEYBFG5JQ496NMY0G7379SRYEDREMSV.Candy::candy"))

 (non-fungible-token-history
 :asset_identifier "SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173.the-explorer-guild::The-Explorer-Guild"
 :value "0x0100000000000000000000000000000803")

 (non-fungible-token-mints
 :asset_identifier "SP2X0TZ59D5SZ8ACQ6YMCHHNR2ZN51Z32E2CJ173.the-explorer-guild::The-Explorer-Guild")

Search

 (search "0x589f73b5cb3f14ae96a9413dfc78fe2e59eff6bd4ddfe76746578884246dd63f")

Smart Contracts

 (get-contract-info "SP213KNHB5QD308TEESY1ZMX1BP8EZDPG4JWD0MEA.web4")

 (get-contract-events "SP000000000000000000002Q6VF78.genesis")

 (get-contract-interface "SP3K8BC0PPEVCV7NZ6QSRWPQ2JE9E5B6N3PA0KBR9" "collateral-rebalancing-pool-v1")

 (get-contract-source "SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9" "nft-trait"
 :proof 0)

Stacking Rewards

 (get-recent-reward-slot-holders)

 (get-recent-reward-slot-holder-entries-for-the-given-address "1BFfc2e6Kk82ut7S3C5yaN3pWRxEFRLLu5")

 (get-recent-burnchain-reward-recipients)

 (get-recent-burnchain-reward-for-the-given-recipient "1BFfc2e6Kk82ut7S3C5yaN3pWRxEFRLLu5")

 (get-total-burnchain-rewards-for-the-given-recipient "1BFfc2e6Kk82ut7S3C5yaN3pWRxEFRLLu5")

Transactions

 (get-recent-transactions
 :type[] '("coinbase" "contract_call"))

 (get-mempool-transactions)

 (get-dropped-mempool-transactions)

 (get-list-of-details-for-transactions
 :tx_id[] '("0xea052bfb2b80732f392e1a16be30be41d84b8bc1bdcf259f58f4b1b5339de452"
 "0x8506a60971a586dcfaf01d758e9ff34d3b2fcd4ffea655e3ca759cbe18a6e4db"))

 (get-transaction "0xeca4233a2ef466e3d311510f391f93d3e783cb050deea755fec5d3ffa1d8bf5c"
 :unanchored t
 :event_limit 5
 :event_offset 1)

 (get-raw-transaction "0xef7e5b73e6cc55140c5374ce21bc4454476ed0650676cc9c653740b7d2fb4c4a")

 (transactions-by-block-hash "0x589f73b5cb3f14ae96a9413dfc78fe2e59eff6bd4ddfe76746578884246dd63f")

 (transactions-by-block-height 1540
 :limit 10
 :offset 3
 :unanchored nil)

 (transactions-for-address "SP22PCWZ9EJMHV4PHVS0C8H3B3E4Q079ZHY6CXDS1")

Not working

REST GET:
- Non-Fungible Tokens metadata functions (non-fungible-tokens-metadata-list & non-fungible-tokens-metadata-for-contract-id) are not activated on public hiro node
POST requests:
- faucet: add-testnet-btc-tokens-to-address fees: get-approximate-fees-for-the-given-transaction
- rosetta: (only get-list-of-available-networks working)
- Smart Contracts: get-specific-data-map-inside-a-contract, call-read-only-function
- Transactions: broadcast-raw-transaction
Websocket: real-time updates for
- account-transactions
- recent blocks
- recent-microblocks
- mempool-transactions

Potential Future Ideas

JSON output validation
warn if there are no results
advanced input validation
query specific parts of contracts: (get-read-only-functions, get-maps, etc.)
more detailed analysis (and tracking?) for SIP 09 Non-fungible token and SIP 10 fungible tokens.
contract interaction (functions, variables, maps, token)
creating valid signed transactions
connect to a local API node
cross validation with local bitcoin node (https://github.com/rodentrabies/bp)

Call for collaboration

Feel free to contribute by opening issues, pull request, feature requests etc. Your help is much appreciated.

Copyright

License

Licensed under the AGPLv3 License.