hirosystems / docs Goto Github PK
View Code? Open in Web Editor NEWHiro developer documentation website
Home Page: https://docs.hiro.so/
Hiro developer documentation website
Home Page: https://docs.hiro.so/
On page Stacking Using the Stacks CLI
guide, there is a link back to the Stacking Integration Guide
, which points back to the stacks.co
domain.
This link is broken: https://docs.stacks.co/build-apps/guides/integrate-stacking
SIP-013 Semi-Fungible Token standard is now in the Accepted status, and there are contracts already using the standard on mainnet.
Examples:
semi-fungible trait: https://explorer.stacks.co/txid/0x74db763fbaa66da3368e642ddac48dc5ac81f3c6e5a9b1aaf358c5745608fdde?chain=mainnet
yield-alex-v1: https://explorer.stacks.co/txid/0x960dda517da8f9a71d8bf7736fc09bddfa5a7035f148387cd737eab73dcc62a6?chain=mainnet
key-alex-autoalex-v1: https://explorer.stacks.co/txid/0x81dfeb1dc081781e8fe6859ebfc6c4ce68b61b2d329b294f44649115dab3ac59?chain=mainnet
ytp-alex-v1: https://explorer.stacks.co/txid/0xc0283d14f4541b9c2844839fda971547c7318ec924115ce44be9109bb85bb9a7?chain=mainnet
Based on the above, it will be great to see Hiro wallet supporting SIP-013 standard.
Note from @BowTiedDeployer:
for every api have a specific example explained
- this is the contract
- this way it is called specifically on it
this gets a better learning curve for using a given api for the first time, after using it once it is enough the theory because you already know an example where you applied it
The Discord link in the footer of the site goes to the Docusaurus Discord, not the Stacks Discord. Fix the URL.
Update the POST URL with the latest from Open API for Testnet. (https://stacks-node-api.testnet.stacks.co)
Old URL:
Related to #84
We should enable the timestamp and author indicating when and who updated a page. It seems to be a simple configuration:
any of the links to docs for stacks.js
are 404ing, i.e. https://blockstack.github.io/stacks.js/modules/transactions.html
As discussed in #90, we want to cleanly switch to Google Tag Manager and rely on it going forward and not rely on Segment's backdoor integration with Google Measurement Protocol API.
Our docs currently use Fathom for analytics. We decided to move to Google Analytics. As part of that we need to replace the tracking code.
Once we get closer to work on this issue, we can create the project ID that should be used for tracking. The GA property needs to be configurated appropriately and all stakeholders should be invited.
Google is forcing a transition to Analytics 4 in July 2023. Marketing would like to start our transition now so we have a good body of year over year data in GA4 before the GA3 cutoff arrives.
Segment has rudimentary support for GA4, but it does not support all the native GA4 features at this time.
The GA4 tracking script can sit alongside Segment so that any systems that draw from the Segment data will still have docs pageview data.
The GA4 script is as follows and should be placed in the <head> of each page on the site:
<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-NB2VBT0KY2"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'G-NB2VBT0KY2');
</script>```
We received feedback that a developer wanted to print/log via Clarity but didn't understand if/how it is possible. We could add a small example to one of our Clarinet tutorials that points out to Clarity can be used to log something and how it can be reviewed using Clarinet and/or the API
surfaced in this conversation: leather-io/extension#1700 (comment)
Looks like a custom Docker image needs to be specific in the toml file
Recently, many Hiro products were moved from the blockstack
organization to the hirosystems
organization in GitHub. Although this move should be mostly transparent, we should make sure that we're not relying on GitHub's internal redirects. Ensure that any links in the documentation point at the correct repository.
Note from @BowTiedDeployer:
clicking or double-clicking should copy the API endpoints (one click already gets all the text, but doing this makes the user feel that it is copied on the clip board and it is not)
The registry sample app needs to be updated:
Flowcharts are a better approach to unpack complex scenarios, especially with conditions. That conditionality is always the case when it comes to troubleshooting and debugging.
Mermaid is a tool that is commonly adopted to describe the guide in a markdown format, and it then translates it to visual charts. Mermaid recently also made it into GitHub proper! However, the Docusaurus support is prioritized and still pending.
As a continuation of #86, anything that pertains to troubleshooting can choose this format to explain the steps more visually to readers (i.e., developers).
Here's an example that uses Mermaid to describe the troubleshooting procedure.
The code snippets embedded in the docs would have to evolve as we tweak the app.
Finally, we must find a way to wrap test harnesses and run those through CI for continuous functionality checks.
Relates to #57.
docs/docs/tutorials/clarity-nft.md
Line 131 in e2ee981
Few versions ago address of deployer wallet has been changed in Clarinet.
The new one is: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM
With Clarinet, stacks.js, and others, we duplicate the install steps in docs instead of maintaining those steps centrally in GitHub READMEs. I couldn't find a way to do that with Docusaurus. There are a few workarounds, including creating a file with .mdx
and references to the README file, but that may not be as dynamic.
It'd be helpful to explore a way to maintain the source of truth centrally in a single location.
https://docs.hiro.so/example-apps/public-registry#waiting-for-transactions
seems like the callback / interface is out of sync with code:
export interface RegularOptionsBase extends TxBase, OptionsBase {
sponsored?: false;
onFinish?: Finished;
onCancel?: Canceled;
}
Just like we did in the Stacks docs, we should add a URL checker and fix broken links. Steps:
Install markdown-link-check:
yarn add markdown-link-check
Add link checker config file mlc_config.json
:
{
"ignorePatterns": [
{
"pattern": "^http://localhost"
},
{
"pattern": "^https://banter.pub"
},
{
"pattern": "^/img"
}
],
"replacementPatterns": [
{
"pattern": "^/",
"replacement": "https://docs.hiro.so/"
}
],
"timeout": "10s",
"retryOn429": true,
"retryCount": 5
}
Add a script to package.json
:
"urlcheck": "find . -type f -name '*.md' ! -path './node_modules/*' ! -path './_site/*' | xargs -L1 npx markdown-link-check -q -c mlc_config.json",
Let's review the README and polish the instructions so it is helps onboard and use the templates.
The link from the desktop wallet page with the Ledger instructions is broken. Looks like the correct link should be https://www.hiro.so/wallet-faq/how-can-i-use-my-ledger-device-with-stacks-wallet
The Hiro's hosted API instance (docs here) are governed by Cloudflare's rate limiting rules to protect the hosted APIs from malicious traffic. As developers continue to use the APIs, they would like to understand the predefined limiting rules for the published endpoints.
More details in Notion here.
Several developers have complained that the Stacks API returns Clarity values that must be deserialized before they can be used in Javascript frontends. Although Stacks.js does provide the necessary tools for performing this conversion, the details are not well-documented. The documentation should include:
the docs for billboard app
https://docs.hiro.so/example-apps/billboard#updating-the-billboard-value
refer to using a shell script
you can use the update-message.sh script in the root
but in fact it's a js
script
https://github.com/pgray-hiro/stacks-billboard/blob/main/update-message.js
also might be good to link to it directly (tho it might move :( )
Marketing would like to add a link to the Docs site to our newsletter signup. The destination URL is:
https://hiro.so/updates-docs
Edit: Swapped in much shorter URL.
Only 25% of visitors end up visiting a tutorial. We suspect it is difficult to discover them. We should build out a nicely designed overview page down the road but as a low hanging fruit, we can add a list of available tutorials to this page:
This issue surfaces the lack of guidance around the usage of post conditions. So far, we documented only the concept in the Stacks documentation: https://docs.stacks.co/understand-stacks/transactions#post-conditions
Note: While this is a gap in our docs, it should be carefully reviewed what priority this should be assigned
The links to the RPC API documentation at the bottom of https://docs.stacks.co/understand-stacks/stacks-blockchain-api need to be updated to the hirosystems URLs. They currently point to the blockstack.github.io URLs and now get 404 errors.
From @BowTiedDeployer:
it'd be useful to have the commands for deploying a smart contract after the blockchain is running with
clarinet integrate
Some of the apps have dated screenshots (eg: TODO) and the "heystack" application doesn't work anymore. Either the dependencies aren't entirely in good shape or the integration of those apps with later versions of APIs or stacks.js modules require updates.
This an extension to #78; just splitting them, so we can address them independently.
https://docs.hiro.so/tutorials/clarity-nft
In the my-nft.clar contract, there is a parenthesis missing at the end of the transfer-memo
function. If developers copy/paste that code, it won't build successfully.
We'll need to update the authentication guide to point developers instead to the new functionality for requesting accounts rather than authenticating users per se.
I tried the NFT tutorial and copy pasting the code from the tutorial does not include line breaks on my machine.
I am using linux and firefox.
A critical area of app development is the integration of a smart contract with the frontend web application. Currently, our documentation provides an overview of how to develop and test Clarity smart contracts, but lacks information on how to integrate them into a frontend.
Add an integration guide to the developer documentation. A proposed outline is located in this Google doc.
Eg: https://docs.hiro.so/smart-contracts/clarinet
Define the acronyms for the first time in a document.
REPL - > Read, Evaluate Print, Loop.
VS code -> Visual Studio Code.
STX - Stacks etc.
Description:
Add placeholders where ever user need to update his values received by running commands.
Eg: Balance, btcaddress, stx address etc.
Add a note for each command to where user can get the values like stx-address, btc-address from.
Eg: Get from #Get balance command.
Output need to stay outside of the bash command tags.
Example:
Output:
{eligible : true}
Once we have confirmed that Segment analytics is working for the Hiro documentation site, remove the Fathom analytics plugin and configuration from the site so we are not double-tracking.
The API Websockets example in https://github.com/hirosystems/docs/blob/main/docs/get-started/stacks-blockchain-api.md is out of date when compared to the API client docs. We should update it to reflect a more recent example.
Also, the example can be confusing because it's given in the context of Typescript when it's written in JavaScript. We should make clear it's in JS or rewrite it to compile in Typescript.
so these seem the wrong way around to me
/nft_events
APIGet list of all nfts owned by an address, contains the clarity value of the identifier of the nft
maybe it's just the naming of the end points, the docs also contradict the api endpoint
/assets
gives a list of all transactions like this:https://docs.hiro.so/api#operation/get_account_assets
shows all the NFT events
INFO tools.stacks response {
INFO tools.stacks "limit": 20,
INFO tools.stacks "offset": 0,
INFO tools.stacks "total": 5,
INFO tools.stacks "results": [
INFO tools.stacks {
INFO tools.stacks "event_index": 0,
INFO tools.stacks "event_type": "non_fungible_token_asset",
INFO tools.stacks "tx_id": "0x7d9656d9b4da543544d02db59b97f9261aa91e5c8f00481cf9373817cfead017",
INFO tools.stacks "asset": {
INFO tools.stacks "asset_event_type": "transfer",
INFO tools.stacks "asset_id": "SP1CSHTKVHMMQJ7PRQRFYW6SB4QAW6SR3XY2F81PA.stxplates::PLATES",
INFO tools.stacks "sender": "SP5JMWT45ZF0RHJZSR4XPAEW8MS7J3DFQS5FAJ0X",
INFO tools.stacks "recipient": "SPNWZ5V2TPWGQGVDR6T7B6RQ4XMGZ4PXTEE0VQ0S.marketplace-v4",
INFO tools.stacks "value": {
INFO tools.stacks "hex": "0x01000000000000000000000000000000ab",
INFO tools.stacks "repr": "u171"
INFO tools.stacks }
INFO tools.stacks }
INFO tools.stacks },
INFO tools.stacks {
INFO tools.stacks "event_index": 0,
INFO tools.stacks "event_type": "non_fungible_token_asset",
INFO tools.stacks "tx_id": "0x5133847ac6ddfa724b69d31a7c1b11098b75d183948058dcb0ec2d1caaa5a274",
INFO tools.stacks "asset": {
INFO tools.stacks "asset_event_type": "transfer",
INFO tools.stacks "asset_id": "SP1CSHTKVHMMQJ7PRQRFYW6SB4QAW6SR3XY2F81PA.stxplates::PLATES",
INFO tools.stacks "sender": "SP1JT14AAXH7N3TYRX118GB7ZPMH4Q341TS0HM0VB",
INFO tools.stacks "recipient": "SP5JMWT45ZF0RHJZSR4XPAEW8MS7J3DFQS5FAJ0X",
INFO tools.stacks "value": {
INFO tools.stacks "hex": "0x01000000000000000000000000000000ab",
INFO tools.stacks "repr": "u171"
INFO tools.stacks }
INFO tools.stacks }
INFO tools.stacks },
INFO tools.stacks {
INFO tools.stacks "event_index": 1,
INFO tools.stacks "event_type": "non_fungible_token_asset",
INFO tools.stacks "tx_id": "0x3e09b4672aae0dfb150e4383fec05493613f4e7c232ff17d1b247431bdda2c78",
INFO tools.stacks "asset": {
INFO tools.stacks "asset_event_type": "mint",
INFO tools.stacks "asset_id": "SP1CSHTKVHMMQJ7PRQRFYW6SB4QAW6SR3XY2F81PA.stxplates::PLATES",
INFO tools.stacks "sender": "",
INFO tools.stacks "recipient": "SP5JMWT45ZF0RHJZSR4XPAEW8MS7J3DFQS5FAJ0X",
INFO tools.stacks "value": {
INFO tools.stacks "hex": "0x01000000000000000000000000000000ad",
INFO tools.stacks "repr": "u173"
INFO tools.stacks }
INFO tools.stacks }
INFO tools.stacks },
INFO tools.stacks {
INFO tools.stacks "event_index": 0,
INFO tools.stacks "event_type": "stx_asset",
INFO tools.stacks "tx_id": "0x3e09b4672aae0dfb150e4383fec05493613f4e7c232ff17d1b247431bdda2c78",
INFO tools.stacks "asset": {
INFO tools.stacks "asset_event_type": "transfer",
INFO tools.stacks "sender": "SP5JMWT45ZF0RHJZSR4XPAEW8MS7J3DFQS5FAJ0X",
INFO tools.stacks "recipient": "SP1CSHTKVHMMQJ7PRQRFYW6SB4QAW6SR3XY2F81PA.stxplates",
INFO tools.stacks "amount": "1000000"
INFO tools.stacks }
INFO tools.stacks },
INFO tools.stacks {
INFO tools.stacks "event_index": 0,
INFO tools.stacks "event_type": "stx_asset",
INFO tools.stacks "tx_id": "0x3d863b088d87842730526314dbb25b314f732289d43e6ec3ec1056ce2eb0d942",
INFO tools.stacks "asset": {
INFO tools.stacks "asset_event_type": "transfer",
INFO tools.stacks "sender": "SP1JT14AAXH7N3TYRX118GB7ZPMH4Q341TS0HM0VB",
INFO tools.stacks "recipient": "SP5JMWT45ZF0RHJZSR4XPAEW8MS7J3DFQS5FAJ0X",
INFO tools.stacks "amount": "100000000"
INFO tools.stacks }
INFO tools.stacks }
INFO tools.stacks ]
INFO tools.stacks } +0ms
shows the single asset I hold:
INFO tools.stacks response {
INFO tools.stacks "nft_events": [
INFO tools.stacks {
INFO tools.stacks "sender": null,
INFO tools.stacks "recipient": "SP5JMWT45ZF0RHJZSR4XPAEW8MS7J3DFQS5FAJ0X",
INFO tools.stacks "asset_identifier": "SP1CSHTKVHMMQJ7PRQRFYW6SB4QAW6SR3XY2F81PA.stxplates::PLATES",
INFO tools.stacks "value": {
INFO tools.stacks "hex": "0x01000000000000000000000000000000ad",
INFO tools.stacks "repr": "u173"
INFO tools.stacks },
INFO tools.stacks "tx_id": "0x3e09b4672aae0dfb150e4383fec05493613f4e7c232ff17d1b247431bdda2c78",
INFO tools.stacks "block_height": 38694
INFO tools.stacks }
INFO tools.stacks ],
INFO tools.stacks "total": 1,
INFO tools.stacks "limit": 20,
INFO tools.stacks "offset": 0
INFO tools.stacks } +0ms
The Stacks Blockchain API documentation is lacking quite a bit of detail. Most endpoints do not have a fully realized description, and all of them lack functional examples of how to at least CURL them. The documentation is generated from the OpenAPI spec file in the stacks-blockchain-api
repository, located here.
Update the OpenAPI spec to include relevant details for every endpoint.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.