hirosystems / docs Goto Github PK

so these seem the wrong way around to me

• /nft_events API
  gives just the items in the wallet now.
  https://docs.hiro.so/api#operation/get_account_nft

Get 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

/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

/nft_events

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

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

Let's review the README and polish the instructions so it is helps onboard and use the templates.

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.

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;
}

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:

1. The type of Clarity value that each endpoint returns (likely included in the OpenAPI spec doc)
2. Examples of the necessary Stacks.js calls to deserialize each type of value
3. A cheatsheet or quick reference for common endpoints and their returned values
4. An example app that exercises the Clarity to JS value code in Stacks.js

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.

We should enable the timestamp and author indicating when and who updated a page. It seems to be a simple configuration:

• https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#showLastUpdateTime
• https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#showLastUpdateAuthor

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:

https://docs.hiro.so/tutorials

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.

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.

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>```

• Run through the document and update required sections.
• Update screenshots

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.

Related to #84

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.

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.

As reported here: https://discord.com/channels/621759717756370964/713087894260023377/915323956431573052

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 :( )

As we continue to answer the questions (sometimes repetitively), it'd be efficient to compile those questions and present them in an FAQ format.

Perhaps add a new FAQ line-item under Developer references, and under the FAQ, we could list API, Clarinet and others.

Something like this:

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.

The registry sample app needs to be updated:

• the sample code on the docs page has new lines making the code unreadable
• the sample code isn't working anymore, as discussed here: stacks-network/docs#1046

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",

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)

example:

https://docs.hiro.so/intro

any of the links to docs for stacks.js are 404ing, i.e. https://blockstack.github.io/stacks.js/modules/transactions.html

Per hirosystems/connect#209

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.

https://docs.hiro.so/build-apps/authentication

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.

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.

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.

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

Description:

1. Add placeholders where ever user need to update his values received by running commands.
   Eg: Balance, btcaddress, stx address etc.

2. 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.

3. Output need to stay outside of the bash command tags.
   Example:

Output:
{eligible : true}

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.

I've tried a few times over the past few days to navigate from the index page to "Write smart contracts" but the site keeps timing out whenever I try, freezing as such:

surfaced in this conversation: leather-io/extension#1700 (comment)

Looks like a custom Docker image needs to be specific in the toml file

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:

curl -X POST https://stacks-node-api.xenon.blockstack.org/extended/v1/faucets/stx?address=ST1P3HXR80TKT48TKM2VTKCDBS4ET9396W0W2S3K8&stacking=true

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.

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.

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.

From @BowTiedDeployer:

it'd be useful to have the commands for deploying a smart contract after the blockchain is running with clarinet integrate

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.

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 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.

Few versions ago address of deployer wallet has been changed in Clarinet.
The new one is: ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM

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.

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