diff --git a/next.config.js b/next.config.js index 6b68b8f3..a0c217fb 100755 --- a/next.config.js +++ b/next.config.js @@ -78,42 +78,42 @@ async function redirects() { }, { source: '/core/smart/overview.html', - destination: '/smart-contracts/overview', + destination: '/write-smart-contracts/overview', permanent: true, }, { source: '/core/smart/tutorial.html', - destination: '/smart-contracts/hello-world-tutorial', + destination: '/write-smart-contracts/hello-world-tutorial', permanent: true, }, { source: '/core/smart/tutorial-counter.html', - destination: '/smart-contracts/counter-tutorial', + destination: '/write-smart-contracts/counter-tutorial', permanent: true, }, { source: '/core/smart/tutorial-test.html', - destination: '/smart-contracts/testing-contracts', + destination: '/write-smart-contracts/testing-contracts', permanent: true, }, { source: '/develop/connect/use-with-clarity.html', - destination: '/smart-contracts/signing-transactions', + destination: '/write-smart-contracts/signing-transactions', permanent: true, }, { source: '/core/smart/principals.html', - destination: '/smart-contracts/principals', + destination: '/write-smart-contracts/principals', permanent: true, }, { source: '/core/smart/testnet-node.html', - destination: '/stacks-blockchain/running-testnet-node', + destination: '/understand-stacks/running-testnet-node', permanent: true, }, { source: '/core/smart/cli-wallet-quickstart.html', - destination: '/smart-contracts/cli-wallet-quickstart', + destination: '/write-smart-contracts/cli-wallet-quickstart', permanent: true, }, { @@ -233,17 +233,17 @@ async function redirects() { }, { source: '/core/atlas/overview.html', - destination: '/stacks-blockchain/atlas-overview', + destination: '/understand-stacks/atlas-overview', permanent: true, }, { source: '/core/atlas/howitworks.html', - destination: '/stacks-blockchain/atlas-how-it-works', + destination: '/understand-stacks/atlas-how-it-works', permanent: true, }, { source: '/core/atlas/howtouse.html', - destination: '/stacks-blockchain/atlas-usage', + destination: '/understand-stacks/atlas-usage', permanent: true, }, { source: '/org/overview.html', destination: '/ecosystem/overview', permanent: true }, @@ -385,7 +385,7 @@ async function redirects() { }, { source: '/core/wire-format.html', - destination: '/stacks-blockchain/wire-format', + destination: '/understand-stacks/wire-format', permanent: true, }, { @@ -400,8 +400,18 @@ async function redirects() { }, { source: '/org/terms.html', destination: '/references/glossary', permanent: true }, // overview redirects - { source: '/stacks-blockchain', destination: '/stacks-blockchain/overview', permanent: true }, - { source: '/smart-contracts', destination: '/smart-contracts/overview', permanent: true }, + { source: '/stacks-blockchain', destination: '/understand-stacks/overview', permanent: true }, + { source: '/smart-contracts', destination: '/write-smart-contracts/overview', permanent: true }, + { + source: '/understand-stacks', + destination: '/understand-stacks/overview', + permanent: true, + }, + { + source: '/write-smart-contracts', + destination: '/write-smart-contracts/overview', + permanent: true, + }, { source: '/data-storage', destination: '/data-storage/overview', permanent: true }, { source: '/data-indexing', destination: '/data-storage/indexing-overview', permanent: true }, { source: '/stacks-wallet', destination: '/stacks-wallet/overview', permanent: true }, @@ -412,22 +422,42 @@ async function redirects() { { source: '/ecosystem', destination: '/ecosystem/overview', permanent: true }, { source: '/stacks-blockchain/testnet-node', - destination: '/stacks-blockchain/running-testnet-node', + destination: '/understand-stacks/running-testnet-node', + permanent: true, + }, + { + source: '/understand-stacks/testnet-node', + destination: '/understand-stacks/running-testnet-node', permanent: true, }, { source: '/stacks-blockchain/atlas/overview', - destination: '/stacks-blockchain/atlas-overview', + destination: '/understand-stacks/atlas-overview', + permanent: true, + }, + { + source: '/understand-stacks/atlas/overview', + destination: '/understand-stacks/atlas-overview', permanent: true, }, { source: '/stacks-blockchain/atlas/how-atlas-works', - destination: '/stacks-blockchain/atlas-how-it-works', + destination: '/understand-stacks/atlas-how-it-works', + permanent: true, + }, + { + source: '/understand-stacks/atlas/how-atlas-works', + destination: '/understand-stacks/atlas-how-it-works', permanent: true, }, { source: '/stacks-blockchain/atlas/usage', - destination: '/stacks-blockchain/atlas-usage', + destination: '/understand-stacks/atlas-usage', + permanent: true, + }, + { + source: '/understand-stacks/atlas/usage', + destination: '/understand-stacks/atlas-usage', permanent: true, }, // data indexing changes diff --git a/package.json b/package.json index 52204fda..81741506 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,9 @@ { "name": "@blockstack/docs", "version": "1.0.0", + "engines": { + "node": ">=12.0.0" + }, "dependencies": { "@docsearch/css": "^1.0.0-alpha.27", "@docsearch/react": "^1.0.0-alpha.27", diff --git a/public/images/pages/build-an-app-sm.svg b/public/images/pages/build-apps-sm.svg similarity index 100% rename from public/images/pages/build-an-app-sm.svg rename to public/images/pages/build-apps-sm.svg diff --git a/public/images/pages/build-an-app.svg b/public/images/pages/build-apps.svg similarity index 100% rename from public/images/pages/build-an-app.svg rename to public/images/pages/build-apps.svg diff --git a/public/images/pages/mining-sm.svg b/public/images/pages/start-mining-sm.svg similarity index 100% rename from public/images/pages/mining-sm.svg rename to public/images/pages/start-mining-sm.svg diff --git a/public/images/pages/mining.svg b/public/images/pages/start-mining.svg similarity index 100% rename from public/images/pages/mining.svg rename to public/images/pages/start-mining.svg diff --git a/public/images/pages/smart-contracts-sm.svg b/public/images/pages/write-smart-contracts-sm.svg similarity index 100% rename from public/images/pages/smart-contracts-sm.svg rename to public/images/pages/write-smart-contracts-sm.svg diff --git a/public/images/pages/smart-contracts.svg b/public/images/pages/write-smart-contracts.svg similarity index 100% rename from public/images/pages/smart-contracts.svg rename to public/images/pages/write-smart-contracts.svg diff --git a/src/common/navigation.yaml b/src/common/navigation.yaml index 5e689818..5fe0ff5c 100644 --- a/src/common/navigation.yaml +++ b/src/common/navigation.yaml @@ -1,12 +1,42 @@ sections: - pages: - path: / - - path: /build-an-app # is an overview page - - path: /smart-contracts + - path: /understand-stacks + pages: + - path: /overview + - path: /testnet + - path: /proof-of-transfer + - path: /mining + - path: /accounts + - path: /transactions + - path: /network + - path: /stacking + - path: /local-development + - path: /technical-specs + sections: + - title: Tutorials + pages: + - path: /managing-accounts + - path: /sending-tokens + - path: /running-testnet-node + - path: /integrate-stacking + - title: Stacks 1.0 + pages: + - path: /stacks-1.0-info + - path: /best-practices + - path: /wire-format + - path: /atlas-overview + - path: /atlas-how-it-works + - path: /atlas-usage + - path: /install-api + - path: /installing-memcached + - path: /build-apps # is an overview page + - path: /write-smart-contracts pages: - path: /overview - path: /principals - - path: /clarity-values + - path: /values + - path: /cli-wallet-quickstart sections: - title: Tutorials pages: @@ -15,7 +45,7 @@ sections: - path: /testing-contracts - path: /public-registry-tutorial - path: /signing-transactions - - path: /mining # is an overview page + - path: /start-mining # is an overview page - title: Technology pages: @@ -46,35 +76,6 @@ sections: - title: Tutorials pages: - path: /integrate-indexing - - path: /stacks-blockchain - pages: - - path: /overview - - path: /testnet - - path: /proof-of-transfer - - path: /mining - - path: /accounts - - path: /transactions - - path: /network - - path: /stacking - - path: /local-development - - path: /technical-specs - sections: - - title: Tutorials - pages: - - path: /managing-accounts - - path: /sending-tokens - - path: /running-testnet-node - - path: /integrate-stacking - - title: Stacks 1.0 - pages: - - path: /stacks-1.0-info - - path: /best-practices - - path: /wire-format - - path: /atlas-overview - - path: /atlas-how-it-works - - path: /atlas-usage - - path: /install-api - - path: /installing-memcached - path: /naming-system # is an overview page - path: /storage-hubs # this seems out of date, kill? pages: diff --git a/src/common/utils/faqs.ts b/src/common/utils/faqs.ts index 56999d00..ad50f286 100644 --- a/src/common/utils/faqs.ts +++ b/src/common/utils/faqs.ts @@ -10,7 +10,7 @@ export const getBetterNames = (id: number) => { return { title: 'Stacks Token', description: 'Questions relating to the native token of Stacks 2.0', - img: '/images/pages/mining.svg', + img: '/images/pages/start-mining.svg', }; case 360007760554: return { diff --git a/src/pages/404.md b/src/pages/404.md index ffa504a9..f32d15b4 100644 --- a/src/pages/404.md +++ b/src/pages/404.md @@ -10,9 +10,9 @@ Looks like the page you are looking for isn't here. [Head back home](/) or try o ## Tutorials [@page-reference | grid] -| /authentication/building-todo-app, /smart-contracts/counter-tutorial +| /authentication/building-todo-app, /write-smart-contracts/counter-tutorial ## Explore [@page-reference | grid-small] -| /ecosystem/overview, /ecosystem/stacks-token, /stacks-blockchain/testnet-node +| /ecosystem/overview, /ecosystem/stacks-token, /understand-stacks/testnet-node diff --git a/src/pages/build-an-app.md b/src/pages/build-apps.md similarity index 87% rename from src/pages/build-an-app.md rename to src/pages/build-apps.md index ae5e2971..f52c95ed 100644 --- a/src/pages/build-an-app.md +++ b/src/pages/build-apps.md @@ -2,8 +2,8 @@ title: Building decentralized apps description: Overview and guides for getting started building decentralized applications. images: - large: /images/pages/build-an-app.svg - sm: /images/pages/build-an-app-sm.svg + large: /images/pages/build-apps.svg + sm: /images/pages/build-apps-sm.svg --- ## Introduction @@ -29,7 +29,7 @@ host, their users’ data. This protects users against security breaches and kee ### Smart contracts -Decentralized apps can use [smart contracts](/smart-contracts/overview) to make their backend logic public, open, and +Decentralized apps can use [smart contracts](/write-smart-contracts/overview) to make their backend logic public, open, and permissionless. Once published on the blockchain, no one really owns or controls a smart contract. They will execute when the terms are met, regardless of who interacts with it. @@ -41,7 +41,7 @@ other apps without requiring permission or fear of being shut out. ## Getting started To build your decentralized app, you’ll use [authentication](/authentication/overview), [data storage](/data-storage/overview), -[data indexing](/data-storage/indexing-overview) (optional), and [smart contracts](/smart-contracts/overview) (optional). +[data indexing](/data-storage/indexing-overview) (optional), and [smart contracts](/write-smart-contracts/overview) (optional). Get started with the documentation and tutorials below. ### Authentication and data storage @@ -72,16 +72,16 @@ You can use smart contracts to decentralize your app’s backend logic, making i on the Stacks blockchain are written in the [Clarity language](https://clarity-lang.org). View the smart contracts documentation or get started with a tutorial. [@page-reference | inline] -| /smart-contracts/overview +| /write-smart-contracts/overview [@page-reference | inline] -| /smart-contracts/hello-world-tutorial +| /write-smart-contracts/hello-world-tutorial [@page-reference | inline] -| /smart-contracts/counter-tutorial +| /write-smart-contracts/counter-tutorial [@page-reference | inline] -| /smart-contracts/public-registry-tutorial +| /write-smart-contracts/public-registry-tutorial ### Stacks.js diff --git a/src/pages/ecosystem/contributing.md b/src/pages/ecosystem/contributing.md index 013a8906..27789257 100644 --- a/src/pages/ecosystem/contributing.md +++ b/src/pages/ecosystem/contributing.md @@ -40,6 +40,8 @@ When workin locally with the site, a few things are needed: - [`node` + `npm`,](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) and [`yarn` installed](https://yarnpkg.com/getting-started/install) on your machine. - Some kind of code editor, such as VSCode, Sublime, or WebStorm. +-> This project requires at least Node version 12 + ### Working with GitHub All of the code for this site is open source, located at the [GitHub repository here](https://github.com/blockstack/docs.blockstack). @@ -132,7 +134,7 @@ If you are adding a new route, you have to add your route to a section contained sections: - pages: - path: / - - path: /build-an-app # is an overview page + - path: /build-apps # is an overview page - path: /smart-contracts pages: - path: /overview diff --git a/src/pages/index.md b/src/pages/index.md index 0afc27cf..79083cd2 100644 --- a/src/pages/index.md +++ b/src/pages/index.md @@ -1,21 +1,24 @@ --- title: Documentation -description: All you need to build decentralized apps and smart contracts. +description: All you need to build decentralized apps, write smart contracts, and start mining --- -# Documentation +## Understand the Stacks blockchain + +[@page-reference | inline] +| /understand-stacks/overview ## Get started [@page-reference | grid] -| /build-an-app, /smart-contracts/overview, /mining +| /build-apps, /write-smart-contracts/overview, /start-mining -## Tutorials +## Try a tutorial [@page-reference | grid] -| /authentication/building-todo-app, /smart-contracts/counter-tutorial +| /authentication/building-todo-app, /write-smart-contracts/counter-tutorial, /understand-stacks/running-testnet-node -## Explore +## Explore more [@page-reference | grid-small] -| /ecosystem/overview, /ecosystem/stacks-token, /stacks-blockchain/running-testnet-node, /stacks-blockchain/proof-of-transfer +| /ecosystem/overview, /ecosystem/stacks-token, /understand-stacks/proof-of-transfer diff --git a/src/pages/references/language-types.md b/src/pages/references/language-types.md index 9989a9d1..4306d454 100644 --- a/src/pages/references/language-types.md +++ b/src/pages/references/language-types.md @@ -1,6 +1,9 @@ --- title: Types description: See a detailed list of all types for the Clarity language. +images: + large: /images/pages/write-smart-contracts.svg + sm: /images/pages/write-smart-contracts-sm.svg --- ## Clarity Type System diff --git a/src/pages/references/stacks-node-configuration.md b/src/pages/references/stacks-node-configuration.md index 6c950566..e30d7c65 100644 --- a/src/pages/references/stacks-node-configuration.md +++ b/src/pages/references/stacks-node-configuration.md @@ -29,7 +29,7 @@ stacks-node mocknet ### krypton (deprecated) -Start a node that will join and stream blocks from the public krypton testnet, powered by Blockstack via [Proof of Transfer](https://docs.blockstack.org/stacks-blockchain/overview#proof-of-transfer-pox). +Start a node that will join and stream blocks from the public krypton testnet, powered by Blockstack via [Proof of Transfer](/understand-stacks/overview#proof-of-transfer-pox). Example: @@ -179,7 +179,7 @@ wait_time_for_microblocks = 15000 The private key to use for mining. Only needed if `miner` is set to `true`. -[See this page for information on how to generate a private key.](https://docs.blockstack.org/mining) +[See this page for information on how to generate a private key.](/start-mining) Example: @@ -191,7 +191,7 @@ seed = "replace-with-your-private-key" The private key to use for signing P2P messages in the networking stack. It differentiates network peers and is used even by non-mining nodes. -[See this page for information on how to generate a private key.](https://docs.blockstack.org/mining) +[See this page for information on how to generate a private key.](/start-mining) Example: @@ -203,7 +203,7 @@ local_peer_seed = "replace-with-your-private-key" Determines whether the stacks-node is running a follower (`false`) or a miner (`true`). Defaults to `false` if omitted. -[See this page for information on how to run a miner.](https://docs.blockstack.org/mining) +[See this page for information on how to run a miner.](/start-mining) Example: @@ -215,7 +215,7 @@ miner = true Determines whether the stacks-node will mine microblocks. Will only take effect if `miner` is set to `true`. -[See this page for information on how to run a miner.](https://docs.blockstack.org/mining) +[See this page for information on how to run a miner.](/start-mining) Example: diff --git a/src/pages/mining.md b/src/pages/start-mining.md similarity index 97% rename from src/pages/mining.md rename to src/pages/start-mining.md index da1a87b6..31f09cff 100644 --- a/src/pages/mining.md +++ b/src/pages/start-mining.md @@ -7,21 +7,21 @@ duration: 10 minutes tags: - tutorial images: - large: /images/pages/mining.svg - sm: /images/pages/mining-sm.svg + large: /images/pages/start-mining.svg + sm: /images/pages/start-mining-sm.svg --- ## Introduction -Make sure you've followed the [Running testnet node](/stacks-blockchain/running-testnet-node) tutorial. Once completed it's only a few more steps to run a proof-of-burn miner on the testnet. +Make sure you've followed the [Running testnet node](/understand-stacks/running-testnet-node) tutorial. Once completed it's only a few more steps to run a proof-of-burn miner on the testnet. [@page-reference | inline] -| /stacks-blockchain/running-testnet-node +| /understand-stacks/running-testnet-node If you want to learn more about the technical details of minig, please review the mining guide: [@page-reference | inline] -| /stacks-blockchain/mining +| /understand-stacks/mining ## Running bitcoind locally @@ -164,7 +164,7 @@ For a full reference of subcommands and configuration options used by `stacks-no To read more about the technical details of mining on the Stacks 2.0 network, have a look at the minig guide: [@page-reference | inline] -| /stacks-blockchain/mining +| /understand-stacks/mining ### Enable debug logging @@ -178,7 +178,7 @@ BLOCKSTACK_DEBUG=1 stacks-node xenon ### Prerequisites -Make sure you've followed the [Running the testnet node on Windows](stacks-blockchain/running-testnet-node#running-the-testnet-node-on-windows) tutorial before starting this tutorial. +Make sure you've followed the [Running the testnet node on Windows](understand-stacks/running-testnet-node#running-the-testnet-node-on-windows) tutorial before starting this tutorial. ### Generate keychain and get testnet tokens in Windows diff --git a/src/pages/stacks-blockchain/accounts.md b/src/pages/understand-stacks/accounts.md similarity index 96% rename from src/pages/stacks-blockchain/accounts.md rename to src/pages/understand-stacks/accounts.md index 8118ee0b..538e3132 100644 --- a/src/pages/stacks-blockchain/accounts.md +++ b/src/pages/understand-stacks/accounts.md @@ -10,13 +10,13 @@ Stacks 2.0 accounts are entities that own assets, like Stacks (STX) tokens. An a If you want to jump right in to generate and query a new account, try this tutorial: [@page-reference | inline] -| /stacks-blockchain/managing-accounts +| /understand-stacks/managing-accounts -> The public-key signature system used for Stacks 2.0 accounts is [Ed25519](https://ed25519.cr.yp.to/). Assets cannot leave an account without an action from the account owner. All changes to assets (and the balances of the account) require a corresponding transaction. --> The [transaction type](/stacks-blockchain/transactions#types) doesn't need to be a token transfer - contract deploy and contract call transactions can change the balances of an account +-> The [transaction type](/understand-stacks/transactions#types) doesn't need to be a token transfer - contract deploy and contract call transactions can change the balances of an account ## Creation @@ -53,7 +53,7 @@ stx make_keychain -t > cli_keychain.json | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `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.privateKey` | Private key for the account. Required for [token transfers](/understand-stacks/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. A construct from the previous blockchain (Stacks 1.0) and currently unused. | @@ -110,7 +110,7 @@ npx -q stacks-gen sk --testnet } ``` --> The stacking object with hashbytes and a version represents the bitcoin address derived from the Stacks address. Read more about the [bitcoin address format](/stacks-blockchain/stacking#bitcoin-address). +-> The stacking object with hashbytes and a version represents the bitcoin address derived from the Stacks address. Read more about the [bitcoin address format](/understand-stacks/stacking#bitcoin-address). Full documentation available at [stacks-gen](https://github.com/psq/stacks-gen). @@ -204,4 +204,4 @@ Sample response: } ``` --> Read more about [pagination](/stacks-blockchain/transactions#pagination) to iterate through the entire result set of the asset events +-> Read more about [pagination](/understand-stacks/transactions#pagination) to iterate through the entire result set of the asset events diff --git a/src/pages/stacks-blockchain/atlas-how-it-works.md b/src/pages/understand-stacks/atlas-how-it-works.md similarity index 100% rename from src/pages/stacks-blockchain/atlas-how-it-works.md rename to src/pages/understand-stacks/atlas-how-it-works.md diff --git a/src/pages/stacks-blockchain/atlas-overview.md b/src/pages/understand-stacks/atlas-overview.md similarity index 100% rename from src/pages/stacks-blockchain/atlas-overview.md rename to src/pages/understand-stacks/atlas-overview.md diff --git a/src/pages/stacks-blockchain/atlas-usage.md b/src/pages/understand-stacks/atlas-usage.md similarity index 100% rename from src/pages/stacks-blockchain/atlas-usage.md rename to src/pages/understand-stacks/atlas-usage.md diff --git a/src/pages/stacks-blockchain/best-practices.md b/src/pages/understand-stacks/best-practices.md similarity index 100% rename from src/pages/stacks-blockchain/best-practices.md rename to src/pages/understand-stacks/best-practices.md diff --git a/src/pages/stacks-blockchain/install-api.md b/src/pages/understand-stacks/install-api.md similarity index 100% rename from src/pages/stacks-blockchain/install-api.md rename to src/pages/understand-stacks/install-api.md diff --git a/src/pages/stacks-blockchain/installing-memcached.md b/src/pages/understand-stacks/installing-memcached.md similarity index 100% rename from src/pages/stacks-blockchain/installing-memcached.md rename to src/pages/understand-stacks/installing-memcached.md diff --git a/src/pages/stacks-blockchain/integrate-stacking.md b/src/pages/understand-stacks/integrate-stacking.md similarity index 97% rename from src/pages/stacks-blockchain/integrate-stacking.md rename to src/pages/understand-stacks/integrate-stacking.md index c6489656..d090664c 100644 --- a/src/pages/stacks-blockchain/integrate-stacking.md +++ b/src/pages/understand-stacks/integrate-stacking.md @@ -29,7 +29,7 @@ This tutorial highlights the following functionality: ## Requirements -First, you'll need to understand the [Stacking mechanism](/stacks-blockchain/stacking). +First, you'll need to understand the [Stacking mechanism](/understand-stacks/stacking). You'll also need [NodeJS](https://nodejs.org/en/download/) `8.12.0` or higher to complete this tutorial. You can verify your installation by opening up your terminal and run the following command: @@ -39,7 +39,7 @@ node --version ## Overview -In this tutorial, we'll implement the Stacking flow laid out in the [Stacking guide](/stacks-blockchain/stacking#stacking-flow). +In this tutorial, we'll implement the Stacking flow laid out in the [Stacking guide](/understand-stacks/stacking#stacking-flow). -> Check out the sample source code for this tutorial in this GitHub repository: [stacking-integration-sample](https://github.com/agraebe/stacking-integration-sample) @@ -101,7 +101,7 @@ const stxAddress = getAddressFromPrivateKey( ); ``` --> Review the [accounts guide](/stacks-blockchain/accounts) for more details +-> Review the [accounts guide](/understand-stacks/accounts) for more details ## Step 3: Display stacking info @@ -234,7 +234,7 @@ unlockingAt.setSeconds( At this point, your app shows Stacking details. If Stacking is executed and the user has enough funds, the user should be asked to provide input for the amount of microstacks to lockup and a bitcoin address to be used to pay out rewards. --> The sample code used assumes usage of the bitcoin address associated with the Stacks account. You can replace this with an address provided by the users or read from your database. Read more about the [bitcoin address format](/stacks-blockchain/stacking#bitcoin-address). +-> The sample code used assumes usage of the bitcoin address associated with the Stacks account. You can replace this with an address provided by the users or read from your database. Read more about the [bitcoin address format](/understand-stacks/stacking#bitcoin-address). With this input, and the data from previous steps, we can determine the eligibility for the next reward cycle: @@ -348,7 +348,7 @@ const waitForTransactionSuccess = txId => const resp = await waitForTransactionSuccess(contractCall.txId); ``` --> More details on the lifecycle of transactions can be found in the [transactions guide](/stacks-blockchain/transactions#lifecycle) +-> More details on the lifecycle of transactions can be found in the [transactions guide](/understand-stacks/transactions#lifecycle) Alternatively to the polling, the Stacks Blockchain API client library offers WebSockets. WebSockets can be used to subscribe to specific updates, like transaction status changes. Here is an example: diff --git a/src/pages/stacks-blockchain/local-development.md b/src/pages/understand-stacks/local-development.md similarity index 100% rename from src/pages/stacks-blockchain/local-development.md rename to src/pages/understand-stacks/local-development.md diff --git a/src/pages/stacks-blockchain/managing-accounts.md b/src/pages/understand-stacks/managing-accounts.md similarity index 97% rename from src/pages/stacks-blockchain/managing-accounts.md rename to src/pages/understand-stacks/managing-accounts.md index 8806fbb3..8426db85 100644 --- a/src/pages/stacks-blockchain/managing-accounts.md +++ b/src/pages/understand-stacks/managing-accounts.md @@ -20,7 +20,7 @@ This tutorial will walk you through the following steps: - Reviewing account history - Getting account balances --> This tutorial is NodeJS-specific. If you would like to understand how to manage Stacks 2.0 accounts using a different language/framework, please [review the accounts guide](/stacks-blockchain/accounts). +-> This tutorial is NodeJS-specific. If you would like to understand how to manage Stacks 2.0 accounts using a different language/framework, please [review the accounts guide](/understand-stacks/accounts). ## Requirements @@ -85,7 +85,7 @@ const stacksAddress = getAddressFromPrivateKey( console.log(accountInfo); ``` --> Note: A "principal" is any entity that can have a token balance. Find more details in the [Principals guide](/smart-contracts/principals). +-> Note: A "principal" is any entity that can have a token balance. Find more details in the [Principals guide](/write-smart-contracts/principals). The API will respond with a balance, nonce (starting at zero), and respective proofs: diff --git a/src/pages/stacks-blockchain/mining.md b/src/pages/understand-stacks/mining.md similarity index 100% rename from src/pages/stacks-blockchain/mining.md rename to src/pages/understand-stacks/mining.md diff --git a/src/pages/stacks-blockchain/network.md b/src/pages/understand-stacks/network.md similarity index 95% rename from src/pages/stacks-blockchain/network.md rename to src/pages/understand-stacks/network.md index a2a0a44c..1fbb28e0 100644 --- a/src/pages/stacks-blockchain/network.md +++ b/src/pages/understand-stacks/network.md @@ -11,7 +11,7 @@ STX amounts should be stored as integers (8 bytes long), and represent the amoun ## Fees -Fees are used to incentivize miners to confirm transactions on the Stacks 2.0 blockchain. The fee is calculated based on the estimate fee rate and the size of the [raw transaction](http://localhost:3000/stacks-blockchain/transactions#serialization) in bytes. The fee rate is a market determined variable. For the [testnet](/stacks-blockchain/testnet), it is set to 1 micro-STX. +Fees are used to incentivize miners to confirm transactions on the Stacks 2.0 blockchain. The fee is calculated based on the estimate fee rate and the size of the [raw transaction](http://localhost:3000/understand-stacks/transactions#serialization) in bytes. The fee rate is a market determined variable. For the [testnet](/understand-stacks/testnet), it is set to 1 micro-STX. Fee estimates can obtained through the [`GET /v2/fees/transfer`](https://blockstack.github.io/stacks-blockchain-api/#operation/get_fee_transfer) endpoint: @@ -41,7 +41,7 @@ Nonces are added to all transactions and help identify them in order to ensure t -> The consensus mechanism also ensures that transactions aren't "replayed" in two ways. First, nodes query its unspent transaction outputs (UTXOs) in order to satisfy their spending conditions in a new transaction. Second, messages sent between nodes review sequence numbers. -When a new [token transfer transaction](/stacks-blockchain/transactions#stacks-token-transfer) is constructed, the most recent nonce of the account needs to fetched and set. +When a new [token transfer transaction](/understand-stacks/transactions#stacks-token-transfer) is constructed, the most recent nonce of the account needs to fetched and set. ## Confirmations @@ -49,7 +49,7 @@ The Stacks 2.0 network is anchored onto the bitcoin network. This allows transac The time to mine a block, to confirm transactions, will eventually match the expected "block time" of the bitcoin network: 10 minutes. -The block time is hardcoded and will change throughout the implementation phases of the [testnet](/stacks-blockchain/testnet). The current block time can be obtained through the [`GET /extended/v1/info/network_block_times`](https://blockstack.github.io/stacks-blockchain-api/#operation/get_network_block_times) endpoint: +The block time is hardcoded and will change throughout the implementation phases of the [testnet](/understand-stacks/testnet). The current block time can be obtained through the [`GET /extended/v1/info/network_block_times`](https://blockstack.github.io/stacks-blockchain-api/#operation/get_network_block_times) endpoint: ```bash curl 'https://stacks-node-api.blockstack.org/extended/v1/info/network_block_times' @@ -96,7 +96,7 @@ Sample response for a successful call: } ``` --> To set the function call arguments and read the result, [Clarity values](http://localhost:3000/stacks-blockchain/transactions#clarity-value-types) need to be serialized into a hexadecimal string. The [Stacks Transactions JS](https://github.com/blockstack/stacks.js/tree/master/packages/transactions) library supports these operations +-> To set the function call arguments and read the result, [Clarity values](http://localhost:3000/understand-stacks/transactions#clarity-value-types) need to be serialized into a hexadecimal string. The [Stacks Transactions JS](https://github.com/blockstack/stacks.js/tree/master/packages/transactions) library supports these operations ## Querying @@ -147,7 +147,7 @@ The easiest way of identifying the health is by looking at the `blockRateStatus` | **Block Rate Value** | **Status** | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `0` | Online. All checks are successful | -| `1` | Slow. The network produces new blocks at slower rate as expected. Transaction confirmation times will likely take longer than the [set block time](/stacks-blockchain/network#confirmations) | +| `1` | Slow. The network produces new blocks at slower rate as expected. Transaction confirmation times will likely take longer than the [set block time](/understand-stacks/network#confirmations) | | `2` | Degraded. The network seems not to be fully operational | ### Network info diff --git a/src/pages/stacks-blockchain/overview.md b/src/pages/understand-stacks/overview.md similarity index 90% rename from src/pages/stacks-blockchain/overview.md rename to src/pages/understand-stacks/overview.md index ef6213af..c0c6df93 100644 --- a/src/pages/stacks-blockchain/overview.md +++ b/src/pages/understand-stacks/overview.md @@ -1,6 +1,10 @@ --- title: Overview description: Learn more about the Stacks blockchain +icon: TestnetIcon +images: + large: /images/pages/testnet.svg + sm: /images/pages/testnet-sm.svg --- ## Introduction @@ -16,9 +20,9 @@ The Stacks 2.0 blockchain is in active development. While the final release ("ma More information about the testnet: [@page-reference | inline] -| /stacks-blockchain/testnet +| /understand-stacks/testnet -=> The status of the Stacks 2.0 network can be viewed on the [status checker](/stacks-blockchain/network#health-check) +=> The status of the Stacks 2.0 network can be viewed on the [status checker](/understand-stacks/network#health-check) ## Explorer @@ -29,11 +33,11 @@ You can view accounts, blocks, transactions, and smart contracts broadcasted to ## Tutorials [@page-reference | grid-small] -| /stacks-blockchain/managing-accounts, /stacks-blockchain/sending-tokens, /stacks-blockchain/running-testnet-node +| /understand-stacks/managing-accounts, /understand-stacks/sending-tokens, /understand-stacks/running-testnet-node ## Features -A high-level summary of various technical aspects of the Stacks 2.0 blockchain can be found below in the [Technical Specifications](/stacks-blockchain/technical-specs). +A high-level summary of various technical aspects of the Stacks 2.0 blockchain can be found below in the [Technical Specifications](/understand-stacks/technical-specs). ### Clarity Smart Contracts @@ -48,18 +52,18 @@ Smart contracts on the Stacks 2.0 blockchain are written in a new programming la -> The [Clarity open-source project](https://clarity-lang.org/) is supported by Stacks and Algorand. [@page-reference | inline] -| /smart-contracts/overview +| /write-smart-contracts/overview ### Stacks Mining Mining is required to make the network usable, trustworthy, and secure. Miners verify incoming transactions and participate in the consensus mechanism of the Stacks 2.0 blockchain, called Proof of Transfer (PoX). To incentivize mining, miners receive freshly minted Stacks (STX) tokens. [@page-reference | inline] -| /mining +| /start-mining ### Proof of Transfer (PoX) -[Proof of Transfer (PoX)](/stacks-blockchain/proof-of-transfer) is a novel consensus mechanism that leverages the security and stability of Bitcoin to create a new blockchain, without modifying the Bitcoin protocol. +[Proof of Transfer (PoX)](/understand-stacks/proof-of-transfer) is a novel consensus mechanism that leverages the security and stability of Bitcoin to create a new blockchain, without modifying the Bitcoin protocol. Stacks (STX) miners transfer Bitcoin to other Stacks (STX) holders in order to mine blocks. This BTC reward mechanism is called **Stacking**. diff --git a/src/pages/stacks-blockchain/proof-of-transfer.md b/src/pages/understand-stacks/proof-of-transfer.md similarity index 97% rename from src/pages/stacks-blockchain/proof-of-transfer.md rename to src/pages/understand-stacks/proof-of-transfer.md index 12939ac1..0bef1171 100644 --- a/src/pages/stacks-blockchain/proof-of-transfer.md +++ b/src/pages/understand-stacks/proof-of-transfer.md @@ -8,7 +8,7 @@ icon: TestnetIcon Consensus algorithms for public blockchains require computing or financial resources to secure the blockchain. The idea being to make it practically infeasible for any single malicious actor to have enough computing power or ownership stake to attack the network. -Mining mechanisms used by these algorithms are broadly divided into proof-of-work, in which nodes dedicate computing resources, and proof-of-stake, in which nodes dedicate financial resources to participate in the [consensus algorithm](/stacks-blockchain/stacking#stacking-consensus-algorithm). +Mining mechanisms used by these algorithms are broadly divided into proof-of-work, in which nodes dedicate computing resources, and proof-of-stake, in which nodes dedicate financial resources to participate in the [consensus algorithm](/understand-stacks/stacking#stacking-consensus-algorithm). A variant of proof-of-work is proof-of-burn where miners compete by ‘burning’ (destroying) a proof-of-work cryptocurrency as a proxy for computing resources. diff --git a/src/pages/stacks-blockchain/running-testnet-node.md b/src/pages/understand-stacks/running-testnet-node.md similarity index 99% rename from src/pages/stacks-blockchain/running-testnet-node.md rename to src/pages/understand-stacks/running-testnet-node.md index c1e0242e..2c15254c 100644 --- a/src/pages/stacks-blockchain/running-testnet-node.md +++ b/src/pages/understand-stacks/running-testnet-node.md @@ -206,4 +206,4 @@ For more information on the Helm chart and configuration options, please refer t Now that you have a running testnet node, you can easily set up a miner. [@page-reference | inline] -| /mining +| /start-mining diff --git a/src/pages/stacks-blockchain/sending-tokens.md b/src/pages/understand-stacks/sending-tokens.md similarity index 94% rename from src/pages/stacks-blockchain/sending-tokens.md rename to src/pages/understand-stacks/sending-tokens.md index 75008f2c..6c952e4f 100644 --- a/src/pages/stacks-blockchain/sending-tokens.md +++ b/src/pages/understand-stacks/sending-tokens.md @@ -21,7 +21,7 @@ This tutorial walks you through the following steps: - Checking transaction completion - Confirming updates account balances (optional) --> This tutorial is NodeJS-specific. If you would like to understand how to initiate a token transfer by constructing and broadcasting transactions using a different language/framework, please [review the transactions guide](/stacks-blockchain/transactions). +-> This tutorial is NodeJS-specific. If you would like to understand how to initiate a token transfer by constructing and broadcasting transactions using a different language/framework, please [review the transactions guide](/understand-stacks/transactions). ## Requirements @@ -31,7 +31,7 @@ You will need [NodeJS](https://nodejs.org/en/download/) `8.12.0` or higher to co node --version ``` -You should also complete the [Managing accounts tutorial](/stacks-blockchain/managing-accounts). The following steps assume we have access to an existing Stacks 2.0 account. +You should also complete the [Managing accounts tutorial](/understand-stacks/managing-accounts). The following steps assume we have access to an existing Stacks 2.0 account. ## Step 1: Installing libraries @@ -45,7 +45,7 @@ npm install --save @stacks/transactions bn.js @stacks/blockchain-api-client cros ## Step 2: Specifying a sender -In order to build and sign transactions, you will need a Stacks private key. You can easily generate a new, random Stacks 2.0 sender key (see ["Generating an account" from the previous tutorial](/stacks-blockchain/managing-accounts#step-2-generating-an-account)). +In order to build and sign transactions, you will need a Stacks private key. You can easily generate a new, random Stacks 2.0 sender key (see ["Generating an account" from the previous tutorial](/understand-stacks/managing-accounts#step-2-generating-an-account)). For this tutorial, we will use an existing Stacks account and instantiate the key object from a private key string: @@ -128,7 +128,7 @@ The generation method will need a few more pieces of information, as specified i If not specified, the transaction builder will automatically estimate the fee. Estimated fee rate is supplied by a Stacks node so network access is required. --> Learn more about fees in the [network guide](/stacks-blockchain/network#fees) +-> Learn more about fees in the [network guide](/understand-stacks/network#fees) Another way to estimate the fee is to use the `estimateTransfer()` function after you have constructed a transaction: @@ -162,7 +162,7 @@ const txId = await broadcastTransaction(transaction, testnet); As soon as the `broadcastTransaction` is completed, a transaction ID is returned. -~> Keep in mind that the existence of a transaction ID does not mean the transaction has been successfully processed. Please review the [transaction lifecycle](/stacks-blockchain/transactions#lifecycle) for more details. +~> Keep in mind that the existence of a transaction ID does not mean the transaction has been successfully processed. Please review the [transaction lifecycle](/understand-stacks/transactions#lifecycle) for more details. ### Serializing transactions @@ -219,4 +219,4 @@ For all property formats and details, please review the [API reference](https:// ## Step 6: Confirming balance (optional) -Now that the token transfer is confirmed, we can verify the new account balance on the sender address by [following the "Getting account balances" steps from the previous tutorial](/stacks-blockchain/managing-accounts#step-5-getting-account-balances). +Now that the token transfer is confirmed, we can verify the new account balance on the sender address by [following the "Getting account balances" steps from the previous tutorial](/understand-stacks/managing-accounts#step-5-getting-account-balances). diff --git a/src/pages/stacks-blockchain/stacking.md b/src/pages/understand-stacks/stacking.md similarity index 97% rename from src/pages/stacks-blockchain/stacking.md rename to src/pages/understand-stacks/stacking.md index 2046fc28..c7f2b5e5 100644 --- a/src/pages/stacks-blockchain/stacking.md +++ b/src/pages/understand-stacks/stacking.md @@ -13,7 +13,7 @@ Stacking rewards Stacks (STX) token holders with bitcoin for providing a valuabl Stacking is a built-in action, required by the "proof-of-transfer" (PoX) mechanism. The PoX mechanism is executed by every miner on the Stacks 2.0 network. --> The Stacking consensus algorithm is implemented as a smart contract, using [Clarity](/smart-contracts/overview). [Read more about the contract](#stacking-contract). +-> The Stacking consensus algorithm is implemented as a smart contract, using [Clarity](/write-smart-contracts/overview). [Read more about the contract](#stacking-contract). ## Stacking flow @@ -33,7 +33,7 @@ The Stacking mechanism can be presented as a flow of actions: If you would like to implement this flow in your own wallet, exchange, or any other application, please have a look at this tutorial: [@page-reference | inline] -| /stacks-blockchain/integrate-stacking +| /understand-stacks/integrate-stacking ## PoX mining @@ -49,7 +49,7 @@ Miners have to run a software (mining client, aka "miner") on their machines to - Assembly: The elected miner writes the new block and collects rewards in form of new Stacks (STX) tokens [@page-reference | inline] -| /mining +| /start-mining ## Token holder eligibility diff --git a/src/pages/stacks-blockchain/stacks-1.0-info.md b/src/pages/understand-stacks/stacks-1.0-info.md similarity index 100% rename from src/pages/stacks-blockchain/stacks-1.0-info.md rename to src/pages/understand-stacks/stacks-1.0-info.md diff --git a/src/pages/stacks-blockchain/technical-specs.md b/src/pages/understand-stacks/technical-specs.md similarity index 89% rename from src/pages/stacks-blockchain/technical-specs.md rename to src/pages/understand-stacks/technical-specs.md index f255d919..367cfd7d 100644 --- a/src/pages/stacks-blockchain/technical-specs.md +++ b/src/pages/understand-stacks/technical-specs.md @@ -7,7 +7,7 @@ description: Summary of technical specifications of Stacks 2.0 - Proof of Transfer (PoX) as described in [SIP-007](https://github.com/blockstack/stacks-blockchain/blob/master/sip/sip-007-stacking-consensus.md) - Network will transition to Proof of Burn (PoB) as described in [SIP-001](https://github.com/blockstack/stacks-blockchain/blob/master/sip/sip-001-burn-election.md) after 10 years. More details [here](https://github.com/blockstack/stacks-blockchain/blob/master/sip/sip-001-burn-election.md). -- For more details, see [Proof of Transfer](/stacks-blockchain/proof-of-transfer). +- For more details, see [Proof of Transfer](/understand-stacks/proof-of-transfer). ## Proof of Transfer Mining @@ -21,7 +21,7 @@ description: Summary of technical specifications of Stacks 2.0 - Reward maturity window: 100 blocks, meaning leaders will earn the coinbase reward 100 blocks after the block they successfully mine. - Block interval: Stacks blockchain produces blocks at the same rate as the underlying burnchain. For Bitcoin, this is approximately every 10 minutes. - BTC commitment: Miners must commit atleast 11,000 satoshis (5,500 sats / [UTXO output](https://learnmeabitcoin.com/technical/utxo)); 2 outputs / block) to avoid "dust". -- For more details, see [Mining](/stacks-blockchain/mining). +- For more details, see [Mining](/understand-stacks/mining). ## Stacking @@ -31,8 +31,8 @@ description: Summary of technical specifications of Stacks 2.0 - Two reward addresses / block, for a total of 4000 addresses every reward cycle. The addresses are chosen using a VRF (verifiable random function), so each node can deterministically arrive at the same reward addresses for a given block. - Stacking threshold: 0.025% of the participating amount of STX when participation is between 25% and 100% and when participation is below 25%, the threshold level is always 0.00625 of the liquid supply of STX. - Delegation: An STX address can designate another address to participate in Stacking on its behalf. [Relevant section in SIP-007](https://github.com/blockstack/stacks-blockchain/blob/master/sip/sip-007-stacking-consensus.md#stacker-delegation). -- Pooling: STX holders that individually do not meet the Stacking threshold can pool together their holdings to participate in Stacking. To do this, STX holders must set the (optional) reward address to the "delegate address". For more details, see [this reference](https://docs.blockstack.org/references/stacking-contract#delegate-stx). -- Further reading: [Stacking](/stacks-blockchain/stacking) +- Pooling: STX holders that individually do not meet the Stacking threshold can pool together their holdings to participate in Stacking. To do this, STX holders must set the (optional) reward address to the "delegate address". For more details, see [this reference](/references/stacking-contract#delegate-stx). +- Further reading: [Stacking](/understand-stacks/stacking) ## Accounts and Addresses @@ -43,11 +43,11 @@ description: Summary of technical specifications of Stacks 2.0 - Nonce counts number of times an account has authorized a transaction. Starts at 0, valid authorization must include the _next_ nonce value. - Assets are a map of all asset types -- STX, any on-chain assets specified by a Clarity contract (e.g. NFTs) -- to quantities owned by that account. - Accounts need not be explicit "created" or registered; all accounts implicitly exist and are instantiated on first-use. -- Further reading: [Accounts](/stacks-blockchain/accounts) +- Further reading: [Accounts](/understand-stacks/accounts) ## Transactions -- [Transaction types](https://docs.blockstack.org/stacks-blockchain/transactions#types): coinbase, token-transfer, contract-deploy, contract-call, poison-microblock. +- [Transaction types](/understand-stacks/transactions#types): coinbase, token-transfer, contract-deploy, contract-call, poison-microblock. - Only standard accounts (not contracts) can pay transaction fees. - Transaction execution is governed by 3 accounts (may or may not be distinct) 1. _originating account_ is the account that creates, _authorizes_ and sends the transaction @@ -55,6 +55,6 @@ description: Summary of technical specifications of Stacks 2.0 3. _sending account_ is the account that identifies who is currently executing the transaction: this can change as a transaction executes via the `as-contract` Clarity function - Two types of authorizations: standard authorization is where originating account is the same as paying account. _Sponsored_ authorization is where originating account and paying account are distinct. For instance, developers or service providers could pay for users to call their smart-contracts. - For sponsored authorization, first a user signs with the originating account and then a sponsor signs with the paying account. -- Transaction encoding is described [here](https://github.com/blockstack/stacks-blockchain/blob/master/sip/sip-005-blocks-and-transactions.md#transaction-encoding) and [here](/stacks-blockchain/transactions#encoding) -- Transaction signing and verification are described [here](https://github.com/blockstack/stacks-blockchain/blob/master/sip/sip-005-blocks-and-transactions.md#transaction-signing-and-verifying) and [here](/stacks-blockchain/transactions.md#signature-and-verification) -- Further reading: [Transactions](/stacks-blockchain/transactions) +- Transaction encoding is described [here](https://github.com/blockstack/stacks-blockchain/blob/master/sip/sip-005-blocks-and-transactions.md#transaction-encoding) and [here](/understand-stacks/transactions#encoding) +- Transaction signing and verification are described [here](https://github.com/blockstack/stacks-blockchain/blob/master/sip/sip-005-blocks-and-transactions.md#transaction-signing-and-verifying) and [here](/understand-stacks/transactions.md#signature-and-verification) +- Further reading: [Transactions](/understand-stacks/transactions) diff --git a/src/pages/stacks-blockchain/testnet.md b/src/pages/understand-stacks/testnet.md similarity index 100% rename from src/pages/stacks-blockchain/testnet.md rename to src/pages/understand-stacks/testnet.md diff --git a/src/pages/stacks-blockchain/transactions.md b/src/pages/understand-stacks/transactions.md similarity index 94% rename from src/pages/stacks-blockchain/transactions.md rename to src/pages/understand-stacks/transactions.md index bbd823c3..827f5195 100644 --- a/src/pages/stacks-blockchain/transactions.md +++ b/src/pages/understand-stacks/transactions.md @@ -5,12 +5,12 @@ description: Guide to Stacks 2.0 transactions ## Introduction -Transactions are the fundamental unit of execution in the Stacks blockchain. Each transaction is originated from a [Stacks 2.0 account](/stacks-blockchain/accounts), and is retained in the Stacks blockchain history for eternity. This guide helps you understand Stacks 2.0 transactions. +Transactions are the fundamental unit of execution in the Stacks blockchain. Each transaction is originated from a [Stacks 2.0 account](/understand-stacks/accounts), and is retained in the Stacks blockchain history for eternity. This guide helps you understand Stacks 2.0 transactions. If you want to jump right in and broadcast your first transaction, try this tutorial: [@page-reference | inline] -| /stacks-blockchain/sending-tokens +| /understand-stacks/sending-tokens -> The information on this page is based on a design proposal. You can find more conceptual details in this document: [SIP 005: Blocks, Transaction, Accounts](https://github.com/blockstack/stacks-blockchain/blob/master/sip/sip-005-blocks-and-transactions.md). @@ -45,7 +45,7 @@ The Stacks 2.0 supports a set of different transaction types: A sample of each transaction type can be found in the [Stacks Blockchain API response definition for transactions](https://blockstack.github.io/stacks-blockchain-api/#operation/get_transaction_by_id). -~> Read-only contract call calls do **not** require transactions. Read more about it in the [network guide](/stacks-blockchain/network#read-only-function-calls). +~> Read-only contract call calls do **not** require transactions. Read more about it in the [network guide](/understand-stacks/network#read-only-function-calls). ## Post-conditions @@ -57,12 +57,12 @@ Post-conditions are meant to be added by the user (or by the user's wallet softw Each transaction includes a field that describes zero or more post-conditions that must all be true when the transaction finishes running. A post-condition includes the following information: -| **Attribute** | **Sample** | **Description** | -| ---------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------- | -| [Principal](/smart-contracts/principals) | `SP2ZD731ANQZT6J4K3F5N8A40ZXWXC1XFXHVVQFKE` | Sender of the transaction, can be a Stacks address or a contract | -| Asset name | `STX` | Asset to apply conditions to (could be Stacks, fungible, or non-fungible tokens) | -| Comparator | `>=` | Compare operation to be applied (could define "how much" or "whether or not") | -| Literal | `1000000` | Integer or boolean value used to compare instances of the asset against via the condition | +| **Attribute** | **Sample** | **Description** | +| ---------------------------------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------- | +| [Principal](/write-smart-contracts/principals) | `SP2ZD731ANQZT6J4K3F5N8A40ZXWXC1XFXHVVQFKE` | Sender of the transaction, can be a Stacks address or a contract | +| Asset name | `STX` | Asset to apply conditions to (could be Stacks, fungible, or non-fungible tokens) | +| Comparator | `>=` | Compare operation to be applied (could define "how much" or "whether or not") | +| Literal | `1000000` | Integer or boolean value used to compare instances of the asset against via the condition | ### Evaluation modes @@ -99,7 +99,7 @@ The easiest way to construct well-formed transactions is by [using the Stacks Tr - Smart contract deploy - Smart contract function call -When constructing transactions, it is required to set the network the transaction is intended for. This can be either mainnet or testnet. At the moment of this writing, the only available option is the [testnet network](/stacks-blockchain/testnet). +When constructing transactions, it is required to set the network the transaction is intended for. This can be either mainnet or testnet. At the moment of this writing, the only available option is the [testnet network](/understand-stacks/testnet). -> Transactions can be constructed and serialized offline. However, it is required to know the nonce and estimated fees ahead of time. Once internet access is available, the transaction can be broadcasted to the network. Keep in mind that the nonce and fee might change during offline activity, making the transaction invalid. @@ -124,7 +124,7 @@ const txOptions = { const transaction = await makeSTXTokenTransfer(txOptions); ``` --> Read more about [nonces](/stacks-blockchain/network#nonces) in the network guide +-> Read more about [nonces](/understand-stacks/network#nonces) in the network guide ### Smart contract deployment @@ -485,7 +485,7 @@ Sample response: #### Filter by type -Recent transactions can be filtered by [transaction type](/stacks-blockchain/transactions#types) using the `type` query parameter: +Recent transactions can be filtered by [transaction type](/understand-stacks/transactions#types) using the `type` query parameter: ```bash curl 'https://stacks-node-api.blockstack.org/extended/v1/tx/?type=contract_call' diff --git a/src/pages/stacks-blockchain/wire-format.md b/src/pages/understand-stacks/wire-format.md similarity index 100% rename from src/pages/stacks-blockchain/wire-format.md rename to src/pages/understand-stacks/wire-format.md diff --git a/src/pages/smart-contracts/cli-wallet-quickstart.md b/src/pages/write-smart-contracts/cli-wallet-quickstart.md similarity index 100% rename from src/pages/smart-contracts/cli-wallet-quickstart.md rename to src/pages/write-smart-contracts/cli-wallet-quickstart.md diff --git a/src/pages/smart-contracts/counter-tutorial.md b/src/pages/write-smart-contracts/counter-tutorial.md similarity index 98% rename from src/pages/smart-contracts/counter-tutorial.md rename to src/pages/write-smart-contracts/counter-tutorial.md index 346b4679..babafac2 100644 --- a/src/pages/smart-contracts/counter-tutorial.md +++ b/src/pages/write-smart-contracts/counter-tutorial.md @@ -203,7 +203,7 @@ Let's get familiar with the tests to understand what the new smart contract shou ## Step 4: Deploy and call the contract Your new smart contract is ready to be deployed to the Stacks 2.0 blockchain. You should be familiar with the steps -from the ["Hello, World" tutorial](/smart-contracts/hello-world-tutorial#deploy-the-contract). +from the ["Hello, World" tutorial](/write-smart-contracts/hello-world-tutorial#deploy-the-contract). As soon as you successfully deploy your contract, you can play around with the contract and verify the functionality by calling all public methods you implemented. Here's a suggested order: diff --git a/src/pages/smart-contracts/hello-world-tutorial.md b/src/pages/write-smart-contracts/hello-world-tutorial.md similarity index 100% rename from src/pages/smart-contracts/hello-world-tutorial.md rename to src/pages/write-smart-contracts/hello-world-tutorial.md diff --git a/src/pages/smart-contracts/install-source.md b/src/pages/write-smart-contracts/install-source.md similarity index 100% rename from src/pages/smart-contracts/install-source.md rename to src/pages/write-smart-contracts/install-source.md diff --git a/src/pages/smart-contracts/overview.md b/src/pages/write-smart-contracts/overview.md similarity index 90% rename from src/pages/smart-contracts/overview.md rename to src/pages/write-smart-contracts/overview.md index 467e0c49..f1992bb7 100644 --- a/src/pages/smart-contracts/overview.md +++ b/src/pages/write-smart-contracts/overview.md @@ -2,8 +2,8 @@ title: Write smart contracts description: Overview and guides for getting started with Clarity images: - large: /images/pages/smart-contracts.svg - sm: /images/pages/smart-contracts-sm.svg + large: /images/pages/write-smart-contracts.svg + sm: /images/pages/write-smart-contracts-sm.svg --- ## Introduction @@ -61,9 +61,9 @@ Note some of the key Clarity language rules and limitations. ## Learning Clarity -The tutorials are ordered from "beginner" to "advanced." Start with the [Hello World tutorial](/smart-contracts/hello-world-tutorial), -then learn how to construct [a counter](/smart-contracts/counter-tutorial), and finally, learn how to -[test your smart contracts](/smart-contracts/testing-contracts) using Mocha. +The tutorials are ordered from "beginner" to "advanced." Start with the [Hello World tutorial](/write-smart-contracts/hello-world-tutorial), +then learn how to construct [a counter](/write-smart-contracts/counter-tutorial), and finally, learn how to +[test your smart contracts](/write-smart-contracts/testing-contracts) using Mocha. Once you've got the hang of the general workflow, environment, and language syntax, you should be ready to start writing contracts, referring to the [Clarity language reference](/references/language-overview) as you go. diff --git a/src/pages/smart-contracts/principals.md b/src/pages/write-smart-contracts/principals.md similarity index 100% rename from src/pages/smart-contracts/principals.md rename to src/pages/write-smart-contracts/principals.md diff --git a/src/pages/smart-contracts/public-registry-tutorial.md b/src/pages/write-smart-contracts/public-registry-tutorial.md similarity index 95% rename from src/pages/smart-contracts/public-registry-tutorial.md rename to src/pages/write-smart-contracts/public-registry-tutorial.md index fad05ce1..d1f38447 100644 --- a/src/pages/smart-contracts/public-registry-tutorial.md +++ b/src/pages/write-smart-contracts/public-registry-tutorial.md @@ -31,14 +31,14 @@ By the end of this tutorial, you will... The Stacks 2.0 blockchain is currently in development and could experience resets and downtimes. To make sure you're not running into any challenges related to the status of the network, please open up the [Status Checker](http://status.test-blockstack.com/) and confirm that all systems are operational. If some systems seem to have issues, it is best to wait until they are back up before you proceed with the next steps. -Furthermore, the to-do app will interact with a smart contract deployed as `ST1234....todo-registry`. he contract source code is available at [github](https://github.com/friedger/blockstack-todos/blob/tut/step1/contracts/todo-registry.clar). There might be already a deployed version available on testnet. You can use the testnet explorer to search for it. Alternatively, You have to deploy the contract as described in the [hello world tutorial](/smart-contracts/hello-world-tutorial#step-5-deploy-the-contract). Then you have to use the corresponding contract address and name in this tutorial. Throughout this tutorial, we use `ST3YPJ6BBCZCMH71TV8BK50YC6QJTWEGCNDFWEQ15.todo-registry` as an example. +Furthermore, the to-do app will interact with a smart contract deployed as `ST1234....todo-registry`. The contract source code is available at [github](https://github.com/friedger/blockstack-todos/blob/tut/step1/contracts/todo-registry.clar). There may already be a deployed version available on the testnet; the [testnet explorer](https://testnet-explorer.blockstack.org/) can be used to search for it. Alternatively, the contract can be deployed as described in the [hello world tutorial](/smart-contracts/hello-world-tutorial#step-5-deploy-the-contract). Then you have to use the corresponding contract address and name in this tutorial. Throughout this tutorial, we use `ST3YPJ6BBCZCMH71TV8BK50YC6QJTWEGCNDFWEQ15.todo-registry` as an example. ### Tutorials You should have followed the instructions of the to-do app tutorial. You should have the code ready on your local machine. It is also helpful to have a basic understanding of Clarity as explained in the counter tutorial. If you are using mocknet or a new, empty testnet you can create transactions following the tutorial about signing transactions. [@page-reference | grid] -| /authentication/building-todo-app, /smart-contracts/counter-tutorial, /smart-contracts/signing-transactions +| /authentication/building-todo-app, /write-smart-contracts/counter-tutorial, /write-smart-contracts/signing-transactions ### Check your to-do app @@ -120,7 +120,7 @@ export const PublicUrlRegistrar = ({ userSession }) => { }; ``` -It is a simple button that calls `doContractCall` method of the Connect library when clicked. The method makes an api call to the Stacks authenticator. The authenticator creates a contract call transaction that is signed by the user and then it is broadcasted to the Stacks 2.0 blockchain as explained in the [transaction signing tutorial](/smart-contracts/signing-transactions). +It is a simple button that calls `doContractCall` method of the Connect library when clicked. The method makes an api call to the Stacks authenticator. The authenticator creates a contract call transaction that is signed by the user and then it is broadcasted to the Stacks 2.0 blockchain as explained in the [transaction signing tutorial](/write-smart-contracts/signing-transactions). Note how the arguments are created using `bufferCVFromString`. There are similar methods for all other Clarity types, like `uintCV` or `trueCV`. See the [documentation](https://github.com/blockstack/stacks-transactions-js#constructing-clarity-values) of the stacks-transactions library for more details. @@ -451,7 +451,7 @@ In addition to `tx_result`, the transaction object also contains a timestamp (`b ## Fetch the first to-do list -There are two other ways to get state information from the blockchain: read-only functions and data map entries. Read-only functions were already discussed in the [Clarity counter tutorial](/smart-contracts/counter-tutorial). They do not require a transaction to complete. Data maps in Clarity are maps that can be read by any user. See the [Clarity reference](https://docs.blockstack.org/references/language-functions#define-map) for more details. +There are two other ways to get state information from the blockchain: read-only functions and data map entries. Read-only functions were already discussed in the [Clarity counter tutorial](/write-smart-contracts/counter-tutorial). They do not require a transaction to complete. Data maps in Clarity are maps that can be read by any user. See the [Clarity reference](/references/language-functions#define-map) for more details. The `todo-registry` contract defines a read-only function `owner-of?` that returns the owner of a registry entry and a data map for details about entries: diff --git a/src/pages/smart-contracts/signing-transactions.md b/src/pages/write-smart-contracts/signing-transactions.md similarity index 99% rename from src/pages/smart-contracts/signing-transactions.md rename to src/pages/write-smart-contracts/signing-transactions.md index 336581e7..3670ef3c 100644 --- a/src/pages/smart-contracts/signing-transactions.md +++ b/src/pages/write-smart-contracts/signing-transactions.md @@ -6,8 +6,8 @@ duration: 30 minutes tags: - tutorial images: - large: /images/pages/smart-contracts.svg - sm: /images/pages/smart-contracts-sm.svg + large: /images/pages/write-smart-contracts.svg + sm: /images/pages/write-smart-contracts-sm.svg --- ## Introduction diff --git a/src/pages/smart-contracts/testing-contracts.md b/src/pages/write-smart-contracts/testing-contracts.md similarity index 100% rename from src/pages/smart-contracts/testing-contracts.md rename to src/pages/write-smart-contracts/testing-contracts.md diff --git a/src/pages/smart-contracts/clarity-values.md b/src/pages/write-smart-contracts/values.md similarity index 87% rename from src/pages/smart-contracts/clarity-values.md rename to src/pages/write-smart-contracts/values.md index c79e4625..4699e7b9 100644 --- a/src/pages/smart-contracts/clarity-values.md +++ b/src/pages/write-smart-contracts/values.md @@ -5,25 +5,16 @@ description: Learn how to deal with Clarity Values in JavaScript. ## Introduction -The Clarity language makes use of a strong static [type system](https://docs.blockstack.org/references/language-clarity#clarity-type-system). This simply means that every function defined in Clarity expects arguments of specific types, and that a failure to provide properly typed arguments will result in your code failing to compile, or your contract call transactions failing prior to execution. +The Clarity language makes use of a strong static [type system](/references/language-clarity#clarity-type-system). This simply means that every function defined in Clarity expects arguments of specific types, and that a failure to provide properly typed arguments will result in your code failing to compile, or your contract call transactions failing prior to execution. In order to build web applications that interact with Clarity contracts, you will need to learn how to construct and use `ClarityValue` objects. The [@stacks/transactions](https://github.com/blockstack/stacks.js/tree/master/packages/transactions) library makes this easy, as we will demonstrate below. ## Clarity Types -Values in Clarity can have the following types: +Please see the following page for information on Clarity Types: -- `(tuple (key-name-0 key-type-0) (key-name-1 key-type-1) ...)` - a typed tuple with named fields. -- `(list max-len entry-type)` - a list of maximum length max-len, with entries of type entry-type -- `(response ok-type err-type)` - object used by public functions to commit their changes or abort. May be returned or used by other functions as well, however, only public functions have the commit/abort behavior. -- `(optional some-type)` - an option type for objects that can either be (some value) or none -- `(buff max-len)` - byte buffer or maximum length max-len. -- `(string-ascii max-len)` - ASCII string of maximum length max-len -- `(string-utf8 max-len)` - UTF-8 string of maximum length max-len -- `principal` - object representing a principal (whether a contract principal or standard principal). -- `bool` - boolean value (true or false) -- `int` - signed 128-bit integer -- `uint` - unsigned 128-bit integer +[@page-reference | inline] +| /references/language-types ## Constructing Clarity Values and accessing their data @@ -225,7 +216,7 @@ A Clarity lists underlying data can be accessed via its `list` field. Now that you know how to construct _and_ deconstruct Clarity values, you can use them to build `contract-call` transactions that call smart contract functions, and you can utilize their responses. -This is covered in depth [here](https://docs.blockstack.org/stacks-blockchain/transactions#construction). +This is covered in depth [here](/understand-stacks/transactions#construction). ## Utilizing Clarity Values from Transaction Responses