From 5b6b0bdf2afdb3869ca170ea4c3bde80aeb8a838 Mon Sep 17 00:00:00 2001 From: Alexander Graebe Date: Tue, 15 Dec 2020 08:30:05 -0800 Subject: [PATCH] docs: fixing style errors, first part --- src/pages/404.md | 2 +- src/pages/authentication/building-todo-app.md | 6 +++--- src/pages/authentication/overview.md | 2 +- src/pages/build-apps.md | 3 +-- src/pages/data-storage/indexing-models.md | 4 ++-- src/pages/data-storage/indexing-overview.md | 2 +- src/pages/data-storage/overview.md | 2 +- src/pages/data-storage/storage-guide.md | 4 ++-- src/pages/ecosystem/address-confirmation.md | 2 +- src/pages/ecosystem/contributing.md | 20 +++++++++---------- src/pages/references/deploy-tips.md | 2 +- .../references/stacks-node-configuration.md | 2 +- src/pages/start-mining.md | 17 ++++++++-------- src/pages/storage-hubs/amazon-ec2-deploy.md | 2 +- .../storage-hubs/digital-ocean-deploy.md | 2 +- src/pages/storage-hubs/gaia-admin.md | 6 +++--- src/pages/technology/naming-system.md | 12 +++++------ .../understand-stacks/atlas-how-it-works.md | 8 ++++---- src/pages/understand-stacks/atlas-overview.md | 2 +- src/pages/understand-stacks/best-practices.md | 8 ++++---- .../understand-stacks/local-development.md | 6 ++---- src/pages/understand-stacks/mining.md | 6 +++--- src/pages/understand-stacks/overview.md | 2 +- .../understand-stacks/proof-of-transfer.md | 2 +- .../understand-stacks/running-testnet-node.md | 6 +++--- src/pages/understand-stacks/stacking.md | 2 +- .../understand-stacks/technical-specs.md | 6 +++--- src/pages/understand-stacks/testnet.md | 2 +- src/pages/understand-stacks/transactions.md | 6 +++--- src/pages/understand-stacks/wire-format.md | 12 +++++------ .../write-smart-contracts/counter-tutorial.md | 14 ++++++------- .../hello-world-tutorial.md | 4 ++-- src/pages/write-smart-contracts/overview.md | 6 +++--- src/pages/write-smart-contracts/principals.md | 10 +++++----- .../public-registry-tutorial.md | 8 ++++---- .../signing-transactions.md | 8 ++++---- .../testing-contracts.md | 4 ++-- 37 files changed, 104 insertions(+), 108 deletions(-) diff --git a/src/pages/404.md b/src/pages/404.md index f32d15b4..ba14925c 100644 --- a/src/pages/404.md +++ b/src/pages/404.md @@ -3,7 +3,7 @@ title: Page not found description: The page you're looking for isn't here. --- -## Whoops! +## Whoops Looks like the page you are looking for isn't here. [Head back home](/) or try out some of these popular pages: diff --git a/src/pages/authentication/building-todo-app.md b/src/pages/authentication/building-todo-app.md index 557b2734..48f7dda7 100644 --- a/src/pages/authentication/building-todo-app.md +++ b/src/pages/authentication/building-todo-app.md @@ -51,7 +51,7 @@ npm run start You should see output similar to the following: ```bash -Compiled successfully! +Compiled successfully You can now view todos in the browser. @@ -177,12 +177,12 @@ It is registered on the Stacks blockchain with [BNS](/technology/naming-system) !["Choose username" screen](/images/todos/choose-username.png) -### Done: You've now completed onboarding into the app! +### Done: You've now completed onboarding into the app ## Add, edit and delete todos privately Once you've authenticated the app, you can can start adding todos by entering values into the "Write your to do" -field and hitting "Enter". +field and hitting "Enter." !["Todos" app home screen](/images/todos/home.png) diff --git a/src/pages/authentication/overview.md b/src/pages/authentication/overview.md index ef3460e4..842b5de5 100644 --- a/src/pages/authentication/overview.md +++ b/src/pages/authentication/overview.md @@ -8,7 +8,7 @@ images: ## Authentication flow -For an application developer, the application flow is similar to the typical client-server flow used by centralized sign in services (e.g., OAuth). However, with Stacks auth, the authentication flow happens entirely client-side. +For an application developer, the application flow is similar to the typical client-server flow used by centralized sign in services (for example, OAuth). However, with Stacks auth, the authentication flow happens entirely client-side. A decentralized application and [the Blockstack App](https://github.com/blockstack/ux/tree/master/packages/app) communicate during the authentication flow by passing back and forth two tokens. The requesting application sends the Blockstack App an `authRequest` token. Once a user approves a sign-in, the Blockstack App responds to the application with an `authResponse` token. These tokens are JSON Web Tokens, and they are passed via URL query strings. diff --git a/src/pages/build-apps.md b/src/pages/build-apps.md index fa3e082b..877d066d 100644 --- a/src/pages/build-apps.md +++ b/src/pages/build-apps.md @@ -49,8 +49,7 @@ Get started with the documentation and tutorials below. ### Authentication and data storage -Like a regular app, yours will require user authentication and data storage — but decentralized. Get started with the -documentation below or try the tutorial. +Like a regular app, yours will require user authentication and data storage, but decentralized. Get started with the documentation below or try the tutorial. [@page-reference | inline] | /authentication/overview diff --git a/src/pages/data-storage/indexing-models.md b/src/pages/data-storage/indexing-models.md index 1c961de5..6953eb68 100644 --- a/src/pages/data-storage/indexing-models.md +++ b/src/pages/data-storage/indexing-models.md @@ -109,7 +109,7 @@ class Person extends Model { isHuman: Boolean, likesDogs: { type: Boolean, - decrypted: true, // all users will know if this record likes dogs! + decrypted: true, // all users will know if this record likes dogs }, }; @@ -166,7 +166,7 @@ To create an instance, pass some attributes to the constructor of that class: const person = new Person({ name: 'Hank', isHuman: false, - likesDogs: false, // just an example, I love dogs! + likesDogs: false, // just an example, I love dogs }); ``` diff --git a/src/pages/data-storage/indexing-overview.md b/src/pages/data-storage/indexing-overview.md index db48bb16..2c09129f 100644 --- a/src/pages/data-storage/indexing-overview.md +++ b/src/pages/data-storage/indexing-overview.md @@ -69,7 +69,7 @@ currently active key related to an organization. ## Is Radiks decentralized -Although Radiks applications rely on a centrally-hosted database, an application using Radiks remains fundamentally +Although Radiks applications rely on a centrally hosted database, an application using Radiks remains fundamentally decentralized. A DApp that uses Radiks has these characteristics. ### Built on decentralized authentication diff --git a/src/pages/data-storage/overview.md b/src/pages/data-storage/overview.md index bd02396c..33bf26ec 100644 --- a/src/pages/data-storage/overview.md +++ b/src/pages/data-storage/overview.md @@ -50,7 +50,7 @@ The control of user data lies in the way that user data is accessed. When an app 2. Read her profile URL from her `zonefile`. 3. Fetch Alice's profile. 4. _Verify_ that the profile is signed by `alice.id`'s key -5. Read the `gaiaHubUrl` (e.g. `https://gaia.alice.org/`) out of the profile +5. Read the `gaiaHubUrl` (for example `https://gaia.alice.org/`) out of the profile 6. Fetch the file from `https://gaia.alice.org/data.txt`. Because `alice.id` has access to her zonefile, she can change where her profile is stored. For example, she may do this if the current profile's service provider or storage is compromised. To change where her profile is stored, she changes her Gaia hub URL to another Gaia hub URL. If a user has sufficient compute and storage resources, a user may run their own Gaia Storage System and bypass a commercial Gaia hub provider all together. diff --git a/src/pages/data-storage/storage-guide.md b/src/pages/data-storage/storage-guide.md index e62a7fb2..47e0bfa1 100644 --- a/src/pages/data-storage/storage-guide.md +++ b/src/pages/data-storage/storage-guide.md @@ -26,7 +26,7 @@ const options: PutFileOptions = { encrypt: false, }; userSession.putFile('hello.txt', 'hello world!', options).then(() => { - // hello.txt exists now, and has the contents "hello world!". + // hello.txt exists now, and has the contents "hello world!." }); ``` @@ -43,7 +43,7 @@ const options: PutFileOptions = { }; userSession.putFile('message.txt', 'Secret hello!', options).then(() => { - // message.txt exists now, and has the contents "hello world!". + // message.txt exists now, and has the contents "hello world!." }); ``` diff --git a/src/pages/ecosystem/address-confirmation.md b/src/pages/ecosystem/address-confirmation.md index f0ae7b6c..22201e83 100644 --- a/src/pages/ecosystem/address-confirmation.md +++ b/src/pages/ecosystem/address-confirmation.md @@ -18,4 +18,4 @@ Make sure to store your hardware wallet's seed phrase (sometimes referred to as ## For Multi-Sig Wallets: If you used a multi-signature wallet (for advanced users), you will need to re-enter your public keys to check your address (by clicking “Create Multi-signature Wallet”). -The order that you enter the public keys into the multi-sig wallet is important! If you do not remember the order in which you entered your public keys, please contact hello@StacksToken.com. +The order that you enter the public keys into the multi-sig wallet is important. If you do not remember the order in which you entered your public keys, please contact hello@StacksToken.com. diff --git a/src/pages/ecosystem/contributing.md b/src/pages/ecosystem/contributing.md index b507dd12..bfc3e0d4 100644 --- a/src/pages/ecosystem/contributing.md +++ b/src/pages/ecosystem/contributing.md @@ -5,7 +5,7 @@ description: Learn how this site is built, and how you could contribute to it. ## Introduction -Welcome! Thank you for your interest in contributing and helping make these docs as good as they can be! This page will +Welcome. Thank you for your interest in contributing and helping make these docs as good as they can be. This page will outline how this site is built, its general structure, getting it running locally, and some helpful tips for using all of its features. ## Next.js, MDX, Markdown @@ -13,7 +13,7 @@ outline how this site is built, its general structure, getting it running locall This docs site is built with [Next.js](https://github.com/vercel/next.js) and uses something called [MDX](https://mdxjs.com/). Next.js is a framework built on top of React, and MDX is a tool that enables writing React code (JSX) within standard Markdown files. In addition to being able to write JSX in Markdown, it allows the application to render out all of the -Markdown content with React components! This means that we are able to do some pretty complex things while a +Markdown content with React components. This means that we are able to do some pretty complex things while a contributor only has to know how to write Markdown. -> **Don't know what Markdown is?** Here is a [helpful guide](https://guides.github.com/features/mastering-markdown/) for learning it. @@ -46,8 +46,8 @@ When workin locally with the site, a few things are needed: All of the code for this site is open source, located at the [GitHub repository here](https://github.com/blockstack/docs). Before you start editing anything, you will need to fork the repo so that you can have your own copy of the code under -your GitHub profile. On the [repository's page](https://github.com/blockstack/docs), you should be able to -see a button in the upper right of the screen that says "Fork". [You can read about Forking here.](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) +your GitHub profile. On the [repository's page](https://github.com/blockstack/docs.blockstack), you should be able to +see a button in the upper right of the screen that says "Fork." [You can read about Forking here.](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) This is a generalized workflow for contributing to these docs: @@ -72,7 +72,7 @@ yarn run v1.22.4 yarn clean:build-files && next dev rimraf .next ready - started server on http://localhost:3000 -warn - You have enabled experimental feature(s). +warn - You have enabled experimental features. warn - Experimental features are not covered by semver, and may cause unexpected or broken application behavior. Use them at your own risk. info - Using external babel configuration from /Users/YOUR_USERNAME/oss/docs.blockstack/babel.config.js @@ -230,7 +230,7 @@ Which will render: (define-public (test-emit-event) (begin - (print "Event! Hello world") + (print "Event. Hello world") (ok u1))) (begin (test-emit-event)) @@ -265,9 +265,9 @@ We use another remark plugin to generate certain kinds of alerts inline in our d => This will be a success style alert. -~> This will be a warning style alert! +~> This will be a warning style alert -!> This will be a danger style alert!!! +!> This will be a danger style alert ``` Which renders: @@ -278,6 +278,6 @@ Which renders: => This will be a success style alert. -~> This will be a warning style alert! +~> This will be a warning style alert -!> This will be a danger style alert!!! +!> This will be a danger style alert diff --git a/src/pages/references/deploy-tips.md b/src/pages/references/deploy-tips.md index 458ed707..2eb92e64 100644 --- a/src/pages/references/deploy-tips.md +++ b/src/pages/references/deploy-tips.md @@ -36,7 +36,7 @@ Regardless of which scaffolding you use, you must customize and extend this basi When your application authenticates users with Stacks, your DApp at one URL requests a resource (an identity) from another DApp, the Blockstack Browser. A request for a resource outside of the origin (your new website) is called as a _cross-origin request_(CORs). Getting data in this manner can be risky, so you must configure your website security to allow interactions across origins. -You can think of CORS interactions as an apartment building with Security. For example, if you need to borrow a ladder, you could ask a neighbor in your building who has one. Security would likely not have a problem with this request (i.e., same-origin, your building). If you needed a particular tool, however, and you ordered it delivered from an online hardware store (i.e., cross-origin, another site), Security may request identification before allowing the delivery man into the apartment building. (Credit: [Codecademy](https://www.codecademy.com/articles/what-is-cors)) +You can think of CORS interactions as an apartment building with Security. For example, if you need to borrow a ladder, you could ask a neighbor in your building who has one. Security would likely not have a problem with this request (that is, same-origin, your building). If you needed a particular tool, however, and you ordered it delivered from an online hardware store (that is, cross-origin, another site), Security may request identification before allowing the delivery man into the apartment building. (Credit: [Codecademy](https://www.codecademy.com/articles/what-is-cors)) The way you configure CORs depends on which company you use to host your web application. The application generator adds a `cors` directory to your application scaffolding. This directory contains files for Netlify (`_headers` and `_redirects`) as well as one for Firebase (`firebase.json`). The configurations in the `cors` directory make your application's `manifest.json` file accessible to other applications (for example, to the Blockstack Browser). If you are deploying to a service other than Netlify or Firebase, you must configure CORS on that service to include the following headers when serving `manifest.json`: diff --git a/src/pages/references/stacks-node-configuration.md b/src/pages/references/stacks-node-configuration.md index 8f43bdee..f7ba9bc3 100644 --- a/src/pages/references/stacks-node-configuration.md +++ b/src/pages/references/stacks-node-configuration.md @@ -100,7 +100,7 @@ Example: rpc_bind = "0.0.0.0:20443" p2p_bind = "0.0.0.0:20444" bootstrap_node = "048dd4f26101715853533dee005f0915375854fd5be73405f679c1917a5d4d16aaaf3c4c0d7a9c132a36b8c5fe1287f07dad8c910174d789eb24bdfb5ae26f5f27@testnet-miner.blockstack.org:20444" -# Enter your private key here! +# Enter your private key here seed = "replace-with-your-private-key" miner = true ``` diff --git a/src/pages/start-mining.md b/src/pages/start-mining.md index c880f02a..ab432460 100644 --- a/src/pages/start-mining.md +++ b/src/pages/start-mining.md @@ -98,8 +98,8 @@ Paste in the following configuration: [node] rpc_bind = "0.0.0.0:20443" p2p_bind = "0.0.0.0:20444" -bootstrap_node = "047435c194e9b01b3d7f7a2802d6684a3af68d05bbf4ec8f17021980d777691f1d51651f7f1d566532c804da506c117bbf79ad62eea81213ba58f8808b4d9504ad@xenon.blockstack.org:20444" -# Enter your private key here! +bootstrap_node = "048dd4f26101715853533dee005f0915375854fd5be73405f679c1917a5d4d16aaaf3c4c0d7a9c132a36b8c5fe1287f07dad8c910174d789eb24bdfb5ae26f5f27@testnet-miner.blockstack.org:20444" +# Enter your private key here seed = "replace-with-your-private-key" miner = true @@ -138,7 +138,7 @@ To run your miner, run this in the command line: stacks-node start --config=./testnet/stacks-node/conf/testnet-miner-conf.toml ``` -Your node should start. It will take some time to sync, and then your miner will be running! +Your node should start. It will take some time to sync, and then your miner will be running. ### Creating an optimized binary @@ -224,8 +224,8 @@ Paste in the following configuration: [node] rpc_bind = "0.0.0.0:20443" p2p_bind = "0.0.0.0:20444" -bootstrap_node = "047435c194e9b01b3d7f7a2802d6684a3af68d05bbf4ec8f17021980d777691f1d51651f7f1d566532c804da506c117bbf79ad62eea81213ba58f8808b4d9504ad@xenon.blockstack.org:20444" -# Enter your private key here! +bootstrap_node = "048dd4f26101715853533dee005f0915375854fd5be73405f679c1917a5d4d16aaaf3c4c0d7a9c132a36b8c5fe1287f07dad8c910174d789eb24bdfb5ae26f5f27@testnet-miner.blockstack.org:20444" +# Enter your private key here seed = "replace-with-your-private-key" miner = true @@ -269,7 +269,7 @@ stacks-node start --config=testnet-miner-conf.toml -> **Note** : While starting the node for the first time, windows defender might pop up with a message to allow access. If so, allow access to run the node. ![Windows Defender](/images/windows-defender.png) -Your node should start. It will take some time to sync, and then your miner will be running! +Your node should start. It will take some time to sync, and then your miner will be running. ### Enable debug logging in Windows @@ -299,7 +299,7 @@ We need to get some testnet BTC to that address. Grab the `btcAddress` field, an ### Create a config file directory -You need a dedicated directory to keep the config file(s): +You need a dedicated directory to keep the config files: ```bash mkdir -p $HOME/stacks @@ -314,8 +314,7 @@ Inside the new `$HOME/stacks` folder, you should create a new miner config `Conf working_dir = "/root/stacks-node/current" rpc_bind = "0.0.0.0:20443" p2p_bind = "0.0.0.0:20444" -bootstrap_node = "047435c194e9b01b3d7f7a2802d6684a3af68d05bbf4ec8f17021980d777691f1d51651f7f1d566532c804da506c117bbf79ad62eea81213ba58f8808b4d9504ad@xenon.blockstack.org:20444" -# Enter your private key here! +# Enter your private key here seed = "replace-with-your-privateKey-from-generate-keychain-step" miner = true diff --git a/src/pages/storage-hubs/amazon-ec2-deploy.md b/src/pages/storage-hubs/amazon-ec2-deploy.md index 51b1ece6..07b25ec3 100644 --- a/src/pages/storage-hubs/amazon-ec2-deploy.md +++ b/src/pages/storage-hubs/amazon-ec2-deploy.md @@ -308,7 +308,7 @@ Everything is fine, continue to the next step, step 8. 9) Choose to proceed. 10) Extend the IP with the `PUBLIC_IP/hub_info` tag like so. - You should see a response from your Gaia hub! + You should see a response from your Gaia hub. ![Hub test](/images/aws-hub.png) diff --git a/src/pages/storage-hubs/digital-ocean-deploy.md b/src/pages/storage-hubs/digital-ocean-deploy.md index 7089fead..5f53af23 100644 --- a/src/pages/storage-hubs/digital-ocean-deploy.md +++ b/src/pages/storage-hubs/digital-ocean-deploy.md @@ -540,7 +540,7 @@ Now, you are ready to test your Gaia server and make sure it is up and running. 3. Copy the IP address for it. 4. In your browser, visit the page `MY_DROPLET_IP/hub_info`. - You should see a response from your Gaia hub! + You should see a response from your Gaia hub. ![Hub test](/images/hub-running.png) diff --git a/src/pages/storage-hubs/gaia-admin.md b/src/pages/storage-hubs/gaia-admin.md index c9803c51..2849a48e 100644 --- a/src/pages/storage-hubs/gaia-admin.md +++ b/src/pages/storage-hubs/gaia-admin.md @@ -18,8 +18,8 @@ The admin service relies on two configuration files, the hub's configuration and The admin service needs to know the following: - where the Gaia hub config file is located -- which API key(s) to use when authenticating administrative requests -- which command(s) to run to restart the Gaia hub on a config change +- which API keys to use when authenticating administrative requests +- which commands to run to restart the Gaia hub on a config change The following is the standard admin service config installed with your EC2 instance. @@ -429,7 +429,7 @@ The following JSON schema details the possible parameters for a hub configuratio }, "maxFileUploadSize": { "default": 20, - "description": "The maximum allowed POST body size in megabytes. \nThe content-size header is checked, and the POST body stream \nis monitoring while streaming from the client. \n[Recommended] Minimum 100KB (or approximately 0.1MB)", + "description": "The maximum allowed POST body size in megabytes. \nThe content-size header is checked, and the POST body stream \nis monitoring while streaming from the client. \n[Recommended] Minimum 100KB (or approximately 0.1 MB)", "minimum": 0.1, "type": "number" }, diff --git a/src/pages/technology/naming-system.md b/src/pages/technology/naming-system.md index 0a41979d..35610a97 100644 --- a/src/pages/technology/naming-system.md +++ b/src/pages/technology/naming-system.md @@ -148,7 +148,7 @@ forever. However, creating a namespace is not free. The namespace creator must _burn_ cryptocurrency to do so. The shorter the namespace, the more cryptocurrency -must be burned (i.e. short namespaces are more valuable than long namespaces). +must be burned (that is, short namespaces are more valuable than long namespaces). For example, it cost Blockstack PBC 40 BTC to create the `.id` namespace in 2015 (in transaction `5f00b8e609821edd6f3369ee4ee86e03ea34b890e242236cdb66ef6c9c6a1b281`). @@ -258,9 +258,9 @@ includes both the public key and signature, and the public key must hash to the previous subdomain operation's "addr=" field. The subdomain-creation and subdomain-transfer transactions for -"cicero.res_publica.id" are broadcast by the owner of "res_publica.id". +"cicero.res_publica.id" are broadcast by the owner of "res_publica.id." However, any on-chain name ("jude.id" in this case) can broadcast a subdomain -update for "cicero.res_publica.id". +update for "cicero.res_publica.id." ``` Subdomain operations are ordered by sequence number, starting at 0. Each new @@ -272,7 +272,7 @@ subdomain operation must include: operation. If two correctly-signed but conflicting subdomain operations are discovered -(i.e. they have the same sequence number), the one that occurs earlier in the +(that is, they have the same sequence number), the one that occurs earlier in the blockchain's history is accepted. Invalid subdomain operations are ignored. Combined, this ensures that a BNS node with all of the zone files with a given @@ -344,7 +344,7 @@ Each name in BNS has an associated DID. The DID format for BNS is: Where: -- `{address}` is an on-chain public key hash (e.g. a Bitcoin address). +- `{address}` is an on-chain public key hash (for example a Bitcoin address). - `{index}` refers to the `nth` name this address created. For example, the DID for `personal.id` is @@ -384,7 +384,7 @@ for subdomains, so the software can determine which code-path to take. - For on-chain BNS names, the `{address}` is the same as the Bitcoin address that owns the name. Currently, both version byte 0 and version byte 5 - addresses are supported (i.e. addresses starting with `1` or `3`, meaning `p2pkh` and + addresses are supported (that is, addresses starting with `1` or `3`, meaning `p2pkh` and `p2sh` addresses). - For off-chain BNS subdomains, the `{address}` has version byte 63 for diff --git a/src/pages/understand-stacks/atlas-how-it-works.md b/src/pages/understand-stacks/atlas-how-it-works.md index 89d1c453..46bdc3a4 100644 --- a/src/pages/understand-stacks/atlas-how-it-works.md +++ b/src/pages/understand-stacks/atlas-how-it-works.md @@ -30,7 +30,7 @@ will remain online for long periods of time. The sampling algorithm accounts for this with the following tweaks: - If the neighbors of the visited node _N_ are all unresponsive, the random - walk resets to a randomly-chosen known neighbor. There is no back-tracking on + walk resets to a randomly chosen known neighbor. There is no back-tracking on the peer graph in this case. - The transition probability from _N_ to a live neighbor is _NOT_ `min(1, degree(neighbor)/degree(N))` like it is in the vanilla MH algorithm. Instead, @@ -41,7 +41,7 @@ for this with the following tweaks: but only reports a random subset of peers that have met a minimum health threshold. - A new neighbor is only selected if it belongs to the same [BNS - fork-set](/naming-services/overview#bns-forks) (i.e. it reports + fork-set](/naming-services/overview#bns-forks) (for example, it reports as having a recent valid consensus hash). The algorithm was adapted from the work from [Lee, Xu, and @@ -64,7 +64,7 @@ It can do so at any point in time after the chunk was first stored, because only the peers who maintain the chunk's hash bucket have to store it. This is a _fundamental_ problem with structured overlay networks that perform request routing based on content hash---they give the attacker -insight as to the path(s) the queries take through the peer graph, and thus +insight as to the paths the queries take through the peer graph, and thus reduce the number of paths the attacker must disrupt in order to censor the chunk. @@ -89,7 +89,7 @@ contacts a given DHT node has an equal chance of becoming its neighbor. The node will instead rank a set of peers as being more or less ideal for being neighbors. In DHTs, the degree of preference a node exhibits to another node is usually a function of the node's self-given node identifier -(e.g. a node might want to select neighbors based on proximity in the key +(for example a node might want to select neighbors based on proximity in the key space). The preferential attachment property means that an adaptive adversary can game the node's diff --git a/src/pages/understand-stacks/atlas-overview.md b/src/pages/understand-stacks/atlas-overview.md index 6cc65c7f..c2ee1a57 100644 --- a/src/pages/understand-stacks/atlas-overview.md +++ b/src/pages/understand-stacks/atlas-overview.md @@ -21,7 +21,7 @@ to familiarize themselves with both systems before approaching this document. Atlas is designed to integrate with BNS in order to allow users to store name state off-chain, encoded as a DNS zone file. -The overwhelmingly-common use-cases in Stacks are: +The common use-cases in Stacks are: - Storing a name's routing information for its owners' [Gaia](https://github.com/blockstack/gaia) datastores. diff --git a/src/pages/understand-stacks/best-practices.md b/src/pages/understand-stacks/best-practices.md index 3f06cc68..2c02f5e0 100644 --- a/src/pages/understand-stacks/best-practices.md +++ b/src/pages/understand-stacks/best-practices.md @@ -6,7 +6,7 @@ description: Helpful tips for getting a core node up and running. ## Hardware and OS requirements - A 64-bit CPU running at at least 1 GHz is _highly_ recommended (but not strictly required) -- You will need ~250MB RAM and ~10 GB disk free. Do **not** attempt to use a network-attached disk for this. +- You will need ~250 MB RAM and ~10 GB disk free. Do **not** attempt to use a network-attached disk for this. - You should have at least 30,000 inodes free in your filesystem. Unless you are using a very small VM image, you almost certainly have enough (you can check with `df -i`). - TCP port 6264 should be open and support bidirectional traffic. If you want to use SSL, then port 6263 should be open. - A reliable Internet connection of DSL-like quality or higher @@ -27,7 +27,7 @@ description: Helpful tips for getting a core node up and running. #### Best Practices for the Less Easy Way -- Take a `blockstack-server.snapshots` database from a known-good node and pass `--expected_snapshots=/path/to/blockstack-server.snapshots`. This will force your bootstrapping node to verify that it reaches the same sequence of consensus hashes as it bootstraps (i.e. your node will detect any divergence from Blockstack's name history and abort early, instead of wasting your time). +- Take a `blockstack-server.snapshots` database from a known-good node and pass `--expected_snapshots=/path/to/blockstack-server.snapshots`. This will force your bootstrapping node to verify that it reaches the same sequence of consensus hashes as it bootstraps (that is, your node will detect any divergence from Blockstack's name history and abort early, instead of wasting your time). - Make sure you're in a position to leave the node online at 100% CPU use for the duration of its bootstrapping period ### The Hard Way @@ -55,8 +55,8 @@ description: Helpful tips for getting a core node up and running. ### No other Stacks nodes contact my node -- Verify that your IP address is publicly-routable, and that peers can communicate on TCP:6264 +- Verify that your IP address is publicly routable, and that peers can communicate on TCP:6264 ### People are attacking my Bitcoin node -- Stick an `nginx` reverse proxy in front of your `bitcoind` node, and use our [nginx](https://github.com/blockstack/atlas/tree/master/public_fleet/bitcoind) scripts to limit API access to only the JSON-RPC methods Stacks actually needs. Better yet, do what we do---build a statically-linked `bitcoind` binary from source that simply omits all of the RPC methods except the ones listed in the linked config file. +- Stick an `nginx` reverse proxy in front of your `bitcoind` node, and use our [nginx](https://github.com/blockstack/atlas/tree/master/public_fleet/bitcoind) scripts to limit API access to only the JSON-RPC methods Stacks actually needs. Better yet, do what we do---build a statically linked `bitcoind` binary from source that simply omits all of the RPC methods except the ones listed in the linked config file. diff --git a/src/pages/understand-stacks/local-development.md b/src/pages/understand-stacks/local-development.md index 13a96eaa..bb7ac1d8 100644 --- a/src/pages/understand-stacks/local-development.md +++ b/src/pages/understand-stacks/local-development.md @@ -174,9 +174,7 @@ explorer: - api ``` -To disable this service, simply comment the section with `#` - -i.e. +To disable this service, simply comment the section with `#`. For example: ```yaml # explorer: @@ -291,7 +289,7 @@ export PGPASSWORD='postgres' && psql --host localhost -p 5432 -U postgres -d sta If you have a port conflict, typically this means you already have a process using that same port. -To resolve, find the port you have in use (i.e. `5432` and edit the [`.env`](https://github.com/blockstack/stacks-local-dev/blob/master/.env) file to use the new port) +To resolve, find the port you have in use (for example, `5432` and edit the [`.env`](https://github.com/blockstack/stacks-local-dev/blob/master/.env) file to use the new port) ```bash netstat -anl | grep 5432 diff --git a/src/pages/understand-stacks/mining.md b/src/pages/understand-stacks/mining.md index a72d3a55..578246e1 100644 --- a/src/pages/understand-stacks/mining.md +++ b/src/pages/understand-stacks/mining.md @@ -38,7 +38,7 @@ For transactions mined in microblocks, the miner that produces the microblock re ## Reward maturity -Miner rewards, i.e. block rewards and transaction fees take 100 blocks on the bitcon blockchain to mature. After successful mining a block your rewards will appear in the Stacks account after ~24 hours. +Miner rewards, that is, block rewards and transaction fees take 100 blocks on the bitcon blockchain to mature. After successful mining a block your rewards will appear in the Stacks account after ~24 hours. ## Mining with Proof-of-Transfer @@ -46,13 +46,13 @@ Miners commit Bitcoin to **two** addresses in every leader block commit. The amo ![mining with pox](/images/pages/mining-with-pox.png) -100,000 Bitcoin blocks **after** mining begins, the PoX sunset phase begins. During this phase, an increasing proportion of the block commit must be burnt. To burn this sunset fee, the miner must send the sunset fee amount to the first output of their block commit transaction (i.e., the OPRETURN output). +100,000 Bitcoin blocks **after** mining begins, the PoX sunset phase begins. During this phase, an increasing proportion of the block commit must be burnt. To burn this sunset fee, the miner must send the sunset fee amount to the first output of their block commit transaction (that is, the OPRETURN output). 400,000 Bitcoin blocks after the sunset phase begins, the sunset phase ends. After this point, PoX is no longer active, and miners must burn all of their leader block commits. They do so by sending Bitcoin to the canonical burn address `1111111111111111111114oLvT2`. ## Probability to mine next block -The miner who is selected to mine the next block is chosen depending on the amount of BTC the miners sent, i.e. transferred or burnt. +The miner who is selected to mine the next block is chosen depending on the amount of BTC the miners sent, that is, transferred or burnt. The probability for a miner to mine the next block equals the BTC the miner sent divided by the total BTC all miners sent. diff --git a/src/pages/understand-stacks/overview.md b/src/pages/understand-stacks/overview.md index df963304..6f01b49b 100644 --- a/src/pages/understand-stacks/overview.md +++ b/src/pages/understand-stacks/overview.md @@ -14,7 +14,7 @@ Smart contracts and apps developed on the Stacks platform are natively integrate ### Status -The Stacks 2.0 blockchain is in active development. While the final release ("mainnet") is in the works, you can get familiar with its features on the "testnet". +The Stacks 2.0 blockchain is in active development. While the final release ("mainnet") is in the works, you can get familiar with its features on the "testnet." [@page-reference | inline] | /understand-stacks/testnet diff --git a/src/pages/understand-stacks/proof-of-transfer.md b/src/pages/understand-stacks/proof-of-transfer.md index c7bfd39f..63a033f7 100644 --- a/src/pages/understand-stacks/proof-of-transfer.md +++ b/src/pages/understand-stacks/proof-of-transfer.md @@ -15,7 +15,7 @@ Mining mechanisms used by these algorithms are broadly divided into proof-of-wor 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. -Proof-of-transfer (PoX) is a new mining mechanism, that generalizes the concept of proof-of-burn. PoX uses the proof-of-work cryptocurrency of an established blockchain to secure a new blockchain. However, unlike proof-of-burn rather than burning the cryptocurrency, miners transfer the committed cryptocurrency to some other participant(s) in the network. +Proof-of-transfer (PoX) is a new mining mechanism, that generalizes the concept of proof-of-burn. PoX uses the proof-of-work cryptocurrency of an established blockchain to secure a new blockchain. However, unlike proof-of-burn rather than burning the cryptocurrency, miners transfer the committed cryptocurrency to some other participants in the network. This allows network participants who are adding value to the new cryptocurrency network to earn a reward in a base cryptocurrency by actively participating in the consensus algorithm, PoX encourages a model where there is one extremely secure proof-of-work blockchain, say Bitcoin. diff --git a/src/pages/understand-stacks/running-testnet-node.md b/src/pages/understand-stacks/running-testnet-node.md index aed47e35..cfc5ac4c 100644 --- a/src/pages/understand-stacks/running-testnet-node.md +++ b/src/pages/understand-stacks/running-testnet-node.md @@ -109,7 +109,7 @@ The first time you run this, you'll see some logs indicating that the Rust code INFO [1588108047.585] [src/chainstate/stacks/index/marf.rs:732] First-ever block 0f9188f13cb7b2c71f2a335e3a4fc328bf5beb436012afca590b1a11466e2206 ``` -**Awesome! Your node is now connected to the testnet network.** +**Awesome. Your node is now connected to the testnet network.** Your node will receive new blocks when they are produced, and you can use the [Stacks Node RPC API](/references/stacks-blockchain-api#stacks-node-rpc-api) to send transactions, fetch information for contracts and accounts, and more. @@ -136,7 +136,7 @@ Before you begin, check that you have the below necessary softwares installed on -> **Note**: Please make sure to download the new Binary and follow the below steps as and when a [new release build](https://github.com/blockstack/stacks-blockchain/releases/latest) is available. -First, Visit the [Stacks Github releases repo](https://github.com/blockstack/stacks-blockchain/releases/latest). From the various binary list, click to download the Windows binary.Refer the image below. +First, Visit the [Stacks Github releases repo](https://github.com/blockstack/stacks-blockchain/releases/latest). From the various binary list, click to download the Windows binary. Refer the image below. ![BinaryList](/images/mining-windows.png) Next, click on save file and Press **Ok** in the popup window. @@ -167,7 +167,7 @@ The first time you run this, you'll see some logs indicating that the Rust code INFO [1588108047.585] [src/chainstate/stacks/index/marf.rs:732] First-ever block 0f9188f13cb7b2c71f2a335e3a4fc328bf5beb436012afca590b1a11466e2206 ``` -**Awesome! Your node is now connected to the testnet network.** +**Awesome. Your node is now connected to the testnet network.** ## Optional: Running with Docker diff --git a/src/pages/understand-stacks/stacking.md b/src/pages/understand-stacks/stacking.md index ab5d8a85..1d62b4ce 100644 --- a/src/pages/understand-stacks/stacking.md +++ b/src/pages/understand-stacks/stacking.md @@ -54,7 +54,7 @@ The Stacking flow is different for delegation use cases: PoX mining is a modification of Proof-of-Burn (PoB) mining, where instead of destroying the committed Bitcoin, it is transferred to eligible Stacks (STX) holders that participate in the Stacking protocol. --> A PoX miner can only receive newly-minted Stacks (STX) tokens when they transfer bitcoin to eligible owners of Stacks (STX) tokens +-> A PoX miner can only receive newly minted Stacks (STX) tokens when they transfer bitcoin to eligible owners of Stacks (STX) tokens Miners have to run a software (mining client, aka "miner") on their machines to participate in the PoX mechanism. The mining client implements the PoX mechanism, which ensures proper handling and incentives through four key phases: diff --git a/src/pages/understand-stacks/technical-specs.md b/src/pages/understand-stacks/technical-specs.md index 728179c4..b5d6c1c9 100644 --- a/src/pages/understand-stacks/technical-specs.md +++ b/src/pages/understand-stacks/technical-specs.md @@ -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](/references/stacking-contract#delegate-stx). -- Further reading: [Stacking](/understand-stacks/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](https://docs.blockstack.org/references/stacking-contract#delegate-stx). +- Further reading: [Stacking](/stacks-blockchain/stacking) ## Accounts and Addresses @@ -41,7 +41,7 @@ description: Summary of technical specifications of Stacks 2.0 - Address contains 2 or 3 fields: 1 byte version, 20 byte public key hash (RIPEMD160(SHA256(input))), optional name (variable length, max 128 bytes) - Two types of accounts: standard accounts are owned by one or more private keys; contract accounts are materialized when a smart-contract is instantiated (specified by the optional name field above) - 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. +- Assets are a map of all asset types -- STX, any on-chain assets specified by a Clarity contract (for example 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](/understand-stacks/accounts) diff --git a/src/pages/understand-stacks/testnet.md b/src/pages/understand-stacks/testnet.md index 8af11739..b3b64338 100644 --- a/src/pages/understand-stacks/testnet.md +++ b/src/pages/understand-stacks/testnet.md @@ -12,7 +12,7 @@ The Stacks 2.0 testnet is a separate blockchain, to be used for testing. It is i -> Stacks (STX) tokens on the testnet are different from real tokens on the mainnet. They can be obtained at no cost through the faucet. -With the completion of the Stacks 2.0 blockchain, a production-ready, stable version will be released as "mainnet". While work for the mainnet is in progress, the testnet reflects the most recent implementation of the Stacks 2.0 blockchain. +With the completion of the Stacks 2.0 blockchain, a production-ready, stable version will be released as "mainnet." While work for the mainnet is in progress, the testnet reflects the most recent implementation of the Stacks 2.0 blockchain. ## Release phases diff --git a/src/pages/understand-stacks/transactions.md b/src/pages/understand-stacks/transactions.md index 5c68dfe8..d6168aba 100644 --- a/src/pages/understand-stacks/transactions.md +++ b/src/pages/understand-stacks/transactions.md @@ -27,7 +27,7 @@ Transactions go through phases before being finally confirmed, and available for - **Generate**: Transactions are assembled according to the encoding specification. - **Validate and sign**: Transactions are validated to confirm they are well-formed. Required signatures are filled in. - **Broadcast**: Transactions are sent to a node. -- **Register**: A miner receives transactions, verifies, and adds them to the ["mempool"](https://academy.binance.com/glossary/mempool), a holding area for all the pending transactions. +- **Register**: A miner receives transactions, verifies, and adds them to the ["mempool,"](https://academy.binance.com/glossary/mempool) a holding area for all the pending transactions. - **Process**: Miners review the mempool and select transactions for the next block to be mined. Depending on the transaction type, different actions can happen during this step. For example, post-conditions could be verified for a token transfer, smart-contract defined tokens could be minted, or an attempt to call an existing smart contract method could be made. - **Confirm**: Miners successfully mine blocks with a set of transactions. The transactions inside are successfully propagated to the network. @@ -81,7 +81,7 @@ Transactions can be authorized in two ways: _standard_ and _sponsored_. The auth **Sponsored transactions** enable developers and/or infrastructure operators to pay for users to call into their smart contracts, even if users do not have the Stacks (STX) to do so. -The signing flow for sponsored transactions would be to have the user first sign the transaction with their origin account with the intent of it being sponsored (i.e. the user must explicitly allow a sponsor to sign), and then have the sponsor sign with their paying account to pay for the user's transaction fee. +The signing flow for sponsored transactions would be to have the user first sign the transaction with their origin account with the intent of it being sponsored (that is, the user must explicitly allow a sponsor to sign), and then have the sponsor sign with their paying account to pay for the user's transaction fee. ## Encoding @@ -355,7 +355,7 @@ console.log(deserializedTx.payload.memo.content); ## Signature and Verification -Every transaction contains verifiable signature(s) that certify its authenticity. These signatures are generated by signing the transaction hash with the origin's private key. The Elliptic Curve Digital Signature Algorithm (ECDSA) is used for signing, with the curve set to secp256k1. The internal structure that encapsulates the signature is the spending condition. Spending conditions include several parameters including the public key hash, nonce, fee rate and the recoverable ECDSA signature. +Every transaction contains verifiable signatures that certify its authenticity. These signatures are generated by signing the transaction hash with the origin's private key. The Elliptic Curve Digital Signature Algorithm (ECDSA) is used for signing, with the curve set to secp256k1. The internal structure that encapsulates the signature is the spending condition. Spending conditions include several parameters including the public key hash, nonce, fee rate and the recoverable ECDSA signature. When constructing a transaction using the JS library, you can supply the private key and signing will be completed automatically. If you would like to sign the transaction manually, use the `TransactionSigner` class. diff --git a/src/pages/understand-stacks/wire-format.md b/src/pages/understand-stacks/wire-format.md index c96ccf9c..8598696f 100644 --- a/src/pages/understand-stacks/wire-format.md +++ b/src/pages/understand-stacks/wire-format.md @@ -5,14 +5,14 @@ description: Learn about the format of transactions used for name operations in ## Introduction -This page is for organizations who want to be able to create and send name operation transactions to the blockchain(s) Stacks supports. +This page is for organizations who want to be able to create and send name operation transactions to the blockchains Stacks supports. It describes the transaction formats for the Bitcoin blockchain. ## Transaction format -Each Bitcoin transaction for Stacks contains signatures from two sets of keys: the name owner, and the payer. The owner `scriptSig` and `scriptPubKey` fields are generated from the key(s) that own the given name. The payer `scriptSig` and `scriptPubKey` fields are used to _subsidize_ the operation. The owner keys do not pay for any operations; the owner keys only control the minimum amount of BTC required to make the transaction standard. The payer keys only pay for the transaction's fees, and (when required) they pay the name fee. +Each Bitcoin transaction for Stacks contains signatures from two sets of keys: the name owner, and the payer. The owner `scriptSig` and `scriptPubKey` fields are generated from the keys that own the given name. The payer `scriptSig` and `scriptPubKey` fields are used to _subsidize_ the operation. The owner keys do not pay for any operations; the owner keys only control the minimum amount of BTC required to make the transaction standard. The payer keys only pay for the transaction's fees, and (when required) they pay the name fee. -This construction is meant to allow the payer to be wholly separate from the owner. The principal that owns the name can fund their own transactions, or they can create a signed transaction that carries out the desired operation and request some other principal (e.g. a parent organization) to actually pay for and broadcast the transaction. +This construction is meant to allow the payer to be wholly separate from the owner. The principal that owns the name can fund their own transactions, or they can create a signed transaction that carries out the desired operation and request some other principal (for example a parent organization) to actually pay for and broadcast the transaction. The general transaction layout is as follows: @@ -26,7 +26,7 @@ The general transaction layout is as follows: (1) The owner `scriptSig` is _always_ the first input. (2) The `OP_RETURN` script that describes the name operation is _always_ the first output. (3) The owner `scriptPubKey` is _always_ the second output. -(4) The payer can use as many payment inputs as (s)he likes. +(4) The payer can use as many payment inputs as they like. (5) At most one output will be the "change" `scriptPubKey` for the payer. Different operations require different outputs. @@ -65,7 +65,7 @@ Outputs: Notes: -- `register_addr` is a base58check-encoded `ripemd160(sha256(pubkey))` (i.e. an address). This address **must not** have been used before in the underlying blockchain. +- `register_addr` is a base58check-encoded `ripemd160(sha256(pubkey))` (that is, an address). This address **must not** have been used before in the underlying blockchain. - `script_pubkey` is either a `p2pkh` or `p2sh` compiled Bitcoin script for the payer's address. ### NAME_REGISTRATION @@ -423,7 +423,7 @@ Outputs: Notes: - These transactions can only be sent between the `NAMESPACE_REVEAL` and `NAMESPACE_READY`. -- The first `NAME_IMPORT` transaction **must** have a `scriptSig` input that matches the `NAMESPACE_REVEAL`'s second output (i.e. the reveal output). +- The first `NAME_IMPORT` transaction **must** have a `scriptSig` input that matches the `NAMESPACE_REVEAL`'s second output (that is, the reveal output). - Any subsequent `NAME_IMPORT` transactions **may** have a `scriptSig` input whose public key is one of the first 300 extended public keys from the `NAMESPACE_REVEAL`'s `scriptSig` public key. ### NAMESPACE_READY diff --git a/src/pages/write-smart-contracts/counter-tutorial.md b/src/pages/write-smart-contracts/counter-tutorial.md index dead21bf..446c7ceb 100644 --- a/src/pages/write-smart-contracts/counter-tutorial.md +++ b/src/pages/write-smart-contracts/counter-tutorial.md @@ -75,10 +75,10 @@ counter contract test suite ... # error details -npm ERR! Test failed. See above for more details. +npm ERR. Test failed. See above for more details. ``` -It looks like we see some failed tests! That is on purpose - we will implement the new smart contract in the next steps! After every step in this tutorial, we will rerun the tests to ensure we're on the right track. +It looks like we see some failed tests. That is on purpose - we will implement the new smart contract in the next steps. After every step in this tutorial, we will rerun the tests to ensure we're on the right track. ## Step 3: Developing a smart contract @@ -141,7 +141,7 @@ Let's get familiar with the tests to understand what the new smart contract shou To provide access to the `counter` variable from outside of the current smart contract, we need to declare a public function to get it. The last lines of the code add a public `get-counter` function. The [`var-get`](/references/language-functions#var-get) statement looks for a variable in the contract's data space and returns it. - With that, you are ready to rerun the tests! + With that, you are ready to rerun the tests 3. Run the tests and review the results: @@ -149,7 +149,7 @@ Let's get familiar with the tests to understand what the new smart contract shou npm test ``` - You should now only see 2 failing tests! `should start at zero` is passing, and you successfully build your first part of the contract. Congrats! + You should now only see 2 failing tests. `should start at zero` is passing, and you successfully build your first part of the contract. Congrats. However, we don't stop here. Let's implement increment and decrement functions. @@ -167,7 +167,7 @@ Let's get familiar with the tests to understand what the new smart contract shou Next, a [`var-set`](/references/language-functions#var-set) is used to set a new value for the `counter` variable. The new value is constructed using the [`+`](/references/language-functions#-add) (add) statement. This statement takes a number of integers and returns the result. Along with add, Clarity provides statements to subtract, multiply, and divide integers. Find more details in the [Clarity language reference](/references/language-functions). -5. Next, implement a new public function `decrement` to subtract `1` from the `counter` variable. You should have all knowledge needed to succeed at this! +5. Next, implement a new public function `decrement` to subtract `1` from the `counter` variable. You should have all knowledge needed to succeed at this Here is the final contract: @@ -188,7 +188,7 @@ Let's get familiar with the tests to understand what the new smart contract shou (ok (var-get counter)))) ``` - Done? Great! Run the tests and make sure all of them are passing. You are looking for 4 passed tests: + Done? Great. Run the tests and make sure all of them are passing. You are looking for 4 passed tests: ```bash counter contract test suite @@ -216,7 +216,7 @@ calling all public methods you implemented. Here's a suggested order: -> As you can see, read-only function calls don't require a transaction to complete. This is because the method doesn't require a state change. -=> Congratulations! You just implemented, deployed, and called your own Clarity smart contract. +=> Congratulations. You just implemented, deployed, and called your own Clarity smart contract. With the completion of this tutorial, you: diff --git a/src/pages/write-smart-contracts/hello-world-tutorial.md b/src/pages/write-smart-contracts/hello-world-tutorial.md index 697d1a1c..25910465 100644 --- a/src/pages/write-smart-contracts/hello-world-tutorial.md +++ b/src/pages/write-smart-contracts/hello-world-tutorial.md @@ -1,5 +1,5 @@ --- -title: Hello, World! +title: Hello, World description: Learn the basics of Clarity and write a simple Hello World smart contract. duration: 18 minutes experience: beginners @@ -160,7 +160,7 @@ On the Sandbox view, switch to the [**Contract call**](https://testnet-explorer. After clicking **Search**, you will see the two public methods implemented in the smart contract. -Locate the `(echo-number)` method, provide any integer for the `val` argument (e.g. 42) and click **Submit**. You will see the value you entered echoed back to you below the button: +Locate the `(echo-number)` method, provide any integer for the `val` argument (for example 42) and click **Submit**. You will see the value you entered echoed back to you below the button: ```clarity Result: (ok 42) diff --git a/src/pages/write-smart-contracts/overview.md b/src/pages/write-smart-contracts/overview.md index f1992bb7..d84a9520 100644 --- a/src/pages/write-smart-contracts/overview.md +++ b/src/pages/write-smart-contracts/overview.md @@ -29,9 +29,9 @@ blockchain in order to independently verify that an app's global shared state ha Not every decentralized application requires smart contracts, but Clarity unlocks interesting capabilities for decentralized applications. Examples of use cases include, but are not limited to: -- Access control (e.g. pay to access) -- Non-fungible (e.g. collectibles) and fungible tokens (e.g. stablecoins) -- Business model templates (e.g. subscriptions) +- Access control (for example pay to access) +- Non-fungible (for example collectibles) and fungible tokens (for example stablecoins) +- Business model templates (for example subscriptions) - App-specific blockchains - Decentralized Autonomous Organizations diff --git a/src/pages/write-smart-contracts/principals.md b/src/pages/write-smart-contracts/principals.md index 34367e2d..391ed83e 100644 --- a/src/pages/write-smart-contracts/principals.md +++ b/src/pages/write-smart-contracts/principals.md @@ -61,7 +61,7 @@ example below. Smart contracts themselves are principals and are represented by the smart contract's identifier -- which is the publishing address of the -contract _and_ the contract's name, e.g.: +contract _and_ the contract's name, for example: ```clarity 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-name @@ -69,7 +69,7 @@ contract _and_ the contract's name, e.g.: For convenience, smart contracts may write a contract's identifier in the form `.contract-name`. This will be expanded by the Clarity interpreter into -a fully-qualified contract identifier that corresponds to the same +a fully qualified contract identifier that corresponds to the same publishing address as the contract it appears in. For example, if the same publisher address, `SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR`, is publishing two contracts, `contract-A` and `contract-B`, the fully @@ -149,7 +149,7 @@ This contract performs two different authorization checks: 1. Before a ship is allowed to fly, the contract checks whether or not the transaction was created and signed by an authorized pilot. A pilot could, for example, call another contract, which then calls - the "fly-ship" public function on the pilot's behalf. + the `fly-ship` public function on the pilot's behalf. 2. Before modifying the allowed-pilots for a given rocket ship, the contract checks that the transaction was signed by the owner of the rocket ship. Furthermore, the contract requires that this function @@ -285,11 +285,11 @@ a smart contract rocket-ship-line: ;; * authorize each employed pilot to the ship (define-public (add-managed-rocket (ship uint)) (begin - ;; only the ceo may call this function! + ;; only the ceo may call this function (asserts! (is-eq tx-sender contract-caller line-ceo) (err u1)) ;; start executing as the contract (as-contract (begin - ;; make sure the contract owns the ship! + ;; make sure the contract owns the ship (asserts! (contract-call? .rockets-base is-my-ship ship) (err u2)) ;; register all of our pilots on the ship (add-pilots-to ship))))) diff --git a/src/pages/write-smart-contracts/public-registry-tutorial.md b/src/pages/write-smart-contracts/public-registry-tutorial.md index 33e3297d..7fcfe972 100644 --- a/src/pages/write-smart-contracts/public-registry-tutorial.md +++ b/src/pages/write-smart-contracts/public-registry-tutorial.md @@ -133,7 +133,7 @@ To use the `PublicUrlRegistrar` component, open `Sharer.jsx` and add the followi ``` -Now, you should be able to register your public to-do list on the blockchain when you click on "Register on-chain". +Now, you should be able to register your public to-do list on the blockchain when you click on "Register on-chain." ![How to register the public to-do list](/images/todos-register-on-chain.png) @@ -379,7 +379,7 @@ const fetchActivities = useCallback(async () => { ### Step 3: Filter for successful contract calls -Contract calls could fail with an error, e.g. if the public url is too long. The transactions should be filtered for successful contract calls: +Contract calls could fail with an error, for example if the public url is too long. The transactions should be filtered for successful contract calls: ```js const contractCallsOnly = r => { @@ -445,7 +445,7 @@ In addition to `tx_result`, the transaction object also contains a timestamp (`b -> Note: The `AccountsApi` and other Api methods provide parameters to page through the results using `limit` and `offset`. See [the docs](https://blockstack.github.io/stacks-blockchain-api/client/interfaces/getaccounttransactionsrequest.html) for more details. -=> Congratulations! You just implemented a list of recent activities that was fetched from the blockchain. +=> Congratulations. You just implemented a list of recent activities that was fetched from the blockchain. ![How recent activities look like](/images/todos-recent-activities.png) @@ -599,7 +599,7 @@ Update the UI to display the data of the first registry entry. } ``` -=> Congratulations! You just called read-only functions and map entries from the public registry — without managing a server. +=> Congratulations. You just called read-only functions and map entries from the public registry, without managing a server. With the completion of this tutorial, you: diff --git a/src/pages/write-smart-contracts/signing-transactions.md b/src/pages/write-smart-contracts/signing-transactions.md index a321577b..b8c71802 100644 --- a/src/pages/write-smart-contracts/signing-transactions.md +++ b/src/pages/write-smart-contracts/signing-transactions.md @@ -95,10 +95,10 @@ interface ContractCallOptions { To be able to serialize your transaction properly, you need to provide the appropriate Clarity type with each argument. These types are named the same as they are in Clarity. The `value` that you pass must be a string. The types you can pass are: -- `uint` - i.e. `"240"` -- `int` - i.e. `"12"` -- `bool` - can be "true", "false", "0" or "1" -- `buff` - i.e. `"asdf"` +- `uint` - for example `"240"` +- `int` - for example `"12"` +- `bool` - can be `true`, `false`, `0` or `1` +- `buff` - for example `"asdf"` - `principal` - This can be a contract principal, or a standard principal. [Read more about principals](/write-smart-contracts/principals). Examples: `"ST22T6ZS7HVWEMZHHFK77H4GTNDTWNPQAX8WZAKHJ"` or `"ST22T6ZS7HVWEMZHHFK77H4GTNDTWNPQAX8WZAKHJ.my-contract"`. diff --git a/src/pages/write-smart-contracts/testing-contracts.md b/src/pages/write-smart-contracts/testing-contracts.md index 044ae539..ec29750b 100644 --- a/src/pages/write-smart-contracts/testing-contracts.md +++ b/src/pages/write-smart-contracts/testing-contracts.md @@ -63,7 +63,7 @@ You should see the following response: 3 passing (412ms) ``` -Great, all tests are passing! Now, let's have a look at the test implementation. That helps understand how to interact with Clarity smart contracts. +Great, all tests are passing. Now, let's have a look at the test implementation. That helps understand how to interact with Clarity smart contracts. ## Interact with contracts @@ -140,4 +140,4 @@ With the completion of this tutorial, you: - Created a working Clarity starter project - Understood how to test Clarity contracts -Congratulations! +Congratulations.