diff --git a/blog/2019-05-28-first-blog-post.md b/blog/2019-05-28-first-blog-post.md deleted file mode 100644 index 02f3f81bd2..0000000000 --- a/blog/2019-05-28-first-blog-post.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -slug: first-blog-post -title: First Blog Post -authors: - name: Gao Wei - title: Docusaurus Core Team - url: https://github.com/wgao19 - image_url: https://github.com/wgao19.png -tags: [hola, docusaurus] ---- - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet diff --git a/blog/2019-05-29-long-blog-post.md b/blog/2019-05-29-long-blog-post.md deleted file mode 100644 index 26ffb1b1f6..0000000000 --- a/blog/2019-05-29-long-blog-post.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -slug: long-blog-post -title: Long Blog Post -authors: endi -tags: [hello, docusaurus] ---- - -This is the summary of a very long blog post, - -Use a `` comment to limit blog post size in the list view. - - - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet - -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque elementum dignissim ultricies. Fusce rhoncus ipsum tempor eros aliquam consequat. Lorem ipsum dolor sit amet diff --git a/blog/2021-08-01-mdx-blog-post.mdx b/blog/2021-08-01-mdx-blog-post.mdx deleted file mode 100644 index c04ebe323e..0000000000 --- a/blog/2021-08-01-mdx-blog-post.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -slug: mdx-blog-post -title: MDX Blog Post -authors: [slorber] -tags: [docusaurus] ---- - -Blog posts support [Docusaurus Markdown features](https://docusaurus.io/docs/markdown-features), such as [MDX](https://mdxjs.com/). - -:::tip - -Use the power of React to create interactive blog posts. - -```js - -``` - - - -::: diff --git a/blog/2021-08-26-welcome/docusaurus-plushie-banner.jpeg b/blog/2021-08-26-welcome/docusaurus-plushie-banner.jpeg deleted file mode 100644 index 11bda09284..0000000000 Binary files a/blog/2021-08-26-welcome/docusaurus-plushie-banner.jpeg and /dev/null differ diff --git a/blog/2021-08-26-welcome/index.md b/blog/2021-08-26-welcome/index.md deleted file mode 100644 index 9455168f17..0000000000 --- a/blog/2021-08-26-welcome/index.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -slug: welcome -title: Welcome -authors: [slorber, yangshun] -tags: [facebook, hello, docusaurus] ---- - -[Docusaurus blogging features](https://docusaurus.io/docs/blog) are powered by the [blog plugin](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-blog). - -Simply add Markdown files (or folders) to the `blog` directory. - -Regular blog authors can be added to `authors.yml`. - -The blog post date can be extracted from filenames, such as: - -- `2019-05-30-welcome.md` -- `2019-05-30-welcome/index.md` - -A blog post folder can be convenient to co-locate blog post images: - -![Docusaurus Plushie](./docusaurus-plushie-banner.jpeg) - -The blog supports tags as well! - -**And if you don't want a blog**: just delete this directory, and use `blog: false` in your Docusaurus config. diff --git a/blog/authors.yml b/blog/authors.yml deleted file mode 100644 index bcb2991563..0000000000 --- a/blog/authors.yml +++ /dev/null @@ -1,17 +0,0 @@ -endi: - name: Endilie Yacop Sucipto - title: Maintainer of Docusaurus - url: https://github.com/endiliey - image_url: https://github.com/endiliey.png - -yangshun: - name: Yangshun Tay - title: Front End Engineer @ Facebook - url: https://github.com/yangshun - image_url: https://github.com/yangshun.png - -slorber: - name: Sébastien Lorber - title: Docusaurus maintainer - url: https://sebastienlorber.com - image_url: https://github.com/slorber.png diff --git a/docs/clarity/crash-course.md b/docs/clarity/crash-course.md deleted file mode 100644 index 89a864e9c6..0000000000 --- a/docs/clarity/crash-course.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: Clarity Crash Course -description: A quick introduction to the Clarity programming language -sidebar_position: 1 ---- - -You now understand why Clarity exists and what problems it was designed to solve. -:::note -If you didn't read the previous section, go ahead and [do that first](./index.md). -::: - -Now let's do a really quick introduction to Clarity so you can familiarize yourself with the language and syntax. - -This crash course is designed for people who have some experience with programming but are new to Clarity. You don't need smart contract development experience, but if you do, with something like Solidity, you'll pick this up really quick. - -Once you've familiarized yourself with the language, if you'd like to continue your journey and master Clarity to become a smart contract developer, we recommend either the book, [Clarity of Mind](https://book.clarity-lang.org/title-page.html), or the course, [Clarity Universe](https://clarity-lang.org/universe), which has both a self-paced and guided cohort-based version. - -## Your First Clarity Smart Contract - -We're going to build a basic Clarity smart contract using [Clarity Tools](https://clarity.tools/code/new), so you won't have to install anything for this introduction. - -Visit that link, and it will open up a new contract for you. - -![Clarity Tools New](tools-new.png) - -Already we can take a look at a few basic features of both Clarity and Clarity Tools. First, on the left you'll see that our Clarity code is being evaluated in real-time for us. This is really nice for experimenting and demonstrating basic Clarity code. - -Next up we can see our first bit of Clarity code. - -Those two semicolons are how we denote comments in Clarity. - -Then the next line down we have a public function declaration. - -Here is out first glimpse of Clarity's syntax, which may be new to you depending on your development background. - -For those new to Clarity, it's a little weird and uncomfortable at first, but one of the core design tenets of Clarity is simplicity and readability, and the more you work with it the more you come to appreciate the succinctness and _clarity_ (sorry) of the code you are writing. - -Clarity takes inspiration from LISP, and you can think of everything in Clarity as a list inside of a list, or an expression inside of an expression. Everything in Clarity is wrapped in parentheses, function definitions, variable declarations, function parameters, etc. - -So here we are saying that we want to: - -1. Call a function called `define-read-only`. This is a built-in function, one of many that you can refer to [in the docs](./language-functions.mdx). - -2. Pass it a parameter of hello, which corresponds to the method signature type. - -3. Pass it a parameter of "Hello", which corresponds to the function body. - -You can refer to the [`define-read-only`](https://docs.stacks.co/docs/write-smart-contracts/clarity-language/language-functions#define-read-only) documentation to see these parameters. - -Why am I describing this as if we are calling a function? Because we are, and it's an important concept in Clarity that everything is an expression inside of an expression. - -Let's expand on this concept a bit by deleting this and writing a new function. - -```clarity -(define-data-var count int 0) -(define-public (add-number (number int)) - (let - ( - (current-count count) - ) - - (var-set count (+ 1 number)) - (ok (var-get count)) - ) -) - - -(add-number 5) -``` - -If you type that into Clarity Tools, you'll see the result that gets printed is 6. - -![Clarity Tools New](tools-new.png) - -Okay there are actually a lot of Clarity concepts packed into this simple code. - -Let's go over what this code is doing, and you'll pick up some Clarity concepts along the way. - -The first thing we are doing here is defining a new variable called `count` and setting its initial value to 0. - -This will be a persistent state variable, so this is actually getting written to the blockchain. If you are new to smart contract development, the fact that data is persisted within the file like this might take some getting used to. - -So if we were to write and deploy this contract (which you can do in the Stacks Explorer if you like), as soon as it gets deployed, it will run through the contract line by line executing anything at the root level. - -Remember that Clarity is interpreted, not compiled, so there's not compile step when developing Clarity contracts. - -So this `define-data-var` will be evaluated and the `count` variable will be initialized with a value of 0. - -Next we are defining a public function called `add-number`, which will be created (but not called) on deploy as well. - -:::note -In Clarity, we have public, private, and read only functions. Public allow you to modify chain state and can be called from anywhere, private do the same except they can only be called from within the contract, and read only will fail if they attempt to modify state. -::: - -This function is taking a single parameter, called `number` that is a type of `int`. - -Now, what is this `let` business all about? Remember that we said that everything in Clarity is an expression and declaring new functions is just a matter of calling the `define-public` function? - -Well the second argument to this is the function body, but it can only evaluate a single expression. - -So this `let` function is a way of wrapping a multi-step function into a single argument. - -But it does one other crucial thing at the beginning. This line: - -```clarity -(current-count count) -``` - -Sets a variable that only exists in the context of this particular function. So here we are saying, create a new variable called `current-count` and set it equal to the value of `count`. - -Then we use that in our actual function body down below. - -In the next step we are setting the value of our `count` variable to 1 plus whatever number we passed in. The `+` is just another call to a function where the parameters are the numbers we want to add. - -Then, finally, we are returning the new value of `count` with our `ok` response, indicating that the function completed successfully. - -Then in the very last line we are actually calling this function, passing in 5. - -This was a very brief overview of Clarity just to get your feet wet and give you a taste of how it works. - -If you are interested in diving into the details, we highly recommend going through either the [Clarity Book](https://book.clarity-lang.org/title-page.html) or [Clarity Universe](https://clarity-lang.org/universe), depending on your learning style. - -If you prefer to dive directly into the docs, you can continue on ahead and check out the types, keywords, and functions available in Clarity, as well as a few sample contracts. diff --git a/docs/clarity/index.md b/docs/clarity/index.md deleted file mode 100644 index a90f91b599..0000000000 --- a/docs/clarity/index.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: Clarity Overview -description: Overview and guides for getting started with Clarity -sidebar_label: Clarity -sidebar_position: 5 ---- - -Clarity is a **decidable** smart contract language that optimizes for predictability and security, designed for the Stacks blockchain. Smart contracts allow developers to encode essential business logic on a blockchain. - -The design decisions behind Clarity were based heavily on taking lessons learned in common Solidity exploits and creating a language that has been purpose-built for safety and security in mind. - -These docs serve primarily as a reference for the functions and keywords that you can use in Clarity. - -In order to learn Clarity, we recommend diving into the [Clarity of Mind](https://book.clarity-lang.org/), an online book to teach you everything you need to know to build robust smart contracts, or joining a [Clarity Camp](https://clarity-lang.org/universe#camp), the cohort-based immersive Clarity experience. - -## What makes Clarity different - -The following section is an excerpt from the excellent book, [Clarity of Mind](https://book.clarity-lang.org/ch00-00-introduction.html): - -The number of smart contract languages grows by the year. Choosing a first language can be challenging, especially for a beginner. The choice is largely dictated by the ecosystem you are interested in, although some languages are applicable to more than just one platform. Each language has its own upsides and downsides and it is out of the scope of this book to look at all of them. Instead, we will focus on what sets Clarity apart and why it is a prime choice if you require the utmost security and transparency. - -One of the core precepts of Clarity is that it is secure by design. The design process was guided by examining common pitfalls, mistakes, and vulnerabilities in the field of smart contract engineering as a whole. There are countless real world examples of where developer failure led to the loss or theft of vast amounts of tokens. To name two big ones: an issue that has become known as the Parity bug led to the irreparable loss of millions of dollars worth of Ethereum. Second, the hacking of The DAO (a "Decentralized Autonomous Organization") caused financial damage so great that the Ethereum Foundation decided to issue a contentious hard fork that undid the theft. These and many other mistakes could have been prevented in the design of the language itself. - -### Clarity is interpreted, not compiled - -Clarity code is interpreted and committed to the chain exactly as written. Solidity and other languages are compiled to byte-code before it is submitted to the chain. The danger of compiled smart contract languages is two-fold: first, a compiler adds a layer of complexity. A bug in the compiler may lead to different byte-code than was intended and thus carries the risk of introducing a vulnerability. Second, byte-code is not human-readable, which makes it very hard to verify what the smart contract is actually doing. Ask yourself, would you sign a contract you cannot read? If your answer is no, then why should it be any different for smart contracts? With Clarity, what you see is what you get. - -### Clarity is decidable - -A decidable language has the property that from the code itself, you can know with certainty what the program will do. This avoids issues like the halting problem. With Clarity you know for sure that given any input, the program will halt in a finite number of steps. In simple terms: it is guaranteed that program execution will end. Decidability also allows for complete static analysis of the call graph so you get an accurate picture of the exact cost before execution. There is no way for a Clarity call to "run out of gas" in the middle of the call. We explore this idea more, along with a discussion on Turing completeness, in the [security deep dive on decidability](./security/decidable.md). - -### Clarity does not permit reentrancy - -Reentrancy is a situation where one smart contract calls into another, which then calls back into the first contract—the call "re-enters" the same logic. It may allow an attacker to trigger multiple token withdrawals before the contract has had a chance to update its internal balance sheet. Clarity's design considers reentrancy an anti-feature and disallows it on the language level. - -### Clarity guards against overflow and underflows - -Overflows and underflows happen when a calculation results in a number that is either too large or too small to be stored, respectively. These events throw smart contracts into disarray and may intentionally be triggered in poorly written contracts by attackers. Usually this leads to a situation where the contract is either frozen or drained of tokens. Overflows and underflows of any kind automatically cause a transaction to be aborted in Clarity. - -### Support for custom tokens is built-in - -Issuance of custom fungible and non-fungible tokens is a popular use-case for smart contracts. Custom token features are built into the Clarity language. Developers do not need to worry about creating an internal balance sheet, managing supply, and emitting token events. Creating custom tokens is covered in depth in later chapters. - -### On Stacks, transactions are secured by post conditions - -In order to further safeguard user tokens, post conditions can be attached to transactions to assert the chain state has changed in a certain way once the transaction has completed. For example, a user calling into a smart contract may attach a post condition that states that after the call completes, exactly 500 STX should have been transferred from one address to another. If the post condition check fails, then the entire transaction is reverted. Since custom token support is built right into Clarity, post conditions can also be used to guard any other token in the same way. - -### Returned responses cannot be left unchecked - -Public contract calls must return a so-called response that indicates success or failure. Any contract that calls another contract is required to properly handle the response. Clarity contracts that fail to do so are invalid and cannot be deployed on the network. Other languages like Solidity permit the use of low level calls without requiring the return value to be checked. For example, a token transfer can fail silently if the developer forgets to check the result. In Clarity it is not possible to ignore errors, although that obviously does prevent buggy error handling on behalf of the developer. Responses and error handling are covered extensively in the chapters on functions and control flow. - -### Composition over inheritance - -Clarity adopts a composition over inheritance. It means that Clarity smart contracts do not inherit from one another like you see in languages like Solidity. Developers instead define traits which are then implemented by different smart contracts. It allows contracts to conform to different interfaces with greater flexibility. There is no need to worry about complex class trees and contracts with implicit inherited behavior. - -### Access to the base chain: Bitcoin - -Clarity smart contracts can read the state of the Bitcoin base chain. It means you can use Bitcoin transactions as a trigger in your smart contracts! Clarity also features a number of built-in functions to verify secp256k1 signatures and recover keys. diff --git a/docs/clarity/language-functions.mdx b/docs/clarity/language-functions.mdx deleted file mode 100644 index a2aef51295..0000000000 --- a/docs/clarity/language-functions.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -title: Functions -description: See a detailed list of all functions for the Clarity language. -sidebar_position: 3 -tags: - - clarity ---- - -import { FunctionsReferences } from "@site/src/components/ApiReferences/FunctionsReferences.jsx"; - -## Functions - -Detailed list of all functions for the Clarity language. - - diff --git a/docs/clarity/language-keywords.mdx b/docs/clarity/language-keywords.mdx deleted file mode 100644 index 63658fab60..0000000000 --- a/docs/clarity/language-keywords.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Keywords -description: See a detailed list of all keywords for the Clarity language. -sidebar_position: 4 -tags: - - clarity ---- - -import { KeywordsReferences } from "@site/src/components/ApiReferences/KeywordsReferences.jsx"; - -![Abstract image illustrate Clarity native keywords](/img/keywords.jpg) - -## Keyword reference - -Detailed list of all keywords for the Clarity language. - - diff --git a/docs/clarity/language-types.md b/docs/clarity/language-types.md deleted file mode 100644 index 8c7bc0e8cd..0000000000 --- a/docs/clarity/language-types.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Types -description: See a detailed list of all types for the Clarity language. -sidebar_position: 2 -tags: - - clarity ---- - -## Clarity Type System - -The type system contains the following types: - -| Types | Notes | -| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `int` | signed 128-bit integer | -| `uint` | unsigned 128-bit integer | -| `bool` | boolean value (`true` or `false`) | -| `principal` | object representing a principal (whether a contract principal or standard principal) | -| `(buff max-len)` | byte buffer of 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` (u"A smiley face emoji \u{1F600} as a utf8 string") | -| `(list max-len entry-type)` | list of maximum length `max-len`, with entries of type `entry-type` | -| `{label-0: value-type-0, label-1: value-type-1, ...}` | tuple, group of data values with named fields | -| `(optional some-type)` | an option type for objects that can either be `(some value)` or `none` | -| `(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. | diff --git a/docs/clarity/new-function.png b/docs/clarity/new-function.png deleted file mode 100644 index a956d776ba..0000000000 Binary files a/docs/clarity/new-function.png and /dev/null differ diff --git a/docs/clarity/noteworthy-contracts/_category_.json b/docs/clarity/noteworthy-contracts/_category_.json deleted file mode 100644 index eb32d48e32..0000000000 --- a/docs/clarity/noteworthy-contracts/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Noteworthy Contracts", - "position": 5, - "link": { - "type": "generated-index", - "description": "Specific deployed Clarity Contracts worth mentioning." - } -} diff --git a/docs/clarity/noteworthy-contracts/bns-contract.md b/docs/clarity/noteworthy-contracts/bns-contract.md deleted file mode 100644 index 6dc73263a2..0000000000 --- a/docs/clarity/noteworthy-contracts/bns-contract.md +++ /dev/null @@ -1,522 +0,0 @@ ---- -title: BNS Contract -description: The Bitcoin Name System. ---- - -![](/img/satoshi-btc.png) - -## Introduction - -The Bitcoin Name System (BNS) is implemented as a smart contract using Clarity. - -Below is a list of public and read-only functions as well as error codes that can be returned by those methods: - -- [Public functions](#public-functions) -- [Read-only functions](#read-only-functions) -- [Error codes](#error-codes) - -## Public functions - -### name-import - -#### Input: `(buff 20), (buff 48), principal, (buff 20)` - -#### Output: `(response bool int)` - -#### Signature: `(name-import namespace name beneficiary zonefile-hash)` - -#### Description: - -Imports name to a revealed namespace. Each imported name is given both an owner and some off-chain state. - -### name-preorder - -#### Input: `(buff 20), uint` - -#### Output: `(response uint int)` - -#### Signature: `(name-preorder hashed-salted-fqn stx-to-burn)` - -#### Description: - -Preorders a name by telling all BNS nodes the salted hash of the BNS name. It pays the registration fee to the namespace owner's designated address. - -### name-register - -#### Input: `(buff 20), (buff 48), (buff 20), (buff 20)` - -#### Output: `(response bool int)` - -#### Signature: `(name-register namespace name salt zonefile-hash)` - -#### Description: - -Reveals the salt and the name to all BNS nodes, and assigns the name an initial public key hash and zone file hash. - -### name-renewal - -#### Input: `(buff 20), (buff 48), uint, (optional principal), (optional (buff 20))` - -#### Output: `(response bool int)` - -#### Signature: `(name-renewal namespace name stx-to-burn new-owner zonefile-hash)` - -#### Description: - -Depending in the namespace rules, a name can expire. For example, names in the .id namespace expire after 2 years. You need to send a name renewal every so often to keep your name. - -You will pay the registration cost of your name to the namespace's designated burn address when you renew it. -When a name expires, it enters a \"grace period\". The period is set to 5000 blocks (a month) but can be configured for each namespace. - -It will stop resolving in the grace period, and all of the above operations will cease to be honored by the BNS consensus rules. -You may, however, send a NAME_RENEWAL during this grace period to preserve your name. After the grace period, everybody can register that name again. -If your name is in a namespace where names do not expire, then you never need to use this transaction. - -### name-revoke - -#### Input: `(buff 20), (buff 48)` - -#### Output: `(response bool int)` - -#### Signature: `(name-revoke namespace name)` - -#### Description: - -Makes a name unresolvable. The BNS consensus rules stipulate that once a name is revoked, no one can change its public key hash or its zone file hash. The name's zone file hash is set to null to prevent it from resolving. You should only do this if your private key is compromised, or if you want to render your name unusable for whatever reason. - -### name-transfer - -#### Input: `(buff 20), (buff 48), principal, (optional (buff 20))` - -#### Output: `(response bool int)` - -#### Signature: `(name-transfer namespace name new-owner zonefile-hash)` - -#### Description: - -Changes the name's public key hash. You would send a name transfer transaction if you wanted to: - -- Change your private key -- Send the name to someone else or -- Update your zone file - -When transferring a name, you have the option to also clear the name's zone file hash (i.e. set it to null). This is useful for when you send the name to someone else, so the recipient's name does not resolve to your zone file. - -### name-update - -#### Input: `(buff 20), (buff 48), (buff 20)` - -#### Output: `(response bool int)` - -#### Signature: `(name-update namespace name zonefile-hash)` - -#### Description: - -Changes the name's zone file hash. You would send a name update transaction if you wanted to change the name's zone file contents. For example, you would do this if you want to deploy your own Gaia hub and want other people to read from it. - -### namespace-preorder - -#### Input: `(buff 20), uint` - -#### Output: `(response uint int)` - -#### Signature: `(namespace-preorder hashed-salted-namespace stx-to-burn)` - -#### Description: - -Registers the salted hash of the namespace with BNS nodes, and burns the requisite amount of cryptocurrency. Additionally, this step proves to the BNS nodes that user has honored the BNS consensus rules by including a recent consensus hash in the transaction. Returns pre-order's expiration date (in blocks). - -### namespace-ready - -#### Input: `(buff 20)` - -#### Output: `(response bool int)` - -#### Signature: `(namespace-ready namespace)` - -#### Description: - -Launches the namespace and makes it available to the public. Once a namespace is launched, anyone can register a name in it if they pay the appropriate amount of cryptocurrency. - -### namespace-reveal - -#### Input: `(buff 20), (buff 20), uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, principal` - -#### Output: `(response bool int)` - -#### Signature: `(namespace-reveal namespace namespace-salt p-func-base p-func-coeff p-func-b1 p-func-b2 p-func-b3 p-func-b4 p-func-b5 p-func-b6 p-func-b7 p-func-b8 p-func-b9 p-func-b10 p-func-b11 p-func-b12 p-func-b13 p-func-b14 p-func-b15 p-func-b16 p-func-non-alpha-discount p-func-no-vowel-discount lifetime namespace-import)` - -#### Description: - -Reveals the salt and the namespace ID (after a namespace preorder). It reveals how long names last in this namespace before they expire or must be renewed, and it sets a price function for the namespace that determines how cheap or expensive names its will be.All of the parameters prefixed by `p` make up the `price function`. These parameters govern the pricing and lifetime of names in the namespace. - -The rules for a namespace are as follows: - -- a name can fall into one of 16 buckets, measured by length. Bucket 16 incorporates all names at least 16 characters long. - -- the pricing structure applies a multiplicative penalty for having numeric characters, or punctuation characters. - -- the price of a name in a bucket is `((coeff) * (base) ^ (bucket exponent)) / ((numeric discount multiplier) * (punctuation discount multiplier))` - -Example: - -- base = 10 -- coeff = 2 -- nonalpha discount: 10 -- no-vowel discount: 10 -- buckets 1, 2: 9 -- buckets 3, 4, 5, 6: 8 -- buckets 7, 8, 9, 10, 11, 12, 13, 14: 7 -- buckets 15, 16+: - -## Read-only functions - -### can-name-be-registered - -#### Input: `(buff 20), (buff 48)` - -#### Output: `(response bool int)` - -#### Signature: `(can-name-be-registered namespace name)` - -#### Description: - -Returns true if the provided name can be registered. - -### can-namespace-be-registered - -#### Input: `(buff 20)` - -#### Output: `(response bool UnknownType)` - -#### Signature: `(can-namespace-be-registered namespace)` - -#### Description: - -Returns true if the provided namespace is available. - -### can-receive-name - -#### Input: `principal` - -#### Output: `(response bool int)` - -#### Signature: `(can-receive-name owner)` - -#### Description: - -Returns true if the provided name can be received. That is, if it is not currently owned, a previous lease is expired, and the name wasn't revoked. - -### get-name-price - -#### Input: `(buff 20), (buff 48)` - -#### Output: `(response uint int)` - -#### Signature: `(get-name-price namespace name)` - -#### Description: - -Gets the price for a name. - -### get-namespace-price - -#### Input: `(buff 20)` - -#### Output: `(response uint int)` - -#### Signature: `(get-namespace-price namespace)` - -#### Description: - -Gets the price for a namespace. - -### get-namespace-properties - -#### Input: `(buff 20)` - -#### Output: `(response (tuple (namespace (buff 20)) (properties (tuple (can-update-price-function bool) (launched-at (optional uint)) (lifetime uint) (namespace-import principal) (price-function (tuple (base uint) (buckets (list 16 uint)) (coeff uint) (no-vowel-discount uint) (nonalpha-discount uint))) (revealed-at uint)))) int)` - -#### Signature: `(get-namespace-properties namespace)` - -#### Description: - -Get namespace properties. - -### is-name-lease-expired - -#### Input: `(buff 20), (buff 48)` - -#### Output: `(response bool int)` - -#### Signature: `(is-name-lease-expired namespace name)` - -#### Description: - -Return true if the provided name lease is expired. - -### name-resolve - -#### Input: `(buff 20), (buff 48)` - -#### Output: `(response (tuple (lease-ending-at (optional uint)) (lease-started-at uint) (owner principal) (zonefile-hash (buff 20))) int)` - -#### Signature: `(name-resolve namespace name)` - -#### Description: - -Get name registration details. - -### resolve-principal - -#### Input: `principal` - -#### Output: `(response (tuple (name (buff 48)) (namespace (buff 20))) (tuple (code int) (name (optional (tuple (name (buff 48)) (namespace (buff 20)))))))` - -#### Signature: `(resolve-principal owner)` - -#### Description: - -Returns the registered name that a principal owns if there is one. A principal can only own one name at a time. - -## Error codes - -### ERR_INSUFFICIENT_FUNDS - -#### type: `int` - -#### value: `4001` - -### ERR_NAMESPACE_ALREADY_EXISTS - -#### type: `int` - -#### value: `1006` - -### ERR_NAMESPACE_ALREADY_LAUNCHED - -#### type: `int` - -#### value: `1014` - -### ERR_NAMESPACE_BLANK - -#### type: `int` - -#### value: `1013` - -### ERR_NAMESPACE_CHARSET_INVALID - -#### type: `int` - -#### value: `1016` - -### ERR_NAMESPACE_HASH_MALFORMED - -#### type: `int` - -#### value: `1015` - -### ERR_NAMESPACE_NOT_FOUND - -#### type: `int` - -#### value: `1005` - -### ERR_NAMESPACE_NOT_LAUNCHED - -#### type: `int` - -#### value: `1007` - -### ERR_NAMESPACE_OPERATION_UNAUTHORIZED - -#### type: `int` - -#### value: `1011` - -### ERR_NAMESPACE_PREORDER_ALREADY_EXISTS - -#### type: `int` - -#### value: `1003` - -### ERR_NAMESPACE_PREORDER_CLAIMABILITY_EXPIRED - -#### type: `int` - -#### value: `1009` - -### ERR_NAMESPACE_PREORDER_EXPIRED - -#### type: `int` - -#### value: `1002` - -### ERR_NAMESPACE_PREORDER_LAUNCHABILITY_EXPIRED - -#### type: `int` - -#### value: `1010` - -### ERR_NAMESPACE_PREORDER_NOT_FOUND - -#### type: `int` - -#### value: `1001` - -### ERR_NAMESPACE_PRICE_FUNCTION_INVALID - -#### type: `int` - -#### value: `1008` - -### ERR_NAMESPACE_STX_BURNT_INSUFFICIENT - -#### type: `int` - -#### value: `1012` - -### ERR_NAMESPACE_UNAVAILABLE - -#### type: `int` - -#### value: `1004` - -### ERR_NAME_ALREADY_CLAIMED - -#### type: `int` - -#### value: `2011` - -### ERR_NAME_BLANK - -#### type: `int` - -#### value: `2010` - -### ERR_NAME_CHARSET_INVALID - -#### type: `int` - -#### value: `2022` - -### ERR_NAME_CLAIMABILITY_EXPIRED - -#### type: `int` - -#### value: `2012` - -### ERR_NAME_COULD_NOT_BE_MINTED - -#### type: `int` - -#### value: `2020` - -### ERR_NAME_COULD_NOT_BE_TRANSFERRED - -#### type: `int` - -#### value: `2021` - -### ERR_NAME_EXPIRED - -#### type: `int` - -#### value: `2008` - -### ERR_NAME_GRACE_PERIOD - -#### type: `int` - -#### value: `2009` - -### ERR_NAME_HASH_MALFORMED - -#### type: `int` - -#### value: `2017` - -### ERR_NAME_NOT_FOUND - -#### type: `int` - -#### value: `2013` - -### ERR_NAME_NOT_RESOLVABLE - -#### type: `int` - -#### value: `2019` - -### ERR_NAME_OPERATION_UNAUTHORIZED - -#### type: `int` - -#### value: `2006` - -### ERR_NAME_PREORDERED_BEFORE_NAMESPACE_LAUNCH - -#### type: `int` - -#### value: `2018` - -### ERR_NAME_PREORDER_ALREADY_EXISTS - -#### type: `int` - -#### value: `2016` - -### ERR_NAME_PREORDER_EXPIRED - -#### type: `int` - -#### value: `2002` - -### ERR_NAME_PREORDER_FUNDS_INSUFFICIENT - -#### type: `int` - -#### value: `2003` - -### ERR_NAME_PREORDER_NOT_FOUND - -#### type: `int` - -#### value: `2001` - -### ERR_NAME_REVOKED - -#### type: `int` - -#### value: `2014` - -### ERR_NAME_STX_BURNT_INSUFFICIENT - -#### type: `int` - -#### value: `2007` - -### ERR_NAME_TRANSFER_FAILED - -#### type: `int` - -#### value: `2015` - -### ERR_NAME_UNAVAILABLE - -#### type: `int` - -#### value: `2004` - -### ERR_PANIC - -#### type: `int` - -#### value: `0` - -### ERR_PRINCIPAL_ALREADY_ASSOCIATED - -#### type: `int` - -#### value: `3001` diff --git a/docs/clarity/noteworthy-contracts/stacking-contract.md b/docs/clarity/noteworthy-contracts/stacking-contract.md deleted file mode 100644 index 6a204159d3..0000000000 --- a/docs/clarity/noteworthy-contracts/stacking-contract.md +++ /dev/null @@ -1,352 +0,0 @@ ---- -title: Stacking Contract -description: See a detailed list of all functions and error codes of the Stacking contract. -sidebar_position: 6 ---- - -## Introduction - -Stacking is implemented as a smart contract using Clarity. You can always find the Stacking contract identifier using the Stacks Blockchain API [`v2/pox` endpoint](https://docs.hiro.so/api#operation/get_pox_info). - -Below is a list of public and read-only functions as well as error codes that can be returned by those methods: - -- [Public functions](#public-functions) -- [Read-only functions](#read-only-functions) -- [Error codes](#error-codes) - -## Public functions - -### allow-contract-caller - -#### input: `principal, (optional uint)` - -#### output: `(response bool int)` - -#### signature: `(allow-contract-caller caller until-burn-ht)` - -#### description: - -Give a contract-caller authorization to call stacking methods. Normally, stacking methods may only be invoked by _direct_ transactions (i.e., the `tx-sender` issues a direct `contract-call` to the stacking methods). - -By issuing an allowance, the tx-sender may call through the allowed contract. - -### delegate-stack-stx - -#### input: `principal, uint, (tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint` - -#### output: `(response (tuple (lock-amount uint) (stacker principal) (unlock-burn-height uint)) int)` - -#### signature: `(delegate-stack-stx stacker amount-ustx pox-addr start-burn-ht lock-period)` - -#### description: - -As a delegate, stack the given principal's STX using `partial-stacked-by-cycle`. - -Once the delegate has stacked > minimum, the delegate should call `stack-aggregation-commit`. - -### delegate-stx - -#### input: `uint, principal, (optional uint), (optional (tuple (hashbytes (buff 20)) (version (buff 1))))` - -#### output: `(response bool int)` - -#### signature: `(delegate-stx amount-ustx delegate-to until-burn-ht pox-addr)` - -#### description: - -Delegate to `delegate-to` the ability to stack from a given address. - -This method _does not_ lock the funds, rather, it allows the delegate to issue the stacking lock. - -The caller specifies: - -- amount-ustx: the total amount of ustx the delegate may be allowed to lock -- until-burn-ht: an optional burn height at which this delegation expiration -- pox-addr: an optional p2pkh or p2sh address to which any rewards _must_ be sent - -### disallow-contract-caller - -#### input: `principal` - -#### output: `(response bool int)` - -#### signature: `(disallow-contract-caller caller)` - -#### description: - -Revokes authorization from a contract to invoke stacking methods through contract-calls - -### reject-pox - -#### input: - -#### output: `(response bool int)` - -#### signature: `(reject-pox)` - -#### description: - -Reject Stacking for this reward cycle. - -`tx-sender` votes all its uSTX for rejection. - -Note that unlike Stacking, rejecting PoX does not lock the tx-sender's tokens: PoX rejection acts like a coin vote. - -### revoke-delegate-stx - -#### input: - -#### output: `(response bool int)` - -#### signature: `(revoke-delegate-stx)` - -#### description: - -Revoke a Stacking delegate relationship. A particular Stacker may only have one delegate, so this method does not take any parameters, and just revokes the Stacker's current delegate (if one exists). - -### stack-aggregation-commit - -#### input: `(tuple (hashbytes (buff 20)) (version (buff 1))), uint` - -#### output: `(response bool int)` - -#### signature: `(stack-aggregation-commit pox-addr reward-cycle)` - -#### description: - -Commit partially stacked STX. - -This allows a stacker/delegate to lock fewer STX than the minimal threshold in multiple transactions, - -so long as: - -1. The pox-addr is the same. -2. This \"commit\" transaction is called _before_ the PoX anchor block. - -This ensures that each entry in the reward set returned to the stacks-node is greater than the threshold, - -but does not require it be all locked up within a single transaction - -### stack-stx - -#### input: `uint, (tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint` - -#### output: `(response (tuple (lock-amount uint) (stacker principal) (unlock-burn-height uint)) int)` - -#### signature: `(stack-stx amount-ustx pox-addr start-burn-ht lock-period)` - -#### description: - -Lock up some uSTX for stacking! Note that the given amount here is in micro-STX (uSTX). - -The STX will be locked for the given number of reward cycles (lock-period). - -This is the self-service interface. tx-sender will be the Stacker. - -- The given stacker cannot currently be stacking. -- You will need the minimum uSTX threshold. This isn't determined until the reward cycle begins, but this method still requires stacking over the _absolute minimum_ amount, which can be obtained by calling `get-stacking-minimum`. -- The pox-addr argument must represent a valid reward address (p2pkh, p2sh, SegWit, or Taproot). - -The tokens will unlock and be returned to the Stacker (tx-sender) automatically. - -## Read-only functions - -### can-stack-stx - -#### input: `(tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint, uint` - -#### output: `(response bool int)` - -#### signature: `(can-stack-stx pox-addr amount-ustx first-reward-cycle num-cycles)` - -#### description: - -Evaluate if a participant can stack an amount of STX for a given period. - -### get-pox-info - -#### input: - -#### output: `(response (tuple (current-rejection-votes uint) (first-burnchain-block-height uint) (min-amount-ustx uint) (prepare-cycle-length uint) (rejection-fraction uint) (reward-cycle-id uint) (reward-cycle-length uint) (total-liquid-supply-ustx uint)) UnknownType)` - -#### signature: `(get-pox-info)` - -#### description: - -Returns information about PoX status. - -### get-pox-rejection - -#### input: `principal, uint` - -#### output: `(optional (tuple (amount uint)))` - -#### signature: `(get-pox-rejection stacker reward-cycle)` - -#### description: - -Returns the amount of uSTX that a given principal used to reject a PoX cycle. - -### get-stacker-info - -#### input: `principal` - -#### output: `(optional (tuple (amount-ustx uint) (first-reward-cycle uint) (lock-period uint) (pox-addr (tuple (hashbytes (buff 20)) (version (buff 1))))))` - -#### signature: `(get-stacker-info stacker)` - -#### description: - -Returns the _current_ stacking information for `stacker. If the information is expired, or if there's never been such a stacker, then returns none. - -### get-stacking-minimum - -#### input: - -#### output: `uint` - -#### signature: `(get-stacking-minimum)` - -#### description: - -Returns the absolute minimum amount that could be validly Stacked (the threshold to Stack in a given reward cycle may be higher than this - -### get-total-ustx-stacked - -#### input: `uint` - -#### output: `uint` - -#### signature: `(get-total-ustx-stacked reward-cycle)` - -#### description: - -Returns the amount of currently participating uSTX in the given cycle. - -### is-pox-active - -#### input: `uint` - -#### output: `bool` - -#### signature: `(is-pox-active reward-cycle)` - -#### description: - -Returns whether or not PoX has been rejected at a given PoX cycle. - -## Error codes - -### ERR_DELEGATION_EXPIRES_DURING_LOCK - -#### type: `int` - -#### value: `21` - -### ERR_DELEGATION_POX_ADDR_REQUIRED - -#### type: `int` - -#### value: `23` - -### ERR_DELEGATION_TOO_MUCH_LOCKED - -#### type: `int` - -#### value: `22` - -### ERR_INVALID_START_BURN_HEIGHT - -#### type: `int` - -#### value: `24` - -### ERR_NOT_ALLOWED - -#### type: `int` - -#### value: `19` - -### ERR_STACKING_ALREADY_DELEGATED - -#### type: `int` - -#### value: `20` - -### ERR_STACKING_ALREADY_REJECTED - -#### type: `int` - -#### value: `17` - -### ERR_STACKING_ALREADY_STACKED - -#### type: `int` - -#### value: `3` - -### ERR_STACKING_EXPIRED - -#### type: `int` - -#### value: `5` - -### ERR_STACKING_INSUFFICIENT_FUNDS - -#### type: `int` - -#### value: `1` - -### ERR_STACKING_INVALID_AMOUNT - -#### type: `int` - -#### value: `18` - -### ERR_STACKING_INVALID_LOCK_PERIOD - -#### type: `int` - -#### value: `2` - -### ERR_STACKING_INVALID_POX_ADDRESS - -#### type: `int` - -#### value: `13` - -### ERR_STACKING_NO_SUCH_PRINCIPAL - -#### type: `int` - -#### value: `4` - -### ERR_STACKING_PERMISSION_DENIED - -#### type: `int` - -#### value: `9` - -### ERR_STACKING_POX_ADDRESS_IN_USE - -#### type: `int` - -#### value: `12` - -### ERR_STACKING_STX_LOCKED - -#### type: `int` - -#### value: `6` - -### ERR_STACKING_THRESHOLD_NOT_MET - -#### type: `int` - -#### value: `11` - -### ERR_STACKING_UNREACHABLE - -#### type: `int` - -#### value: `255` diff --git a/docs/clarity/noteworthy-contracts/xbtc.md b/docs/clarity/noteworthy-contracts/xbtc.md deleted file mode 100644 index e535dcf260..0000000000 --- a/docs/clarity/noteworthy-contracts/xbtc.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: xBTC -description: Wrapped BTC on Stacks ---- - -![](/img/xbtc-icon.webp) - -## Introduction - -[Wrapped.com](https://www.wrapped.com) has brought Bitcoin (xBTC) to the Stacks ecosystem. - -xBTC is backed 1:1 by Bitcoin and empowers developers to expand the Bitcoin DeFi ecosystem. - -The reserves are publicly visible [here](https://open.wrapped.com/reserves/). - -## Contract - -[SP3DX3H4FEYZJZ586MFBS25ZW3HZDMEW92260R2PR.Wrapped-Bitcoin](https://explorer.stacks.co/txid/SP3DX3H4FEYZJZ586MFBS25ZW3HZDMEW92260R2PR.Wrapped-Bitcoin?chain=mainnet) - -## Examples of uses - -[Friedger Mining Pool](https://pool.friedger.de/) currently supports Stacking rewards payments in xBTC (optional). - -## More information - -- [Blog post announcement](https://www.stacks.co/blog/tokensoft-wrapped-fundamental-bitcoin-defi-building-blocks-xbtc) by Muneeb Ali - -- Video: [Why xBTC is Important For Bitcoin to Grow](https://www.youtube.com/watch?v=xIoadrfSdi4) diff --git a/docs/clarity/sample-contracts.md b/docs/clarity/sample-contracts.md deleted file mode 100644 index adb12a58fd..0000000000 --- a/docs/clarity/sample-contracts.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Sample Contracts -description: Example contracts for learning and building Clarity smart contracts. -sidebar_position: 5 ---- - -Here's a list of sample contracts to learn Clarity or to serve as a starting point for your next project. All contracts come from the [Clarity book](https://book.clarity-lang.org/) and have been audited by [Coinfabrik](https://www.coinfabrik.com/). - -- [Counter](https://github.com/clarity-lang/book/tree/main/projects/counter) -- [Multisig Vault](https://github.com/clarity-lang/book/tree/main/projects/multisig-vault) -- [Sip-009 NFT](https://github.com/clarity-lang/book/tree/main/projects/sip009-nft) -- [SIP-010 FT](https://github.com/clarity-lang/book/tree/main/projects/sip010-ft) -- [Timelocked Wallet](https://github.com/clarity-lang/book/tree/main/projects/timelocked-wallet) -- [Tiny Market (NFT marketplace)](https://github.com/clarity-lang/book/tree/main/projects/tiny-market) diff --git a/docs/clarity/security/decidable.md b/docs/clarity/security/decidable.md deleted file mode 100644 index 7d5411e382..0000000000 --- a/docs/clarity/security/decidable.md +++ /dev/null @@ -1,179 +0,0 @@ ---- -title: Decidability -description: An exploration of the security advantages that come with a non-Turing complete, decidable language -sidebar_label: Decidability -sidebar_position: 1 ---- - -## What does it mean for a language to be Non-Turing Complete or Decidable? - -Non-Turing complete and decidable are two terms you will often hear about the security advantages of Clarity, but what do they mean? - -While related, they are not quite interchangeable, since there are a few differences. - -### Non-Turing Complete - -A system or language is non-Turing complete if it cannot simulate a Turing machine, which is an abstract model of computation. Non-Turing complete systems have limited computational power compared to Turing complete systems. -A Turing-complete system or language can simulate any Turing machine. Examples of non-Turing complete systems include finite state machines and some domain-specific languages (like Clarity). - -Non-Turing complete languages typically cannot express all possible algorithms. -Specifically, some problems whose solutions require unbounded loops or recursion cannot be expressed using -non-Turing complete languages. This last property is especially important in the context of Clarity, as it makes it so that features like unbounded loops and reentrancy are disallowed at a language level. - -### Decidable - -A problem is decidable if there exists an algorithm that can always determine whether a given input has a particular property or not in a finite amount of time. In other words, a decidable problem can be solved by a Turing machine that is guaranteed to halt for all input instances. Decidability is a property of problems, whereas Turing completeness is a property of languages or computational systems. - -The fact that Clarity is decidable means that developers (and tooling) can more easily reason about and predict with certainty the behavior of Clarity contracts, regardless of the input. - -## Mindset of a Smart Contract Developer - -Before we dive into specifics, let's first set the context and viewpoint we should hold as smart contract developers who want to write secure code. - -As you explore further into the security properties of Solidity and Clarity, you'll see that there are always mitigation steps that _can_ be taken by developers to help address some of these security issues. - -The main issue, with this line of thinking, is it increases the odds of human error in smart contract security. If we can preserve functionality while mitigating the chance of human error as much as possible, we should do so. - -## Should smart contracts be Turing complete? - -We will discover new applications for smart contracts. These applications will go beyond current smart contracts, traditional contracts, and may even open new economic opportunities. Given these possibilities, how should we build our smart contracts? What characteristics should our smart contract languages have? - -It is good practice to separate data from programs. Should smart contracts be data, or programs, or something in between? If smart contracts are data, then should the programs that execute-them be Turing complete or perhaps less powerful? If smart contracts are programs, then what language should smart contracts be written in? What characteristics should this programming language have? - -The Church-Turing thesis is the hypothesis that all formal notions of computation are captured by Turing machines or modern computers. A programming language is Turing complete if it captures all formal notions of computation. Many programming languages are Turing complete. For example, Python, C++, Rust, Java, Lisp, and Solidity are all Turing complete. - -Consider a program and its input. In the worst case, determining this program’s output is impossible. Validating a program, on a particular input, is done by generating a proof-of-correctness. - -Proofs-of-correctness are logical proofs that can be mechanically validated. Finding proofs-of-correctness for programs and their input is undecidable. Kurt G\”odel showed there are undecidability logical statements. - -This indicates all programs in Turing complete languages cannot be validated in the worst case. Thus, Turing complete smart contract languages must allow contracts that cannot be validated. - -Alonzo Church and Alan Turing showed there are problems that are uncomputable. Uncomputable problems cannot be solved by any Turing machine. Hence, assuming the Church-Turing thesis, these uncomputable problems cannot be solved by any computer. - -We'll explore this idea further later in this section. - -Turing complete languages are very expressive. In fact, assuming the Church-Turing thesis, -Turing complete languages are as expressive as possible in some sense. - -Is there a trade-off? What types of problems can occur with uncomputable problems and programs whose validity may be undecidable? - -As smart contracts subsume parts of contract law, consider the large body of laws and regulations for tax law. - -For instance, US tax law and regulations take up several million words. International tax law and regulations pushes these numbers much higher. - -Are these laws and regulations programs or are they data? If tax law were to be written in a Turing complete language, then the law may codify uncomputable problems. It is an accountant’s nightmare for their advice to be undecidable. - -Clarity is non-Turing complete, yet very expressive. This makes it so that Clarity is decidable and cannot encode uncomputable problems. There are discussions and papers on smart contract languages such as Solidity that propose subsets of Solidity that are non-Turing complete. These subsets are decidable and cannot encode uncomputable problems. However, there is no consensus on which subsets to work with and they are not widely used. - -## Advantages of Decidability in Smart Contracts - -Why is decidability important in the context of smart contracts? - -First, it is not possible for a Clarity call to run out of gas in the middle of a call. Because of its decidability, it is possible to get a complete static analysis of the call graph to get an accurate picture of the cost before execution. - -Solidity allows for unbounded loops, recursion, and dynamic function calls, which makes it difficult to accurately predict the execution cost or gas usage beforehand. As a result, Solidity contracts may run out of gas during execution if the gas limit is not set appropriately or if the contract encounters a scenario with unexpectedly high computational requirements. - -One practical example is the issue of a specific kind of DoS attack in Solidity, where the contract is rendered inoperable because of unbounded execution constraints. An example of this is the GovernMental attack, where a mapping that needed to be deleted for a payout became so large that working with it exceeded the block gas limit. - -There are a few different properties of Clarity's language design that prevents such DoS attacks. - -The reason that the analysis system can accurately estimate the execution cost is because certain functionality is intentionally limited in Clarity. - -For example, there is no recursion in Clarity, so we can't infinitely call into a function over and over. - -Data types in Clarity are also restricted. Any data types that don't require a hard length limit are not iterable. - -Maps and tuples, for example, do not require you to enter a maximum length when defining them, but you also can't iterate over them. - -Lists, on the other hand, which are iterable, do require the developer to define an upper limit when defining them. This is a large part of what allows an accurate static analysis of Clarity contracts. - -So how would we implement a mapping of an undefined size in Clarity? We wouldn't, because it's an anti-pattern in smart contract design. - -Instead, Clarity forces us to think of a better solution to our problem. For example, implementing a way for users to handle mapping/list element operations themselves, instead of mass operations handled at the contract level. - -If you [analyze the GovernMental attack](https://hackernoon.com/smart-contract-attacks-part-2-ponzi-games-gone-wrong-d5a8b1a98dd8#h-attack-2-call-stack-attack), you'll see that it took advantage of multiple security issues, all of which are mitigated in Clarity. You'll also see that a fix was added to make it economically infeasible to carry out this type of attack again. - -This brings up another crucial point when setting appropriate mental models for smart contracts and blockchain systems: complexity means more potential bugs, which means adding more complexity to address those bugs. - -When this happens over and over again, we are trapping ourselves into creating an evermore complex system. Addressing these issues at the language level prevents this ever-growing complexity. - -For a deep dive into how Clarity was designed, check out [SIP-002](https://github.com/stacksgov/sips/blob/main/sips/sip-002/sip-002-smart-contract-language.md). - -:::note -You can view some more common smart contract vulnerabilities and how they are mitigated in [this article](https://stacks.org/bringing-clarity-to-8-dangerous-smart-contract-vulnerabilities/). -::: - -This has second-order effects as well when we look at security testing and auditing. One of the common tools for testing smart contracts is formal verification, where we mathematically prove that certain properties of smart contracts will or will not remain true in all cases. - -This can lead to the path explosion problem, where there are so many paths available that formal verification becomes incredibly difficult. This problem is mitigated in Clarity, since there is not chance of a program encountering an unbounded loop. - -This leads us to a more general mental model for thinking about decidability as smart contracts continue to become a larger part of our economy. Remember that the goal with blockchain systems is to create an open, transparent, fair financial system. - -This means that smart contracts will be responsible for managing large amounts of wealth for ever-growing amounts of people. As smart contracts encompass more financial structures, their complexity and usage will grow. - -Complexity is the enemy of security. The more complex a system is, the more danger there is in creating uncomputable problems when there are no hard restrictions on the execution steps that can be taken. - -This is deadly in financial infrastructure that is not only open and transparent, but immutable. Let's explore this idea of uncomputability a bit more. - -## Intuition on Uncomputability - -Intuitively, uncomputability is an algorithmic view of undecidability. Uncomputability has the same foundations as undecidability. Undecidable questions are framed as logic statements or statements about integers. Of course, programs are logic statements and may even be viewed as integers, though we view programs differently. We often view programs with additional details of memory models, implementation details, and execution semantics. - -The [Halting problem](https://en.wikipedia.org/wiki/Halting_problem#:~:text=In%20computability%20theory%2C%20the%20halting,or%20continue%20to%20run%20forever.): As an example, given any program `P` and any finite input `I` for `P`, then the Halting Problem is the challenge of determining if `P` halts on input `I`. - -Alonzo Church and Alan Turing showed the Halting Problem is unsolvable. - -Christopher Strachey gave an intuitive proof-by-contradiction showing the Halting problem is uncomputable. This is set up by supposing there is a program `H` that can solve the Halting problem for any program `P`. `H(P)` returns true if `P` halts and false otherwise. Then build a program `P` that does not halt when `H(P)` is true, giving a contradiction. Similarly, this program `P` halts when `H(P)` is false, also a contradiction. - -Uncomputable problems are problems that cannot be solved by an algorithm or a computer, no matter how much time or resources are provided. These problems exist in various forms, and one such example is the Post correspondence problem, which was proposed by Emil Post. - -The Post correspondence problem can be described using pairs of strings and an integer. Imagine you have n pairs of strings, called P. These strings are made up of characters from a character set, such as UTF-8 or any other alphabet with at least two symbols. The pairs of strings look like this: - -`P = { (x1, y1), (x2, y2), … , (xn, yn) }` - -Now, you also have an integer `m` that is greater than 0. The Post correspondence problem asks whether there is a way to create a list of indices `(i1, i2, …, im)` using the given pairs of strings. You can repeat these indices if needed, with one condition: when you combine the `x` strings from the pairs using the indices, the resulting string must be equal to the combined `y` strings from the same pairs using the same indices. In other words: - -`x(i1) x(i2) … x(im) = y(i1) y(i2) … y(im)` - -When developers try to solve the Post correspondence problem, they often attempt to use indeterminate loops (loops without a fixed number of iterations) rather than recursion. This is because the problem seems to require searching through different combinations of indices until a solution is found or it's proven that no solution exists. - -In simple terms, the Post correspondence problem involves trying to find a sequence of indices that, when applied to the given pairs of strings, produces equal concatenated strings from both the `x` and `y` components. This problem is considered uncomputable because there is no general algorithm that can solve it for all possible input pairs of strings and integers. - -It turns out, many questions about how programs behave are uncomputable. This has a number of consequences for smart contracts that are built in Turing complete languages, many of which we are not aware of yet but will surely become aware of as we encounter them in the future. - -## Raymond Smullyan’s Intuition on Undecidability - -This is a part of Raymond Smullyan’s approach to understanding undecidability in propositional logic. It uses meta-information to show something must be true, though it cannot be proved in propositional logic. This is based on a paradox. - -In propositional logic, a logical statement is undecidable if we cannot prove it true or false. -Given a propositional logic statement S, a proof is a sequence of formal logical deductions, starting from basic facts and ending by indicating if S is true or false. - -Smullyan’s starts with an island of Knights and Knaves. Knights always tell the truth. Knaves always lie. We cannot distinguish islanders otherwise. - -There is a great logician named Ray. Whatever Ray proves is true. This is just like a good theorem prover. - -An islander Jack proclaims: “You cannot prove I am a Knight” to the logician Ray. - -The next reasoning is based on meta-knowledge of this situation. This meta-knowledge shows that some problems are undecidable in propositional logic. - -If Ray can prove Jack is a Knight, then Jack must be a Knave, since Jack must have lied. That is because Ray proved Jack is a Knight. Since Jack is a Knave, Ray’s proof contradicts the assumption that Ray only proves true things. So, this case cannot hold. - -If Ray cannot prove Jack is a Knight, then Jack must be a Knight, since Jack stated the truth. But Ray cannot prove the fact that Jack is a Knight. - -In the context of smart contracts and programming languages, Turing complete languages like Solidity come with the possibility of undecidable problems. - -These undecidable problems are similar to the paradox presented in the Knights and Knaves story, where it's impossible to determine whether Jack is a Knight or a Knave based on the given information. - -In the Knights and Knaves story, Ray is analogous to a theorem prover or a smart contract in a Turing complete language. Ray is faced with a statement that is undecidable within the constraints of the system (Knights and Knaves), which leads to a paradox. - -Similarly, a Turing complete smart contract language might face undecidable problems that can't be resolved, leading to unexpected behavior, vulnerabilities, or resource consumption issues (like running out of gas in Ethereum). - -On the other hand, non-Turing complete languages like Clarity are designed to avoid undecidable problems by limiting their expressiveness. - -In the context of the Knights and Knaves story, a non-Turing complete language would simply not allow Jack to make a statement that could lead to a paradox. By disallowing certain features like unbounded loops and recursion, non-Turing complete languages can provide stronger guarantees about the behavior and resource usage of smart contracts. - -This predictability is desirable in many cases, especially when dealing with high-value transactions or critical systems. - -## Reference - -The Mathematics of Various Entertaining Subjects: Research in Recreational Math Illustrated Edition, Jennifer Beineke (Editor), Jason Rosenhouse (Editor), Raymond M. Smullyan (Foreword), Princeton University Press, 2016. diff --git a/docs/clarity/security/index.md b/docs/clarity/security/index.md deleted file mode 100644 index 90aa31abb4..0000000000 --- a/docs/clarity/security/index.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Clarity Security -description: Deep dives into the different security properties of Clarity -sidebar_label: Security -sidebar_position: 4 ---- - -Clarity has been purpose-built from the ground up to write safe, secure smart contracts. This gives a number of unique properties not seen in other smart contract languages like Solidity. - -If you are coming from a Solidity background, or wondering why you should bother learning a new language like Clarity, security is one of the top reasons. Every design decision for Clarity has been made with this in mind. - -This section will dive deeper into some of these concepts and properties to dig into the security advantages of using Clarity. - -We'll cover conceptual and practical examples, often comparing Clarity to similar functionality in Solidity to demonstrate the unique security advantages of Clarity. - -This section is a work in progress and [contributions are always welcome](../../contribute/). - -## Non-Turing Complete - -This is an often-discussed property of Clarity, and is in contrast to Solidity and most other languages, which are Turing-complete. Turing-completeness is often seen as an advantage and a necessity in fully-expressive languages, but it comes with some dangers and disadvantages that we'll explore in this section. - -[Read More](./decidable.md) diff --git a/docs/clarity/tools-new.png b/docs/clarity/tools-new.png deleted file mode 100644 index 094e36cc4f..0000000000 Binary files a/docs/clarity/tools-new.png and /dev/null differ diff --git a/docs/contribute/docs.md b/docs/contribute/docs.md deleted file mode 100644 index 1c08e25868..0000000000 --- a/docs/contribute/docs.md +++ /dev/null @@ -1,220 +0,0 @@ ---- -title: Contribute to docs -description: Learn how this site is built, and how you can contribute to it. ---- - -## Introduction - -Thank you for your interest in contributing and helping make these docs as good as they can be. - -This docs site is built on the open source platform [Docusaurus 2](https://docusaurus.io/) and most of its content is written in Markdown files. All of the code for this site is free and open source, located at the [GitHub repository here](https://github.com/stacks-network/docs). - -:::tip Don't know what Markdown is? -Want to learn? Here is a [helpful guide](https://guides.github.com/features/mastering-markdown/). - -Don't want to learn it? No need to. Write [in plain text an issue on Github](https://github.com/stacks-network/docs/issues/new?assignees=&labels=documentation&template=add-documentation.md&title=%5BAdd+docs%5D) -::: - -:::info -You need a free [Github](https://www.github.com) account to add or edit any content. -::: - -To edit any page, just click on the _Edit this page_ button at the bottom of each page and submit your changes online. - -To add new content, they are two different ways to do it, the [easy way](#easy-way) and the [advanced way](#advanced-way). - -## Easy way - -[**Simply click here and enter the text of the article you wish to add.**](https://github.com/stacks-network/docs/issues/new?assignees=&labels=documentation&template=add-documentation.md&title=%5BAdd+docs%5D) - -This will open up an issue on github using our template. - -## Advanced way - -For more advanced changes you can follow the next steps. - -You can also test the site locally using this method. - -### Steps - -1. Fork the [docs repository](https://github.com/stacks-network/docs) by clicking on the _Fork_ button in the upper right of the screen. -2. Clone your fork to your local machine with this command `git clone git@github.com:/docs.git stacks_docs` -3. Enter your project folder `cd stacks_docs` -4. Create a branch `git checkout -b feat/my-feature-branch`. -5. You can optionally preview your changes in real time with: - - `npm install` (to install dependencies). - - `npx docusaurus start` to start a local copy of the site. A web browser will open at http://localhost:3000, so you can see a preview of your changes in real time. -6. Make the changes you wish and then commit them with this kind of message: `git commit -am "feat: some new feature or content"`. -7. Push to to GitHub with `git push --set-upstream origin feature/my-feature-branch`. -8. Visit GitHub and make your pull request. - -## Additional information - -### Running and building the site locally (optional) - -You can start the page locally with the following command. This is enough to preview your changes. - -```bash -npx docusaurus start -``` - -Before running this command for the first time you will need to run `npm install` to install dependencies. - -The docs site will be accessible at this url: [`http://localhost:3000`](http://localhost:3000). - -After you finished your changes, you can also build the entire site with the following command (not usually needed): - -```bash -npm run build -``` - -:::tip -`npx docusaurus start` will only load the default language (english). To test all languages you can build with `npm run build` and then preview your build with `npm run serve`. -::: - -### An alternative: Working in browser - -As an alterative to working locally, you can also use the web IDE gitpod that provides an environment to contribute directly from within your browser. - -You only need to have a github account and open [this link](https://gitpod.io/#https://github.com/stacks-network/docs). - -### Folder structure of the site - -If you are interested in only adding new documentation content to the site, the files that will be important to you are located within `./docs/*`: - -```bash -docs/ - build-apps - contribute/ - faq/ - gaia/ - nodes-and-miners/ - noteworthy-contracts/ - references/ - understand-stack/ - write-smart-contracts/ -``` - -The routing for this site is file based, meaning if you created a folder within `/docs/gaia/` named `testing` and in it a file named `test1.md`, you would be able to navigate to `http://localhost:3000/gaia/testing/test1` and you would see whatever content is in that markdown file. - -All the docs in English are stored in the folder `/docs/`. - -To add new English content simply add a markdown file (.md) into any subfolder in docs, and it will be automatically displayed in the category of that folder. - -All the docs in other languages are stored under the folder `i18n`, but these files should never be edited using GitHub as they are overwritten by Crowdin every time new translations are added. **To make changes in other languages**, you must do so using Crowdin. -Please refer to [translations](translations) instead. - -### Frontmatter - -Frontmatter is the top part of any markdown document that is written in a language called [YAML](https://yaml.org/). It looks like this: - -```yaml ---- -title: This is my page title -description: A short, concise sentence describing what is on this page ---- -``` - -Frontmatter gives us the ability to define some things within a page that the site can use, such as a page title or page description. -When adding any new page, please include a `title` and `description`. - - - -### Use Conventional Commits - -We use the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) as and commits naming convention. Use it while contributing, please. - -### Code blocks - -To write a code block, you need to wrap your code in ` ```language `, and end your code block with ` ``` `. Here is an example of ` ```clarity `. - -```clarity -(define-data-var counter int 0) - -(define-public (get-counter) - (ok (var-get counter))) -``` - -### Admonitions - -You can use the following admonitions to highlight content. - -```md -:::note -Some **content** with _markdown_ `syntax`. -::: - -:::tip -Some **content** with _markdown_ `syntax`. -::: - -:::info -Some **content** with _markdown_ `syntax`. -::: - -:::caution -Some **content** with _markdown_ `syntax`. -::: - -:::danger -Some **content** with _markdown_ `syntax`. -::: - -:::tip My personalized title -Some **content** with _markdown_ `syntax`. -::: -``` - -Which renders: - -:::note - -Some **content** with _markdown_ `syntax`. - -::: - -:::tip - -Some **content** with _markdown_ `syntax`. - -::: - -:::info - -Some **content** with _markdown_ `syntax`. - -::: - -:::caution - -Some **content** with _markdown_ `syntax`. - -::: - -:::danger - -Some **content** with _markdown_ `syntax`. - -::: - -:::tip My personalized title - -Some **content** with _markdown_ `syntax`. - -::: diff --git a/docs/contribute/index.md b/docs/contribute/index.md deleted file mode 100644 index ac81d899bd..0000000000 --- a/docs/contribute/index.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Contribute -description: Contribute to the Stacks ecosystem. -sidebar_position: 10 -sidebar_label: "Contribute" ---- - -You can contribute to the Stacks ecosystem in multiple ways: - - - -### Documentation - -Contribute to the Stacks Docs on this website. More info [here](docs). - -### Translations - -Help us reach more people with translations. More details [here](translations). - - - -### Articles - -Write an article or a blog post about Stacks. A good place to start is [Stacks Forum](https://forum.stacks.org). - -### Github - -If you are familiar with Github they are multiple repositories of the Stack Ecosystem that you can contribute to. - -- https://github.com/stacks-network/ diff --git a/docs/contribute/translations.md b/docs/contribute/translations.md deleted file mode 100644 index bb2e9d95e2..0000000000 --- a/docs/contribute/translations.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Contribute with translations -description: Want to help translating these docs to your local language? ---- - -## Help with translations - -Translations are managed with Crowdin. -Anybody can collaborate and no technical skills are required, as it's all done on the browser. - -To help with translation please go to [this page](https://crowdin.com/project/docsstacksco), click any language and start translating. - -All help is appreciated. - -:::caution -Please don't add any translations to the Github repository, as the translated pages get rewritten from Crowdin. Translations need to be added on Crowdin instead. -::: - -### Common issues on translations - -When translating in Crowdin, please only translate the texts and not the html code. - -If you accidentally modify the html tags you will get errors like shown below (`Seems like some formatting tags are missing` or `Translation contains tag that source text doesn't have`). These errors will prevent your translation getting published until the tags are left as they were in the original text. - -![](/img/crowdin-qa-issue-formatting_tags_missing.png) -![](/img/crowdin-qa-issue-tag_source.png) diff --git a/docs/cookbook/creating-an-ft.md b/docs/cookbook/creating-an-ft.md deleted file mode 100644 index 4e3bad99d2..0000000000 --- a/docs/cookbook/creating-an-ft.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Creating a Fungible Token -description: Clarity and Stacks.js code required to make a FT ---- - -Much the same as creating an NFT, Clarity also makes creating a fungible token (FT) trivial as well. - -The process and code are much the same. - -## Trait - -Just like with the NFT, it's a good idea to create a trait when you create a fungible token so that different tools and protocols and be confident in building interfaces for those tokens. - -Since FTs may be divisible, the [FT official mainnet deployment trait address](https://explorer.stacks.co/txid/0x99e01721e57adc2c24f7d371b9d302d581dba1d27250c7e25ea5f241af14c387?chain=mainnet) has additional functions. - -```clarity -(define-trait sip-010-trait - ( - ;; Transfer from the caller to a new principal - (transfer (uint principal principal (optional (buff 34))) (response bool uint)) - - ;; the human readable name of the token - (get-name () (response (string-ascii 32) uint)) - - ;; the ticker symbol, or empty if none - (get-symbol () (response (string-ascii 32) uint)) - - ;; the number of decimals used, e.g. 6 would mean 1_000_000 represents 1 token - (get-decimals () (response uint uint)) - - ;; the balance of the passed principal - (get-balance (principal) (response uint uint)) - - ;; the current total supply (which does not need to be a constant) - (get-total-supply () (response uint uint)) - - ;; an optional URI that represents metadata of this token - (get-token-uri () (response (optional (string-utf8 256)) uint)) - ) -) -``` - -Now let's see how we might implement this in Clarity, just like we would an NFT. - -## Clarity Code - -```clarity -(impl-trait 'SP3FBR2AGK5H9QBDH3EEN6DF8EK8JY7RX8QJ5SVTE.sip-010-trait-ft-standard.sip-010-trait) - - -(define-constant contract-owner tx-sender) -(define-constant err-owner-only (err u100)) -(define-constant err-not-token-owner (err u101)) - -;; No maximum supply! -(define-fungible-token clarity-coin) - -(define-public (transfer (amount uint) (sender principal) (recipient principal) (memo (optional (buff 34)))) - (begin - (asserts! (is-eq tx-sender sender) err-not-token-owner) - (try! (ft-transfer? clarity-coin amount sender recipient)) - (match memo to-print (print to-print) 0x) - (ok true) - ) -) - -(define-read-only (get-name) - (ok "Clarity Coin") -) - -(define-read-only (get-symbol) - (ok "CC") -) - -(define-read-only (get-decimals) - (ok u6) -) - -(define-read-only (get-balance (who principal)) - (ok (ft-get-balance clarity-coin who)) -) - -(define-read-only (get-total-supply) - (ok (ft-get-supply clarity-coin)) -) - - -(define-read-only (get-token-uri) - (ok none) -) - - -(define-public (mint (amount uint) (recipient principal)) - (begin - (asserts! (is-eq tx-sender contract-owner) err-owner-only) - (ft-mint? clarity-coin amount recipient) - ) -) -``` diff --git a/docs/cookbook/creating-an-nft.md b/docs/cookbook/creating-an-nft.md deleted file mode 100644 index 851189579e..0000000000 --- a/docs/cookbook/creating-an-nft.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: Creating an NFT -description: Clarity and Stacks.js code required to make an NFT ---- - -Clarity makes creating NFTs incredibly easy. With built-in functions for creating and working with the token, you can have an NFT created in less than 10 minutes of work. - -Let's see how. - -:::tip -For a more in-depth discussion of NFTs in Clarity and how to create them, check out the [NFTs chapter in the Clarity book](https://book.clarity-lang.org/ch10-01-sip009-nft-standard.html). -::: - -## Trait - -The first thing we need when we create an NFT is a trait. A trait is an interface that allows us to create an NFT with a defined set of functions. Its primary purpose is to ensure that NFTs are composable and different tools know how to interact with them. - -By implementing a trait that the community agrees on, all protocols and products know how they can interact with an NFT. - -The official mainnet trait can be [found on the Stacks Explorer](https://explorer.stacks.co/txid/0x80eb693e5e2a9928094792080b7f6d69d66ea9cc881bc465e8d9c5c621bd4d07?chain=mainnet) and looks like this: - -```clarity -(define-trait nft-trait - ( - ;; Last token ID, limited to uint range - (get-last-token-id () (response uint uint)) - - ;; URI for metadata associated with the token - (get-token-uri (uint) (response (optional (string-ascii 256)) uint)) - - ;; Owner of a given token identifier - (get-owner (uint) (response (optional principal) uint)) - - ;; Transfer from the sender to a new principal - (transfer (uint principal principal) (response bool uint)) - ) -) -``` - -All we are doing here is defining the function signatures for functions we'll need to implement in out Clarity contract, which we can see a simple version of below. - -## Clarity Code - -This is the Clarity code we need in order to create an NFT, with one additional function, `mint` that allows us to actually create a new NFT. This `mint` function is not needed to adhere to the trait. - -```clarity -(impl-trait 'SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9.nft-trait.nft-trait) - -(define-non-fungible-token amazing-aardvarks uint) - -(define-data-var last-token-id uint u0) - -(define-constant contract-owner tx-sender) -(define-constant err-owner-only (err u100)) -(define-constant err-not-token-owner (err u101)) - -(define-read-only (get-last-token-id) - (ok (var-get last-token-id)) -) - -(define-read-only (get-token-uri (token-id uint)) - (ok none) -) - -(define-read-only (get-owner (token-id uint)) - (ok (nft-get-owner? amazing-aardvarks token-id)) -) - -(define-public (transfer (token-id uint) (sender principal) (recipient principal)) - (begin - (asserts! (is-eq tx-sender sender) err-not-token-owner) - (nft-transfer? amazing-aardvarks token-id sender recipient) - ) -) - -(define-public (mint (recipient principal)) - (let - ( - (token-id (+ (var-get last-token-id) u1)) - ) - (asserts! (is-eq tx-sender contract-owner) err-owner-only) - (try! (nft-mint? amazing-aardvarks token-id recipient)) - (var-set last-token-id token-id) - (ok token-id) - ) -) -``` diff --git a/docs/cookbook/get-sats-per-stx.md b/docs/cookbook/get-sats-per-stx.md deleted file mode 100644 index d6ef942f94..0000000000 --- a/docs/cookbook/get-sats-per-stx.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: Get Sats per STX Price -description: Use built-in Clarity functions to retrieve the on-chain exchange rate between BTC and STX ---- - -Utilizing the built-in Clarity function `get-block-info?` we can create what is essentially an on-chain Bitcoin price oracle. We can do this by taking the amount of Bitcoin spent by miners and the block reward earned by those miners to get the sats per stx ratio. - -Let's see how to do this. - -```clarity -(define-read-only (get-sats-per-stx (block uint)) - (let - ( - (miner-spend (unwrap! (get-block-info? miner-spend-winner block) (err "no miner spend"))) - (block-reward (unwrap! (get-block-info? block-reward block) (err "no block reward"))) - (sats-per-stx (/ miner-spend block-reward)) - ) - (ok sats-per-stx) - ) -) -``` - -Here we are defining a read-only function. - -If we deploy this function up to testnet, we can run it in the sandbox. - -I actually have deployed this and you can check it out on the explorer and pass in whatever block you want to get the sats/stx ratio. diff --git a/docs/cookbook/index.md b/docs/cookbook/index.md deleted file mode 100644 index 9a40e62b46..0000000000 --- a/docs/cookbook/index.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Cookbook -description: Code snippets and examples for building Stacks apps -sidebar_label: Cookbook -sidebar_position: 7 ---- - -The Stacks Cookbook is a collection of sample apps and smart contracts to serve as starting points and references for building your own Stacks apps. It is currently a work in progress. Here is some of the content we have planned and we welcome [contributions](../contribute/). - -Many of these cookbook recipes have been pulled from other tutorials and linked here for easy access. Links to full tutorials and sample code have been included for reference and further exploration. - -Got an idea you think would make a good addition? We're always [accepting contributions](../contribute/). - -## Bitcoin Integration - -[Sending Bitcoin with Hiro wallet](./sending-bitcoin-with-hiro-wallet.md) - -Getting a Stacks address from a public key - -[Verifying a transaction on the BTC chain](./verifying-a-btc-tx-was-mined.md) - -Get Sats per STX price - -[Parsing a Bitcoin transaction](./parse-a-btc-tx.md) - -## DAOs - -Creating a simple DAO with ExecutorDAO - -Creating a BTC-backed DAO treasury - -## Tokens - -[Creating an NFT](./creating-an-nft) - -[Creating a Fungible Token](./creating-an-ft.md) - -Minting an NFT with Bitcoin - -## Stacking and Mining - -Simple stacking pool - -Continuous stacking - -Simple mining pool - -Proof of PoX payout - -## Frontend - -[Post conditions with Stacks.js](./post-conditions) - -[Authentication with Stacks.js](./stacks-js-auth) - -[Sending transactions with Stacks.js](./stacks-js-sending-transactions) - -Authenticating with Sign in with Stacks - -## Complete Apps - -[Sup](https://github.com/kenrogers/sup) - -[Hello Stacks](https://github.com/kenrogers/hello-stacks) diff --git a/docs/cookbook/parse-a-btc-tx.md b/docs/cookbook/parse-a-btc-tx.md deleted file mode 100644 index f42dcee690..0000000000 --- a/docs/cookbook/parse-a-btc-tx.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Parse the Data from a Bitcoin Transaction -description: Use the Clarity-Bitcoin library to parse a Bitcoin transaction ---- - -While we can verify that a transaction was mined using a library and Clarity's built-in functions, as outlined in the [Verifying a transaction on the BTC chain](./verifying-a-btc-tx-was-mined.md) docs, we can parse a Bitcoin transaction using Clarity as well. - -This doesn't actually require having access to the chain, all we need is the raw transaction hex. - -If you aren't familiar with how Bitcoin transactions are encoded in raw form, take a quick look at that. - -The short version is that all of the data from a Bitcoin transaction is encoded in hex form in a string of numbers, we can slice out pieces of that hex value to pull out all of our transaction data. - -The process to do this is relatively complex, but the Clarity-Bitcoin library comes with a function called `parse-tx` that makes this simple. - -All we need to do is pass it a raw transaction hex and we can get back the data of the transaction, including inputs and outputs. - -:::caution -Note that currently the library only supports legacy transactions, although work to support segwit and taproot transactions is currently underway. -::: - -You can view a [deployed version of the library](https://explorer.hiro.so/txid/0xd493b9ada8899be8773d3f55b21d300ef83ac5c0dd38c8a4dd52a295bd71d539?chain=mainnet) on the explorer and the [GitHub repo here](https://github.com/friedger/clarity-bitcoin). - -The `parse-tx` function looks like this. - -```clarity -(define-read-only (parse-tx (tx (buff 1024))) - (let ((ctx { txbuff: tx, index: u0}) - (parsed-version (try! (read-uint32 ctx))) - (parsed-txins (try! (read-txins (get ctx parsed-version)))) - (parsed-txouts (try! (read-txouts (get ctx parsed-txins)))) - (parsed-locktime (try! (read-uint32 (get ctx parsed-txouts))))) - (ok {version: (get uint32 parsed-version), - ins: (get txins parsed-txins), - outs: (get txouts parsed-txouts), - locktime: (get uint32 parsed-locktime)}))) -``` - -We can get the raw transaction hex from a Bitcoin block explorer API like mempool, and it will be returned back to use looking something like this: - -`0200000000010196277c04c986c1ad78c909287fd12dba2924324699a0232e0533f46a6a3916bb0100000000ffffffff026400000000000000160014274ae586ad2035efb4c25049c155f98310d7e106ca16440000000000160014599bcef6387256c6b019030c421b4a4d382fe2600247304402204d94a1e4047ca38a450177ccb6f88585ca147f1939df343d8ac5d962c5f35bb302206f7fa42c21c47ebccdc460393d35c5dfd3b6f0a26cf10fac23d3e6fab71835c20121020cb972a66e3fb1cdcc9efcad060b4457ebec534942700d4af1c0d82a33aa13f100000000`. - -You can paste this into a raw transaction decoder like [this one](https://live.blockcypher.com/btc/decodetx/) and see the data. - -If we were using stacks.js, we would just need to pass this to our function as a buffer like this: - -```javascript -bufferCV(Buffer.from(txRaw, "hex")); -``` - -Where `txRaw` is just a string containing our raw transaction. When we do that, we are presented with the data of the transaction. - -We can then take that data and pull out whatever we need from it. diff --git a/docs/cookbook/post-conditions.md b/docs/cookbook/post-conditions.md deleted file mode 100644 index 571fc20d48..0000000000 --- a/docs/cookbook/post-conditions.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -title: Post Conditions -description: Working with Stacks post conditions ---- - -The content in this recipe has ben pulled from the [tutorial on post conditions](https://dev.to/stacks/understanding-stacks-post-conditions-e65). Post conditions are an additional safety feature built into the Stacks chain itself that help to protect end users. - -Rather than being a function of Clarity smart contracts, they are implemented on the client side and meant to be an additional failsafe against malicious contracts. - -Put simply, post conditions are a set of conditions that must be met before a user's transaction will execute. The primary goal behind post conditions is to limit the amount of damage that can be done to a user's assets due to a bug, intentional or otherwise. - -So they are sent as part of the transaction when the user initiates it, meaning we need a frontend library to utilize them. - -Whenever you are transferring an asset (fungible or non-fungible) from one address to another, you should taker advantage of post conditions. - -We're going to use [Stacks.js](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions#post-conditions) to familiarize ourselves with them. - -## STX Post Condition - -```js -import { - FungibleConditionCode, - makeStandardSTXPostCondition, - makeContractSTXPostCondition, -} from "@stacks/transactions"; - -// With a standard principal -const postConditionAddress = "SP2ZD731ANQZT6J4K3F5N8A40ZXWXC1XFXHVVQFKE"; -const postConditionCode = FungibleConditionCode.GreaterEqual; -const postConditionAmount = 12345n; - -const standardSTXPostCondition = makeStandardSTXPostCondition( - postConditionAddress, - postConditionCode, - postConditionAmount -); - -// With a contract principal -const contractAddress = "SPBMRFRPPGCDE3F384WCJPK8PQJGZ8K9QKK7F59X"; -const contractName = "test-contract"; - -const contractSTXPostCondition = makeContractSTXPostCondition( - contractAddress, - contractName, - postConditionCode, - postConditionAmount -); -``` - -## Fungible Token Post Condition - -```js -import { - FungibleConditionCode, - createAssetInfo, - makeStandardFungiblePostCondition, -} from "@stacks/transactions"; - -// With a standard principal -const postConditionAddress = "SP2ZD731ANQZT6J4K3F5N8A40ZXWXC1XFXHVVQFKE"; -const postConditionCode = FungibleConditionCode.GreaterEqual; -const postConditionAmount = 12345n; -const assetAddress = "SP62M8MEFH32WGSB7XSF9WJZD7TQB48VQB5ANWSJ"; -const assetContractName = "test-asset-contract"; -const fungibleAssetInfo = createAssetInfo(assetAddress, assetContractName); - -const standardFungiblePostCondition = makeStandardFungiblePostCondition( - postConditionAddress, - postConditionCode, - postConditionAmount, - fungibleAssetInfo -); - -// With a contract principal -const contractAddress = "SPBMRFRPPGCDE3F384WCJPK8PQJGZ8K9QKK7F59X"; -const contractName = "test-contract"; -const assetAddress = "SP62M8MEFH32WGSB7XSF9WJZD7TQB48VQB5ANWSJ"; -const assetContractName = "test-asset-contract"; -const fungibleAssetInfo = createAssetInfo(assetAddress, assetContractName); - -const contractFungiblePostCondition = makeContractFungiblePostCondition( - contractAddress, - contractName, - postConditionCode, - postConditionAmount, - fungibleAssetInfo -); -``` - -## NFT Post Condition - -```js -import { - NonFungibleConditionCode, - createAssetInfo, - makeStandardNonFungiblePostCondition, - makeContractNonFungiblePostCondition, - bufferCVFromString, -} from "@stacks/transactions"; - -// With a standard principal -const postConditionAddress = "SP2ZD731ANQZT6J4K3F5N8A40ZXWXC1XFXHVVQFKE"; -const postConditionCode = NonFungibleConditionCode.Owns; -const assetAddress = "SP62M8MEFH32WGSB7XSF9WJZD7TQB48VQB5ANWSJ"; -const assetContractName = "test-asset-contract"; -const assetName = "test-asset"; -const tokenAssetName = bufferCVFromString("test-token-asset"); -const nonFungibleAssetInfo = createAssetInfo( - assetAddress, - assetContractName, - assetName -); - -const standardNonFungiblePostCondition = makeStandardNonFungiblePostCondition( - postConditionAddress, - postConditionCode, - nonFungibleAssetInfo, - tokenAssetName -); - -// With a contract principal -const contractAddress = "SPBMRFRPPGCDE3F384WCJPK8PQJGZ8K9QKK7F59X"; -const contractName = "test-contract"; - -const contractNonFungiblePostCondition = makeContractNonFungiblePostCondition( - contractAddress, - contractName, - postConditionCode, - nonFungibleAssetInfo, - tokenAssetName -); -``` - -## Sample App - -Here's a [sample application](https://github.com/kenrogers/fabulous-frogs) that utilizes post conditions on the front end to secure user assets. diff --git a/docs/cookbook/sending-bitcoin-with-hiro-wallet.md b/docs/cookbook/sending-bitcoin-with-hiro-wallet.md deleted file mode 100644 index fda05f7356..0000000000 --- a/docs/cookbook/sending-bitcoin-with-hiro-wallet.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Sending Bitcoin with Hiro Wallet -description: Initiate a basic Bitcoin transaction with the Hiro wallet ---- - -Using Hiro's web wallet, we can easily initiate a simple Bitcoin transaction using only a few lines of code. - -You'll need to be authenticated with the Hiro wallet for this to work, with you can see how to do in the [Authentication with Stacks.js](./stacks-js-auth) recipe. - -Once you have the wallet hooked up, you can use the Hiro wallet API to initiate a simple Bitcoin transaction in your JS app like this. - -```javascript -const sendBitcoin = async () => { - const resp = await window.btc?.request("sendTransfer", { - address: "tb1qya9wtp4dyq67ldxz2pyuz40esvgd0cgx9s3pjl", //replace this with whatever address you want to send to - amount: "10000", // the amount you want to send denoted in satoshis - }); - - // Storing txid in local storage - // We'll get back the transaction IF, which we can then use to do whatever we want - if (typeof window !== "undefined") { - localStorage.setItem("txid", JSON.stringify(resp.result.txid)); - } - - // We may want to do something once this transaction has confirmed, so we can set it to pending here and then use an API like mempool.space to query the Bitcoin chain for information about this transaction - localStorage.setItem("txStatus", "pending"); -}; -``` - -Then all we would do is hook up our button to call this `sendBitcoin` function. - -```javascript - -``` - -You can take a look at the [Verifying a transaction on the BTC chain](./verifying-a-btc-tx-was-mined.md) recipe to see a more complex user flow of verifying a transaction was mined using this returned ID as a starting point. - -You can take a look at a bit more info about this simple API on the [Hiro wallet developer docs](https://hirowallet.gitbook.io/developers/bitcoin/sign-transactions/sending-bitcoin). diff --git a/docs/cookbook/stacks-js-auth.md b/docs/cookbook/stacks-js-auth.md deleted file mode 100644 index 89d1f06e00..0000000000 --- a/docs/cookbook/stacks-js-auth.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: Authentication with Stacks.js -description: Authenticating a user with Stacks.js ---- - -Authenticating with a Stacks wallet is a very common task when building Stacks dapps. - -Let's see how to set this up on the front end. - -Code here is pulled from the [Hello Stacks](../tutorials/hello-stacks.md) tutorial. - -## Stacks.js Code - -We're using React here, but you can modify this for whatever frontend code you are using. - -Before you add the frontend code, you need to install the correct NPM package. - -```bash -yarn add @stacks/connect -``` - -And here's the JS code we'll need to implement. - -```js -import { - AppConfig, - UserSession, - AuthDetails, - showConnect, -} from "@stacks/connect"; -import { useState, useEffect } from "react"; - -function App() { - const [message, setMessage] = useState(""); - const [transactionId, setTransactionId] = useState(""); - const [currentMessage, setCurrentMessage] = useState(""); - const [userData, setUserData] = useState(undefined); - - const appConfig = new AppConfig(["store_write"]); - const userSession = new UserSession({ appConfig }); - - const appDetails = { - name: "Hello Stacks", - icon: "https://freesvg.org/img/1541103084.png", - }; - - const connectWallet = () => { - showConnect({ - appDetails, - onFinish: () => window.location.reload(), - userSession, - }); - }; - - useEffect(() => { - if (userSession.isSignInPending()) { - userSession.handlePendingSignIn().then((userData) => { - setUserData(userData); - }); - } else if (userSession.isUserSignedIn()) { - setUserData(userSession.loadUserData()); - } - }, []); - - return ( -
- -

Hello Stacks

-
- ); -} - -export default App; -``` - -This is all the code we need to authenticate and access the user data in the UI. - -But how do we actually use it? - -Let's implement a `connectWallet` button to see how we can utilize the data we're pulling here. - -```js -{ - !userData && ( - - ); -} -``` diff --git a/docs/cookbook/stacks-js-sending-transactions.md b/docs/cookbook/stacks-js-sending-transactions.md deleted file mode 100644 index 849c7d1f42..0000000000 --- a/docs/cookbook/stacks-js-sending-transactions.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: Sending Transactions with Stacks.js -description: Sending transactions with Stacks.js ---- - -Any Stacks dapp is going to require sending transaction at some point, so how do we do that? We use the `@stacks/transactions` package. - -Again, this particular snippet is pulled from our [Hello Stacks](../tutorials/hello-stacks.md) tutorial. - -When you send Stacks transactions, don't forget to utilize [post conditions](./post-conditions.md). - -But first, you'll need to install the right NPM package. - -```bash -yarn add @stacks/transactions -``` - -## Stacks.js Frontend Code - -Assuming you are [authenticated](./stacks-js-auth.md), you'll need to import from the `network` package to connect and import the right Clarity values to convert. - -You need to convert values from JS into the right format for Clarity values to ingest. You can view the complete list of types on the [Stacks.js docs](https://stacks.js.org/modules/_stacks_transactions#constructing-clarity-values). - -```js -import { StacksMocknet } from "@stacks/network"; -import { stringUtf8CV } from "@stacks/transactions"; -``` - -Let's assume we have a message that we need to send. - -``` -Hello this is something I need to say. -``` - -```js -const submitMessage = async (e) => { - e.preventDefault(); - - const network = new StacksMocknet(); - - const options = { - contractAddress: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM", - contractName: "hello-stacks", - functionName: "write-message", - functionArgs: [stringUtf8CV(message)], - network, - appDetails, - onFinish: ({ txId }) => console.log(txId), - }; - - await openContractCall(options); -}; -``` - -For more details on the different types of transactions you can send, the [Stacks.js docs](https://stacks.js.org/modules/_stacks_transactions) have multiple examples. diff --git a/docs/cookbook/verifying-a-btc-tx-was-mined.md b/docs/cookbook/verifying-a-btc-tx-was-mined.md deleted file mode 100644 index fbbdbd98b4..0000000000 --- a/docs/cookbook/verifying-a-btc-tx-was-mined.md +++ /dev/null @@ -1,195 +0,0 @@ ---- -title: Verifying a BTC Transaction was Mined -description: Using Clarity to verify that a Bitcoin transaction was actually mined in the blockchain ---- - -One of the coolest things about Clarity is that it allows us to have visibility into the state of the Bitcoin blockchain. Since Stacks blocks are mined in lockstep with Bitcoin blocks, we can directly read the burnchain header info of each Bitcoin block using Clarity's built-in [`get-burn-block-info?`](https://docs.stacks.co/docs/clarity/language-functions#get-burn-block-info-clarity2) function. - -There are quite a few relatively complex things that need to happen to do this successfully, but a [clarity-bitcoin library](https://github.com/friedger/clarity-bitcoin/) exists to make the process a lot easier and handle some of the heavy lifting for us. - -Let's take a look at how to verify a Bitcoin transaction was mined using Clarity using the library. If you take a look at the `clarity-bitcoin.clar` file in the linked repo, you'll find a function called `was-tx-mined-compact`. That's what we'll be working with, and it looks like this: - -```clarity -(define-read-only (was-tx-mined-compact (height uint) (tx (buff 1024)) (header (buff 80)) (proof { tx-index: uint, hashes: (list 14 (buff 32)), tree-depth: uint})) - (let ((block (unwrap! (parse-block-header header) (err ERR-BAD-HEADER)))) - (was-tx-mined-internal height tx header (get merkle-root block) proof))) -``` - -The transaction itself is relatively simple, but there's a lot happening within other private function calls. I encourage you to read the contract for yourself and trace what is happening, step-by-step, when we call this function. - -For now, we'll just go over how to actually call this function successfully. - -You can see that it takes a few pieces of information: - -- `(height uint)` the block height you are looking to verify the transaction within -- `(tx (buff 1024))` the raw transaction hex of the transaction you are looking to verify -- `(header (buff 80))` the block header of the block -- `(proof { tx-index: uint, hashes: (list 14 (buff 32)), tree-depth: uint})` a merkle proof formatted as a tuple - -:::info - -A Merkle proof is a compact way to prove that a transaction is included in a block in the Bitcoin blockchain. Here's how it works: - -1. Transactions in a block are hashed and paired, then the hashes of the pairs are hashed and paired, and so on until a single hash remains - this is called the Merkle root. -2. The Merkle root is included in the block header. By providing the hashes that lead from a transaction's hash up to the Merkle root, along with the block header, one can prove that the transaction is included in that block. -3. These hashes that connect a transaction to the Merkle root are called the Merkle proof or Merkle path. By providing the Merkle proof along with the transaction hash and block header, anyone can verify that the transaction is part of that block. -4. This allows for efficient decentralized verification of transactions without having to download the entire blockchain. One only needs the transaction hash, Merkle proof, and block header to verify. - -::: - -Once we have this information, we can call into the `clarity-bitcoin.clar` contract and pass in this data. A common practice would be to get this data from a Bitcoin block explorer API like Mempool.space or Blockstream's esplora, parse it into the correct format for this helper, and then pass it to this function. - -We could do that directly via this contract if we just need a direct response on if the transaction was included or not, but more likely we would want to integrate this functionality into a Clarity contract of our own where we can `asserts!` that a transaction was mined before taking another action. - -Here's a basic example where we are calling [Blockstream's API](https://github.com/Blockstream/esplora/blob/master/API.md) using JavaScript, parsing the data into the right format, and then calling into our own `mint` function to only mint an NFT if the selected transaction was mined. - -We can get all the information we need with nothing but the transaction ID, which will usually be passed to us when we use a wallet like [Hiro's web wallet](https://hirowallet.gitbook.io/developers/bitcoin/sign-transactions/sending-bitcoin) to initiate the Bitcoin transaction. - -Let's go through the code we can use to implement this. For full context, this code is taken from the example [bitbadge](https://github.com/kenrogers/bitbadge) repo, which you can take a look at. For a complete ste-by-step walkthrough of how to implement this, check out the [Bitcoin Primer](https://bitcoinprimer.dev). - -Here's the mint function: - -```clarity -(define-public (mint (recipient principal) (height uint) (tx (buff 1024)) (header (buff 80)) (proof { tx-index: uint, hashes: (list 14 (buff 32)), tree-depth: uint})) - (let - ( - (token-id (+ (var-get last-token-id) u1)) - (tx-was-mined (try! (contract-call? .clarity-bitcoin was-tx-mined-compact height tx header proof))) - ) - (asserts! (is-eq tx-sender contract-owner) err-owner-only) - (asserts! (is-eq tx-was-mined true) err-tx-not-mined) - (try! (nft-mint? bitbadge token-id recipient)) - (var-set last-token-id token-id) - (ok token-id) - ) -) -``` - -Note the `(asserts! (is-eq tx-was-mined true) err-tx-not-mined)` line. This is what is doing the heavy lifting. - -:::caution -Right now the clarity-bitcoin library only supports legacy transactions. Work is in-progress to add support for segwit, but until then we have to do a bit of work on the front end to strip the witness data from the raw transaction hex. -::: - -Here's the JavaScript code we can use to get the data we need. - -First we get the raw transaction and the merkle proof (we do this when we first get the transaction ID back). - -The `useEffect` here is so that we can check to see if the transaction was confirmed every 10 seconds before we get the rest of the information. - -```javascript -// Effect hook to check and see if the tx has been confirmed using blockstream API -useEffect(() => { - const intervalId = setInterval(() => { - const txid = JSON.parse(localStorage.getItem("txid")); - if (txid) { - fetch(`https://blockstream.info/testnet/api/tx/${txid}/status`) - .then((response) => response.json()) - .then(async (status) => { - // set txStatus in localStorage if it is confirmed, otherwise we want to leave it pending - if (status.confirmed) { - localStorage.setItem("txStatus", "confirmed"); - // set the block details - const blockDetails = { - block_height: status.block_height, - block_hash: status.block_hash, - }; - setBlockDetails(blockDetails); - localStorage.setItem("blockDetails", JSON.stringify(blockDetails)); - // fetch and set the tx raw - const rawResponse = await fetch( - `https://blockstream.info/testnet/api/tx/${txid}/hex` - ); - const txRaw = await rawResponse.text(); - localStorage.setItem("txRaw", txRaw); - // fetch and set the merkle proof - const proofResponse = await fetch( - `https://blockstream.info/testnet/api/tx/${txid}/merkle-proof` - ); - const txMerkleProof = await proofResponse.json(); - localStorage.setItem( - "txMerkleProof", - JSON.stringify(txMerkleProof) - ); - clearInterval(intervalId); - } - }) - .catch((err) => console.error(err)); - } - }, 10000); - return () => clearInterval(intervalId); // Clean up on component unmount -}, []); -``` - -Then we get and parse the rest of the data when we call the actual mint function. - -```javascript -// This function retrieves raw transaction and merkle proof from localStorage and calls the mint Clarity function -const mintBitbadge = async () => { - // Retrieving rawTx and merkleProof from local storage - let txRaw = ""; - let txMerkleProof = ""; - - if (typeof window !== "undefined") { - txRaw = removeWitnessData(localStorage.getItem("txRaw")); - txMerkleProof = JSON.parse(localStorage.getItem("txMerkleProof")); - } - - // First we need to verify that the sender of this transaction is the same as the user that is signed in - if (!verifyCorrectSender()) { - console.log("wrong sender"); - return false; - } - - const blockHeight = blockDetails.block_height; - - // Fetch the block hash - const blockHashResponse = await fetch( - `https://blockstream.info/testnet/api/block-height/${blockHeight}` - ); - const blockHash = await blockHashResponse.text(); - - // Fetch the block header - const blockHeaderResponse = await fetch( - `https://blockstream.info/testnet/api/block/${blockHash}/header` - ); - const blockHeaderHex = await blockHeaderResponse.text(); - - const txIndex = txMerkleProof.pos; - const hashes = txMerkleProof.merkle.map( - (hash) => bufferCV(hexToBytes(hash).reverse()) // lib needs reversed hashes - ); // Convert each hash to BufferCV and reverse it - - const functionArgs = [ - principalCV(userData.profile.stxAddress.testnet), - uintCV(blockHeight), - bufferCV(Buffer.from(txRaw, "hex")), - bufferCV(Buffer.from(blockHeaderHex, "hex")), - tupleCV({ - "tx-index": uintCV(txIndex), - hashes: listCV(hashes), - "tree-depth": uintCV(txMerkleProof.merkle.length), - }), - ]; - - const contractAddress = "ST3QFME3CANQFQNR86TYVKQYCFT7QX4PRXM1V9W6H"; // Replace with your contract address - const contractName = "bitbadge-v3"; // Replace with your contract name - const functionName = "mint"; // Replace with your function name - - const options = { - contractAddress, - contractName, - functionName, - functionArgs, - appDetails: { - name: "BitBadge", - icon: "https://freesvg.org/img/bitcoin.png", - }, - onFinish: (data) => { - console.log(data); - }, - }; - - await openContractCall(options); -}; -``` diff --git a/docs/gaia/configuration.md b/docs/gaia/configuration.md deleted file mode 100644 index b9a6a5119f..0000000000 --- a/docs/gaia/configuration.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Configuration -description: Configuring Gaia Hub ---- - -## Configuration files - -The following configuration files exist in the folder `deploy/configs/gaia/`: - -``` -admin-config.json -hub-config.json -reader-config.json -``` - -## GAIA Admin Service - -You can also use the GAIA Admin Service to remotely administer it with an API Key. It will require you to install `npm` with a `apt install npm`. -Once `npm` is installed you can continue with the steps in the [GAIA Admin Service](https://github.com/stacks-network/gaia/blob/master/admin/README.md). - -## Driver Selection - -The Gaia hub currently supports the following drivers: - -``` -'aws' == Amazon S3 -'azure' == Azure Blob Storage -'disk' == Local disk -'google-cloud' === Google Cloud Storage -``` - -Set the driver you wish to use in your [config.json](https://github.com/stacks-network/gaia/blob/master/hub/config.sample.json) file with the `driver` parameter. Many drivers additionally accept the `bucket` parameter, which controls the bucket name that files should be written to. - -These driver may require you to provide additional credentials for performing writes to the backends. See `config.sample.json` for fields for those credentials. In some cases, the driver can use a system configured credential for the backend (e.g., if you are logged into your AWS CLI account, and run the hub from that environment, it won't need to read credentials from your `config.json`). - -:::caution -The disk driver requires a \*nix like filesystem interface, and will not work correctly when trying to run in a Windows environment. -::: - -## Note on SSL - -We _strongly_ recommend that you deploy your Gaia hub with SSL enabled. Otherwise, the tokens used to authenticate with the Gaia hub may be stolen by attackers, which could allow them to execute writes on your behalf. -Configuration options are available to run the hub with an `https` Node.js server. -Otherwise, a reverse proxy web server such as nginx or Apache can be used. - -## Require Correct Hub URL - -If you turn on the `requireCorrectHubUrl` option in your `config.json` file, your Gaia hub will require that authentication requests correctly include the `hubURL` they are trying to connect with. -This is used to prevent a malicious gaia hub from using an authentication token for itself on other Gaia hubs. - -By default, the Gaia hub will validate that the supplied URL matches `https://${config.serverName}`, but if there are multiple valid URLs for clients to reach the hub at, you can include a list in your `config.json`: - -```javascript -{ - .... - serverName: "normalserver.com" - validHubUrls: [ "https://specialserver.com/", - "https://legacyurl.info" ] - .... -} -``` - -## The readURL parameter - -By default, the gaia hub drivers will return read URLs which point directly at the written content. -For example, an S3 driver would return the URL directly to the S3 file. -However, if you configure a CDN or domain to point at that same bucket, you can use the `readURL` parameter to tell the gaia hub that files can be read from the given URL. -For example, the `hub.blockstack.org` Gaia Hub is configured to return a read URL that looks like `https://gaia.blockstack.org/hub/`. - -Unset this configuration parameter if you do not intend to deploy any caching. - -## Minimum Proofs Requirement - -The gaia hub can also be configured to require a minimum number of social proofs in a user's profile to accept writes from that user. This can be used as a kind of spam-control mechanism. However, we recommend for the smoothest operation of your gaia hub, to set the `proofsConfig.proofsRequired` configuration key to `0`. - -## CDN & Replicated Hubs - -- https://docs.microsoft.com/en-us/azure/storage/blobs/storage-https-custom-domain-cdn - -- The hub implementation is designed to be ran from a single Node.js instance. If the hub instance is sharded (e.g. replicated hubs via load balancing), then any given `bucket` (identified by URI segment) must be served by the same instance, At least a couple elements of the Gaia Hub depend on this: token invalidation in-memory caching, and resource endpoint 409 contention behavior. diff --git a/docs/gaia/deploy-gaia-hub.md b/docs/gaia/deploy-gaia-hub.md deleted file mode 100644 index 558cbb14f5..0000000000 --- a/docs/gaia/deploy-gaia-hub.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Deploy Gaia Hub -description: Steps and tutorials ---- - -## Deploy your GAIA hub - -Tutorials to deploy your own GAIA hub are currently available for [Linux](./setup-linux), [MacOS](./setup-mac) and [Amazon EC2 / CloudFormation](./gaia-on-ec2). - -Regardless of what server the Gaia Hub runs on, the storage it uses can currently be deployed on multiple platforms: - -- Local disk (the server itself) -- Amazon S3 -- Azure Blob Storage -- Google Cloud - -:::tip -Support for IPFS is under development. -::: \ No newline at end of file diff --git a/docs/gaia/gaia-on-ec2.md b/docs/gaia/gaia-on-ec2.md deleted file mode 100644 index dca15e3b8d..0000000000 --- a/docs/gaia/gaia-on-ec2.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -title: Amazon EC2 -description: Use a template to deploy a Gaia hub on Amazon EC2 -tags: - - tutorial - - gaia ---- - -## Introduction - -The template provided on this page provides an easy way to deploy a Gaia hub directly to Amazon EC2. You can use this template to deploy your own Gaia hub to your Amazon Web Services (AWS) account. Amazon EC2 is an affordable and convenient cloud computing provider. The template provides a one-click deploy for Amazon EC2 with either S3 or EBS as a storage provider. - -## Prerequisites - -This procedure uses Amazon CloudFormation to configure an EC2 cloud compute provider to run the Gaia hub service with an S3 or EBS provider for file storage. You should have access to an AWS account either through your personal account or through a corporate account. This account should have permissions to create resources. - -Additionally, you must also own a domain name and be able to update the DNS records associated with that domain name. - -## Setup steps - -### Step 1 - Create Stack - -Use a link in the table to launch the [CloudFormation](https://console.aws.amazon.com/cloudformation/) template in the AWS region that you wish to deploy a Gaia hub. - -![Create stack](/img/cloudformation-create-stack.png) - -### Step 2 - Setup stack using template - -You need to configure the template with the appropriate values for your hub and domain it runs on. - -Select `Template is ready` and `Amazon S3 URL` and enter the following Amazon S3 URL: - -``` -https://s3-external-1.amazonaws.com/cf-templates-vzldibfi2mw8-us-east-1/2022160J6G-cloudformation.yaml -``` - -If you prefer you can instead select `Template is ready` and `Upload a template file` to upload the template file `cloudformation.yaml`. - -The latest `cloudformation.yaml` file can be downloaded [here](https://raw.githubusercontent.com/stacks-network/gaia/master/deploy/cloudformation.yaml). On most browsers you can right-click on that page and click on `Save page as` to download the file. Alternatively, you can copy/paste the text into a text file called `cloudformation.yaml`. - -Then click `Next`. - -![Specify template](/img/cloudformation-specify-template.png) - -### Step 3 - Specify stack details - -Specify the stack details and then click `Next`: -![Specify template](/img/cloudformation-specify-stack-details.png) - -| Field | Value | Notes | -| --------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Stack name | _a unique name in your AWS account_ | e.g.: my_gaia_hub | -| DomainName | _your-domain_ | -| EmailAddress | _your email address_ | -| GaiaBucketName | _S3 bucket name_ | The template combines this name with the stack name to create a unique S3 bucket. The template ignores this field if GaiaStorageType is set to `disk`. | -| GaiaStorageType | `s3` or `disk` | Select the GaiaStorageType of which to use as a backend for the Gaia Hub. Selecting `s3` causes the template to create an S3 bucket based on the name given in the previous field. Selecting `disk` causes the template to attach a separate EBS volume to the EC2 instance for Hub storage. | -| InstanceType | t2.micro | Select the instance type you want. Default value is `t2.micro`. | -| KeyName | | In the KeyName drop-down, select an [EC2 KeyPair](https://console.aws.amazon.com/ec2/v2/home?region=us-east-1#KeyPairs:) to enable SSH access to the EC2 instance. You should download the `.pem` keyfile for this pair from the EC2 console. For more information see the [EC2 key pair documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html#prepare-key-pair) | -| SSHLocation | 0.0.0.0/0 | Leave the SSHLocation field with the default value of `0.0.0.0/0` to enable SSH access from any IP address. If you wish to restrict SSH access to the EC2 instance to a certain IP, you can update this field. | -| SubnetId | _subnetid_ | Select a public subnet | -| VpcId | _vpcid_ | - -### Step 4 - Configure stack options - -Configure any stack options that fit your desired setup and click `Next`. All these fields are optional. - -![Specify template](/img/cloudformation-stack-options.png) - -### Step 5 - Review - -Review the configuration of your Gaia hub, select the checkbox to acknowledge that AWS may create IAM resources with custom names and click on `Create stack`. - -![Specify template](/img/cloudformation-iam-resources.png) - -### Step 6 - Retrieve the public IP of your Gaia hub - -Your stack can take several minutes to launch. You can monitor the Events tab of your hub to review the current progress of the launch. When the launch is complete, the Outputs tab displays information about the hub. Select the PublicIP and copy it to configure your domain name. - -Create an `A` DNS record pointing to the given IP in your domain. - -Wait a few minutes for the DNS record to propagate, and your should be able to access your Gaia hub with SSH. - -## Accessing your Gaia hub with SSH - -To SSH into your Gaia hub EC2 host directly, you must have the keyfile used in container creation. Access the host with the following command in your terminal: - -```bash -ssh -i admin@ -``` - -:::tip -If you can only access SSH with the IP but not with the DNS name and you wish to do so, you can optionally activate it by following these steps: - - Open your [AWS Console](https://console.aws.amazon.com) - Click on `Service` -> VPC - Open Your VPCs - Select your VPC connected to your Gaia Hub - Click `Actions` -> `Edit DNS Hostnames` -> Change `DNS hostnames` to `Enable` - -::: - -## Graphical representation of the cloudformation template - -![](/img/cloudformation-gaia-template1-designer.png) diff --git a/docs/gaia/gaia.md b/docs/gaia/gaia.md deleted file mode 100644 index ccae8da80a..0000000000 --- a/docs/gaia/gaia.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: Gaia -description: Decentralized storage architecture for off-chain data -sidebar_position: 6 -tags: - - gaia ---- - -## Introduction - -Apps built with the Stacks blockchain can store off-chain data using a storage system called Gaia. - -Gaia is a unique approach to decentralized storage that focuses primarily on user-ownership of data, rather than immutable on-chain storage. The emphasis here is on user control. - -While on-chain storage solutions like IPFS and Arweave are designed for immutable, censorship-resistant permanent storage, they cannot be deemed as providing user control of the data since the user cannot modify or remove the data once it has been deployed. - -Gaia solves a different problem of allowing users to be in control of where their data is stored while connecting the access of that data to their on-chain Stacks identity. - -Whereas public transactional metadata is best stored on the Stacks blockchain, user application data can often be stored more efficiently and privately in Gaia storage. - -Storing data off of the blockchain ensures that Stacks applications can provide users with high performance and high availability for data reads and writes without introducing central trust parties. - -:::tip -Latest whitepaper of GAIA (May 2022) is available [here](https://dev1-gaia-hub.s3.amazonaws.com/GAIA_Whitepaper.pdf) -::: - -## Understand Gaia in the Stacks architecture - -The following diagram depicts the Stacks architecture and Gaia's place in it: - -![Stacks Architecture](/img/architecture.png) - -Blockchains require consensus among large numbers of people, so they can be slow. Additionally, a blockchain is not designed to hold a lot of data. This means using a blockchain for every bit of data a user might write and store is expensive. For example, imagine if an application were storing every tweet in the chain. - -The Stacks blockchain addresses performance problems using a layered approach. The base layer consists of the Stacks blockchain and the Blockchain Naming System (BNS). The blockchain governs ownership of identities in the Stacks network. Identities can be names such as domain names, usernames, or application names. - -When an identity is created, its creation is recorded in the Stacks blockchain. Identities make up the primary data stored into the Stacks blockchain. These identities correspond to routing data in the OSI stack. The routing data is stored in the Atlas Peer Network, the second layer. Every core node that joins the Stacks Network is able to obtain an entire copy of this routing data. Stacks uses the routing data to associate identities (domain names, user names, and application names) with a particular storage location in the final layer, the Gaia Storage System. - -A Gaia Storage System consists of a _hub service_ and storage resource on a cloud software provider. The storage provider can be any commercial provider such as Azure, DigitalOcean, Amazon EC2, and so forth. Typically the compute resource and the storage resource reside same cloud vendor, though this is not a requirement. Gaia currently has driver support for S3, Azure Blob Storage, Google Cloud Platform and local disk, but the driver model allows for other backend support as well. - -Gaia stores data as a simple key-value store. When an identity is created, a corresponding data store is associated with that identity on Gaia. When a user logs into a dApp, -the authentication process gives the application the URL of a Gaia hub, which -then writes to storage on behalf of that user. - -The Stacks blockchain stores only identity data. Data created by the actions of an identity is stored in a Gaia Storage System. Each user has profile data. When a user interacts with a decentralized dApp that application stores application data on behalf of the user. Because Gaia stores user and application data off the blockchain, a Stacks DApp is typically more performant than DApps created on other blockchains. - -## User control or how is Gaia decentralized? - -A Gaia hub runs as a service which writes to data storage. The storage itself is a simple key-value store. The hub service writes to data storage by requiring a valid authentication token from a requestor. Typically, the hub service runs on a compute resource and the storage itself on separate, dedicated storage resource. Typically, both resources belong to the same cloud computing provider. - -![Gai storage](/img/gaia-storage.png) - -Gaia's approach to decentralization focuses on user control of data and its storage. Users can choose a Gaia hub provider. If a user can choose which Gaia hub provider to use, then that choice is all the decentralization required to enable user-controlled applications. Moreover, Gaia defines a uniform API for applications to access that data. - -The control of user data lies in the way that user data is accessed. When an application fetches a file `data.txt` for a given user `alice.id`, the lookup will follow these steps: - -1. Fetch the `zonefile` for `alice.id`. -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. Find the read-only url out of the profile's `appsMeta` section (e.g. `https://example-app.gaia.alice.org`). -6. Fetch the file from `https://example-app.gaia.alice.org/data.txt`. - -Because `alice.id` has access to her [zonefile](https://docs.stacks.co/references/bns-contract#name-update), 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. - -:::caution -Users with existing identities cannot yet migrate their data from one hub to another. -::: - -Applications writing directly on behalf of `alice.id` do not need to perform a lookup. Instead, the [Stacks authentication flow](https://stacks.js.org) provides Alice's chosen gaia hub URL to the application. This authentication flow _is also_ within Alice's control because Alice's wallet _must_ generate the authentication response. - -## Understand data storage - -A Gaia hub stores the written data _exactly_ as given. It offers minimal guarantees about the data. It does not ensure that data is validly formatted, contains valid signatures, or is encrypted. Rather, the design philosophy is that these concerns are client-side concerns. - -Client libraries (such as [`Stacks.js`](https://stacks.js.org/)) are capable of providing these guarantees. A liberal definition of the [end-to-end principle](https://en.wikipedia.org/wiki/End-to-end_principle) guides this design decision. - -When an application writes to a Gaia hub, an authentication token, key, and the data are passed to the Gaia hub. - -![Gaia writes](/img/gaia-writes.png) - -The token ensures the app has the authorization to write to the hub on the user's behalf. - -## Gaia versus other storage systems - -Here's how Gaia stacks up against other decentralized storage systems. Features that are common to all storage systems are omitted for brevity. - -| Features | [Gaia](https://github.com/stacks-network/gaia) | [Sia](https://sia.tech/) | [Storj](https://storj.io/) | [IPFS](https://ipfs.io/) | [DAT](https://datproject.org/) | [SSB](https://www.scuttlebutt.nz/) | -| ------------------------------------------ | ---------------------------------------------- | ------------------------ | -------------------------- | ------------------------ | ------------------------------ | ---------------------------------- | -| User controls where data is hosted | X | | | | | | -| Data can be viewed in a normal Web browser | X | | | X | | | -| Data is read/write | X | | | | X | X | -| Data can be deleted | X | | | | X | X | -| Data can be listed | X | X | X | | X | X | -| Deleted data space is reclaimed | X | X | X | X | | | -| Data lookups have predictable performance | X | | X | | | | -| Writes permission can be delegated | X | | | | | | -| Listing permission can be delegated | X | | | | | | -| Supports multiple backends natively | X | | X | | | | -| Data is globally addressable | X | X | X | X | X | | -| Needs a cryptocurrency to work | | X | X | | | | -| Data is content-addressed | | X | X | X | X | X | diff --git a/docs/gaia/setup-linux.md b/docs/gaia/setup-linux.md deleted file mode 100644 index b19a74a13d..0000000000 --- a/docs/gaia/setup-linux.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: Linux -description: Steps to setup a GAIA hub on a Linux server (fresh install). This example is using Debian, but should work on any Linux distribution. It uses docker compose in the background. -tags: - - tutorial - - gaia ---- - -This configuration will setup the following 4 docker containers: - -- Nginx with certbot on TCP ports 80 and 443. -- Gaia hub on TCP port 3000. -- Gaia admin on TCP port 8009. -- Gaia reader on TCP port 8008 - -**1. Update the system and install the dependencies and software we will use to test:** - -```bash -apt update && apt upgrade -y && apt install -y git vim gnupg jq -``` - -**2. Install [docker](https://docs.docker.com/engine/install/debian/) and [docker-compose](https://docs.docker.com/compose/cli-command/#install-on-linux)** in your OS. -For our example we install _docker_ with: - -```bash -curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg - -echo \ - "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian \ - $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null - -apt update && apt install -y docker-ce docker-ce-cli containerd.io -``` - -Install _docker-compose_ by downloading the [latest-release](https://github.com/docker/compose/releases): - -```bash -VERSION_DC=$(curl --silent https://api.github.com/repos/docker/compose/releases/latest | jq .name -r) -DESTINATION_DC=~/.docker/cli-plugins -mkdir -p ${DESTINATION_DC} -curl -SL https://github.com/docker/compose/releases/download/${VERSION_DC}/docker-compose-linux-x86_64 -o ${DESTINATION_DC}/docker-compose -chmod +x ${DESTINATION_DC}/docker-compose -``` - -**3. Clone the GAIA repository** and enter it's docker directory. - -```bash -git clone https://github.com/stacks-network/gaia.git && cd gaia/deploy/docker -``` - -**4. Copy and edit appropriate .env file**. -In the folder `./deploy/docker/` they are different sample files for different configurations like using aws, azure or disk among others. In this example we will store the data locally so we will copy the _disk_ file and update the domain and email fields. Please change `gaia.site.com` and `gaiarocks@mydomain.com` accordingly. Note you need both for the SSL certificate to be created correctly. - -```bash -export MYGAIADOMAIN=gaia.site.com -export MYGAIAEMAIL=gaiarocks@mydomain.com -cp sample-disk.env disk.env -sed -i 's/my-domain.com/'"$MYGAIADOMAIN"'/g' disk.env -sed -i 's/my-email@example.com/'"$MYGAIAEMAIL"'/g' disk.env - -``` - -**5. Start GAIA HUB service** - -To start GAIA HUB - -```bash -./gaiahub.sh start -``` - -To stop GAIA HUB - -```bash -./gaiahub.sh stop -``` - -To view GAIA HUB status - -```bash -./gaiahub.sh status -``` - -**6. Verify server works locally** with the following command: - -```bash -curl -sk http://localhost/hub_info | jq -``` - -A correct result should look similar to this: - -```bash - { - "challenge_text": "[\"gaiahub\",\"0\",\"gaia-0\",\"blockstack_storage_please_sign\"]", - "latest_auth_version": "v1", - "max_file_upload_size_megabytes": 20, - "read_url_prefix": "https://gaia.site.com/reader/" - } -``` - -**7. Test your GAIA HUB** -Running `gaia_test.js` will test your GAIA Hub, by trying to connect to it, uploading a file and downloading it again. - -First install all required dependencies with: - -```bash -npm install -``` - -Then, from the root folder of the project type: - -```bash -node ./deploy/gaia_test.js https://yourgaiaurl -``` - -A correct result will be something like this: - -``` -Will run a test for the GAIA HUB: https://gaia.mydomain.com -Generating some test keys... -Private key: 5aacc60fc2a429e1f02be139f3cac82061c6a980******************** -Public key: 025691f17f2ab80dc4af363bb9c7aac59e9e1db6ae8ff668202582a3f4ec9678ff -Address: 15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS -[DEBUG] connectToGaiaHub: https://gaia.mydomain.com/hub_info -[DEBUG] uploadToGaiaHub: uploading testing.txt to https://gaia.mydomain.com -File uploaded successfully. -Upload to gaia hub thinks it can read it from: https://gaia.mydomain.com/reader/15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS/testing.txt -Hub info thinks it can read it from : https://gaia.mydomain.com/reader/15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS/testing.txt -Let's now try to fetch the uploaded file... -File fetched successfully. Contents of file: GAIA ROCKS! -``` diff --git a/docs/gaia/setup-mac.md b/docs/gaia/setup-mac.md deleted file mode 100644 index 808833b212..0000000000 --- a/docs/gaia/setup-mac.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: MacOS -description: MacOS for local testing/development -tags: - - tutorial ---- - -The following assumes you have [Docker Installed](https://docs.docker.com/docker-for-mac/install/) - -- Recommended to also have [MacOS Homebrew](https://docs.brew.sh/Installation) installed -- Use Homebrew to install jq with `brew install jq` - -In your working directory: - -**1. Clone a copy of the [gaia repo](https://github.com/stacks-network/gaia):** - -```bash -$ git clone -b master --single-branch https://github.com/stacks-network/gaia -``` - -**2. Change your cwd:** - -```bash -$ cd gaia/deploy/docker -``` - -**3. Create a copy of sample-disk.env and fill out the values:** - -``` -$ cp sample-disk.env disk.env -# Update the DOMAIN_NAME variable to `localhost` -``` - -**4. Start the server:** - -``` -$ docker-compose -f docker-compose-base.yaml -f docker-compose-disk.yaml --env-file disk.env up -``` - -**5. Verify the server is responding locally:** - -``` -$ curl -sk https://localhost/hub_info | jq - { - "challenge_text": "[\"gaiahub\",\"0\",\"gaia-0\",\"blockstack_storage_please_sign\"]", - "latest_auth_version": "v1", - "max_file_upload_size_megabytes": 20, - "read_url_prefix": "https://localhost/reader/" - } -``` - -### Modifying the configuration for your gaia-hub - -Two methods exist: - -1. Edit the `gaia/deploy/configs/gaia/hub-config.json` using `vim` or other - -- requires a restart of the containers: `docker-compose -f docker-compose-base.yaml -f docker-compose-disk.yaml --env-file disk.env restart` - -2. Use the running `admin` container to modify any config values, and also reload the hub when complete: - -- [GitHub - Gaia Admin README.md](https://github.com/stacks-network/gaia/blob/master/admin/README.md) - -``` -$ export API_KEY="hello" -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - -H 'Content-Type: application/json' \ - -X POST \ - --data-raw '{"serverName": "myserver"}' \ - http://localhost:8009/v1/admin/config - -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - -X POST \ - http://localhost:8009/v1/admin/reload - -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - http://localhost:8009/v1/admin/config | jq -``` diff --git a/docs/glossary/index.md b/docs/glossary/index.md deleted file mode 100644 index b389c50dde..0000000000 --- a/docs/glossary/index.md +++ /dev/null @@ -1,294 +0,0 @@ ---- -title: Glossary -description: A comprehensive list of terms used within the ecosystem. ---- - -A comprehensive list of terms used within the ecosystem. - -#### App Review - -An incentive mechanism for application developers in the early stage (first four years) of the ecosystem and helps with bootstrapping the two-sided market. - -#### Atlas - -A peer network provide a global index for discovery. - -#### Bitcoin (BTC) address - -A string of letters and numbers. -`3E53XjqK4Cxt71BGeP2VhpcotM8LZ853C8` -Sharing this address allows anyone to send Bitcoin to the address. - -#### block - -A discrete group of records written to a blockchain that can effectively be identified and referenced by the use of headers that contain a digital fingerprint of the records each block contains. - -#### blockchain - -A database created and shared by the members of a peer-to-peer computer network which each member of that network can independently trust due to the rules governing the database’s creation. A blockchain can therefore be used to replace centralized databases. - -#### Blockchain Name System (BNS) - -Replacement for DNS. More info [here](../clarity/noteworthy-contracts/bns-contract). - -#### Blockstack Browser - -A deprecated application for accessing identity and storage. - -#### Blockstack Owner Address - -Looks like a bitcoin address but starts with `ID` for example: -`ID-1J3PUxY5uDShUnHRrMyU6yKtoHEUPhKULs` - -#### Burning - -Burning a token means that the token is transferred to an address that is a black hole—one that is not owned by any entity and for which guessing the applicable private key is effectively impossible based on known mathematical principles. This effectively destroys the token by making it unavailable for future use and decreases the total number of tokens available from that point forward. - -#### consensus hash - -A consensus hash is a cryptographic hash that each node calculates at each block. It is derived from the accepted state transitions in the last-processed block and a geometric series of prior-calculated consensus hashes. - -#### Consensus rules - -"The rules governing the creation of new valid records in a blockchain database and the mining algorithms used for this purpose. - -#### control plane - -The part of a network that carries signaling traffic and is responsible for routing. Control packets originate from or are destined for a router. Functions of the control plane include system configuration and management. - -#### core node - -A server that runs Stacks Blockchain services. - -#### crypto-asset - -A digital asset which utilizes cryptography, peer-to-peer networking and a public ledger to regulate the creation of new units, verify transactions and secure the transactions without the intervention of any middleman. - -#### cryptography - -The practice and study of encryption and decryption - encoding data so that it can only be decoded by specific individuals. A system for encrypting and decrypting data is a cryptographic system. - -#### DAO - -See Decentralized Autonomous Organization. - -#### decentralized application (DApp) - -A DApp is a service that enables direct interaction between end users and providers (e.g. connecting buyers and sellers in some marketplace, owners and stores in file storage). A term coined by Ethereum. See their glossary: http://ethdocs.org/en/latest/glossary.html#dapp" - -#### Decentralized Autonomous Organization - -A type of contract or suite of contracts on the blockchain that is intended to codify, enforce or automate the processes of an organization. - -#### digital asset - -Also referred to as a crypto-asset. Any set of unique digital information—including, for example, programs, decentralized programs, isolated chunks of programming code, collections of data, e-mail or web addresses or cryptocurrency tokens—that is capable of being stored and uniquely tracked on a computer network such as the Stacks network and over which a user can maintain control through that network. - -#### digital fingerprint - -A digital fingerprint is a unique number of a fixed length that can be produced by running any set of digital information through something called a cryptographic hash function. Each set of digital information (including a digital asset, and the digital record of any network operation on that digital asset) should (as a practical matter) have a unique digital fingerprint, which allows that set of digital information to be identified. However, it is almost impossible to recreate a digital asset from its digital fingerprint. The Blockstack network uses industry-standard algorithms such as SHA-256 to create digital fingerprints. - -#### digital signature - -A digital signature is a sequence of digital information combining a user’s private key and any digital information that the user wishes to sign. Any other party can use the user’s paired public key to verify that the digital signature is authentic, i.e. that the public key was generated from a particular piece of digital information and the user’s private key. - -#### distributed hash tables (DHT) - -A form of network used to store some content in the form of key/value pairs. ... This experimental project try to avoid keeping all the blockchain, but instead prefers to store it in a DHT. - -#### ephemeral key - -A cryptographic key is called ephemeral if it is generated for each execution of a key establishment process. - -#### fork - -The term fork is used to refer both to any situation where there are two or more competing versions of a blockchain on a network (a situation that may arise and resolve itself in the ordinary course of network operations due to lags in communication between core nodes) and any software update that is proposed for adoption by the core nodes of a blockchain network that may result in a persistent fork on the network, with core nodes that adopt the update recognizing one version of the blockchain and those which do not recognizing another. - -#### Gaia - -Decentralized storage architecture for off-chain data. More info [here](../gaia). - -#### genesis block - -The genesis block is the first block of the Stacks blockchain, which will create the initial 1.32 billion Stacks Tokens. - -#### id.blockstack - -An identifier in the Blockstack, for example meepers.id.blockstack. This is your name & identity that is registered in the .id namespace on Blockstack. Your personal data and storage are built around this ID. Apps that want to access your data use your permission and identity to find it. An id is usually a shorthand for a longer, hash ID string, for example ID-1Fj9kkw15P51Fj9kkw15P5xJmyefWhLKrQMKNPREfaqsJ" - -#### Identity management (IDM) - -Identity management, also known as identity and access management is, in computer security, the security and business discipline that enables the right individuals to access the right resources at the right times and for the right reason. - -#### Know your customer (KYC) - -KYC is a popular term used in the banking or financial field. KYC is a process where financial institutions, insurers and other companies obtain information about the identity and address of the customers as part of risk management. - -#### identity management (IDM) - -Identity management, also known as identity and access management is, in computer security, the security and business discipline that enables the right individuals to access the right resources at the right times and for the right reason". - -#### know your customer (KYC) - -Or KYC, is a popular term used in the banking or financial field. KYC is a process where financial institutions, insurers and other companies obtain information about the identity and address of the customers as part of risk management. - -#### light clients - -Clients that can independently validate the existence of transactions by downloading only block headers and not the entire blockchain. - -#### magic recovery code - -A long encrypted string, for example: -`36mWivFdy0YPH2z31EflpQz/Y0UMrOrJ++lH=0EI7c3mop2JuRBm5WXxSTazJsUjOA...` -Do not share the QR code that accompanied your recovery code either. This is a QR code: - -![](/img/qr-code.png) - -#### mesh network - -A local network topology in which the infrastructure nodes (i.e. bridges, switches, and other infrastructure devices) connect directly, dynamically and non-hierarchically to as many other nodes as possible and cooperate with one another to efficiently route data from/to clients. - -#### mining - -Mining generally refers to the process of performing certain functions for a network such as adding new records to a blockchain in exchange for mining rewards; it may also refer to other mechanisms whereby rewards (usually in the form of cryptocurrency) are provided for performing other tasks helpful to the network. - -#### mining power - -A miner’s (or group of miners’) mining power is equal to the probability it will be selected to write a new block to the blockchain. Depending on the mechanism for mining, this is usually related to the overall share of computing power or cryptoassets the miner or miners possess relative to all miners for that blockchain. - -#### mining rewards - -Mining rewards are newly issued tokens received by miners in exchange for adding new records to the blockchain or other activities beneficial to the network. - -#### name - -An identifier or name. Names are a type of digital asset in the Stacks network. If you have signed into the Stacks Wallet, you might have created a name. If an application developer registered an application within Stacks, then they registered a name. Public Stacking pools can also have a name. - -#### network operation - -A network operation is any change to the information about a digital asset (or smart contract) stored on a blockchain, including, for example, a change in the digital asset’s owner, or a change in the location at which it is stored on the network. How and when these network operations are performed for each digital asset is governed, on the Blockstack network, either by the Stacks Node software or a smart contract. - -#### NFT - -Non fungible token. - -#### Private key - -Private keys matches a corresponding public key. A public key also looks like a string of letters and numbers: - -![](/img/private.png) - -The exact format of the public and private key depend on the software you use to create them. - -#### proof-of-burn mining - -The consensus algorithm used in the Stacks blockchain where miners destroy a proof-of-work-based cryptocurrency (currently Bitcoin) to get tokens; this enables the functionality where nodes can select between conflicting blockchain forks, as the blockchain fork with the most amount of cryptocurrency burned is considered to be the correct fork. - -#### proof-of-work - -A proof-of-work system or proof-of-work mining is a mining mechanism where miners must expend computing power to solve complicated cryptographic puzzles, and prove that they have done so by writing the solution to the blockchain, in order to be allowed to add blocks to a blockchain. This is the mining system used, for example, by Bitcoin. - -#### public key - -Public and private key pair comprise of two uniquely related cryptographic keys. It looks like a long random string of letters and numbers: -`3048 0241 00C9 18FA CF8D EB2D EFD5 FD37 89B9 E069 EA97 FC20 …` - -The exact format of the public and private key depend on the software you use to create them. - -#### Public Key Infrastructure (PKI) - -A system which returns a cryptographic public key associated with a name. - -#### replicated state machines (RSMs) - -This is a model for reasoning about distributed computer programs -- any program (plus it's input) can be represented as a state machine, and when trying to get a distributed set of servers to agree on the output of an algorithm, you can model that process as N different state machines" - -#### Secret recovery Key, - -Used to access an identity on the Stacks blockchain. A 24-word sequence of words for example: -`applied binge crisp pictorial fiery` -` dancing agreeable frogs light finish ping apple` - -#### seed phrase - -Used to access Stacks Wallet software. The seed phrase consists of 24 words in a sequence. Both the word _and its position the sequence_ are important. -Write down your seed phrase and store it in a secure location such as a safe deposit box. When you write the seed phrase down, include its position, for example,`1-frog, 2-horse, 3-building` and so on until you reach a final position `24-ocean`. - -#### smart contract - -A smart contract is a computer program written to a blockchain such as the Stacks blockchain by developers. This computer program defines the various network operations that can be performed on the digital assets on the blockchain, the computations that can be performed using the smart contract, along with defining various important properties of the respective digital assets like ownership rights and the cost in fuel required to register the digital assets. - -#### soft fork - -A soft fork is a proposed update to the software governing the network that results in a post-update network that is compatible with the network as it existed prior to the update, because it restricts the network operations that can be performed after the update. - -#### Stacks (STX) address - -A STX address is a string of letters and numbers starting with an `SP` or `SM`, for example: `SM3KJBA4RZ7Z20KD2HBXNSXVPCR1D3CRAV6Q05MKT` -If you created a software-only wallet with the Stacks Wallet software, the wallet has a single STX address which is also sometimes called the _wallet address_. You access a software wallet with a _seed phrase_. " - -#### Stacks blockchain - -The Stacks blockchain is the custom blockchain being developed for use by the Stacks network that will use the Stacks token as its native currency and which will include the genesis block and subsequent blocks created by the mining activities described in the Stacks Network—Development of the Stacks network. - -#### Stacks Explorer - -An application that allow you to view and search transactions in the blockchain. For example, https://explorer.stacks.co. - -#### Stacks node - -A complete version of our open-source software available on Github at https://github.com/stacks-network/stacks-blockchain/ that governs the creation of the blockchain, the smart contracts that may be written to our blockchain, and other systems that make up the Stacks network, when run on the systems and devices of our users and developers. - -#### Stacks wallet - -An application for accessing assets, identity and storage. - -Examples are the [Hiro Wallet](https://www.hiro.so/wallet), [xverse](https://www.xverse.app/) and [dcent](https://dcentwallet.com/). - -#### storage hub - -A Gaia instance run by a hub provider or software. A Gaia hub stores data in a separate, addressed location. - -#### storage provider - -A third-party company cloud or software provider that hosts one or more Gaia storage hubs. - -#### transaction - -A transaction is a unit of work within a block. - -#### transaction fee - -Fees paid by participants in a transaction to miners. - -#### two-sided market problem - -Economic platforms having two distinct user groups that provide each other with network benefits. The Stacks platform is a classic two-sided market. - -#### username - -A shorthand name for your id.blockstack. - -#### virtual blockchain - -A layer that sits on top of a blockchain that introduces new functionality and operations without requiring changes to the underlying blockchain. - -#### wallet address - -A wallet address is the form in which a public key can be presented and recorded on a blockchain. Wallet addresses are therefore used to assign the ownership of digital assets on the Blockstack network. - -#### watch-only wallet - -A wallet without send and receive ability. You can view only balances and transaction history. - -#### web of trust mining - -Web-of-trust mining provides incentive mechanisms for users where an initial trusted-set of unique users is curated in the genesis block and, in the future, the initial set of users can expand the web-of-trust after the network goes live. - -#### web3 - -The exact definition is still under discussion, but it general refers to the 3rd generation of the web that is based on blockchain technology and incorporates decentralized and token-based economics. - -#### zone file - -A Domain Name System (DNS) zone file is a text file that describes a DNS zone. A DNS zone is a subset, often a single domain, of the hierarchical domain name structure of the DNS. diff --git a/docs/intro.md b/docs/intro.md deleted file mode 100644 index f284f060c8..0000000000 --- a/docs/intro.md +++ /dev/null @@ -1,70 +0,0 @@ ---- -sidebar_label: "Start Here" -sidebar_position: 1 ---- - -# Stacks Docs - -**Stacks is Bitcoin L2 that brings smart contract functionality to Bitcoin, without modifying Bitcoin itself.** - -These docs serve as: - -1. An introduction to Stacks (what it is, why you should care, how to build Bitcoin apps with it), -2. A reference guide to various aspects of the Stacks ecosystem -3. A collection of tutorials and code samples to help you learn and build - -If you see something you think you might want to contribute, [please do so](/docs/contribute)! We are always looking for good contributions from the community. - -:::note -Stacks is currently in the middle of a major upgrade called the Nakamoto Release. The next section is dedicated to describing how Nakamoto works and the benefits it brings. - -Keep in mind that other sections of this documentation apply to the pre-Nakamoto version of Stacks, and will be updated when it is released. -::: - -## Nakamoto - -The Nakamoto Release is an upcoming hard fork on the Stacks network designed to bring several benefits, chief among them are increased transaction throughput and 100% Bitcoin finality. Nakamoto is designed to make Stacks a true Bitcoin L2 and further unlock the decentralized Bitcoin economy. - -[Learn More About Nakamoto](/docs/nakamoto) - -## Tutorials - -Looking to understand how to build full-stack Bitcoin dapps with Stacks? These tutorials will give you a solid introduction. At the moment we have an intro tutorial and a collection of community-created tutorials focusing on Stacks and Clarity specifically, with a comprehensive deep-dive tutorial series covering Bitcoin-first development on the way. - -[View Hello Stacks Tutorial](/docs/tutorials/hello-stacks) - -## Stacks Academy - -If you are looking to understand Stacks and what it's all about at a deeper level, Stacks Academy is the place to go. - -[Start Stacks Academy](/docs/stacks-academy) - -## Clarity Reference - -Clarity is the language that powers smart contracts built on Stacks. You'll be introduced to Clarity in Stacks Academy, but this section of the docs is where you can find the references for all the keywords and functions in Clarity. - -[View Clarity Reference](/docs/clarity) - -## Nodes and Miners - -Interested in mining or running a Stacks node? This section is where you'll learn what that looks like and how to set it up. - -[View Nodes and Miners](/docs/nodes-and-miners) - -## Gaia - -Gaia is a unique approach to off-chain data storage that focuses on user-ownership of data with access connected to a Stacks identity. - -[View Gaia Docs](/docs/gaia) - -## Cookbook - -The Cookbook is a WIP, but you can check out what we have available now. This is designed to be a collection of code snippets, mini tutorials, and sample projects designed to help you accomplish specific things with Stacks. - -[View Cookbook](/docs/cookbook) - -## Next Steps - -Apply for a grant, get a job, start a company, join an immersive education experience like Clarity Universe. This section will point you to the different places in the Stacks community you can launch and grow your career as a Stacks developer. - -[Grow Your Skills and Career](/docs/next-steps) diff --git a/docs/nakamoto/bitcoin-mev-mitigation.md b/docs/nakamoto/bitcoin-mev-mitigation.md deleted file mode 100644 index 46c768ce69..0000000000 --- a/docs/nakamoto/bitcoin-mev-mitigation.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Bitcoin MEV Mitigation -description: How Nakamoto mitigates Bitcoin MEV -sidebar_label: Bitcoin MEV Mitigation -sidebar_position: 4 ---- - -Miner Extractable Value (MEV) has been a longstanding issue across many blockchains, including Stacks pre-Nakamoto. - -MEV refers to the potential profit miners can extract from the manipulation of transaction inclusion and ordering within the blocks they produce, which can lead to unfair practices and diminished trust in the network. - -Specifically in pre-Nakamoto releases of Stacks, Bitcoin miners with a significant percentage of Bitcoin’s hashrate had the ability to censor commitment transactions of other Stacks miners ensuring they were able to win the block rewards and fees of Stacks blocks where they were also the winner of the Bitcoin block as a Bitcoin miner. - -This allowed them to sometimes win these rewards for minimal bitcoin cost in PoX. This has led to reduction in Stacker BTC rewards and other bad incentives for Stacks mining. As such Nakamoto has changed the approach to sortitions to promote better fairness in the mining process. - -## Sortition Probability Factors - -With the Nakamoto release, Stacks introduces a series of countermeasures to mitigate the influence of MEV and promote a fairer mining landscape. - -- Miner Participation in Recent Blocks: The update emphasizes a miner's consistent participation within the network, requiring a history of attempts in recent blocks (the last 10) to qualify for sortition. This persistent involvement in at least the last 10 blocks aims to foster a dedicated and stable miner community. -- Median of Past Bids Method: By calculating the winning probability based on the median total BTC bids of the last ten blocks, the system discourages aberrant bidding behavior. This reduces the likelihood of a miner skewing sortition chances through atypical or extreme bids. -- Absolute Bid Total: Inclusion of an absolute measure of bids further strengthens the system's robustness. Rather than having a variable determined by just the immediate mining environment, the absolute bid total keeps the process anchored to a broader and more stable economic baseline. - -These changes ensure that miners are rewarded for their genuine contributions to the network's security and continuity, safeguarding the blockchain from manipulation and encouraging a more equitable distribution of rewards. - -## MEV Mitigation Details - -The Nakamoto system uses a variation of the Assumed Total Commitment with Carryforward (ATC-C) MEV mitigation strategy described in [this document](https://forum.stacks.org/uploads/short-url/bqIX4EQ5Wgf2PH4UtiZHZBqJvYE.pdf) to allocate block rewards to miners. Unlike pre-Nakamoto Stacks, there is no 40/60 fee split between two consecutive miners. - -Each miner nominally receives the entire coinbase and transaction fees before the MEV mitigation is applied. - -In the ATC-C algorithm, Nakamoto uses the document's recommended assumed total commitment function: the median total PoX spend across all miners for the past ten Bitcoin blocks. - -It also uses the document's recommended carryforward function for missed sortitions' coinbases: the coinbase for a Bitcoin block without a sortition would be available to winning miners across the next ten tenures. That is, if a miner whose tenure begins during the next ten tenure-changes manages to produce a Stacks block with a Coinbase, then they receive a 10% of the coinbase that was lost. - -The reason ATC (and ATC-C) were not considered as viable anti-MEV strategies before is because a decrease in the PoX total spend can lead to a Bitcoin block with no sortition. This is a deliberate design choice in ATC-C, because it has the effect of lowering the expected return of MEV mining. - -In ATC-C, the probability of a miner winning a sortition is equal to (i.e. no longer proportional to) the miner's BTC spend, divided by the maximum of either the assumed total commit (median total BTC spend in the last 10 blocks) or the total BTC spend in this Bitcoin block. This means that the sum of each miners' winning probabilities is not guaranteed to be 1. The system deals with this by creating a virtual "null" miner that participates in each sortition, such that its probability of the null miner winning is 1 - sum(probabilities-of-all-other-miners). If the null miner wins, then the sortition is treated as empty. - -While the existence of a null miner was a liveness concern in pre-Nakamoto Stacks, it is not a concern in Nakamoto. If the null miner wins tenure N, then the last non-null miner continues to produce blocks in tenure N. They receive transaction fees, but no coinbase for tenure N. - -Nakamoto includes one additional change to ATC-C as described in the above report: if a miner does not mine in at least five of the ten prior Bitcoin blocks, it has zero chance of winning. This requires a Bitcoin MEV miner to participate as an honest miner for the majority of blocks it produces, such that even if they pay the bare minimum PoX payout each time, they are still paying Bitcoin transaction fees to other miners. - -## Example - -The need for this additional tweak becomes apparent when considering the consequences for a real Bitcoin MEV miner who was active in pre-Nakamoto Stacks: F2Pool. - -Consider what happens to F2Pool, who spends 200 sats on PoX and zero sats on transaction fees for their block-commit. Suppose the median total BTC spend over the last ten Bitcoin blocks was 500,000 sats (about what it is at the time of this writing). - -With ATC-C alone, their probability of winning the sortition would be 200 / max(500,000, 200), or about 0.04% chance. The miner would need to send 2,500 such block-commits before winning a Stacks coinbase (worth about 500 USD). - -F2Pool had 13.89% of Bitcoin's mining power over the past three months, so it would take them about 4 months to win a single STX coinbase (which is a very long time horizon). Right now, it costs 22 sats/vbyte to get a Bitcoin transaction mined in the next Bitcoin block; this is what Stacks miners pay. - -A block-commit tx is about 250 vbytes, so that's 5500 sats, or about 1.41 USD with today's BTC price. So, F2Pool would lose money by MEV mining at their current rate if prices stay the same over those 4 months -- they'd forfeit about 3,525 USD in Bitcoin transaction fees (lost by excluding other Bitcoin transactions in order to include their block-commit) for a Stacks coinbase worth 500 USD. They'd have to pay about 1410 sats per block-commit just to break even, and they'd only recoup their investment on average once every 4 months. - -This by itself is not a significant improvement -- F2Pool would be required to go from paying 200 sats to 1410 sats. However, with this proposal's tweek, F2Pool would be required to additionally win five Bitcoin blocks in a row in order to mine this cheaply. - -Given that they have 13.89% of the mining power today, the odds of this happening by chance are only 0.005%. Since this is unlikely -- about once every 20,000 Bitcoin blocks (once every 138.9 days) -- F2Pool would instead be required to send legitimate block-commit transactions in at least 50% of the Bitcoin blocks. - -In 87.11% of those, they would be paying the same transaction fees as every other Stacks miner. This alone would cost them $106.13 USD/day. With the additional de minimis PoX payout, this rises to $212.25 USD/day. In other words, they would expect to pay $29,481.51 USD just to be able to mine one Stacks block for a de minimis PoX payout. This is more expensive than mining honestly! - -If the largest Bitcoin mining pool -- Foundry USA, at 30% of the Bitcoin mining power -- wanted to become a Bitcoin MEV miner on Stacks, then the given parameter choice still renders this unprofitable. There is a 0.243% chance that they win five blocks in a row, and can thus mine a de-minimis block-commit and be guaranteed to win. This happens about once every 2.85 days (every 411.5 Bitcoin blocks), so they'd be spending about $604.91 USD just to mine one Stacks block for free (which is not profitable either). diff --git a/docs/nakamoto/block-production.md b/docs/nakamoto/block-production.md deleted file mode 100644 index 2137f2b4b6..0000000000 --- a/docs/nakamoto/block-production.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Block Production -description: How blocks are produced in Nakamoto and how this unlocks fast blocks and Bitcoin finality -sidebar_label: Block Production -sidebar_position: 2 ---- - -One of the most significant changes coming in Nakamoto is how new blocks are produced. Historically, because Stacks blocks have been anchored 1:1 to Bitcoin blocks, slow block times and transaction times have been one of the biggest pain points for Stacks users and developers. - -Nakamoto brings significantly faster block times by decoupling Stacks block production from Bitcoin block production. In Nakamoto, new Stacks blocks are produced roughly every 5 seconds. - -## Tenure-Based Block Production - -This is achieved via the use of tenure-based block production. Each Bitcoin block introduces a new tenure, in which a single miner cryptographically selected for that tenure is responsible for producing all Stacks blocks. - -But if a single miner is only cryptographically selected for their tenure, and not their produced blocks, what mechanisms exist to ensure the validity of their block production. - -## Stackers - -This is where Stackers come in. In pre-Nakamoto Stacks, Stackers were responsible only for locking their STX tokens to contribute to the economic security of the network. - -In Nakamoto, Stackers are responsible for validating and approving each block produced during a miner's tenure. - -To ensure network consistency, the Stacks protocol commits to the state of the Stacks blockchain with each new Bitcoin block by referencing the first Stacks block produced in the previous tenure. Such a design reinforces the fidelity of transaction data and the synchronization between the two chains. It also links the Stacker’s actions with the actions of miners producing a partnership between the two to create both fast and secure blocks. - -As part of this tenure change, Stackers also agree on a last signed block and require the next miner to build off of this, which prevents new Stacks forks. Stacks does not fork on its own and automatically forks with Bitcoin. - -This symbiotic relationship between Stackers and miners is what creates the capability for both fast blocks and 100% Bitcoin finality. - -This elegant design creates a cooperative relationship between miners and stackers while achieving the best of both worlds with block production and transaction speed and security. - -## Bitcoin Finality - -Speaking of security, the concept of 100% Bitcoin finality is crucial to the design of Stacks. This is what turns Stacks into a true Bitcoin L2 and allows it to leverage all of the security inherent in Bitcoin. - -Let's first define what we mean by 100% Bitcoin finality, then we'll dig into how Nakamoto accomplishes this. - -Finality refers to the point at which transactions are irreversible. Once a blockchain reaches finality, it is nearly impossible to change the ledger's history without undertaking extraordinary measures that are often computationally and economically prohibitive. - -When we talk about Stacks blocks having 100% Bitcoin finality, we mean that they are as hard to reverse as Bitcoin transactions themselves. - -That's a bold claim, so how does Stacks accomplish that? - -As discussed above, miners are responsible for producing Stacks blocks in their tenure, which corresponds to a single Bitcoin block. As part of their block commit transaction, which is the transaction that commits the hash of the Stacks blocks to the Bitcoin chain, miners will also be required to add an indexed block hash. - -Stacks miners are required to commit the indexed block hash of the first block produced by the last Stacks miner in their block-commit transactions on Bitcoin. This is the SHA512/256 hash of both the consensus hash of all previously-accepted Bitcoin transactions that Stacks recognizes, as well as the hash of the block itself. - -This will anchor the Stacks chain history to Bitcoin up to the start of the previous miner's tenure, as well as all causally-dependent Bitcoin state that Stacks has processed. This ensures Bitcoin finality, resolves miner connectivity issues by putting fork prevention on stackers, and allows nodes with up-to-date copies of the Stacks chain state to identify which Stacks blocks are affected by a Bitcoin reorg and recover the affected Stacks transactions. diff --git a/docs/nakamoto/clarity-wasm.md b/docs/nakamoto/clarity-wasm.md deleted file mode 100644 index ecf28e3e90..0000000000 --- a/docs/nakamoto/clarity-wasm.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Clarity WASM -description: The new Clarity WASM runtime -sidebar_label: Clarity WASM -sidebar_position: 5 -draft: true ---- diff --git a/docs/nakamoto/index.md b/docs/nakamoto/index.md deleted file mode 100644 index 979febfe7c..0000000000 --- a/docs/nakamoto/index.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Nakamoto -description: Overview of the Nakamoto release and how to use it -sidebar_label: Nakamoto -sidebar_position: 2 ---- - -The Nakamoto Release is an upcoming hard fork on the Stacks network designed to bring several benefits, chief among them are increased transaction throughput and 100% Bitcoin finality. - -The Nakamoto release brings many new capabilities and improvements to the Stacks blockchain by focusing on a set of core advancements: improving transaction speed, enhancing finality guarantees for transactions, mitigating Bitcoin miner MEV (miner extractable value) opportunities that affect PoX, and boosting robustness against chain reorganizations. - -This portion of the documentation is broken up into several sections. - -## How Nakamoto Works - -If you are interested in learning more about how Nakamoto works, you can continue on in the following pages where we'll cover each component of Nakamoto. - -## Controlled Testnet - -Neon is the currently released controlled testnet that is available for us. It actually comes with two testnets, one which uses the new ClarityWASM VM (one of the components of Nakamoto) and one that uses the current Clarity VM. - -Argon is the next testnet to be released, slated for late February. - -Neon is available to be used now, get more details on the [Neon docs page](/docs/nakamoto/neon). - -Expect frequent changes to the testnets as it will be upgraded quite often. - -You can track the work being done on Nakamoto [on GitHub](https://github.com/stacks-network/stacks-core/milestones?direction=asc&sort=title&state=open). diff --git a/docs/nakamoto/neon.md b/docs/nakamoto/neon.md deleted file mode 100644 index ece2bc3372..0000000000 --- a/docs/nakamoto/neon.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Neon -description: How to get started with the Neon Nakamoto testnet -sidebar_label: Neon -sidebar_position: 6 ---- - -Neon is the first controlled testnet release for Nakamoto and ships with two separate testnets, one with the previous Clarity VM and one with the upcoming Clarity WASM. - -The primary purpose of these testnets is is performance benchmarking with the new consensus rules. - -Both testnets allow users and developers to view and interact with Nakamoto block production, meaning each testnet has Nakamoto coinbase transactions, testable VRF, tenure change transactions, and multiple Stacks blocks per Bitcoin block. - -Both testnets utilize Bitcoin Regtest and utilize a single miner, this is what is meant by "controlled" testnet. These testnets are producing blocks roughly every 5 seconds, which you can see reflected in the explorer. - -If non of that makes any sense, be sure to check out the previous pages of this Nakamoto section. - -Both testnets ship with functioning APIs and explorers to experiment with - -## Controlled Testnet 1 (Clarity VM) - -- [API](https://api.nakamoto-1.hiro.so/extended/v1/status) -- [Explorer](https://explorer.hiro.so/blocks?chain=testnet&api=https://api.nakamoto-1.hiro.so) - -## Controlled Testnet 2 (Clarity WASM) - -- [API](https://api.nakamoto-2.hiro.so/extended/v1/status) -- [Explorer](https://explorer.hiro.so/blocks?chain=testnet&api=https://api.nakamoto-2.hiro.so) - -You can also use this [preview version of Clarinet](https://github.com/hirosystems/clarinet/releases/tag/nakamoto-preview-1) in order to test Clarity WASM in your local Devnet. - -Further documentation on API endpoints and Stacks.js functions is forthcoming. diff --git a/docs/nakamoto/signer.md b/docs/nakamoto/signer.md deleted file mode 100644 index 8f5f3d9921..0000000000 --- a/docs/nakamoto/signer.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -title: Running a Signer -description: How to run a Stacks signer -sidebar_label: Running a Signer -sidebar_position: 4 ---- - -:::warning -This document intends to lay out all the steps required to run a signer on testnet after the “Argon” milestone is reached and deployed to testnet. Much of this will not work today, but is being included so that interested parties can familiarize themselves with the process as it will work after the Argon release. Argon is still in development and these instructions will change. -::: - -## Step by Step Instructions - -### 1. Generate TOML file - -Create a TOML file (`signers.toml`) with the following content: - -```toml -node_host = "127.0.0.1:20443" -endpoint = "127.0.0.1:30000" -network = "testnet" -``` - -### 2. Generate Keys - -You’ll need two private keys: - -`stacks_private_key`: the private key that corresponds to the public key that will be registered in the StackerDB -`message_private_key`: the key used when signing messages for block proposals and other messages. - -One way to generate a private key is using the `@stacks/cli` package. With node.js installed, run in the command line: - -`npx –yes @stacks/cli@latest make_keychain` - -You’ll see output like this: - -```json -{ - "mnemonic": "tilt invite caught shoe shed gravity guitar bench spot dial garlic cushion gate garlic need often boss spoon under fence used across tip use", - "keyInfo": { - "privateKey": "7567052905c21867fff273f5c018fb254a282499008d7e8181935a1a1855cb0601", - "publicKey": "0396152c9c1ba3edce6d708d9b652916a4a8320f3a4a5f44c7b1142002cf87882f", - "address": "SP2R765DGGBJRAEJD368QDWS471NRY4D566XKTSY8", - "btcAddress": "1H5ynzN1D9FPV7wknsAHR7RhoX1YBEoSy9", - "wif": "L19veovqpwzNgVgzY45ETu8nSMc8vp21vVjbHNdDN85KnUAEEKQX", - "index": 0 - } -} -``` - -Save the output somewhere. - -Take the `privateKey` property from that and add it to your `signer.toml` with the property `stacks_private_key. - -e.g. `stacks_private_key = "7567052905c21867fff273f5c018fb254a282499008d7e8181935a1a1855cb0601"` - -Next, we need to add the `message_private_key`. You can choose to reuse your Stacks private key or generate a new one. - -The `message_private_key` needs to be base58 encoded. You can use [this tool](https://appdevtools.com/base58-encoder-decoder) to encode the private key as base58. - -In the base58 encoding tool, paste in your `stacks_private_key` and set "Treat input as Hex". Make sure you delete the 01 at the end or the signer will throw an error. - -Take the output and add it to your signer.toml file: - -`message_private_key = "8uHp7CVqu8JWiPzW5g7FX2ZthwCKzyxVK9DfjiYjUkiy"` - -The config file should now look like this, but with different private keys: - -```toml -node_host = "127.0.0.1:20443" -endpoint = "127.0.0.1:30000" -network = "testnet" -stacks_private_key = "7567052905c21867fff273f5c018fb254a282499008d7e8181935a1a1855cb0601" -message_private_key = "8uHp7CVqu8JWiPzW5g7FX2ZthwCKzyxVK9DfjiYjUkiy" -``` - -:::note -At the moment, there are 3 other fields that need to be included, but those will be removed by the Argon release. Prior to argon, add this to the end of the config file if you want to run the signer: - -```toml -stackerdb_contract_id = "ST11Z60137Y96MF89K1KKRTA3CR6B25WY1Y931668.signers-stackerdb" -signer_id = 0 -signers = [ - {public_key = "swBaKxfzs4pQne7spxhrkF6AtB34WEcreAkJ8mPcqx3t", key_ids = [1, 2, 3, 4]}, - {public_key = "yDJhntuJczbss1XGDmyWtG9Wpw5NDqoBBnedxmyhKiFN", key_ids = [5, 6, 7, 8]}, - {public_key = "xNVCph6zd7HLLJcuwrWz1gNbFoPHjXxn7cyRvvTYhP3U", key_ids = [9, 10, 11, 12]}, - {public_key = "p2wFfLEbwGCmxCR5eGa46Ct6i3BVjFrvBixRn7FnCQjA", key_ids = [13, 14, 15, 16]}, - {public_key = "26jpUNnJPvzDJRJg3hfBn5s5MR4eQ4LLTokjrSDzByh4i", key_ids = [17, 18, 19, 20]} -] -``` - -::: - -### 3. Run the signer - -We don't yet have Docker images that include the stacks-signer binary, so in the meantime you'll build from source. [This pull request](https://github.com/stacks-network/stacks-core/pull/4268) changes our CI to include the stacks-signer binary in Docker builds. - -The signer will need to store state via disk, but that code is not yet built. Documentation will be created when it is more defined. - -Follow [these instructions](https://github.com/stacks-network/stacks-core?tab=readme-ov-file#building) for building the stacks-core repository from source. - -Once you've run `cargo build`, go back to the folder with your `signer.toml` file and run: - -```bash -# replace with the location of your `stacks-core` folder: -_STACKS_CORE_FOLDER_/target/debug/stacks-signer start --config signer.toml -``` - -You should see output that looks like this: - -```bash -Signer spawned successfully. Waiting for messages to process... -INFO [1705699009.844671] [stacks-signer/src/runloop.rs:438] [signer_runloop] Running one pass for signer ID# 0. Current state: Uninitialized -``` - -:::note -[This PR](https://github.com/stacks-network/stacks-core/pull/4280) adds a /status endpoint to the signer. Once the signer is running, the client should check this endpoint to ensure it is running and listening correctly. -::: - -## Production environment for Signer - -Running the signer in production requires two things: - -- A machine for running a Docker image -- A volume for storing state - -The Docker image needs to use a user-provided config file, which is used when running the signer. Depending on the production environment, there are typically two ways to do this: - -Use the default published image, which expects you to include the config file somewhere on disk -Create your own Dockerfile, which is a simple wrapper around the official image - -An example wrapper Dockerfile (this doesn’t work today!): - -```DOCKERFILE -FROM blockstack/stacks-core - -RUN mkdir -p /config - -COPY signer.toml /config/signer.toml - -CMD ["stacks-signer", "run", "--config", "/config/signer.toml"] -``` - -## System Requirements to Run a Signer - -https://github.com/stacksfoundation/miner-docs/blob/main/stacks-blockchain.md -https://github.com/stacksfoundation/miner-docs/blob/main/scripts/install_stacks.sh - -Minimum Requirements: run a full node, run the signer binary. 1 cpu, 4gb of ram, 150GB of storage as a minimum. diff --git a/docs/nakamoto/stacking.md b/docs/nakamoto/stacking.md deleted file mode 100644 index 4c5c22f647..0000000000 --- a/docs/nakamoto/stacking.md +++ /dev/null @@ -1,174 +0,0 @@ ---- -title: Stacking Flows -description: Stacking flows in Nakamoto -sidebar_label: Stacking Flows -sidebar_position: 5 ---- - -In Nakamoto, stacking flows have significant changes in comparison to previous versions of Stacks. Because Nakamoto requires stackers to run a signer, which validates blocks produced by Stacks miners, stackers need to provide new information when making Stacking transactions. - -These changes affect both solo Stacking and delegated Stacking. This document intends to outline the new flows for both cases, so that we can better understand what Stackers need to do to Stack in Nakamoto. - -## Definitions - -- Stacker: an entity locking their STX to receive PoX rewards. This is a broad term including solo Stackers and Stackers who use pools. -- Solo stacker: an entity that locks their own STX and runs a signer. They don’t receive delegation. -- Delegator: a stacker who locks their STX and delegates to a signer. They don’t run the signer. -- Delegatee: an entity that runs a Signer and allows others to delegate their STX to them. A delegatee doesn’t need to Stack their own STX, but they can. -- Signer: an entity that runs the stacks-signer software and participates in block validation. This can be either a solo Stacker an entity receiving delegated STX. In many cases we also refer to “signer” as the software that validates blocks. We may want to try and improve this language to be more clear. - -## First, run a signer - -This is a necessary prerequisite to stacking. - -Running a signer involves setting up a hosted production environment that includes both a Stacks Node and the Stacks Signer. For more information, refer to [how to run a signer](./signer.md). - -Once the signer software is running, the signer needs to keep track of the `stacks_private_key` that they used when configuring their signer. This will be used in subsequent Stacking transactions. - -## Signer keys and signer key signatures - -The main difference with Stacking in Nakamoto is that the Signer (either solo Stacker or signer running a pool) needs to include two new parameters in their Stacking transactions: - -1. `signer-key`: the public key that corresponds to the `stacks_private_key` their signer is using -2. `signer-signature`: a signature that demonstrates that this Stacker actually controls their `signer-key`. Because signer keys need to be unique, this is also a safety check to ensure that other Stackers can’t use someone else’s public key. - -## Generating a signer key signature - -The `signer-signature` uses the signer’s Stacks private key and creates a signature over the message (`pox-address`, `reward-cycle`), `where pox-address` is the BTC address used for rewards, and `reward-cycle` is the current reward cycle. - -The exact user experiences for generating the `signer-signature` is to be determined, but there are two high-level processes that can be expected: - -1. Using the stacks-signer or other CLI, via a command like `stacks-signer generate-stacking-signature {pox-address} {reward-cycle}`. -2. Using an application like a wallet or a web app. The signature is designed such that Stackers can use pre-existing standards for signing data with a wallet like [Leather](https://leather.io/) and [XVerse](https://www.xverse.app/). Stackers can also use hardware wallets to create this signature. - -Solo Stackers will likely generate their signature as a first step while making their Stacking transaction. - -### Using a hardware or software wallet to generate signatures - -When the signer is configured with a `stacks_private_key`, the signer may want to be able to use that key in a wallet to make stacking signatures. - -If the signer uses a tool like [@stacks/cli](https://docs.hiro.so/get-started/command-line-interface) to generate the key, the CLI also outputs a mnemonic (aka “seed phrase”) that can be imported into a wallet. Because the Stacks CLI uses the standard derivation path for generating Stacks keys, any Stacks wallet will default to having that same private key when the wallet is imported from a derivation path. Similarly, if a hardware wallet is setup with that mnemonic, then the Signer can use a wallet like Leather to make stacking signatures. - -The workflow for using a setting up a wallet to generate signatures would be: - -1. Use @stacks/cli to generate the keychain and private key. - 1. Typically, when using a hardware wallet, it’s better to generate the mnemonic on the hardware wallet. For this use case, however, the signer software needs the private key, and hardware wallets (by design) don’t allow exporting private keys. -2. Take the `privateKey` from the CLI output and add it to your signer’s configuration. -3. Take the mnemonic (24 words) and either: - 1. Setup a new hardware wallet with this mnemonic - 2. Store it somewhere securely, like a password manager. When the signer needs to generate signatures for Stacking transactions, they can import it into either Leather or XVerse. - -When the user needs to generate signatures: - -1. Setup your wallet with your signer key’s private key. Either: - 1. Setup your Leather wallet with a Ledger hardware wallet - 2. Import your mnemonic into Leather, XVerse, or another Stacks wallet -2. Open an app that has stacking signature functionality built-in -3. Connect your wallet to the app (aka sign in) -4. In the app, enter your PoX address and “submit” -5. The app will popup a window in your wallet that prompts you to sign the information - 1. The app will show clear information about what you’re signing -6. Create the signature - 1. If using a Ledger, confirm on your device -7. The app will display two results: - 1. Your signer key, which is the public key associated with your signer’s key - 2. Your signer signature -8. Finally, make a Stacking transaction using the signer key and signer signature. - -## Solo Stacking - -### Call the function `stack-stx` - -Just like in previous versions of PoX, Stackers call `stack-stx`, but with the new arguments added in Nakamoto. The arguments are: - -- Amount -- PoX Address: the BTC wallet to receive Stacking rewards -- Start burn height: the current BTC block height -- Lock period: the number of cycles to lock for (1 minimum, 12 max) -- Signer key: the public key that their signer is using -- Signer signature: the signature that proves control of this signer key - -### Act as a signer - -In the “prepare phase” before the next stacking cycle (100 blocks), the exact set of Stackers will be selected based on the amount of STX stacked. Just like in previous versions of PoX, each Stacker will have some number of reward slots based on the amount of STX locked. - -It is critical that Stackers have their signer running during this period. The prepare phase is when distributed key generation (DKG) occurs, which is used when validating blocks by signers. - -In general, Stackers don’t need to do anything actively during this period, other than monitoring their Signer to ensure it’s running properly. - -### Extending their stacking period - -Just like in the current version of PoX, Stackers can extend their lock period while still Stacking. The function called is `stack-extend`. - -Stackers can “rotate” their signing key when extending their lock period. - -The arguments are: - -- Extend count: the number of cycles to add to their lock period. The resulting lock period cannot be larger than 12. For example, if currently locked with 6 cycles remaining, the maximum number they can extend is 6. -- Pox Address: the BTC address to receive rewards -- Signer public key: the public key used for signing. This can stay the same, or the Stacker can use a new key. -- Signer signature: a signature proving control of their signing key - -## Delegated stacking - -Similar to the changes to solo Stacking, the big difference for delegation flows is the inclusion of signer keys and signatures. Because signers need to make transactions to “finalize” a delegation, these new arguments add new complexities to the signer. - -### Delegator initiates delegation - -The first step, where the delegator sets up their delegation to a signer, is to call `delegate-stx`. The arguments here are unchanged: - -- Amount -- Delegate to: the STX address of the signer they’re delegating to. Note that this is different from the “signer key” used. Instead, this is the STX address that is used to make PoX transactions. -- Until burn height: an optional argument where the delegation expires -- Pox Address: an option BTC address that, if specified, the signer must use to accept this delegation - -### Signer “activates” the delegation - -Just as in the current PoX contract, the signer calls `delegate-stack-stx` to commit the delegator’s STX. The arguments are: - -- Stacker: the STX address of the delegator -- Amount -- Pox Address -- Start burn height -- Lock period: number of cycles to lock for. If the delegator provided the until burn height argument, then the end of these cycles cannot be past the expiration provided. - -This step also allows the Signer to proactively choose which Stackers they’ll accept delegation from. For “closed” pools, the signer will only call this function for approved Stackers. It is up to each signer who runs a closed pool to implement this process, but tooling will likely be created to make this easier. - -This step can happen for many Stackers before going to the next step. - -### Signer “commits” delegated STX - -At this point, the STX are committed to the signer, and the signer has some “aggregate balance” of committed STX. The signer is not actually eligible for rewards and signer slots until this step is called. - -The signer cannot call this until the total number of STX committed is larger than the minimum threshold required to Stack. This threshold is a function of the total number of liquid STX. At the moment, the threshold is 90,000 STX. - -Once the threshold is reached, the signer calls `stack-aggregation-commit`. This is the point where the signer must provide their signer key and signer key signature. The arguments are: - -- Pox Address -- Reward-cycle: the current reward cycle -- Signer key: the public key of their signer -- Signer signature - -Once this succeeds, the signer is eligible for reward slots. The number of reward slots depends on the amount of STX committed to this signer. Even if the signer commits more than the “global minimum”, the minimum amount to receive a slot depends on the amount of STX locked for each cycle. For example, in the current PoX cycle, that amount is 110,000 STX. - -To act as a signer, each step up to this point must be taken before the prepare phase of the next cycle begins. It is crucial that the signer software is running. - -### Signer increases amount committed - -Even after the signer commits to a certain amount of STX in the previous step, the signer can increase this amount once more delegations are received. The initial steps must be taken for each Stacker (`delegate-stx` and then `delegate-stack-stx`), and then `stack-aggregation-increase` can be called. - -### The need for a separate “Delegate Private Key” - -The concept of the “signer key” or “signer private key” was introduced earlier in this document. The signer key is used during consensus mechanisms to sign blocks in Nakamoto. - -Signers using delegation also need a separate keychain to make Stacking transactions such as `delegate-stack-stx` listed earlier. They need a separate key because they need to have the ability to rotate their signer key when necessary. The PoX contract is designed to support rotating the signer key without needing their Stackers to un-stack and re-stack later. You cannot rotate a delegate key without needing to wait for all delegated Stackers to un-stack and finally re-stack to the new delegate address. - -Because of this limitation of being unable to rotate delegate addresses, it’s highly recommended to have a separate delegate key. The benefit of a separate delegate key is that it can easily be used in existing wallets, including hardware wallets. - -## Tooling for Stackers - -The exact tooling that will be available for both solo and delegated stacking is still in the works, but several options are being explored including: - -- CLI tooling -- Web apps -- BTC native multi-sigs diff --git a/docs/next-steps/index.md b/docs/next-steps/index.md deleted file mode 100644 index 00ddec9178..0000000000 --- a/docs/next-steps/index.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Next Steps -description: A guide to making a living in the Stacks world -sidebar_position: 7 ---- - -# Furthering Your Stacks Skills and Career - -The Stacks ecosystem is rapidly growing, and there are currently multiple ways for interested developers to monetize their hard work and make a living building the next generation of the Internet. - -## Awesome Stacks - -Awesome Stacks is a community-curated collection of resources for learning and building on Stacks. It has tons of helpful developer tools, companies, and learning resources to help you further your Stacks knowledge. - -[Awesome Stacks Repo](https://github.com/friedger/awesome-stacks-chain) - -## Grow Your Skills - -The first step to going pro is to level-up your skills. The best way to do that is through Clarity Universe, a comprehensive Clarity training camp that will take you from Stacks beginner to Clarity smart contract developer. - -[Register for Clarity Universe](https://clarity-lang.org/universe) - -## Stacks Jobs - -Multiple entities in the Stacks world are currently hiring. After you've learned how to build things on Stacks, you can show employers you are available for work and start looking for a full-time role in the Stacks job board. - -[View the Job Board](https://stacks.co/jobs) - -## Grants - -Have an idea for a project that could help the Stacks ecosystem? One of the Stacks Foundation's primary focuses is the grants program, which rewards builders for creating tools that benefit Stacks as a whole. - -[Apply for a Grant](https://stacks.org/grants) - -## Stacks Accelerator - -Interested in starting your own company? Join the Stacks Accelerator to get mentorship and funding to build the next great Stacks company. - -[Join the Accelerator](https://stacks.ac) diff --git a/docs/nodes-and-miners/digitalocean.md b/docs/nodes-and-miners/digitalocean.md deleted file mode 100644 index cf842d4762..0000000000 --- a/docs/nodes-and-miners/digitalocean.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: Run a Node with Digital Ocean -description: A guide to setup Stacks on DigitalOcean -sidebar_position: 2 -tags: - - tutorial ---- - -## Introduction - -This is a step by step guide to deploy the [Stacks Blockchain](https://github.com/stacks-network/stacks-blockchain) on [DigitalOcean](https://digitalocean.com). - -Build code is hosted on this [Github repository](https://github.com/stacksfoundation/stacks-machine-images) using the [methods from here](https://github.com/stacks-network/stacks-blockchain-docker) - -## Steps - -#### Step 1 - -Go to the [Stacks Blockchain page](https://marketplace.digitalocean.com/apps/stacks-blockchain) in DigitalOcean's marketplace. Click on `Create Stacks Blockchain Droplet`. -![](/img/sh_digitalocean-marketplace.png) - -#### Step 2 - -Choose a plan (it will only allow you to select a droplet that meets the minimum requirements) and your preferred datacenter region. -![](/img/sh_digitalocean-choose-plan.png) - -#### Step 3 - -Enter a root password or [enable SSH keys](https://docs.digitalocean.com/products/droplets/how-to/add-ssh-keys/) if your prefer. - -![](/img/sh_digitalocean-choose-authentication.png) - -#### Step 4 - -You can leave the rest of the options as they are and click on `Create Droplet` - -#### Step 5 - -You will need to wait a few seconds for the droplet to get created. Once created click on it to see more information. - -![](/img/sh_digitalocean-creating-droplet.png) - -![](/img/sh_digitalocean-created-droplet.png) - -### Step 6 - -Congratulations! You are now running the Stacks Blockchain. You can click on `Console` for a terminal window to open or login using SSH to the public IP you've been assigned to with user `root`. - -![](/img/sh_digitalocean-console-button.png) -![](/img/sh_digitalocean-console.png) - -## Getting started after deploying Stacks Blockchain - -Once the droplet is launched, the initial startup can take several minutes while BNS data is imported (this is a one time operation) and the Bitcoin headers are synced. - -To keep track of the progress, you can `ssh root@your_droplet_public_ipv4` to the host and run: `/opt/stacks-blockchain-docker/manage.sh -n mainnet -a logs`. - -After the stacks blockchain finishes the initial header sync and starts to sync with its peers, the application ports will open (`20443` and `3999`) and HTTP port `80` will now start proxying requests. - -Use `http://your_droplet_public_ipv4` to access the data directly, with output being similar to: - -```json -{ - "server_version": "stacks-blockchain-api v6.2.3 (master:77ab3ae2)", - "status": "ready", - "chain_tip": { - "block_height": 91820, - "block_hash": "0x06b276e85f238151414616618ae0adaf5eeda4eac6cad5bbefceeb37948ab275", - "index_block_hash": "0x4d7c075d7ab0f90b1dbc175f5c42b7344265d00cfef202dd9681d95388eeed8c", - "microblock_hash": "0xcf4f9037cc10696b2812b617ca105885be625c6acf8ad67e71bb4c09fa6ebb21", - "microblock_sequence": 4 - } -} -``` - -:::tip -For the full list of API endpoints for the Stacks Blockchain, consult the [Hiro API Docs](https://docs.hiro.so/api) -::: - -All services are managed by a [systemd unit file](https://github.com/stacksfoundation/stacks-machine-images/blob/master/files/etc/systemd/system/stacks.service) that is set to start on boot. - -Manual control is also possible via the [manage.sh script](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/manage.sh) at `/opt/stacks-blockchain-docker/manage.sh` on the host. - -Full details on how to use the manage.sh script is [available here](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/docs/usage.md). - -## Launching a Droplet using the DigitalOcean API - -In addition to creating a Droplet from the Stacks Blockchain 1-Click App via the control panel, you can also use the [DigitalOcean API](https://digitalocean.com/docs/api). - -As an example, to create a 4GB Stacks Blockchain Droplet in the SFO2 region, you can use the following curl command. You’ll need to either save your [API access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/) to an environment variable or substitute it into the command below. - -:::note -_The `name`, `region` and `size` values below are hardcoded, so adjust as desired._ -::: - -```bash -$ export TOKEN= -$ curl -X POST -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer '$TOKEN'' -d \ - '{"name":"stacks-blockchain","region":"sfo2","size":"s-2vcpu-4gb","image":"stacksfoundation-stacksblockchain"}' \ - "https://api.digitalocean.com/v2/droplets" -``` diff --git a/docs/nodes-and-miners/hosted-nodes.md b/docs/nodes-and-miners/hosted-nodes.md deleted file mode 100644 index eb8c25322f..0000000000 --- a/docs/nodes-and-miners/hosted-nodes.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Run a Node with a Hosted Provider -description: A guide to setup Stacks on a hosted provider -sidebar_position: 3 -tags: - - tutorial ---- - -We're always looking for new hosting providers that enable anyone to run the Stacks Blockchain. -Below, you'll find some examples on the current providers that are know to support running a node. - -## Quicknode - -Please refer to the [Quicknode Section](./quicknode) for instructions on launching an instance with Quicknode. - -## Stacks on Render - -The [render-stacks](https://github.com/stacksfoundation/render-stacks) GitHub repo has instructions so anyone can deploy a Stacks node to the hosted [Render](https://render.com) service in one click. - -:::note -While it is _possible_ to use the free plan with some modifications, _ ***it is recommended to run this on paid plan*** _ -::: - -## Stacks on Fly - -The [fly-stacks](https://github.com/stacksfoundation/fly-stacks) GitHub repo has instructions so anyone can deploy a Stacks node to the hosted [Fly](https://fly.io) service. diff --git a/docs/nodes-and-miners/index.md b/docs/nodes-and-miners/index.md deleted file mode 100644 index e5f4f2c250..0000000000 --- a/docs/nodes-and-miners/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Nodes and Miners -description: Nodes and Miners -sidebar_position: 5 ---- - -This section will walk through the technical setup steps required to run Stacks Blockchain nodes and miners. There are multiple options available for running a node, including Docker, Digital Ocean, and Render. - -Running your own Stacks node is a great way to increase the decentralization of the ecosystem and not have to rely on any third-party, centralized providers. - -Although it does take some more effort and setup, it's a valuable exercise in understanding how the different pieces of a Stacks Dapp interact with each other. diff --git a/docs/nodes-and-miners/miner-costs-and-fees.md b/docs/nodes-and-miners/miner-costs-and-fees.md deleted file mode 100644 index f1838b6268..0000000000 --- a/docs/nodes-and-miners/miner-costs-and-fees.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Miner costs and fees -description: Miner Cost and Fee Estimation -sidebar_position: 8 ---- - -## Configuring Cost and Fee Estimation - -Fee and cost estimators can be configured via the config section `[fee_estimation]`: - -```toml -[fee_estimation] -cost_estimator = naive_pessimistic -fee_estimator = fuzzed_weighted_median_fee_rate -fee_rate_fuzzer_fraction = 0.1 -fee_rate_window_size = 5 -cost_metric = proportion_dot_product -log_error = true -enabled = true -``` - -Fee and cost estimators observe transactions on the network and use the observed costs of those transactions to build estimates for viable fee rates -and expected execution costs for transactions. -Estimators and metrics can be selected using the configuration fields above, though the default values are the only options currently. `log_error` controls whether or not the INFO logger will display information about the cost estimator accuracy as new costs are observed. Setting `enabled = false` turns off the cost estimators. -Cost estimators are **not** consensus-critical components, but rather can be used by miners to rank transactions in the mempool or client to determine appropriate fee rates for transactions before broadcasting them. - -The `fuzzed_weighted_median_fee_rate` uses a median estimate from a window of the fees paid in the last `fee_rate_window_size` blocks. -Estimates are then randomly "fuzzed" using uniform random fuzz of size up to `fee_rate_fuzzer_fraction` of the base estimate. - -There is also a [mining calculator](https://friedger.id/mining-calculator/) that can help you with this process, with the [source code available here](https://github.com/friedger/mining-calculator). diff --git a/docs/nodes-and-miners/miner-mainnet.md b/docs/nodes-and-miners/miner-mainnet.md deleted file mode 100644 index 59b955a976..0000000000 --- a/docs/nodes-and-miners/miner-mainnet.md +++ /dev/null @@ -1,277 +0,0 @@ ---- -title: Mine mainnet Stacks tokens -description: Set up and run a miner on Stacks Mainnet -sidebar_position: 6 -tags: - - tutorial ---- - -## Introduction - -For more on the technical details of mining, please review the [mining guide](../stacks-academy/mining) - -The following is an abridged version of the [walkthrough here](https://github.com/stacksfoundation/miner-docs), written for a Linux system. If you're on Windows or MacOS, there will be some slight modifications needed ([PR's welcome!](../contribute/docs)). - -If you're interested in mining on the Stacks testnet, you can find instructions on how to do that [here](miner-testnet): - -## Running a Bitcoin Mainnet Full Node - -To participate as a miner on mainnet, you must have access to a mainnet bitcoin node with a wallet (and the wallet's private key). One way to accomplish this is to run bitcoin locally. - -- [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements#system-requirements) - -First, download a [bitcoin binary](https://bitcoin.org/en/download), or [build from source](https://github.com/stacksfoundation/miner-docs/blob/main/bitcoin.md#source-install) -If you want to learn more about the technical details of mining, please review the [mining guide](../stacks-academy/mining): - -:::tip -It is recommened to use a persistent location for the chainstate, in the steps below we're using `/bitcoin` -::: - -### Update the Bitcoin Configuration File - -Next, update the bitcoin configuration: - -- **optional but recommended:** Use a persistent directory to store the Bitcoin chainstate, i.e. `datadir=/bitcoin` -- **optional but recommended:** Update the `rpcallowip` value to only allow `127.0.0.1`, or the stacks miner IPv4 -- Modify the `rpcuser` and `rpcpassword` values from the defaults below -- Store the following configuration somewhere on your filesystem (ex: `$HOME/bitcoin.conf`) - -```toml -server=1 -disablewallet=0 -datadir=/bitcoin -rpcuser=btcuser -rpcpassword=btcpassword -rpcallowip=0.0.0.0/0 -bind=0.0.0.0:8333 -rpcbind=0.0.0.0:8332 -dbcache=512 -banscore=1 -rpcthreads=256 -rpcworkqueue=256 -rpctimeout=100 -txindex=1 -``` - -### Start Bitcoin - -Finally, start bitcoin as follows (adjust the `conf` path to where it was created in the previous step, i.e. `$HOME/bitcoin.conf`): - -```bash -bitcoind -conf=$HOME/bitcoin.conf -``` - -:::note -It will take a few days for the node to synchronize with Bitcoin mainnet. -::: - -While it's syncing, you can track the progress with `bitcoin-cli` or the logfile (will be located where the chainstate is stored, i.e. `/bitcoin/debug.log`): - -```bash -$ bitcoin-cli \ - -rpcconnect=localhost \ - -rpcport=8332 \ - -rpcuser=btcuser \ - -rpcpassword=btcpassword \ -getblockchaininfo | jq .blocks -773281 -``` - ---- - -## Running a Stacks Blockchain miner - -First, download a [stacks blockchain binary](https://github.com/stacks-network/stacks-blockchain/releases/latest), or [build from source](https://github.com/stacksfoundation/miner-docs/blob/main/stacks-blockchain.md#build-and-install-stacks-blockchain-from-source) - -_There may be some extra requirements to building, [defined here](https://github.com/stacksfoundation/miner-docs/blob/main/prerequisites.md#install-required-packages)_ - -:::tip -It is recommened to use a persistent location for the chainstate, in the steps below we're using `/stacks-blockchain` -::: - -### Generate a keychain - -First, a keychain needs to be generated. With this keychain, we'll purchase some BTC from a cryptocurrency exchange, and then use that BTC to start mining. - -To create a keychain, the simplest way is to use the [stacks-cli](https://docs.hiro.so/references/stacks-cli) with the `make_keychain` command. - -```bash -npx @stacks/cli make_keychain 2>/dev/null | jq -r -``` - -After this runs, you should see some JSON printed to the screen that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -:::warning -**Do not lose this information** - we'll need to use the `privateKey` and `btcAddress` fields in later steps. -::: - -The above `btcAddress` (mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND) will then need to be imported into the bitcoin mainnet network. -:::note -Be sure to replace `` with the bitcoin address in the "Generate a keychain" step -::: - -```bash -bitcoin-cli \ - -rpcport=8332 \ - -rpcuser=btcuser \ - -rpcpassword=btcpassword \ -importaddress -``` - - - -Once imported, we need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - - - -### Update the Stacks Blockchain Configuration File - -Now, we need to configure our node to use this Bitcoin keychain. Copy the [sample mainnet miner config](https://raw.githubusercontent.com/stacks-network/stacks-blockchain/master/testnet/stacks-node/conf/mainnet-miner-conf.toml) to your local machine in a _memorable_ location like `$HOME/mainnet-miner-conf.toml`. - -Now, grab your `privateKey` from earlier when you ran the `make_keychain` command. -Replace the `seed` and `local_peer_seed` field with your private key. Save and close this configuration file. - -Next, update the bitcoin configuration: - -- **optional but recommended:** Use a persistent directory to store the Stacks chainstate, i.e. `working_dir = "/stacks-blockchain"` -- From the `make_keychain` step, modify the `seed` and `local_peer_seed` values with `privatekey` -- Store the following configuration somewhere on your filesystem (ex: `$HOME/mainnet-miner-conf.toml`) - -```toml -[node] -working_dir = "/stacks-blockchain" -rpc_bind = "0.0.0.0:20443" -p2p_bind = "0.0.0.0:20444" -seed = "" -local_peer_seed = "" -miner = true -bootstrap_node = "02da7a464ac770ae8337a343670778b93410f2f3fef6bea98dd1c3e9224459d36b@seed-0.mainnet.stacks.co:20444,02afeae522aab5f8c99a00ddf75fbcb4a641e052dd48836408d9cf437344b63516@seed-1.mainnet.stacks.co:20444,03652212ea76be0ed4cd83a25c06e57819993029a7b9999f7d63c36340b34a4e62@seed-2.mainnet.stacks.co:20444" - -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "127.0.0.1" -username = "" -password = "" -rpc_port = 8332 -peer_port = 8333 -satoshis_per_byte = 100 -burn_fee_cap = 20000 -``` - -### Start the Stacks Blockchain - -To run your miner, run this in the command line: - -```bash -stacks-node start --config=$HOME/mainnet-miner-conf.toml -``` - -Your node should start. It will take some time to sync, and then your miner will be running. - -### Enable Debug Logging - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -STACKS_LOG_DEBUG=1 stacks-node start --config=$HOME/mainnet-miner-conf.toml -``` - ---- - -## Optional: Running a Stacks Blockchain miner with Docker - -Alternatively, you can run a Stacks mainnet miner with Docker. - -:::caution -Ensure you have [Docker](https://docs.docker.com/get-docker/) installed. -::: - -### Generate a Keychain and Get Some Tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null | jq -r -``` - -We need to get some BTC to that address. You should be able to transfer BTC to this address using a cryptocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Update Stacks Blockchain Docker Configuration File - -Use the steps oulined above to create the [configuration file](miner-mainnet#update-the-stacks-blockchain-configuration-file) - -### Start the Stacks Blockchain miner with Docker - -:::info -The ENV VARS `RUST_BACKTRACE` and `STACKS_LOG_DEBUG` are optional. If removed, debug logs will be disabled -::: - -```bash -docker run -d \ - --name stacks_miner \ - --rm \ - --network host \ - -e RUST_BACKTRACE="full" \ - -e STACKS_LOG_DEBUG="1" \ - -v "$HOME/mainnet-miner-conf.toml:/src/stacks-node/mainnet-miner-conf.toml" \ - -v "/stacks-blockchain:/stacks-blockchain" \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain:latest \ -/bin/stacks-node start --config /src/stacks-node/mainnet-miner-conf.toml -``` - -You can review the node logs with this command: - -```bash -docker logs -f stacks_miner -``` - -## Optional: Running in Kubernetes with Helm - -In addition, you're also able to run a Stacks miner in a Kubernetes cluster using the [stacks-blockchain Helm chart](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). - -Ensure you have the following prerequisites installed: - -- [Docker](https://docs.docker.com/get-docker/) -- [minikube](https://minikube.sigs.k8s.io/docs/start/) (Only needed if standing up a local Kubernetes cluster) -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [helm](https://helm.sh/docs/intro/install/) - -### Generate keychain and get some tokens - -Use the steps [outlined above](miner-mainnet#generate-a-keychain-and-get-some-tokens) - -### Install the chart and run the miner - -To install the chart with the release name `my-release` and run the node as a miner: - -```bash -minikube start # Only run this if standing up a local Kubernetes cluster -helm repo add blockstack https://charts.blockstack.xyz -helm install my-release blockstack/stacks-blockchain \ - --set config.node.miner=true \ - --set config.node.seed="replace-with-your-privateKey-from-generate-keychain-step" \ - --set config.burnchain.mode="mainnet" -``` - -You can review the node logs with this command: - -```bash -kubectl logs -l app.kubernetes.io/name=stacks-blockchain -``` - -For more information on the Helm chart and configuration options, please refer to the [chart's homepage](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). diff --git a/docs/nodes-and-miners/miner-testnet.md b/docs/nodes-and-miners/miner-testnet.md deleted file mode 100644 index 0a83d57a73..0000000000 --- a/docs/nodes-and-miners/miner-testnet.md +++ /dev/null @@ -1,292 +0,0 @@ ---- -title: Mine testnet Stacks tokens -description: Set up and run a miner on Stacks Testnet -sidebar_position: 5 -tags: - - tutorial ---- - -## Introduction - -For more on the technical details of mining, please review the [mining guide](../stacks-academy/mining) - -The following is an abridged version of the [walkthrough here](https://github.com/stacksfoundation/miner-docs/tree/testnet), written for a Linux system. If you're on Windows or MacOS, there will be some slight modifications needed ([PR's welcome!](../contribute/docs)). - -If you're interested in mining on the Stacks mainnet, you can find instructions on how to do that [here](miner-mainnet): - -## Running a Bitcoin Testnet Full Node - -To participate as a miner on testnet, you must have access to a testnet bitcoin node with a wallet (and the wallet's private key). One way to accomplish this is to run bitcoin locally. - -- [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements#system-requirements) - -First, download a [bitcoin binary](https://bitcoin.org/en/download), or [build from source](https://github.com/stacksfoundation/miner-docs/blob/main/bitcoin.md#source-install) - -:::tip -It is recommened to use a persistent location for the chainstate, in the steps below we're using `/bitcoin` -::: - -### Update the Bitcoin Configuration File - -Next, update the bitcoin configuration: - -- **optional but recommended:** Use a persistent directory to store the Bitcoin chainstate, i.e. `datadir=/bitcoin` -- **optional but recommended:** Update the `rpcallowip` value to only allow `127.0.0.1`, or the stacks miner IPv4 -- Modify the `rpcuser` and `rpcpassword` values from the defaults below -- Store the following configuration somewhere on your filesystem (ex: `$HOME/bitcoin.conf`) - -```toml -server=1 -testnet=1 -disablewallet=0 -datadir=/bitcoin -rpcuser=btcuser -rpcpassword=btcpass -rpcallowip=0.0.0.0/0 -dbcache=512 -banscore=1 -rpcthreads=256 -rpcworkqueue=256 -rpctimeout=100 -txindex=1 - -[test] -bind=0.0.0.0:18333 -rpcbind=0.0.0.0:18332 -rpcport=18332 -``` - -### Start Bitcoin - -Finally, start bitcoind as follows: - -```bash -bitcoind -conf=$HOME/bitcoin.conf -``` - -:::note -It will take a few hours for the node to synchronize with Bitcoin testnet. -::: - -While it's syncing, you can track the progress with `bitcoin-cli` or the logfile (will be located where the chainstate is stored, i.e. `/bitcoin/testnet3/debug.log`): - -```bash -$ bitcoin-cli \ - -rpcconnect=localhost \ - -rpcport=18332 \ - -rpcuser=btcuser \ - -rpcpassword=btcpass \ -getblockchaininfo | jq .blocks -2417570 -``` - ---- - -## Running a Stacks Blockchain miner - -First, download a [stacks blockchain binary](https://github.com/stacks-network/stacks-blockchain/releases/latest), or [build from source](https://github.com/stacksfoundation/miner-docs/blob/main/stacks-blockchain.md#build-and-install-stacks-blockchain-from-source) - -_There may be some extra requirements to building, [defined here](https://github.com/stacksfoundation/miner-docs/blob/main/prerequisites.md#install-required-packages)_ - -:::tip -It is recommened to use a persistent location for the chainstate, in the steps below we're using `/stacks-blockchain` -::: - -### Generate a keychain - -First, a keychain needs to be generated. With this keychain, we'll get some testnet BTC from a faucet, and then use that BTC to start mining. - -To create a keychain, the simplest way is to use the [stacks-cli](https://docs.hiro.so/references/stacks-cli) with the `make_keychain` command. - -```bash -npx @stacks/cli make_keychain -t 2>/dev/null | jq -r -``` - -After this runs, you should see some JSON printed to the screen that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -:::warning -**Do not lose this information** - we'll need to use the `privateKey` and `btcAddress` fields in later steps. -::: - -The above `btcAddress` (mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND) will then need to be imported into the bitcoin testnet network. -:::note -Be sure to replace `` with the bitcoin address in the "Generate a keychain" step -::: - -```bash -bitcoin-cli \ - -rpcport=18332 \ - -rpcuser=btcuser \ - -rpcpassword=btcpassword \ -importaddress -``` - -Once imported, we need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). You'll be sent `0.01` testnet BTC to that address. - -### Update the Stacks Blockchain Configuration File - -Now, we need to configure our node to use this Bitcoin keychain. Copy the [sample testnet miner config](https://raw.githubusercontent.com/stacks-network/stacks-blockchain/master/testnet/stacks-node/conf/testnet-miner-conf.toml) to your local machine in a _memorable_ location like `$HOME/testnet-miner-conf.toml`. - -Now, grab your `privateKey` from earlier when you ran the `make_keychain` command. -Replace the `seed` and `local_peer_seed` field with your private key. Save and close this configuration file. - -Next, update the bitcoin configuration: - -- **optional but recommended:** Use a persistent directory to store the Stacks chainstate, i.e. `working_dir = "/stacks-blockchain"` -- From the `make_keychain` step, modify the `seed` and `local_peer_seed` values with `privatekey` -- Store the following configuration somewhere on your filesystem (ex: `$HOME/testnet-miner-conf.toml`) - -```toml -[node] -working_dir = "/stacks-blockchain" -rpc_bind = "0.0.0.0:20443" -p2p_bind = "0.0.0.0:20444" -seed = "" -local_peer_seed = "" -miner = true -bootstrap_node = "047435c194e9b01b3d7f7a2802d6684a3af68d05bbf4ec8f17021980d777691f1d51651f7f1d566532c804da506c117bbf79ad62eea81213ba58f8808b4d9504ad@testnet.stacks.co:20444" -wait_time_for_microblocks = 10000 - -[burnchain] -chain = "bitcoin" -mode = "xenon" -peer_host = "127.0.0.1" -username = "" -password = "" -rpc_port = 18332 -peer_port = 18333 - -[[ustx_balance]] -address = "ST2QKZ4FKHAH1NQKYKYAYZPY440FEPK7GZ1R5HBP2" -amount = 10000000000000000 - -[[ustx_balance]] -address = "ST319CF5WV77KYR1H3GT0GZ7B8Q4AQPY42ETP1VPF" -amount = 10000000000000000 - -[[ustx_balance]] -address = "ST221Z6TDTC5E0BYR2V624Q2ST6R0Q71T78WTAX6H" -amount = 10000000000000000 - -[[ustx_balance]] -address = "ST2TFVBMRPS5SSNP98DQKQ5JNB2B6NZM91C4K3P7B" -amount = 10000000000000000 -``` - -### Start the Stacks Blockchain - -To run your miner, run this in the command line: - -```bash -stacks-node start --config=$HOME/testnet-miner-conf.toml -``` - -Your node should start. It will take some time to sync, and then your miner will be running. - -### Enable Debug Logging - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -STACKS_LOG_DEBUG=1 stacks-node start --config=$HOME/testnet-miner-conf.toml -``` - ---- - -## Optional: Running a Stacks Blockchain miner with Docker - -Alternatively, you can run a Stacks testnet miner with Docker. - -:::caution -Ensure you have [Docker](https://docs.docker.com/get-docker/) installed -::: - -### Generate a Keychain and Get Some Tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null | jq -r -``` - -Now, we need to get some tBTC. Grab the `btcAddress` field, and paste it into this Bitcoin testnet faucet. You'll be sent `0.01` tBTC to that address. - -### Update Stacks Blockchain Docker Configuration File - -Use the steps oulined above to create the [configuration file](miner-testnet#update-the-stacks-blockchain-configuration-file) - -### Start the Stacks Blockchain miner with Docker - -:::info -The ENV VARS `RUST_BACKTRACE` and `STACKS_LOG_DEBUG` are optional. If removed, debug logs will be disabled -::: - -```bash -docker run -d \ - --name stacks_miner \ - --rm \ - --network host \ - -e RUST_BACKTRACE="full" \ - -e STACKS_LOG_DEBUG="1" \ - -v "$HOME/testnet-miner-conf.toml:/src/stacks-node/testnet-miner-conf.toml" \ - -v "/stacks-blockchain:/stacks-blockchain" \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain:latest \ -/bin/stacks-node start --config /src/stacks-node/testnet-miner-conf.toml -``` - -You can review the node logs with this command: - -```bash -docker logs -f stacks_miner -``` - ---- - -## Optional: Running in Kubernetes with Helm - -In addition, you're also able to run a Stacks miner in a Kubernetes cluster using the [stacks-blockchain Helm chart](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). - -Ensure you have the following prerequisites installed: - -- [Docker](https://docs.docker.com/get-docker/) -- [minikube](https://minikube.sigs.k8s.io/docs/start/) (Only needed if standing up a local Kubernetes cluster) -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [helm](https://helm.sh/docs/intro/install/) - -### Generate keychain and get some tokens - -Use the steps [outlined above](miner-testnet#generate-a-keychain-and-get-some-tokens) - -### Install the chart and run the miner - -To install the chart with the release name `my-release` and run the node as a miner: - -```bash -minikube start # Only run this if standing up a local Kubernetes cluster -helm repo add blockstack https://charts.blockstack.xyz -helm install my-release blockstack/stacks-blockchain \ - --set config.node.miner=true \ - --set config.node.seed="replace-with-your-privateKey-from-generate-keychain-step" \ -``` - -You can review the node logs with this command: - -```bash -kubectl logs -l app.kubernetes.io/name=stacks-blockchain -``` - -For more information on the Helm chart and configuration options, please refer to the [chart's homepage](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). diff --git a/docs/nodes-and-miners/quicknode-endpoint.png b/docs/nodes-and-miners/quicknode-endpoint.png deleted file mode 100644 index 0bde1b9353..0000000000 Binary files a/docs/nodes-and-miners/quicknode-endpoint.png and /dev/null differ diff --git a/docs/nodes-and-miners/quicknode.md b/docs/nodes-and-miners/quicknode.md deleted file mode 100644 index 1281964689..0000000000 --- a/docs/nodes-and-miners/quicknode.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Run a Node with QuickNode -description: A guide to setup Stacks on QuickNode -sidebar_position: 4 -tags: - - tutorial ---- - -[QuickNode](https://www.quicknode.com/) is a service for rapidly getting set up with a Stacks node. - -As an easy and fast alternative to running your own node, you can utilize QuickNode to serve as an API. - -To get started, [set up an account](https://www.quicknode.com/signup) on QuickNode. - -Once you are signed in, getting set up with your own Stacks node is a matter of a few clicks, starting with 'Create an endpoint'. - -![Set up a QuickNode endpoint](./quicknode-endpoint.png) - -From there, you just need to select Stacks, your desired network, and your desired QuickNode plan level. - -_That's it._ - -You now have an API endpoint URL you can use to connect to Stacks. - -How do you do that? - -It depends on the frontend framework you are using, but let's see how to do it with Stacks.js. - -First, you'll need to install the `@stacks/network` package. - -Next we'll import it: - -```javascript -import { StacksTestnet } from "@stacks/network"; -``` - -Then in your frontend, set up the network with the following line: - -```javascript -const network = new StacksTestnet({ url: "" }); -``` - -Then you can call transactions like you normally would using the `@stacks/transactions` library. - -For an example of how to do this, please refer to the [Hello Stacks](../tutorials/hello-stacks.md) tutorial. diff --git a/docs/nodes-and-miners/run-a-node.md b/docs/nodes-and-miners/run-a-node.md deleted file mode 100644 index ddfe34690c..0000000000 --- a/docs/nodes-and-miners/run-a-node.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: Run a Node with Docker -description: Set up and run a Stacks node -sidebar_position: 1 -tags: - - tutorial ---- - -## Stacks Blockchain with Docker - -Run your own Stacks Blockchain node using [docker-compose](https://docs.docker.com/compose/) with just few commands using [stacks-blockchain-docker](https://github.com/stacks-network/stacks-blockchain-docker) - -- [Quickstart](./run-a-node#quickstart) -- [Requirements](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/docs/requirements.md) -- [Docker Setup](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/docs/docker.md) -- [Configuration](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/docs/config.md) -- [Upgrading](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/docs/upgrade.md) -- [Common Issues](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/docs/issues.md) - -## **Requirements:** - -The **minimum viable requirements** are listed below. - -While you _can_ run a node using these specs, it's _recommended_ to assign more than the minimum for better performance. - -- ⚠️ [docker-compose](https://docs.docker.com/compose/install/) version `2.2.2` or greater is **required** -- **4GB memory** -- **1 Vcpu** ( _minimum of 2 Vcpu is recommended_ ) -- **100GB disk** ( _minimum of 150GB SSD is recommended_ ) - -:::caution MacOS with an ARM processor is NOT recommended - -The way Docker for Mac on an Arm CPU is designed makes the I/O incredibly slow, and blockchains are **_very_** heavy on I/O. -This only seems to affect MacOS, other Arm based systems like Raspberry Pi work as expected. -::: - -## **Quickstart** - -The `` placeholder used below can be replaced with one of: - -- mainnet -- testnet -- mocknet - -1. **Clone the stacks-blockchain-docker repository locally** - -```bash -git clone https://github.com/stacks-network/stacks-blockchain-docker && cd stacks-blockchain-docker -``` - -2. **Start the Services** - -```bash -./manage.sh -n -a start -``` - -:::note With an optional HTTP proxy on port 80: - -```bash -./manage.sh -n -a start -f proxy -``` - -::: - -## **Accessing the services** - -:::tip -For networks other than `mocknet`, downloading the initial headers can take several minutes. Until the headers are downloaded, the `/v2/info` endpoints won't return any data. - -Follow the logs to track the sync progress: - -```bash -./manage.sh -n -a logs -``` - -::: - -**stacks-blockchain**: - -- Ports `20443-20444` are exposed on `localhost` - -```bash -curl -sL localhost:20443/v2/info | jq -r -``` - -**stacks-blockchain-api**: - -- Port `3999` is exposed on `localhost` - -```bash -curl -sL localhost:3999 | jq -r -``` - -**proxy**: - -- Port `80` is exposed on `localhost` - -```bash -curl -sL localhost/v2/info | jq -r -curl -sL localhost | jq -r -``` - ---- - -## Upgrades - -:::caution -For schema-breaking upgrades to running instances of this repo, you'll need to [run an event-replay](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/docs/upgrade.md): -::: - ---- diff --git a/docs/nodes-and-miners/stacks-node-configuration.md b/docs/nodes-and-miners/stacks-node-configuration.md deleted file mode 100644 index daa1906268..0000000000 --- a/docs/nodes-and-miners/stacks-node-configuration.md +++ /dev/null @@ -1,556 +0,0 @@ ---- -title: Stacks Node Configuration -description: Configuration parameters and options for the stacks-node binary -sidebar_position: 4 ---- - -## Usage - -```bash -stacks-node sub-command [--subcommand-option ] -``` - -### Subcommands - -- `mocknet`: start a mocknet instance using defaults -- `testnet`: start a testnet instance using defaults (chainstate is not persistent) -- `mainnet`: start a mainnet instance using defaults (chainstate is not persistent) -- `start`: combined with `--config`, starts an instance with a specified configuration file -- `version`: displays binary version -- `help`: displays the help message - -## Configuration File Options - -The Stacks Blockchain configuration file has multiple sections under which an option may be placed. - -- [node](./stacks-node-configuration#node) -- [events_observer](./stacks-node-configuration#events_observer) -- [connection_options](./stacks-node-configuration#connection_options) -- [burnchain](./stacks-node-configuration#burnchain) -- [ustx_balance](./stacks-node-configuration#ustx_balance) - -For reference, several configuration file examples are [available here](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf) - -- [Example mainnet follower configuration](./stacks-node-configuration#example-mainnet-follower-configuration) - -### node - -Contains various configuration options for the stacks-node binary. - -| Name | Required | Description | -| ------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- | -| rpc_bind | ✓ | IPv4 address and port to open for RPC connections | -| p2p_bind | ✓ | IPv4 address and port to open for P2P connections | -| working_dir | | Absolute path to the directory where chainstate data will be stored | -| data_url | | IPv4 address and port for incoming RPC connections | -| p2p_address | | IPv4 address and port for incoming P2P connections | -| bootstrap_node | | Public key, IPv4 address, and port to bootstrap the chainstate | -| wait_time_for_microblocks | | The amount of time in ms to wait before trying to mine a block after catching up to the anchored chain tip | -| seed | | The [private key](./miner-mainnet#generate-a-keychain) to use for mining. Only needed if `miner` is set to `true` | -| local_peer_seed | | The [private key](./miner-mainnet#generate-a-keychain) to use for signing P2P messages in the networking stack | -| miner | | Determines whether the node is running a follower (`false`) or a miner (`true`). Defaults to `false` | -| mock_miner | | Simulates running a miner (typically used for debugging) | -| mine_microblocks | | Determines whether the node will mine microblocks. Will only take effect if `miner` is set to `true` | -| prometheus_bind | | Address and port for Prometheus metrics collection. | - -### events_observer - -:::info -This section is _optional_ and not required - -However, if this section is added, **all** fields are required -::: -Contains options for sending events emitted to the [stacks-blockchain-api](https://github.com/hirosystems/stacks-blockchain-api) service. - -| Name | Required | Description | -| ----------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | -| endpoint | ✓ | Address and port to a [stacks-blockchain-api](https://github.com/hirosystems/stacks-blockchain-api) service | -| retry_count | ✓ | Number of times to retry sending events to the endpoint before failing | -| events_keys | ✓ | Event keys for which to watch. The emitted node events can be restricted by account, function name and event type. Asterix ("\*") can be used to emit all events. | | - -### connection_options - -:::info -This section is _optional_ and not required. - -However, if this section is added, **all** fields are required -::: - -Specifies configuration options for others connecting to the stacks node. - -| Name | Required | Description | -| -------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -| public_ip_address | ✓ | Public IPv4 to advertise to other nodes | -| download_interval | ✓ | Time (in seconds) between attempts to download blocks | -| walk_interval | ✓ | Time (in seconds) between attempts to walk the list of neighbors | -| read_only_call_limit_read_length | ✓ | Total number of bytes allowed to be read by an individual read-only function call | -| read_only_call_limit_read_count | ✓ | Total number of independent read operations permitted for an individual read-only function call | -| read_only_call_limit_runtime | ✓ | [Runtime cost](https://github.com/stacksgov/sips/blob/main/sips/sip-006/sip-006-runtime-cost-assessment.md) limit for an individual read-only function call | - -### burnchain - -This section contains configuration options pertaining to the blockchain the stacks-node binds to on the backend for proof-of-transfer (BTC). - -| Name | Required | Description | -| --------- | -------- | -------------------------------------------------------------------------------------------------------------------- | -| chain | ✓ | The blockchain stacks-node binds to on the backend for proof-of-transfer. Only value supported: `bitcoin` | -| mode | ✓ | The profile or test phase of which to run stacks-node. Valid values are [ `mocknet`, `testnet`, `xenon`, `mainnet` ] | -| peer_host | | FQDN of the host running the backend Bitcoin blockchain | -| rpc_port | | RPC port of `peer_host` | -| peer_port | | P2P port of `peer_host` | - -#### Mining - -| Name | Required | Description | -| -------------------------- | -------- | -------------------------------------------------------------------------------------------------- | -| burn_fee_cap | ✓ | Maximum amount (in sats) of "burn commitment" to broadcast for the next block's leader election | -| satoshis_per_byte | ✓ | [Amount (in sats) per byte](https://bitcoinfees.net/) - Used to calculate the transaction fees | -| commit_anchor_block_within | | Sets the time period (in milliseconds) for commitments. Only used when `mode` is set to `mocknet`. | - -### ustx_balance - -- `mocknet`/`testnet` only - -This section contains configuration options allocating microSTX per address in the genesis block - -This section can repeat multiple times, but each section can only define a single address. - -:::info -This section is only required for the `testnet` and `mocknet` networks. - -However, if this section is added, **all** fields are required -::: - -| Name | Required | Description | -| ------- | -------- | --------------------------------------------------------------------- | -| address | ✓ | Address which maintains a microSTX balance | -| amount | ✓ | The balance of microSTX given to the address at the start of the node | - -## Example Mainnet Follower Configuration - -```toml -[node] -working_dir = "/stacks-blockchain" -rpc_bind = "0.0.0.0:20443" -p2p_bind = "0.0.0.0:20444" -bootstrap_node = "02da7a464ac770ae8337a343670778b93410f2f3fef6bea98dd1c3e9224459d36b@seed-0.mainnet.stacks.co:20444,02afeae522aab5f8c99a00ddf75fbcb4a641e052dd48836408d9cf437344b63516@seed-1.mainnet.stacks.co:20444,03652212ea76be0ed4cd83a25c06e57819993029a7b9999f7d63c36340b34a4e62@seed-2.mainnet.stacks.co:20444" - -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "localhost" -username = "user" -password = "pass" -rpc_port = 8332 -peer_port = 8333 - -[[events_observer]] -endpoint = "localhost:3700" -retry_count = 255 -events_keys = ["*"] -``` - - diff --git a/docs/nodes-and-miners/verify-miner.md b/docs/nodes-and-miners/verify-miner.md deleted file mode 100644 index 18e8dd3a48..0000000000 --- a/docs/nodes-and-miners/verify-miner.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Verify Miner -description: Verify node is operating as miner -sidebar_position: 7 ---- - -You can verify that your node is operating as a miner by checking its log output to verify that it was able to find its Bitcoin UTXOs: - -```bash -$ head -n 1000 /path/to/your/node/logs | grep -i utxo -INFO [1630127492.031042] [testnet/stacks-node/src/run_loop/neon.rs:146] [main] Miner node: checking UTXOs at address: -INFO [1630127492.062652] [testnet/stacks-node/src/run_loop/neon.rs:164] [main] UTXOs found - will run as a Miner node -``` diff --git a/docs/references/_category_.json b/docs/references/_category_.json deleted file mode 100644 index 0bb2c6de80..0000000000 --- a/docs/references/_category_.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "label": "References", - "position": 9, - "link": { - "type": "generated-index", - "description": "Stacks references." - } - } - \ No newline at end of file diff --git a/docs/services-using-stacks/_category_.json b/docs/services-using-stacks/_category_.json deleted file mode 100644 index 72c0987c1f..0000000000 --- a/docs/services-using-stacks/_category_.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "label": "Services using Stacks", - "position": 8, - "link": { - "type": "generated-index", - "description": "An 'always incomplete' list of services that use Stacks." - } -} - \ No newline at end of file diff --git a/docs/services-using-stacks/defi.md b/docs/services-using-stacks/defi.md deleted file mode 100644 index a90aad85fa..0000000000 --- a/docs/services-using-stacks/defi.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: DeFi -description: De-Fi sites on Stacks -sidebar_position: 2 ---- - -They are multiple De-Fi sites that operate on the Stacks blockchain. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Alex - -[Alex](https://app.alexlab.co) -![](/img/sh_alex.png) - -## Arkadiko - -[Arkadiko](https://arkadiko.finance/) -![](/img/sh_arkadiko.png) - -## Catamaran Swaps - -[Catamaran Swaps](https://www.catamaranswaps.org/) allows trustless exchange of digital assets. - -![](/img/sh_catamaran.png) - -## Lnswap - -[LNSWAP](https://www.lnswap.org). Non-custodial crypto currency exchange - -![](/img/sh_lnswap.png) - -## Neoswap - -[Neoswap](https://neoswap.party) - -![](/img/sh_neoswap.png) - -## Stackswap - -[Stackswap](https://app.stackswap.org/v2) - -![](/img/sh_stackswap.png) diff --git a/docs/services-using-stacks/more.md b/docs/services-using-stacks/more.md deleted file mode 100644 index 1e14b9a5a5..0000000000 --- a/docs/services-using-stacks/more.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: More -description: More services built on Stacks. -sidebar_position: 5 ---- - -List of sites on alphabetical order added by the community. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Citycoins - -[Citycoins](https://citycoins.co) - -![](/img/sh_citycoins.png) - -## Sigle - -[Sigle](https://www.sigle.io/) is a decentralized and open source web 3 writing platform. - -![](/img/sh_sigle.png) diff --git a/docs/services-using-stacks/nft.md b/docs/services-using-stacks/nft.md deleted file mode 100644 index d582604854..0000000000 --- a/docs/services-using-stacks/nft.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: NFTs -description: NFTs on Stacks -sidebar_position: 3 ---- - -List of sites that operate NFTS on Stacks on alphabetical order. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -### [Byzantion](https://byzantion.xyz/) - -![website-screenshot](/img/sh_nft_byzantion.png) - -### [Gamma](https://gamma.io/) - -![website-screenshot](/img/sh_nft_gamma.png) - -### [Megapont](https://www.megapont.com/) - -![website-screenshot](/img/sh_nft_megapont.png) - -### [Satoshibles](https://satoshibles.com/) - -![website-screenshot](/img/sh_nft_satoshibles.png) - -### [StacksArt](https://www.stacksart.com/) - -![website-screenshot](/img/sh_nft_stacksart.png) - -### [StacksBridge](https://stacksbridge.com/) - -![website-screenshot](/img/sh_nft_stacksbridge.png) - -### [Superfandom](https://superfandom.io/) - -![website-screenshot](/img/sh_superfandom.png) diff --git a/docs/services-using-stacks/stacks-info-sites.md b/docs/services-using-stacks/stacks-info-sites.md deleted file mode 100644 index 54f6823e33..0000000000 --- a/docs/services-using-stacks/stacks-info-sites.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Stacks info sites -description: Status and stats of the Stacks network. -sidebar_position: 1 ---- - -A list of sites on alphabetical order that display status and stats of the Stacks network. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -### [Haystack](https://haystack.tools/mempool) - -![website-screenshot](/img/sh_haystacks.png) - -### [Stacksdata](https://stacksdata.info/) - -![website-screenshot](/img/sh_stacksdata.png) - -### [Stacksonchain](https://stacksonchain.com) - -![website-screenshot](/img/sh_stacksonchain.png) - -### [Status Hiro](https://status.hiro.so/) - -![website-screenshot](/img/sh_statushiro.png) - -### [Stxstats](https://www.stxstats.co/) - -![website-screenshot](/img/sh_stxstats.png) - -### [Novum Insights](https://stacks.novuminsights.com/health) - -![website-screenshot](/img/sh_novuminsights.png) - -### [Onstacks](https://app.onstacks.com/) - -![website-screenshot](/img/sh_onstacks.png) diff --git a/docs/services-using-stacks/wallets.md b/docs/services-using-stacks/wallets.md deleted file mode 100644 index 80142a29d1..0000000000 --- a/docs/services-using-stacks/wallets.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Wallets -description: Wallets for Stacks -sidebar_position: 4 ---- - -A list of hardware and software wallets for Stacks - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Blockchain.com - -[Blockchain.com](https://www.blockchain.com/wallet) - -![](/img/sh_blockchain.png) - -## Boom - -[Boom](https://boom.money) - -![](/img/sh_boom.png) - -## Dcent wallet - -[D'CENT](https://dcentwallet.com) - -![](/img/sh_dcent.png) - -## Hiro Wallet - -[Hiro Wallet](https://www.hiro.so/wallet) - -![](/img/sh_hirowallet.png) - -## Xverse - -[Xverse](https://www.xverse.app/) - -![](/img/sh_xverse.png) - -## Wise - -[Wise](https://wiseapp.id) - -![](/img/sh_wiseapp.png) diff --git a/docs/stacks-academy/accounts.md b/docs/stacks-academy/accounts.md deleted file mode 100644 index f5b6ec1a26..0000000000 --- a/docs/stacks-academy/accounts.md +++ /dev/null @@ -1,225 +0,0 @@ ---- -title: Accounts -description: Guide to Stacks 2.0 accounts -sidebar_position: 7 ---- - -## Introduction - -Stacks 2.0 accounts are entities that own assets, like Stacks (STX) tokens. An account has an address, private key, nonce, and one or more asset balances. - -:::tip -The encryption algorithm used in Stacks 2.0 is **[secp256k1](https://en.bitcoinwiki.org/wiki/Secp256k1)**. - -Additionally, [Ed25519](https://ed25519.cr.yp.to/) is also used just for the VRF (Verifiable Random Function). -::: - -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. - -:::tip -The transaction type doesn't need to be a token transfer - contract deploy and contract call transactions can change the balances of an account -::: - -## Creation - -An account is generated from a 24-word mnemonic phrase. This is often referred to as the **seed phrase**. The seed phrase provides access to Stacks 2.0 accounts. - -:::danger -If the seed phrase is lost, access to the associated account cannot be restored. No person or organization can recover a lost seed phrase. -::: - -The easiest way to generate a new Stacks 2.0 account is to use the [Stacks CLI](https://github.com/hirosystems/stacks.js/tree/master/packages/cli): - -```bash -# install CLI globally -npm install --global @stacks/cli - -# generate a new account and store details in a new file -# '-t' option makes this a testnet account -stx make_keychain -t > cli_keychain.json -``` - -`make_keychain` creates the following file: - -```js -{ - "mnemonic": "aaa bbb ccc ddd ...", - "keyInfo": { - "privateKey": "5a3f1f15245bb3fb...", - "address": "STJRM2AMVF90ER6G3RW1QTF85E3HZH37006D5ER1", - "btcAddress": "biwSd6KTEvJcyX2R8oyfgj5REuLzczMYC1", - "wif": "L4HXn7PLmzoNW...", - "index": 0 - } -} -``` - -:::tip -Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details -::: - -| Field | Description | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `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.privateKey` | Private key for the account. Required for token transfers and often referred to as `senderKey` | -| `keyInfo.address` | Stacks address for the account | -| `keyInfo.btcAddress` | Corresponding BTC address for the account. | -| `keyInfo.wif` | Private key of the btcAddress in compressed format. | -| `keyInfo.index` | Nonce for the account, starting at 0 | - -Note that a new account automatically exists for each new private key. There is no need to manually instantiate an account on the Stacks 2.0 blockchain. - -:::tip -Addresses are created by generating the [RIPEMD-160 hash](https://en.wikipedia.org/wiki/RIPEMD#RIPEMD-160_hashes) of the [SHA256](https://en.bitcoinwiki.org/wiki/SHA-256) of the public key. BTC addresses are encoded with [Base58Check](https://en.bitcoin.it/wiki/Base58Check_encoding). For Stacks addresses, [c32check](https://github.com/stacks-network/c32check) is used. Deriving an address from a public key can be done without internet access, for instance using the c32check `c32addressDecode` method. -::: - -Alternatively to the CLI creation, the [Stacks Transactions JS](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library can be used: - -```js -import { - makeRandomPrivKey, - privateKeyToString, - getAddressFromPrivateKey, - TransactionVersion, - getPublicKey, -} from "@stacks/transactions"; - -const privateKey = makeRandomPrivKey(); - -// Get public key from private -const publicKey = getPublicKey(privateKey); - -const stacksAddress = getAddressFromPrivateKey( - privateKeyToString(privateKey), - TransactionVersion.Testnet // remove for Mainnet addresses -); -``` - -A second alternative would be to use [stacks-gen](https://github.com/psq/stacks-gen). This tool will generate all the keys you need in one place, including the values needed for calling the stacking contract, and also a WIF key for use with `bitcoind`. - -#### stacks-gen prerequisite - -Install [npx](https://github.com/npm/npx) if not already installed. (npx will check whether `` exists in \$PATH, or in the local project binaries, and execute that. If `` is not found, it will be installed prior to execution). - -``` -npm install -g npx -``` - -#### stacks-gen usage - -``` -npx -q stacks-gen sk --testnet - -{ - "phrase": "guide air pet hat friend anchor harvest dog depart matter deny awkward sign almost speak short dragon rare private fame depart elevator snake chef", - "private": "0351764dc07ee1ad038ff49c0e020799f0a350dd0769017ea09460e150a6401901", - "public": "022d82baea2d041ac281bebafab11571f45db4f163a9e3f8640b1c804a4ac6f662", - "stacks": "ST16JQQNQXVNGR8RZ1D52TMH5MFHTXVPHRV6YE19C", - "stacking": "{ hashbytes: 0x4d2bdeb7eeeb0c231f0b4a2d5225a3e3aeeed1c6, version: 0x00 }", - "btc": "mnYzsxxW271GkmyMnRfiopEkaEpeqLtDy8", - "wif": "cMh9kwaCEttgTQYkyMUYQVbdm5ZarZdBHErcq7mXUChXXCo7CFEh" -} -``` - -:::tip -The stacking object with hashbytes and a version represents the bitcoin address derived from the Stacks address. Read more about the [bitcoin address format](stacking#bitcoin-address). -::: - -Full documentation available at [stacks-gen](https://github.com/psq/stacks-gen). - -## Querying - -### Get Stacks (STX) balance and nonce - -STX balance and nonce can be obtained through the [`GET /v2/accounts/`](https://docs.hiro.so/api#operation/get_account_info) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/accounts/' -``` - -Sample response: - -```js -{ - "balance": "0x0000000000000000002386f26f3f40ec", - "nonce": 17 -} -``` - -:::tip -The balance string represents an unsigned 128-bit integer (big-endian) in hex encoding -::: - -### Get all token balances - -All token balances can be obtained through the [`GET /extended/v1/address//balances`](https://docs.hiro.so/api#operation/get_account_balance) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/address//balances' -``` - -Sample response: - -```js -{ - "stx": { - "balance": "0", - "total_sent": "0", - "total_received": "0" - }, - "fungible_tokens": {}, - "non_fungible_tokens": {} -} -``` - -:::tip -Stacks accounts cannot hold bitcoins. The best way to obtain corresponding BTC balances is to derive the BTC address from the Stacks address (using [`c32check`](https://github.com/stacks-network/c32check#c32tob58-b58toc32)) and query the Bitcoin network. -::: - -### Get all asset events - -All asset events associated with the account can be obtained through the [`GET /extended/v1/address//assets`](https://docs.hiro.so/api#operation/get_account_balance) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/address//assets' -``` - -Sample response: - -```js -{ - "limit": 20, - "offset": 0, - "total": 0, - "results": [ - { - "event_index": 5, - "event_type": "non_fungible_token_asset", - "asset": { - "asset_event_type": "transfer", - "asset_id": "ST2W14YX9SFVDB1ZGHSH40CX1YQAP9XKRAYSSVYAG.hello_world::hello-nft", - "sender": "SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR", - "recipient": "SM2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQVX8X0G", - "value": { - "hex": "0x0100000000000000000000000000000001", - "repr": "u1" - } - } - }, - { - "event_index": 3, - "event_type": "fungible_token_asset", - "asset": { - "asset_event_type": "mint", - "asset_id": "ST2W14YX9SFVDB1ZGHSH40CX1YQAP9XKRAYSSVYAG.hello_world::novel-token-19", - "sender": "", - "recipient": "SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR", - "amount": "12" - } - } - ] -} -``` diff --git a/docs/stacks-academy/authentication.md b/docs/stacks-academy/authentication.md deleted file mode 100644 index 55b89ee93b..0000000000 --- a/docs/stacks-academy/authentication.md +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: Authentication -description: Register and sign in users with identities on the Stacks blockchain -sidebar_position: 8 ---- - -## Introduction - -This guide explains how authentication is performed on the Stacks blockchain. - -Authentication provides a way for users to identify themselves to an app while retaining complete control over their credentials and personal details. It can be integrated alone or used in conjunction with [transaction signing](https://docs.hiro.so/get-started/transactions#signature-and-verification) and [data storage](https://docs.stacks.co/gaia/overview), for which it is a prerequisite. - -Users who register for your app can subsequently authenticate to any other app with support for the [Blockchain Naming System](bns) and vice versa. - -## How it works - -The authentication flow with Stacks is similar to the typical client-server flow used by centralized sign in services (for example, OAuth). However, with Stacks the authentication flow happens entirely client-side. - -An app and authenticator, such as [the Stacks Wallet](https://www.hiro.so/wallet/install-web), communicate during the authentication flow by passing back and forth two tokens. The requesting app sends the authenticator an `authRequest` token. Once a user approves authentication, the authenticator responds to the app with an `authResponse` token. - -These tokens are based on [a JSON Web Token (JWT) standard](https://tools.ietf.org/html/rfc7519) with additional support for the `secp256k1` curve used by Bitcoin and many other cryptocurrencies. They are passed via URL query strings. - -When a user chooses to authenticate an app, it sends the `authRequest` token to the authenticator via a URL query string with an equally named parameter: - -`https://wallet.hiro.so/...?authRequest=j902120cn829n1jnvoa...` - -When the authenticator receives the request, it generates an `authResponse` token for the app using an _ephemeral transit key_ . The ephemeral transit key is just used for the particular instance of the app, in this case, to sign the `authRequest`. - -The app stores the ephemeral transit key during request generation. The public portion of the transit key is passed in the `authRequest` token. The authenticator uses the public portion of the key to encrypt an _app private key_ which is returned via the `authResponse`. - -The authenticator generates the app private key from the user's _identity address private key_ and the app's domain. The app private key serves three functions: - -1. It is used to create credentials that give the app access to a storage bucket in the user's Gaia hub -2. It is used in the end-to-end encryption of files stored for the app in the user's Gaia storage. -3. It serves as a cryptographic secret that apps can use to perform other cryptographic functions. - -Finally, the app private key is deterministic, meaning that the same private key will always be generated for a given Stacks address and domain. - -The first two of these functions are particularly relevant to [data storage with Stacks.js](https://docs.stacks.co/docs/gaia). - -## Key pairs - -Authentication with Stacks makes extensive use of public key cryptography generally and ECDSA with the `secp256k1` curve in particular. - -The following sections describe the three public-private key pairs used, including how they're generated, where they're used and to whom private keys are disclosed. - -### Transit private key - -The transit private is an ephemeral key that is used to encrypt secrets that -need to be passed from the authenticator to the app during the -authentication process. It is randomly generated by the app at the beginning of -the authentication response. - -The public key that corresponds to the transit private key is stored in a single -element array in the `public_keys` key of the authentication request token. The -authenticator encrypts secret data such as the app private key using this -public key and sends it back to the app when the user signs in to the app. The -transit private key signs the app authentication request. - -### Identity address private key - -The identity address private key is derived from the user's keychain phrase and -is the private key of the Stacks username that the user chooses to use to sign in -to the app. It is a secret owned by the user and never leaves the user's -instance of the authenticator. - -This private key signs the authentication response token for an app to indicate that the user approves sign in to that app. - -### App private key - -The app private key is an app-specific private key that is generated from the -user's identity address private key using the `domain_name` as input. - -The app private key is securely shared with the app on each authentication, encrypted by the authenticator with the transit public key. Because the transit key is only stored on the client side, this prevents a man-in-the-middle attack where a server or internet provider could potentially snoop on the app private key. diff --git a/docs/stacks-academy/bns.md b/docs/stacks-academy/bns.md deleted file mode 100644 index 66b21d2640..0000000000 --- a/docs/stacks-academy/bns.md +++ /dev/null @@ -1,404 +0,0 @@ ---- -title: Bitcoin Name System -description: Binds Stacks usernames to off-chain state -sidebar_position: 8 ---- - -Bitcoin Name System (BNS) is a network system that binds Stacks usernames -to off-chain state without relying on any central points of control. - -The Stacks V1 blockchain implemented BNS through first-order name operations. -In Stacks V2, BNS is instead implemented through a smart-contract loaded -during the genesis block. - -Names in BNS have three properties: - -- **Names are globally unique.** The protocol does not allow name collisions, and all - well-behaved nodes resolve a given name to the same state. -- **Names are human-meaningful.** Each name is chosen by its creator. -- **Names are strongly owned.** Only the name's owner can change the state it - resolves to. Specifically, a name is owned by one or more ECDSA private keys. - -The Stacks blockchain insures that each node's BNS view is -synchronized to all of the other nodes in the world, so queries on one -node will be the same on other nodes. Stacks blockchain nodes allow a -name's owner to bind up to 40Kb of off-chain state to their name, -which will be replicated to all other Stacks blockchain nodes via a P2P network. - -The biggest consequence for developers is that in BNS, reading name state is -fast and cheap but writing name state is slow and expensive. This is because -registering and modifying names requires one or more transactions to be sent to -the underlying blockchain, and BNS nodes will not process them until they are -sufficiently confirmed. Users and developers need to acquire and spend -the requisite cryptocurrency (STX) to send BNS transactions. - -## Motivation behind name systems - -We rely on name systems in everyday life, and they play a critical -role in many different applications. For example, when you look up a -friend on social media, you are using the platform's name system to resolve -their name to their profile. When you look up a website, you are using the -Domain Name Service to -resolve the hostname to its host's IP address. When you check out a Git branch, you -are using your Git client to resolve the branch name to a commit hash. -When you look up someone's PGP key on a keyserver, you are resolving -their key ID to their public key. - -What kinds of things do we want to be true about names? In BNS, names are -globally unique, names are human-meaningful, and names are strongly owned. -However, if you look at these examples, you'll see that each of them only -guarantees _two_ of these properties. This limits how useful they can be. - -- In DNS and social media, names are globally unique and human-readable, but not - strongly owned. The system operator has the - final say as to what each names resolves to. - - - **Problem**: Clients must trust the system to make the right - choice in what a given name resolves to. This includes trusting that - no one but the system administrators can make these changes. - -- In Git, branch names are human-meaningful - and strongly owned, but not globally unique. Two different Git nodes may resolve the same - branch name to different unrelated repository states. - - - **Problem**: Since names can refer to conflicting state, developers - have to figure out some other mechanism to resolve ambiguities. In Git's - case, the user has to manually intervene. - -- In PGP, names are key IDs. They are globally unique and cryptographically owned, but not human-readable. PGP - key IDs are derived from the keys they reference. - - **Problem**: These names are difficult for most users to - remember since they do not carry semantic information relating to their use in the system. - -BNS names have all three properties, and none of these problems. This makes it a -powerful tool for building all kinds of network applications. With BNS, we -can do the following and more: - -- Build domain name services where hostnames can't be hijacked. -- Build social media platforms where user names can't be stolen by phishers. -- Build version control systems where repository branches do not conflict. -- Build public-key infrastructure where it's easy for users to discover and - remember each other's keys. - -## Organization of BNS - -BNS names are organized into a global name hierarchy. There are three different -layers in this hierarchy related to naming: - -- **Namespaces**. These are the top-level names in the hierarchy. An analogy - to BNS namespaces are DNS top-level domains. Existing BNS namespaces include - `.id`, `.podcast`, and `.helloworld`. All other names belong to exactly one - namespace. Anyone can create a namespace, but in order for the namespace - to be persisted, it must be _launched_ so that anyone can register names in it. - Namespaces are not owned by their creators. - -- **BNS names**. These are names whose records are stored directly on the - blockchain. The ownership and state of these names are controlled by sending - blockchain transactions. Example names include `verified.podcast` and - `muneeb.id`. Anyone can create a BNS name, as long as the namespace that - contains it exists already. - -- **BNS subdomains**. These are names whose records are stored off-chain, - but are collectively anchored to the blockchain. The ownership and state for - these names lives within the P2P network data. While BNS - subdomains are owned by separate private keys, a BNS name owner must - broadcast their subdomain state. Example subdomains include `jude.personal.id` - and `podsaveamerica.verified.podcast`. Unlike BNS namespaces and names, the - state of BNS subdomains is _not_ part of the blockchain consensus rules. - -A feature comparison matrix summarizing the similarities and differences -between these name objects is presented below: - -| Feature | **Namespaces** | **BNS names** | **BNS Subdomains** | -| -------------------------------------- | -------------- | ------------- | ------------------ | -| Globally unique | X | X | X | -| Human-meaningful | X | X | X | -| Owned by a private key | | X | X | -| Anyone can create | X | X | [1] | -| Owner can update | | X | [1] | -| State hosted on-chain | X | X | | -| State hosted off-chain | | X | X | -| Behavior controlled by consensus rules | X | X | | -| May have an expiration date | | X | | - -[1] Requires the cooperation of a BNS name owner to broadcast its transactions - -## Namespaces - -Namespaces are the top-level name objects in BNS. - -They control a few properties about the names within them: - -- How expensive they are to register -- How long they last before they have to be renewed -- Who (if anyone) receives the name registration fees -- Who is allowed to seed the namespace with its initial names. - -At the time of this writing, by far the largest BNS namespace is the `.id` -namespace. Names in the `.id` namespace are meant for resolving user -identities. Short names in `.id` are more expensive than long names, and have -to be renewed by their owners every two years. Name registration fees are not -paid to anyone in particular---they are instead sent to a "black hole" where -they are rendered non-spendable (the intention is to discourage ID squatters). - -Unlike DNS, _anyone_ can create a namespace and set its properties. Namespaces -are created on a first-come first-serve basis, and once created, they last -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 (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`). - -Namespaces can be between 1 and 19 characters long, and are composed of the -characters `a-z`, `0-9`, `-`, and `_`. - -## Subdomains - -BNS names are strongly owned because the owner of its private key can generate -valid transactions that update its zone file hash and owner. However, this comes at the -cost of requiring a name owner to pay for the underlying transaction in the -blockchain. Moreover, this approach limits the rate of BNS name registrations -and operations to the underlying blockchain's transaction bandwidth. - -BNS overcomes this with subdomains. A **BNS subdomain** is a type of -BNS name whose state and owner are stored outside of the blockchain, -but whose existence and operation history are anchored to the -blockchain. Like their on-chain counterparts, subdomains are globally -unique, strongly owned, and human-readable. BNS gives them their own -name state and public keys. Unlike on-chain names, subdomains can be -created and managed cheaply, because they are broadcast to the BNS -network in batches. A single blockchain transaction can send up to 120 -subdomain operations. - -This is achieved by storing subdomain records in the BNS name zone files. -An on-chain name owner broadcasts subdomain operations by encoding them as -`TXT` records within a DNS zone file. To broadcast the zone file, -the name owner sets the new zone file hash with a `NAME_UPDATE` transaction and -replicates the zone file. This, in turn, replicates all subdomain -operations it contains, and anchors the set of subdomain operations to -an on-chain transaction. The BNS node's consensus rules ensure that only -valid subdomain operations from _valid_ `NAME_UPDATE` transactions will ever be -stored. - -For example, the name `verified.podcast` once wrote the zone file hash `247121450ca0e9af45e85a82e61cd525cd7ba023`, -which is the hash of the following zone file: - -```bash -$TTL 3600 -1yeardaily TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxeWVhcmRhaWx5CiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMXllYXJkYWlseS9oZWFkLmpzb24iCg==" -2dopequeens TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAyZG9wZXF1ZWVucwokVFRMIDM2MDAKX2h0dHAuX3RjcCBVUkkgMTAgMSAiaHR0cHM6Ly9waC5kb3Rwb2RjYXN0LmNvLzJkb3BlcXVlZW5zL2hlYWQuanNvbiIK" -10happier TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxMGhhcHBpZXIKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8xMGhhcHBpZXIvaGVhZC5qc29uIgo=" -31thoughts TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzMXRob3VnaHRzCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzF0aG91Z2h0cy9oZWFkLmpzb24iCg==" -359 TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzNTkKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8zNTkvaGVhZC5qc29uIgo=" -30for30 TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzMGZvcjMwCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzBmb3IzMC9oZWFkLmpzb24iCg==" -onea TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiBvbmVhCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vb25lYS9oZWFkLmpzb24iCg==" -10minuteteacher TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxMG1pbnV0ZXRlYWNoZXIKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8xMG1pbnV0ZXRlYWNoZXIvaGVhZC5qc29uIgo=" -36questionsthepodcastmusical TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzNnF1ZXN0aW9uc3RoZXBvZGNhc3RtdXNpY2FsCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzZxdWVzdGlvbnN0aGVwb2RjYXN0bXVzaWNhbC9oZWFkLmpzb24iCg==" -_http._tcp URI 10 1 "https://dotpodcast.co/" -``` - -Each `TXT` record in this zone file encodes a subdomain-creation. -For example, `1yeardaily.verified.podcast` resolves to: - -```json -{ - "address": "1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH", - "blockchain": "bitcoin", - "last_txid": "d87a22ebab3455b7399bfef8a41791935f94bc97aee55967edd5a87f22cce339", - "status": "registered_subdomain", - "zonefile_hash": "e7acc97fd42c48ed94fd4d41f674eddbee5557e3", - "zonefile_txt": "$ORIGIN 1yeardaily\n$TTL 3600\n_http._tcp URI 10 1 \"https://ph.dotpodcast.co/1yeardaily/head.json\"\n" -} -``` - -This information was extracted from the `1yeardaily` `TXT` resource record in the zone -file for `verified.podcast`. - -### Subdomain Lifecycle - -Note that `1yeardaily.verified.podcast` has a different public key -hash (address) than `verified.podcast`. A BNS node will only process a -subsequent subdomain operation on `1yeardaily.verified.podcast` if it includes a -signature from this address's private key. `verified.podcast` cannot generate -updates; only the owner of `1yeardaily.verified.podcast can do so`. - -The lifecycle of a subdomain and its operations is shown in Figure 2. - -``` - subdomain subdomain subdomain - creation update transfer -+----------------+ +----------------+ +----------------+ -| cicero | | cicero | | cicero | -| owner="1Et..." | signed | owner="1Et..." | signed | owner="1cJ..." | -| zf0="7e4..." |<--------| zf0="111..." |<--------| zf0="111..." |<---- ... -| seqn=0 | | seqn=1 | | seqn=2 | -| | | sig="xxxx" | | sig="xxxx" | -+----------------+ +----------------+ +----------------+ - | | | - | off-chain | | -~ ~ ~ ~ | ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~|~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ | ~ ~ ~ ~ ~ ~ ~ ... - | on-chain | | - V V (zone file hash ) V -+----------------+ +----------------+ +----------------+ -| res_publica.id | | jude.id | | res_publica.id | -| NAME_UPDATE |<--------| NAME_UPDATE |<--------| NAME_UPDATE |<---- ... -+----------------+ +----------------+ +----------------+ - blockchain blockchain blockchain - block block block - - -Figure 2: Subdomain lifetime with respect to on-chain name operations .A new -subdomain operation will only be accepted if it has a later "sequence=" number, -and a valid signature in "sig=" over the transaction body .The "sig=" field -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." -However, any on-chain name ("jude.id" in this case) can broadcast a subdomain -update for "cicero.res_publica.id." -``` - -Subdomain operations are ordered by sequence number, starting at 0. Each new -subdomain operation must include: - -- The next sequence number -- The public key that hashes to the previous subdomain transaction's address -- A signature from the corresponding private key over the entire subdomain - operation. - -If two correctly signed but conflicting subdomain operations are discovered -(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 -subdomain's operations will be able to determine the valid sequence of -state-transitions it has undergone, and determine the current zone file and public -key hash for the subdomain. - -### Subdomain Creation and Management - -Unlike an on-chain name, a subdomain owner needs an on-chain name owner's help -to broadcast their subdomain operations. In particular: - -- A subdomain-creation transaction can only be processed by the owner of the on-chain - name that shares its suffix. For example, only the owner of `res_publica.id` - can broadcast subdomain-creation transactions for subdomain names ending in - `.res_publica.id`. -- A subdomain-transfer transaction can only be broadcast by the owner of the - on-chain name that created it. For example, the owner of - `cicero.res_publica.id` needs the owner of `res_publica.id` to broadcast a - subdomain-transfer transaction to change `cicero.res_publica.id`'s public key. -- In order to send a subdomain-creation or subdomain-transfer, all - of an on-chain name owner's zone files must be present in the Atlas network. - This lets the BNS node prove the _absence_ of any conflicting subdomain-creation and - subdomain-transfer operations when processing new zone files. -- A subdomain update transaction can be broadcast by _any_ on-chain name owner, - but the subdomain owner needs to find one who will cooperate. For example, - the owner of `verified.podcast` can broadcast a subdomain-update transaction - created by the owner of `cicero.res_publica.id`. - -That said, to create a subdomain, the subdomain owner generates a -subdomain-creation operation for their desired name -and gives it to the on-chain name owner. - -Once created, a subdomain owner can use any on-chain name owner to broadcast a -subdomain-update operation. To do so, they generate and sign the requisite -subdomain operation and give it to an on-chain name owner, who then packages it -with other subdomain operations into a DNS zone file and broadcasts it to the network. - -If the subdomain owner wants to change the address of their subdomain, they need -to sign a subdomain-transfer operation and give it to the on-chain name owner -who created the subdomain. They then package it into a zone file and broadcast -it. - -### Subdomain Registrars - -Because subdomain names are cheap, developers may be inclined to run -subdomain registrars on behalf of their applications. For example, -the name `personal.id` is used to register usernames without -requiring them to spend any Bitcoin. - -We supply a reference implementation of a [BNS Subdomain -Registrar](https://github.com/stacks-network/subdomain-registrar) to help -developers broadcast subdomain operations. Users would still own their -subdomain names; the registrar simply gives developers a convenient -way for them to register and manage them in the context of a -particular application. - -## BNS and DID Standards - -BNS names are compliant with the emerging -[Decentralized Identity Foundation](http://identity.foundation) protocol -specification for decentralized identifiers (DIDs). - -Each name in BNS has an associated DID. The DID format for BNS is: - -```bash - did:stack:v0:{address}-{index} -``` - -Where: - -- `{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 -`did:stack:v0:1dARRtzHPAFRNE7Yup2Md9w18XEQAtLiV-0`, because the name -`personal.id` was the first-ever name created by -`1dARRtzHPAFRNE7Yup2Md9w18XEQAtLiV`. - -As another example, the DID for `jude.id` is `did:stack:v0:16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg-1`. -Here, the address `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` had created one earlier -name in history prior to this one (which happens to be `abcdefgh123456.id`). - -The purpose of a DID is to provide an eternal identifier for a public key. -The public key may change, but the DID will not. - -Stacks Blockchain implements a DID method of its own -in order to be compatible with other systems that use DIDs for public key resolution. -In order for a DID to be resolvable, all of the following must be true for a -name: - -- The name must exist -- The name's zone file hash must be the hash of a well-formed DNS zone file -- The DNS zone file must be present in the Stacks node's data. -- The DNS zone file must contain a `URI` resource record that points to a signed - JSON Web Token -- The public key that signed the JSON Web Token (and is included with it) must - hash to the address that owns the name - -Not all names will have DIDs that resolve to public keys. However, names created by standard tooling -will have DIDs that do. - -A RESTful API is under development. - -## DID Encoding for Subdomains - -Every name and subdomain in BNS has a DID. The encoding is slightly different -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 (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 - subdomains owned by a single private key, and version byte 50 for subdomains - owned by a m-of-n set of private keys. That is, subdomain DID addresses start - with `S` or `M`, respectively. - -The `{index}` field for a subdomain's DID is distinct from the `{index}` field -for a BNS name's DID, even if the same created both names and subdomains. -For example, the name `abcdefgh123456.id` has the DID `did:stack:v0:16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg-0`, -because it was the first name created by `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg`. -However, `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` _also_ created `jude.statism.id` -as its first subdomain name. The DID for `jude.statism.id` is -`did:stack:v0:SSXMcDiCZ7yFSQSUj7mWzmDcdwYhq97p2i-0`. Note that the address -`SSXMcDiCZ7yFSQSUj7mWzmDcdwYhq97p2i` encodes the same public key hash as the address -`16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` (the only difference between these two -strings is that the first is base58check-encoded with version byte 0, and the -second is encoded with version byte 63). diff --git a/docs/stacks-academy/btc-connection.md b/docs/stacks-academy/btc-connection.md deleted file mode 100644 index 1fd8b988c3..0000000000 --- a/docs/stacks-academy/btc-connection.md +++ /dev/null @@ -1,236 +0,0 @@ ---- -title: Bitcoin Connection -description: How Stacks is connected to Bitcoin -sidebar_position: 3 ---- - -At the very beginning of these docs, we described Stacks as bringing smart contract functionality to Bitcoin, without modifying Bitcoin itself. - -That's a big promise, but how does Stacks actually deliver on it? And what makes Stacks unique among other Bitcoin layers and other blockchains like Ethereum? - -Before we get into the technical details of how Stacks works, it's important to get a high-level overview of the problem its solving and how it actually does that. We'll dive deeper into some of these topics as we go through Stacks Academy, but it's good to get a high-level picture to bring everything together. - -This topic is a bit of a rabbit hole, and this section of Stacks Academy is pretty long, but it will give you an in-depth understanding of exactly the problem Stacks is looking to solve, and how it solves it. - -Let's get into it. - -## Is Stacks a Bitcoin L2? - -Stacks is a Bitcoin layer for smart contracts. The classification as a layer-1 (L1) or layer-2 (L2) or sidechain really depends on the definition used. With that said, generally speaking L1 chains are sovereign meaning that (a) they have their own security budget, and (b) they can survive without the need for any other L1 chain. L2 chains typically do not have their own security budget and share the security of the underlying L1 chain, and they cannot live without the underlying L1 chain. - -The initial release of Stacks in early 2021 had a separate security budget from Bitcoin L1. Even though the Stacks layer could not function without Bitcoin L1, the developers working on the project described it as a different system that does not fit neatly into existing classifications, sometimes using the term layer 1.5 (see [this Decrypt article](https://decrypt.co/82019/bitcoin-defi-thing-says-stacks-founder-muneeb-ali) for example). - -The upcoming planned release of Stacks, called the Nakamoto release (convention to use names of famous Computer Scientists for major releases), will no longer have a separate security budget from Bitcoin. Instead, a 100% of Bitcoin hashpower will determine finality on Stacks layer. After the next upgrade, to reorg Stacks blocks/transactions the attacker will need to reorg Bitcoin L1 itself (which is very hard to do and therefore a great security property for a Bitcoin layer to have). More details in the [Stacks paper](https://stacks.co/stacks.pdf). - -The definition of [L2 used in Ethereum](https://ethereum.org/en/layer-2/) and other newer ecosystems is different and focuses on the ability to withdraw assets using only L1 security and L1 miners. According to that definition Stacks layer is not a clear L2, given the set of peg-out signers determine if users can withdraw sBTC. Bitcoin cannot support such verification without changes to Bitcoin L1 (which may happen in the future). The Ethereum L2 definition also does not apply that cleanly to Bitcoin L2s, given new assets are issued on L2s when it comes to Bitcoin and not issued on L1 (only BTC is the L1 asset). Therefore, using the definition of security of withdrawing assets is not directly applicable given assets are defined and used on L2s and not withdrawn out to Bitcoin L1 anyway (with the exception of BTC itself). Rather, what becomes more important is "settlement on Bitcoin" i.e., is contract data and state secured by 100% of Bitcoin's hashpower or not. - -Users and developers organically call Stacks a Bitcoin L2, since it is a simpler concept to understand. There are certain properties of Stacks layer that also help the concept of Stacks as a Bitcoin L2: - -1. Bitcoin finality, as discussed above, where 100% of the Bitcoin hashpower decides block ordering and transaction finality. -2. Stacks consensus runs on Bitcoin L1, and Stacks L2 cannot operate or survive without Bitcoin L1. -3. With the upcoming decentralized Bitcoin peg, called sBTC (see [sBTC paper](https://stacks.co/sbtc.pdf)), most of economy on Stacks layer will likely use BTC as the unit of economy. It is expected that most users will simply use Bitcoin in wallets and apps and then peg out their BTC to Bitcoin L1. -4. All data and transactions on Stacks are automatically hashed and permanently stored on Bitcoin L1 on every Bitcoin block. Anyone can verify that some data on Stacks is valid by checking the corresponding hash on Bitcoin L1. This compact storage of hashes on L1 is somewhat similar to rollups (although there are other differences). -5. Contracts on Stacks layer can read Bitcoin L1 transactions and respond to them. Assets on Stacks layer can be moved simply through Bitcoin L1 transactions. - -Given all the details above, why would some people think that Stacks is not a Bitcoin L2? There are a couple of reasons why this question comes up often: - -1. The initial version of Stacks (released early 2021) had a separate security budget which changed to following 100% Bitcoin hashpower with the Nakamoto release. There is old material and blog posts floating around that still talk about the initial Stacks version. The old materials will likely get updated with time. -2. According to the Ethereum definition of L2s a user should be able to withdraw their base-layer assets purely by doing a L1 transaction and relying only on L1 security (this is true for Lightning for example). This definition does not apply cleanly to Bitcoin L2s because assets are not defined at Bitcoin L1 but are defined in L2s instead. The only asset where this matters is the pegged BTC asset from Bitcoin L1, given all other assets are native to L2s anyway. In the upcoming Stacks release, users can withdraw their BTC by sending just a Bitcoin L1 transaction but Bitcoin L1 cannot validate that complex transaction and a majority of peg-out signers will need to sign on the peg-out request. In an ideal world Bitcoin miners can validate such transactions but that would require a change to Bitcoin L1. Therefore, Stacks design optimizes for a method that is decentralized and can be deployed without any changes to Bitcoin L1. If in the future it is possible to make changes to Bitcoin L1 then Stacks layer security can benefit from that as well. -3. Bitcoin community members are generally skeptical of claims and on a look out for people making any false marketing claims. This is generally a healthy thing for the Bitcoin ecosystem and builds up the immune system. Some such community members might be skeptical about Stacks as a Bitcoin layer or L2 until they fully read the technical details and reasoning. There is a good [Twitter thread](https://twitter.com/lopp/status/1623756872976158722?s=20) about his topic as well. - -Why don't we use the term 'sidechain' for Stacks then? Sidechains in Bitcoin typically have a different security budget from Bitcoin L1, typically as a subset of Bitcoin miners who participate in the sidechain (they don't follow 100% Bitcoin finality), their consensus runs on the sidechain (vs running on Bitcoin L1), and they don't publish their data/hashes on Bitcoin L1. The Stacks layer does not fit that definition cleanly given the consensus runs on Bitcoin L1, it follows Bitcoin finality, and publishes data/hashes on L1. - -The TLDR is that it is better to refer to Stacks as a Bitcoin layer (the more generic term). However, the Bitcoin L2 term is more organic and simpler for users and we'll likely keep seeing the use of it. If the Bitcoin L2 term comes up then it's important to understand the technical differences and that unlike Ethereum L2s withdrawing BTC from Stacks requires signatures from peg-out signers. - -## Stacks Among Other Bitcoin Layers - -Let's take a look at how Stacks compares to some of the other Bitcoin layering solutions. This is a fresh and rapidly evolving ecosystem, so there are quite a few interesting approaches in the works. - -### Lightning - -Lightning is probably the most well-known Bitcoin layer, and is primarily designed to address scalability issues. Lightning functions as a separate P2P network from Bitcoin, allowing participants to conduct move their BTC from the main chain to Lightning, conduct multiple transactions on Lightning, and then send the final result to the BTC chain where it is finalized. - -This is actually a completely separate problem from what Stacks is trying to address. Where Lightning takes the existing functionality of Bitcoin and makes it much more scalable, Stacks is seeking to expand Bitcoin's functionality to do things you can't do now. - -Crucially, Lightning is ephemeral, meaning it has no state management. There is no continuous record of what has happened on the Lightning network, only current channels. Once users close their channel and their transactions are written back to the Bitcoin chain, they are gone. - -A key component of full-expressive smart contracts is that they maintain a permanent historical record of all transactions that have happened on the chain. - -Bitcoin does this now, but its scripting language is very limited. So where Lightning seeks to make existing Bitcoin functionality happen faster, Stacks seeks to add new functionality. - -### RSK - -Like Stacks, [RSK](https://www.rsk.co/) seeks to add additional functionality to Bitcoin, but it goes about that process differently than Stacks. - -RSK is a merge-mined chain, meaning that it is mined concurrently with Bitcoin. Stacks has its own miners and mining process, and its own economic value and security that is a function of that token value, more on this below. - -There are multiple perspectives to look at this from. Because RSK is merge-mined, Bitcoin miners are also the ones mining RSK blocks, and RSK does not have its own token. - -RSK can only exist with opt-in from Bitcoin miners and mining rewards are highly dependent on transaction volume. - -This also opens up a wider discussion on the costs and benefits of having a separate token, which we'll get into below. - -RSK is also EVM-compatible, where Stacks uses Clarity and the Clarity VM. - -### Liquid - -[Liquid](https://liquid.net/) is a federated network focused on unlocking more advanced financial capabilities with Bitcoin. Being federated, Liquid is not an open network, and thus not decentralized. - -The Liquid consensus mechanism is managed by 15 functionaries, who handle the transaction processing and validating. Liquid also does not support general-purpose applications, but is solely focused on financial applications. - -This was a brief overview of these other Bitcoin projects, for another perspective, Hiro wrote an [excellent post](https://www.hiro.so/blog/building-on-bitcoin-project-comparison) comparing Stacks with other Bitcoin projects. - -### Bitcoin Rollups - -Rollups are an exciting development for scaling decentralized applications. There are many different types of rollups; they're broadly divided into ZK rollups and Optimistic rollups, although other classifications are also there (see [this overview](https://era.zksync.io/docs/dev/fundamentals/rollups.html#what-are-rollups)). - -Rollups are generally considered layer-2 (L2) technology that runs on top of a layer-1 blockchain like Bitcoin or Ethereum. A critical aspect of rollups is the trustless nature where logic running on the L1 chain can determine whether something that happened on the rollup was valid. This is not true for all types of rollups, and there is some fuzziness around exact definitions. [Sovereign rollups](https://blog.celestia.org/sovereign-rollup-chains/), for example, only use the underlying L1 for data availability (DA) and not for consensus. - -Most of the rollups work on Ethereum uses Ethereum L1 both as a data availability layer, and for consensus, i.e., the validity of rollup transactions is determined by logic running on Ethereum L1. Newer systems, [like Celestia](https://celestia.org/), are taking a more modular approach and are separating DA from consensus. One interesting aspect of separating DA is that more established and durable chains like Bitcoin can be used for DA as well. Below is an interesting comparison of sidechains and two types of rollups possible on Bitcoin (John Light posted this [on Twitter](https://twitter.com/lightcoin/status/1630301411962388481?s=20)): - -![Bitcoin rollups compared with other L2s](rollup-comparison.png) - -This image broadly means developers can build sovereign rollups on Bitcoin today, but you'll need a "trusted" setup for moving BTC in and out of the rollup. In fact, people are already doing this -- see the recent [Rollkit announcement](https://rollkit.dev/blog/sovereign-rollups-on-bitcoin/). To build validity rollups, meaning Bitcoin L1 enforces BTC withdrawals from the rollup, you'll need modifications to Bitcoin L1. See [this overview](https://bitcoinrollups.org/) for more details. - -#### How does the Stacks layer compare? - -Stacks is not really a sidechain, given the Nakamoto release (see [latest Stacks paper](https://stacks.co/stacks.pdf)), Stacks layer will achieve 100% Bitcoin finality. Also, the Stacks layer has various other direct connections to Bitcoin L1 that sidechains typically do not have -- see [the above section](#is-stacks-a-bitcoin-l2) for details if Stacks is a Bitcoin L2 or not; the short answer is it depends on the definition you use. - -Stacks with the Nakamoto release will have Bitcoin-grade reorg resistance. The Nakamoto release does not allow Stacks forks, which means that the Stacks chain does not fork on its own, follows Bitcoin blocks with 100% finality, and does not have a separate security budget. This means that once a Stacks transaction is finalized, it is at least as hard to re-org as a Bitcoin transaction. - -For data availability, Stacks publishes only hashes of data to Bitcoin every Bitcoin block instead of posting all the data to Bitcoin. The designers separate data validation from data availability. Bitcoin is used for data validation, which is important. Bitcoin L1 and only Bitcoin L1 can confirm whether a presented Stacks layer history is valid. The block data itself is kept outside of Bitcoin L1 for scalability. As long as STX has any market cap, there is an incentive for Stacks miners to keep copies of the Stacks layer ledger around. Even if a single copy of the Stacks ledger exists, it can be independently verified against Bitcoin L1. Sovereign rollups publish all data to Bitcoin L1, giving both Bitcoin-grade data validity and data availability. The potential downside is scalability at Bitcoin L1, but the hope is that rollup data will not become very large. - -#### Can Stacks layer work with rollups? - -Yes! There is already an active R&D effort to integrate rollups with the Stacks layer. Both with the Stacks layer and sovereign rollups the technically challenging part is how to get BTC in and out of the Stacks layer or the sovereign rollup. The decentralized BTC peg, see [the sBTC paper](https://stacks.co/sbtc.pdf), applies to both the Stacks layer and sovereign rollups. Without modifying Bitcoin L1, an sBTC-like design with a decentralized open-membership group of signers is the most trust-minimized way to move BTC in and out of Bitcoin layers. Once the necessary upgrades to Bitcoin L1 can be made to enable validity rollups i.e., Bitcoin L1 can enforce BTC withdrawal from a layer, then the Stacks layer can also upgrade to benefit from it. - -Given a trust-minimized asset like sBTC is needed for sovereign rollups, with the launch of sBTC such sovereign rollups become even more interesting to deploy. The Stacks layer can potentially provide the decentralized group of signers for a trust-minimized BTC asset that can be used in a sovereign rollup, and DA comes directly from Bitcoin L1 e.g., with Ordinals. If you want to learn more, please join the [sBTC working group](https://github.com/stacks-network/stacks/discussions/469). There might be a dedicated rollups working group in the Stacks project soon as well. - -## Why Does Stacks Need a Token? - -This brings us to a central philosophical conversation in the world of crypto and Bitcoin, whether or not blockchains need tokens. - -Let's start by looking at the fundamental reason why tokens exist: to fund the maintenance and forward progress of a blockchain. - -Bitcoin is a token. It is a cryptocurrency that is used to incentivize miners to add new blocks to the chain. In Bitcoin's case, mining rewards are set on a predefined schedule, and once those mining rewards run out, the chain will need to survive on transaction fees alone. - -The purpose of a blockchain is to have a permanent historical record of every transaction that has ever occurred on the chain. Blockchains are basically ledgers. The token aspect is used as an incentive mechanism to secure the chain. - -This is why networks like Lightning and other P2P networks don't need tokens, they don't need to maintain a historical record. When we are talking about a system that is supposed to maintain a global financial system, it is important for the maintenance of that system to be incentivized correctly. - -Let's look at this concept in the context of Stacks and its goals. Stacks seeks to provide smart contract functionality to Bitcoin, to serve as the programming rails for building a decentralized economy on top of Bitcoin. - -Many Bitcoin community members are skeptical of new tokens and rightly so. There are countless projects out there that force the use of a token on their project and in many cases a token is actually not needed. Stacks project was started by Bitcoin builders who have a long history of building apps & protocols on Bitcoin L1 without any token (e.g., BNS launched in 2015 on Bitcoin L1 which was one of the largest protocols using OP_RETURN on Bitcoin L1). So why did a bunch of Bitcoin builders decided to have a separate token for Stacks L2? Great question! Let's dig into the details. - -The Stacks token (STX) is primarily meant to be used for two things (details in Stacks paper): - -1. Incentives for Stacks L2 miners -2. Incentives for peg-out signers - -The only way to remove the token is to build Stacks as a federated network like Liquid. In a federation the pre-selected group of companies control the mining and block production and a pre-selected group of companies need to be trusted for peg-out transactions. Stacks developers wanted to design an open and permissionsless system. The only way to have a decentralized mining process is through incentives. As mentioned above, his is how Bitcoin works as well, where newly minted BTC are used as incentives to mine new blocks and anyone in the world can decide to become a miner. Anyone with BTC can mine the Stacks L2 chain, it is open and permissionless. - -Similarly, the way the decentralized BTC peg, called sBTC (see the sBTC paper), is designed is that the group of signer is open and permissionless (unlike a federation). These signers have economic incentives to correctly follow the protocol for peg-out requests. In a federation, users need to blindly trust the pre-set federation members to get their BTC out of the federation and back on Bitcoin L1. Stacks developers wanted to have an open, permissionless, and decentralized way to move BTC from Bitcoin L1 to Stacks L2 and back. This is made possible through economic incentives i.e., need for a token. - -Other than these two reasons, STX is also used to pay gas fees for transactions. However, once the upcoming sBTC peg is live most of the economy of Stacks L2 is expected to follow a Bitcoin standard and work using BTC as the economic unit. It is expected that users will mostly interact just with Bitcoin and use BTC in wallets and apps (gas fees can be paid with BTC using atomic swaps in the background). It is important to note that BTC cannot be used for mining incentives on Stacks L2 because the only way to incentivize decentralized block production is through newly minted assets by the protocol (similar to how Bitcoin works itself) i.e., need for a token. - -## The Symbiotic Relationship Between Stacks and Bitcoin - -Stacks and Bitcoin complement each other. Stacks leverages the extreme decentralization of Bitcoin, its PoW consensus mechanism, and its value as a cryptocurrency. - -But Stacks also complements Bitcoin by unlocking additional use cases, thereby increasing its value over time. This also helps to solve the additional problem of the future maintainability of Bitcoin after the coinbase rewards are gone and Bitcoin has to function on transaction fees alone. - -If Bitcoin is seen as only a store of value, the economic density, meaning how much value is being exchanged, of each transaction will be minimal. But if Bitcoin is the underlying foundation for an entire decentralized economy, those [transactions become much more valuable](https://twitter.com/muneeb/status/1506976317618728963), increasing transaction fees. This is a crucial incentive for miners to continue securing the network as coinbase rewards drop. - - - -## Reading from and Writing to Bitcoin - -One of the things that gives the Stacks chain its superpowers in connecting with Bitcoin is not only how it connects to Bitcoin at a protocol level, discussed above, but also how we can utilize that Bitcoin at a programmatic level. - -That's where [Clarity](../clarity/) comes in. Clarity is the smart contract language for Stacks, and is how we actually build out a lot of the functionality we are talking about here. - -### How Does Clarity Read BTC State? - -One of the often-touted features of Clarity is that it has access to the state of the Bitcoin chain built in, but how does it actually do that? Because of Stacks' [PoX mechanism](../stacks-academy/proof-of-transfer.md), every Stacks block is connected to a Bitcoin block, and can query Bitcoin block header hashes with the [`get-burn-block-info?` function](https://github.com/stacksgov/sips/blob/feat/sip-015/sips/sip-015/sip-015-network-upgrade.md#new-method-get-burn-block-info). - -This function allows us to pass in a Bitcoin block height and get back the header hash. The [`burn-block-height` Clarity keyword](https://docs.stacks.co/docs/write-smart-contracts/clarity-language/language-keywords#burn-block-height) will give us the current block height of the Bitcoin chain. - -However, `get-burn-block-info?` only returns data of the Bitcoin block at that height if it has already been processed and was created after the launch of the Stacks chain. So if we want to evaluate whether or not something happened on Bitcoin, we have to wait at least one block later to do so. - -This is step 1 of Clarity contracts being able to serve as the programming layer for Bitcoin, when a BTC transaction is initiated, the first thing that needs to happen is that a Clarity contract needs to become aware of it. This can happen manually by utilizing Clarity functions discussed above with the [BTC library](https://explorer.stacks.co/txid/0x8b112f2b50c1fa864997b7496aaad1e3940700309a3fdcc6c07f1c6f8b9cfb7b?chain=mainnet), as [Catamaran Swaps](https://docs.catamaranswaps.org/en/latest/catamaran.html) do. - -:::tip -Note that this process is made easier by the additional Clarity functions added in 2.1, like the `get-burn-block-info?` function we looked at above. -::: - -Or we can automate (albeit at a cost of some centralization in our dapp) using an event-based architecture using something like Hiro's [chainhooks](https://www.hiro.so/blog/meet-4-new-features-in-clarinet#setting-up-trigger-actions-with-chainhooks), which will allow us to automatically trigger a Clarity contract call when a certain BTC transaction is initiated. - -This is the first component of using Stacks to build Bitcoin dapps, the read access to Bitcoin chain. - -### Can Clarity Write to BTC? - -But how can Stacks actually write to the Bitcoin chain? This has been somewhat of a holy grail problem in the Bitcoin and crypto world for years now, as it solves a difficult dilemma. - -On one hand, Bitcoin write functionality from more expressive smart contract chains allows for us to take the latent capital of Bitcoin and utilize it to build a Bitcoin-based economy. - -Bitcoin has a market cap of more than double that of Ethereum's, but has an almost non-existent app ecosystem because of this write problem. There is a massive market opportunity here for both developers and entrepreneurs if we are able to build decentralized applications that have a rival programming capacity to other chains like Ethereum. - -But the tradeoff here is that allowing this on the Bitcoin chain opens up a lot of new attack vectors and undermines a core tenet of Bitcoin: the fact that it is very simple and very good at doing what it does. - -Vitalik originally wanted to add functionality to Bitcoin, and created Ethereum when that didn't work. There's good reason for this. Allowing additional functionality like this exposes Bitcoin to more risk and attack vectors, this conundrum is what Stacks seeks to solve with sBTC. How can we achieve the same functionality as Ethereum but keep the security of Bitcoin? - -One possible route is by separating the programming and money layers, as Stacks and a few other chains do. While Stacks is a good chunk of the way towards this goal right now, due to the [PoX mechanism](../stacks-academy/proof-of-transfer.md), there is still some work to be done before it can be considered a Bitcoin programming layer. - -Specifically, it needs a tighter connection to the Bitcoin chain than PoX currently provides, and needs to share complete finality with Bitcoin. - -Second, it needs a completely trustless, decentralized two-way peg between the Stacks chain and Bitcoin, so that end users only have to send Bitcoin to an address, have things happen on the Stacks side, and have Bitcoin returned to them. - -These issues are currently being addressed with sBTC and the Stacks Nakamoto Release, both of which you can [read about on Stacks' website](https://www.stacks.co/learn/sbtc). - -## Bitcoin-First Applications in the Wild - -Putting all of this information together we can begin to see how we might build applications that are Bitcoin-first. The ultimate goal of Stacks is to serve as an invisible programming layer for Bitcoin, where STX operates primarily as a gas token to operate the Stacks network, but users only ever have to interact with it using their Bitcoin wallet. - -One of the most interesting projects currently taking advantage of this functionality is Zest, which uses a protocol called Magic under the hood to trustlessly swap BTC on the Bitcoin chain for xBTC on the Stacks chain. Zest is a protocol for decentralized borrowing and lending with Bitcoin. - -Here are the basics of how it works: - -1. First, Zest generates a unique [HTLC](https://en.bitcoin.it/wiki/Hash_Time_Locked_Contracts) Bitcoin address for liquidity providers to deposit their BTC to, this uses [Magic Protocol](https://www.magic.fun/) under the hood, which allows users to trustlessly swap BTC for xBTC. - -2. After LP (liquidity provider) sends funds to the HTLC address and the block is confirmed, the payment is considered in escrow. - -3. Now Stacks comes in by reading the Bitcoin state and verifying that deposit actually occurred on the BTC chain, and escrows the corresponding amount of xBTC if it did. If for some reason that were to fail, the LP is still in control of their BTC funds. - -4. Once that escrow is confirmed, LP signs a Stacks transaction that transfers control of the BTC over to Magic, at which point Magic controls the BTC and xBTC is transferred to the Zest liquidity pool. Zest tokens are then minted on the Stacks chain, representing a claim token for the LP's BTC funds - -The cool thing is that this all happens in a single Stacks block, because Stacks and Bitcoin blocks are completed in lockstep. For more details on how Magic handles this process we highly recommend [checking out their docs](https://magicstx.gitbook.io/magic-protocol/guides/technical-overview). - -To dive deeper into the details of how Zest is building a Bitcoin-first application, [check out their docs](https://zestprotocol.gitbook.io/zest/what-is-zest-protocol/the-technology-under-the-hood), and if you are interested in building something like this out for yourself, check out their smart contracts. - -## How to Build Bitcoin-First Dapps with Stacks - -We are currently working on a Stacks Cookbook, which will provide numerous examples for how to build Bitcoin-first apps using both Clarity and frontend Stacks and Bitcoin libraries. - -Until then, you can take a look at Magic and Zest, the protocols mentioned above, to see how they are going about facilitating this process using xBTC and model your applications after them. - -We are in the very early stages of being able to unlock and use BTC in decentralized applications, and much more content and tools will be created in the coming year to make this process easier for developers. - -## What's Next? - -As mentioned earlier on this page, xBTC is not an ideal solution. xBTC is a custodial solution run by [Wrapped](https://wrapped.com/). It does however, give us the building blocks we need to begin building Bitcoin-first applications with Stacks. And updates from Stacks 2.1 make it easier to perform these actions. - -With sBTC on its way, we'll begin to see a new batch of innovative projects that are able to build truly trustless, decentralized dapps with Bitcoin. - -Here are some resources to dive into to learn more about improvements coming to Stacks via the 2.1 upgrade, Nakamoto release, and sBTC. - -- [List of New Clarity Functions for 2.1](https://github.com/stacksgov/sips/blob/feat/sip-015/sips/sip-015/sip-015-network-upgrade.md#clarity) -- [How the Stacks 2.1 Transition Impacts Stacking](https://www.hiro.so/blog/how-the-stacks-2-1-transition-impacts-stacking) -- [Developer's Guide to Stacks 2.1](https://www.hiro.so/blog/a-developers-guide-to-stacks-2-1) -- [Learn About sBTC](https://www.stacks.co/learn/sbtc) -- [Stacks Nakamoto Release](https://stx.is/nakamoto) diff --git a/docs/stacks-academy/index.md b/docs/stacks-academy/index.md deleted file mode 100644 index 5e8c943eda..0000000000 --- a/docs/stacks-academy/index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Stacks Academy -description: An introduction to Stacks -sidebar_position: 3 ---- -# Stacks Academy - -Stacks Academy is designed to give you a start-to-finish introduction to Stacks, what it is, what problems it solves, and how it works. If you are looking to learn how to build on it, the [Tutorials](../tutorials/) are the best place for that. - -Let's get started by diving into exactly what the Stacks blockchain is. diff --git a/docs/stacks-academy/lw3-faucet.png b/docs/stacks-academy/lw3-faucet.png deleted file mode 100644 index cea83a0086..0000000000 Binary files a/docs/stacks-academy/lw3-faucet.png and /dev/null differ diff --git a/docs/stacks-academy/microblocks.md b/docs/stacks-academy/microblocks.md deleted file mode 100644 index ff1b38a4b2..0000000000 --- a/docs/stacks-academy/microblocks.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -title: Microblocks -description: Guide to Stacks Microblocks -sidebar_position: 5 ---- - -## Introduction - -Microblocks are a protocol-level feature of the Stacks blockchain that solve the technical challenge of transaction latency. - -Because each Stacks block is anchored to a Bitcoin block through the [Proof-of-Transfer consensus mechanism](../stacks-academy/proof-of-transfer), -Stacks is necessarily limited to the same block times as the Bitcoin network. Microblocks allow the Stacks blockchain to -perform state transitions between anchor blocks. - -Microblocks are a powerful mechanism for developers to create performant, high quality applications on Stacks, while -still inheriting the security of Bitcoin. - -## Transaction states - -The [Stacks block production model](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.) is described in SIP-001. The standard outlines the mechanism by which elected -block leaders can produce blocks on the Stacks blockchain either by batching transactions or by streaming them. -Microblocks are the product of the streaming model. - -If a block leader has elected to mine microblocks, the leader selects transactions from the mempool and package them -into microblocks during the current epoch. Microblocks are blocks of transactions included by a miner after the previous -anchor block has been mined, but before the next block is selected. Transactions included in microblocks are processed by -the network: their results are known. - -Consider a transaction from the perspective of the number of block confirmations it has. A transaction included in a -microblock might have the following example lifecycle: - -``` -Transaction 1 is broadcast to the mempool. It has 0 confirmations. -Transaction 1 is included in a microblock. It still has 0 confirmations, but the results of the transaction are known -Transaction 1 is included in the next anchor block. It has 1 confirmation. -The next Stacks block confirms the previous block. Transaction 1 has 2 confirmations. -The next Stacks block confirms the previous block. Transaction 1 has 3 confirmations. -... -``` - -Consider a similar transaction that is not included in a microblock: - -``` -Transaction 2 is broadcast to the mempool. It has 0 confirmations. -Transaction 2 is included in the next anchor block. It has 1 confirmation. -The next Stacks block confirms the previous block. Transaction 2 has 2 confirmations. -The next Stacks block confirms the previous block. Transaction 2 has 3 confirmations. -``` - -The lifecycle of the two transactions is similar, but the difference is pending state. Many Bitcoin wallets display -0-confirmation balances: your wallet balance with any mempool transactions already applied. This is useful because it -tells you when you've sent a transaction or received one. With smart contracts, displaying pending state is not as -straightforward, because smart contracts do not just transfer inputs to outputs, they may call other contracts, emit -events, or perform other computations. A transaction processed in a microblock generates all that information. - -:::tip -If a transaction is dependent on a chain state that could by altered by previous transactions with serious -implications, you should carefully consider whether it should be performed using microblocks. -::: - -## Enabling microblocks - -Miners can choose to enable or disable microblocks in their mining configuration. As a best practice, miners should enable -microblock mining. When an application or user submits a transaction, the transaction can include an argument that -requires the transaction to be in a microblock, an anchor block, or in either. - -### Transactions - -Transactions include an option that controls if a miner should include them in microblocks or in anchor blocks. The -anchor mode transaction option is an optional argument that controls whether a transaction must be included in -an anchor block or a microblock, or is eligible for either. - -### Mining - -Stacks miners must enable microblocks in their miner configuration to implement the block streaming model. For more -information, see [mining microblocks](../stacks-academy/mining#microblocks). - -## Developing with microblocks - -In most cases, information from transactions included in microblocks should be treated like information from any other -block. Wallets and explorers should display the consequences of microblock transactions as the current state of the -network. This state should be acknowledged as tentative. - -A microblock transaction can end up being reorganized in the next block rather than just being confirmed as-is. Because -of this, your UI should communicate to users if the outputs of a transaction changed, or if the transaction's associated -block changed. This is the same outcome as if a 1-block fork occurred. - -### Stacks.js Library - -If you are using Hiro's, Stacks.js, it provides the [AnchorMode](https://stacks.js.org/enums/transactions.AnchorMode.html) argument on transaction objects so that your application can set the microblocks preference for transactions. - -### API - -:::danger -API support for microblocks is a work-in-progress. Review the [API documentation][microblocks_api] carefully to -ensure that you are up-to-date on the latest implementation details for microblocks. -::: - -The Stacks Blockchain API exposes microblocks through several endpoints. Please review the -[Stacks Blockchain API guide](https://docs.hiro.so/get-started/stacks-blockchain-api#microblocks-support) for more details. - -## Best practices - -Working with microblocks is a design decision that you must make for your own application. When working with -microblocks, the following best practices are recommended. - -### Handling nonce - -Nonce handling with microblocks is challenging because the next account nonce must take into account any nonce values -included in microblocks, which may not yet be included in an anchor block. The Stacks Blockchain API -[provides an endpoint][] to retrieve the next nonce for a given principal. - -### Application design - -The state of microblock transactions should be carefully communicated to users. No transaction is final until it's -included in an anchor block, and your application design should reflect this. - -The following guidelines are provided as an initial set of best practices for UI design when incorporating microblocks -into your application. - -#### Explorers - -Display pending state, but warn that a transaction is still pending. Indicate visually that displayed balances depend -on pending state. - -#### Wallets - -Display pending state, but warn that a transaction is still pending. Indicate visually that displayed balances depend -on pending state. - -#### Exchanges - -Continue to count confirmations, microblocks should be considered pending. - -#### Applications - -Microblock communication is highly app-dependent. For some applications, displaying a pending or 0-confirmation -transaction as confirmed may be fine. For example, storing data on the chain, or querying the BNS contract. For other -applications, such as the transfer of real value, waiting for 3-confirmations would be prudent before displaying the -state as confirmed. - -[anchormode]: https://stacks.js.org/enums/transactions.AnchorMode.html -[stacks blockchain api guide]: https://docs.hiro.so/get-started/stacks-blockchain-api#microblocks-support -[provides an endpoint]: https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling -[microblocks_api]: https://docs.hiro.so/api#tag/Microblocks diff --git a/docs/stacks-academy/mining.md b/docs/stacks-academy/mining.md deleted file mode 100644 index beec56e58b..0000000000 --- a/docs/stacks-academy/mining.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: Mining -description: A guide to mining on Stacks 2.0 -sidebar_position: 4 ---- - -## Introduction - -This guide highlights some technical details related to mining on the Stacks 2.0 network. - -For steps on how to setup your own miner please refer to [miner on testnet](nodes-and-miners/miner-testnet.md) and [miner on mainnet](nodes-and-miners/miner-testnet.md). - -## Mining frequency - -A new Stacks block may be mined once per Bitcoin block. To be considered for mining a block, a miner must have a block commit included in a Bitcoin block. If a miner wishes to update their commitment after submission, they may use Bitcoin Replace-By-Fee. - -## Coinbase rewards - -Miners receive coinbase rewards for blocks they win. - -The reward amounts are: - -- 1000 STX per block are released in the first 4 years of mining -- 500 STX per block are released during the following 4 years -- 250 STX per block are released during the following 4 years -- 125 STX per block are released from then on indefinitely. - -These "halvings" are synchronized with Bitcoin halvings. - -![coinbase rewards](/img/pages/coinbase-rewards.png) - -## Transaction fees - -Miners receive Stacks fees for transactions mined in any block they produce. - -For transactions mined in microblocks, the miner that produces the microblock receives 40% of the fees, while the miner that confirms the microblock receives 60% of the fees. - -## Reward maturity - -Block rewards and transaction fees take 100 blocks on the Bitcoin blockchain to mature. After successfully mining a block your rewards appear in your Stacks account after ~24 hours. - -## Mining with proof-of-transfer - -Miners commit Bitcoin to **two** addresses in every leader block commit. The amount committed to each address must be the same. The addresses are chosen from the current reward set of stacking participants. Addresses are chosen using a verifiable-random-function, and determining the correct two addresses for a given block requires monitoring the Stacks chain. - -![mining with pox](/img/pages/mining-with-pox.png) - -PoX mining is a modification of Proof-of-Burn (PoB) mining, where instead of sending the committed Bitcoin to a burn address, it's transferred to eligible STX holders that participate in the stacking protocol. - -:::note -A PoX miner can only receive newly minted STX tokens when they transfer Bitcoin to eligible owners of STX tokens -::: - -![Mining flow](/img/pox-mining-flow.png) - -Miners run Stacks nodes with mining enabled to participate in the PoX mechanism. The node implements the PoX mechanism, which ensures proper handling and incentives through four key phases: - -- Registration: miners register for a future election by sending consensus data to the network -- Commitment: registered miners transfer Bitcoin to participate in the election. Committed BTC are sent to a set participating STX token holders -- Election: a verifiable random function chooses one miner to write a new block on the Stacks blockchain -- Assembly: the elected miner writes the new block and collects rewards in form of new STX tokens - -## 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, 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. - -While there is no minimum BTC commitment enforced by the protocol, in practice, there's a floor constrained by [dust](https://unchained-capital.com/blog/dust-thermodynamics/)": basically, if the fees for a transaction exceed the value of the spent output, it's considered dust. How dust is [calculated](https://github.com/bitcoin/bitcoin/blob/master/src/policy/policy.cpp#L14) depends on a number of factors, we've found 5,500 satoshis to be good lower bound per [output](https://learnmeabitcoin.com/technical/output). Bitcoin transactions from Stacks miners contain two outputs (for Proof-of-Transfer), so a commitment of at least 11,000 satoshis / block is recommended. - -To calculate the amount of BTC to send miners should: - -- Guess the price BTC/STX for the next day (100 blocks later) -- Guess the total amount of BTCs committed by all miners - -## Microblocks - -The Stacks blockchain produces blocks at the same rate as the Bitcoin blockchain. In order to provide lower latency -transactions, miners can opt to enable microblocks. Microblocks allow the current block leader to stream transactions -and include their state transitions in the current epoch. - -If a block leader opts to produce microblocks, the next leader builds the chain tip off the last microblock that the -current leader produces. - -The block streaming model is described in [SIP-001][]. - -[sip-001]: https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md#operation-as-a-leader diff --git a/docs/stacks-academy/network.md b/docs/stacks-academy/network.md deleted file mode 100644 index 959476e709..0000000000 --- a/docs/stacks-academy/network.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -title: Network -description: Guide to the Stacks 2.0 network -sidebar_position: 5 ---- - -## Tokens - -Stacks (STX) tokens are the native tokens on the Stacks 2.0 blockchain. The smallest fraction is one micro-STX. 1,000,000 micro-STX make one Stacks (STX). - -STX amounts should be stored as integers (8 bytes long), and represent the amount of micro-STX. For display purposes, micro-STX are divided by 1,000,000 (decimal precision of 6). - -## 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 in bytes. The fee rate is a market determined variable. For the [testnet](testnet), it is set to 1 micro-STX. - -Fee estimates can obtained through the [`GET /v2/fees/transfer`](https://docs.hiro.so/api#operation/get_fee_transfer) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/fees/transfer' -``` - -The API will respond with the fee rate (as integer): - -```json -1 -``` - -[The Stacks Transactions JS library](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) supports fee estimation for: - -- token transfers (`estimateTransfer`) -- contract deploys (`estimateContractDeploy`) -- non read-only contract calls (`estimateContractFunctionCall`) - -:::tip -For an implementation using a different language than JavaScript, please review [this reference implementation](https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/src/builders.ts#L97). -::: - -## Nonces - -Every account carries a [nonce property](https://en.wikipedia.org/wiki/Cryptographic_nonce) that indicates the number of transactions processed for the given account. Nonces are one-time codes, starting at `0` for new accounts, and incremented by 1 on every transaction. - -Nonces are added to all transactions and help identify them in order to ensure transactions are processed in order and to avoid duplicated processing. - -:::tip -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 is constructed, the most recent nonce of the account needs to fetched and set. - -:::tip -The API provides an endpoint to [simplify nonce handling](https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling). -::: - -## Confirmations - -The Stacks 2.0 network is anchored onto the bitcoin network. This allows transactions on Stacks to inherit the same finality and security of the Bitcoin blockchain. - -The time to mine a block, to confirm transactions, will eventually match the expected "block time" of the bitcoin network: 10 minutes. - -:::tip -Transactions can also be mined in [microblocks](microblocks), reducing the latency significantly. -::: - -The block time is hardcoded and will change throughout the implementation phases of the [testnet](testnet). The current block time can be obtained through the [`GET /extended/v1/info/network_block_times`](https://docs.hiro.so/api#operation/get_network_block_times) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/info/network_block_times' -``` - -The API will respond with the block time (in seconds): - -```js -{ - "testnet": { - "target_block_time": 120 - }, - "mainnet": { - "target_block_time": 600 - } -} -``` - -## Read-only function calls - -Smart contracts can expose public function calls. For functions that make state modifications to the blockchain, transactions need to be generated and broadcasted. - -However, for read-only function calls, transactions are **not** required. Instead, these calls can be done using the [Stacks Blockchain API](https://docs.hiro.so/get-started/stacks-blockchain-api). - -:::tip -Read-only function calls do not require transaction fees -::: - -A read-only contract call can be done using the [`POST /v2/contracts/call-read///`](https://docs.hiro.so/api#operation/call_read_only_function) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl --location --request POST 'https://stacks-node-api.testnet.stacks.co/v2/contracts/call-read///' \ ---header 'Content-Type: application/json' \ ---data-raw '{ - "sender": ".", - "arguments": [, ...] -}' -``` - -Sample response for a successful call: - -```js -{ - "okay": true, - "result": "" -} -``` - -:::tip -To set the function call arguments and read the result, Clarity values need to be serialized into a hexadecimal string. The [Stacks Transactions JS](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library supports these operations -::: - -## Querying - -Stacks 2.0 network details can be queried using the [Stacks Blockchain API](https://docs.hiro.so/get-started/stacks-blockchain-api). - -### Health check - -The [status checker](https://stacks-status.com/) is a service that provides a user interface to quickly review the health of the Stacks 2.0 blockchain. - -### Network info - -The network information can be obtained using the [`GET /v2/info`](https://docs.hiro.so/api#operation/get_core_api_info) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/info' -``` - -Sample response: - -```js -{ - "peer_version": 385875968, - "burn_consensus": "826401d65cf3671210a3fb135d827d549c0b4d37", - "burn_block_height": 1972, - "stable_burn_consensus": "e27ea23f199076bc41a729d76a813e125b725f64", - "stable_burn_block_height": 1971, - "server_version": "blockstack-core 0.0.1 => 23.0.0.0 (master:bdd042242+, release build, linux [x86_64]", - "network_id": 2147483648, - "parent_network_id": 3669344250, - "stacks_tip_height": 933, - "stacks_tip": "1f601823fbcc5b6b2215b2ff59d2818fba61ee4a3cea426d8bc3dbb268005d8f", - "stacks_tip_burn_block": "54c56a9685545c45accf42b5dcb2787c97eda8185a1c794daf9b5a59d4807abc", - "unanchored_tip": "71948ee211dac3b241eb65d881637f649d0d49ac08ee4a41c29217d3026d7aae", - "exit_at_block_height": 28160 -} -``` diff --git a/docs/stacks-academy/post-condition.jpeg b/docs/stacks-academy/post-condition.jpeg deleted file mode 100644 index 465695e0bd..0000000000 Binary files a/docs/stacks-academy/post-condition.jpeg and /dev/null differ diff --git a/docs/stacks-academy/post-conditions.md b/docs/stacks-academy/post-conditions.md deleted file mode 100644 index bb0727194f..0000000000 --- a/docs/stacks-academy/post-conditions.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Post Conditions -description: What post conditions are and how they work -sidebar_position: 10 ---- - -Post conditions are one of the most interesting and unique aspects of Stacks. - -From the beginning, safety and security has been at the heart of the Stacks ethos and formed the foundation of architecture decisions when building it. - -Like Clarity, Stacks' smart contract programming language, post conditions were specifically built and design to solve the problem of user safety when interacting with blockchain applications. - -So what are they and how do they work? - -## How Post Conditions Work - -Post conditions are conditions that are set on the client side to ensure that a smart contract does not perform any unexpected behavior. - -Let's look at an example to make this more concrete. - -Let's say a user is on an NFT marketplace and is expecting to purchase an NFT for 100 STX. Using post conditions, the developer who is building the frontend of the application can add in post conditions to ensure that this is in fact what happens when the user initiates the transaction. - -If it does not, the transaction will abort and the user won't be out anything except the transaction fee. - -It's important to note that post conditions do not live in smart contracts. They are designed to be an extra layer of security on top of smart contracts. - -The problem they help address is a user interacting with a malicious smart contract that attempts to do something the user does not expect. - -But rather than simply being a UI feature of a wallet, these post conditions are built into the Stacks blockchain itself and are enforced at the protocol level. - -When you use a Stacks wallet like the Hiro web wallet and initiate a transaction, the wallet will display the post conditions set by the developer and tell the user exactly what is going to happen. If the action taken by the smart contract matches, the transaction goes through fine, otherwise it aborts. - -Here's what that looks like: - -![Stacks post condition example](./post-condition.jpeg) - -In this example, if the smart contract does not transfer one fabulous-frog NFT and and take 50 STX from the user, the transaction will abort. - -You can learn more about how post conditions work in [SIP-005](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md#transaction-post-conditions) and how to utilize them in your applications in the tutorial, [Understanding Stacks Post Conditions](https://dev.to/stacks/understanding-stacks-post-conditions-e65). diff --git a/docs/stacks-academy/proof-of-transfer.md b/docs/stacks-academy/proof-of-transfer.md deleted file mode 100644 index 50f4b739d6..0000000000 --- a/docs/stacks-academy/proof-of-transfer.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: Proof of Transfer -description: Understand the proof-of-transfer consensus mechanism -sidebar_position: 3 ---- - -In the previous section, we took a look at the vision and ethos of Stacks. We talked a lot about it being connected to Bitcoin and how it enables expanding functionality without modifying Bitcoin itself. - -In this section, we'll run through the consensus mechanism that makes that happen, Proof of Transfer. - -Consensus algorithms for blockchains require compute or financial resources to secure the blockchain. The general practice of decentralized consensus is to make it practically infeasible for any single malicious actor to have enough computing power or ownership stake to attack the network. - -Popular consensus mechanisms in modern blockchains include proof of work, in which nodes dedicate computing resources, and proof of stake, in which nodes dedicate financial resources to secure the network. - -Proof of burn is another, less-frequently used consensus mechanism where miners compete by ‘burning’ (destroying) a proof of work cryptocurrency as a proxy for computing resources. - -Proof of transfer (PoX) is an extension of the proof of burn mechanism. 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. - -![PoX mechanism](/img/pox-mechanism.png) - -This allows network participants to secure the PoX cryptocurrency network and earn a reward in the base cryptocurrency. Thus, PoX blockchains are anchored on their chosen PoW chain. Stacks uses [Bitcoin](#why-bitcoin) as its anchor chain. - -![PoX participants](/img/pox-participants.png) - -## Why Bitcoin? - -There are a number of reasons that Stacks chose Bitcoin as the blockchain to power consensus. It's the oldest blockchain protocol, having launched in 2009, and has become a recognized asset outside of the cryptocurrency community. BTC has held the highest market capitalization of any cryptocurrency for the past decade. - -Bitcoin champions simplicity and stability, and has stood the test of time. Influencing or attacking the network is infeasible or impractical for any potential hackers. It's one of the only cryptocurrencies to capture public attention. Bitcoin is a household name, and is recognized as an asset by governments, large corporations, and legacy banking institutions. Lastly, Bitcoin is largely considered a reliable store of value, and provides extensive infrastructure to support the PoX consensus mechanism. - -SIP-001 provides a full [list of reasons why Bitcoin was chosen to secure Stacks](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md). - -:::note -By the way, SIP stands for Stacks Improvement Proposal, and it's the process by which community members agree on making changes to the network, we'll look at these in a future lesson. -::: - -## Blocks and microblocks - -The Stacks blockchain allows for increased transaction throughput using a mechanism called microblocks. Bitcoin and Stacks progress in lockstep, and their blocks are confirmed simultaneously. On Stacks, this is referred to as an ‘anchor block’. An entire block of Stacks transactions corresponds to a single Bitcoin transaction. This significantly improves cost/byte ratio for processing Stacks transactions. Because of simultaneous block production, Bitcoin acts as a rate-limiter for creating Stacks blocks, thereby preventing denial-of-service attacks on its peer network. - -However, in between Stacks anchor blocks settling on the Bitcoin blockchain, there are also a varying number of microblocks that allow rapid settlement of Stacks transactions with a high degree of confidence. This allows Stacks transaction throughput to scale independently of Bitcoin, while still periodically establishing finality with the Bitcoin chain. The Stacks blockchain adopts a block streaming model whereby each leader can adaptively select and package transactions into their block as they arrive in the mempool. Therefore when an anchor block is confirmed, all of the transactions in the parent microblock stream are packaged and processed. This is an unprecedented method for achieving scalability without creating a totally separate protocol from Bitcoin. - -![stx-microblock](/img/stx-microblocks.png) - -## Unlocking Bitcoin capital - -In the previous section we talked about Stacks being able to allow us to build a decentralized economy on top of Bitcoin and that PoX was a key piece of being able to do that. - -The reason is two-fold. First, as a part of this PoX mining process we have covered here, a hash of each Stacks block is recorded to the OP_RETURN opcode of a Bitcoin transaction. If you aren't familiar, the OP_RETURN opcode allows us to store up to 40 bytes of arbitrary data in a Bitcoin transaction. - -:::note -This [Stack Exchange answer](https://bitcoin.stackexchange.com/questions/29554/explanation-of-what-an-op-return-transaction-looks-like) gives a good overview of the reasoning and history of this opcode. -::: - -This is how Stacks records its history to the Bitcoin chain and why it inherits some security as a result of this process. If you wanted to try and create a false Stacks fork, you would have to broadcast the entire process to the Bitcoin chain. - -Similarly, if you wanted to try and change the history of the Stacks chain, you would have to somehow modify these OP_RETURN values in each corresponding Bitcoin block, meaning you would have to compromise Bitcoin in order to compromise the history of Stacks. - -:::caution -Note that this is not the same thing as saying that you need to compromise Bitcoin in order compromise Stacks at all, but simply that in order to falsify the history of the Stacks chain you would have to also falsify the history of the Bitcoin chain. -::: - -Additionally, part of this PoX process involves each Stacks block also knowing which Bitcoin block it is anchored to. Clarity, Stacks' smart contract language, has built-in functions for reading this data, such as [`get-block-info`](https://docs.stacks.co/docs/write-smart-contracts/clarity-language/language-functions#get-block-info), which returns, among other things, a field called `burnchain-header-hash`, which gives us the hash of the Bitcoin header corresponding to this Stacks block. - -This allows us to do really interesting things like trigger certain things to happen in a Clarity contract by watching the chain and verifying whether or not certain transactions occurred. You can see this in action in [Catamaran Swaps](https://docs.catamaranswaps.org/en/latest/catamaran.html), with other interesting projects like [Zest](https://www.zestprotocol.com/) seeking to expand on this functionality. - -The ultimate goal of all this is to enable the vision of web3, building a decentralized economy and enabling true user ownership of assets and data, on top of Bitcoin as a settlement layer, and using Bitcoin as a base decentralized money. - -![Unlocking Bitcoin](/img/pox-unlocking-btc.png) - -We also recommend [reading the full PoX whitepaper](https://community.stacks.org/pox), as it breaks down the reasoning behind creating a PoX chain and the unique benefits we get from doing so. - -## Proof of Transfer Contracts and Technical Details - -The Proof of Transfer functionality is implemented on the Stacks chain via a [Clarity smart contract](https://explorer.stacks.co/txid/0xfc878ab9c29f3d822a96ee73898000579bdf69619a174e748672eabfc7cfc589). An overview of this contract is [available in the docs](../clarity/noteworthy-contracts/stacking-contract.md). - -You can see the original design for stacking and proof of transfer by reading the relevant SIP, [SIP-007](https://github.com/stacksgov/sips/blob/main/sips/sip-007/sip-007-stacking-consensus.md). You can also utilize [Hiro's API](https://docs.hiro.so/api#tag/Info/operation/get_pox_info) to get proof of transfer details including the relevant contract address. - -However, since Stacks mainnet launched in January 2021, several shortcomings have been recognized in the stacking process, which are being corrected in the next major network epoch, Stacks 2.1 You can read more about these changes in [SIP-015](https://github.com/stacksgov/sips/blob/feat/sip-015/sips/sip-015/sip-015-network-upgrade.md), the SIP responsible for managing the upgrade to 2.1. - -### Got another question - -Have another question not answered here? Post in on Stack Overflow under the appropriate tag(s) and post the link to the Stack Overflow question in the Stacks Discord in the appropriate channel. diff --git a/docs/stacks-academy/rollup-comparison.png b/docs/stacks-academy/rollup-comparison.png deleted file mode 100644 index e444a6e3ec..0000000000 Binary files a/docs/stacks-academy/rollup-comparison.png and /dev/null differ diff --git a/docs/stacks-academy/sips.md b/docs/stacks-academy/sips.md deleted file mode 100644 index c70cc5866b..0000000000 --- a/docs/stacks-academy/sips.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: SIPs -description: SIPs -sidebar_position: 2 ---- - -## Stacks Improvement Proposals (SIPs) - -Stacks improvement proposals (SIPs) are aimed at describing the implementation of the Stacks blockchain, as well as proposing improvements. - -The SIP process [(SIP-000)](https://github.com/stacksgov/sips/blob/main/sips/sip-000/sip-000-stacks-improvement-proposal-process.md) describes how to make a SIP and get it ratified. - -They should contain concise technical specifications of features or standards and the rationale behind it. SIPs are intended to be the primary medium for proposing new features, for collecting community input on a system-wide issue, and for documenting design decisions. - -The SIPs are located in the [stacksgov/sips](https://github.com/stacksgov/sips) repository as part of the [Stacks Community Governance organization](https://github.com/stacksgov). - -Anyone in the Stacks community can submit a SIP. - -:::tip Stacks Improvement Proposals Community Calls -Add the [weekly community SIP call](https://www.addevent.com/event/wS15955379) to your calendar. - -SIP Meeting calls are recorded and available [here](https://www.youtube.com/playlist?list=PLg717Ri_rTnx5kuaWqp3cUAtwQk_yzslT) - -More details of the meetings are available [here](https://github.com/stacksgov/sips/issues/79) -::: - -## Ratified SIPSs - -- [x] [SIP 001: Burn Election](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md) -- [x] [SIP 002: Clarity, a language for predictable smart contracts](https://github.com/stacksgov/sips/blob/main/sips/sip-002/sip-002-smart-contract-language.md) -- [x] [SIP 003: Peer Network](https://github.com/stacksgov/sips/blob/main/sips/sip-003/sip-003-peer-network.md) -- [x] [SIP 004: Cryptographic Commitment to Materialized Views](https://github.com/stacksgov/sips/blob/main/sips/sip-004/sip-004-materialized-view.md) -- [x] [SIP 005: Blocks, Transactions, and Accounts](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md) -- [x] [SIP 006: Clarity Execution Cost Assessment](https://github.com/stacksgov/sips/blob/main/sips/sip-006/sip-006-runtime-cost-assessment.md) -- [x] [SIP 007: Stacking Consensus](https://github.com/stacksgov/sips/blob/main/sips/sip-007/sip-007-stacking-consensus.md) -- [x] [SIP 008: Clarity Parsing and Analysis Cost Assessment](https://github.com/stacksgov/sips/blob/main/sips/sip-008/sip-008-analysis-cost-assessment.md) -- [x] [SIP 009: Standard Trait Definition for Non-Fungible Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-009/sip-009-nft-standard.md) -- [x] [SIP 010: Standard Trait Definition for Fungible Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-010/sip-010-fungible-token-standard.md) -- [x] [SIP 012: Burn Height Selection for a Network Upgrade to Introduce New Cost-Limits](https://github.com/stacksgov/sips/blob/main/sips/sip-012/sip-012-cost-limits-network-upgrade.md) -- [x] [SIP-015: Stacks Upgrade of Proof-of-Transfer and Clarity](https://github.com/stacksgov/sips/blob/main/sips/sip-015/sip-015-network-upgrade.md) -- [x] [SIP-016: Metadata for Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-016/sip-016-token-metadata.md) -- [x] [SIP-018: Signed Structured Data](https://github.com/stacksgov/sips/blob/main/sips/sip-018/sip-018-signed-structured-data.md) -- [x] [SIP-020: Bitwise Operations in Clarity](https://github.com/stacksgov/sips/blob/main/sips/sip-020/sip-020-bitwise-ops.md) - -## How to Get Involved - -There are several ways you can get involved with the SIP process: - -- **Join the weekly SIP Meeting call** listed [here](https://community.stacks.org/events). - -- **SIP Editor**. SIP editors help SIP authors make sure their SIPs are well-formed and follow the right process. They help get SIPs ready for deep review by advancing it them from Draft to Accepted status. If you want to become a SIP editor, open an issue with your name and email to ask to be added to the list of SIP editors. - -- **Join a CAB** (Consideration Advisory Board). SIPs fall under the purview of one or more considerations. - A full list is in [this github](https://github.com/stacksgov/sips/tree/main/considerations) directory. Currently they are: Diversity, Economics, Ethics, Governance and Technical. - Members of SIP consideration advisory boards use their domain expertise to give Accepted SIPs a deep read, and give the authors any/all feedback to help make the SIP workable. If you want to join a board, reach out to the board's chairperson via the listed contact information. - -- **Steering Committee**. The Steering Committee organizes the consideration advisory boards and votes to advance Recommended SIPs to Activation-in-Progress status, and then to either Ratified or Rejected status. - Once they are in the process of being activated, they use a SIP's Activation section to determine whether or not the Stacks ecosystem has ratified or rejected the SIP. - Joining this committee requires the consent of the Stacks Foundation board. diff --git a/docs/stacks-academy/stacking.md b/docs/stacks-academy/stacking.md deleted file mode 100644 index 846152ecf9..0000000000 --- a/docs/stacks-academy/stacking.md +++ /dev/null @@ -1,188 +0,0 @@ ---- -title: Stacking -description: Introduction to the reward mechanism of Proof-of-Transfer -sidebar_position: 11 ---- - -## Introduction - -Stacking rewards Stacks (STX) token holders with bitcoin for providing a valuable service to the network by locking up their tokens for a certain time. - -## Stacking vs Staking - -It is crucial to note that this has no impact on block production or validation. **Stacks is not a Proof-of-Stake network and _stacking_ is different than _staking_**. - -There are two primary differences between stacking in Stacks and staking in other PoS networks. - -### Yield generated in burnchain token - -In staking, users lock one token and earn their yield in the same token. In stacking, users lock one token (STX) and earn a yield in the "burnchain" token (BTC), rather than the same token that was locked. In [PoX](./proof-of-transfer.md), the yield comes from a finite, external source (Bitcoin deposits from Stacks miners). In PoS, the yield comes from the currency's issuance schedule itself, which means it is programmatically unlimited (but theoretically limited, we'll get into this a bit more below). - -That's the first main difference. Staking involves a yield of the same token being generated by the issuance mechanism set by the core protocol, where stacking yield requires an input of an external, separate token. - -How are these issuance rates set? In Ethereum, issuance rates are determined by network usage. Ethereum's goal is to create a deflationary money supply, so the issuance rate is determined depending on the usage of the network. In order for an Ethereum transaction to be considered valid, it must include a base fee that is burned during transaction execution. The [issuance rate is algorithmically determined](https://ethereum.org/en/roadmap/merge/issuance/#post-merge) block-by-block depending on how much ETH is being burned by these base fees plus normal gas fees. - -Stacking doesn't have any of this complex functionality, since it does not generate a yield of the same token (and therefore doesn't need to issue new tokens, but rather transfer existing tokens from the base network) and it does not need to maintain an issuance rate. We are speaking here of the yield specifically, Stacks does have an issuance rate and does generate new STX tokens, but this process is completely separate from stacking and the yield generated from it. - -The Bitcoin yield that stackers earn is determined by a combination of the Bitcoin being committed by miners and the number of STX tokens that are locked up in the network. - -### No effect on transaction validation or consensus mechanism - -The other main difference is that staking involves validators, and is tightly coupled with the operations of the network. - -In both protocols stackers/stakers are earning a yield for providing a service. In PoX, that service is providing economic security by signaling what the canonical Stacks chain is (the chain with the most money locked in it is the real chain) and soon will provide the service of serving as signers for [sBTC](https://stacks.co/sbtc). - -In PoS, the service stakers provide is running a validator node, which is in charge of determining what transactions are or are not valid. So in a PoX system with stacking, the yield generation process is not attached to the validity and operations of the network, whereas in PoS it is. - -In PoS, the entities that are locking up their tokens and earning a yield are the same entities that are in charge of determining what does and does not count as a valid transaction. This and the fact that the yield is in the same token that is locked, have large implications on a PoS chain functioning much like equities in that the entities with the largest stake have the most controlling power over the transactional operations of the chain. - -Here's an [article](https://krgrs.dev/why-bitcoin-is-the-biggest-opportunity-for-developers-in-2023#heading-technology-and-economic-incentives) by Stacks Foundation Developer Advocate Kenny Rogers that goes more in-depth into these economic incentives, with additional resources. - -It is important to note that this control does not extend to being able to change the rules of the blockchain itself, but only to vote transactions as valid or invalid. - -In order to incentivize honest behavior on the part of validators, stake can be slashed as a punishment. Since PoX stackers do not have any say in transaction validity, this punishment mechanism does not exist and is not necessary in PoX. - -![](/img/stacking.png) - -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 network. - -:::info -Stacking functionality is implemented as a smart contract, using [Clarity](../clarity/). [Read more about the contract](../clarity/noteworthy-contracts/stacking-contract). -::: - -## Stacking flow - -The Stacking mechanism can be presented as a flow of actions: - -![Stacking flow](/img/stacking-illustration.png) - -1. Make API calls to get details about the upcoming reward cycle -2. For a specific Stacks account, confirm eligibility -3. Confirm the BTC reward address and the lockup duration -4. The transaction is broadcasted and the STX tokens are locked. This needs to happen before the prepare phase of the next reward cycle, the last 100 Bitcoin blocks of the ongoing reward phase -5. The Stacking mechanism executes reward cycles and sends out rewards to the set BTC reward address -6. During the lockup period, details about unlocking timing, rewards and more can be obtained -7. Once the lockup period is passed, the tokens are released and accessible again -8. Display reward history, including details like earnings for previous reward cycles - -:::info -Keep in mind that the target duration for a reward cycles is ~2 weeks. This duration is based on the target block time of the network (10 minutes) and can be higher at times due to [confirmation time variances](https://www.blockchain.com/charts/median-confirmation-time) of the bitcoin network. -::: - -## Stacking delegation flow - -The Stacking flow is different for delegation use cases: - -![Delegated tacking flow](/img/stacking-delegation-illustration.png) - -- Before Stacking can be initiated for a token holder, the delegator needs to be granted permission to Stack on behalf of the account owner. The permission is restricted to the maximum amount the delegator is allowed to Stack. The maximum amount is not limited by the available funds and can be set much higher. An account can only be associated with one single delegator -- The account has to define the delegation relationship. They can optionally restrict the Bitcoin reward address that must be used for payouts, and the expiration burn block height for the permission, thus limiting the time a delegator has permission to Stack -- Delegators have to lock Stacks from different accounts ("pooling phase") until they reach the minimum amount of Stacks required to participate in Stacking -- Once a delegator locks enough STX tokens, they can finalize and commit their participation in the next reward cycle -- Certain delegation relationships may allow the STX holder to receive the payout directly from the miner (step 5/6) -- The termination of the delegation relationship can either happen automatically based on set expiration rules or by actively revoking delegation rights - -## Token holder eligibility - -Stacks (STX) token holders don't automatically receive stacking rewards. Instead, they must: - -- Commit to participation before a reward cycle begins -- Commit the minimum amount of STX tokens to secure a reward slot, or pool with others to reach the minimum -- Lock up STX tokens for a specified period -- Provide a supported Bitcoin address to receive rewards (p2pkh, p2sh, SegWit, or Taproot) - -The following diagram describes how the minimum STX tokens per slot is determined. More information on -[dynamic minimums for stacking](https://stacking.club) is available at stacking.club. - -![Dynamic minimum for individual eligibility](/img/stacking-dynamic-minimum.png) - -Token holders have a variety of providers and tools to support their participation in Stacking. The Stacks website contains a [list of stacking providers and pools](https://stacks.org/stacking#earn). - -## Stacking in the PoX consensus algorithm - -Stacking is a built-in capability of PoX and occurs through a set of actions on the Stacks blockchain. The [full proof-of-transfer implementation details](https://github.com/stacks-network/stacks-blockchain/blob/develop/sip/sip-007-stacking-consensus.md) are in SIP-007. Below is a summary of the most relevant actions of the algorithm. - -![PoX cycles](/img/pox-cycles.png) - -- Stacking happens over reward cycles with a fixed length. In each reward cycle, a set of Bitcoin addresses associated with stacking participants receive BTC rewards -- A reward cycle consists of two phases: prepare and reward -- During the prepare phase, miners decide on an anchor block and a reward set. Mining any descendant forks of the anchor block requires transferring mining funds to the appropriate reward addresses. The reward set is the set of Bitcoin addresses which are eligible to receive funds in the reward cycle -- Miners register as leader candidates for a future election by sending a key transaction that burns cryptocurrency. The transaction also registers the leader's preferred chain tip (must be a descendant of the anchor block) and commitment of funds to 2 addresses from the reward set -- Token holders register for the next rewards cycle by broadcasting a signed message that locks up associated STX tokens for a protocol-specified lockup period, specifies a Bitcoin address to receive the funds, and votes on a Stacks chain tip -- Multiple leaders can commit to the same chain tip. The leader that wins the election and the peers who also burn for that leader collectively share the reward, proportional to how much each one burned -- Token holders' locked up tokens automatically unlock as soon as the lockup period finishes - -## Bitcoin address - -:::note -Currently, all 4 address types are supported: Legacy, SegWit, Native SegWit, and Taproot. -::: - -The Stacking contract needs a special format for the Bitcoin address (the reward address). This is required to ensure that miners are able to correctly construct the Bitcoin transaction containing the reward address. - -The address must be specified in the following format using the Clarity language: - -```clar -;; a tuple of a version and hashbytes buffer -(pox-addr (tuple (version (buff 1)) (hashbytes (buff 20)))) -``` - -The `version` buffer must represent what kind of bitcoin address is being submitted. It can be one of the following: - -```js -SerializeP2PKH = 0x00, // hash160(public-key), same as bitcoin's p2pkh -SerializeP2SH = 0x01, // hash160(multisig-redeem-script), same as bitcoin's multisig p2sh -SerializeP2WPKH = 0x02, // hash160(segwit-program-00(p2pkh)), same as bitcoin's p2sh-p2wpkh -SerializeP2WSH = 0x03, // hash160(segwit-program-00(public-keys)), same as bitcoin's p2sh-p2wsh -``` - -The `hashbytes` are the 20 hash bytes of the bitcoin address. You can obtain that from a bitcoin library, for instance using [`bitcoinjs-lib`](https://github.com/bitcoinjs/bitcoinjs-lib): - -```js -const btc = require("bitcoinjs-lib"); -console.log( - "0x" + - btc.address - .fromBase58Check("1C56LYirKa3PFXFsvhSESgDy2acEHVAEt6") - .hash.toString("hex") -); -``` - -## Choosing the right Stacking strategy - -[Here](https://blog.stacks.co/stacking-strategy) is an interesting article that may help you choose the right Stacking strategy. - -## Where to Stack? - -You can Stack on your own, on a pool or on an exchange: - -### Stacking on your own - -Stacking on your own is non-custodial. - -Stacking on your own requires a protocol minimum (amount changes but about 100,000 STX). - -[Hiro Wallet](https://www.hiro.so/wallet) allows stacking on your own. - -### Stacking on a pool - -Stacking on a pool allows Stacking without the requirement of the protocol minimum. - -Some available pools are: - -| Pool | Type | Pays rewards in | Fee | Minimum amount | -| --------------------------------------------------- | ------------- | :-------------: | --- | :------------: | -| [Friedger's Pool](https://pool.friedger.de/) | Non custodial | STX or xBTC | No | 40 STX | -| [Planbetter](https://planbetter.org/) | Non custodial | BTC | 5% | 200 STX | -| [Stacked](https://staking.staked.us/stacks-staking) | Non custodial | BTC | | 100,000 STX | -| [Xverse](https://www.xverse.app/) | Non custodial | BTC | No | 100 STX | - -### Stacking on an exchange - -Stacking on an exchange is custodial, meaning you are trusting the exchange with your Stacks. - -Several exchanges allow Stacking directly on their sites. Examples are [Okcoin](https://www.okcoin.com) and [Binance](https://www.binance.com/en/staking) - -## Stacking statistics - -You can view all sorts of Stacking data and statistics on [Stacking Club](https://stacking.club) diff --git a/docs/stacks-academy/stacks-blockchain-api.md b/docs/stacks-academy/stacks-blockchain-api.md deleted file mode 100644 index 4197ac6588..0000000000 --- a/docs/stacks-academy/stacks-blockchain-api.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: Stacks Blockchain API -description: Interacting with the Stacks 2.0 Blockchain via API -sidebar_position: 6 ---- - -## Introduction -The Stacks 2.0 Blockchain API allows you to query the Stacks 2.0 blockchain and interact with smart contracts. It was built to maintain pageable materialized views of the Stacks 2.0 Blockchain. - -:::tip API Documentation -Official API Documentation is available [here](https://stacks-network.github.io/stacks-blockchain/). -::: - -Note that the [Stacks Node RPC API](https://github.com/stacks-network/stacks-blockchain/) and the [Hiro Stacks API](https://www.hiro.so/stacks-api) are two different things. The Hiro API is a centralized service run by Hiro, a developer tooling company, that makes it easy to get onboarded and begin interacting with the Stacks blockchain in a RESTful way. You can also [run your own API server](https://docs.hiro.so/get-started/running-api-node) - -The Hiro Stacks API is a proxy for the Stacks Node API that makes it a bit easier to work with by providing additional functionality. - -The RPC API is generated by every Stacks node and allows developers to [self-host their own node and API](../nodes-and-miners/) for a more decentralized architecture. - -:::note -This documentation only covers endpoints that are exposed on a Stacks node, referred to as the RPC API. For full documentation on the RESTful API, check out the [Hiro's API reference](https://docs.hiro.so/api). -::: - -The RPC API can be used without any authorization. The basepath for the API is: - -```bash -# for mainnet, replace `testnet` with `mainnet` -https://stacks-node-api.testnet.stacks.co/ -``` - -## Proxied Stacks Node RPC API endpoints -The Stacks 2.0 Blockchain API (Hiro's API) is centrally hosted. However, every running Stacks node exposes an RPC API, which allows you to interact with the underlying blockchain. Instead of using a centrally hosted API, you can directly access the RPC API of a locally hosted Node. - -While the Node RPC API doesn't give the same functionality as the hosted Stacks 2.0 Blockchain API, you get similar functionality in a way that is scoped to that specific node. The RPC API includes the following endpoints: - -- [POST /v2/transactions](https://docs.hiro.so/api#operation/post_core_node_transactions) -- [GET /v2/contracts/interface/{contract_address}/{contract_name}](https://docs.hiro.so/api#operation/get_contract_interface) -- [POST /v2/map_entry/{contract_address}/{contract_name}/{map_name}](https://docs.hiro.so/api#operation/get_contract_data_map_entry) -- [GET /v2/contracts/source/{contract_address}/{contract_name}](https://docs.hiro.so/api#operation/get_contract_source) -- [GET /v2/accounts/{principal}](https://docs.hiro.so/api#operation/get_account_info) -- [POST /v2/contracts/call-read/{contract_address}/{contract_name}/{function_name}](https://docs.hiro.so/api#operation/call_read_only_function) -- [GET /v2/fees/transfer](https://docs.hiro.so/api#operation/get_fee_transfer) -- [GET /v2/info](https://docs.hiro.so/api#operation/get_core_api_info) - -:::caution -If you run a local node, it exposes an HTTP server on port `20443`. The info endpoint would be `localhost:20443/v2/info`. -::: diff --git a/docs/stacks-academy/technical-specs.md b/docs/stacks-academy/technical-specs.md deleted file mode 100644 index 6f9fe1599e..0000000000 --- a/docs/stacks-academy/technical-specs.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Technical Specifications -description: Summary of technical specifications of Stacks 2.0 -sidebar_position: 13 ---- - -## Consensus - -- Proof of Transfer (PoX) as described in [SIP-007](https://github.com/stacksgov/sips/blob/main/sips/sip-007/sip-007-stacking-consensus.md) -- Network will transition to Proof of Burn (PoB) as described in [SIP-001](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md) after 10 years. [Learn more about Proof-of-Burn in SIP-001](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md). -- Threat model - - 51% of malicious Stacks mining power can perform a double-spend attack - - 51% of malicious Bitcoin mining power can reorg the Stacks chain -- Different actors and their roles - - Stacks Miners package transactions into blocks, mine them through a Bitcoin transaction, propagate them, and if they win the block race, append microblocks to their winning block until the next block is mined. The next block confirms the microblock stream. - - Stacks Holders may alter the calculation of block limits (subject to a miner veto) and may vote to disable Proof-of-Transfer rewards for a reward cycle. -- Transactions are considered final when the corresponding "block commit" transaction on Bitcoin is finalized. Typically this can by 3-6 confirmations. -- For more details, see [Proof of Transfer](proof-of-transfer). - -## Proof of Transfer Mining - -- Coinbase reward schedule: - - 1000 STX/block for first 4 years - - 500 STX/block for following 4 years - - 250 STX/block for subsequent 4 years - - 125 STX/block in perpetuity after that -- Coinbase rewards accumulate for "missed sortitions": If a Bitcoin block has no sortition (at height N), then any Stacks block mined in a subsequent sortition that builds off of any Stacks chain tip that existed at the penultimate sortition (at height N-1) may claim its coinbase. This encourages miners to keep mining even if Bitcoin fees are high. -- Initial mining bonus: This is a special case of the above to incentivize early miners. Coinbase for all burnchain blocks between the first burn block height (to be chosen by independent miners as part of the Stacks 2.0 launch) and the first sortition winner accumulate and are distributed to miners over a fixed window (to be determined). For instance, say burn block height is 10,000 and first sortition is at block 10500 and distribution window is 100 blocks, then coinbase for the first 500 blocks (10,500 - 10,000) will be distributed evenly to miners who win sortition over the subsequent 100 blocks. -- 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 at least 11,000 satoshis (5,500 sats / [UTXO output](https://learnmeabitcoin.com/technical/utxo)); 2 outputs / block) to avoid "dust." -- For more details, see [Mining](mining). - -## Stacking - -- Stacking works in 2 phases - 1. Prepare phase: In this phase an "anchor block" is chosen. The qualifying set of addresses ("reward set") is determined based on the snapshot of the chain at the anchor block. Length of prepare phase is 100 blocks. Stacking commitments need to be confirmed before this phase starts - 2. Reward phase: In this phase miner BTC commitments are distributed amongst the reward set. Reward cycle length is 2000 BTC blocks (~2 weeks). -- 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/stacksgov/sips/blob/main/sips/sip-007/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.stacks.co/references/stacking-contract#delegate-stx). -- All 4 address types are supported: Legacy, SegWit, Native SegWit, and Taproot -- Further reading: [Stacking](stacking) - -## Accounts and Addresses - -- Transactions in the Stacks blockchain originate from, are paid for by, and execute under the authority of accounts -- An account is fully specified by its address + nonce + assets -- 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 (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](accounts) - -## Transactions - -- Transaction 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 - 2. _paying account_ is the account that is billed by the leader for the cost of validating and executing the transaction - 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 -- Transactions can be batched or streamed into blocks. The behavior can be controlled by the anchor mode of a transaction. With streaming ([microblocks](microblocks)), a faster confirmation time is possible. -- 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. -- Mempool limit for concurrent pending transactions is 25 per account -- Pending mempool transactions will be garbage-collected [256 blocks after receipt](https://github.com/stacks-network/stacks-blockchain/blob/master/src/core/mempool.rs#L62). With 10 minutes target block time, this would equal ~42 hours -- [Learn more about transaction encoding in SIP-005](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md#transaction-encoding) -- [Transaction signing and verification are described in SIP-005](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md#transaction-signing-and-verifying) -- All transactions impacting account balance are atomic, a transfer operation can not increment one account’s balance without decrementing another’s. However, transactions that perform multiple account actions (for example, transferring from multiple accounts) may partially complete. -- Transactions can include a memo string (max 34 bytes) - -## See also - -- [Read the full Stacks 2.0: Apps and Smart Contracts for Bitcoin whitepaper](https://cloudflare-ipfs.com/ipfs/QmaGgiVHymeDjAc3aF1AwyhiFFwN97pme5m536cHT4FsAW). - -- [Watch Aaron Blankstein video on Stacks whitepaper v2](https://www.youtube.com/watch?v=Wd-Bfe8Sn-Y). diff --git a/docs/stacks-academy/testnet.md b/docs/stacks-academy/testnet.md deleted file mode 100644 index da2e561fd1..0000000000 --- a/docs/stacks-academy/testnet.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Testnet -description: Test your smart contracts and apps -sidebar_position: 12 ---- - -## About testnet - -The testnet is a separate blockchain from the Stacks mainnet analogous to a staging environnement. It's a network used by developers to test their apps, smart contracts, or changes to the protocol in a production-like environment. - -It produces blocks at roughly the same rate as mainnet; about 1 block every 10 minutes on average. The Stacks testnet is rarely reset. - -### Faucets - -Testnet faucets provide you with free Stacks Token (STX) to test with. These are not the same as STX on mainnet and have no value. There are a couple of different options for getting testnet STX. - -#### Hiro - -You can get STX from the Hiro faucet on the [Hiro Explorer Sandbox](https://explorer.hiro.so/sandbox/faucet?chain=testnet), or using the [API](https://docs.hiro.so/api#tag/Faucets). - -To get STX tokens from within the Explorer Sandbox, navigate to the "Faucet" tab on the left and click "Request STX" button. - -![](/img/stx_faucet.png) - -You can also try out [Stacking](./stacking) by clicking on `I want to stack`. - -:::note -The Explorer Sandbox requires you to login with a Stacks wallet -::: - -#### LearnWeb3 - -Alternatively, you can use the [LearnWeb3 faucet](https://learnweb3.io/faucets). - -![Alt text](lw3-faucet.png) - -### Testnet API - -The hosted Stacks Blockchain API for the testnet is available at this base URL: - -```shell -https://stacks-node-api.testnet.stacks.co/ -``` - -![](/img/api_testnet_status.png) diff --git a/docs/stacks-academy/transactions.md b/docs/stacks-academy/transactions.md deleted file mode 100644 index 0cdc4d5deb..0000000000 --- a/docs/stacks-academy/transactions.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: Transactions -description: Guide to Stacks 2.0 transactions -sidebar_position: 9 ---- - -## Introduction - -Transactions are the fundamental unit of execution in the Stacks blockchain. Each transaction is originated from a [Stacks 2.0 account](accounts), and is retained in the Stacks blockchain history for eternity. This guide helps you understand Stacks 2.0 transactions. - -## Lifecycle - -Transactions go through phases before being finally confirmed, and available for all, on the Stacks 2.0 network. - -![Transaction lifecycle](/img/tx-lifecycle.png) - -- **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/en/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. - -:::note -A transaction can have one of three states once it is registered: `pending`, `success`, or `failed`. -::: - -## Types - -The Stacks 2.0 supports a set of different transaction types: - -| **Type** | **Value** | **Description** | -| ----------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Coinbase | `coinbase` | The first transaction in a new block (an entity holding several transactions). Used to register for block rewards. These are not manually generated and broadcasted like other types of transactions. | -| Token transfer | `token_transfer` | Asset transfer from a sender to a recipient | -| Contract deploy | `smart_contract` | Contract instantiation | -| Contract call | `contract_call` | Contract call for a public, non read-only function | -| Poison Microblock | `poison_microblock` | Punish leaders who intentionally equivocate about the microblocks they package | - -A sample of each transaction type can be found in the [Stacks Blockchain API response definition for transactions](https://docs.hiro.so/api#operation/get_transaction_by_id). - -:::caution -Read-only contract call calls do **not** require transactions. Read more about it in the [network guide](network#read-only-function-calls). -::: diff --git a/docs/stacks-academy/what-is-stacks.md b/docs/stacks-academy/what-is-stacks.md deleted file mode 100644 index abada2d864..0000000000 --- a/docs/stacks-academy/what-is-stacks.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: What is Stacks? -description: An introduction to Stacks -sidebar_position: 1 ---- - -# What is Stacks? - -We can get an idea of the goal and ethos behind Stacks by looking at [how Satoshi envisioned generalizing Bitcoin](https://satoshi.nakamotoinstitute.org/posts/bitcointalk/threads/244/#222) back in 2010: - -> "...to be a completely separate network and separate block chain, yet share CPU power with Bitcoin...all networks in the world would share combined CPU power, increasing the total strength." - -This is major theme in the design decisions for Stacks. A bit of a contradiction in the Bitcoin world, the Stacks network is a Bitcoin L2, but it does have its own token. - -This is an intentional and critical design decision primarily for the purpose of maintaining decentralization, rather than needing to rely on a federation. - -If that's confusing or you are skeptical, that's understandable, we'll be diving deeper into these ideas as we go through Stacks Academy. - -## Stacks and the Purpose of Blockchain Technology - -When evaluating new blockchain technologies, it's important to keep the original intent and purpose of them intact. If we go back to Bitcoin, it was originally designed to be: - -- Decentralized -- Immutable -- Secure - -You've likely heard of the blockchain trilemma, the problem of trying to balance the decentralization, scalability, and security of a blockchain network. - -Stacks takes the approach of solving this trilemma by separating out chains into layers. - -So at the bottom, you have the foundational layer: Bitcoin. - -Bitcoin is the most decentralized, most secure, and most immutable blockchain network. However, that comes with a few tradeoffs. - -Bitcoin is very slow compared to other networks. Bitcoin only has a new block written once every 10 minutes or so, making its throughput negligible compared to networks designed for speed like Solana. - -Bitcoin is also "boring". Ethereum came along after Bitcoin and sought to do the same thing for software that Bitcoin did for money. Ethereum's goal is to be a decentralized supercomputer of sorts, serving as a global compute environment for smart contracts (code that is written to a blockchain). - -Bitcoin is also not scalable. Because every new block must propagate to every node on the network, Bitcoin can only run as fast as the slowest node in the network. Now we are seeing the rise of modular blockchain networks like Cosmos that are designed to make it easy for people to spin up their own blockchain networks. - -While most new blockchain protocols popping up these days see these properties as negatives and seek to eliminate them, the Stacks community sees things differently. - -## The Stacks Way - -Stacks takes a pyramid approach, where you have the foundational settlement layer at the bottom (Bitcoin), and then a layer on top of that to add smart contracts and programmability (Stacks), and then layers on top of that for scalability and speed (Hiro's Subnets). - -Additionally, there are other layers on top of Bitcoin that serve different purpose and have their own mechanisms and philosophies like Lightning, RSK, and Liquid. - -By taking this layered approach, we are able to have all of the same functionality as chains like Ethereum without all of the drawbacks of having a massively complex chain. - -So Stacks is a Bitcoin layer 2 with some unique properties, like having its own token, that acts as an incentive mechanism to maintain a historical ledger of all of its transactions and operate with its own security budget. - -The only alternative to this model is a federated model like what Liquid uses. Stacks' design decisions operate under the idea that decentralization is more important than rejecting altcoins. - -This is one of the things that separates Stacks from other Bitcoin layers like Lightning. - -Lightning doesn't add any additional functionality to Bitcoin, it simply helps to scale functionality Bitcoin already has and help it operate faster. Lightning is also ephemeral, it has no permanent state that it keeps track of, and so is unsuitable for things like smart contracts that need to keep track of data and maintain state. - -Contrast this to Stacks, which adds additional functionality to Bitcoin but still ultimately settles down to Bitcoin (we'll cover this next in the section on Proof of Transfer). - -This is also what separates Stacks from L2 scaling solutions on Ethereum like Polygon or Arbitrum. The benefit we get here is that we can maintain a separation of concerns and keep Bitcoin simple and sturdy, chugging along producing blocks, and add additional layers for functionality and speed. But if those other layers were to be compromised, that would not affect the foundational layer at all. - -This is an important property when we are talking about building blockchains that are designed to be a global decentralized money (Bitcoin) and a decentralized economy built on top of that money (Stacks). - -![btc-stacks](/img/pox-why-bitcoin.png) - -_Sounds like a sidechain_. - -Not quite. We'll get into the technical details of how this works in the next section, but because Stacks records its entire history to Bitcoin, it is at least as hard to re-org the Stacks chain as it is Bitcoin. This is a key differentiator from side chains, which do not have their history recorded to their primary chain. - -Second, Stacks has its own token, it does not represent pegged Bitcoin. While this may ruffle some feathers among some people in the Bitcoin community, it has several advantages. - -First, rather than the security of the Stacks chain relying exclusively on system-specific measures the sidechain has implemented to incentivize validators to produce blocks honestly. - -What does that actually mean? By implementing a token into the Stacks chain, we provide additional economic incentive for miners to produce Stacks blocks honestly. - -This token provides additional incentive in the form of serving as a way to grow the chain. Rather than relying on altruism in order to produce blocks and grow the chain, we can incentivize builders, token-holders, and investors all at the same time by having a token. - -The ICO scams of 2017 put a bad taste in a lot of peoples' mouths, which has justifiably made a lot of people skeptical of every new blockchain project that pops up with a new token. - -But the problem with all of these projects is that they had no actual value, they weren't anchored to anything else of value and provided no real utility. - -With a project like Stacks, we have real utility in the sense of serving as a way to utilize Bitcoin and make it a productive asset **in a decentralized way.** This is a key point, Currently the only way to make Bitcoin productive (meaning use it to make more money) is by giving it to a custodial service or transferring it off the Bitcoin chain by way of something like wBTC on Ethereum. - -Stacks allows us to do this while ultimately still settling to the Bitcoin chain. - -In addition, Stacks allows us to build decentralized and censorship-resistant software utilizing Bitcoin as the foundational settlement layer. Eventually, the goal is to build a network of financial systems and decentralized software products that all utilize Bitcoin as their money. - -A caveat here, a lot of the functionality we've talked about here is still in the early stages, and the highest priority for the ecosystem at the moment is more tightly integrating Stacks with Bitcoin in order to easily use it with Stacks dapps. - -With that context, let's dive into some of the technical details of how Stacks operates, starting with Proof of Transfer. diff --git a/docs/stacks-academy/whitepapers.md b/docs/stacks-academy/whitepapers.md deleted file mode 100644 index 0e564fbf44..0000000000 --- a/docs/stacks-academy/whitepapers.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: Whitepapers -description: Documents detailing how different pieces of Stacks works -sidebar_position: 2 ---- - -In addition to the documentation here, there are numerous whitepapers detailing how the different pieces of the Stacks ecosystem work. - -- [Stacks 2.0](https://gaia.blockstack.org/hub/1AxyPunHHAHiEffXWESKfbvmBpGQv138Fp/stacks.pdf) -- [Stacks Nakamoto Release](https://assets.stacks.co/stacks.pdf) -- [Proof of Transfer](https://assets.website-files.com/5fcf9ac604d37418aa70a5ab/60072dbb32d416d6b3806935_5f1596b12bcc0800f3dcadcd_pox.pdf) -- [sBTC](https://assets.stacks.co/sbtc.pdf) diff --git a/docs/tutorials/clarinet-structure.png b/docs/tutorials/clarinet-structure.png deleted file mode 100644 index 8d16dc55cf..0000000000 Binary files a/docs/tutorials/clarinet-structure.png and /dev/null differ diff --git a/docs/tutorials/community-tutorials.md b/docs/tutorials/community-tutorials.md deleted file mode 100644 index a4f3d970ca..0000000000 --- a/docs/tutorials/community-tutorials.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Community Tutorials -description: Tutorials created by various people in the Stacks community ---- - -These tutorials have been created by various members of the Stacks community. Have a tutorial to suggest? View the [contribution guide](http://localhost:3000/docs/contribute/docs) to submit a PR with a new tutorial added. - -## Written Tutorials - -- [Create a server-side rendered Stacks app with Remix](https://micro-stacks.dev/guides/with-remix) -- [Build a Stacks app with Next.js](https://micro-stacks.dev/guides/with-nextjs) -- [Creating a Voting Contract](https://www.clearness.dev/01-voting-clarity-smart-contract/01-getting-started) -- [Building an NFT with Stacks and Clarity](https://blog.developerdao.com/building-an-nft-with-stacks-and-clarity) -- [Minting NFTs with QuickNode](https://www.quicknode.com/guides/web3-sdks/how-to-mint-nfts-on-the-stacks-blockchain) -- [Order Book Contract Walkthrough](https://byzantion.hiro.so/) -- [Build a DEX on Stacks](https://www.pointer.gg/tutorials/build-a-dex-with-stacks/56abb3a4-05c1-4608-b096-f82189e9f759) -- [NFT Tutorial](https://docs.hiro.so/tutorials/clarity-nft) -- [Billboard Tutorial](https://docs.hiro.so/tutorials/clarity-billboard) -- [Integrating NFTs Into a Game](https://gamefi-stacks.gitbook.io/gamefistacks/tutorials/integrate-nfts-into-game) -- [Building on Stacks](https://github.com/amoweolubusayo/stacks-clarinet-tutorial) - -## Video Tutorials - -- [Web3 for Bitcoin](https://www.crowdcast.io/e/web3-for-bitcoin/) diff --git a/docs/tutorials/event-log.png b/docs/tutorials/event-log.png deleted file mode 100644 index 51f04851f8..0000000000 Binary files a/docs/tutorials/event-log.png and /dev/null differ diff --git a/docs/tutorials/explorer-view.png b/docs/tutorials/explorer-view.png deleted file mode 100644 index 74a2042496..0000000000 Binary files a/docs/tutorials/explorer-view.png and /dev/null differ diff --git a/docs/tutorials/function-call.png b/docs/tutorials/function-call.png deleted file mode 100644 index 32a28b347a..0000000000 Binary files a/docs/tutorials/function-call.png and /dev/null differ diff --git a/docs/tutorials/hello-stacks.md b/docs/tutorials/hello-stacks.md deleted file mode 100644 index a0a442d135..0000000000 --- a/docs/tutorials/hello-stacks.md +++ /dev/null @@ -1,759 +0,0 @@ ---- -title: Hello Stacks (Quickstart) -description: A quick introduction to building dapps with Stacks -sidebar_position: 2 ---- - -# Hello Stacks (Quickstart Tutorial) - -Looking to see what building on Stacks is all about? You're in the right place. - -This tutorial is designed to take you from never having worked with Stacks before to a complete app in about an hour. - -You'll be introduced to all the main concepts and tools utilized to build Stacks dapps, with further resources to continue to learn. - -It does assume a basic familiarity with blockchain and smart contract technology. If you need an intro to those things, we recommend Codecademy's [Intro to Blockchain and Crypto](https://www.codecademy.com/learn/introduction-to-blockchain-and-crypto) course to get up to speed. - -Let's get started. - -## What We're Building - -We're going to be building a very simple practice application called Hello Stacks. Hello Stacks allows users to post a message to the Stacks blockchain and automatically generates a link for others to view that message. - -Here's a brief overview video of what it looks like. - -We'll be utilizing various tools throughout this tutorial, most of which you don't need to have prior experience with. - -It will be helpful, however, for you to be familiar with JavaScript and React to be able to most effectively follow along, as that's what we're going to be using to build the frontend, along with [Vite](https://vitejs.dev/). - -You can either follow along from scratch starting in the next section, or you can download the [starter repo](https://github.com/kenrogers/hello-stacks/tree/starter-branch) with all of the dependencies already set up on GitHub. - -You can also view the finished code in the `master` branch of that same repo. - -Let's get started by getting everything set up. - -## Wallet Setup - -The very first thing you'll need to do is set up the Hiro wallet extension. This is how you can get STX tokens and interact with Stacks dapps. All you need to do right now is visit Hiro's [wallet page](https://wallet.hiro.so/) and install it. We'll set it up later with our dev environment. - -## Code Setup - -If you want to use the starter repo, you can clone that, run `yarn` and move on to the next section, titled '[Writing Our Smart Contract](#writing-our-smart-contract)'. - -Otherwise, follow along if you want to start from scratch. If you are brand new to Stacks and are not familiar with the tooling ecosystem like Clarinet, Stacks.js, etc. I highly recommend following along to get everything set up on your own. - -:::tip -Hiro also has a set of [Stacks.js starters](https://docs.hiro.so/stacksjs-starters) that you can use to quickly get up and running with a new Stacks project. We won't be using them here, but they are an excellent resource. -::: - -The first thing we need to do is scaffold a new project with Vite, the frontend build tool we'll be using. - -We're going to be using [Yarn](https://yarnpkg.com/), but you can also use NPM if you prefer. I'm using Yarn version `1.22.19` for this project and running Node version 18.7.0. You'll need to have both of those installed to follow along. I'm also working on a Mac, but will provide alternative installation instructions for tools like Clarinet as we go. - -:::tip -We recommend [installing and using NVM](https://github.com/nvm-sh/nvm) in order to install Node and easily switch versions. -::: - -We'll have two separate directories for our project, one to handle the smart contracts and one to handle the frontend. Let's start by creating that and changing into it. - -```bash -mkdir hello-stacks && cd hello-stacks -``` - -Then get our frontend scaffolded. - -```bash -yarn create vite frontend --template react -``` - -Next we are going to install Clarinet. Clarinet is a development environment for Stacks created by Hiro. It allows us to set up a local Stacks chain, easily work with Clarity smart contracts (covered next), deploy our contracts, and test them. You can think of it as similar to Hardhat in the Ethereum world. - -Installation instructions vary depending on your system, so I'll refer you to the [Clarinet documentation](https://github.com/hirosystems/clarinet) to get that installed, then come back here to set up our project. - -Still inside the `hello-stacks` directory, let's get our Stacks folder created with the following command. You can name this whatever you want, but I like the frontend/contracts convention. - -```bash -clarinet new contracts -``` - -After this, you should have a `contracts` directory in your project that looks like this. - -![Clarinet directory structure](./clarinet-structure.png) - -There's not much here yet, we'll be creating our contracts in the next section. You'll also see a folder for tests, which are not covered in this tutorial. - -:::note -Some people don't like the `contracts/contracts` structure that results from this naming convention. It's a matter of personal preference what you want to name this top-level folder when you create the Clarinet project. -::: - -Finally, there is a directory called `settings` which contains a few configuration files for how we can interact with each chain. We are primarily concerned with `Devnet.toml` here, as this is how we can set up our local Stacks node for testing purposes. The others mainly come into play when we deploy. - -The `Clarinet.toml` file also provides some configuration options for our smart contracts and Clarinet will add our contracts here when we create them. - -:::tip -Hiro has created an excellent [Clarinet 101](https://www.youtube.com/playlist?list=PL5Ujm489LoJaAz9kUJm8lYUWdGJ2AnQTb) series on YouTube for getting up to speed on everything Clarinet has to offer. -::: - -Now we need to install some dependencies for working with Stacks and for styling so our app looks halfway decent. I'm a big fan of Tailwind, so we'll be utilizing that in this tutorial. - -Let's get Tailwind installed. We'll need some additional packages from Stacks.js as well, but we'll install those as we go. First make sure you are in the `frontend` directory and install the necessary dependencies for Tailwind. - -```bash -yarn add -D tailwindcss postcss autoprefixer -``` - -and initialize it with - -```bash -npx tailwindcss init -p -``` - -Now we need to tell Tailwind where our content is coming from and change out processing mode to "Just-In-Time" by modifying the `tailwind.config.js` file to look like this. - -```js -/** @type {import('tailwindcss').Config} */ -module.exports = { - mode: "jit", - content: ["./index.html", "./src/**/*.{js,ts,jsx,tsx}"], - theme: { - extend: {}, - }, - plugins: [], -}; -``` - -Add the Tailwind directives to the `index.css` file. - -```css -@tailwind base; -@tailwind components; -@tailwind utilities; -``` - -Now we need to modify our `App.jsx` file to make sure Tailwind is working. - -```js -function App() { - return ( -
-

Hello Stacks

-
- ); -} - -export default App; -``` - -You can also delete the `App.css` file. - -Now run `yarn dev` and make sure everything is working. Your screen should look like this. - -![Initial app screen](./initial-screen.png) - -Awesome! We have our set up out of the way, now we can start actually coding. We're going to start with our smart contract and learn a bit about Clarity in the process. - -## Writing Our Smart Contract - -Clarity is a smart contract language that has been purpose-built to help developers write safe, secure smart contracts. - -It took a lot of the lessons learned from the Solidity hacks over the years and used them to create something much more secure and safe. - -Stacks smart contracts are written using Clarity and live on the Stacks chain. For a comprehensive introduction to writing Clarity contracts, I highly recommend the book, [Clarity of Mind](https://book.clarity-lang.org/). We'll go over the basics here as we write a simple smart contract, but we are only scratching the surface. - -Before we do that, take a minute to familiarize yourself with what makes Clarity unique and why you might want to build on it by reading just the [Introduction chapter](https://book.clarity-lang.org/ch00-00-introduction.html) of Clarity of Mind. - -Now that you understand why Clarity is useful, let's get started writing our first contract and go over some Clarity concepts along the way. - -The first thing we need to do is generate our new smart contract with Clarinet. Make sure you are in the top level `contracts` folder and generate that. - -```bash -clarinet contract new hello-stacks -``` - -That created a few things for us. First, it created a `hello-stacks_test.ts` file in the `tests` directory. This is how we can use Clarinet to test our smart contracts. We won't cover that here, but you can check out the [TDD with Clarinet](https://dev.to/stacks/test-driven-stacks-development-with-clarinet-2e4i) tutorial for more information on that. - -It also created our actual Clarity file, `hello-stacks.clar` inside the inner `contracts` directory. This is where we'll actually write our smart contract. - -:::tip -If you use VS Code, be sure to install the [Clarity Extension](https://marketplace.visualstudio.com/items?itemName=HiroSystems.clarity-lsp#:~:text=Clarity%20is%20a%20decidable%20Smart,safety%20checks%2C%20debugger%20and%20more.) for a more enjoyable Clarity developer experience. -::: - -If you open up the `Clarinet.toml` file, you'll also see that Clarinet added our new contract there. - -Now let's open up that `hello-stacks.clar` file and get writing our contract. - -You'll see that it set up a bit of a template we can use, with each section commented out. This is a good introduction to some of the common data structures and functions we'll be using in a Clarity contract. - -But we can delete it for now as we'll be writing our own and covering what each does along the way. - -Let's look at the very basic completed Clarity smart contract, then we'll go over what each line does. - -``` -(define-public (write-message (message (string-utf8 500))) - (begin - (print message) - (ok "Message printed") - ) -) -``` - -All we are doing here is defining a new public function called `write-message`. Public means that we can call this function from anywhere, as opposed to private, which would mean only this contract could call it. - -Whenever we call this function, we need to pass it a `message` which is a UTF8 string with a maximum of 500 characters. - -Next we see a block called `begin`. In Clarity, everything is a list inside of a list, so in this function definition, what we are really doing is calling the `define-public` function and passing it to arguments. - -The first is the function signature, which contains the name and the arguments. - -The second argument is the body of the function, but this can only contain a single expression. By wrapping our function body in a `begin` block, we can pass a multi-step function as a single expression. - -Again, there is much more information on how Clarity works in the [Clarity Book](https://book.clarity-lang.org/), this is just a high-level introduction to get you familiar. - -Within this `begin` block we are doing two things. First we are bringing the contents of our message to the blockchain, this will actually post the contents of this message to the chain when we send this transaction, something we'll look at soon. - -Then we are returning a response of `ok`, indicating success, with the message "Message printed". - -Clarity requires return values in all functions. In more complex functions, we would return either a success or error message depending on what action was taken and other logic. - -We can test this right now using the Clarinet console. In the `contracts` folder, run `clarinet console` to open it up and write the following: - -```bash -(contract-call? .hello-stacks write-message u"Hello there") -``` - -Here we are calling the function we just created and passing a message of "Hello there". We prefix that with a `u` to indicate this is a UTF8 string. - -You should get an `ok` message returned here, which indicates that our function was called successfully. - -## Running a Local Stacks Devnet - -One of the coolest features of Clarinet is that it allows us to set up an entire mock Stacks network on our local machine for testing. - -This comes complete with a local block explorer and sandbox environment so we can further test our contracts. - -Make sure you have Docker installed and running, exit out of console with `CMD/CTRL + C` and run `clarinet integrate`. - -It will take a few minutes to get up and running, but then we can open up our local Stacks block explorer. - -:::note -You can [view the live Stacks block explorer](https://explorer.stacks.co/?chain=mainnet) and switch between mainnet and testnet to get familiar with it. -::: - -Once it finishes, visit the local block explorer at `localhost:8000`. You'll be able to see blocks as they are created and also see your `hello-stacks` contract deployment. - -Click on that and copy the contract name, we'll need it for the next step. - -![Explorer view](./explorer-view.png) - -Now go ahead and visit the sandbox by clicking on the 'Sandbox' link up at the top. You'll need to connect with your wallet to use it, but we can also interact with our contract here. - -Be sure to change your network to `Devnet` in your Hiro wallet, then connect. - -:::caution -If you run into funky rendering issues, be sure to change the network URL parameter in the address bar to `testnet`. -::: - -Click on the little function symbol on the left and take the contract name you copied and paste it in the top field there, the name should be automatically populated. - -Hit 'Get Contract' and you should see the function we created there. - -![Loaded hello-stacks contract](./loaded-contract.png) - -Now we can click on that and type in a message to call the function. But if you try to do that now, you might get an error saying you don't have enough STX. - -How do we get STX tokens in our Devnet account? Remember that `Devnet.toml` file Clarinet generates? That determines what accounts have what tokens. - -So now we need to set up our Hiro wallet extension that we set up at the beginning of this tutorial. If you already have an existing Hiro wallet, you'll need to sign out in order to use it with the local Clarinet Devnet. - -:::warning -Make sure you copy your secret key before you sign out. You'll need it to restore your Hiro wallet when you are done developing. -::: - -Go ahead and copy the mnemonic listed in the `Devnet.toml` file and use that to import your local wallet into the Hiro wallet. Then we can use that for interacting with our local Devnet chain. - -Once you do that, go ahead and restart `clarinet integrate`. - -Now we can go back to the sandbox and call that function. You might need to sign out of the sandbox first and reauthenticate. - -When we do, you'll see the Hiro wallet pop up with a transaction confirmation. You'll also see a little notice at the top that no transfers besides fees will occur. - -This is a cool feature of Stacks called Post Conditions. They are outside the scope of this tutorial, but you can learn more about them in the [Understanding Stacks Post Conditions](https://dev.to/stacks/understanding-stacks-post-conditions-e65) tutorial. They are another safety feature to help protect users. - -Now we can go back to the 'Transactions' page, click on this transaction, and see the data that was written to the chain. - -Here you can see a lot of information about the transaction, including the fact that a print event was detected, and what content was printed. - -![Print event log](./event-log.png) - -Let's get our frontend set up so we can see how to do this with a UI and also read this information from the chain. - -## Adding a UI - -For this tutorial, we'll be using [Stacks.js](https://www.hiro.so/stacks-js), a JS library from Hiro that helps us interact with the Stacks chain, our Hiro wallet, and our contracts. Another option is [Micro-Stacks](https://micro-stacks.dev/), a community-created resource. - -Since this is not a React tutorial, I'm going to give you all the boilerplate at once so you can just copy and paste this into `App.jsx` and we'll add the Stacks-specific stuff together. - -```jsx -import { useState } from "react"; - -function App() { - const [message, setMessage] = useState(""); - const [transactionId, setTransactionId] = useState(""); - const [currentMessage, setCurrentMessage] = useState(""); - - const connectWallet = () => { - // implement code - }; - - const handleMessageChange = (e) => { - setMessage(e.target.value); - }; - - const submitMessage = () => { - // submit transaction - }; - - const handleTransactionChange = (e) => { - setTransactionId(e.target.value); - }; - - const retrieveMessage = () => { - // submit transaction - }; - - return ( -
- -

Hello Stacks

-
- - -
-
- - -
- {currentMessage.length > 0 ? ( -

{currentMessage}

- ) : ( - "" - )} -
- ); -} - -export default App; -``` - -We've got a very basic React application set up here that will allow us to add a new message to the Stacks chain and also find the content of a message by entering the transaction ID where the message was posted. - -The first thing we need to do is implement the 'Connect Wallet' functionality. - -In order to do that, we need to add the [`@stacks/connect`](https://github.com/hirosystems/connect/tree/main/packages/connect) package with - -```bash -yarn add @stacks/connect -``` - -:::note -Some users get an error about the `regenerator-runtime` dependency being missing. If that's the case, running `yarn add regenerator-runtime` should fix the issue. -::: - -And import a couple things from it at the top of our `App.jsx` file. - -```jsx -import { - AppConfig, - UserSession, - AuthDetails, - showConnect, -} from "@stacks/connect"; -``` - -Now let's use `AppConfig` which is charge of setting some config options for the wallet to read and `UserSession`, which will actually handle the wallet authentication. - -Below the state declarations, add the following. - -```jsx -const appConfig = new AppConfig(["store_write"]); -const userSession = new UserSession({ appConfig }); -``` - -Here we are setting up an app that needs permission to store and write data to the Stacks chain, and we are instantiating a new user session with that config option passed in. - -We also need to add a few details for the Hiro wallet to display to people interacting with our app. We can do that with the following line: - -```jsx -const appDetails = { - name: "Hello Stacks", - icon: "https://freesvg.org/img/1541103084.png", -}; -``` - -We'll use this when we set up the connect function, which we can do right now in the `connectWallet` function. - -```jsx -const connectWallet = () => { - showConnect({ - appDetails, - onFinish: () => window.location.reload(), - userSession, - }); -}; -``` - -Here we are using the `showConnect` function to actually trigger the Hiro wallet to show up, allowing the user to authenticate. From there we are triggering a page refresh when the authentication finishes and setting the `userSession` variable, which handles the data for our logged in user. - -At this point you should be able to authenticate with the wallet and have the page refresh, although we can't really do anything with that yet. - -First we need to get our app to be able to read that data. - -We'll add another state variable for our `userData`. - -```jsx -const [userData, setUserData] = useState(undefined); -``` - -And we will also add a `useEffect` call to set this data on page load. - -```jsx -useEffect(() => { - if (userSession.isSignInPending()) { - userSession.handlePendingSignIn().then((userData) => { - setUserData(userData); - }); - } else if (userSession.isUserSignedIn()) { - setUserData(userSession.loadUserData()); - } -}, []); - -console.log(userData); -``` - -Now we have access to our authenticated user data, but we need to actually utilize it in our UI. - -The first thing we'll do is hide the 'Connect Wallet' button if there is currently an authenticated user. Change the code that renders our button to the following. - -```jsx -{ - !userData && ( - - ); -} -``` - -We also want to hide the form to submit a message if we are not authenticated. - -```jsx -{ - userData && ( -
- - -
- ); -} -``` - -Alright, now we need to actually implement the functionality that will call our `hello-stacks` contract. To do that, we need to use Stacks.js to send a transaction, we'll do that in the `submitMessage` function. - -First we need to install a couple more packages. - -```bash -yarn add @stacks/transactions @stacks/network -``` - -And import a couple things from those at the top. - -```jsx -import { - AppConfig, - UserSession, - showConnect, - openContractCall, -} from "@stacks/connect"; -import { StacksMocknet } from "@stacks/network"; -import { stringUtf8CV } from "@stacks/transactions"; -``` - -We're importing the network we'll be calling the transaction on and a utility helper from the `transactions` package that will help to encode our data in a format that the Clarity contract can understand. - -Now we need to add a new constant to hold the network that we are using. In our case we want to be using `Mocknet`, which we can add using the following right under our current state declarations. - -```jsx -const network = new StacksMocknet(); -``` - -And finally we can add the code to initiate the transaction. - -```jsx -const submitMessage = async (e) => { - e.preventDefault(); - - const network = new StacksMocknet(); - - const options = { - contractAddress: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM", - contractName: "hello-stacks", - functionName: "write-message", - functionArgs: [stringUtf8CV(message)], - network, - appDetails, - onFinish: ({ txId }) => console.log(txId), - }; - - await openContractCall(options); -}; -``` - -What we are doing here is calling our contract (I got the address from the local block explorer) using the `openContractCall` function and passing in some options. - -The contract information, the function we want to call, our function arguments, the network, the app details from earlier, and an action we want to take when we finish calling. - -Note that all values passed to Clarity contracts need to be converted like this. You can see what all the various options are for doing so on the [GitHub page](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions#constructing-clarity-values). - -And if you type a message and hit the submit button, you should see the transaction initiation window pop up. - -![transaction init](./tx-call.png) - -Here's our current `App.jsx` file in its entirety. - -```jsx -import { useEffect, useState } from "react"; -import { - AppConfig, - UserSession, - showConnect, - openContractCall, -} from "@stacks/connect"; -import { StacksMocknet } from "@stacks/network"; -import { stringUtf8CV } from "@stacks/transactions"; - -function App() { - const [message, setMessage] = useState(""); - const [transactionId, setTransactionId] = useState(""); - const [currentMessage, setCurrentMessage] = useState(""); - const [userData, setUserData] = useState(undefined); - - const appConfig = new AppConfig(["store_write"]); - const userSession = new UserSession({ appConfig }); - const appDetails = { - name: "Hello Stacks", - icon: "https://freesvg.org/img/1541103084.png", - }; - - useEffect(() => { - if (userSession.isSignInPending()) { - userSession.handlePendingSignIn().then((userData) => { - setUserData(userData); - }); - } else if (userSession.isUserSignedIn()) { - setUserData(userSession.loadUserData()); - } - }, []); - - console.log(userData); - - const connectWallet = () => { - showConnect({ - appDetails, - onFinish: () => window.location.reload(), - userSession, - }); - }; - - const handleMessageChange = (e) => { - setMessage(e.target.value); - }; - - const submitMessage = async (e) => { - e.preventDefault(); - - const network = new StacksMocknet(); - - const options = { - contractAddress: "ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM", - contractName: "hello-stacks", - functionName: "write-message", - functionArgs: [stringUtf8CV(message)], - network, - appDetails, - onFinish: ({ txId }) => console.log(txId), - }; - - await openContractCall(options); - }; - - const handleTransactionChange = (e) => { - setTransactionId(e.target.value); - }; - - const retrieveMessage = () => { - // submit transaction - }; - - return ( -
- {!userData && ( - - )} -

Hello Stacks

- {userData && ( -
- - -
- )} -
- - -
- {currentMessage.length > 0 ? ( -

{currentMessage}

- ) : ( - "" - )} -
- ); -} - -export default App; -``` - -If you click 'Confirm' you should see the transaction id logged in the console and you can see the transaction in the block explorer. - -![new transaction](./tx-proof.png) - -## Retrieving Messages - -Now that we can write a message to the chain, we also want to add functionality so that we can retrieve a message from the chain. - -We'll do that by having users enter in a transaction ID and we'll query the chain for that transaction and the event data associated with it. - -The Stacks API is perfect for this, and we can query our local devnet chain directly. - -Let's set that up in our `retrieveMessage` function. - -```jsx -const retrieveMessage = async () => { - const retrievedMessage = await fetch( - "http://localhost:3999/extended/v1/tx/events?" + - new URLSearchParams({ - tx_id: transactionId, - }) - ); - const responseJson = await retrievedMessage.json(); - setCurrentMessage(responseJson.events[0].contract_log.value.repr); -}; -``` - -Here we are using `fetch` to call the Stacks API and passing our transaction as a query parameter to get the events and then digging down through that returned data to get the printed message. - -You can view the documentation for this specific API call on [Hiro's website](https://docs.hiro.so/api#tag/Transactions/operation/get_filtered_events). - -If you run this you should see the message printed at the bottom of the screen. - -## Wrapping Up and Next Steps - -Here we've just gone over a very simple and very brief example of a Stacks application. This was meant to give you a high level introduction to the Stacks ecosystem and how you might begin building Stacks dapps. - -There is obviously a lot more to learn, so here are a few good places to continue your learning. - -### Stacks Academy - -Stacks Academy is your guide to all things Stacks. This comprehensive walkthrough will cover key concepts about Stacks so you can learn everything you need to know about how it works. - -[View Stacks Academy](../stacks-academy/) - -### Clarity Book - -The Clarity Book, Clarity of Mind, is the go-to resource for mastering Clarity. It will teach you Clarity development from start to finish so you can begin writing high-quality Clarity smart contracts. - -[Read the Clarity Book](https://book.clarity-lang.org/) - -### Clarity Universe - -Prefer a more immersive experience? Clarity Universe is a start-to-finish guide to learning Clarity, with self-paced option and a guided cohort-based option. - -[Enroll in Clarity Universe](https://clarity-lang.org/universe) - -### Community Tutorials - -There is an ever-growing list of tutorials created by members of the Stacks community so you can learn how to accomplish different tasks and build useful things with Stacks. - -[View Community Tutorials](../tutorials/community-tutorials.md) - -### Next Steps - -Looking to get paid to build something awesome with Stacks? Be sure to see all the different opportunities available to you like full-time jobs, grants, the startup accelerator, and more. - -[Next Steps](../next-steps/) - -### Get Involved - -Finally, be sure to get involved in the Stacks community by [joining Discord](https://discord.gg/5DJaBrf) and [checking out the website](https://stacks.co) to learn more about Stacks. diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md deleted file mode 100644 index 1d544c7bc1..0000000000 --- a/docs/tutorials/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Tutorials -description: Step-by-step tutorials to learn Stacks development -sidebar_position: 2 ---- - -Looking to learn Stacks development? You're in the right place. - -The quickstart tutorial, Hello Stacks, is designed to give you a quick introduction to Stacks development, which will take about an hour to go through. There is also a comprehensive full-stack tutorial in the works to demonstrate how to build a production-ready dapp using Stacks, complete with integration with BTC. - -You can also view the [Community Tutorials](./community-tutorials) page for a list of community-created tutorials organized by topic. diff --git a/docs/tutorials/initial-screen.png b/docs/tutorials/initial-screen.png deleted file mode 100644 index 222c5c517d..0000000000 Binary files a/docs/tutorials/initial-screen.png and /dev/null differ diff --git a/docs/tutorials/loaded-contract.png b/docs/tutorials/loaded-contract.png deleted file mode 100644 index 95a182977d..0000000000 Binary files a/docs/tutorials/loaded-contract.png and /dev/null differ diff --git a/docs/tutorials/satoshis-ridge.md b/docs/tutorials/satoshis-ridge.md deleted file mode 100644 index 0c72f41b88..0000000000 --- a/docs/tutorials/satoshis-ridge.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Satoshi's Ridge (Deep Dive) -description: A comprehensive overview of building useful Stacks dapps -sidebar_position: 2 -draft: true ---- - -# Satoshi's Ridge (Deep Dive) - -Alright so you've taken the [quickstart tutorial](./hello-stacks.md) and know how to get started building on Stacks. Maybe you've read a bit of [Stacks Academy](../stacks-academy/) and understand why Stacks is unique ad what benefits it provides. - -Now you want to know how to actually build real-world Bitcoin-first dapps using Stacks as the underlying programming layer. - -You're in the right place. - -This comprehensive tutorial is designed to teach you everything you need to know about building Bitcoin dapps. We'll be introducing all the important tools and concepts with links out to additional resources for you to dive deeper into what you need. - -We'll be covering: - -- TDD with Clarity and Clarinet -- Writing robust, secure Clarity contracts -- Utilizing Bitcoin in our Stacks dapp -- Creating a smooth, enjoyable frontend with Remix and Micro-Stacks -- Utilizing oracle data with Redstone -- Off-chain data storage -- Self-hosting our own Stacks node -- Deploying our app to Fly.io -- Deploying our contracts to Stacks testnet with Clarinet -- Potential improvements to make - -Let's do this. - -## Prerequisites - -We won't be covering Bitcoin programming in this tutorial. If you are familiar with the technical aspects of how Bitcoin works (public/private keys, derivation paths, transactions, etc.), we highly recommend giving [Learn Me a Bitcoin](https://learnmeabitcoin.com/) a read. it will arm you with all of the knowledge you'll need to be successful here. - -While you won't need to do any actual Bitcoin programming, it will be very helpful to know how Bitcoin works under the hood to know why we are doing some of the things we are doing here. - -## What is a Bitcoin Dapp? - -The ultimate goal of Stacks is to unlock Bitcoin's potential as latent capital and bring the same functionality as Ethereum has to Bitcoin. But there is a key difference between the two. We can't do that by changing Bitcoin itself. Bitcoin's simplicity and resistance to change may make it more difficult to build on top of, but it is arguably one of its strengths. - -Instead, we need to create separate layers that add additional functionality without modifying Bitcoin itself. Stacks is one such layer. The grand vision of Stacks is to serve as a programming layer for Bitcoin, being completely invisible to the end user in many cases. That is the kind of dapp we'll be building here. - -In order to dive deeper into how we actually go about doing that, check out the [BTC Connection](../stacks-academy/btc-connection.md) section of the docs. - -## What We're Building - -We're going to be building Satoshi's Ridge, a platform for creating a Bitcoin-based mini-society a la Balaji's [Network State](https://thenetworkstate.com/). If you aren't familiar with The Network State, don't worry. We're basically building a platform that enables us to create a decentralized organization and mini-economy based around Bitcoin. - -In The Network State, one of the key ideas is that a network state should have a singular unifying focus. In the case of Satoshi's Ridge, the unifying focus is that of voluntary regulation. - -So the primary goal of Satoshi's Ridge is to create a small network state whose focus is on conceiving of and building voluntary regulation systems. - -What do we mean by voluntary regulation? Let's look at the FDA as an example. The FDA is an example of centralized, involuntary regulation. Medical products cannot be sold without FDA approval (theoretically, but that's another matter) and there is no alternative to getting FDA approval. - -Centralized, involuntary regulation schemes like this are ripe for corruption, because they provide a prime opportunity for corporate interests to influence this centralized entity. - -As an alternative, a decentralized system of various voluntary regulatory agencies would allow consumers to purchase products based on the regulatory organizations they trust to evaluate things effectively. - -Furthermore, by structuring this system as a DAO where members are the ones funding the organization, we significantly reduce the risk of corruption. - -Obviously this is just a tutorial for learning purposes, and there are complex layers of philosophy, politics, economics, and incentive mechanisms at the heart of this, and people will debate about the merits of such systems. - -That is not the point of this tutorial, but only to highlight one of the potential use cases for blockchain technology, and more specifically, Stacks and Bitcoin. - -These types of systemic changes are where blockchains potential really shines. And by using the world's best money, Bitcoin, as the bedrock of this system, we are building it on a solid foundation. - -Bitcoin is an incredible invention, and it generally fixes many of the issues caused by traditional monetary and banking systems, but it doesn't fix human nature. - -If our institutions are still centralized and prone to corruption, Bitcoin only changes the funding source. We need to take the same concepts of decentralization that make Bitcoin so powerful and apply them to our institutions as well, with Bitcoin serving as the economic base layer. - -That's the power of Stacks, and is what we'll be exploring in this deep dive. - -Let's get started building. diff --git a/docs/tutorials/tx-call.png b/docs/tutorials/tx-call.png deleted file mode 100644 index e376f24ef1..0000000000 Binary files a/docs/tutorials/tx-call.png and /dev/null differ diff --git a/docs/tutorials/tx-proof.png b/docs/tutorials/tx-proof.png deleted file mode 100644 index 0bd0a0525f..0000000000 Binary files a/docs/tutorials/tx-proof.png and /dev/null differ diff --git a/i18n/de/docusaurus-plugin-content-docs/current/blockchain/index.md b/i18n/de/docusaurus-plugin-content-docs/current/blockchain/index.md deleted file mode 100644 index 13db24ec30..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/blockchain/index.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: Blockchain -description: Stacks Blockchain -sidebar_position: 6 ---- - -Below is a guide to start working locally with the Stacks Blockchain. - -Code repository is [here](https://github.com/stacks-network/stacks-blockchain). - -## Getting started with the Stacks Blockchain - -### Download and build stacks-blockchain - -The first step is to ensure that you have Rust and the support software installed. - -```bash -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -``` - -:::info -For building on Windows, follow the rustup installer instructions at https://rustup.rs/ -::: - -From there, you can clone the Stacks Blockchain repository: - -```bash -git clone --depth=1 https://github.com/stacks-network/stacks-blockchain.git - -cd stacks-blockchain -``` - -Then build the project: - -```bash -cargo build -``` - -Run the tests: - -```bash -cargo test testnet -- --test-threads=1 -``` - -### Encode and sign transactions - -Here, we have generated a keypair that will be used for signing the upcoming transactions: - -```bash -cargo run --bin blockstack-cli generate-sk --testnet - -# Output -# { -# secretKey: "b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001", -# publicKey: "02781d2d3a545afdb7f6013a8241b9e400475397516a0d0f76863c6742210539b5", -# stacksAddress: "ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH" -# } -``` - -This keypair is already registered in the `testnet-follower-conf.toml` file, so it can be used as presented here. - -We will interact with the following simple contract `kv-store`. In our examples, we will assume this contract is saved to `./kv-store.clar`: - -```scheme -(define-map store { key: (string-ascii 32) } { value: (string-ascii 32) }) - -(define-public (get-value (key (string-ascii 32))) - (match (map-get? store { key: key }) - entry (ok (get value entry)) - (err 0))) - -(define-public (set-value (key (string-ascii 32)) (value (string-ascii 32))) - (begin - (map-set store { key: key } { value: value }) - (ok true))) -``` - -We want to publish this contract on chain, then issue some transactions that interact with it by setting some keys and getting some values, so we can observe read and writes. - -Our first step is to generate and sign, using your private key, the transaction that will publish the contract `kv-store`. To do that, we will use the subcommand `blockstack-cli` that has the following usage: - -```bash -blockstack-cli (options) publish [publisher-secret-key-hex] [fee-rate] [nonce] [contract-name] [file-name.clar] -``` - -With the following arguments: - -```bash -cargo run --bin blockstack-cli publish b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 515 0 kv-store ./kv-store.clar --testnet -``` - -The `515` is the transaction fee, denominated in microSTX. Right now, the testnet requires one microSTX per byte minimum, and this transaction should be less than 515 bytes. The third argument `0` is a nonce, that must be increased monotonically with each new transaction. - -This command will output the **binary format** of the transaction. In our case, we want to pipe this output and dump it to a file that will be used later in this tutorial. - -```bash -cargo run --bin blockstack-cli publish b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 515 0 kv-store ./kv-store.clar --testnet | xxd -r -p > tx1.bin -``` - -### Run the testnet - -You can observe the state machine in action locally by running: - -```bash -cargo stacks-node start --config=./testnet/stacks-node/conf/testnet-follower-conf.toml -``` - -`testnet-follower-conf.toml` is a configuration file that you can use for setting genesis balances or configuring Event observers. You can grant an address an initial account balance by adding the following entries: - -``` -[[ustx_balance]] -address = "ST2VHM28V9E5QCRD6C73215KAPSBKQGPWTEE5CMQT" -amount = 100000000 -``` - -The `address` field is the Stacks testnet address, and the `amount` field is the number of microSTX to grant to it in the genesis block. The addresses of the private keys used in the tutorial below are already added. - -### Publish your contract - -Assuming that the testnet is running, we can publish our `kv-store` contract. - -In another terminal (or file explorer), you can move the `tx1.bin` generated earlier, to the mempool: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx1.bin http://localhost:20443/v2/transactions -``` - -In the terminal window running the testnet, you can observe the state machine's reactions. - -### Reading from / Writing to the contract - -Now that our contract has been published on chain, let's try to submit some read / write transactions. We will start by trying to read the value associated with the key `foo`. - -To do that, we will use the subcommand: - -```bash -cargo run --bin blockstack-cli contract-call --help -``` - -With the following arguments: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 1 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store get-value -e \"foo\" --testnet | xxd -r -p > tx2.bin -``` - -`contract-call` generates and signs a contract-call transaction. - -We can submit the transaction by moving it to the mempool path: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx2.bin http://localhost:20443/v2/transactions -``` - -Similarly, we can generate a transaction that would be setting the key `foo` to the value `bar`: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 2 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store set-value -e \"foo\" -e \"bar\" --testnet | xxd -r -p > tx3.bin -``` - -And submit it by moving it to the mempool path: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx3.bin http://localhost:20443/v2/transactions -``` - -Finally, we can issue a third transaction, reading the key `foo` again, for ensuring that the previous transaction has successfully updated the state machine: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 3 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store get-value -e \"foo\" --testnet | xxd -r -p > tx4.bin -``` - -And submit this last transaction by moving it to the mempool path: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx4.bin http://localhost:20443/v2/transactions -``` - -Congratulations, you can now [write your own smart contracts with Clarity](write-smart-contracts/). diff --git a/i18n/de/docusaurus-plugin-content-docs/current/blockchain/networks.md b/i18n/de/docusaurus-plugin-content-docs/current/blockchain/networks.md deleted file mode 100644 index fe9725352c..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/blockchain/networks.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Stacks Blockchain Networks -description: Stacks Blockchain Networks -sidebar_position: 3 ---- - -### Stacks Blockchain Networks - -- [x] **Krypton** is a Stacks 2 testnet with a fixed, two-minute block time, called `regtest`. Regtest is generally unstable for regular use, and is reset often. See the [regtest documentation](understand-stacks/testnet) for more information on using regtest. - -- [x] **Testnet** (old Xenon) is the Stacks 2 public testnet, which runs PoX against the Bitcoin testnet. It is the full implementation of the Stacks 2 blockchain, and should be considered a stable testnet for developing Clarity smart contracts. See the [testnet documentation](understand-stacks/testnet) for more information on the public testnet. - -- [x] **Mainnet** is the fully functional Stacks 2 blockchain, see the [Stacks overview](understand-stacks/) for information on running a Stacks node, mining, stacking, and writing Clarity smart contracts. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md b/i18n/de/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md deleted file mode 100644 index cf4f84a2da..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Stacks Blockchain API -description: Interacting with the Stacks 2.0 Blockchain via API -sidebar_position: 4 ---- - -## Introduction - -:::tip API Documentation Official API Documentation is available [here](https://stacks-network.github.io/stacks-blockchain/). ::: - - -The Stacks 2.0 Blockchain API allows you to query the Stacks 2.0 blockchain and interact with smart contracts. It was built to maintain pageable materialized views of the Stacks 2.0 Blockchain. - -:::caution The RESTful API is developed by Hiro. Hiro also hosts a public API node for easy onboarding. Using it requires you to trust the hosted server, but provides a faster onboarding experience. You can [run your own API server](https://docs.hiro.so/get-started/running-api-node) ::: - -The RESTful JSON API can be used without any authorization. The basepath for the API is: - -```bash -# for mainnet, replace `testnet` with `mainnet` -https://stacks-node-api.testnet.stacks.co/ -``` - -:::note This documentation only covers endpoints that are exposed on a Stacks node, referred to as the RPC API. For full documentation on the RESTful API, check out the [Hiro's API reference](https://docs.hiro.so/api). ::: - -### Stacks Node RPC API - -The [stacks-node implementation](https://github.com/stacks-network/stacks-blockchain/) exposes JSON RPC endpoints. - -All `/v2/` routes a proxied to a Hiro-hosted Stacks Node. For a trustless architecture, you should make these requests to a self-hosted node. - -## Proxied Stacks Node RPC API endpoints - -The Stacks 2.0 Blockchain API is centrally hosted. However, every running Stacks node exposes an RPC API, which allows you to interact with the underlying blockchain. Instead of using a centrally hosted API, you can directly access the RPC API of a locally hosted Node. - -:::tip -The Stacks Blockchain API proxies to Node RPC endpoints -::: - -While the Node RPC API doesn't give the same functionality as the hosted Stacks 2.0 Blockchain API, you get similar functionality in a way that is scoped to that specific node. The RPC API includes the following endpoints: - -- [POST /v2/transactions](https://docs.hiro.so/api#operation/post_core_node_transactions) -- [GET /v2/contracts/interface/{contract_address}/{contract_name}](https://docs.hiro.so/api#operation/get_contract_interface) -- [POST /v2/map_entry/{contract_address}/{contract_name}/{map_name}](https://docs.hiro.so/api#operation/get_contract_data_map_entry) -- [GET /v2/contracts/source/{contract_address}/{contract_name}](https://docs.hiro.so/api#operation/get_contract_source) -- [GET /v2/accounts/{principal}](https://docs.hiro.so/api#operation/get_account_info) -- [POST /v2/contracts/call-read/{contract_address}/{contract_name}/{function_name}](https://docs.hiro.so/api#operation/call_read_only_function) -- [GET /v2/fees/transfer](https://docs.hiro.so/api#operation/get_fee_transfer) -- [GET /v2/info](https://docs.hiro.so/api#operation/get_core_api_info) - -:::caution If you run a local node, it exposes an HTTP server on port `20443`. The info endpoint would be `localhost:20443/v2/info`. ::: diff --git a/i18n/de/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md b/i18n/de/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md deleted file mode 100644 index 71e3542302..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Stacks Releases -description: Stacks Blockchain Releases -sidebar_position: 2 ---- - -:::info -This page needs contributions. Help us improve it. -::: - -### Stacks Blockchain Releases - -All releases are published [here](https://github.com/stacks-network/stacks-blockchain/releases). Most important ones are described below. - -### Stacks 2.1 - -Scheduled for release at the end of 2022. - -More information on [what to expect with Stacks 2.1](https://stacks.org/stacks-21-what-to-expect). - -#### Stacks 2.05 -Activated on [Bitcoin block 713000](https://explorer.stacks.co/txid/0xece8e369310b5ff9b92ef11181ae0d2457ac0c821376d4a96c4998763e22ad04?chain=mainnet). - -This breaking change enables storage cost for list to be based on actual length and change in number of indexed I/O operations. More info on this [blog post](https://www.stacks.org/stacks-2-05?ref=docs-website). - -#### Stacks 2.0 -Activated on January 14th 2021 - -This hard fork enables Stacking, Clarity smart contracts, scalable transactions, and also building directly on Bitcoin. More info [here](https://forum.stacks.org/t/path-to-mainnet-for-stx-holders-things-to-know-ahead-of-stacks-2-0/11529). - -#### Stacks Genesis -Released on 2018, October 30th UTC+6 at Bitcoin block height 547921 - -This hard fork addresses registration of digital assets with Stacks token and also distribution of Stacks token to the existing purchasers. More info [here](https://blog.blockstack.org/the-launch-of-the-stacks-genesis-block/?ref=docs-website). - diff --git a/i18n/de/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md b/i18n/de/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md deleted file mode 100644 index 25ec969824..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Deploy tips -description: Learn some common methods for deploying your application. ---- - -## Introduction - -Stacks applications are web applications that authenticate users with Stacks Auth and store data with Gaia. Both of these technologies can be accessed on the client side. As such, Stacks apps tend to be simple in design and operation, since in many cases, they don’t have to host anything besides the application’s assets. - -## Where to deploy your application - -Before users can interact with your application, you must deploy it on a server that is accessible over the internet. Deploying requires that you: - -- Configure or customize the files in the `public` directory. -- Build your application site for deployment. -- Copy your generated application files to your production server. - -If you first populated your application with the Stacks application generator, your application contains the starting blocks for configuring, building, and deploying your app. For example, the React template builds out a scaffolding with the following building blocks. - -| File or Directory | Description | -| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| node_modules/react-scripts | A set of scripts for that helps you kick off React projects without configuring, so you do not have to set up your project by yourself. | -| package.json | Contains a scripts section that includes a reference to the react-scripts, which are a dependency. This script creates a build directory containing your files for deployment. | -| public/favicon.ico | An example shortcut icon. | -| public/index.html | An entry page for an application. | -| public/manifest.json | A JSON file that describes your web application to the browser. | -| cors | Contains example deployment files for cross-origin request configuration. | - -If you use the generator to build JavasScript or Vue scaffolding, your project configuration files will be different. - -Regardless of which scaffolding you use, you must customize and extend this basic scaffolding as needed by your application. For example, you may want to add more properties to the `manifest.json` file. Since every application is different, Stacks Auth cannot give you specific instructions on how to do this. The steps you take are specific to your application. - -## Stacks Authentication and deployment - -When your application authenticates users with Stacks, the Stacks Wallet at on URL requests a resource (the app manifest) from your DApp. A request for a resource outside of the origin (the Stacks Wallet) 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 (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) - -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 Stacks 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`: - -```html -Access-Control-Allow-Origin: * Access-Control-Allow-Headers: "X-Requested-With, Content-Type, -Origin, Authorization, Accept, Client-Security-Token, Accept-Encoding" Access-Control-Allow-Methods: -"POST, GET, OPTIONS, DELETE, PUT" -``` - -Consult the documentation for your hosting service to learn how to configure CORS on that service. - -## Deployment and Radiks - -If you are deploying a Stacks application that uses [Radiks](https://github.com/stacks-network/radiks), your deployment includes a server and a database component. You must take this into account when deploying your application. You may want to choose a service such as [Heroku](https://www.heroku.com) or [Digital Ocean](https://www.digitalocean.com) if your app uses Radiks. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/build-apps/index.md b/i18n/de/docusaurus-plugin-content-docs/current/build-apps/index.md deleted file mode 100644 index 23714cba5d..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/build-apps/index.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Build apps with Stacks -description: Authenticate users, sign transactions and store data with the Stacks blockchain -sidebar_position: 3 -sidebar_label: Build apps ---- - -## Introduction - -Apps built with the Stacks blockchain give users control over their digital identities, assets, and data. - -Unlike most cloud-based apps, they are "decentralized" since they don't depend on any centralized platform, server, or database to function. Rather, they use the Stacks blockchain to authenticate users and facilitate read and write requests for them without any single point of failure or trust. - -Stacks provides three main functions for building apps: - - - -- **Authentication**: Register and sign users in with identities on the Stacks blockchain -- **Transaction signing**: Prompt users to sign and broadcast transactions to the Stacks blockchain -- **Data storage**: Save and retrieve data for users with [Gaia](../gaia) - - -All three of these integrations can be used together to create powerful new user experiences that rival or exceed those of traditional apps—all while protecting your users' digital rights. - -While integration is possible for any type of app, most of the resources available here are for web developers experienced with JavaScript. See [Hiro developer docs](https://docs.hiro.so) for more information on the available app development libraries for Stacks. - -## [References](references) - -[Authentication](references/authentication) - -[BNS](references/bns) - -[Gaia](../gaia/) - diff --git a/i18n/de/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md b/i18n/de/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md deleted file mode 100644 index 727b4e2163..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: NoCodeClarity -description: Launch apps for the Stacks blockchain through no code platforms like Bubble. ---- - -## Introduction - -![](https://d1muf25xaso8hp.cloudfront.net/https%3A%2F%2Fs3.amazonaws.com%2Fappforest_uf%2Ff1653407713550x759333524803365600%2FLogo%2520of%2520NoCodeClarity.png?w=179&h=84&auto=compress&dpr=1&fit=max) - -[NoCodeClarity](https://nocodeclarity.com) allows people to create applications for the Stacks blockchain without coding. - -## Stacks Plug-In on bubble - -The [Stacks-No-Code-Plugin](https://bubble.io/plugin/the-stacks-plug-in-1645467277638x949839693014368300) released in May 2022 and it can easily be installed on Bubble with a few clicks allowing users to deploy applications with no coding knowledge. [Bubble](https://bubble.io/blog/explaining-bubble-to-investors/) is the first No Code platform that the Stacks plugin launched on. More platforms are in the roadmap of NoCodeClarity, founded by Christopher Perceptions and Sergio Gongora. The Stacks plugin was created through the support of the Stacks Foundation via a grant in January 2022 and NoCodeClarity was awarded a $100,000 grant in June 2022 to expand the roadmap. - -Additional [instructions](https://s3.amazonaws.com/appforest_uf/f1654202471526x991633667675927800/Instructions%20v2.docx.pdf) are also available. Tutorials and step by step guides will be released soon. - -The Stacks-No-Code-Plugin code is [publicly available on Github](https://github.com/nocodeclarity/Stacks-No-Code-Plugin). - -![](/img/bubble-stacks-plugin.png) - -## Demo page - -A demo page is available [here](https://test-stacks-plugin.bubbleapps.io/version-test). - -## NoCodeClarity videos - -NodeCodeClarity has their own [youtube channel](https://www.youtube.com/channel/UC9Ep0VQ-GQ-yDzt-wmIElRA). - -Videos: - -* [NoCodeClarity Setup](https://www.youtube.com/watch?v=WanXlpBGl0w) -* [NoCodeClarity - Part 1 of the plugin](https://www.youtube.com/watch?v=o6d3hrzNqVI&t=248s) -* [NoCodeClarity - Part 2 of the plugin](https://www.youtube.com/watch?v=0rzMdsrRg80) -* [Sneak Peek of the No Code Stacks Wallet Template](https://www.youtube.com/watch?v=Xe6Yv0rF6XM) \ No newline at end of file diff --git a/i18n/de/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md b/i18n/de/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md deleted file mode 100644 index 8d9e627e2e..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Authentication -description: Register and sign in users with identities on the Stacks blockchain ---- - -## Introduction - -This guide explains how authentication is performed on the Stacks blockchain. - -Authentication provides a way for users to identify themselves to an app while retaining complete control over their credentials and personal details. It can be integrated alone or used in conjunction with [transaction signing](https://docs.hiro.so/get-started/transactions#signature-and-verification) and [data storage](https://docs.stacks.co/build-apps/references/gaia), for which it is a prerequisite. - -Users who register for your app can subsequently authenticate to any other app with support for the [Blockchain Naming System](bns) and vice versa. - -## How it works - -The authentication flow with Stacks is similar to the typical client-server flow used by centralized sign in services (for example, OAuth). However, with Stacks the authentication flow happens entirely client-side. - -An app and authenticator, such as [the Stacks Wallet](https://www.hiro.so/wallet/install-web), communicate during the authentication flow by passing back and forth two tokens. The requesting app sends the authenticator an `authRequest` token. Once a user approves authentication, the authenticator responds to the app with an `authResponse` token. - -These tokens are are based on [a JSON Web Token (JWT) standard](https://tools.ietf.org/html/rfc7519) with additional support for the `secp256k1` curve used by Bitcoin and many other cryptocurrencies. They are passed via URL query strings. - -When a user chooses to authenticate an app, it sends the `authRequest` token to the authenticator via a URL query string with an equally named parameter: - -`https://wallet.hiro.so/...?authRequest=j902120cn829n1jnvoa...` - -When the authenticator receives the request, it generates an `authResponse` token for the app using an _ephemeral transit key_ . The ephemeral transit key is just used for the particular instance of the app, in this case, to sign the `authRequest`. The app private key serves three functions: - -The app stores the ephemeral transit key during request generation. The public portion of the transit key is passed in the `authRequest` token. The authenticator uses the public portion of the key to encrypt an _app private key_ which is returned via the `authResponse`. - -When the authenticator receives the request, it generates an `authResponse` token for the app using an _ephemeral transit key_ . The ephemeral transit key is just used for the particular instance of the app, in this case, to sign the `authRequest`. The app private key serves three functions: - -1. It is used to create credentials that give the app access to a storage bucket in the user's Gaia hub -2. It is used in the end-to-end encryption of files stored for the app in the user's Gaia storage. -3. It serves as a cryptographic secret that apps can use to perform other cryptographic functions. - -Finally, the app private key is deterministic, meaning that the same private key will always be generated for a given Stacks address and domain. - -The first two of these functions are particularly relevant to [data storage with Stacks.js](https://docs.stacks.co/docs/gaia). - -## Key pairs - -Authentication with Stacks makes extensive use of public key cryptography generally and ECDSA with the `secp256k1` curve in particular. - -The following sections describe the three public-private key pairs used, including how they're generated, where they're used and to whom private keys are disclosed. - -### Transit private key - -The transit private is an ephemeral key that is used to encrypt secrets that need to be passed from the authenticator to the app during the authentication process. It is randomly generated by the app at the beginning of the authentication response. - -The public key that corresponds to the transit private key is stored in a single element array in the `public_keys` key of the authentication request token. The authenticator encrypts secret data such as the app private key using this public key and sends it back to the app when the user signs in to the app. The transit private key signs the app authentication request. - -### Identity address private key - -The identity address private key is derived from the user's keychain phrase and is the private key of the Stacks username that the user chooses to use to sign in to the app. It is a secret owned by the user and never leaves the user's instance of the authenticator. - -This private key signs the authentication response token for an app to indicate that the user approves sign in to that app. - -### App private key - -The app private key is an app-specific private key that is generated from the user's identity address private key using the `domain_name` as input. - -The app private key is securely shared with the app on each authentication, encrypted by the authenticator with the transit public key. Because the transit key is only stored on the client side, this prevents a man-in-the-middle attack where a server or internet provider could potentially snoop on the app private key. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/build-apps/references/bns.md b/i18n/de/docusaurus-plugin-content-docs/current/build-apps/references/bns.md deleted file mode 100644 index 32b045dc83..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/build-apps/references/bns.md +++ /dev/null @@ -1,241 +0,0 @@ ---- -title: Blockchain Naming System -description: Binds Stacks usernames to off-chain state ---- - -Blockchain Naming System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of control. - -The Stacks V1 blockchain implemented BNS through first-order name operations. In Stacks V2, BNS is instead implemented through a smart-contract loaded during the genesis block. - -Names in BNS have three properties: - -- **Names are globally unique.** The protocol does not allow name collisions, and all well-behaved nodes resolve a given name to the same state. -- **Names are human-meaningful.** Each name is chosen by its creator. -- **Names are strongly owned.** Only the name's owner can change the state it resolves to. Specifically, a name is owned by one or more ECDSA private keys. - -The Stacks blockchain insures that each node's BNS view is synchronized to all of the other nodes in the world, so queries on one node will be the same on other nodes. Stacks blockchain nodes allow a name's owner to bind up to 40Kb of off-chain state to their name, which will be replicated to all other Stacks blockchain nodes via a P2P network. - -The biggest consequence for developers is that in BNS, reading name state is fast and cheap but writing name state is slow and expensive. This is because registering and modifying names requires one or more transactions to be sent to the underlying blockchain, and BNS nodes will not process them until they are sufficiently confirmed. Users and developers need to acquire and spend the requisite cryptocurrency (STX) to send BNS transactions. - -## Motivation behind naming systems - -We rely on naming systems in everyday life, and they play a critical role in many different applications. For example, when you look up a friend on social media, you are using the platform's naming system to resolve their name to their profile. When you look up a website, you are using the Domain Name Service to resolve the hostname to its host's IP address. When you check out a Git branch, you are using your Git client to resolve the branch name to a commit hash. When you look up someone's PGP key on a keyserver, you are resolving their key ID to their public key. - -What kinds of things do we want to be true about names? In BNS, names are globally unique, names are human-meaningful, and names are strongly owned. However, if you look at these examples, you'll see that each of them only guarantees _two_ of these properties. This limits how useful they can be. - -- In DNS and social media, names are globally unique and human-readable, but not strongly owned. The system operator has the final say as to what each names resolves to. - - - **Problem**: Clients must trust the system to make the right choice in what a given name resolves to. This includes trusting that no one but the system administrators can make these changes. - -- In Git, branch names are human-meaningful and strongly owned, but not globally unique. Two different Git nodes may resolve the same branch name to different unrelated repository states. - - - **Problem**: Since names can refer to conflicting state, developers have to figure out some other mechanism to resolve ambiguities. In Git's case, the user has to manually intervene. - -- In PGP, names are key IDs. They are are globally unique and cryptographically owned, but not human-readable. PGP key IDs are derived from the keys they reference. - - **Problem**: These names are difficult for most users to remember since they do not carry semantic information relating to their use in the system. - -BNS names have all three properties, and none of these problems. This makes it a powerful tool for building all kinds of network applications. With BNS, we can do the following and more: - -- Build domain name services where hostnames can't be hijacked. -- Build social media platforms where user names can't be stolen by phishers. -- Build version control systems where repository branches do not conflict. -- Build public-key infrastructure where it's easy for users to discover and remember each other's keys. - -## Organization of BNS - -BNS names are organized into a global name hierarchy. There are three different layers in this hierarchy related to naming: - -- **Namespaces**. These are the top-level names in the hierarchy. An analogy to BNS namespaces are DNS top-level domains. Existing BNS namespaces include `.id`, `.podcast`, and `.helloworld`. All other names belong to exactly one namespace. Anyone can create a namespace, but in order for the namespace to be persisted, it must be _launched_ so that anyone can register names in it. Namespaces are not owned by their creators. - -- **BNS names**. These are names whose records are stored directly on the blockchain. The ownership and state of these names are controlled by sending blockchain transactions. Example names include `verified.podcast` and `muneeb.id`. Anyone can create a BNS name, as long as the namespace that contains it exists already. - -- **BNS subdomains**. These are names whose records are stored off-chain, but are collectively anchored to the blockchain. The ownership and state for these names lives within the P2P network data. While BNS subdomains are owned by separate private keys, a BNS name owner must broadcast their subdomain state. Example subdomains include `jude.personal.id` and `podsaveamerica.verified.podcast`. Unlike BNS namespaces and names, the state of BNS subdomains is _not_ part of the blockchain consensus rules. - -A feature comparison matrix summarizing the similarities and differences between these name objects is presented below: - -| Feature | **Namespaces** | **BNS names** | **BNS Subdomains** | -| -------------------------------------- | -------------- | ------------- | ------------------ | -| Globally unique | X | X | X | -| Human-meaningful | X | X | X | -| Owned by a private key | | X | X | -| Anyone can create | X | X | [1] | -| Owner can update | | X | [1] | -| State hosted on-chain | X | X | | -| State hosted off-chain | | X | X | -| Behavior controlled by consensus rules | X | X | | -| May have an expiration date | | X | | - -[1] Requires the cooperation of a BNS name owner to broadcast its transactions - -## Namespaces - -Namespaces are the top-level naming objects in BNS. - -They control a few properties about the names within them: - -- How expensive they are to register -- How long they last before they have to be renewed -- Who (if anyone) receives the name registration fees -- Who is allowed to seed the namespace with its initial names. - -At the time of this writing, by far the largest BNS namespace is the `.id` namespace. Names in the `.id` namespace are meant for resolving user identities. Short names in `.id` are more expensive than long names, and have to be renewed by their owners every two years. Name registration fees are not paid to anyone in particular---they are instead sent to a "black hole" where they are rendered unspendable (the intention is to discourage ID squatters). - -Unlike DNS, _anyone_ can create a namespace and set its properties. Namespaces are created on a first-come first-serve basis, and once created, they last 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 (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`). - -Namespaces can be between 1 and 19 characters long, and are composed of the characters `a-z`, `0-9`, `-`, and `_`. - -## Subdomains - -BNS names are strongly owned because the owner of its private key can generate valid transactions that update its zone file hash and owner. However, this comes at the cost of requiring a name owner to pay for the underlying transaction in the blockchain. Moreover, this approach limits the rate of BNS name registrations and operations to the underlying blockchain's transaction bandwidth. - -BNS overcomes this with subdomains. A **BNS subdomain** is a type of BNS name whose state and owner are stored outside of the blockchain, but whose existence and operation history are anchored to the blockchain. Like their on-chain counterparts, subdomains are globally unique, strongly owned, and human-readable. BNS gives them their own name state and public keys. Unlike on-chain names, subdomains can be created and managed cheaply, because they are broadcast to the BNS network in batches. A single blockchain transaction can send up to 120 subdomain operations. - -This is achieved by storing subdomain records in the BNS name zone files. An on-chain name owner broadcasts subdomain operations by encoding them as `TXT` records within a DNS zone file. To broadcast the zone file, the name owner sets the new zone file hash with a `NAME_UPDATE` transaction and replicates the zone file. This, in turn, replicates all subdomain operations it contains, and anchors the set of subdomain operations to an on-chain transaction. The BNS node's consensus rules ensure that only valid subdomain operations from _valid_ `NAME_UPDATE` transactions will ever be stored. - -For example, the name `verified.podcast` once wrote the zone file hash `247121450ca0e9af45e85a82e61cd525cd7ba023`, which is the hash of the following zone file: - -```bash -$TTL 3600 -1yeardaily TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxeWVhcmRhaWx5CiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMXllYXJkYWlseS9oZWFkLmpzb24iCg==" -2dopequeens TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAyZG9wZXF1ZWVucwokVFRMIDM2MDAKX2h0dHAuX3RjcCBVUkkgMTAgMSAiaHR0cHM6Ly9waC5kb3Rwb2RjYXN0LmNvLzJkb3BlcXVlZW5zL2hlYWQuanNvbiIK" -10happier TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxMGhhcHBpZXIKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8xMGhhcHBpZXIvaGVhZC5qc29uIgo=" -31thoughts TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzMXRob3VnaHRzCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzF0aG91Z2h0cy9oZWFkLmpzb24iCg==" -359 TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzNTkKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8zNTkvaGVhZC5qc29uIgo=" -30for30 TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzMGZvcjMwCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzBmb3IzMC9oZWFkLmpzb24iCg==" -onea TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiBvbmVhCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vb25lYS9oZWFkLmpzb24iCg==" -10minuteteacher TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxMG1pbnV0ZXRlYWNoZXIKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8xMG1pbnV0ZXRlYWNoZXIvaGVhZC5qc29uIgo=" -36questionsthepodcastmusical TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzNnF1ZXN0aW9uc3RoZXBvZGNhc3RtdXNpY2FsCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzZxdWVzdGlvbnN0aGVwb2RjYXN0bXVzaWNhbC9oZWFkLmpzb24iCg==" -_http._tcp URI 10 1 "https://dotpodcast.co/" -``` - -Each `TXT` record in this zone file encodes a subdomain-creation. For example, `1yeardaily.verified.podcast` resolves to: - -```json -{ - "address": "1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH", - "blockchain": "bitcoin", - "last_txid": "d87a22ebab3455b7399bfef8a41791935f94bc97aee55967edd5a87f22cce339", - "status": "registered_subdomain", - "zonefile_hash": "e7acc97fd42c48ed94fd4d41f674eddbee5557e3", - "zonefile_txt": "$ORIGIN 1yeardaily\n$TTL 3600\n_http._tcp URI 10 1 \"https://ph.dotpodcast.co/1yeardaily/head.json\"\n" -} -``` - -This information was extracted from the `1yeardaily` `TXT` resource record in the zone file for `verified.podcast`. - -### Subdomain Lifecycle - -Note that `1yeardaily.verified.podcast` has a different public key hash (address) than `verified.podcast`. A BNS node will only process a subsequent subdomain operation on `1yeardaily.verified.podcast` if it includes a signature from this address's private key. `verified.podcast` cannot generate updates; only the owner of `1yeardaily.verified.podcast can do so`. - -The lifecycle of a subdomain and its operations is shown in Figure 2. - -``` - subdomain subdomain subdomain - creation update transfer -+----------------+ +----------------+ +----------------+ -| cicero | | cicero | | cicero | -| owner="1Et..." | signed | owner="1Et..." | signed | owner="1cJ..." | -| zf0="7e4..." |<--------| zf0="111..." |<--------| zf0="111..." |<---- ... -| seqn=0 | | seqn=1 | | seqn=2 | -| | | sig="xxxx" | | sig="xxxx" | -+----------------+ +----------------+ +----------------+ - | | | - | off-chain | | -~ ~ ~ ~ | ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~|~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ | ~ ~ ~ ~ ~ ~ ~ ... - | on-chain | | - V V (zone file hash ) V -+----------------+ +----------------+ +----------------+ -| res_publica.id | | jude.id | | res_publica.id | -| NAME_UPDATE |<--------| NAME_UPDATE |<--------| NAME_UPDATE |<---- ... -+----------------+ +----------------+ +----------------+ - blockchain blockchain blockchain - block block block - - -Figure 2: Subdomain lifetime with respect to on-chain name operations .A new -subdomain operation will only be accepted if it has a later "sequence=" number, -and a valid signature in "sig=" over the transaction body .The "sig=" field -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." -However, any on-chain name ("jude.id" in this case) can broadcast a subdomain -update for "cicero.res_publica.id." -``` - -Subdomain operations are ordered by sequence number, starting at 0. Each new subdomain operation must include: - -- The next sequence number -- The public key that hashes to the previous subdomain transaction's address -- A signature from the corresponding private key over the entire subdomain operation. - -If two correctly signed but conflicting subdomain operations are discovered (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 subdomain's operations will be able to determine the valid sequence of state-transitions it has undergone, and determine the current zone file and public key hash for the subdomain. - -### Subdomain Creation and Management - -Unlike an on-chain name, a subdomain owner needs an on-chain name owner's help to broadcast their subdomain operations. In particular: - -- A subdomain-creation transaction can only be processed by the owner of the on-chain name that shares its suffix. For example, only the owner of `res_publica.id` can broadcast subdomain-creation transactions for subdomain names ending in `.res_publica.id`. -- A subdomain-transfer transaction can only be broadcast by the owner of the on-chain name that created it. For example, the owner of `cicero.res_publica.id` needs the owner of `res_publica.id` to broadcast a subdomain-transfer transaction to change `cicero.res_publica.id`'s public key. -- In order to send a subdomain-creation or subdomain-transfer, all of an on-chain name owner's zone files must be present in the Atlas network. This lets the BNS node prove the _absence_ of any conflicting subdomain-creation and subdomain-transfer operations when processing new zone files. -- A subdomain update transaction can be broadcast by _any_ on-chain name owner, but the subdomain owner needs to find one who will cooperate. For example, the owner of `verified.podcast` can broadcast a subdomain-update transaction created by the owner of `cicero.res_publica.id`. - -That said, to create a subdomain, the subdomain owner generates a subdomain-creation operation for their desired name and gives it to the on-chain name owner. - -Once created, a subdomain owner can use any on-chain name owner to broadcast a subdomain-update operation. To do so, they generate and sign the requisite subdomain operation and give it to an on-chain name owner, who then packages it with other subdomain operations into a DNS zone file and broadcasts it to the network. - -If the subdomain owner wants to change the address of their subdomain, they need to sign a subdomain-transfer operation and give it to the on-chain name owner who created the subdomain. They then package it into a zone file and broadcast it. - -### Subdomain Registrars - -Because subdomain names are cheap, developers may be inclined to run subdomain registrars on behalf of their applications. For example, the name `personal.id` is used to register usernames without requiring them to spend any Bitcoin. - -We supply a reference implementation of a [BNS Subdomain Registrar](https://github.com/stacks-network/subdomain-registrar) to help developers broadcast subdomain operations. Users would still own their subdomain names; the registrar simply gives developers a convenient way for them to register and manage them in the context of a particular application. - -# BNS and DID Standards - -BNS names are compliant with the emerging [Decentralized Identity Foundation](http://identity.foundation) protocol specification for decentralized identifiers (DIDs). - -Each name in BNS has an associated DID. The DID format for BNS is: - -```bash - did:stack:v0:{address}-{index} -``` - -Where: - -- `{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 `did:stack:v0:1dARRtzHPAFRNE7Yup2Md9w18XEQAtLiV-0`, because the name `personal.id` was the first-ever name created by `1dARRtzHPAFRNE7Yup2Md9w18XEQAtLiV`. - -As another example, the DID for `jude.id` is `did:stack:v0:16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg-1`. Here, the address `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` had created one earlier name in history prior to this one (which happens to be `abcdefgh123456.id`). - -The purpose of a DID is to provide an eternal identifier for a public key. The public key may change, but the DID will not. - -Stacks Blockchain implements a DID method of its own in order to be compatible with other systems that use DIDs for public key resolution. In order for a DID to be resolvable, all of the following must be true for a name: - -- The name must exist -- The name's zone file hash must be the hash of a well-formed DNS zone file -- The DNS zone file must be present in the Stacks node's data. -- The DNS zone file must contain a `URI` resource record that points to a signed JSON Web Token -- The public key that signed the JSON Web Token (and is included with it) must hash to the address that owns the name - -Not all names will have DIDs that resolve to public keys. However, names created by standard tooling will have DIDs that do. - -A RESTful API is under development. - -## DID Encoding for Subdomains - -Every name and subdomain in BNS has a DID. The encoding is slightly different 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 (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 subdomains owned by a single private key, and version byte 50 for subdomains owned by a m-of-n set of private keys. That is, subdomain DID addresses start with `S` or `M`, respectively. - -The `{index}` field for a subdomain's DID is distinct from the `{index}` field for a BNS name's DID, even if the same created both names and subdomains. For example, the name `abcdefgh123456.id` has the DID `did:stack:v0:16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg-0`, because it was the first name created by `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg`. However, `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` _also_ created `jude.statism.id` as its first subdomain name. The DID for `jude.statism.id` is `did:stack:v0:SSXMcDiCZ7yFSQSUj7mWzmDcdwYhq97p2i-0`. Note that the address `SSXMcDiCZ7yFSQSUj7mWzmDcdwYhq97p2i` encodes the same public key hash as the address `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` (the only difference between these two strings is that the first is base58check-encoded with version byte 0, and the second is encoded with version byte 63). diff --git a/i18n/de/docusaurus-plugin-content-docs/current/build-apps/references/references.md b/i18n/de/docusaurus-plugin-content-docs/current/build-apps/references/references.md deleted file mode 100644 index babe5e119a..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/build-apps/references/references.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: References -sidebar_label: References ---- - -[Authentication](./authentication) - -[Blockchain Naming System](./bns) - -[Hiro example apps](https://docs.hiro.so/example-apps) \ No newline at end of file diff --git a/i18n/de/docusaurus-plugin-content-docs/current/contribute/docs.md b/i18n/de/docusaurus-plugin-content-docs/current/contribute/docs.md deleted file mode 100644 index 77705451b8..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/contribute/docs.md +++ /dev/null @@ -1,207 +0,0 @@ ---- -title: Contribute to docs -description: Learn how this site is built, and how you can contribute to it. ---- - -## Introduction - -Thank you for your interest in contributing and helping make these docs as good as they can be. - -This docs site is built on the open source platform [Discosaurus 2](https://docusaurus.io/) and most of its content is written in Markdown files. All of the code for this site is free and open source, located at the [GitHub repository here](https://github.com/stacks-network/docs). - -:::tip Don't know what Markdown is? Want to learn? Here is a [helpful guide](https://guides.github.com/features/mastering-markdown/). - -Don't want to learn it? No need to. Write [in plain text an issue on Github](https://github.com/stacks-network/docs/issues/new?assignees=&labels=documentation&template=add-documentation.md&title=%5BAdd+docs%5D) ::: - -:::info You need a free [Github](https://www.github.com) account to add or edit any content. ::: - -To edit any page, just click on the *Edit this page* button at the bottom of each page and submit your changes online. - -To add new content, they are two different ways to do it, the [easy way](#easy-way) and the [advanced way](#advanced-way). - -## Easy way - -[**Simply click here and enter the text of the article you wish to add.**](https://github.com/stacks-network/docs/issues/new?assignees=&labels=documentation&template=add-documentation.md&title=%5BAdd+docs%5D) - -This will open up an issue on github using our template. -## Advanced way - -For more advanced changes you can follow the next steps. - -You can also test the site locally using this method. -### Steps - -1. Fork the [docs reposiroty](https://github.com/stacks-network/docs) by clicking on the *Fork* button in the upper right of the screen. -2. Clone your fork to your local machine with this command `git clone git@github.com:/docs.git stacks_docs` -3. Enter your project folder `cd stacks_docs` -4. Create a branch `git checkout -b feat/my-feature-branch`. -5. You can optionally preview your changes in real time with: - - `npm install` (to install dependencies). - - `npx docusaurus start` to start a local copy of the site. A web browser will open at http://localhost:3000, so you can see a preview of yourhanges in real time. -6. Make the changes you wish and then commit them with this kind of message: `git commit -am "feat: some new feature or content"`. -7. Push to to GitHub with `git push --set-upstream origin feature/my-feature-branch`. -8. Visit GitHub and make your pull request. - -## Aditional information -### Running and building the site locally (optional) - -You can start the page locally with the following command. This is enough to preview your changes. -```bash -npx docusaurus start -``` - -Before running this command for the first time you will need to run `npm install` to install dependencies. - -The docs site will be accessible at this url: [`http://localhost:3000`](http://localhost:3000). - - -After you finished your changes, you can also build the entire site with the following command (not usually needed): -```bash -npm run build -``` - -:::tip `npx docusaurus start` will only load the default language (english). To test all languages you can build with `npm run build` and then preview your build with `npm run serve`. ::: - -### An alternative: Working in browser - -As an alterative to working locally, you can also use the web IDE gitpod that provides an environment to contribute directly from within your browser. - -You only need to have a github account and open [this link](https://gitpod.io/#https://github.com/stacks-network/docs). - -### Folder structure of the site - -If you are interested in only adding new documentation content to the site, the files that will be important to you are located within `./docs/*`: - -```bash -docs/ - build-apps - contribute/ - faq/ - gaia/ - nodes-and-miners/ - noteworthy-contracts/ - references/ - understand-stack/ - write-smart-contracts/ -``` - -The routing for this site is file based, meaning if you created a folder within `/docs/gaia/` named `testing` and in it a file named `test1.md`, you would be able to navigate to `http://localhost:3000/gaia/testing/test1` and you would see whatever content is in that markdown file. - -All the docs in English are stored in the folder `/docs/`. - -To add new English content simply add a markdown file (.md) into any subfolder in docs, and it will be automatically displayed in the category of that folder. - -All the docs in other languages are stored under the folder `i18n`, but these files should never be edited using GitHub as they are overwritten by Crowdin every time new translations are added. **To make changes in other languages**, you must do so using Crowdin. Please refer to [translations](translations) instead. - -### Frontmatter - -Frontmatter is the top part of any markdown document that is written in a language called [YAML](https://yaml.org/). It looks like this: - -```yaml ---- -title: This is my page title -description: A short, concise sentence describing what is on this page ---- -``` - -Frontmatter gives us the ability to define some things within a page that the site can use, such as a page title or page description. When adding any new page, please include a `title` and `description`. - - - -### Use Conventional Commits - -We use the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) as and commits naming convention. Use it while contributing, please. - -### Code blocks - -To write a code block, you need to wrap your code in ` ```language `, and end your code block with ` ``` `. Here is an example of ` ```clarity `. - -```clarity -(define-data-var counter int 0) - -(define-public (get-counter) - (ok (var-get counter))) -``` -### Admonitions - -You can use the following admonitions to highlight content. - -```md -:::note -Some **content** with _markdown_ `syntax`. -::: - -:::tip -Some **content** with _markdown_ `syntax`. -::: - -:::info -Some **content** with _markdown_ `syntax`. -::: - -:::caution -Some **content** with _markdown_ `syntax`. -::: - -:::danger -Some **content** with _markdown_ `syntax`. -::: - -:::tip My personalized title -Some **content** with _markdown_ `syntax`. -::: -``` - -Which renders: - -:::note - -Some **content** with _markdown_ `syntax`. - -::: - -:::tip - -Some **content** with _markdown_ `syntax`. - -::: - -:::info - -Some **content** with _markdown_ `syntax`. - -::: - -:::caution - -Some **content** with _markdown_ `syntax`. - -::: - -:::danger - -Some **content** with _markdown_ `syntax`. - -::: - -:::tip My personalized title - -Some **content** with _markdown_ `syntax`. - -::: \ No newline at end of file diff --git a/i18n/de/docusaurus-plugin-content-docs/current/contribute/index.md b/i18n/de/docusaurus-plugin-content-docs/current/contribute/index.md deleted file mode 100644 index ac81d899bd..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/contribute/index.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Contribute -description: Contribute to the Stacks ecosystem. -sidebar_position: 10 -sidebar_label: "Contribute" ---- - -You can contribute to the Stacks ecosystem in multiple ways: - - - -### Documentation - -Contribute to the Stacks Docs on this website. More info [here](docs). - -### Translations - -Help us reach more people with translations. More details [here](translations). - - - -### Articles - -Write an article or a blog post about Stacks. A good place to start is [Stacks Forum](https://forum.stacks.org). - -### Github - -If you are familiar with Github they are multiple repositories of the Stack Ecosystem that you can contribute to. - -- https://github.com/stacks-network/ diff --git a/i18n/de/docusaurus-plugin-content-docs/current/contribute/translations.md b/i18n/de/docusaurus-plugin-content-docs/current/contribute/translations.md deleted file mode 100644 index bd9a452333..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/contribute/translations.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Contribute with translations -description: Want to help tranlating these docs to your local language? ---- - -## Help with translations - -Translations are managed with Crowdin. -Anybody can colaborate and no technichal skills are required, as it's all done on the browser. - -To help with translation please go to [this page](https://crowdin.com/project/docsstacksco), click any language and start translating. - -All help is appreciated. - -:::caution -Please don't add any translations to the Github repository, as the translated pages get rewritten from Crowdin. Translations need to be added on Crodin intead. -::: - -### Common issues on translations - -When translating in Crowdin, please only translate the texts and not the html code. - -If you acccidently modify the html tags you will get errors like shown below (`Seems like some formating tags are missing` or `Translation contains tag that source text doesn't have`). These errors will prevent your translation getting published until the tags are left as they were in the original text. - -![](/img/crowdin-qa-issue-formatting_tags_missing.png) ![](/img/crowdin-qa-issue-tag_source.png) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/faq/faq.md b/i18n/de/docusaurus-plugin-content-docs/current/faq/faq.md deleted file mode 100644 index 07d7616631..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/faq/faq.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: General FAQs -description: Frequently Asked Questions -sidebar_label: "FAQ" -sidebar_position: 10 ---- - -![](/img/glasses.png) - -## Why is my transfer still pending? - -Commonly it's because your fee is too low or your [nonce](#what-is-nonce) is incorrect. - -More information can be found [here](https://www.hiro.so/wallet-faq/why-is-my-stacks-transaction-pending). There are also [best practices and known issues](https://forum.stacks.org/t/transactions-in-mempool-best-practices-and-known-issues/11659) and [diagnosing pending transactions](https://forum.stacks.org/t/diagnosing-pending-transactions/11908). - -There is also this [script](https://github.com/citycoins/scripts/blob/main/getnetworkstatus.js) to look at either the first 200 transactions or all the transactions in the mempool, to then return the maximum adn average fee values. We've noticed that using 1.5-2x the average fee in the mempool will generally get things processed within 6-10 blocks even during high congestion. - -There is also this [script](https://github.com/citycoins/scripts/blob/main/gettxstatus.js) to track a pending transaction until it reaches a final status. - -## What is Nonce? - -A nonce is used to make sure that every transaction goes in right order. Nonce starts at 0, so the very first transaction from an address should set to nonce=0. You can find the nonce of your wallet address by searching the address in any [Stacks blockchain explorer](https://explorer.stacks.co/). You can also user `$ stx balance
`. - -If you have a transaction nonce that is less than your account nonce, the transaction is unmineable and will (should) disappear after 256 blocks. This does not affect future transactions and therefore can be just ignored, they are in the past. - -If you have a transaction nonce that is equal to your account nonce, then that transaction is valid and should be the next in line to be processed next. - -If you have a transaction nonce that is higher than your account nonce, then there needs to be a chain of transactions starting with your account nonce in order for it to be processed. E.g. E.g. E.g. Your account nonce is 10 but the pending transaction has a nonce of 12. It will not be mineable until a transaction with nonces 10 and 11 are processed. - -## Whats a Replace-by-fee (RBF)? - -A replace-by-fee (RBF) transaction tells the blockchain that you would like to replace one transaction with another, while specifying a fee that is higher than the original transaction fee. A transaction can be replaced with **any other transaction**, and is not limited to the same operation. - -This can be used to effectively **cancel a transaction** by replacing it with something else, like a small STX transfer to another owned address. - -This can be used to **raise the fee for a pending transaction** so it is considered by miners during periods of high congestion. This can also be used to _resubmit_ a transaction, in the sense that the RBF transaction gets a new txid and gets considered again (or faster) by miners. E.g. E.g. E.g. I submit my transaction with 1 STX fee at block 54,123. By block 54,133 I see my tx hasn’t been picked up, so I RBF with 1.1 STX. Then wait 10 blocks again, and RBF again if not received. There’s a balance between doing this too often and keeping a consistent pace, but it has been seen to help get transactions through, especially when new ones are constantly flooding in. - -The replacement transaction needs to use the same nonce as the original transaction with a fee increase of at least 0.000001 STX. E.g. E.g. E.g. Your original transaction has a fee of 0.03 STX, the new RBF transaction must have a fee of 0.030001 STX or above. - -RBF transactions process in one of two ways: - -- If miners pick up the original transaction before the RBF transaction is received, then the original transaction is processed and the replacement transaction goes into an unmineable state. It will eventually disappear and doesn’t affect future transactions. -- If miners pick up the replaced transaction then the new transaction is processed instead of the original, and the status of the original transaction is set to “droppped_replaced_by_fee”. This status is not shown on the explorer but can be seen when querying the txid. - -Submitting multiple transactions for the same action can slow things down in a few ways. - -- If the total spent in 2 or 3 transactions is more than can be spent in a single transaction, the transactions appear unmineable. -- If the fees for multiple transactions exceed the STX balance, the transactions will be unmineable. - -## What are .btc domains? - -[This forum post](https://forum.stacks.org/t/btc-domains-are-live/12065) explains all the benefits of .btc domains. They can currently be purchased in [btc.us](https://btc.us/) - -## What is the blockchain trilemma? - -## Stacks vs. Solana vs. Polygon: How Do They Compare From a Developer Perspective? - -[This blog post answers the question](https://www.hiro.so/blog/stacks-vs-solana-vs-polygon-how-do-they-compare-from-a-developer-perspective). - -## What Does Lightning’s Taro Proposal Mean for Stacks? - -[This blog post answers the question](https://www.hiro.so/blog/what-does-lightnings-taro-proposal-mean-for-stacks). - - -## Is Stacks a [PoS chain](https://en.wikipedia.org/wiki/Proof_of_stake)?[¹][] - -No. - -The act of block production requires an extrinsic expenditure — it is not tied to owning the native token, as would be required in PoS. The only way to produce blocks in the Stacks chain is to transfer Bitcoin to a predetermined randomized list of Bitcoin addresses. Moreover, the Stacks blockchain can fork, and there exists a protocol to rank forks by quality independent of the set of miners and the tokens they hold. These two properties further distinguish it from PoS chains, which cannot fork due to the inability to identify a canonical fork without trusting a 3rd party to decree a particular fork as valid. The ability to fork allows the Stacks blockchain to survive failure modes that would crash a PoS chain. - -## Is Stacks a [sidechain](https://en.bitcoin.it/wiki/Sidechain)?[¹][] - -No. - -For two key reasons. - -First, the history of all Stacks blocks produced is recorded to Bitcoin. This means that the act of producing a private Stacks fork is at least as hard as reorging the Bitcoin chain. This in turn makes it so attacks on the chain that rely on creating private forks (such as selfish mining and double-spending) are much harder to carry out profitably, since all honest participants can see the attack coming before it happens and have a chance to apply countermeasures. Sidechains offer no such security benefit. - -Second, the Stacks blockchain has its own token; it does not represent pegged Bitcoin. This means that the safety of the canonical fork of the Stacks blockchain is underpinned by its entire token economy’s value, whereas the safety of a sidechain’s canonical fork is underpinned only by whatever system-specific measures incentivize its validators to produce blocks honestly, or the Bitcoin miners’ willingness to process peg-in requests (whichever is the weaker guarantee). - - -## Is Stacks a [layer-2 system](https://academy.binance.com/en/glossary/layer-2) for Bitcoin?[¹][] - -No. - -Stacks blockchain is a layer-1 blockchain, which uses a novel and unique mining protocol called proof-of-transfer (PoX). A PoX blockchain runs in parallel to another blockchain (Bitcoin in Stacks’ case), which it uses as a reliable broadcast medium for its block headers. It's a sovereign system in its own right. The Stacks blockchain state is distinct from Bitcoin, and is wholly maintained by and for Stacks nodes. Stacks transactions are separate from Bitcoin transactions. Layer-2 systems like Lightning are designed to help scale Bitcoin payment transactions, whereas Stacks is designed to bring new use-cases to Bitcoin through smart contracts. Stacks is not designed as a Bitcoin layer-2 scalability solution. - - -## Is Stacks a [merged-mined chain](https://en.bitcoin.it/wiki/Merged_mining_specification)?[¹][] - -No. - -The only block producers on the Stacks chain are Stacks miners. Bitcoin miners do not participate in Stacks block validation, and do not claim Stacks block rewards. Moreover, Stacks is not a [blind merged-mined chain](https://github.com/bitcoin/bips/blob/master/bip-0301.mediawiki), because STX block winners are public and randomly chosen (instead of highest-bid-wins), and its tokens are minted according to a schedule that is independent of the degree of miner commitment or Bitcoin transferred (instead of minted only by one-way pegs from Bitcoin). This ensures that Stacks is able to make forward progress without opt-in from Bitcoin miners, and it ensures that Stacks miners are adequately compensated for keeping the system alive regardless of transaction volume. - -## Whats the difference between Stacks and Ethereum?[²][] -**Computation and Storage** Stacks does all computation and storage outside of the blockchain, and uses the blockchain only as a “shared source of truth” between clients. By contrast, Ethereum does all computation and most application storage in the blockchain itself. Like Ethereum, if two Stacks nodes see the same underlying blockchain, they will independently run the same computations and produce the same state. Unlike Ethereum, there is no Stacks-specific blockchain. - -**Programming Language and Tooling** Stacks’s programming model is based on running off-chain programs. These programs can be written and debugged in any language you want. By contrast, Ethereum’s programming model is based on running on-chain “smart contracts.” These are written and debugged with a whole new set of tools, like Solidity and Serpent. These are written and debugged with a whole new set of tools, like Solidity and Serpent. - -**Scalability of On-chain Computation** Stacks is designed around a “virtual chain” concept, where nodes only need to reach consensus on the shared “virtual chain” they’re interested in. Virtual chains do not interact with one another, and a single blockchain can host many virtual chains. Although Stacks’s specific virtual chain is not Turing-complete (i.e. it’s a list of instructions to build the name database), it is possible to create Turing-complete virtual chains like Ethereum. These virtual chains can live in any blockchain for which there exists a driver, and virtual chain clients only need to execute their virtual chain transactions (i.e. Stacks only processes Stacks virtual chain transactions). Stacks only processes Stacks virtual chain transactions). - -By contrast, because smart contracts run on-chain and can call one another, all Ethereum nodes need to process all smart contracts’ computations in order to reach consensus. This can get expensive as the number of running smart contracts grow, which takes the form of gas fee increases. - -**Scalability of Off-chain Computation** Stacks applications are very similar to Web applications today and almost never need to interact with the blockchain. For most Stacks applications, the blockchain is only used to authenticate the application’s code and data before the user runs it. By contrast, Ethereum applications usually require an application-specific smart contract, and must interact with the blockchain to carry out its operations. - - -[¹]: https://stacks.org/stacks-blockchain -[²]: https://forum.stacks.org/t/what-is-the-difference-between-blockstack-and-ethereum/781 diff --git a/i18n/de/docusaurus-plugin-content-docs/current/gaia/configuration.md b/i18n/de/docusaurus-plugin-content-docs/current/gaia/configuration.md deleted file mode 100644 index a6a530cd70..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/gaia/configuration.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Configuration -description: Configuring Gaia Hub ---- - -## Configuration files - -The following configuration files exist in the folder `deploy/configs/gaia/`: - -``` -admin-config.json -hub-config.json -reader-config.json -``` - -## GAIA Admin Service - -You can also use the GAIA Admin Service to remotely administer it with an API Key. It will require you to install `npm` with a `apt install npm`. Once `npm` is installed you can continue with the steps in the [GAIA Admin Service](https://github.com/stacks-network/gaia/blob/master/admin/README.md). - -## Driver Selection - -The Gaia hub currently supports the following drivers: - -``` -'aws' == Amazon S3 -'azure' == Azure Blob Storage -'disk' == Local disk -'google-cloud' === Google Cloud Storage -``` - -Set the driver you wish to use in your [config.json](https://github.com/stacks-network/gaia/blob/master/hub/config.sample.json) file with the `driver` parameter. Many drivers additionally accept the `bucket` parameter, which controls the bucket name that files should be written to. - -These driver may require you to provide additional credentials for performing writes to the backends. See `config.sample.json` for fields for those credentials. In some cases, the driver can use a system configured credential for the backend (e.g., if you are logged into your AWS CLI account, and run the hub from that environment, it won't need to read credentials from your `config.json`). - -_Note:_ The disk driver requires a \*nix like filesystem interface, and will not work correctly when trying to run in a Windows environment. ::: - -## Note on SSL - -We _strongly_ recommend that you deploy your Gaia hub with SSL enabled. Otherwise, the tokens used to authenticate with the Gaia hub may be stolen by attackers, which could allow them to execute writes on your behalf. -Configuration options are available to run the hub with an `https` Node.js server. -Otherwise, a reverse proxy web server such as nginx or Apache can be used. - -## Require Correct Hub URL - -If you turn on the `requireCorrectHubUrl` option in your `config.json` file, your Gaia hub will require that authentication requests correctly include the `hubURL` they are trying to connect with. This is used to prevent a malicious gaia hub from using an authentication token for itself on other Gaia hubs. - -By default, the Gaia hub will validate that the supplied URL matches `https://${config.serverName}`, but if there are multiple valid URLs for clients to reach the hub at, you can include a list in your `config.json`: - -```javascript -{ - .... - serverName: "normalserver.com" - validHubUrls: [ "https://specialserver.com/", - "https://legacyurl.info" ] - .... -} -``` - -## The readURL parameter - -By default, the gaia hub drivers will return read URLs which point directly at the written content. For example, an S3 driver would return the URL directly to the S3 file. However, if you configure a CDN or domain to point at that same bucket, you can use the `readURL` parameter to tell the gaia hub that files can be read from the given URL. For example, the `hub.blockstack.org` Gaia Hub is configured to return a read URL that looks like `https://gaia.blockstack.org/hub/`. - -Unset this configuration parameter if you do not intend to deploy any caching. - -## Minimum Proofs Requirement - -The gaia hub can also be configured to require a minimum number of social proofs in a user's profile to accept writes from that user. This can be used as a kind of spam-control mechanism. However, we recommend for the smoothest operation of your gaia hub, to set the `proofsConfig.proofsRequired` configuration key to `0`. - -## CDN & Replicated Hubs - -- https://docs.microsoft.com/en-us/azure/storage/blobs/storage-https-custom-domain-cdn - -- The hub implementation is designed to be ran from a single Node.js instance. If the hub instance is sharded (e.g. replicated hubs via load balancing), then any given `bucket` (identified by URI segment) must be served by the same instance, At least a couple elements of the Gaia Hub depend on this: token invalidation in-memory caching, and resource endpoint 409 contention behavior. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md b/i18n/de/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md deleted file mode 100644 index 558cbb14f5..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Deploy Gaia Hub -description: Steps and tutorials ---- - -## Deploy your GAIA hub - -Tutorials to deploy your own GAIA hub are currently available for [Linux](./setup-linux), [MacOS](./setup-mac) and [Amazon EC2 / CloudFormation](./gaia-on-ec2). - -Regardless of what server the Gaia Hub runs on, the storage it uses can currently be deployed on multiple platforms: - -- Local disk (the server itself) -- Amazon S3 -- Azure Blob Storage -- Google Cloud - -:::tip -Support for IPFS is under development. -::: \ No newline at end of file diff --git a/i18n/de/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md b/i18n/de/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md deleted file mode 100644 index 2067e7d57c..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Amazon EC2 -description: Use a template to deploy a Gaia hub on Amazon EC2 -tags: - - tutorial - - gaia ---- - -## Introduction - -The template provided on this page provides an easy way to deploy a Gaia hub directly to Amazon EC2. You can use this template to deploy your own Gaia hub to your Amazon Web Services (AWS) account. Amazon EC2 is an affordable and convenient cloud computing provider. The template provides a one-click deploy for Amazon EC2 with either S3 or EBS as a storage provider. - -## Prerequisites - -This procedure uses Amazon CloudFormation to configure an EC2 cloud compute provider to run the Gaia hub service with an S3 or EBS provider for file storage. You should have access to an AWS account either through your personal account or through a corporate account. This account should have permissions to create resources. - -Additionally, you must also own a domain name and be able to update the DNS records associated with that domain name. - -## Setup steps - -### Step 1 - Create Stack - -Use a link in the table to launch the [CloudFormation](https://console.aws.amazon.com/cloudformation/) template in the AWS region that you wish to deploy a Gaia hub. - -![Create stack](/img/cloudformation-create-stack.png) - -### Step 2 - Setup stack using template - -You need to configure the template with the appropiate values for your hub and domain it runs on. - -Select `Template is ready` and `Amazon S3 URL` and enter the following Amazon S3 URL: -``` -https://s3-external-1.amazonaws.com/cf-templates-vzldibfi2mw8-us-east-1/2022160J6G-cloudformation.yaml -``` - -If you prefer you can instead select `Template is ready` and `Upload a template file` to upload the template file `cloudformation.yaml`. - -The latest `cloudformation.yaml` file can be downloaded [here](https://raw.githubusercontent.com/stacks-network/gaia/master/deploy/cloudformation.yaml). On most browsers you can right-click on that page and click on `Save page as` to download the file. Alternatively, you can copy/paste the text into a text file called `cloudformation.yaml`. - -Then click `Next`. - -![Specify template](/img/cloudformation-specify-template.png) - -### Step 3 - Specify stack details - -Specify the stack details and then click `Next`: ![Specify template](/img/cloudformation-specify-stack-details.png) - -| Field | Value | Notes | -| --------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Stack name | _a unique name in your AWS account_ | e.g.: my_gaia_hub | -| DomainName | _your-domain_ | | -| EmailAddress | _your email address_ | | -| GaiaBucketName | _S3 bucket name_ | The template combines this name with the stack name to create a unique S3 bucket. The template ignores this field if GaiaStorageType is set to `disk`. | -| GaiaStorageType | `s3` or `disk` | Select the GaiaStorageType of which to use as a backend for the Gaia Hub. Selecting `s3` causes the template to create an S3 bucket based on the name given in the previous field. Selecting `disk` causes the template to attach a separate EBS volume to the EC2 instance for Hub storage. | -| InstaceType | t2.micro | Select the instance type you want. Default value is `t2.micro`. | -| KeyName | | In the KeyName drop-down, select an [EC2 KeyPair](https://console.aws.amazon.com/ec2/v2/home?region=us-east-1#KeyPairs:) to enable SSH access to the EC2 instance. You should download the `.pem` keyfile for this pair from the EC2 console. For more information see the [EC2 key pair documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html#prepare-key-pair) | -| SSHLocation | 0.0.0.0/0 | Leave the SSHLocation field with the default value of `0.0.0.0/0` to enable SSH access from any IP address. If you wish to restrict SSH access to the EC2 instance to a certain IP, you can update this field. | -| SubnetId | _subnetid_ | Select a public subnet | -| VpcId | _vpcid_ | | - -### Step 4 - Configure stack options - -Configure any stack options that fit your desired setup and click `Next`. All these fields are optional. - -![Specify template](/img/cloudformation-stack-options.png) - -### Step 5 - Review - -Review the configuration of your Gaia hub, select the checkbox to acknowledge that AWS may create IAM resources with custom names and click on `Create stack`. - -![Specify template](/img/cloudformation-iam-resources.png) - -### Step 6 - Retrieve the public IP of your Gaia hub - -Your stack can take several minutes to launch. You can monitor the Events tab of your hub to review the current progress of the launch. When the launch is complete, the Outputs tab displays information about the hub. Select the PublicIP and copy it to configure your domain name. - -Create an `A` DNS record pointing to the given IP in your domain. - -Wait a few minutes for the DNS record to propagate, and your should be able to access your Gaia hub with SSH. - -## Accessing your Gaia hub with SSH - -To SSH into your Gaia hub EC2 host directly, you must have the keyfile used in container creation. Access the host with the following command in your terminal: - -```bash -ssh -i admin@ -``` - -:::tip If you can only access SSH with the IP but not with the DNS name and you wish to do so, you can optionally activate it by following these steps: - - Open your [AWS Console](https://console.aws.amazon.com) - Click on `Service` -> VPC - Open Your VPCs - Select your VPC connected to your Gaia Hub - Click `Actions` -> `Edit DNS Hostnames` -> Change `DNS hostnames` to `Enable` -::: -## Graphical representation of the cloudformation template - -![](/img/cloudformation-gaia-template1-designer.png) \ No newline at end of file diff --git a/i18n/de/docusaurus-plugin-content-docs/current/gaia/gaia.md b/i18n/de/docusaurus-plugin-content-docs/current/gaia/gaia.md deleted file mode 100644 index 1070857350..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/gaia/gaia.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Gaia -description: Decentralized storage architecture for off-chain data -sidebar_position: 5 -tags: - - gaia ---- - -## Introduction - -Apps built with the Stacks blockchain store off-chain data using a storage system called Gaia. - -Whereas public transactional metadata is best stored on the Stacks blockchain, user application data can often be stored more efficiently and privately in Gaia storage. - -Storing data off of the blockchain ensures that Stacks applications can provide users with high performance and high availability for data reads and writes without introducing central trust parties. - -:::tip Latest whitepaper of GAIA (May 2022) is available [here](https://dev1-gaia-hub.s3.amazonaws.com/GAIA_Whitepaper.pdf) ::: - -## Understand Gaia in the Stacks architecture - -The following diagram depicts the Stacks architecture and Gaia's place in it: - -![Stacks Architecture](/img/architecture.png) - -Blockchains require consensus among large numbers of people, so they can be slow. Additionally, a blockchain is not designed to hold a lot of data. This means using a blockchain for every bit of data a user might write and store is expensive. For example, imagine if an application were storing every tweet in the chain. - -The Stacks blockchain addresses performance problems using a layered approach. The base layer consists of the Stacks blockchain and the Blockchain Naming System (BNS). The blockchain governs ownership of identities in the Stacks network. Identities can be names such as domain names, usernames, or application names. - -When an identity is created, its creation is recorded in the Stacks blockchain. Identities make up the primary data stored into the Stacks blockchain. These identities correspond to routing data in the OSI stack. The routing data is stored in the Atlas Peer Network, the second layer. Every core node that joins the Stacks Network is able to obtain an entire copy of this routing data. Stacks uses the routing data to associate identities (domain names, user names, and application names) with a particular storage location in the final layer, the Gaia Storage System. - -A Gaia Storage System consists of a _hub service_ and storage resource on a cloud software provider. The storage provider can be any commercial provider such as Azure, DigitalOcean, Amazon EC2, and so forth. Typically the compute resource and the storage resource reside same cloud vendor, though this is not a requirement. Gaia currently has driver support for S3, Azure Blob Storage, Google Cloud Platform and local disk, but the driver model allows for other backend support as well. - -Gaia stores data as a simple key-value store. When an identity is created, a corresponding data store is associated with that identity on Gaia. When a user logs into a dApp, the authentication process gives the application the URL of a Gaia hub, which then writes to storage on behalf of that user. - -The Stacks blockchain stores only identity data. Data created by the actions of an identity is stored in a Gaia Storage System. Each user has profile data. When a user interacts with a decentralized dApp that application stores application data on behalf of the user. Because Gaia stores user and application data off the blockchain, a Stacks DApp is typically more performant than DApps created on other blockchains. - -## User control or how is Gaia decentralized? - -A Gaia hub runs as a service which writes to data storage. The storage itself is a simple key-value store. The hub service writes to data storage by requiring a valid authentication token from a requestor. Typically, the hub service runs on a compute resource and the storage itself on separate, dedicated storage resource. Typically, both resources belong to the same cloud computing provider. - -![Gaiastorage](/img/gaia-storage.png) - -Gaia's approach to decentralization focuses on user control of data and its storage. Users can choose a Gaia hub provider. If a user can choose which Gaia hub provider to use, then that choice is all the decentralization required to enable user-controlled applications. Moreover, Gaia defines a uniform API for applications to access that data. - -The control of user data lies in the way that user data is accessed. When an application fetches a file `data.txt` for a given user `alice.id`, the lookup will follow these steps: - -1. Fetch the `zonefile` for `alice.id`. -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. Find the read-only url out of the profile's `appsMeta` section (e.g. `https://example-app.gaia.alice.org`). -6. Fetch the file from `https://example-app.gaia.alice.org/data.txt`. - -Because `alice.id` has access to her [zonefile](https://docs.stacks.co/references/bns-contract#name-update), 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. - -:::caution -Users with existing identities cannot yet migrate their data from one hub to another. -::: - -Applications writing directly on behalf of `alice.id` do not need to perform a lookup. Instead, the [Stacks authentication flow](https://stacks.js.org) provides Alice's chosen gaia hub URL to the application. This authentication flow _is also_ within Alice's control because Alice's wallet _must_ generate the authentication response. - -## Understand data storage - -A Gaia hub stores the written data _exactly_ as given. It offers minimal guarantees about the data. It does not ensure that data is validly formatted, contains valid signatures, or is encrypted. Rather, the design philosophy is that these concerns are client-side concerns. - -Client libraries (such as [`Stacks.js`](https://stacks.js.org/)) are capable of providing these guarantees. A liberal definition of the [end-to-end principle](https://en.wikipedia.org/wiki/End-to-end_principle) guides this design decision. - -When an application writes to a Gaia hub, an authentication token, key, and the data are passed to the Gaia hub. - -![Gaia writes](/img/gaia-writes.png) - -The token ensures the app has the authorization to write to the hub on the user's behalf. - -## Gaia versus other storage systems - -Here's how Gaia stacks up against other decentralized storage systems. Features that are common to all storage systems are omitted for brevity. - -| Features | [Gaia](https://github.com/stacks-network/gaia) | [Sia](https://sia.tech/) | [Storj](https://storj.io/) | [IPFS](https://ipfs.io/) | [DAT](https://datproject.org/) | [SSB](https://www.scuttlebutt.nz/) | -| ------------------------------------------ | ---------------------------------------------- | ------------------------ | -------------------------- | ------------------------ | ------------------------------ | ---------------------------------- | -| User controls where data is hosted | X | | | | | | -| Data can be viewed in a normal Web browser | X | | | X | | | -| Data is read/write | X | | | | X | X | -| Data can be deleted | X | | | | X | X | -| Data can be listed | X | X | X | | X | X | -| Deleted data space is reclaimed | X | X | X | X | | | -| Data lookups have predictable performance | X | | X | | | | -| Writes permission can be delegated | X | | | | | | -| Listing permission can be delegated | X | | | | | | -| Supports multiple backends natively | X | | X | | | | -| Data is globally addressable | X | X | X | X | X | | -| Needs a cryptocurrency to work | | X | X | | | | -| Data is content-addressed | | X | X | X | X | X | diff --git a/i18n/de/docusaurus-plugin-content-docs/current/gaia/setup-linux.md b/i18n/de/docusaurus-plugin-content-docs/current/gaia/setup-linux.md deleted file mode 100644 index db427f890a..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/gaia/setup-linux.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: Linux -description: Steps to setup a GAIA hub on a Linux server (fresh install). This example is using Debian, but should work on any Linux distribution. It uses docker compose in the backgroud. -tags: - - tutorial - - gaia ---- - -This configuration will setup the following 4 docker containers: - -- Nginx with certbot on TCP ports 80 and 443. -- Gaia hub on TCP port 3000. -- Gaia admin on TCP port 8009. -- Gaia reader on TCP port 8008 - -**1. Update the system and install the dependencies and software we will use to test:** - -```bash -apt update && apt upgrade -y && apt install -y git vim gnupg jq -``` - -**2. Install [docker](https://docs.docker.com/engine/install/debian/) and [docker-compose](https://docs.docker.com/compose/cli-command/#install-on-linux)** in your OS. -For our example we install _docker_ with: - -```bash -curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg - -echo \ - "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian \ - $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null - -apt update && apt install -y docker-ce docker-ce-cli containerd.io -``` - -Install _docker-compose_ by downloading the [latest-release](https://github.com/docker/compose/releases): - -```bash -VERSION_DC=$(curl --silent https://api.github.com/repos/docker/compose/releases/latest | jq .name -r) -DESTINATION_DC=~/.docker/cli-plugins -mkdir -p ${DESTINATION_DC} -curl -SL https://github.com/docker/compose/releases/download/${VERSION_DC}/docker-compose-linux-x86_64 -o ${DESTINATION_DC}/docker-compose -chmod +x ${DESTINATION_DC}/docker-compose -``` - -**3. Clone the GAIA repository** and enter it's docker directory. - -```bash -git clone https://github.com/stacks-network/gaia.git && cd gaia/deploy/docker -``` - -**4. Copy and edit appropiate .env file**. -In the folder `./deploy/docker/` they are different sample files for different configurations like using aws, azure or disk among others. In this example we will store the data localy so we will copy the _disk_ file and update the domain and email fields. Please change `gaia.site.com` and `gaiarocks@mydomain.com` accordingly. Note you need both for the SSL certificate to be created correctly. - -```bash -export MYGAIADOMAIN=gaia.site.com -export MYGAIAEMAIL=gaiarocks@mydomain.com -cp sample-disk.env disk.env -sed -i 's/my-domain.com/'"$MYGAIADOMAIN"'/g' disk.env -sed -i 's/my-email@example.com/'"$MYGAIAEMAIL"'/g' disk.env - -``` - -**5. Start GAIA HUB service** - -To start GAIA HUB - -```bash -./gaiahub.sh start -``` - -To stop GAIA HUB - -```bash -./gaiahub.sh stop -``` - -To view GAIA HUB status - -```bash -./gaiahub.sh status -``` - -**6. Verify server works locally** with the following command: - -```bash -curl -sk http://localhost/hub_info | jq -``` - -A correct result should look similar to this: - -```bash - { - "challenge_text": "[\"gaiahub\",\"0\",\"gaia-0\",\"blockstack_storage_please_sign\"]", - "latest_auth_version": "v1", - "max_file_upload_size_megabytes": 20, - "read_url_prefix": "https://gaia.site.com/reader/" - } -``` - -**7. Test your GAIA HUB** Running `gaia_test.js` will test your GAIA Hub, by trying to connect to it, uploading a file and downloading it again. - -First install all required dependencies with: - -```bash -npm install -``` - -Then, from the root folder of the project type: - -```bash -node ./deploy/gaia_test.js https://yourgaiaurl -``` - -A correct result will be something like this: - -``` -Will run a test for the GAIA HUB: https://gaia.mydomain.com -Generating some test keys... -Private key: 5aacc60fc2a429e1f02be139f3cac82061c6a980******************** -Public key: 025691f17f2ab80dc4af363bb9c7aac59e9e1db6ae8ff668202582a3f4ec9678ff -Address: 15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS -[DEBUG] connectToGaiaHub: https://gaia.mydomain.com/hub_info -[DEBUG] uploadToGaiaHub: uploading testing.txt to https://gaia.mydomain.com -File uploaded successfully. -Upload to gaia hub thinks it can read it from: https://gaia.mydomain.com/reader/15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS/testing.txt -Hub info thinks it can read it from : https://gaia.mydomain.com/reader/15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS/testing.txt -Let's now try to fetch the uploaded file... -File fetched successfully. Contents of file: GAIA ROCKS! -``` diff --git a/i18n/de/docusaurus-plugin-content-docs/current/gaia/setup-mac.md b/i18n/de/docusaurus-plugin-content-docs/current/gaia/setup-mac.md deleted file mode 100644 index 808833b212..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/gaia/setup-mac.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: MacOS -description: MacOS for local testing/development -tags: - - tutorial ---- - -The following assumes you have [Docker Installed](https://docs.docker.com/docker-for-mac/install/) - -- Recommended to also have [MacOS Homebrew](https://docs.brew.sh/Installation) installed -- Use Homebrew to install jq with `brew install jq` - -In your working directory: - -**1. Clone a copy of the [gaia repo](https://github.com/stacks-network/gaia):** - -```bash -$ git clone -b master --single-branch https://github.com/stacks-network/gaia -``` - -**2. Change your cwd:** - -```bash -$ cd gaia/deploy/docker -``` - -**3. Create a copy of sample-disk.env and fill out the values:** - -``` -$ cp sample-disk.env disk.env -# Update the DOMAIN_NAME variable to `localhost` -``` - -**4. Start the server:** - -``` -$ docker-compose -f docker-compose-base.yaml -f docker-compose-disk.yaml --env-file disk.env up -``` - -**5. Verify the server is responding locally:** - -``` -$ curl -sk https://localhost/hub_info | jq - { - "challenge_text": "[\"gaiahub\",\"0\",\"gaia-0\",\"blockstack_storage_please_sign\"]", - "latest_auth_version": "v1", - "max_file_upload_size_megabytes": 20, - "read_url_prefix": "https://localhost/reader/" - } -``` - -### Modifying the configuration for your gaia-hub - -Two methods exist: - -1. Edit the `gaia/deploy/configs/gaia/hub-config.json` using `vim` or other - -- requires a restart of the containers: `docker-compose -f docker-compose-base.yaml -f docker-compose-disk.yaml --env-file disk.env restart` - -2. Use the running `admin` container to modify any config values, and also reload the hub when complete: - -- [GitHub - Gaia Admin README.md](https://github.com/stacks-network/gaia/blob/master/admin/README.md) - -``` -$ export API_KEY="hello" -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - -H 'Content-Type: application/json' \ - -X POST \ - --data-raw '{"serverName": "myserver"}' \ - http://localhost:8009/v1/admin/config - -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - -X POST \ - http://localhost:8009/v1/admin/reload - -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - http://localhost:8009/v1/admin/config | jq -``` diff --git a/i18n/de/docusaurus-plugin-content-docs/current/governance/_index.md b/i18n/de/docusaurus-plugin-content-docs/current/governance/_index.md deleted file mode 100644 index 1ecdf67871..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/governance/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Governance -description: Governance -sidebar_position: 9 ---- - -This page needs contributions. Help us write it! \ No newline at end of file diff --git a/i18n/de/docusaurus-plugin-content-docs/current/governance/index.md b/i18n/de/docusaurus-plugin-content-docs/current/governance/index.md deleted file mode 100644 index 91b0215b5f..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/governance/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Governance -description: Governance -sidebar_position: 9 ---- - -![](/img/stacks-governance.png) - -This page needs contributions. Help us write it! - -Governance in web3 is driven by the community. - -How can I get involved ? - -[Governance Resources website](https://resources.stacksgov.com) - -[Github - Stack Community Governance](https://github.com/stacksgov) - -:::tip Community Calls Monthly community calls are recorded and available [here](https://www.youtube.com/playlist?list=PLg717Ri_rTnwwYjQYlc7rIP6x2FaTNn7f) ::: diff --git a/i18n/de/docusaurus-plugin-content-docs/current/governance/sips.md b/i18n/de/docusaurus-plugin-content-docs/current/governance/sips.md deleted file mode 100644 index 29ac1ae1ed..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/governance/sips.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: SIPs -description: SIPs -sidebar_position: 9 ---- - -## Stacks Improvement Proposals (SIPs) - -Stacks improvement proposals (SIPs) are aimed at describing the implementation of the Stacks blockchain, as well as proposing improvements. - -The SIP process [(SIP-000)](https://github.com/stacksgov/sips/blob/main/sips/sip-000/sip-000-stacks-improvement-proposal-process.md) describes how to make a SIP and get it ratified. - -They should contain concise technical specifications of features or standards and the rationale behind it. SIPs are intended to be the primary medium for proposing new features, for collecting community input on a system-wide issue, and for documenting design decisions. - -The SIPs are located in the [stacksgov/sips](https://github.com/stacksgov/sips) repository as part of the [Stacks Community Governance organization](https://github.com/stacksgov). - -Anyone in the Stacks community can submit a SIP. - -:::tip Stacks Improvement Proposals Community Calls SIP Meeting calls are recorded and available [here](https://www.youtube.com/playlist?list=PLg717Ri_rTnx5kuaWqp3cUAtwQk_yzslT) - -More details of the meetings are available [here](https://github.com/stacksgov/sips/issues/79) ::: - -## Ratified SIPSs - -- [x] [SIP 001: Burn Election](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md) -- [x] [SIP 002: Clarity, a language for predictable smart contracts](https://github.com/stacksgov/sips/blob/main/sips/sip-002/sip-002-smart-contract-language.md) -- [x] [SIP 003: Peer Network](https://github.com/stacksgov/sips/blob/main/sips/sip-003/sip-003-peer-network.md) -- [x] [SIP 004: Cryptographic Committment to Materialized Views](https://github.com/stacksgov/sips/blob/main/sips/sip-004/sip-004-materialized-view.md) -- [x] [SIP 005: Blocks, Transactions, and Accounts](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md) -- [x] [SIP 006: Clarity Execution Cost Assessment](https://github.com/stacksgov/sips/blob/main/sips/sip-006/sip-006-runtime-cost-assessment.md) -- [x] [SIP 007: Stacking Consensus](https://github.com/stacksgov/sips/blob/main/sips/sip-007/sip-007-stacking-consensus.md) -- [x] [SIP 008: Clarity Parsing and Analysis Cost Assessment](https://github.com/stacksgov/sips/blob/main/sips/sip-008/sip-008-analysis-cost-assessment.md) -- [x] [SIP 009: Standard Trait Definition for Non-Fungible Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-009/sip-009-nft-standard.md) -- [x] [SIP 010: Standard Trait Definition for Fungible Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-010/sip-010-fungible-token-standard.md) -- [x] [SIP 012: Burn Height Selection for a Network Upgrade to Introduce New Cost-Limits](https://github.com/stacksgov/sips/blob/main/sips/sip-012/sip-012-cost-limits-network-upgrade.md) -- [x] [SIP-016: Metadata for Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-016/sip-016-token-metadata.md) - -## How to Get Involved - -There are several ways you can get involved with the SIP process: - -* **Join the weekly SIP Meeting call** listed [here](https://community.stacks.org/events). - -* **SIP Editor**. SIP editors help SIP authors make sure their SIPs are well-formed and follow the right process. They help get SIPs ready for deep review by advancing it them from Draft to Accepted status. If you want to become a SIP editor, open an issue with your name and email to ask to be added to the list of SIP editors. - -* **Join a CAB** (Consideration Advisory Board). SIPs fall under the purview of one or more considerations. A full list is in [this github](https://github.com/stacksgov/sips/tree/main/considerations) directory. Currently they are: Diversity, Economics, Ethics, Governance and Technical. Members of SIP consideration advisory boards use their domain expertise to give Accepted SIPs a deep read, and give the authors any/all feedback to help make the SIP workable. If you want to join a board, reach out to the board's chairperson via the listed contact information. - -* **Steering Committee**. The Steering Committee organizes the consideration advisory boards and votes to advance Recommended SIPs to Activation-in-Progress status, and then to either Ratified or Rejected status. Once they are in the process of being activated, they use a SIP's Activation section to determine whether or not the Stacks ecosystem has ratified or rejected the SIP. Joining this committee requires the consent of the Stacks Foundation board. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/intro.md b/i18n/de/docusaurus-plugin-content-docs/current/intro.md deleted file mode 100644 index 84f1eaa649..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/intro.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_label: "Home" -sidebar_position: 1 ---- - -# Stacks Docs Introduction - -Welcome to the community driven official Stacks Documentation. - -Learn about Stacks mining, the STX token, and the Clarity smart contract language. - -![](/img/Bitcoinet-L_2.svg) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md b/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md deleted file mode 100644 index dd7194f504..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Stacks on DigitalOcean -description: A guide to setup Stacks on DigitalOcean -sidebar_position: 4 -tags: - - tutorial ---- - -## Introduction - -This is a step by step guide to deploy the [Stacks Blockchain on DigitalOcean](https://marketplace.digitalocean.com/apps/stacks-blockchain). Code is hosted on this [Github repository](https://github.com/stacks-network/stacks-blockchain-docker). - -## Steps - -#### Step 1 - -Go to the [Stacks Blockchain page](https://marketplace.digitalocean.com/apps/stacks-blockchain) in DigitalOcean's marketplace. Click on `Create Stacks Blockchain Droplet`. - -#### Step 2 - -Choose a plan (it will only allow you to select a plan that meets the minimum requirements) and your prefered datacenter region. ![](/img/sh_digitalocean-choose-plan.png) - -#### Step 3 - -Enter a root password or enable SSH keys if your prefer. - -![](/img/sh_digitalocean-choose-authentication.png) - -#### Step 4 - -You can leave the rest of the options as they are and click on `Create Droplet` - -#### Step 5 - -You will need to wait a few seconds for the droplet to get created. Once created click on it to see more information. - -![](/img/sh_digitalocean-creating-droplet.png) - -![](/img/sh_digitalocean-created-droplet.png) - -### Step 6 - -Congratulations! You are now running the Stacks Blockchain. You can click on `Console` for a terminal window to open or login using SSH to the public IP you've been assigned to with user `root`. - -![](/img/sh_digitalocean-console-button.png) ![](/img/sh_digitalocean-console.png) - -## Getting started after deploying Stacks Blockchain - -Once droplet is launched, initial startup can take several minutes while BNS data is imported (this is a one time operation). - -To keep track of the progress, you can `ssh root@your_droplet_public_ipv4` to the host and run: `/opt/stacks-blockchain-docker/manage.sh -n mainnet -a logs`. - -Once the stacks blockchain starts to sync with peers, application ports will open and nginx port 80 will now start proxying requests. - -Use `http://your_droplet_public_ipv4` to access the data directly, with output being similar to: - -```json -{ - "server_version": "stacks-blockchain-api v3.0.3 (master:cd0c8aef)", - "status": "ready", - "chain_tip": { - "block_height": 16220, - "block_hash": "0x3123fba9c0de6b569573494cf83c1d5d198a66bfd5f48ef97949b6bf11ba13be", - "index_block_hash": "0xeec960fbbd6186b4ccac85ce12adba72be497d881f81e077305c90955b51a6ae" - } -} -``` - -All services are managed by a [systemd unit file](https://github.com/stacksfoundation/stacks-machine-images/blob/master/files/etc/systemd/system/stacks.service) that is set to start on boot. - -Manual control is also possible via the [manage.sh script](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/manage.sh) at `/opt/stacks-blockchain-docker/manage.sh` on the host. - -Full details on how to use the manage.sh script is [available here](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/README.md#quickstart). - -## API Creation - -In addition to creating a Droplet from the Stacks Blockchain 1-Click App via the control panel, you can also use the [DigitalOcean API](https://digitalocean.com/docs/api). - -As an example, to create a 4GB Stacks Blockchain Droplet in the SFO2 region, you can use the following curl command. You’ll need to either save your [API access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/) to an environment variable or substitute it into the command below. - -```bash -curl -X POST -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer '$TOKEN'' -d \ - '{"name":"choose_a_name","region":"sfo2","size":"s-2vcpu-4gb","image":"stacksfoundation-stacksblockchain"}' \ - "https://api.digitalocean.com/v2/droplets" -``` diff --git a/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md b/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md deleted file mode 100644 index b6cbb9754a..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Nodes and Miners -description: Nodes and Miners -sidebar_position: 7 ---- - -Here are all the steps to run nodes and miners, both on mainnet and testnet. - -## What's a Stacks node? - -## What's a Stacks miner? diff --git a/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md b/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md deleted file mode 100644 index 40397a51e0..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Miner costs and fees -description: Miner Cost and Fee Estimation -sidebar_position: 8 ---- - -## Configuring Cost and Fee Estimation - -Fee and cost estimators can be configured via the config section `[fee_estimation]`: - -``` -[fee_estimation] -cost_estimator = naive_pessimistic -fee_estimator = fuzzed_weighted_median_fee_rate -fee_rate_fuzzer_fraction = 0.1 -fee_rate_window_size = 5 -cost_metric = proportion_dot_product -log_error = true -enabled = true -``` - -Fee and cost estimators observe transactions on the network and use the observed costs of those transactions to build estimates for viable fee rates and expected execution costs for transactions. Estimators and metrics can be selected using the configuration fields above, though the default values are the only options currently. `log_error` controls whether or not the INFO logger will display information about the cost estimator accuracy as new costs are observed. Setting `enabled = false` turns off the cost estimators. Cost estimators are **not** consensus-critical components, but rather can be used by miners to rank transactions in the mempool or client to determine appropriate fee rates for transactions before broadcasting them. - -The `fuzzed_weighted_median_fee_rate` uses a median estimate from a window of the fees paid in the last `fee_rate_window_size` blocks. Estimates are then randomly "fuzzed" using uniform random fuzz of size up to `fee_rate_fuzzer_fraction` of the base estimate. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md b/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md deleted file mode 100644 index 59528c33e1..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md +++ /dev/null @@ -1,430 +0,0 @@ ---- -title: Mine mainnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 mainnet -sidebar_position: 5 -tags: - - tutorial ---- - -## Introduction - -Make sure you've followed the [run a node](run-a-node) procedure. Once completed it's only a few more steps to run a proof-of-burn miner on the mainnet. - -If you're interested in mining on the testnet, you can find instructions on how to do that [here](miner-testnet): - -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining): - -## Running bitcoind locally - -To participate as a miner on mainnet, you must have access to a mainnet bitcoin node. One way to accomplish this is to run bitcoind locally. [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements) - -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. - -Next, start bitcoind with the following configuration: - -```toml -server=1 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=1 -banscore=1 -bind=0.0.0.0:8333 -rpcbind=0.0.0.0:8332 -rpcport=8332 -``` - -Finally, start bitcoind as follows: - -```bash -bitcoind -conf=path/to/bitcoin.conf -``` - -It may take a few days for the node to synchronize with the Bitcoin mainnet. - -## Running a miner - -First, a keychain needs to be generated. With this keychain, we'll purchase some BTC from a crytpocurrency exchange, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. We'll use the `make_keychain` command. - -```bash -npx @stacks/cli make_keychain 2>/dev/null | json_pp > keychain.txt -``` - -After this runs, you should see some JSON in the new `keychain.txt` file that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -**Don't lose this information** - we'll need to use the `privateKey` field later on. - -The above BTC address will then need to be imported into the BTC network. - -```bash -bitcoin-cli -rpcport=8332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - - - -Once imported, we need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - - - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/mainnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... - -[burnchain] -... -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `make_keychain` command. Replace the `seed` field with your private key. Save and close this configuration file. - -To run your miner, run this in the command line: - -```bash -stacks-node start --config=./testnet/stacks-node/conf/mainnet-miner-conf.toml -``` - -Your node should start. It will take some time to sync, and then your miner will be running. - -### Creating an optimized binary - -The steps above are great for trying to run a node temporarily. If you want to host a node on a server somewhere, you might want to generate an optimized binary. To do so, use the same configuration as above, but run: - -```bash -cd testnet/stacks-node -cargo build --release --bin stacks-node -``` - -The above code will compile an optimized binary. To use it, run: - -```bash -cd ../.. -./target/release/stacks-node start --config=./mainnet-miner-conf.toml -``` - -To read more about the technical details of mining on the Stacks 2.0 network, have a look at [the mining guide](../understand-stacks/mining). - -### Enable debug logging - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -STACKS_LOG_DEBUG=1 stacks-node mainnet -``` - -## Running a miner in Windows - -### Prerequisites - -Make sure are [running a node](run-a-node) and [running bitcoind locally](#running-bitcoind-locally) before starting this tutorial. - -### Generate keychain and get mainnet tokens in Windows - -To setup the miner, first we need to generate a keychain. With this keychain, we'll purchase some BTC from a crytpocurrency exchange, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. To get a keychain, the simplest way is to use the `stacks-cli`. - -Generate a keychain: - -```bash -npm install --global @stacks/cli -stx make_keychain > cli_keychain.json -type cli_keychain.json -``` - -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -The above BTC address will then need to be imported into the BTC network. - -```bash -bitcoin-cli -rpcport=8332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - -Once imported, we need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Update configuration file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/mainnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... - -[burnchain] -... -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Run the miner - -To start your miner, run this in the command line: - -```bash -stacks-node start --config=testnet/stacks-node/conf/mainnet-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](/img/windows-defender.png) - -Your node should start. It will take some time to sync, and then your miner will be running. - -### Enable debug logging in Windows - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=mainnet-miner-conf.toml -``` - -## Optional: Running with Docker - -Alternatively, you can run the mainnet node with Docker. - -:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: - -### Generate keychain and get tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null -``` - -We need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Update configuration file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/mainnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... - -[burnchain] -... -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Start the miner - -:::info The ENV VARS `RUST_BACKTRACE` and `STACKS_LOG_DEBUG` are optional. If removed, debug logs will be disabled ::: - -```bash -docker run -d \ - --name stacks_miner \ - --rm \ - --network host \ - -e RUST_BACKTRACE="full" \ - -e STACKS_LOG_DEBUG="1" \ - -v "$(pwd)/testnet/stacks-node/conf/mainnet-miner-conf.toml:/src/stacks-node/mainnet-miner-conf.toml" \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain:latest \ -/bin/stacks-node start --config /src/stacks-node/mainnet-miner-conf.toml -``` - -You can review the node logs with this command: - -```bash -docker logs -f stacks_miner -``` - -## Optional: Running in Kubernetes with Helm - -In addition, you're also able to run a mainnet node in a Kubernetes cluster using the [stacks-blockchain Helm chart](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). - -Ensure you have the following prerequisites installed on your machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [minikube](https://minikube.sigs.k8s.io/docs/start/) (Only needed if standing up a local Kubernetes cluster) -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [helm](https://helm.sh/docs/intro/install/) - -### Generate keychain and get some tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null -``` - -We need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Install the chart and run the miner - -To install the chart with the release name `my-release` and run the node as a miner: - -```bash -minikube start # Only run this if standing up a local Kubernetes cluster -helm repo add blockstack https://charts.blockstack.xyz -helm install my-release blockstack/stacks-blockchain \ - --set config.node.miner=true \ - --set config.node.seed="replace-with-your-privateKey-from-generate-keychain-step" \ - --set config.burnchain.mode="mainnet" -``` - -You can review the node logs with this command: - -```bash -kubectl logs -l app.kubernetes.io/name=stacks-blockchain -``` - -For more information on the Helm chart and configuration options, please refer to the [chart's homepage](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). diff --git a/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md b/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md deleted file mode 100644 index 3e2343d344..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md +++ /dev/null @@ -1,417 +0,0 @@ ---- -title: Mine testnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 testnet -sidebar_position: 4 -tags: - - tutorial ---- - -## Introduction - -Make sure you've followed the [Run a node](run-a-node) procedure. Once completed it's only a few more steps to run a proof-of-burn miner on the testnet. - -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining). - -## Running bitcoind locally - -To participate as a miner on Testnet, you must have access to a testnet bitcoin node. One way to accomplish this is to run bitcoind locally. [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements) - -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. - -Next, start bitcoind with the following configuration: - -```toml -server=1 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password -testnet=1 -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=1 -banscore=1 - -[test] -bind=0.0.0.0:18333 -rpcbind=0.0.0.0:18332 -rpcport=18332 -``` - -Finally, start bitcoind as follows: - -```bash -bitcoind -conf=path/to/bitcoin.conf -``` - -It may take a few hours for the node to synchronize with the Bitcoin testnet. - -## Running a miner - -First, a keychain needs to be generated. With this keychain, we'll get some testnet BTC from a faucet, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. To get a keychain, the simplest way is to use the `stacks-cli`. - -```bash -npx @stacks/cli make_keychain -t 2>/dev/null | json_pp > keychain.txt -``` - -After this runs, you should see some JSON in the new `keychain.txt` file that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -**Don't lose this information** - we'll need to use the `privateKey` field later on. - -The above BTC address will then need to be imported into the BTC testnet network. - -```bash -bitcoin-cli -rpcport=18332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - -Once imported, we need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). You'll be sent `0.01` testnet BTC to that address. - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/testnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/testnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... - -[burnchain] -... -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `make_keychain` command. Replace the `seed` field with your private key. Save and close this configuration file. - -To run your miner, run this in the command line: - -```bash -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. - -### Creating an optimized binary - -The steps above are great for trying to run a node temporarily. If you want to host a node on a server somewhere, you might want to generate an optimized binary. To do so, use the same configuration as above, but run: - -```bash -cd testnet/stacks-node -cargo build --release --bin stacks-node -``` - -The above code will compile an optimized binary. To use it, run: - -```bash -cd ../.. -./target/release/stacks-node start --config=./testnet/conf/testnet-follower-conf.toml -``` - -To read more about the technical details of mining on the Stacks 2.0 network, have a look at [the minig guide](../understand-stacks/mining): - -### Enable debug logging - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -STACKS_LOG_DEBUG=1 stacks-node testnet -``` - -## Running a miner in Windows - -### Prerequisites - -Make sure are [running a testnet node](run-a-node) before starting this tutorial. - -### Generate keychain and get testnet tokens in Windows - -To setup the miner, first, we need to generate a keychain. With this keychain, we'll get some testnet BTC from a faucet, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. We'll use the `stx make-keychain` command, and pass `-t` to indicate that we want a testnet keychain. - -Generate a keychain: - -```bash -npm install --global @stacks/cli -stx make_keychain -t > cli_keychain.json -type cli_keychain.json -``` - -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -Request BTC from faucet: - -We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). - -### Update configuration file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/testnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/testnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... - -[burnchain] -... -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Run the miner - -To start your miner, run this in the command line: - -```bash -stacks-node start --config=testnet/stacks-node/conf/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](/img/windows-defender.png) - - - -Your node should start. It will take some time to sync, and then your miner will be running. - -### Enable debug logging in Windows - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=testnet-miner-conf.toml -``` - -## Optional: Running with Docker - -Alternatively, you can run the testnet node with Docker. - -:::warning Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: - -### Generate keychain and get testnet tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` - -We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). - -### Update config file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/testnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/testnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... - -[burnchain] -... -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Start the miner - -:::info The ENV VARS `RUST_BACKTRACE` and `STACKS_LOG_DEBUG` are optional. If removed, debug logs will be disabled ::: - -```bash -docker run -d \ - --name stacks_miner \ - --rm \ - --network host \ - -e RUST_BACKTRACE="full" \ - -e STACKS_LOG_DEBUG="1" \ - -v "$(pwd))/testnet/stacks-node/conf/testnet-miner-conf.toml:/src/stacks-node/testnet-miner-conf.toml" \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain:latest \ -/bin/stacks-node start --config /src/stacks-node/testnet-miner-conf.toml -``` - -You can review the node logs with this command: - -```bash -docker logs -f stacks_miner -``` - -## Optional: Running in Kubernetes with Helm - -In addition, you're also able to run a testnet node in a Kubernetes cluster using the [stacks-blockchain Helm chart](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). - -Ensure you have the following prerequisites installed on your machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [minikube](https://minikube.sigs.k8s.io/docs/start/) (Only needed if standing up a local Kubernetes cluster) -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [helm](https://helm.sh/docs/intro/install/) - -### Generate keychain and get some testnet tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` - -We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). - -### Install the chart and run the miner - -To install the chart with the release name `my-release` and run the node as a miner: - -```bash -minikube start # Only run this if standing up a local Kubernetes cluster -helm repo add blockstack https://charts.blockstack.xyz -helm install my-release blockstack/stacks-blockchain \ - --set config.node.miner=true \ - --set config.node.seed="replace-with-your-privateKey-from-generate-keychain-step" -``` - -You can review the node logs with this command: - -```bash -kubectl logs -l app.kubernetes.io/name=stacks-blockchain -``` - -For more information on the Helm chart and configuration options, please refer to the [chart's homepage](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). diff --git a/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md b/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md deleted file mode 100644 index 94d938c5ca..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md +++ /dev/null @@ -1,351 +0,0 @@ ---- -title: Run a node -description: Set up and run a Stacks node -sidebar_position: 1 -tags: - - tutorial ---- - -## Stacks Blockchain with Docker - -Run your own Stacks Blockchain node easily with just few commands. - -This tutorial describes a simple and effective [quickstart](#quickstart) to run a Stacks node using public scripts hosted in [Stacks Blockchain repository](https://github.com/stacks-network/stacks-blockchain-docker). Valid for mainnet, testnet and mocknet. - -## **Quickstart** - -1. **Clone the stacks-blockchain-docker repository locally** - -```bash -git clone https://github.com/stacks-network/stacks-blockchain-docker && cd stacks-blockchain-docker -``` - -2. **Optionally, create/copy `.env` file**. If file `.env` doesn't exist when launched it will be created from `sample.env` automatically. - -```bash -cp sample.env .env -``` - -_You may also use a symlink as an alternative to copying: `ln -s sample.env .env`_ - -3. **Optionally, ensure all images are up to date** - -```bash -./manage.sh -n -a pull -``` - -4. **Start the Services** - -```bash -./manage.sh -n -a start -``` - -- With optional proxy: - -```bash -./manage.sh -n -a start -f proxy -``` - -- With optional bitcoin node: - -```bash -./manage.sh -n -a start -f bitcoin -``` - -5. **Stop the Services** - -```bash -./manage.sh -n -a stop -``` - -6. **Retrieve Service Logs** - -```bash -./manage.sh -n -a logs -``` - -- Export docker log files to `./exported-logs`: - -This will create one log file for every running service, for example: postgres.log, stacks-blockain.log, stacks-blockchain-api.log and bitcoin-core.log. -Notice that each time you run this command the log files will be overwritten. - -```bash -./manage.sh -n -a logs export -``` - -7. **Restart all services** - -```bash -./manage.sh -n -a restart -``` - -- With optional proxy: - -```bash -./manage.sh -n -a restart -f proxy -``` - -8. **Delete** all data in `./persistent-data/` and/or data of the Bitcoin blockchain. - - This data is owned by root, so you will need to run it with sudo privileges so it can delete the data. - -```bash -$ sudo ./manage.sh -n -a reset - -Please confirm what persistent data you wish to delete: - -0. Cancel -1. Delete Persistent data for Stacks testnet only and leave Bitcoin blockchain data unaffected. -2. Delete Persistent data for Stacks testnet and Bitcoin blockchain data in ./persistent-data/blockchain-bitcoin -3. Delete Persistent data for Bitcoin blockchain data in ./persistent-data/blockchain-bitcoin only. -Please note that BNS data will never get deleted. - -Type 0, 1, 2 or 3: 2 - -Ok. Delete Stacks and Bitcoin data. -[ Success ] Persistent data deleted for Bitcoin blockchain. -[ Success ] Persistent data deleted for Stacks testnet. - -``` - -9. **Download BNS data to** `./persistent-data/bns-data` - -```bash -./manage.sh bns -``` - -10. **Export stacks-blockchain-api events** (_Not applicable for mocknet_) - -```bash -./manage.sh -n -a export -# check logs for completion -./manage.sh -n -a restart -``` - -11. **Replay stacks-blockchain-api events** (_Not applicable for mocknet_) - -```bash -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart -``` - -## **Running also a bitcoin node (Optional)** - -Stacks needs to use a Bitcoin node, and by default when you run a Stacks node you will be using a public Bitcoin node, which is configured in the `.env` file. Default values is `BITCOIN_NODE=bitcoin.mainnet.stacks.org`. - -However, you can optionaly run both nodes together and configured in a way that you Stacks node will use your own Bitcoin node instead of a public one. - -If you run the script with a bitcoin node it will download and build it directly from source for increased security. This process which only needs to happen once can take up to 20-30 minutes depending on the speed of your system. Also, once the bitcoin node is up and running it will need an additional time for sync for the first time (can be hours for testnet and days for mainnet). - -### Why run Stacks node with your own Bitcoin node? - -Because running your own Bitcoin node will give you higher security and improved perfomance. - -* **Improved perfomance**: The Bitcoin node will serve you blocks faster, as well as UTXOs for your miner (if you run one). -* **Higher security**: The Bitcoin node will also have validated all bitcoin transactions the Stacks node consumes. If you don't run your own Bitcoin node, you're relying on the SPV headers to vouch for the validity of Bitcoin blocks. - -The disadvantage of running your own Bitcoin node is that you need the extra space to store the Bitcoin blockchain (about 500GB) and the initial time it will take to download this data the first time. - -### Example - -You can run easily run your Stacks node with your own Bitcoin node by adding the flag `bitcoin`. This is available only for testnet and mainnet. - -Example: `./manage.sh -n mainnet -a start -f bitcoin` or `./manage.sh -n testnet -a start -f bitcoin` - -### Bitcoin node configuration - -In the `.env` file there is the variable `BITCOIN_BLOCKCHAIN_FOLDER`. As the bitcoin blockchain can be large (over 500GB) you optionally change this variable to any location of your choosing. If you have previously used the [bitcoin core application](https://bitcoin.org/en/bitcoin-core/) and already have the bitcoin blockchain synced, you can use the same data folder and avoid redownloading the entire bitcoin blockchain. - -## **Accessing the services** - -:::tip For networks other than `mocknet`, downloading the initial headers can take several minutes. Until the headers are downloaded, the `/v2/info` endpoints won't return any data. - -Use the command `./manage.sh -n -a logs` to check the sync progress. ::: - -**stacks-blockchain**: - -- Ports `20443-20444` are exposed to `localhost` - -```bash -curl -sL localhost:20443/v2/info | jq -``` - -**stacks-blockchain-api**: - -- Port `3999` are exposed to `localhost` - -```bash -curl -sL localhost:3999/v2/info | jq -``` - -**proxy**: - -- Port `80` is exposed to `localhost` - -```bash -curl -sL localhost/v2/info | jq -curl -sL localhost/ | jq -``` - ---- - -## Upgrades - -⚠️ For upgrades to running instances of this repo, you'll need to [run the event-replay](https://github.com/hirosystems/stacks-blockchain-api#event-replay): - -```bash -./manage.sh -n -a stop -./manage.sh -n -a export -./manage.sh -n -a import -./manage.sh -n -a restart -``` - ---- - -## **Workarounds to potential issues** - -_**Port(s) already in use**_: - -- 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. `3999` and edit your `.env` file to use the new port. - -```bash -netstat -anl | grep 3999 -``` - -``` -tcp46 0 0 *.3999 *.* LISTEN -``` - -_**Containers not starting (hanging on start)**_: - -- Occasionally, docker can get **stuck** and not allow new containers to start. If this happens, simply restart your docker daemon and try again. - -_**Database Issues**_: - -- For any of the various Postgres/sync issues, it may be easier to simply remove the persistent data dir. Note that doing so will result in a longer startup time as the data is repopulated. - -```bash -./manage.sh -n -a stop -./manage.sh -n -a reset -./manage.sh -n -a start -``` - -_**API Missing Parent Block Error**_: - -- If the Stacks blockchain is no longer syncing blocks, and the API reports an error similar to this:\ - `Error processing core node block message DB does not contain a parent block at height 1970 with index_hash 0x3367f1abe0ee35b10e77fbcaa00d3ca452355478068a0662ec492bb30ee0f13e"`,\ - The API (and by extension the DB) is out of sync with the blockchain. \ - The only known method to recover is to resync from genesis (**event-replay _may_ work, but in all likelihood will restore data to the same broken state**). - -- To attempt the event-replay - -```bash -./manage.sh -n -a stop -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart -``` - -- To wipe data and re-sync from genesis - -```bash -./manage.sh -n -a stop -./manage.sh -n -a reset -./manage.sh -n -a restart -``` - - -## **Requirements:** - -- [Docker](https://docs.docker.com/get-docker/) >= `17.09` -- [docker-compose](https://github.com/docker/compose/releases/) >= `1.27.4` -- [git](https://git-scm.com/downloads) -- [jq binary](https://stedolan.github.io/jq/download/) -- [sed](https://www.gnu.org/software/sed/) -- Machine with (at a minimum): - - 4GB memory - - 1 Vcpu - - 50GB storage (600GB if you optionally also run the bitcoin mainnet node) - -:::caution MacOS with an M1 processor is NOT recommended - -The way Docker for Mac on an Arm chip is designed makes the I/O incredibly slow, and blockchains are **_very_** heavy on I/O. This only seems to affect MacOS, other Arm based systems like Raspberry Pi's seem to work fine. - -::: - - -### Install/Update docker-compose - -:::note `docker-compose` executable is required, even though recent versions of Docker contain `compose` natively ::: - -- [Install Docker-compose](https://docs.docker.com/compose/install/) -- [Docker Desktop for Mac](https://docs.docker.com/docker-for-mac/install/) -- [Docker Desktop for Windows](https://docs.docker.com/docker-for-windows/install/) -- [Docker Engine for Linux](https://docs.docker.com/engine/install/#server) - -First, check if you have `docker-compose` installed locally. - -To do that, run this command in your terminal : - -```bash -docker-compose --version -``` - -Output should look something very similar to this : - -``` -docker-compose version 1.27.4, build 40524192 -``` - -If the command is not found, or the version is < `1.27.4`, run the following to install the latest to `/usr/local/bin/docker-compose`: - -```bash -#You will need to have jq installed, or this snippet won't run. -VERSION=$(curl --silent https://api.github.com/repos/docker/compose/releases/latest | jq .name -r) -DESTINATION=/usr/local/bin/docker-compose -sudo curl -L https://github.com/docker/compose/releases/download/${VERSION}/docker-compose-$(uname -s)-$(uname -m) -o $DESTINATION -sudo chmod 755 $DESTINATION -``` - -### Security note on docker - -The Docker daemon always runs as the root user so by default you will need root privileges to interact with it. - -The script `manage.sh` uses docker, so to avoid the requirement of needing to run the script with root privileges it is prefered to be able to *manage Docker as a non-root user*, following [these simple tests](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user). - -This will avoid the need of running the script with root privileges for all operations except the removal of data. - -### Configuration files you can edit - -The following files can be modified to personalize your node configuration, but generally most of them should be left as-is. All these files will be created from the sample copy if they don't exist at runtime (for example `.env` is created from `sample.env`). However these files will never be modified by the application once created and will never be pushed back to github, so your changes will be safe. - -* `.env` -* `./conf/mainnet/Config.toml` -* `./conf/mainnet/bitcoin.conf` -* `./conf/testnet/Config.toml` -* `./conf/testnet/bitcoin.conf` - -By default: - -- BNS data is **not** enabled/imported - - To enable, uncomment `# BNS_IMPORT_DIR=/bns-data` in `./env` - - Download BNS data: `./manage.sh bns` -- Fungible token metadata is **not** enabled - - To enable, uncomment `# STACKS_API_ENABLE_FT_METADATA=1` in `./env` -- Non-Fungible token metadata is **not** enabled - - To enable, uncomment `# STACKS_API_ENABLE_NFT_METADATA=1` in `./env` -- Verbose logging is **not** enabled - - To enable, uncomment `# VERBOSE=true` in `./env` -- Bitcoin blockchain folder is configured in `BITCOIN_BLOCKCHAIN_FOLDER` in `./env` - -### Local Data Dirs - -Directories will be created on first start that will store persistent data under `./persistent-data/` - -`` can be 1 of: - -- mainnet -- testnet -- mocknet diff --git a/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md b/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md deleted file mode 100644 index 09db354d0d..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md +++ /dev/null @@ -1,188 +0,0 @@ ---- -title: Running a mainnet node -description: Set up and run a mainnet node with Docker -sidebar_position: 3 -tags: - - tutorial ---- - -## Introduction - -This procedure demonstrates how to run a local mainnet node using Docker images. - -:::caution -This procedure focuses on Unix-like operating systems (Linux and MacOS). This procedure has not been tested on Windows. -::: - -## Prerequisites - -Running a node has no specialized hardware requirements. Users have been successful in running nodes on Raspberry Pi boards and other system-on-chip architectures. In order to complete this procedure, you must have the following software installed on the node host machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [curl](https://curl.se/download.html) -- [jq](https://stedolan.github.io/jq/download/) - -### Firewall configuration - -In order for the API node services to work correctly, you must configure any network firewall rules to allow traffic on the ports discussed in this section. The details of network and firewall configuration are highly specific to your machine and network, so a detailed example isn't provided. - -The following ports must open on the host machine: - -Ingress: - -- stacks-blockchain (open to `0.0.0.0/0`): - - `20443 TCP` - - `20444 TCP` - -Egress: - -- `8332` -- `8333` -- `20443-20444` - -These egress ports are for syncing stacks-blockchain and Bitcoin headers. If they're not open, the sync will fail. - -## Step 1: initial setup - -In order to run the mainnet node, you must download the Docker images and create a directory structure to hold the persistent data from the services. Download and configure the Docker images with the following commands: - -```sh -docker pull blockstack/stacks-blockchain -``` - -Create a directory structure for the service data with the following command: - -```sh -mkdir -p ./stacks-node/{persistent-data/stacks-blockchain/mainnet,config/mainnet} && cd stacks-node -``` - -## Step 2: running Stacks blockchain - -First, create the `./config/mainnet/Config.toml` file and add the following content to the file using a text editor: - -```toml -[node] -working_dir = "/root/stacks-node/data" -rpc_bind = "0.0.0.0:20443" -p2p_bind = "0.0.0.0:20444" -bootstrap_node = "02da7a464ac770ae8337a343670778b93410f2f3fef6bea98dd1c3e9224459d36b@seed-0.mainnet.stacks.co:20444,02afeae522aab5f8c99a00ddf75fbcb4a641e052dd48836408d9cf437344b63516@seed-1.mainnet.stacks.co:20444,03652212ea76be0ed4cd83a25c06e57819993029a7b9999f7d63c36340b34a4e62@seed-2.mainnet.stacks.co:20444" -wait_time_for_microblocks = 10000 - -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "bitcoin.blockstack.com" -username = "blockstack" -password = "blockstacksystem" -rpc_port = 8332 -peer_port = 8333 - -[connection_options] -read_only_call_limit_write_length = 0 -read_only_call_limit_read_length = 100000 -read_only_call_limit_write_count = 0 -read_only_call_limit_read_count = 30 -read_only_call_limit_runtime = 1000000000 -``` - -Start the `stacks-blockchain` container with the following command: - -```sh -docker run -d --rm \ - --name stacks-blockchain \ - -v $(pwd)/persistent-data/stacks-blockchain/mainnet:/root/stacks-node/data \ - -v $(pwd)/config/mainnet:/src/stacks-node \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain \ -/bin/stacks-node start --config /src/stacks-node/Config.toml -``` - -You can verify the running `stacks-blockchain` container with the command: - -```sh -docker ps --filter name=stacks-blockchain -``` - -## Step 3: verifying the services - -:::note -The initial burnchain header sync can take several minutes, until this is done the following commands will not work -::: - -To verify the `stacks-blockchain` burnchain header sync progress: - -```sh -docker logs stacks-blockchain -``` - -The output should be similar to the following: - -``` -INFO [1626290705.886954] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.2% (8000 out of 691034) -INFO [1626290748.103291] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.4% (10000 out of 691034) -INFO [1626290776.956535] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.7% (12000 out of 691034) -``` - -To verify the `stacks-blockchain` tip height is progressing use the following command: - -```sh -curl -sL localhost:20443/v2/info | jq -``` - -If the instance is running you should recieve terminal output similar to the following: - -```json -{ - "peer_version": 402653184, - "pox_consensus": "89d752034e73ed10d3b97e6bcf3cff53367b4166", - "burn_block_height": 666143, - "stable_pox_consensus": "707f26d9d0d1b4c62881a093c99f9232bc74e744", - "stable_burn_block_height": 666136, - "server_version": "stacks-node 2.0.11.1.0-rc1 (master:67dccdf, release build, linux [x86_64])", - "network_id": 1, - "parent_network_id": 3652501241, - "stacks_tip_height": 61, - "stacks_tip": "e08b2fe3dce36fd6d015c2a839c8eb0885cbe29119c1e2a581f75bc5814bce6f", - "stacks_tip_consensus_hash": "ad9f4cb6155a5b4f5dcb719d0f6bee043038bc63", - "genesis_chainstate_hash": "74237aa39aa50a83de11a4f53e9d3bb7d43461d1de9873f402e5453ae60bc59b", - "unanchored_tip": "74d172df8f8934b468c5b0af2efdefe938e9848772d69bcaeffcfe1d6c6ef041", - "unanchored_seq": 0, - "exit_at_block_height": null -} -``` - -## Stopping the mainnet node - -Use the following commands to stop the local mainnet node: - -```sh -docker stop stacks-blockchain -``` - -## Optional. Run stacks node with own bitcoin node - -It's encouraged to use your own bitcoin node when possible. - -To do this simply update the `stacks-node/config/mainnet/Config.toml` file with the details of your bitcoin node. For example: - -``` -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "localhost" -username = "rpc username" -password = "rpc password" -rpc_port = 8332 -peer_port = 8333 -``` - -The rpc configuration of your bitcoin node is out of the scope of this document, but you can find more information on how to set it up [here](https://developer.bitcoin.org/examples/intro.html). - -## Additional reading - - - -- [Running a Stacks API node](https://docs.hiro.so/get-started/running-api-node) -- [Running a Stacks testnet node](running-testnet-node) - diff --git a/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md b/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md deleted file mode 100644 index da01ce2ea1..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: Running a testnet node -description: Set up and run a testnet node with Docker -sidebar_position: 2 -tags: - - tutorial ---- - -## Introduction - -This procedure demonstrates how to run a local testnet node using Docker images. - -:::caution -This procedure focuses on Unix-like operating systems (Linux and MacOS). This procedure has not been tested on Windows. -::: - -## Prerequisites - -Running a node has no specialized hardware requirements. Users have been successful in running nodes on Raspberry Pi boards and other system-on-chip architectures. In order to complete this procedure, you must have the following software installed on the node host machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [curl](https://curl.se/download.html) -- [jq](https://stedolan.github.io/jq/download/) - -### Firewall configuration - -In order for the API node services to work correctly, you must configure any network firewall rules to allow traffic on the ports discussed in this section. The details of network and firewall configuration are highly specific to your machine and network, so a detailed example isn't provided. - -The following ports must open on the host machine: - -Ingress: - -- stacks-blockchain (open to `0.0.0.0/0`): - - `20443 TCP` - - `20444 TCP` - -Egress: - -- `18332` -- `18333` -- `20443-20444` - -These egress ports are for syncing stacks-blockchain and Bitcoin headers. If they're not open, the sync will fail. - -## Step 1: initial setup - -In order to run the testnet node, you must download the Docker images and create a directory structure to hold the persistent data from the services. Download and configure the Docker images with the following commands: - -```sh -docker pull blockstack/stacks-blockchain -``` - -Create a directory structure for the service data with the following command: - -```sh -mkdir -p ./stacks-node/persistent-data/stacks-blockchain/testnet && cd stacks-node -``` - -## Step 2: running Stacks blockchain - -Start the stacks-blockchain container with the following command: - -```sh -docker run -d --rm \ - --name stacks-blockchain \ - -v $(pwd)/persistent-data/stacks-blockchain/testnet:/root/stacks-node/data \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain \ -/bin/stacks-node testnet -``` - -You can verify the running stacks-blockchain container with the command: - -```sh -docker ps --filter name=stacks-blockchain -``` - -## Step 3: verifying the services - -:::info -The initial burnchain header sync can take several minutes, until this is done the following commands will not work -::: - -To verify the stacks-blockchain burnchain header sync progress: - -```sh -docker logs stacks-blockchain -``` - -The output should be similar to the following: - -``` -INFO [1626290705.886954] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.2% (8000 out of 2034380) -INFO [1626290748.103291] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.4% (10000 out of 2034380) -INFO [1626290776.956535] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.7% (12000 out of 2034380) -``` - -To verify the stacks-blockchain tip height is progressing use the following command: - -```sh -curl -sL localhost:20443/v2/info | jq -``` - -If the instance is running you should recieve terminal output similar to the following: - -```json -{ - "peer_version": 4207599105, - "pox_consensus": "12f7fa85e5099755a00b7eaecded1aa27af61748", - "burn_block_height": 2034380, - "stable_pox_consensus": "5cc4e0403ff6a1a4bd17dae9600c7c13d0b10bdf", - "stable_burn_block_height": 2034373, - "server_version": "stacks-node 2.0.11.2.0-rc1 (develop:7b6d3ee+, release build, linux [x86_64])", - "network_id": 2147483648, - "parent_network_id": 118034699, - "stacks_tip_height": 509, - "stacks_tip": "e0ee952e9891709d196080ca638ad07e6146d4c362e6afe4bb46f42d5fe584e8", - "stacks_tip_consensus_hash": "12f7fa85e5099755a00b7eaecded1aa27af61748", - "genesis_chainstate_hash": "74237aa39aa50a83de11a4f53e9d3bb7d43461d1de9873f402e5453ae60bc59b", - "unanchored_tip": "32bc86590f11504f17904ee7f5cb05bcf71a68a35f0bb3bc2d31aca726090842", - "unanchored_seq": 0, - "exit_at_block_height": null -} -``` - -## Stopping the testnet node - -Use the following commands to stop the local testnet node: - -```sh -docker stop stacks-blockchain -``` - -## Additional reading - - - -- [Running a Stacks API node](https://docs.hiro.so/get-started/running-api-node) -- [Running a Stacks mainnet node](running-mainnet-node) - diff --git a/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md b/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md deleted file mode 100644 index 89af343dc6..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md +++ /dev/null @@ -1,506 +0,0 @@ ---- -title: Stacks Node Configuration -description: Configuration parameters and options for the stacks-node binary -sidebar_position: 6 ---- - -## Usage - -```bash -stacks-node sub-command [--subcommand-option ] -``` - -## Subcommands - -:::caution The `stacks-node` binary may have deprecated commands that are not documented on this page. Deprecated commands may be accessible until they are fully removed from the sources. ::: - -### mocknet - -Start a node based on a fast local setup emulating a burnchain. Ideal for smart contract development. - -Example: - -```bash -stacks-node mocknet -``` - -### krypton - -Start a node that will join and stream blocks from the public krypton regtest, powered by Blockstack via [Proof of Transfer](../understand-stacks#consensus-mechanism). - -Example: - -```bash -stacks-node krypton -``` - -### testnet - -Start a node that will join and stream blocks from the public testnet. - -Example: - -```bash -stacks-node testnet -``` - -### mainnet - -Start a node that joins and streams blocks from the public mainnet. - -Example: - -```bash -stacks-node mainnet -``` - -### start - -Start a node with a config of your own. Can be used for joining a network, starting a new chain, or replacing default values used by the `mocknet` or `testnet` subcommands. - -#### Arguments - -**--config**: relative or absolute path to the TOML config file. Required. - -Example: - -```bash -stacks-node start --config=/path/to/config.toml -``` - -See [Configuration File Options](#configuration-file-options) for more information. - -#### version - -Displays information about the current version and the release cycle. - -Example: - -```bash -stacks-node version -``` - -#### help - -Displays a help message. - -Example: - -```bash -stacks-node help -``` - -## Configuration File Options - -The TOML configuration file has multiple sections under which an option may be placed. - -To see a list of example configurations, [please see this page](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf). - -### Section: node - -Contains various configuration options pertaining to the stacks-node. - -Example: - -```toml -[node] -rpc_bind = "0.0.0.0:20443" -p2p_bind = "0.0.0.0:20444" -# Enter your private key here -seed = "replace-with-your-private-key" -miner = true -``` - -#### working_dir (optional) - -Absolute path to the directory which the stacks-node will use for storing various data. - -Example: - -```toml -working_dir = "/root/stacks-node" -``` - -#### rpc_bind - -Address and port stacks-node should bind to for RPC connections. - -Example: - -```toml -rpc_bind = "0.0.0.0:20443" -``` - -#### p2p_bind - -Address and port stacks-node should bind to for P2P connections. - -Example: - -```toml -p2p_bind = "0.0.0.0:20444" -``` - -#### data_url (optional) - -Address and port from which the stacks-node will be receiving incoming rpc connections. - -Example: - -```toml -data_url = "1.2.3.4:20443" -``` - -#### p2p_address (optional) - -Address and port from which the stacks-node will be receiving incoming p2p connections. - -Example: - -```toml -p2p_address = "1.2.3.4:20444" -``` - -#### bootstrap_node (optional) - -Public key, address, and port stacks-node should use to pull transaction data from when starting. - -Example: - -```toml -bootstrap_node = "047435c194e9b01b3d7f7a2802d6684a3af68d05bbf4ec8f17021980d777691f1d51651f7f1d566532c804da506c117bbf79ad62eea81213ba58f8808b4d9504ad@testnet.blockstack.org:20444" -``` - -#### wait_time_for_microblocks (optional) - -The amount of time (in milliseconds) that a node will wait before trying to mine a block, after catching up to the anchored chain tip. This gives the current leader time to broadcast microblocks that will get included in that mined block. - -Example: - -```toml -wait_time_for_microblocks = 15000 -``` - -#### seed (optional) - -The private key to use for mining. Only needed if `miner` is set to `true`. - -Example: - -```toml -seed = "replace-with-your-private-key" -``` - -#### local_peer_seed (optional) - -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. - -Example: - -```toml -local_peer_seed = "replace-with-your-private-key" -``` - -#### miner (optional) - -Determines whether the stacks-node is running a follower (`false`) or a miner (`true`). Defaults to `false` if omitted. - -Example: - -```toml -miner = true -``` - -#### mine_microblocks (optional) - -Determines whether the stacks-node will mine microblocks. Will only take effect if `miner` is set to `true`. - -Example: - -```toml -mine_microblocks = true -``` - -#### prometheus_bind (optional) - -Address and port stacks-node should open for Prometheus metrics collection. - -Example: - -```toml -prometheus_bind = "0.0.0.0:9153" -``` - -### Section: events_observer (optional) - -Contains options for watching events emitted by a local [stacks-blockchain-api](https://github.com/hirosystems/stacks-blockchain-api) service. - -:::info -This section can be repeated multiple times. -::: - -Example: - -```toml -[[events_observer]] -endpoint = "address-to-my-local.stacks-node-api.com:3700" -retry_count = 255 -events_keys = ["*"] -``` - -#### endpoint - -Address and port to a stacks-node-api to watch for events. - -Example: - -```toml -endpoint = "address-to-my-local.stacks-node-api.com:3700" -``` - -#### retry_count - -Number of times to retry sending events to the endpoint before failing. - -Example: - -```toml -retry_count = 255 -``` - -#### events_keys - -Event keys for which to watch. The emitted node events can be restricted by account, function name and event type. Asterix ("\*") can be used to emit all events. - -Examples: - -```toml -events_keys = ["*"] -``` - -```toml -events_keys = [ - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.store::print", - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.contract.ft-token", - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.contract.nft-token", - "stx" -] -``` - -### Section: connection_options (optional) - -Specifies configuration options for others connecting to the stacks node. - -Example: - -```toml -[connection_options] -public_ip_address = "1.2.3.4:20444" -download_interval = 60 -walk_interval = 30 -``` - -#### public_ip_address - -The advertised public IP of this stacks-node. - -Example: - -```toml -public_ip_address = "1.2.3.4:20444" -``` - -#### download_interval - -Time (in seconds) between attempts to download blocks. - -Example: - -```toml -download_interval = 60 -``` - -#### walk_interval - -Time (in seconds) between attempts to walk the neighborhood. - -Example: - -```toml -walk_interval = 30 -``` - -#### read_only_call_limit_read_length - -Total number of bytes allowed to be read by an individual read-only function call. - -Example: - -```toml -read_only_call_limit_read_length = 100000 -``` - -#### read_only_call_limit_read_count - -Total number of independent read operations permitted for an individual read-only function call. - -Example: - -```toml -read_only_call_limit_read_count = 30 -``` - -#### read_only_call_limit_runtime - -[Runtime cost](https://github.com/stacksgov/sips/blob/2d3fd9bf8da7a04f588d90ff6252173d7609d7bf/sips/sip-006/sip-006-runtime-cost-assessment.md#introduction) limit for an individual read-only function call. - -Example: - -```toml -read_only_call_limit_runtime = 1000000000 -``` - -### Section: burnchain - -This section contains configuration options pertaining to the blockchain the stacks-node binds to on the backend for proof-of-transfer (BTC). - -Example: - -```toml -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "your.bitcoind.node.org" -rpc_port = 8332 -peer_port = 8333 -``` - -#### chain - -The blockchain stacks-node binds to on the backend for proof-of-transfer. Only value supported: `"bitcoin"`. - -Example: - -```toml -chain = "bitcoin" -``` - -#### mode - -The profile or test phase of which to run stacks-node. Valid values are `"mocknet"`, `"helium"`, `"neon"`, `"argon"`, `"krypton"`, `"xenon"`. - -Example: - -```toml -mode = "xenon" -``` - -#### peer_host - -Domain name of the host running the backend Bitcoin blockchain. It's required to either run a personal Bitcoin node locally, or to use a publicly hosted Bitcoin node. - -Example: - -```toml -peer_host = "your.bitcoind.node.org" -``` - -#### rpc_port - -peer_host's port stacks-node will connect to for RPC connections. - -Example: - -```toml -rpc_port = 8332 -``` - -#### peer_port - -peer_host's port stacks-node will connect to for P2P connections. - -Example: - -```toml -peer_port = 8333 -``` - -#### burn_fee_cap (optional) - -Maximum amount (in Satoshis) of "burn commitment" to broadcast for the next block's leader election. - -Example: - -```toml -burn_fee_cap = 30000 -``` - -#### satoshis_per_byte (optional) - -Amount (in Satoshis) per [virtual byte](https://en.bitcoin.it/wiki/Weight_units). This is used to compute the transaction fees. - -Example: - -```toml -satoshis_per_byte = 50 -``` - -So total transaction cost would be `(estimated_tx_size * satoshis_per_byte) + burn_fee_cap`. - -#### commit_anchor_block_within (optional) - -Sets the time period (in milliseconds) for commitments. Only used when `mode` is set to `"helium"`. - -Example: - -```toml -commit_anchor_block_within = 10000 -``` - -### Section: ustx_balance (testnet/regtest only) - -This section contains configuration options pertaining to the genesis block allocation for an address in micro-STX. If a user changes these values, their node may be in conflict with other nodes on the network and find themselves unable to sync with other nodes. - -:::info -This section can repeat multiple times, and thus is in double-brackets. Each section can define only one address. This section is ignored if running a node on mainnet. -::: - -Example: - -```toml -[[ustx_balance]] -address = "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6" -amount = 10000000000000000 - -[[ustx_balance]] -address = "ST11NJTTKGVT6D1HY4NJRVQWMQM7TVAR091EJ8P2Y" -amount = 10000000000000000 - -[[ustx_balance]] -address = "ST1HB1T8WRNBYB0Y3T7WXZS38NKKPTBR3EG9EPJKR" -amount = 10000000000000000 - -[[ustx_balance]] -address = "STRYYQQ9M8KAF4NS7WNZQYY59X93XEKR31JP64CP" -amount = 10000000000000000 -``` - -#### address - -Address which maintains a micro-STX balance. - -Example: - -```toml -address = "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6" -``` - -#### amount - -The balance of micro-STX given to the address at the start of the node. - -Example: - -```toml -amount = 10000000000000000 -``` diff --git a/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md b/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md deleted file mode 100644 index 094e3f03a1..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Verify Miner -description: Verify node is operating as miner -sidebar_position: 7 ---- - -You can verify that your node is operating as a miner by checking its log output to verify that it was able to find its Bitcoin UTXOs: - -```bash -$ head -n 100 /path/to/your/node/logs | grep -i utxo -INFO [1630127492.031042] [testnet/stacks-node/src/run_loop/neon.rs:146] [main] Miner node: checking UTXOs at address: -INFO [1630127492.062652] [testnet/stacks-node/src/run_loop/neon.rs:164] [main] UTXOs found - will run as a Miner node -``` \ No newline at end of file diff --git a/i18n/de/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json b/i18n/de/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json deleted file mode 100644 index f5de305558..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Noteworthy Contracts", - "position": 4, - "link": { - "type": "generated-index", - "description": "Specific deployed Clarity Contracts worth mentioning." - } -} \ No newline at end of file diff --git a/i18n/de/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md b/i18n/de/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md deleted file mode 100644 index 99723a9ff2..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md +++ /dev/null @@ -1,362 +0,0 @@ ---- -title: BNS Contract -description: The Blockchain Naming System. ---- - -![](/img/satoshi-btc.png) - -## Introduction - -The Blockchain Naming System (BNS) is implemented as a smart contract using Clarity. - -Below is a list of public and read-only functions as well as error codes that can be returned by those methods: -* [Public functions](#public-functions) -* [Read-only functions](#read-only-functions) -* [Error codes](#error-codes) - -## Public functions - - -### name-import - -#### Input: `(buff 20), (buff 48), principal, (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-import namespace name beneficiary zonefile-hash)` -#### Description: -Imports name to a revealed namespace. Each imported name is given both an owner and some off-chain state. - -### name-preorder - -#### Input: `(buff 20), uint` -#### Output: `(response uint int)` -#### Signature: `(name-preorder hashed-salted-fqn stx-to-burn)` -#### Description: -Preorders a name by telling all BNS nodes the salted hash of the BNS name. It pays the registration fee to the namespace owner's designated address. - -### name-register - -#### Input: `(buff 20), (buff 48), (buff 20), (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-register namespace name salt zonefile-hash)` -#### Description: -Reveals the salt and the name to all BNS nodes, and assigns the name an initial public key hash and zone file hash. - -### name-renewal - -#### Input: `(buff 20), (buff 48), uint, (optional principal), (optional (buff 20))` -#### Output: `(response bool int)` -#### Signature: `(name-renewal namespace name stx-to-burn new-owner zonefile-hash)` -#### Description: -Depending in the namespace rules, a name can expire. For example, names in the .id namespace expire after 2 years. You need to send a name renewal every so often to keep your name. - -You will pay the registration cost of your name to the namespace's designated burn address when you renew it. When a name expires, it enters a \"grace period\". The period is set to 5000 blocks (a month) but can be configured for each namespace. - -It will stop resolving in the grace period, and all of the above operations will cease to be honored by the BNS consensus rules. You may, however, send a NAME_RENEWAL during this grace period to preserve your name. After the grace period, everybody can register that name again. If your name is in a namespace where names do not expire, then you never need to use this transaction. -### name-revoke - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(name-revoke namespace name)` -#### Description: -Makes a name unresolvable. The BNS consensus rules stipulate that once a name is revoked, no one can change its public key hash or its zone file hash. The name's zone file hash is set to null to prevent it from resolving. You should only do this if your private key is compromised, or if you want to render your name unusable for whatever reason. - -### name-transfer - -#### Input: `(buff 20), (buff 48), principal, (optional (buff 20))` -#### Output: `(response bool int)` -#### Signature: `(name-transfer namespace name new-owner zonefile-hash)` -#### Description: -Changes the name's public key hash. You would send a name transfer transaction if you wanted to: -* Change your private key -* Send the name to someone else or -* Update your zone file - -When transferring a name, you have the option to also clear the name's zone file hash (i.e. set it to null). This is useful for when you send the name to someone else, so the recipient's name does not resolve to your zone file. - -### name-update - -#### Input: `(buff 20), (buff 48), (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-update namespace name zonefile-hash)` -#### Description: -Changes the name's zone file hash. You would send a name update transaction if you wanted to change the name's zone file contents. For example, you would do this if you want to deploy your own Gaia hub and want other people to read from it. - -### namespace-preorder - -#### Input: `(buff 20), uint` -#### Output: `(response uint int)` -#### Signature: `(namespace-preorder hashed-salted-namespace stx-to-burn)` -#### Description: -Registers the salted hash of the namespace with BNS nodes, and burns the requisite amount of cryptocurrency. Additionally, this step proves to the BNS nodes that user has honored the BNS consensus rules by including a recent consensus hash in the transaction. Returns pre-order's expiration date (in blocks). - -### namespace-ready - -#### Input: `(buff 20)` -#### Output: `(response bool int)` -#### Signature: `(namespace-ready namespace)` -#### Description: -Launches the namespace and makes it available to the public. Once a namespace is launched, anyone can register a name in it if they pay the appropriate amount of cryptocurrency. - -### namespace-reveal - -#### Input: `(buff 20), (buff 20), uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, principal` -#### Output: `(response bool int)` -#### Signature: `(namespace-reveal namespace namespace-salt p-func-base p-func-coeff p-func-b1 p-func-b2 p-func-b3 p-func-b4 p-func-b5 p-func-b6 p-func-b7 p-func-b8 p-func-b9 p-func-b10 p-func-b11 p-func-b12 p-func-b13 p-func-b14 p-func-b15 p-func-b16 p-func-non-alpha-discount p-func-no-vowel-discount lifetime namespace-import)` -#### Description: -Reveals the salt and the namespace ID (after a namespace preorder). It reveals how long names last in this namespace before they expire or must be renewed, and it sets a price function for the namespace that determines how cheap or expensive names its will be.All of the parameters prefixed by `p` make up the `price function`. These parameters govern the pricing and lifetime of names in the namespace. - -The rules for a namespace are as follows: - -* a name can fall into one of 16 buckets, measured by length. Bucket 16 incorporates all names at least 16 characters long. - -* the pricing structure applies a multiplicative penalty for having numeric characters, or punctuation characters. - -* the price of a name in a bucket is `((coeff) * (base) ^ (bucket exponent)) / ((numeric discount multiplier) * (punctuation discount multiplier))` - -Example: - -* base = 10 -* coeff = 2 -* nonalpha discount: 10 -* no-vowel discount: 10 -* buckets 1, 2: 9 -* buckets 3, 4, 5, 6: 8 -* buckets 7, 8, 9, 10, 11, 12, 13, 14: 7 -* buckets 15, 16+: - - -## Read-only functions - -### can-name-be-registered - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(can-name-be-registered namespace name)` -#### Description: -Returns true if the provided name can be registered. - -### can-namespace-be-registered - -#### Input: `(buff 20)` -#### Output: `(response bool UnknownType)` -#### Signature: `(can-namespace-be-registered namespace)` -#### Description: -Returns true if the provided namespace is available. - -### can-receive-name - -#### Input: `principal` -#### Output: `(response bool int)` -#### Signature: `(can-receive-name owner)` -#### Description: -Returns true if the provided name can be received. That is, if it is not curretly owned, a previous lease is expired, and the name wasn't revoked. - -### get-name-price - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response uint int)` -#### Signature: `(get-name-price namespace name)` -#### Description: -Gets the price for a name. - -### get-namespace-price - -#### Input: `(buff 20)` -#### Output: `(response uint int)` -#### Signature: `(get-namespace-price namespace)` -#### Description: -Gets the price for a namespace. - -### get-namespace-properties - -#### Input: `(buff 20)` -#### Output: `(response (tuple (namespace (buff 20)) (properties (tuple (can-update-price-function bool) (launched-at (optional uint)) (lifetime uint) (namespace-import principal) (price-function (tuple (base uint) (buckets (list 16 uint)) (coeff uint) (no-vowel-discount uint) (nonalpha-discount uint))) (revealed-at uint)))) int)` -#### Signature: `(get-namespace-properties namespace)` -#### Description: -Get namespace properties. - -### is-name-lease-expired - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(is-name-lease-expired namespace name)` -#### Description: -Return true if the provided name lease is expired. - -### name-resolve - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response (tuple (lease-ending-at (optional uint)) (lease-started-at uint) (owner principal) (zonefile-hash (buff 20))) int)` -#### Signature: `(name-resolve namespace name)` -#### Description: -Get name registration details. - -### resolve-principal - -#### Input: `principal` -#### Output: `(response (tuple (name (buff 48)) (namespace (buff 20))) (tuple (code int) (name (optional (tuple (name (buff 48)) (namespace (buff 20)))))))` -#### Signature: `(resolve-principal owner)` -#### Description: -Returns the registered name that a principal owns if there is one. A principal can only own one name at a time. - -## Error codes - -### ERR_INSUFFICIENT_FUNDS -#### type: `int` -#### value: `4001` - -### ERR_NAMESPACE_ALREADY_EXISTS -#### type: `int` -#### value: `1006` - -### ERR_NAMESPACE_ALREADY_LAUNCHED -#### type: `int` -#### value: `1014` - -### ERR_NAMESPACE_BLANK -#### type: `int` -#### value: `1013` - -### ERR_NAMESPACE_CHARSET_INVALID -#### type: `int` -#### value: `1016` - -### ERR_NAMESPACE_HASH_MALFORMED -#### type: `int` -#### value: `1015` - -### ERR_NAMESPACE_NOT_FOUND -#### type: `int` -#### value: `1005` - -### ERR_NAMESPACE_NOT_LAUNCHED -#### type: `int` -#### value: `1007` - -### ERR_NAMESPACE_OPERATION_UNAUTHORIZED -#### type: `int` -#### value: `1011` - -### ERR_NAMESPACE_PREORDER_ALREADY_EXISTS -#### type: `int` -#### value: `1003` - -### ERR_NAMESPACE_PREORDER_CLAIMABILITY_EXPIRED -#### type: `int` -#### value: `1009` - -### ERR_NAMESPACE_PREORDER_EXPIRED -#### type: `int` -#### value: `1002` - -### ERR_NAMESPACE_PREORDER_LAUNCHABILITY_EXPIRED -#### type: `int` -#### value: `1010` - -### ERR_NAMESPACE_PREORDER_NOT_FOUND -#### type: `int` -#### value: `1001` - -### ERR_NAMESPACE_PRICE_FUNCTION_INVALID -#### type: `int` -#### value: `1008` - -### ERR_NAMESPACE_STX_BURNT_INSUFFICIENT -#### type: `int` -#### value: `1012` - -### ERR_NAMESPACE_UNAVAILABLE -#### type: `int` -#### value: `1004` - -### ERR_NAME_ALREADY_CLAIMED -#### type: `int` -#### value: `2011` - -### ERR_NAME_BLANK -#### type: `int` -#### value: `2010` - -### ERR_NAME_CHARSET_INVALID -#### type: `int` -#### value: `2022` - -### ERR_NAME_CLAIMABILITY_EXPIRED -#### type: `int` -#### value: `2012` - -### ERR_NAME_COULD_NOT_BE_MINTED -#### type: `int` -#### value: `2020` - -### ERR_NAME_COULD_NOT_BE_TRANSFERED -#### type: `int` -#### value: `2021` - -### ERR_NAME_EXPIRED -#### type: `int` -#### value: `2008` - -### ERR_NAME_GRACE_PERIOD -#### type: `int` -#### value: `2009` - -### ERR_NAME_HASH_MALFORMED -#### type: `int` -#### value: `2017` - -### ERR_NAME_NOT_FOUND -#### type: `int` -#### value: `2013` - -### ERR_NAME_NOT_RESOLVABLE -#### type: `int` -#### value: `2019` - -### ERR_NAME_OPERATION_UNAUTHORIZED -#### type: `int` -#### value: `2006` - -### ERR_NAME_PREORDERED_BEFORE_NAMESPACE_LAUNCH -#### type: `int` -#### value: `2018` - -### ERR_NAME_PREORDER_ALREADY_EXISTS -#### type: `int` -#### value: `2016` - -### ERR_NAME_PREORDER_EXPIRED -#### type: `int` -#### value: `2002` - -### ERR_NAME_PREORDER_FUNDS_INSUFFICIENT -#### type: `int` -#### value: `2003` - -### ERR_NAME_PREORDER_NOT_FOUND -#### type: `int` -#### value: `2001` - -### ERR_NAME_REVOKED -#### type: `int` -#### value: `2014` - -### ERR_NAME_STX_BURNT_INSUFFICIENT -#### type: `int` -#### value: `2007` - -### ERR_NAME_TRANSFER_FAILED -#### type: `int` -#### value: `2015` - -### ERR_NAME_UNAVAILABLE -#### type: `int` -#### value: `2004` - -### ERR_PANIC -#### type: `int` -#### value: `0` - -### ERR_PRINCIPAL_ALREADY_ASSOCIATED -#### type: `int` -#### value: `3001` diff --git a/i18n/de/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md b/i18n/de/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md deleted file mode 100644 index ce1b1ba859..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -title: Stacking Contract -description: See a detailed list of all functions and error codes of the Stacking contract. ---- - -## Introduction - -Stacking is implemented as a smart contract using Clarity. You can always find the Stacking contract identifier using the Stacks Blockchain API [`v2/pox` endpoint](https://docs.hiro.so/api#operation/get_pox_info). - -Below is a list of public and read-only functions as well as error codes that can be returned by those methods: - -* [Public functions](#public-functions) -* [Read-only functions](#read-only-functions) -* [Error codes](#error-codes) - -## Public functions - -### allow-contract-caller -#### input: `principal, (optional uint)` -#### output: `(response bool int)` -#### signature: `(allow-contract-caller caller until-burn-ht)` -#### description: -Give a contract-caller authorization to call stacking methods. Normally, stacking methods may only be invoked by _direct_ transactions (i.e., the `tx-sender` issues a direct `contract-call` to the stacking methods). - -By issuing an allowance, the tx-sender may call through the allowed contract. - -### delegate-stack-stx -#### input: `principal, uint, (tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint` -#### output: `(response (tuple (lock-amount uint) (stacker principal) (unlock-burn-height uint)) int)` -#### signature: `(delegate-stack-stx stacker amount-ustx pox-addr start-burn-ht lock-period)` -#### description: -As a delegate, stack the given principal's STX using `partial-stacked-by-cycle`. - -Once the delegate has stacked > minimum, the delegate should call `stack-aggregation-commit`. - -### delegate-stx -#### input: `uint, principal, (optional uint), (optional (tuple (hashbytes (buff 20)) (version (buff 1))))` -#### output: `(response bool int)` -#### signature: `(delegate-stx amount-ustx delegate-to until-burn-ht pox-addr)` -#### description: -Delegate to `delegate-to` the ability to stack from a given address. - -This method _does not_ lock the funds, rather, it allows the delegate to issue the stacking lock. - -The caller specifies: - -* amount-ustx: the total amount of ustx the delegate may be allowed to lock -* until-burn-ht: an optional burn height at which this delegation expiration -* pox-addr: an optional p2pkh or p2sh address to which any rewards *must* be sent - -### disallow-contract-caller -#### input: `principal` -#### output: `(response bool int)` -#### signature: `(disallow-contract-caller caller)` -#### description: -Revokes authorization from a contract to invoke stacking methods through contract-calls - -### reject-pox -#### input: -#### output: `(response bool int)` -#### signature: `(reject-pox)` -#### description: -Reject Stacking for this reward cycle. - -`tx-sender` votes all its uSTX for rejection. - -Note that unlike Stacking, rejecting PoX does not lock the tx-sender's tokens: PoX rejection acts like a coin vote. - -### revoke-delegate-stx -#### input: -#### output: `(response bool int)` -#### signature: `(revoke-delegate-stx)` -#### description: -Revoke a Stacking delegate relationship. A particular Stacker may only have one delegate, so this method does not take any parameters, and just revokes the Stacker's current delegate (if one exists). - -### stack-aggregation-commit -#### input: `(tuple (hashbytes (buff 20)) (version (buff 1))), uint` -#### output: `(response bool int)` -#### signature: `(stack-aggregation-commit pox-addr reward-cycle)` -#### description: -Commit partially stacked STX. - -This allows a stacker/delegate to lock fewer STX than the minimal threshold in multiple transactions, - -so long as: - -1. The pox-addr is the same. -2. This \"commit\" transaction is called _before_ the PoX anchor block. - -This ensures that each entry in the reward set returned to the stacks-node is greater than the threshold, - - but does not require it be all locked up within a single transaction - -### stack-stx -#### input: `uint, (tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint` -#### output: `(response (tuple (lock-amount uint) (stacker principal) (unlock-burn-height uint)) int)` -#### signature: `(stack-stx amount-ustx pox-addr start-burn-ht lock-period)` -#### description: -Lock up some uSTX for stacking! Note that the given amount here is in micro-STX (uSTX). - -The STX will be locked for the given number of reward cycles (lock-period). - -This is the self-service interface. tx-sender will be the Stacker. - -* The given stacker cannot currently be stacking. -* You will need the minimum uSTX threshold. This isn't determined until the reward cycle begins, but this method still requires stacking over the _absolute minimum_ amount, which can be obtained by calling `get-stacking-minimum`. -* The pox-addr argument must represent a valid reward address. Right now, this must be a Bitcoin p2pkh or p2sh address. It cannot be a native Segwit address, but it may be a p2wpkh-p2sh or p2wsh-p2sh address. - -The tokens will unlock and be returned to the Stacker (tx-sender) automatically. - -## Read-only functions - -### can-stack-stx -#### input: `(tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint, uint` -#### output: `(response bool int)` -#### signature: `(can-stack-stx pox-addr amount-ustx first-reward-cycle num-cycles)` -#### description: -Evaluate if a participant can stack an amount of STX for a given period. - -### get-pox-info -#### input: -#### output: `(response (tuple (current-rejection-votes uint) (first-burnchain-block-height uint) (min-amount-ustx uint) (prepare-cycle-length uint) (rejection-fraction uint) (reward-cycle-id uint) (reward-cycle-length uint) (total-liquid-supply-ustx uint)) UnknownType)` -#### signature: `(get-pox-info)` -#### description: -Returns information about PoX status. - -### get-pox-rejection -#### input: `principal, uint` -#### output: `(optional (tuple (amount uint)))` -#### signature: `(get-pox-rejection stacker reward-cycle)` -#### description: -Returns the amount of uSTX that a given principal used to reject a PoX cycle. - -### get-stacker-info -#### input: `principal` -#### output: `(optional (tuple (amount-ustx uint) (first-reward-cycle uint) (lock-period uint) (pox-addr (tuple (hashbytes (buff 20)) (version (buff 1))))))` -#### signature: `(get-stacker-info stacker)` -#### description: -Returns the _current_ stacking information for `stacker. If the information is expired, or if there's never been such a stacker, then returns none. - -### get-stacking-minimum -#### input: -#### output: `uint` -#### signature: `(get-stacking-minimum)` -#### description: -Returns the absolute minimum amount that could be validly Stacked (the threshold to Stack in a given reward cycle may be higher than this - -### get-total-ustx-stacked -#### input: `uint` -#### output: `uint` -#### signature: `(get-total-ustx-stacked reward-cycle)` -#### description: -Returns the amount of currently participating uSTX in the given cycle. - -### is-pox-active -#### input: `uint` -#### output: `bool` -#### signature: `(is-pox-active reward-cycle)` -#### description: -Returns whether or not PoX has been rejected at a given PoX cycle. -## Error codes - -### ERR_DELEGATION_EXPIRES_DURING_LOCK -#### type: `int` -#### value: `21` - -### ERR_DELEGATION_POX_ADDR_REQUIRED -#### type: `int` -#### value: `23` - -### ERR_DELEGATION_TOO_MUCH_LOCKED -#### type: `int` -#### value: `22` - -### ERR_INVALID_START_BURN_HEIGHT -#### type: `int` -#### value: `24` - -### ERR_NOT_ALLOWED -#### type: `int` -#### value: `19` - -### ERR_STACKING_ALREADY_DELEGATED -#### type: `int` -#### value: `20` - -### ERR_STACKING_ALREADY_REJECTED -#### type: `int` -#### value: `17` - -### ERR_STACKING_ALREADY_STACKED -#### type: `int` -#### value: `3` - -### ERR_STACKING_EXPIRED -#### type: `int` -#### value: `5` - -### ERR_STACKING_INSUFFICIENT_FUNDS -#### type: `int` -#### value: `1` - -### ERR_STACKING_INVALID_AMOUNT -#### type: `int` -#### value: `18` - -### ERR_STACKING_INVALID_LOCK_PERIOD -#### type: `int` -#### value: `2` - -### ERR_STACKING_INVALID_POX_ADDRESS -#### type: `int` -#### value: `13` - -### ERR_STACKING_NO_SUCH_PRINCIPAL -#### type: `int` -#### value: `4` - -### ERR_STACKING_PERMISSION_DENIED -#### type: `int` -#### value: `9` - -### ERR_STACKING_POX_ADDRESS_IN_USE -#### type: `int` -#### value: `12` - -### ERR_STACKING_STX_LOCKED -#### type: `int` -#### value: `6` - -### ERR_STACKING_THRESHOLD_NOT_MET -#### type: `int` -#### value: `11` - -### ERR_STACKING_UNREACHABLE -#### type: `int` -#### value: `255` \ No newline at end of file diff --git a/i18n/de/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md b/i18n/de/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md deleted file mode 100644 index 5f38edfb57..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: xBTC -description: Wrapped BTC on Stacks ---- - -![](/img/xbtc-icon.webp) - -## Introduction - -[Wrapped.com](https://www.wrapped.com) has brought Bitcoin (xBTC) to the Stacks ecosystem. - -xBTC is backed 1:1 by Bitcoin and empowers developers to expand the Bitcoin DeFi ecosystem. - -The reserves are publicly visible [here](https://open.wrapped.com/reserves/). - -## Contract - -[SP3DX3H4FEYZJZ586MFBS25ZW3HZDMEW92260R2PR.Wrapped-Bitcoin](https://explorer.stacks.co/txid/SP3DX3H4FEYZJZ586MFBS25ZW3HZDMEW92260R2PR.Wrapped-Bitcoin?chain=mainnet) - -## Examples of uses - -[Friedger Mining Pool](https://pool.friedger.de/) currrently supports Stacking rewards payments in xBTC (optional). - - -## More information - -* [Blog post announcement](https://www.stacks.co/blog/tokensoft-wrapped-fundamental-bitcoin-defi-building-blocks-xbtc) by Muneeb Ali - -* Video: [Why xBTC is Important For Bitcoin to Grow](https://www.youtube.com/watch?v=xIoadrfSdi4) \ No newline at end of file diff --git a/i18n/de/docusaurus-plugin-content-docs/current/references/_category_.json b/i18n/de/docusaurus-plugin-content-docs/current/references/_category_.json deleted file mode 100644 index 3805ab0783..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/references/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "References", - "position": 9, - "link": { - "type": "generated-index", - "description": "Stacks references." - } -} \ No newline at end of file diff --git a/i18n/de/docusaurus-plugin-content-docs/current/references/glossary.md b/i18n/de/docusaurus-plugin-content-docs/current/references/glossary.md deleted file mode 100644 index ebb24ca97b..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/references/glossary.md +++ /dev/null @@ -1,215 +0,0 @@ ---- -title: Glossary -description: A comprehensive list of terms used within the ecosystem. ---- - -A comprehensive list of terms used within the ecosystem. - -#### App Review -An incentive mechanism for application developers in the early stage (first four years) of the ecosystem and helps with bootstrapping the two-sided market. - -#### Atlas -A peer network provide a global index for discovery. - -#### Bitcoin (BTC) address -A string of letters and numbers. `3E53XjqK4Cxt71BGeP2VhpcotM8LZ853C8` Sharing this address allows anyone to send Bitcoin to the address. - -#### block -A discrete group of records written to a blockchain that can effectively be identified and referenced by the use of headers that contain a digital fingerprint of the records each block contains. - -#### blockchain -A database created and shared by the members of a peer-to-peer computer network which each member of that network can independently trust due to the rules governing the database’s creation. A blockchain can therefore be used to replace centralized databases. - -#### Blockchain Name System (BNS) -Replacement for DNS. More info [here](../noteworthy-contracts/bns-contract). - -#### Blockstack Browser -A deprecated application for accessing identity and storage. - -#### Blockstack Owner Address - -Looks like a bitcoin address but starts with `ID` for example: `ID-1J3PUxY5uDShUnHRrMyU6yKtoHEUPhKULs` - -#### Burning -Burning a token means that the token is transferred to an address that is a black hole—one that is not owned by any entity and for which guessing the applicable private key is effectively impossible based on known mathematical principles. This effectively destroys the token by making it unavailable for future use and decreases the total number of tokens available from that point forward. - -#### consensus hash -A consensus hash is a cryptographic hash that each node calculates at each block. It is derived from the accepted state transitions in the last-processed block and a geometric series of prior-calculated consensus hashes. - -#### Consensus rules -"The rules governing the creation of new valid records in a blockchain database and the mining algorithms used for this purpose. - -#### control plane -The part of a network that carries signaling traffic and is responsible for routing. Control packets originate from or are destined for a router. Functions of the control plane include system configuration and management. - -#### core node -A server that runs Stacks Blockchain services. - -#### crypto-asset -A digital asset which utilises cryptography, peer-to-peer networking and a public ledger to regulate the creation of new units, verify transactions and secure the transactions without the intervention of any middleman. - -#### cryptography -The practise and study of encryption and decryption - encoding data so that it can only be decoded by specific individuals. A system for encrypting and decrypting data is a cryptosystem. - -#### DAO -See Decentralized Autonomous Organization. - -#### decentralized application (DApp) -A DApp is a service that enables direct interaction between end users and providers (e.g. connecting buyers and sellers in some marketplace, owners and stores in file storage). A term coined by Ethereum. See their glossary: http://ethdocs.org/en/latest/glossary.html#dapp" - -#### Decentralized Autonomous Organization -A type of contract or suite of contracts on the blockchain that is intented to codify, enforce or automate the processes of an organization. - -#### digital asset -Also referred to as a crypto-asset. Any set of unique digital information—including, for example, programs, decentralized programs, isolated chunks of programming code, collections of data, e-mail or web addresses or cryptocurrency tokens—that is capable of being stored and uniquely tracked on a computer network such as the Stacks network and over which a user can maintain control through that network. - -#### digital fingerprint -A digital fingerprint is a unique number of a fixed length that can be produced by running any set of digital information through something called a cryptographic hash function. Each set of digital information (including a digital asset, and the digital record of any network operation on that digital asset) should (as a practical matter) have a unique digital fingerprint, which allows that set of digital information to be identified. However, it is almost impossible to recreate a digital asset from its digital fingerprint. The Blockstack network uses industry-standard algorithms such as SHA-256 to create digital fingerprints. - -#### digital signature -A digital signature is a sequence of digital information combining a user’s private key and any digital information that the user wishes to sign. A digital signature is a sequence of digital information combining a user’s private key and any digital information that the user wishes to sign. Any other party can use the user’s paired public key to verify that the digital signature is authentic, i.e. that the public key was generated from a particular piece of digital information and the user’s private key. A digital signature is a sequence of digital information combining a user’s private key and any digital information that the user wishes to sign. Any other party can use the user’s paired public key to verify that the digital signature is authentic, i.e. that the public key was generated from a particular piece of digital information and the user’s private key. - -#### distributed hash tables (DHT) -A form of network used to store some content in the form of key/value pairs. ... ... This experimental project try to avoid keeping all the blockchain, but instead prefers to store it in a DHT. - -#### ephemeral key -A cryptographic key is called ephemeral if it is generated for each execution of a key establishment process. - -#### fork -The term fork is used to refer both to any situation where there are two or more competing versions of a blockchain on a network (a situation that may arise and resolve itself in the ordinary course of network operations due to lags in communication between core nodes) and any software update that is proposed for adoption by the core nodes of a blockchain network that may result in a persistent fork on the network, with core nodes that adopt the update recognizing one version of the blockchain and those which do not recognizing another. - -#### Gaia -Decentralized storage architecture for off-chain data. More info [here](../gaia). - -#### genesis block -The genesis block is the first block of the Stacks blockchain, which will create the initial 1.32 billion Stacks Tokens. - -#### id.blockstack -An identifier in the Blockstack, for example meepers.id.blockstack. This is your name & identity that is registered in the .id namespace on Blockstack. Your personal data and storage are built around this ID. Apps that want to access your data use your permission and identity to find it. An id is usually a shorthand for a longer, hash ID string, for example ID-1Fj9kkw15P51Fj9kkw15P5xJmyefWhLKrQMKNPREfaqsJ" - -#### identity - -A way to identify a person or an organization on the Stacks network. An identity is unique, both `meepers.id.blockstack` or `chad.id` are examples of IDs. - -#### identity management (IDM) -Identity management, also known as identity and access management is, in computer security, the security and business discipline that enables the right individuals to access the right resources at the right times and for the right reason". - -#### know your customer (KYC) -Or KYC, is a popular term used in the banking or financial field. KYC is a process where financial institutions, insurers and other companies obtain information about the identity and address of the customers as part of risk management. - -#### light clients -Clients that can independently validate the existence of transactions by downloading only block headers and not the entire blockchain. - -#### magic recovery code - -A long encrypted string, for example: `36mWivFdy0YPH2z31EflpQz/Y0UMrOrJ++lH=0EI7c3mop2JuRBm5WXxSTazJsUjOA...` Do not share the QR code that accompanied your recovery code either. This is a QR code: - -![](/img/qr-code.png) - -#### mesh network -A local network topology in which the infrastructure nodes (i.e. bridges, switches, and other infrastructure devices) connect directly, dynamically and non-hierarchically to as many other nodes as possible and cooperate with one another to efficiently route data from/to clients. - -#### mining -Mining generally refers to the process of performing certain functions for a network such as adding new records to a blockchain in exchange for mining rewards; it may also refer to other mechanisms whereby rewards (usually in the form of cryptocurrency) are provided for performing other tasks helpful to the network. - -#### mining power -A miner’s (or group of miners’) mining power is equal to the probability it will be selected to write a new block to the blockchain. Depending on the mechanism for mining, this is usually related to the overall share of computing power or cryptoassets the miner or miners possess relative to all miners for that blockchain. - -#### mining rewards -Mining rewards are newly issued tokens received by miners in exchange for adding new records to the blockchain or other activities beneficial to the network. - -#### name -An identifier or name. Names are a type of digital asset in the Stacks network. If you have signed into the Stacks Wallet, you might have created a name. If an application developer registered an application within Stacks, then they registered a name. Public Stacking pools can also have a name. - -#### network operation -A network operation is any change to the information about a digital asset (or smart contract) stored on a blockchain, including, for example, a change in the digital asset’s owner, or a change in the location at which it is stored on the network. How and when these network operations are performed for each digital asset is governed, on the Blockstack network, either by the Stacks Node software or a smart contract. - -#### NFT -Non fungible token. - -#### private key - -Private keys matches a corresponding public key. A public key also looks like a string of letters and numbers: - -![](/img/private.png) - -The exact format of the public and private key depend on the software you use to create them. - -#### proof-of-burn mining -The consensus algorithm used in the Stacks blockchain where miners destroy a proof-of-work-based cryptocurrency (currently Bitcoin) to get tokens; this enables the functionality where nodes can select between conflicting blockchain forks, as the blockchain fork with the most amount of cryptocurrency burned is considered to be the correct fork. - -#### proof-of-work -A proof-of-work system or proof-of-work mining is a mining mechanism where miners must expend computing power to solve complicated cryptographic puzzles, and prove that they have done so by writing the solution to the blockchain, in order to be allowed to add blocks to a blockchain. This is the mining system used, for example, by Bitcoin. - -#### public key -Public and private key pair comprise of two uniquely related cryptographic keys. It looks like a long random string of letters and numbers: `3048 0241 00C9 18FA CF8D EB2D EFD5 FD37 89B9 E069 EA97 FC20 …` The exact format of the public and private key depend on the software you use to create them. - -#### Public Key Infrastructure (PKI) -A system which returns a cryptographic public key associated with a name. - -#### replicated state machines (RSMs) -This is a model for reasoning about distributed computer programs -- any program (plus it's input) can be represented as a state machine, and when trying to get a distributed set of servers to agree on the output of an algorithm, you can model that process as N different state machines" - -#### Secret recovery Key, -Used to access an identity on the Stacks blockchain. A 24-word sequence of words for example: `applied binge crisp pictorial fiery` `dancing agreeable frogs light finish ping apple` - -#### seed phrase - -Used to access Stacks Wallet software. The seed phrase consists of 24 words in a sequence. Both the word *and its position the sequence* are important. Write down your seed phrase and store it in a secure location such as a safe deposit box. When you write the seed phrase down, include its position, for example,`1-frog, 2-horse, 3-building` and so on until you reach a final position `24-ocean`. -#### smart contract -A smart contract is a computer program written to a blockchain such as the Stacks blockchain by developers. This computer program defines the various network operations that can be performed on the digital assets on the blockchain, the computations that can be performed using the smart contract, along with defining various important properties of the respective digital assets like ownership rights and the cost in fuel required to register the digital assets. - -#### soft fork -A soft fork is a proposed update to the software governing the network that results in a post-update network that is compatible with the network as it existed prior to the update, because it restricts the network operations that can be performed after the update. - -#### Stacks (STX) address - - A STX address is a string of letters and numbers starting with an `SP` or `SM`, for example: `SM3KJBA4RZ7Z20KD2HBXNSXVPCR1D3CRAV6Q05MKT` If you created a software-only wallet with the Stacks Wallet software, the wallet has a single STX address which is also sometimes called the *wallet address*. You access a software wallet with a *seed phrase*. " - -#### Stacks blockchain -The Stacks blockchain is the custom blockchain being developed for use by the Stacks network that will use the Stacks token as its native currency and which will include the genesis block and subsequent blocks created by the mining activities described in the Stacks Network—Development of the Stacks network. - -#### Stacks Explorer -An application that allow you to view and search transactions in the blockchain. For example, https://explorer.stacks.co. - -#### Stacks node -A complete version of our open-source software available on Github at https://github.com/stacks-network/stacks-blockchain/ that governs the creation of the blockchain, the smart contracts that may be written to our blockchain, and other systems that make up the Stacks network, when run on the systems and devices of our users and developers. - -#### Stacks wallet -An application for accessing assets, identity and storage. Examples are the [Hiro Wallet](https://www.hiro.so/wallet), [xverse](https://www.xverse.app/) and [dcent](https://dcentwallet.com/). More information and example [here](../services-using-stacks/wallets). - -#### storage hub -A Gaia instance run by a hub provider or software. A Gaia hub stores data in a separate, addressed location. - -#### storage provider -A third-party company cloud or software provider that hosts one or more Gaia storage hubs. - -#### transaction -A transaction is a unit of work within a block. - -#### transaction fee -Fees paid by participants in a transaction to miners. - -#### two-sided market problem -Economic platforms having two distinct user groups that provide each other with network benefits. The Stacks platform is a classic two-sided market. - -#### username -A shorthand name for your id.blockstack. - -#### virtual blockchain -A layer that sits on top of a blockchain that introduces new functionality and operations without requiring changes to the underlying blockchain. - -#### wallet address -A wallet address is the form in which a public key can be presented and recorded on a blockchain. Wallet addresses are therefore used to assign the ownership of digital assets on the Blockstack network. - -#### watch-only wallet -A wallet without send and receive ability. You can view only balances and transaction history. - -#### web of trust mining -Web-of-trust mining provides incentive mechanisms for users where an initial trusted-set of unique users is curated in the genesis block and, in the future, the initial set of users can expand the web-of-trust after the network goes live. - -#### web3 -The exact definition is still under discussion, but it general refers to the 3rd generation of the web that is based on blockchain technology and incorporates decentralized and token-based economics. - -#### zone file -A Domain Name System (DNS) zone file is a text file that describes a DNS zone. A DNS zone is a subset, often a single domain, of the hierarchical domain name structure of the DNS. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/references/nft.md b/i18n/de/docusaurus-plugin-content-docs/current/references/nft.md deleted file mode 100644 index 033ee0a71a..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/references/nft.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: NFTs on Stacks -description: A list of sites that operate NFTs on Stacks ---- - -List of sites that operate NFTS on Stacks on alphabetical order. - -### [Byzantion](https://byzantion.xyz/) - -![website-screenshot](/img/sh_nft_byzantion.png) - -### [Gamma](https://gamma.io/) -![website-screenshot](/img/sh_nft_gamma.png) - -### [Megapont](https://www.megapont.com/) - -![website-screenshot](/img/sh_nft_megapont.png) - -### [StacksArt](https://www.stacksart.com/) - -![website-screenshot](/img/sh_nft_stacksart.png) - diff --git a/i18n/de/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md b/i18n/de/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md deleted file mode 100644 index dc6e507d5e..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Stacks info sites -description: A list of sites on alphabetical order that display status and stats of the Stacks network. ---- - -### [Haystack](https://haystack.tools/mempool) - -![website-screenshot](/img/sh_haystacks.png) - -### [Stacksdata](https://stacksdata.info/) - -![website-screenshot](/img/sh_stacksdata.png) - -### [Stacksonchain](https://stacksonchain.com) - -![website-screenshot](/img/sh_stacksonchain.png) - -### [Status Hiro](https://status.hiro.so/) - -![website-screenshot](/img/sh_statushiro.png) - -### [Stxstats](https://www.stxstats.co/) - -![website-screenshot](/img/sh_stxstats.png) - -### [Novuminsights](https://stacks.novuminsights.com/health) - -![website-screenshot](/img/sh_novuminsights.png) - -### [Onstacks](https://app.onstacks.com/) - -![website-screenshot](/img/sh_onstacks.png) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json b/i18n/de/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json deleted file mode 100644 index ebd63f366c..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Services using Stacks", - "position": 8, - "link": { - "type": "generated-index", - "description": "An 'always incomplete' list of services that use Stacks." - } -} \ No newline at end of file diff --git a/i18n/de/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md b/i18n/de/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md deleted file mode 100644 index 51defacba7..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: DeFi -description: De-Fi sites on Stacks -sidebar_position: 2 ---- - -They are multiple De-Fi sites that operate on the Stacks blockchain. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Alex - -[Alex](https://app.alexlab.co) ![](/img/sh_alex.png) - -## Arkadiko - -[Arkadiko](https://arkadiko.finance/) ![](/img/sh_arkadiko.png) - -## Catamaran Swaps - -[Catamaran Swaps](https://www.catamaranswaps.org/) allows trustless exchange of digital assets. - -![](/img/sh_catamaran.png) - -## Lnswap - -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange - -![](/img/sh_lnswap.png) - -## Neoswap - -[Neoswap](https://neoswap.party) - -![](/img/sh_neoswap.png) - -## Stackswap - -[Stackswap](https://app.stackswap.org/v2) - -![](/img/sh_stackswap.png) - diff --git a/i18n/de/docusaurus-plugin-content-docs/current/services-using-stacks/more.md b/i18n/de/docusaurus-plugin-content-docs/current/services-using-stacks/more.md deleted file mode 100644 index df0b3e2254..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/services-using-stacks/more.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: More -description: More services built on Stacks. -sidebar_position: 5 ---- - -List of sites on alphabetical order added by the community. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Citycoins - -[Citycoins](https://citycoins.co) - -![](/img/sh_citycoins.png) - -## Sigle - -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. - -![](/img/sh_sigle.png) \ No newline at end of file diff --git a/i18n/de/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md b/i18n/de/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md deleted file mode 100644 index bfa0505dc9..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: NFTs -description: NFTs on Stacks -sidebar_position: 3 ---- - -List of sites that operate NFTS on Stacks on alphabetical order. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -### [Byzantion](https://byzantion.xyz/) - -![website-screenshot](/img/sh_nft_byzantion.png) - -### [Gamma](https://gamma.io/) -![website-screenshot](/img/sh_nft_gamma.png) - -### [Megapont](https://www.megapont.com/) - -![website-screenshot](/img/sh_nft_megapont.png) - -### [StacksArt](https://www.stacksart.com/) - -![website-screenshot](/img/sh_nft_stacksart.png) - -### [Superfandom](https://superfandom.io/) - -![website-screenshot](/img/sh_superfandom.png) \ No newline at end of file diff --git a/i18n/de/docusaurus-plugin-content-docs/current/services-using-stacks/other.md b/i18n/de/docusaurus-plugin-content-docs/current/services-using-stacks/other.md deleted file mode 100644 index 199fc41da5..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/services-using-stacks/other.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Other Stacks sites -description: A list of sites on alphabetical order built on Stacks. -sidebar_position: 4 ---- - -List of sites on alphabetical order added by the community. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Alex -[Alex](https://app.alexlab.co) - -## Sigle - -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. \ No newline at end of file diff --git a/i18n/de/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md b/i18n/de/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md deleted file mode 100644 index 35ced8dac6..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Stacks info sites -description: Status and stats of the Stacks network. -sidebar_position: 1 ---- - -A list of sites on alphabetical order that display status and stats of the Stacks network. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -### [Haystack](https://haystack.tools/mempool) - -![website-screenshot](/img/sh_haystacks.png) - -### [Stacksdata](https://stacksdata.info/) - -![website-screenshot](/img/sh_stacksdata.png) - -### [Stacksonchain](https://stacksonchain.com) - -![website-screenshot](/img/sh_stacksonchain.png) - -### [Status Hiro](https://status.hiro.so/) - -![website-screenshot](/img/sh_statushiro.png) - -### [Stxstats](https://www.stxstats.co/) - -![website-screenshot](/img/sh_stxstats.png) - -### [Novuminsights](https://stacks.novuminsights.com/health) - -![website-screenshot](/img/sh_novuminsights.png) - -### [Onstacks](https://app.onstacks.com/) - -![website-screenshot](/img/sh_onstacks.png) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md b/i18n/de/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md deleted file mode 100644 index d4b4cbf18c..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Swaps -description: A list of sites that allow Swaps -sidebar_position: 2 ---- - -They are multiple sites that allow you to make swaps using the Stacks blockchain. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Catamaran Swaps - -[Catamaran Swaps](https://www.catamaranswaps.org/) allows trustless exchange of digital assets. - -![](/img/sh_catamaran.png) - -## Lnswap - -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange - -![](/img/sh_lnswap.png) - -## Neoswap - -[Neoswap](https://neoswap.party) - -![](/img/sh_neoswap.png) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md b/i18n/de/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md deleted file mode 100644 index e5ea6c5b45..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Wallets -description: Wallets for Stacks -sidebar_position: 4 ---- - -A list of hardware and software wallets for Stacks - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Blockchain.com - -[Blockchain.com](https://www.blockchain.com/wallet) - -![](/img/sh_blockchain.png) -## Boom - -[Boom](https://boom.money) - -![](/img/sh_boom.png) - -## Dcent wallet - -[D'CENT](https://dcentwallet.com) - -![](/img/sh_dcent.png) -## Hiro Wallet - -[Hiro Wallet](https://www.hiro.so/wallet) - -![](/img/sh_hirowallet.png) - -## Neptune - -[Neptune](https://neptunewallet.io) - -![](/img/sh_neptunewallet.png) - -## Xverse - -[Xverse](https://www.xverse.app/) - -![](/img/sh_xverse.png) - -## Wise - -[Wise](https://wiseapp.id) - -![](/img/sh_wiseapp.png) \ No newline at end of file diff --git a/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md b/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md deleted file mode 100644 index bd2c361985..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md +++ /dev/null @@ -1,214 +0,0 @@ ---- -title: Accounts -description: Guide to Stacks 2.0 accounts -sidebar_position: 5 ---- - -## Introduction - -Stacks 2.0 accounts are entities that own assets, like Stacks (STX) tokens. An account has an address, private key, nonce, and one or more asset balances. - -:::tip The encryption algorithm used in Stacks 2.0 is **[secp256k1](https://en.bitcoinwiki.org/wiki/Secp256k1)**. - -Additionally, [Ed25519](https://ed25519.cr.yp.to/) is also used just for the VRF (Verifiable Random Function). ::: - -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. - -:::tip -The transaction type doesn't need to be a token transfer - contract deploy and contract call transactions can change the balances of an account -::: - -## Creation - -An account is generated from a 24-word mnemonic phrase. This is often referred to as the **seed phrase**. The seed phrase provides access to Stacks 2.0 accounts. - -:::danger -If the seed phrase is lost, access to the associated account cannot be restored. No person or organization, including Blockstack, can recover a lost seed phrase. -::: - -The easiest way to generate a new Stacks 2.0 account is to use the [Stacks CLI](https://github.com/hirosystems/stacks.js/tree/master/packages/cli): - -```bash -# install CLI globally -npm install --global @stacks/cli - -# generate a new account and store details in a new file -# '-t' option makes this a testnet account -stx make_keychain -t > cli_keychain.json -``` - -`make_keychain` creates the following file: - -```js -{ - "mnemonic": "aaa bbb ccc ddd ...", - "keyInfo": { - "privateKey": "5a3f1f15245bb3fb...", - "address": "STJRM2AMVF90ER6G3RW1QTF85E3HZH37006D5ER1", - "btcAddress": "biwSd6KTEvJcyX2R8oyfgj5REuLzczMYC1", - "wif": "L4HXn7PLmzoNW...", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -| Field | Description | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `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.privateKey` | Private key for the account. Required for token transfers and often referred to as `senderKey` | -| `keyInfo.address` | Stacks address for the account | -| `keyInfo.btcAddress` | Corresponding BTC address for the account. | -| `keyInfo.wif` | Private key of the btcAddress in compressed format. | -| `keyInfo.index` | Nonce for the account, starting at 0 | - -Note that a new account automatically exists for each new private key. There is no need to manually instantiate an account on the Stacks 2.0 blockchain. - -:::tip Addresses are created by generating the [RIPEMD-160 hash](https://en.wikipedia.org/wiki/RIPEMD#RIPEMD-160_hashes) of the [SHA256](https://en.bitcoinwiki.org/wiki/SHA-256) of the public key. BTC addresses are encoded with [Base58Check](https://en.bitcoin.it/wiki/Base58Check_encoding). For Stacks addresses, [c32check](https://github.com/stacks-network/c32check) is used. Deriving an address from a public key can be done without internet access, for instance using the c32check `c32addressDecode` method. ::: - -Alternatively to the CLI creation, the [Stacks Transactions JS](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library can be used: - -```js -import { - makeRandomPrivKey, - privateKeyToString, - getAddressFromPrivateKey, - TransactionVersion, -} from '@stacks/transactions'; - -const privateKey = makeRandomPrivKey(); - -// Get public key from private -const publicKey = getPublicKey(privateKey); - -const stacksAddress = getAddressFromPrivateKey( - privateKeyToString(privateKey), - TransactionVersion.Testnet // remove for Mainnet addresses -); -``` - -A second alternative would be to use [stacks-gen](https://github.com/psq/stacks-gen). This tool will generate all the keys you need in one place, including the values needed for calling the stacking contract, and also a WIF key for use with `bitcoind`. - -#### stacks-gen prerequisite - -Install [npx](https://github.com/npm/npx) if not already installed. (npx will check whether `` exists in \$PATH, or in the local project binaries, and execute that. If `` is not found, it will be installed prior to execution). - -``` -npm install -g npx -``` - -#### stacks-gen usage - -``` -npx -q stacks-gen sk --testnet - -{ - "phrase": "guide air pet hat friend anchor harvest dog depart matter deny awkward sign almost speak short dragon rare private fame depart elevator snake chef", - "private": "0351764dc07ee1ad038ff49c0e020799f0a350dd0769017ea09460e150a6401901", - "public": "022d82baea2d041ac281bebafab11571f45db4f163a9e3f8640b1c804a4ac6f662", - "stacks": "ST16JQQNQXVNGR8RZ1D52TMH5MFHTXVPHRV6YE19C", - "stacking": "{ hashbytes: 0x4d2bdeb7eeeb0c231f0b4a2d5225a3e3aeeed1c6, version: 0x00 }", - "btc": "mnYzsxxW271GkmyMnRfiopEkaEpeqLtDy8", - "wif": "cMh9kwaCEttgTQYkyMUYQVbdm5ZarZdBHErcq7mXUChXXCo7CFEh" -} -``` - -:::tip The stacking object with hashbytes and a version represents the bitcoin address derived from the Stacks address. Read more about the [bitcoin address format](stacking#bitcoin-address). ::: - -Full documentation available at [stacks-gen](https://github.com/psq/stacks-gen). - -## Querying - -### Get Stacks (STX) balance and nonce - -STX balance and nonce can be obtained through the [`GET /v2/accounts/`](https://docs.hiro.so/api#operation/get_account_info) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/accounts/' -``` - -Sample response: - -```js -{ - "balance": "0x0000000000000000002386f26f3f40ec", - "nonce": 17 -} -``` - -:::tip -The balance string represents an unsigned 128-bit integer (big-endian) in hex encoding -::: - -### Get all token balances - -All token balances can be obtained through the [`GET /extended/v1/address//balances`](https://docs.hiro.so/api#operation/get_account_balance) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/address//balances' -``` - -Sample response: - -```js -{ - "stx": { - "balance": "0", - "total_sent": "0", - "total_received": "0" - }, - "fungible_tokens": {}, - "non_fungible_tokens": {} -} -``` - -:::tip Stacks accounts cannot hold bitcoins. The best way to obtain corresponding BTC balances is to derive the BTC address from the Stacks address (using [`c32check`](https://github.com/stacks-network/c32check#c32tob58-b58toc32)) and query the Bitcoin network. ::: - -### Get all asset events - -All asset events associated with the account can be obtained through the [`GET /extended/v1/address//assets`](https://docs.hiro.so/api#operation/get_account_balance) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/address//assets' -``` - -Sample response: - -```js -{ - "limit": 20, - "offset": 0, - "total": 0, - "results": [ - { - "event_index": 5, - "event_type": "non_fungible_token_asset", - "asset": { - "asset_event_type": "transfer", - "asset_id": "ST2W14YX9SFVDB1ZGHSH40CX1YQAP9XKRAYSSVYAG.hello_world::hello-nft", - "sender": "SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR", - "recipient": "SM2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQVX8X0G", - "value": { - "hex": "0x0100000000000000000000000000000001", - "repr": "u1" - } - } - }, - { - "event_index": 3, - "event_type": "fungible_token_asset", - "asset": { - "asset_event_type": "mint", - "asset_id": "ST2W14YX9SFVDB1ZGHSH40CX1YQAP9XKRAYSSVYAG.hello_world::novel-token-19", - "sender": "", - "recipient": "SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR", - "amount": "12" - } - } - ] -} -``` diff --git a/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/index.md b/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/index.md deleted file mode 100644 index 1533219df9..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/index.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Understand Stacks -description: Learn more about the Stacks 2.0 blockchain -sidebar_position: 1 ---- - -![](/img/SBC-L-2x-10.png) -## Introduction - -Stacks 2.0 is a layer-1 blockchain that connects to Bitcoin and brings smart contracts and decentralized apps to it. Smart contracts and apps developed on the Stacks platform are natively integrated with the security, stability, and economic power of Bitcoin. - -## Capabilities - -Read more about the features provided by the Stacks 2.0 blockchain. - - - -:::tip Check out the [technical specifications](technical-specs) for a brief overview ::: - - - - -A detailed [comparison of the Stacks blockchain to other blockchain technologies][] is available at the Stacks Foundation blog. -### Consensus mechanism -![](/img/pages/stacking.svg) Stacks 2.0 implements a new mining mechanism called Proof of Transfer ("PoX"). PoX is a consensus algorithm between two blockchains. It uses an established blockchain (in this case Bitcoin) to secure a new blockchain (Stacks). - -PoX connects to Bitcoin with a 1:1 block ratio, meaning anything that happens on the Stacks blockchain can be verified on the Bitcoin Blockchain. - -Instead of burning electricity on proof of work, PoX reuses already minted bitcoins as "proof of computation" and miners represent their cost of mining in bitcoins directly. - - -[Read more about Proof of Transfer](proof-of-transfer) -### Mining - -![](/img/pages/testnet-sm.svg) Mining is required to make the network usable, trustworthy, and secure. Miners verify incoming transactions, participate in the consensus mechanism, and write new blocks to the blockchain. - -To incentivize mining, miners receive freshly minted Stacks (STX) tokens if they win the bid for becoming the leader of the next round. - -[Read more about Mining](mining) - -### Stacking - -Bitcoins used for miner bids are sent to a set of specific addresses corresponding to Stacks (STX) tokens holders that are actively participating in consensus ("Stackers"). Thus, rather than being destroyed, the bitcoins consumed in the mining process go to productive Stacks holders as a reward based on their holdings of Stacks and participation in the Stacking algorithm. - -Stackers have to lock up their Stacks (STX) tokens for a certain period of time. - -[Read more about Stacking](stacking) - -### Smart contracts - -![](/img/pages/write-smart-contracts-sm.svg) Clarity is a new language for smart contracts on the Stacks 2.0 blockchain. The Clarity smart contract language optimizes for predictability and security. - -Stacks 2.0 anchors clarity smart contracts to Bitcoin making it possible for smart contracts to operate based on actions seen on the bitcoin blockchain. - -:::note The [Clarity open-source project](https://clarity-lang.org/) is supported by Stacks and [Algorand](https://www.algorand.com/) ::: - - -Clarity is distinct from other languages designed for writing smart contracts in a few ways: - -- **Predictability**: The Clarity language uses precise and unambiguous syntax that allows developers to predict exactly how their contracts will be executed. -- **Security**: The Clarity language allows users to supply their own conditions for transactions that ensure that a contract may never unexpectedly transfer a token owned by a user. -- **No compiler**: Contracts written in Clarity are broadcasted on the Stacks blockchain exactly as they are written by developers. This ensures that the code developers wrote, analyzed, and tested, is exactly what gets executed. - -[Read more about Clarity](../write-smart-contracts/clarity-language/) - -## Guides - -Read one of our guides to understand the ins and outs of the Stacks 2.0 blockchain. - -* [Account](../understand-stacks/accounts) -* [Transactions](../understand-stacks/transactions) -* [Network](../understand-stacks/network) -* [Microblocks](../understand-stacks/microblocks) - -[comparison of the Stacks blockchain to other blockchain technologies]: https://stacks.org/stacks-blockchain diff --git a/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md b/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md deleted file mode 100644 index de64c617f4..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: Microblocks -description: Guide to Stacks Microblocks -sidebar_position: 8 ---- - -## Introduction - -Microblocks are a protocol-level feature of the Stacks blockchain that solve the technical challenge of transaction latency. Because each Stacks block is anchored to a Bitcoin block through the [Proof-of-Transfer consensus mechanism](../understand-stacks/proof-of-transfer), Stacks is necessarily limited to the same block times as the Bitcoin network. Microblocks allow the Stacks blockchain to perform state transitions between anchor blocks. - -Microblocks are a powerful mechanism for developers to create performant, high quality applications on Stacks, while still inheriting the security of Bitcoin. - -## Transaction states - -The [Stacks block production model](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.) is described in SIP-001. The standard outlines the mechanism by which elected block leaders can produce blocks on the Stacks blockchain either by batching transactions or by streaming them. Microblocks are the product of the streaming model. - -If a block leader has elected to mine microblocks, the leader selects transactions from the mempool and package them into microblocks during the current epoch. Microblocks are blocks of transactions included by a miner after the previous anchor block has been mined, but before the next block is selected. Transactions included in microblocks are processed by the network: their results are known. - -Consider a transaction from the perspective of the number of block confirmations it has. A transaction included in a microblock might have the following example lifecycle: - -``` -Transaction 1 is broadcast to the mempool. It has 0 confirmations. -Transaction 1 is included in a microblock. It still has 0 confirmations, but the results of the transaction are known -Transaction 1 is included in the next anchor block. It has 1 confirmation. -The next Stacks block confirms the previous block. Transaction 1 has 2 confirmations. -The next Stacks block confirms the previous block. Transaction 1 has 3 confirmations. -... -``` - -Consider a similar transaction that is not included in a microblock: - -``` -Transaction 2 is broadcast to the mempool. It has 0 confirmations. -Transaction 2 is included in the next anchor block. It has 1 confirmation. -The next Stacks block confirms the previous block. Transaction 2 has 2 confirmations. -The next Stacks block confirms the previous block. Transaction 2 has 3 confirmations. -``` - -The lifecycles of the two transactions are similar, but the difference is pending state. Many Bitcoin wallets display 0-confirmation balances: your wallet balance with any mempool transactions already applied. This is useful because it tells you when you've sent a transaction or received one. With smart contracts, displaying pending state is not as straightforward, because smart contracts do not just transfer inputs to outputs, they may call other contracts, emit events, or perform other computations. A transaction processed in a microblock generates all that information. - -:::tip -If a transaction is dependent on a chain state that could by altered by previous transactions with serious -implications, you should carefully consider whether it should be performed using microblocks. -::: - -## Enabling microblocks - -Miners can choose to enable or disable microblocks in their mining configuration. As a best practice, miners should enable microblock mining. When an application or user submits a transaction, the transaction can include an argument that requires the transaction to be in a microblock, an anchor block, or in either. - -### Transactions - -Transactions include an option that controls if a miner should include them in microblocks or in anchor blocks. The anchor mode transaction option is an optional argument that controls whether a transaction must be included in an anchor block or a microblock, or is eligible for either. - -### Mining - -Stacks miners must enable microblocks in their miner configuration to implement the block streaming model. For more information, see [mining microblocks](../understand-stacks/mining#microblocks). - -## Developing with microblocks - -In most cases, information from transactions included in microblocks should be treated like information from any other block. Wallets and explorers should display the consequences of microblock transactions as the current state of the network. This state should be acknowledged as tentative. - -A microblock transaction can end up being reorganized in the next block rather than just being confirmed as-is. Because of this, your UI should communicate to users if the outputs of a transaction changed, or if the transaction's associated block changed. This is the same outcome as if a 1-block fork occurred. - -### Stacks.js libraries - -Stacks.js provides the [AnchorMode][] argument on transaction objects so that your application can set the microblocks preference for transactions. - -### API - -:::danger API support for microblocks is a work-in-progress. Review the [API documentation][microblocks_api] carefully to ensure that you are up-to-date on the latest implementation details for microblocks. ::: - -The Stacks Blockchain API exposes microblocks through several endpoints. Please review the [Stacks Blockchain API guide][] for more details. - -## Best practices - -Working with microblocks is a design decision that you must make for your own application. When working with microblocks, the following best practices are recommended. - -### Handling nonce - -Nonce handling with microblocks is challenging because the next account nonce must take into account any nonce values included in microblocks, which may not yet be included in an anchor block. The Stacks Blockchain API [provides an endpoint][] to retrieve the next nonce for a given principal. - -### Application design - -The state of microblock transactions should be carefully communicated to users. No transaction is final until it's included in an anchor block, and your application design should reflect this. - -The following guidelines are provided as an initial set of best practices for UI design when incorporating microblocks into your application. - -#### Explorers - -Display pending state, but warn that a transaction is still pending. Indicate visually that displayed balances depend on pending state. - -#### Wallets - -Display pending state, but warn that a transaction is still pending. Indicate visually that displayed balances depend on pending state. - -#### Exchanges - -Continue to count confirmations, microblocks should be considered pending. - -#### Applications - -Microblock communication is highly app-dependent. For some applications, displaying a pending or 0-confirmation transaction as confirmed may be fine. For example, storing data on the chain, or querying the BNS contract. For other applications, such as the transfer of real value, waiting for 3-confirmations would be prudent before displaying the state as confirmed. - -[AnchorMode]: https://stacks.js.org/enums/transactions.AnchorMode.html -[Stacks Blockchain API guide]: https://docs.hiro.so/get-started/stacks-blockchain-api#microblocks-support -[provides an endpoint]: https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling -[microblocks_api]: https://docs.hiro.so/api#tag/Microblocks diff --git a/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/mining.md b/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/mining.md deleted file mode 100644 index fa1f56ed3f..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/mining.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Mining -description: A guide to mining on Stacks 2.0 -sidebar_position: 4 ---- - -## Introduction - -This guide highlights some technical details related to mining on the Stacks 2.0 network. - -For steps on how to setup your own miner please refer to [miner on tesnet](nodes-and-miners/miner-testnet.md) and [miner on mainnet](nodes-and-miners/miner-testnet.md). - -## Mining frequency - -A new Stacks block may be mined once per Bitcoin block. To be considered for mining a block, a miner must have a block commit included in a Bitcoin block. If a miner wishes to update their commitment after submission, they may use Bitcoin Replace-By-Fee. - -## Coinbase rewards - -Miners receive coinbase rewards for blocks they win. - -The reward amounts are: - -- 1000 STX per block are released in the first 4 years of mining -- 500 STX per block are released during the following 4 years -- 250 STX per block are released during the following 4 years -- 125 STX per block are released from then on indefinitely. - -These "halvings" are synchronized with Bitcoin halvings. - -![coinbase rewards](/img/pages/coinbase-rewards.png) - -## Transaction fees - -Miners receive Stacks fees for transactions mined in any block they produce. - -For transactions mined in microblocks, the miner that produces the microblock receives 40% of the fees, while the miner that confirms the microblock receives 60% of the fees. - -## Reward maturity - -Block rewards and transaction fees take 100 blocks on the Bitcoin blockchain to mature. After successfully mining a block your rewards appear in your Stacks account after ~24 hours. - -## Mining with proof-of-transfer - -Miners commit Bitcoin to **two** addresses in every leader block commit. The amount committed to each address must be the same. The addresses are chosen from the current reward set of stacking participants. Addresses are chosen using a verifiable-random-function, and determining the correct two addresses for a given block requires monitoring the Stacks chain. - -![mining with pox](/img/pages/mining-with-pox.png) - -## 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, 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. - -While there is no minimum BTC commitment enforced by the protocol, in practice, there's a floor constrained by [dust](https://unchained-capital.com/blog/dust-thermodynamics/)": basically, if the fees for a transaction exceed the value of the spent output, it's considered dust. How dust is [calculated](https://github.com/bitcoin/bitcoin/blob/master/src/policy/policy.cpp#L14) depends on a number of factors, we've found 5,500 satoshis to be good lower bound per [output](https://learnmeabitcoin.com/technical/output). Bitcoin transactions from Stacks miners contain two outputs (for Proof-of-Transfer), so a commitment of at least 11,000 satoshis / block is recommended. - -To calculate the amount of BTC to send miners should: - -- Guess the price BTC/STX for the next day (100 blocks later) -- Guess the total amount of BTCs committed by all miners - -## Microblocks - -The Stacks blockchain produces blocks at the same rate as the Bitcoin blockchain. In order to provide lower latency transactions, miners can opt to enable microblocks. Microblocks allow the current block leader to stream transactions and include their state transitions in the current epoch. - -If a block leader opts to produce microblocks, the next leader builds the chain tip off the last microblock that the current leader produces. - -The block streaming model is described in [SIP-001][]. - -[SIP-001]: https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md#operation-as-a-leader diff --git a/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/network.md b/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/network.md deleted file mode 100644 index 2aa8fd4b0e..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/network.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -title: Network -description: Guide to the Stacks 2.0 network -sidebar_position: 7 ---- - -## Tokens - -Stacks (STX) tokens are the native tokens on the Stacks 2.0 blockchain. The smallest fraction is one micro-STX. 1,000,000 micro-STX make one Stacks (STX). - -STX amounts should be stored as integers (8 bytes long), and represent the amount of micro-STX. For display purposes, micro-STX are divided by 1,000,000 (decimal precision of 6). - -## 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 in bytes. The fee rate is a market determined variable. For the [testnet](testnet), it is set to 1 micro-STX. - -Fee estimates can obtained through the [`GET /v2/fees/transfer`](https://docs.hiro.so/api#operation/get_fee_transfer) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/fees/transfer' -``` - -The API will respond with the fee rate (as integer): - -```json -1 -``` - -[The Stacks Transactions JS library](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) supports fee estimation for: - -- token transfers (`estimateTransfer`) -- contract deploys (`estimateContractDeploy`) -- non read-only contract calls (`estimateContractFunctionCall`) - -:::tip For an implementation using a different language than JavaScript, please review [this reference implementation](https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/src/builders.ts#L97). ::: - -## Nonces - -Every account carries a [nonce property](https://en.wikipedia.org/wiki/Cryptographic_nonce) that indicates the number of transactions processed for the given account. Nonces are one-time codes, starting at `0` for new accounts, and incremented by 1 on every transaction. - -Nonces are added to all transactions and help identify them in order to ensure transactions are processed in order and to avoid duplicated processing. - -:::tip -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 is constructed, the most recent nonce of the account needs to fetched and set. - -:::tip The API provides an endpoint to [simplify nonce handling](https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling). ::: - -## Confirmations - -The Stacks 2.0 network is anchored onto the bitcoin network. This allows transactions on Stacks to inherit the same finality and security of the Bitcoin blockchain. - -The time to mine a block, to confirm transactions, will eventually match the expected "block time" of the bitcoin network: 10 minutes. - -:::tip Transactions can also be mined in [microblocks](microblocks), reducing the latency significantly. ::: - -The block time is hardcoded and will change throughout the implementation phases of the [testnet](testnet). The current block time can be obtained through the [`GET /extended/v1/info/network_block_times`](https://docs.hiro.so/api#operation/get_network_block_times) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/info/network_block_times' -``` - -The API will respond with the block time (in seconds): - -```js -{ - "testnet": { - "target_block_time": 120 - }, - "mainnet": { - "target_block_time": 600 - } -} -``` - -## Read-only function calls - -Smart contracts can expose public function calls. For functions that make state modifications to the blockchain, transactions need to be generated and broadcasted. - -However, for read-only function calls, transactions are **not** required. Instead, these calls can be done using the [Stacks Blockchain API](https://docs.hiro.so/get-started/stacks-blockchain-api). - -:::tip -Read-only function calls do not require transaction fees -::: - -A read-only contract call can be done using the [`POST /v2/contracts/call-read///`](https://docs.hiro.so/api#operation/call_read_only_function) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl --location --request POST 'https://stacks-node-api.testnet.stacks.co/v2/contracts/call-read///' \ ---header 'Content-Type: application/json' \ ---data-raw '{ - "sender": ".", - "arguments": [, ...] -}' -}' -}' -}' -``` - -Sample response for a successful call: - -```js -{ - "okay": true, - "result": "" -} -``` - -:::tip To set the function call arguments and read the result, [Clarity values](../write-smart-contracts/values) need to be serialized into a hexadecimal string. The [Stacks Transactions JS](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library supports these operations ::: - -## Querying - -Stacks 2.0 network details can be queried using the [Stacks Blockchain API](https://docs.hiro.so/get-started/stacks-blockchain-api). - -### Health check - -The [status checker](https://stacks-status.com/) is a service that provides a user interface to quickly review the health of the Stacks 2.0 blockchain. - -### Network info - -The network information can be obtained using the [`GET /v2/info`](https://docs.hiro.so/api#operation/get_core_api_info) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/info' -``` - -Sample response: - -```js -{ - "peer_version": 385875968, - "burn_consensus": "826401d65cf3671210a3fb135d827d549c0b4d37", - "burn_block_height": 1972, - "stable_burn_consensus": "e27ea23f199076bc41a729d76a813e125b725f64", - "stable_burn_block_height": 1971, - "server_version": "blockstack-core 0.0.1 => 23.0.0.0 (master:bdd042242+, release build, linux [x86_64]", - "network_id": 2147483648, - "parent_network_id": 3669344250, - "stacks_tip_height": 933, - "stacks_tip": "1f601823fbcc5b6b2215b2ff59d2818fba61ee4a3cea426d8bc3dbb268005d8f", - "stacks_tip_burn_block": "54c56a9685545c45accf42b5dcb2787c97eda8185a1c794daf9b5a59d4807abc", - "unanchored_tip": "71948ee211dac3b241eb65d881637f649d0d49ac08ee4a41c29217d3026d7aae", - "exit_at_block_height": 28160 -} -``` diff --git a/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md b/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md deleted file mode 100644 index c933f7af68..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Proof of Transfer -description: Understand the proof-of-transfer consensus mechanism -sidebar_position: 3 ---- - -## Overview - -Consensus algorithms for blockchains require compute or financial resources to secure the blockchain. The general practice of decentralized consensus is to make it practically infeasible for any single malicious actor to have enough computing power or ownership stake to attack the network. - -Popular consensus mechanisms in modern blockchains include proof-of-work, in which nodes dedicate computing resources, and proof-of-stake, in which nodes dedicate financial resources to secure the network. - -Proof-of-burn is a novel consensus mechanism where miners compete by ‘burning’ (destroying) a proof-of-work cryptocurrency as a proxy for computing resources. - -Proof-of-transfer (PoX) is an extension of the proof-of-burn mechanism. 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. - -![PoX mechanism](/img/pox-mechanism.png) - -This allows network participants to secure the PoX cryptocurrency network and earn a reward in the base cryptocurrency. Thus, proof-of-transfer blockchains are anchored on their chosen proof-of-work chain. Stacks uses [Bitcoin](#why-bitcoin) as its anchor chain. - -![PoX participants](/img/pox-participants.png) - -## Why Bitcoin? - -There are a number of reasons that Stacks chose Bitcoin as the blockchain to power consensus. It's the oldest blockchain protocol, having launched in 2009, and has become a recognized asset outside of the cryptocurrency community. BTC has held the highest market capitalization of any cryptocurrency for the past decade. - -Bitcoin champions simplicity and stability, and has stood the test of time. Influencing or attacking the network is infeasible or impractical for any potential hackers. It's one of the only cryptocurrencies to capture public attention. Bitcoin is a household name, and is recognized as an asset by governments, large corporations, and legacy banking institutions. Lastly, Bitcoin is largely considered a reliable store of value, and provides extensive infrastructure to support the proof-of-transfer consensus mechanism. - -SIP-001 provides a full [list of reasons why Bitcoin was chosen to secure Stacks](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md). - -![btc-stacks](/img/pox-why-bitcoin.png) - -## Blocks and microblocks - -The Stacks blockchain allows for increased transaction throughput using a mechanism called microblocks. Bitcoin and Stacks progress in lockstep, and their blocks are confirmed simultaneously. On Stacks, this is referred to as an ‘anchor block’. An entire block of Stacks transactions corresponds to a single Bitcoin transaction. This significantly improves cost/byte ratio for processing Stacks transactions. Because of simultaneous block production, Bitcoin acts as a rate-limiter for creating Stacks blocks, thereby preventing denial-of-service attacks on its peer network. - -However, in between Stacks anchor blocks settling on the Bitcoin blockchain, there are also a varying number of microblocks that allow rapid settlement of Stacks transactions with a high degree of confidence. This allows Stacks transaction throughput to scale independently of Bitcoin, while still periodically establishing finality with the Bitcoin chain. The Stacks blockchain adopts a block streaming model whereby each leader can adaptively select and package transactions into their block as they arrive in the mempool. Therefore when an anchor block is confirmed, all of the transactions in the parent microblock stream are packaged and processed. This is an unprecedented method for achieving scalability without creating a totally separate protocol from Bitcoin. - -![stx-microblock](/img/stx-microblocks.png) - -## Unlocking Bitcoin capital - -Stacks also unlocks the hundreds of billions in capital in Bitcoin, and gives Bitcoiners new opportunities to use and earn BTC. Stacks is a accompaniment to the Bitcoin ecosystem, and the two networks working in tandem enables totally novel ways of using BTC. The Stacks ecosystem makes interactive cryptocurrency applications available to Bitcoin holders. Additionally, By stacking STX tokens and participating in the PoX consensus mechanism, users have the opportunity to earn BTC while securing the Stacks chain. - -![Unlocking Bitcoin](/img/pox-unlocking-btc.png) - -## Clarity and the Bitcoin state - -Clarity smart contracts also have unique visibility into the state of the Bitcoin blockchain. This means that contract logic in a Clarity file has the ability to trigger when specific Bitcoin transactions are confirmed. Clarity smart contracts have a built in Simple Payment Verification (SPV) proofs for Bitcoin that make interacting with Bitcoin’s state much simpler for developers. Additionally, Clarity contracts can fork with the original Bitcoin chain. Therefore, in an edge case where Bitcoin forks, developers wouldn’t have to worry about adjusting the deployment of their smart contracts. - -## See also - -- [Read the full PoX whitepaper](https://community.stacks.org/pox) -- [Watch Executive Chair of Hiro Muneeb Ali and Evangelist Joe Bender give an overview of Stack's breakthrough PoX mining mechanism](https://www.youtube.com/watch?v=NY_eUrIcWOY) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md b/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md deleted file mode 100644 index 5f3863e8dd..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: Stacking -description: Introduction to the reward mechanism of Proof-of-Transfer -sidebar_position: 9 ---- - -## Introduction - -Stacking rewards Stacks (STX) token holders with bitcoin for providing a valuable service to the network by locking up their tokens for a certain time. - -![](/img/stacking.png) - -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. - -:::info The Stacking consensus algorithm is implemented as a smart contract, using [Clarity](../write-smart-contracts/). [Read more about the contract](../noteworthy-contracts/stacking-contract). ::: - -## Stacking flow - -The Stacking mechanism can be presented as a flow of actions: - -![Stacking flow](/img/stacking-illustration.png) - -1. Make API calls to get details about the upcoming reward cycle -2. For a specific Stacks account, confirm eligibility -3. Confirm the BTC reward address and the lockup duration -4. The transaction is broadcasted and the STX tokens are locked. This needs to happen before the prepare phase of the next reward cycle, the last 100 Bitcoin blocks of the ongoing reward phase -5. The Stacking mechanism executes reward cycles and sends out rewards to the set BTC reward address -6. During the lockup period, details about unlocking timing, rewards and more can be obtained -7. Once the lockup period is passed, the tokens are released and accessible again -8. Display reward history, including details like earnings for previous reward cycles - -:::info Keep in mind that the target duration for a reward cycles is ~2 weeks. This duration is based on the target block time of the network (10 minutes) and can be higher at times due to [confirmation time variances](https://www.blockchain.com/charts/median-confirmation-time) of the bitcoin network. ::: - -## Stacking delegation flow - -The Stacking flow is different for delegation use cases: - -![Delegated tacking flow](/img/stacking-delegation-illustration.png) - -- Before Stacking can be initiated for a token holder, the delegator needs to be granted permission to Stack on behalf of the account owner. The permission is restricted to the maximum amount the delegator is allowed to Stack. The maximum amount is not limited by the available funds and can be set much higher. An account can only be associated with one single delegator -- The account has to define the delegation relationship. They can optionally restrict the Bitcoin reward address that must be used for payouts, and the expiration burn block height for the permission, thus limiting the time a delegator has permission to Stack -- Delegators have to lock Stacks from different accounts ("pooling phase") until they reach the minimum amount of Stacks required to participate in Stacking -- Once a delegator locks enough STX tokens, they can finalize and commit their participation in the next reward cycle -- Certain delegation relationships may allow the STX holder to receive the payout directly from the miner (step 5/6) -- The termination of the delegation relationship can either happen automatically based on set expiration rules or by actively revoking delegation rights - -## PoX mining - -PoX mining is a modification of Proof-of-Burn (PoB) mining, where instead of sending the committed Bitcoin to a burn address, it's transferred to eligible STX holders that participate in the stacking protocol. - -:::note -A PoX miner can only receive newly minted STX tokens when they transfer Bitcoin to eligible owners of STX tokens -::: - -![Mining flow](/img/pox-mining-flow.png) - -Miners run Stacks nodes with mining enabled to participate in the PoX mechanism. The node implements the PoX mechanism, which ensures proper handling and incentives through four key phases: - -- Registration: miners register for a future election by sending consensus data to the network -- Commitment: registered miners transfer Bitcoin to participate in the election. Committed BTC are sent to a set participating STX token holders -- Election: a verifiable random function chooses one miner to write a new block on the Stacks blockchain -- Assembly: the elected miner writes the new block and collects rewards in form of new STX tokens - -## Token holder eligibility - -Stacks (STX) token holders don't automatically receive stacking rewards. Instead, they must: - -- Commit to participation before a reward cycle begins -- Commit the minimum amount of STX tokens to secure a reward slot, or pool with others to reach the minimum -- Lock up STX tokens for a specified period -- Provide a supported Bitcoin address to receive rewards (native segwit is not supported) - -The following diagram describes how the minimum STX tokens per slot is determined. More information on [dynamic minimums for stacking](https://stacking.club) is available at stacking.club. - -![Dynamic minimum for individual eligibility](/img/stacking-dynamic-minimum.png) - -Token holders have a variety of providers and tools to support their participation in Stacking. The Stacks website contains a [list of stacking providers and pools](https://stacks.org/stacking#earn). - -## Stacking in the PoX consensus algorithm - -Stacking is a built-in capability of PoX and occurs through a set of actions on the Stacks blockchain. The [full proof-of-transfer implementation details](https://github.com/stacks-network/stacks-blockchain/blob/develop/sip/sip-007-stacking-consensus.md) are in SIP-007. Below is a summary of the most relevant actions of the algorithm. - -![PoX cycles](/img/pox-cycles.png) - -- Stacking happens over reward cycles with a fixed length. In each reward cycle, a set of Bitcoin addresses associated with stacking participants receive BTC rewards -- A reward cycle consists of two phases: prepare and reward -- During the prepare phase, miners decide on an anchor block and a reward set. Mining any descendant forks of the anchor block requires transferring mining funds to the appropriate reward addresses. The reward set is the set of Bitcoin addresses which are eligible to receive funds in the reward cycle -- Miners register as leader candidates for a future election by sending a key transaction that burns cryptocurrency. The transaction also registers the leader's preferred chain tip (must be a descendant of the anchor block) and commitment of funds to 2 addresses from the reward set -- Token holders register for the next rewards cycle by broadcasting a signed message that locks up associated STX tokens for a protocol-specified lockup period, specifies a Bitcoin address to receive the funds, and votes on a Stacks chain tip -- Multiple leaders can commit to the same chain tip. The leader that wins the election and the peers who also burn for that leader collectively share the reward, proportional to how much each one burned -- Token holders' locked up tokens automatically unlock as soon as the lockup period finishes - -## Bitcoin address - -:::danger You must provide a BTC address in one of two formats: - -* [Legacy (P2PKH)](https://en.bitcoin.it/wiki/Transaction#Pay-to-PubkeyHash), which starts with `1`. - -* [Segregated Witness / Segwit (P2SH)](https://en.bitcoin.it/wiki/Pay_to_script_hash), which starts with `3`. The "Native Segwit" format (which starts with `bc1`), for example, is not supported. ::: - -The Stacking contract needs a special format for the Bitcoin address (the reward address). This is required to ensure that miners are able to correctly construct the Bitcoin transaction containing the reward address. - -The address must be specified in the following format using the Clarity language: - -```clar -;; a tuple of a version and hashbytes buffer -(pox-addr (tuple (version (buff 1)) (hashbytes (buff 20)))) -``` - -The `version` buffer must represent what kind of bitcoin address is being submitted. It can be one of the following: - -```js -SerializeP2PKH = 0x00, // hash160(public-key), same as bitcoin's p2pkh -SerializeP2SH = 0x01, // hash160(multisig-redeem-script), same as bitcoin's multisig p2sh -SerializeP2WPKH = 0x02, // hash160(segwit-program-00(p2pkh)), same as bitcoin's p2sh-p2wpkh -SerializeP2WSH = 0x03, // hash160(segwit-program-00(public-keys)), same as bitcoin's p2sh-p2wsh -``` - -The `hashbytes` are the 20 hash bytes of the bitcoin address. You can obtain that from a bitcoin library, for instance using [`bitcoinjs-lib`](https://github.com/bitcoinjs/bitcoinjs-lib): - -```js -const btc = require('bitcoinjs-lib'); -console.log( - '0x' + btc.address.fromBase58Check('1C56LYirKa3PFXFsvhSESgDy2acEHVAEt6').hash.toString('hex') -); -``` - -## Choosing the right Stacking strategy - -[Here](https://blog.stacks.co/stacking-strategy) is an interesting article that may help you choose the right Stacking stategy. - - -## Where to Stacks? - -You can Stack on your own, on a pool or on an exchange: -### Stacking on your own - -Stacking on your own is non-custodial. - -Stacking on your own requires a protocol minimum (amount changes but about 100,000 STX). - -[Hiro Wallet](https://www.hiro.so/wallet) allows stacking on your own. - -### Stacking on a pool - -Stacking on a pool allows Stacking without the requirement of the protocol minumum. - -Some available pools are: - -| Pool | Type | Pays rewards in | Fee | Minimum amount | -| --------------------------------------------------- | ------------- |:---------------:| --- |:--------------:| -| [Friedger's Pool](https://pool.friedger.de/) | Non custodial | STX or xBTC | No | 40 STX | -| [Planbetter](https://planbetter.org/) | Non custodial | BTC | 5% | 200 STX | -| [Stacked](https://staking.staked.us/stacks-staking) | Non custodial | BTC | | 100,000 STX | -| [Xverse](https://www.xverse.app/) | Non custodial | BTC | No | 100 STX | - -### Stacking on an exchange - -Stacking on an exchange is custodial, meaning you are trusting the exchange with your Stacks. - -Several exchanges allow Stacking directly on their sites. Examples are [Okcoin](https://www.okcoin.com) and [Binance](https://www.binance.com/en/staking) - -## Stacking statistics - -You can view all sorts of Stacking data and statistics on [Stacking Club](https://stacking.club) \ No newline at end of file diff --git a/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md b/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md deleted file mode 100644 index d942d6af8f..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Stacks Blockchain API -description: Interacting with the Stacks 2.0 Blockchain via API ---- - -## Temporal page because of a Crowdin bug \ No newline at end of file diff --git a/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md b/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md deleted file mode 100644 index e370129d1d..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Technical Specifications -description: Summary of technical specifications of Stacks 2.0 -sidebar_position: 10 ---- - -## Consensus - -- Proof of Transfer (PoX) as described in [SIP-007](https://github.com/stacksgov/sips/blob/main/sips/sip-007/sip-007-stacking-consensus.md) -- Network will transition to Proof of Burn (PoB) as described in [SIP-001](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md) after 10 years. [Learn more about Proof-of-Burn in SIP-001](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md). -- Threat model - - 51% of malicious Stacks mining power can perform a double-spend attack - - 51% of malicious Bitcoin mining power can reorg the Stacks chain -- Different actors and their roles - - Stacks Miners package transactions into blocks, mine them through a Bitcoin transaction, propagate them, and if they win the block race, append microblocks to their winning block until the next block is mined. The next block confirms the microblock stream. - - Stacks Holders may alter the calculation of block limits (subject to a miner veto) and may vote to disable Proof-of-Transfer rewards for a reward cycle. -- Transactions are considered final when the corresponding "block commit" transaction on Bitcoin is finalized. Typically this can by 3-6 confirmations. -- For more details, see [Proof of Transfer](proof-of-transfer). - -## Proof of Transfer Mining - -- Coinbase reward schedule: - - 1000 STX/block for first 4 years - - 500 STX/block for following 4 years - - 250 STX/block for subsequent 4 years - - 125 STX/block in perpetuity after that -- Coinbase rewards accumulate for "missed sortitions": If a Bitcoin block has no sortition (at height N), then any Stacks block mined in a subsequent sortition that builds off of any Stacks chain tip that existed at the penultimate sortition (at height N-1) may claim its coinbase. This encourages miners to keep mining even if Bitcoin fees are high. -- Initial mining bonus: This is a special case of the above to incentivize early miners. Coinbase for all burnchain blocks between the first burn block height (to be chosen by independent miners as part of the Stacks 2.0 launch) and the first sortition winner accumulate and are distributed to miners over a fixed window (to be determined). For instance, say burn block height is 10,000 and first sortition is at block 10500 and distribution window is 100 blocks, then coinbase for the first 500 blocks (10,500 - 10,000) will be distributed evenly to miners who win sortition over the subsequent 100 blocks. -- 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 at least 11,000 satoshis (5,500 sats / [UTXO output](https://learnmeabitcoin.com/technical/utxo)); 2 outputs / block) to avoid "dust." -- For more details, see [Mining](mining). - -## Stacking - -- Stacking works in 2 phases - 1. Prepare phase: In this phase an "anchor block" is chosen. The qualifying set of addresses ("reward set") is determined based on the snapshot of the chain at the anchor block. Length of prepare phase is 100 blocks. Stacking commitments need to be confirmed before this phase starts - 2. Reward phase: In this phase miner BTC commitments are distributed amongst the reward set. Reward cycle length is 2000 BTC blocks (~2 weeks). -- 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/stacksgov/sips/blob/main/sips/sip-007/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.stacks.co/references/stacking-contract#delegate-stx). -- Only two types of BTC reward addresses are supported: [Legacy (P2PKH)](https://en.bitcoin.it/wiki/Transaction#Pay-to-PubkeyHash) or [Segregated Witness / Segwit (P2SH)](https://en.bitcoin.it/wiki/Pay_to_script_hash). Native Segwit is not supported. -- Further reading: [Stacking](stacking) - -## Accounts and Addresses - -- Transactions in the Stacks blockchain originate from, are paid for by, and execute under the authority of accounts -- An account is fully specified by its address + nonce + assets -- 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 (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](accounts) - -## Transactions - -- Transaction 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 - 2. _paying account_ is the account that is billed by the leader for the cost of validating and executing the transaction - 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 -- Transactions can be batched or streamed into blocks. The behavior can be controlled by the anchor mode of a transaction. With streaming ([microblocks](microblocks)), a faster confirmation time is possible. -- 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. -- Mempool limit for concurrent pending transactions is 25 per account -- Pending mempool transactions will be garbage-collected [256 blocks after receipt](https://github.com/stacks-network/stacks-blockchain/blob/master/src/core/mempool.rs#L62). With 10 minutes target block time, this would equal ~42 hours -- [Learn more about transaction encoding in SIP-005](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md#transaction-encoding) -- [Transaction signing and verification are described in SIP-005](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md#transaction-signing-and-verifying) -- All transactions impacting account balance are atomic, a transfer operation can not increment one account’s balance without decrementing another’s. However, transactions that perform multiple account actions (for example, transferring from multiple accounts) may partially complete. -- Transactions can include a memo string (max 34 bytes) - -## See also - -- [Read the full Stacks 2.0: Apps and Smart Contracts for Bitcoin whitepaper](https://cloudflare-ipfs.com/ipfs/QmaGgiVHymeDjAc3aF1AwyhiFFwN97pme5m536cHT4FsAW). - -- [Watch Aaron Blankstein video on Stacks whitepater v2](https://www.youtube.com/watch?v=Wd-Bfe8Sn-Y). \ No newline at end of file diff --git a/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md b/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md deleted file mode 100644 index 59934a5bde..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Testnet -description: Test your smart contracts and apps -sidebar_position: 2 ---- - -## About testnet - -The testnet is a separate blockchain from the Stacks mainnet analogous to a staging environment. It's a network used by developers to test their apps, smart contracts, or changes to the protocol in a production-like environment. It produces blocks at roughly the same rate as mainnet; about 1 block every 10 minutes on average. The Stacks testnet is rarely reset. - -### Faucet - -The testnet faucet provides you with free Stacks Token (STX) to test with. These are not the same as STX on mainnet and have no value. You can get STX from the faucet on the [Stacks Explorer Sandbox](https://explorer.stacks.co/sandbox/faucet?chain=testnet), or using the [API](https://docs.hiro.so/api#tag/Faucets). - -To get STX tokens from within the Explorer Sandbox, navigate to the "Faucet" tab on the left and click "Request STX" button. - -![](/img/stx_faucet.png) - -You can also try out [Stacking](stacking) by clicking on `I want to stack`. - -:::note -The Explorer Sandbox requires you to login with a Stacks wallet -::: - -### Testnet API - -The hosted Stacks Blockchain API for the testnet is available at this base URL: - -```shell -https://stacks-node-api.testnet.stacks.co/ -``` - -![](/img/api_testnet_status.png) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md b/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md deleted file mode 100644 index 2ff6072384..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Transactions -description: Guide to Stacks 2.0 transactions -sidebar_position: 6 ---- - -## Introduction - -Transactions are the fundamental unit of execution in the Stacks blockchain. Each transaction is originated from a [Stacks 2.0 account](accounts), and is retained in the Stacks blockchain history for eternity. This guide helps you understand Stacks 2.0 transactions. - -## Lifecycle - -Transactions go through phases before being finally confirmed, and available for all, on the Stacks 2.0 network. - -![Transaction lifecycle](/img/tx-lifecycle.png) - -- **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/en/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. - -:::note A transaction can have one of three states once it is registered: `pending`, `success`, or `failed`. ::: - -## Types - -The Stacks 2.0 supports a set of different transaction types: - -| **Type** | **Value** | **Description** | -| ----------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Coinbase | `coinbase` | The first transaction in a new block (an entity holding several transactions). Used to register for block rewards. These are not manually generated and broadcasted like other types of transactions. | -| Token transfer | `token_transfer` | Asset transfer from a sender to a recipient | -| Contract deploy | `smart_contract` | Contract instantiation | -| Contract call | `contract_call` | Contract call for a public, non read-only function | -| Poison Microblock | `poison_microblock` | Punish leaders who intentionally equivocate about the microblocks they package | - -A sample of each transaction type can be found in the [Stacks Blockchain API response definition for transactions](https://docs.hiro.so/api#operation/get_transaction_by_id). - -:::caution Read-only contract call calls do **not** require transactions. Read more about it in the [network guide](network#read-only-function-calls). ::: diff --git a/i18n/de/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md b/i18n/de/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md deleted file mode 100644 index fd45c80583..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Clarity Language -description: Overview of the Clarity language constructs -sidebar_label: Clarity Language -tags: - - clarity ---- - -## Clarity Type System - -The Clarity language uses a strong static type system. Function arguments and database schemas require specified types, and use of types is checked during contract launch. The type system does _not_ have a universal super type. - -## Public Functions - -Functions specified via `define-public` statements are _public_ functions and these are the only types of functions which may be called directly through signed blockchain transactions. In addition to being callable directly from a transaction (see the Stacks wire formats for more details on Stacks transactions), public functions may be called by other smart contracts. - -Public functions _must_ return a `(response ...)` type. This is used by Clarity to determine whether or not to materialize any changes from the execution of the function. If a function returns an `(err ...)` type, any mutations on the blockchain state from executing the function (and any function that it called during execution) will be aborted. - -In addition to functions defined via `define-public`, contracts may expose read-only functions. These functions, defined via `define-read-only`, are callable by other smart contracts, and may be queryable via public blockchain explorers. These functions _may not_ mutate any blockchain state. Unlike normal public functions, read-only functions may return any type. - -## Contract Calls - -A smart contract may call functions from other smart contracts using a `(contract-call?)` function. - -This function returns a response type result -- the return value of the called smart contract function. - -We distinguish 2 different types of `contract-call?`: - -### Static dispatch - -The callee is a known, invariant contract available on-chain when the caller contract is deployed. In this case, the callee's principal is provided as the first argument, followed by the name of the method and its arguments: - -```clarity -(contract-call? - .registrar - register-name - name-to-register) -``` - -### Dynamic dispatch - -The callee is passed as an argument, and typed as a trait reference (``). - -```clarity -(define-public (swap (token-a ) - (amount-a uint) - (owner-a principal) - (token-b ) - (amount-b uint) - (owner-b principal))) - (begin - (unwrap! (contract-call? token-a transfer-from? owner-a owner-b amount-a)) - (unwrap! (contract-call? token-b transfer-from? owner-b owner-a amount-b)))) -``` - -Traits can either be locally defined: - -```clarity -(define-trait can-transfer-tokens ( - (transfer-from? (principal principal uint) (response uint))) -``` - -Or imported from an existing contract: - -```clarity -(use-trait can-transfer-tokens - .contract-defining-trait.can-transfer-tokens) -``` - -Looking at trait conformance, callee contracts have two different paths. They can either be "compatible" with a trait by defining methods matching some of the methods defined in a trait, or explicitly declare conformance using the `impl-trait` statement: - -```clarity -(impl-trait .contract-defining-trait.can-transfer-tokens) -``` - -Explicit conformance should be prefered when adequate. It acts as a safeguard by helping the static analysis system to detect deviations in method signatures before contract deployment. - -The following limitations are imposed on contract calls: - -1. On static dispatches, callee smart contracts _must_ exist at the time of creation. -2. No cycles may exist in the call graph of a smart contract. This prevents recursion (and re-entrancy bugs). Such structures can be detected with static analysis of the call graph, and will be rejected by the network. -3. `contract-call?` are for inter-contract calls only. Attempts to execute when the caller is also the callee will abort the transaction. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md b/i18n/de/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md deleted file mode 100644 index 45be763e21..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md +++ /dev/null @@ -1,1388 +0,0 @@ ---- -title: Functions -description: See a detailed list of all functions for the Clarity language. -tags: - - clarity ---- - -## Functions - -Detailed list of all functions for the Clarity language. - -### + (add) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(+ i1 i2...)` -#### description: -Adds a variable number of integer inputs and returns the result. In the event of an _overflow_, throws a runtime error. -#### example: -```clarity -(+ 1 2 3) ;; Returns 6 -(+ 2 3) ;; Returns 5 -(+ 1 2 3 4) ;; Returns 10 -(+ 9 -3) ;; Returns 6 -(+ -3 -2) ;; Returns -5 -``` - -### - (subtract) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(- i1 i2...)` -#### description: -Subtracts a variable number of integer inputs and returns the result. In the event of an _underflow_, throws a runtime error. -#### example: -```clarity -(- 2 1 1) ;; Returns 0 -(- 0 3) ;; Returns -3 -(- 5 -3) ;; Returns 8 -(- -4 -5) ;; Returns 1 -``` - -### * (multiply) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(* i1 i2...)` -#### description: -Multiplies a variable number of integer inputs and returns the result. In the event of an _overflow_, throws a runtime error. -#### example: -```clarity -(* 2 3) ;; Returns 6 -(* 5 2) ;; Returns 10 -(* 2 2 2) ;; Returns 8 -(* 3 -2) ;; Returns -6 -(* -1 -2) ;; Returns 2 -``` - -### / (divide) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(/ i1 i2...)` -#### description: -Divides a variable number of integer inputs and returns the _integer part_ of the result. In the event of _division by zero_, throws a runtime error. - -#### example: -```clarity -(/ 2 3) ;; Returns 0 -(/ 5 2) ;; Returns 2 -(/ 4 2 2) ;; Returns 1 -(/ -10 2) ;; Returns -5 -(/ -8 -2) ;; Returns 4 -(/ -9 4) ;; Returns -2 -``` - -### >= (greater than or equal) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(>= i1 i2)` -#### description: -Compares two integers, returning `true` if `i1` is greater than or equal to `i2` and `false` otherwise. -#### example: -```clarity -(>= 1 1) ;; Returns true -(>= 5 2) ;; Returns true -``` - -### <= (less than or equal) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(<= i1 i2)` -#### description: -Compares two integers, returning true if `i1` is less than or equal to `i2` and `false` otherwise. -#### example: -```clarity -(<= 1 1) ;; Returns true -(<= 5 2) ;; Returns false -``` - -### < (less than) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(< i1 i2)` -#### description: -Compares two integers, returning `true` if `i1` is less than `i2` and `false` otherwise. -#### example: -```clarity -(< 1 2) ;; Returns true -(< 5 2) ;; Returns false -``` - -### > (greater than) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(> i1 i2)` -#### description: -Compares two integers, returning `true` if `i1` is greater than `i2` and false otherwise. -#### example: -```clarity -(> 1 2) ;; Returns false -(> 5 2) ;; Returns true -``` - -### to-int -#### input: `uint` -#### output: `int` -#### signature: `(to-int u)` -#### description: -Tries to convert the `uint` argument to an `int`. Will cause a runtime error and abort if the supplied argument is >= `pow(2, 127)`` -#### example: -```clarity -(to-int u238) ;; Returns 238 -``` - -### to-uint -#### input: `int` -#### output: `uint` -#### signature: `(to-uint i)` -#### description: -Tries to convert the `int` argument to a `uint`. Will cause a runtime error and abort if the supplied argument is negative. -#### example: -```clarity -(to-uint 238) ;; Returns u238 -``` - -### mod -#### input: `int, int | uint, uint` -#### output: `int | uint` -#### signature: `(mod i1 i2)` -#### description: -Returns the integer remainder from integer dividing `i1` by `i2`. In the event of a division by zero, throws a runtime error. -#### example: -```clarity -(mod 2 3) ;; Returns 2 -(mod 5 2) ;; Returns 1 -(mod 7 1) ;; Returns 0 -``` - -### pow -#### input: `int, int | uint, uint` -#### output: `int | uint` -#### signature: `(pow i1 i2)` -#### description: -Returns the result of raising `i1` to the power of `i2`. In the event of an _overflow_, throws a runtime error. -#### example: -```clarity -(pow 2 3) ;; Returns 8 -(pow 2 2) ;; Returns 4 -(pow 7 1) ;; Returns 7 -``` - -### sqrti -#### input: `int | uint` -#### output: `int | uint` -#### signature: `(sqrti n)` -#### description: -Returns the largest integer that is less than or equal to the square root of `n`. Fails on a negative numbers. -#### example: -```clarity -(sqrti u11) ;; Returns u3 -(sqrti 1000000) ;; Returns 1000 -(sqrti u1) ;; Returns u1 -(sqrti 0) ;; Returns 0 -``` - -### log2 -#### input: `int | uint` -#### output: `int | uint` -#### signature: `(log2 n)` -#### description: -Returns the _integer part_ of the power to which the number 2 must be raised to obtain the value `n`. Fails on zero or a negative number. -#### example: -```clarity -(log2 u8) ;; Returns u3 -(log2 8) ;; Returns 3 -(log2 u1) ;; Returns u0 -(log2 1000) ;; Returns 9 -``` - -### xor -#### input: `int, int | uint, uint` -#### output: `int | uint` -#### signature: `(xor i1 i2)` -#### description: -Returns the result of bitwise exclusive or'ing `i1` with `i2`. -#### example: -```clarity -(xor 1 2) ;; Returns 3 -(xor 120 280) ;; Returns 352 -``` - -### and -#### input: `bool, ...` -#### output: `bool` -#### signature: `(and b1 b2 ...)` -#### description: -Returns `true` if all boolean inputs are `true`. Importantly, the supplied arguments are evaluated in-order and lazily. Lazy evaluation means that if one of the arguments returns `false`, the function short-circuits, and no subsequent arguments are evaluated. -#### example: -```clarity -(and true false) ;; Returns false -(and (is-eq (+ 1 2) 1) (is-eq 4 4)) ;; Returns false -(and (is-eq (+ 1 2) 3) (is-eq 4 4)) ;; Returns true -``` - -### or -#### input: `bool, ...` -#### output: `bool` -#### signature: `(or b1 b2 ...)` -#### description: -Returns `true` if any boolean inputs are `true`. Importantly, the supplied arguments are evaluated in-order and lazily. Importantly, the supplied arguments are evaluated in-order and lazily. -#### example: -```clarity -(or true false) ;; Returns true -(or (is-eq (+ 1 2) 1) (is-eq 4 4)) ;; Returns true -(or (is-eq (+ 1 2) 1) (is-eq 3 4)) ;; Returns false -(or (is-eq (+ 1 2) 3) (is-eq 4 4)) ;; Returns true -``` - -### not -#### input: `bool` -#### output: `bool` -#### signature: `(not b1)` -#### description: -Returns the inverse of the boolean input. -#### example: -```clarity -(not true) ;; Returns false -(not (is-eq 1 2)) ;; Returns true -``` - -### is-eq -#### input: `A, A, ...` -#### output: `bool` -#### signature: `(is-eq v1 v2...)` -#### description: -Compares the inputted values, returning `true` if they are all equal. Note that _unlike_ the `(and ...)` function, `(is-eq ...)` will _not_ short-circuit. All values supplied to is-eq _must_ be the same type. -#### example: -```clarity -(is-eq 1 1) ;; Returns true -(is-eq true false) ;; Returns false -(is-eq \"abc\" 234 234) ;; Throws type error -``` - -### if -#### input: `bool, A, A` -#### output: `A` -#### signature: `(if bool1 expr1 expr2)` -#### description: -The `if` function admits a boolean argument and two expressions which must return the same type. In the case that the boolean input is `true`, the `if` function evaluates and returns `expr1`. If the boolean input is `false`, the `if` function evaluates and returns `expr2`. -#### example: -```clarity -(if true 1 2) ;; Returns 1 -(if (> 1 2) 1 2) ;; Returns 2 -``` - -### let -#### input: `((name1 AnyType) (name2 AnyType) ...), AnyType, ... A` A -#### output: `A` -#### signature: `(let ((name1 expr1) (name2 expr2) ...) expr-body1 expr-body2 ... expr-body-last)` -#### description: -The `let` function accepts a list of `variable name` and `expression` pairs, evaluating each expression and _binding_ it to the corresponding variable name. `let` bindings are sequential: when a `let` binding is evaluated, it may refer to prior binding. The _context_ created by this set of bindings is used for evaluating its body expressions. The let expression returns the value of the last such body expression. Note: intermediary statements returning a response type must be checked` -#### example: -```clarity -(let ((a 2) (b (+ 5 6 7))) (print a) (print b) (+ a b)) ;; Returns 20 -(let ((a 5) (c (+ a 1)) (d (+ c 1)) (b (+ a c d))) (print a) (print b) (+ a b)) ;; Returns 23 -``` - -### map -#### input: `Function(A, B, ..., N) -> X, sequence_A, sequence_B, ..., sequence_N` -#### output: `(list X)` -#### signature: `(map func sequence_A sequence_B ... sequence_N)` -#### description: -Also, note that, no matter what kind of sequences the inputs are, the output is always a list. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. The `map` function applies the function `func` to each corresponding element of the input sequences, and outputs a _list_ of the same type containing the outputs from those function applications. -#### example: -```clarity -(map not (list true false true false)) ;; Returns (false true false true) -(map + (list 1 2 3) (list 1 2 3) (list 1 2 3)) ;; Returns (3 6 9) -(define-private (a-or-b (char (string-utf8 1))) (if (is-eq char u\"a\") u\"a\" u\"b\")) -(map a-or-b u\"aca\") ;; Returns (u\"a\" u\"b\" u\"a\") -(define-private (zero-or-one (char (buff 1))) (if (is-eq char 0x00) 0x00 0x01)) -(map zero-or-one 0x000102) ;; Returns (0x00 0x01 0x01) -``` - -### fold -#### input: `Function(A, B) -> B, sequence_A, B` -#### output: `B` -#### signature: `(fold func sequence_A initial_B)` -#### description: -The `fold` function condenses `sequence_A` into a value of type `B` by recursively applies the function `func` to each element of the input sequence _and_ the output of a previous application of `func`. - -`fold` uses `initial_B` in the initial application of `func`, along with the first element of `sequence_A`. The resulting value of type `B` is used for the next application of `func`, along with the next element of `sequence_A` and so on. `fold` returns the last value of type `B` returned by these successive applications `func`. - -Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. - -#### example: -```clarity -(fold * (list 2 2 2) 1) ;; Returns 8 -(fold * (list 2 2 2) 0) ;; Returns 0 -;; calculates (- 11 (- 7 (- 3 2))) -(fold - (list 3 7 11) 2) ;; Returns 5 -(define-private (concat-string (a (string-ascii 20)) (b (string-ascii 20))) (unwrap-panic (as-max-len? (concat a b) u20))) -(fold concat-string \"cdef\" \"ab\") ;; Returns \"fedcab\" -(fold concat-string (list \"cd\" \"ef\") \"ab\") ;; Returns \"efcdab\" -(define-private (concat-buff (a (buff 20)) (b (buff 20))) (unwrap-panic (as-max-len? (concat a b) u20))) -(fold concat-buff 0x03040506 0x0102) ;; Returns 0x060504030102 -``` - -### append -#### input: `list A, A` -#### output: `list` -#### signature: `(append (list 1 2 3 4) 5)` -#### description: -The `append` function takes a list and another value with the same entry type, and outputs a list of the same type with max_len += 1. -#### example: -```clarity -(append (list 1 2 3 4) 5) ;; Returns (1 2 3 4 5) -``` - -### concat -#### input: `sequence_A, sequence_A` -#### output: `sequence_A` -#### signature: `(concat sequence1 sequence2)` -#### description: -The `func` argument must be a literal function name. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. - -#### example: -```clarity -(concat (list 1 2) (list 3 4)) ;; Returns (1 2 3 4) -(concat \"hello \" \"world\") ;; Returns \"hello world\" -(concat 0x0102 0x0304) ;; Returns 0x01020304 -``` - -### as-max-len? -#### input: `sequence_A, uint` -#### output: `sequence_A` -#### signature: `(as-max-len? sequence max_length)` -#### description: -The `as-max-len?` function takes a sequence argument and a uint-valued, literal length argument. The function returns an optional type. If the input sequence length is less than or equal to the supplied max_length, this returns `(some sequence)`, otherwise it returns `none`. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. ` -#### example: -```clarity -(as-max-len? (list 2 2 2) u3) ;; Returns (some (2 2 2)) -(as-max-len? (list 1 2 3) u2) ;; Returns none -(as-max-len? \"hello\" u10) ;; Returns (some \"hello\") -(as-max-len? 0x010203 u10) ;; Returns (some 0x010203) -``` - -### len -#### input: `sequence_A` -#### output: `uint` -#### signature: `(len sequence)` -#### description: -The `len` function returns the length of a given sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. ` -#### example: -```clarity -(len \"blockstack\") ;; Returns u10 -(len (list 1 2 3 4 5)) ;; Returns u5 -(len 0x010203) ;; Returns u3 -``` - -### element-at -#### input: `sequence_A, uint` -#### output: `(optional A)` -#### signature: `(element-at sequence index)` -#### description: -The `element-at` function returns the element at `index` in the provided sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. ` -#### example: -```clarity -(element-at \"blockstack\" u5) ;; Returns (some \"s\") -(element-at (list 1 2 3 4 5) u5) ;; Returns none -(element-at (list 1 2 3 4 5) (+ u1 u2)) ;; Returns (some 4) -(element-at \"abcd\" u1) ;; Returns (some \"b\") -(element-at 0xfb01 u1) ;; Returns (some 0x01) -``` - -### index-of -#### input: `sequence_A, A` -#### output: `(optional uint)` -#### signature: `(index-of sequence item)` -#### description: -The `index-of` function returns the first index at which `item` can be found, using `is-eq` checks, in the provided sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. If the target item is not found in the sequence (or if an empty string or buffer is supplied), this function returns `none`. -#### example: -```clarity -(index-of \"blockstack\" \"b\") ;; Returns (some u0) -(index-of \"blockstack\" \"k\") ;; Returns (some u4) -(index-of \"blockstack\" \"\") ;; Returns none -(index-of (list 1 2 3 4 5) 6) ;; Returns none -(index-of 0xfb01 0x01) ;; Returns (some u1) -``` - -### list -#### input: `A, ...` -#### output: `(list A)` -#### signature: `(list expr1 expr2 expr3 ...)` -#### description: -The `list` function constructs a list composed of the inputted values. Each supplied value must be of the same type. -#### example: -```clarity -(list (+ 1 2) 4 5) ;; Returns (3 4 5) -``` - -### var-get -#### input: `VarName` -#### output: `A` -#### signature: `(var-get var-name)` -#### description: -The `var-get` function looks up and returns an entry from a contract's data map. The value is looked up using `var-name`. -#### example: -```clarity -(define-data-var cursor int 6) -(var-get cursor) ;; Returns 6 -``` - -### var-set -#### input: `VarName, AnyType` -#### output: `bool` -#### signature: `(var-set var-name expr1)` -#### description: -The `var-set` function sets the value associated with the input variable to the inputted value. The function always returns `true`. -#### example: -```clarity -(define-data-var cursor int 6) -(var-get cursor) ;; Returns 6 -(var-set cursor (+ (var-get cursor) 1)) ;; Returns true -(var-get cursor) ;; Returns 7 -``` - -### map-get? -#### input: `MapName, tuple` -#### output: `(optional (tuple))` -#### signature: `(map-get? map-name key-tuple)` -#### description: -The `map-get?` function looks up and returns an entry from a contract's data map. The value is looked up using `key-tuple`. If there is no value associated with that key in the data map, the function returns a `none` option. Otherwise, it returns `(some value)`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(map-get? names-map (tuple (name \"blockstack\"))) ;; Returns (some (tuple (id 1337))) -(map-get? names-map { name: \"blockstack\" }) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-set -#### input: `MapName, tuple_A, tuple_B` -#### output: `bool` -#### signature: `(map-set map-name key-tuple value-tuple)` -#### description: -The `map-set` function sets the value associated with the input key to the inputted value. This function performs a _blind_ update; whether or not a value is already associated with the key, the function overwrites that existing association. - -Note: the `value-tuple` requires 1 additional byte for storage in the materialized blockchain state, and therefore the maximum size of a value that may be inserted into a map is MAX_CLARITY_VALUE - 1. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-set names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-insert -#### input: `MapName, tuple_A, tuple_B` -#### output: `bool` -#### signature: `(map-insert map-name key-tuple value-tuple)` -#### description: -The `map-insert` function sets the value associated with the input key to the inputted value if and only if there is not already a value associated with the key in the map. If an insert occurs, the function returns `true`. If a value already existed for this key in the data map, the function returns `false`. - -Note: the `value-tuple` requires 1 additional byte for storage in the materialized blockchain state, and therefore the maximum size of a value that may be inserted into a map is MAX_CLARITY_VALUE - 1. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns false -(map-insert names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-delete -#### input: `MapName, tuple` -#### output: `bool` -#### signature: `(map-delete map-name key-tuple)` -#### description: -The `map-delete` function removes the value associated with the input key for the given map. If an item exists and is removed, the function returns `true`. If a value did not exist for this key in the data map, the function returns `false`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-delete names-map { name: \"blockstack\" }) ;; Returns true -(map-delete names-map { name: \"blockstack\" }) ;; Returns false -(map-delete names-map (tuple (name \"blockstack\"))) ;; Same command, using a shorthand for constructing the tuple -``` - -### tuple -#### input: `(key-name A), (key-name-2 B), ...` -#### output: `(tuple (key-name A) (key-name-2 B) ...)` -#### signature: `(tuple (key0 expr0) (key1 expr1) ...)` -#### description: -The `tuple` special form constructs a typed tuple from the supplied key and expression pairs. A `get` function can use typed tuples as input to select specific values from a given tuple. Key names may not appear multiple times in the same tuple definition. Supplied expressions are evaluated and associated with the expressions' paired key name. - -There is a shorthand using curly brackets of the form {key0: expr0, key1: expr, ...}` -#### example: -```clarity -(tuple (name \"blockstack\") (id 1337)) ;; using tuple -{name: \"blockstack\", id: 1337} ;; using curly brackets -``` - -### get -#### input: `KeyName, (tuple) | (optional (tuple))` -#### output: `A` -#### signature: `(get key-name tuple)` -#### description: -The `get` function fetches the value associated with a given key from the supplied typed tuple. If an `Optional` value is supplied as the inputted tuple, `get` returns an `Optional` type of the specified key in the tuple. If the supplied option is a `(none)` option, get returns `(none)`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(get id (tuple (name \"blockstack\") (id 1337))) ;; Returns 1337 -(get id (map-get? names-map (tuple (name \"blockstack\")))) ;; Returns (some 1337) -(get id (map-get? names-map (tuple (name \"non-existent\")))) ;; Returns none -``` - -### merge -#### input: `tuple, tuple` -#### output: `tuple` -#### signature: `(merge tuple { key1: val1 })` -#### description: -The `merge` function returns a new tuple with the combined fields, without mutating the supplied tuples. -#### example: -```clarity -(define-map users { id: int } { name: (string-ascii 12), address: (optional principal) }) -(map-insert users { id: 1337 } { name: \"john\", address: none }) ;; Returns true -(let ((user (unwrap-panic (map-get? users { id: 1337 })))) -(merge user { address: (some 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) })) ;; Returns (tuple (address (some SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF)) (name \"john\")) -``` - -### begin -#### input: `AnyType, ... A` A -#### output: `A` -#### signature: `(begin expr1 expr2 expr3 ... expr-last)` -#### description: -The `begin` function evaluates each of its input expressions, returning the return value of the last such expression. Note: intermediary statements returning a response type must be checked. -#### example: -```clarity -(begin (+ 1 2) 4 5) ;; Returns 5 -``` - -### hash160 -#### input: `buff|uint|int` -#### output: `(buff 20)` -#### signature: `(hash160 value)` -#### description: -The `hash160` function computes `RIPEMD160(SHA256(x))` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(hash160 0) ;; Returns 0xe4352f72356db555721651aa612e00379167b30f -``` - -### sha256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(sha256 value)` -#### description: -The `sha256` function computes `SHA256(x)` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(sha256 0) ;; Returns 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb -``` - -### sha512 -#### input: `buff|uint|int` -#### output: `(buff 64)` -#### signature: `(sha512 value)` -#### description: -The `sha512` function computes `SHA512(x)` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(sha512 1) ;; Returns 0x6fcee9a7b7a7b821d241c03c82377928bc6882e7a08c78a4221199bfa220cdc55212273018ee613317c8293bb8d1ce08d1e017508e94e06ab85a734c99c7cc34 -``` - -### sha512/256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(sha512/256 value)` -#### description: -The `sha512/256` function computes `SHA512/256(x)` (the SHA512 algorithm with the 512/256 initialization vector, truncated to 256 bits) of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(sha512/256 1) ;; Returns 0x515a7e92e7c60522db968d81ff70b80818fc17aeabbec36baf0dda2812e94a86 -``` - -### keccak256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(keccak256 value)` -#### description: -The `keccak256` function computes `KECCAK256(value)` of the inputted value. Note that this differs from the `NIST SHA-3` (that is, FIPS 202) standard. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(keccak256 0) ;; Returns 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4 -``` - -### secp256k1-recover? -#### input: `(buff 32), (buff 65)` -#### output: `(response (buff 33) uint)` -#### signature: `(secp256k1-recover? message-hash signature)` -#### description: -The `secp256k1-recover?` function recovers the public key used to sign the message which sha256 is `message-hash` with the provided `signature`. If the signature does not match, it will return the error code `(err u1).`. If the signature is invalid, it will return the error code `(err u2).`. The signature includes 64 bytes plus an additional recovery id (00..03) for a total of 65 bytes. -#### example: -```clarity -(secp256k1-recover? 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a1301) - ;; Returns (ok 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) - ``` - -### secp256k1-verify -#### input: `(buff 32), (buff 64) | (buff 65), (buff 33)` -#### output: `bool` -#### signature: `(secp256k1-verify message-hash signature public-key)` -#### description: -The `secp256k1-verify` function verifies that the provided signature of the message-hash was signed with the private key that generated the public key. The `message-hash` is the `sha256` of the message. The signature includes 64 bytes plus an optional additional recovery id (00..03) for a total of 64 or 65 bytes. -#### example: -```clarity -(secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a1301 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns true -(secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a13 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns true -(secp256k1-verify 0x0000000000000000000000000000000000000000000000000000000000000000 - 0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns false - ``` - -### print -#### input: `A` -#### output: `A` -#### signature: `(print expr)` -#### description: -The `print` function evaluates and returns its input expression. On Stacks Core nodes configured for development (as opposed to production mining nodes), this function prints the resulting value to `STDOUT` (standard output). -#### example: -```clarity -(print (+ 1 2 3)) ;; Returns 6 -``` - -### contract-call? -#### input: `ContractName, PublicFunctionName, Arg0, ...` -#### output: `(response A B)` -#### signature: `(contract-call? .contract-name function-name arg0 arg1 ...)` -#### description: -The `contract-call?` function executes the given public function of the given contract. You _may not_ use this function to call a public function defined in the current contract. If the public function returns _err_, any database changes resulting from calling `contract-call?` are aborted. If the function returns _ok_, database changes occurred. -#### example: -```clarity - -;; instantiate the sample-contracts/tokens.clar contract first! -(as-contract (contract-call? .tokens mint! u19)) ;; Returns (ok u19) -``` - -### as-contract -#### input: `A` -#### output: `A` -#### signature: `(as-contract expr)` -#### description: -The `as-contract` function switches the current context's `tx-sender` value to the _contract's_ principal and executes `expr` with that context. It returns the resulting value of `expr`. -#### example: -```clarity -(as-contract tx-sender) ;; Returns S1G2081040G2081040G2081040G208105NK8PE5.docs-test -``` - -### contract-of -#### input: `Trait` -#### output: `principal` -#### signature: `(contract-of .contract-name)` -#### description: -The `contract-of` function returns the principal of the contract implementing the trait. -#### example: -```clarity -(use-trait token-a-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) -(define-public (forward-get-balance (user principal) (contract )) - (begin - (ok (contract-of contract)))) ;; returns the principal of the contract implementing -``` - -### principal-of? -#### input: `(buff 33)` -#### output: `(response principal uint)` -#### signature: `(principal-of? public-key)` -#### description: -The `principal-of?` function returns the principal derived from the provided public key. If the `public-key` is invalid, it will return the error code `(err u1).`. ` -#### example: -```clarity -(principal-of? 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns (ok ST1AW6EKPGT61SQ9FNVDS17RKNWT8ZP582VF9HSCP) -``` - -### at-block -#### input: `(buff 32), A` -#### output: `A` -#### signature: `(at-block id-block-hash expr)` -#### description: -The `at-block` function evaluates the expression `expr` _as if_ it were evaluated at the end of the block indicated by the _block-hash_ argument. The `expr` closure must be read-only. - -This hash uniquely identifies Stacks blocks and is unique across Stacks forks. Note: The block identifying hash must be a hash returned by the `id-header-hash` block information property. While the hash returned by `header-hash` is unique within the context of a single fork, it is not unique across Stacks forks. - -The function returns the result of evaluating `expr`. - -#### example: -```clarity -(define-data-var data int 1) -(at-block 0x0000000000000000000000000000000000000000000000000000000000000000 block-height) ;; Returns u0 -(at-block (get-block-info? id-header-hash 0) (var-get data)) ;; Throws NoSuchDataVariable because `data` wasn't initialized at block height 0 -``` - -### get-block-info? -#### input: `BlockInfoPropertyName, BlockHeightInt` -#### output: `(optional buff) | (optional uint)` -#### signature: `(get-block-info? prop-name block-height-expr)` -#### description: -The `get-block-info?` function fetches data for a block of the given block height. The value and type returned are determined by the specified `BlockInfoPropertyName`. If the provided `BlockHeightInt` does not correspond to an existing block prior to the current block, the function returns `none`. The currently available property names are `time`, `header-hash`, `burnchain-header-hash`, `id-header-hash`, `miner-address`, and `vrf-seed`. - -This is a Unix epoch timestamp in seconds which roughly corresponds to when the block was mined. The `time` property returns an integer value of the block header time field. **Warning**: this does not increase monotonically with each block and block times are accurate only to within two hours. See [BIP113](https://github.com/bitcoin/bips/blob/master/bip-0113.mediawiki) for more information. - -The `header-hash`, `burnchain-header-hash`, `id-header-hash`, and `vrf-seed` properties return a 32-byte buffer. - -The `miner-address` property returns a `principal` corresponding to the miner of the given block. - -The `id-header-hash` is the block identifier value that must be used as input to the `at-block` function. - -#### example: -```clarity -(get-block-info? time u0) ;; Returns (some u1557860301) -(get-block-info? header-hash u0) ;; Returns (some 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb) -(get-block-info? vrf-seed u0) ;; Returns (some 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4) -``` - -### err -#### input: `A` -#### output: `(response A B)` -#### signature: `(err value)` -#### description: -The `err` function constructs a response type from the input value. Use `err` for creating return values in public functions. An _err_ value indicates that any database changes during the processing of the function should be rolled back. -#### example: -```clarity -(err true) ;; Returns (err true) -``` - -### ok -#### input: `A` -#### output: `(response A B)` -#### signature: `(ok value)` -#### description: -The `ok` function constructs a response type from the input value. Use `ok` for creating return values in public functions. An _ok_ value indicates that any database changes during the processing of the function should materialize. -#### example: -```clarity -(ok 1) ;; Returns (ok 1) -``` - -### some -#### input: `A` -#### output: `(optional A)` -#### signature: `(some value)` -#### description: -The `some` function constructs a `optional` type from the input value. -#### example: -```clarity -(some 1) ;; Returns (some 1) -(is-none (some 2)) ;; Returns false -``` - -### default-to -#### input: `A, (optional A)` -#### output: `A` -#### signature: `(default-to default-value option-value)` -#### description: -The `default-to` function attempts to 'unpack' the second argument: if the argument is a `(some ...)` option, it returns the inner value of the option. If the second argument is a `(none)` value, `default-to` it returns the value of `default-value`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(default-to 0 (get id (map-get? names-map (tuple (name \"blockstack\"))))) ;; Returns 1337 -(default-to 0 (get id (map-get? names-map (tuple (name \"non-existant\"))))) ;; Returns 0 -``` - -### asserts! -#### input: `bool, C` -#### output: `bool` -#### signature: `(asserts! bool-expr thrown-value)` -#### description: -The `asserts!` function admits a boolean argument and asserts its evaluation: if bool-expr is `true`, `asserts!` returns `true` and proceeds in the program execution. If the supplied argument is returning a false value, `asserts!` _returns_ `thrown-value` and exits the current control-flow. -#### example: -```clarity -(asserts! (is-eq 1 1) (err 1)) ;; Returns true -``` - -### unwrap! -#### input: `(optional A) | (response A B), C` -#### output: `A` -#### signature: `(unwrap! option-input thrown-value)` -#### description: -The `unwrap!` function attempts to 'unpack' the first argument: if the argument is an option type, and the argument is a `(some ...)` option, `unwrap!` returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, `unwrap!` returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `(none)` value, `unwrap!` _returns_ `thrown-value` from the current function and exits the current control-flow. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(define-private (get-name-or-err (name (string-ascii 12))) - (let ((raw-name (unwrap! (define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(define-private (get-name-or-err (name (string-ascii 12))) - (let ((raw-name (unwrap! names-map { name: name }) (err 1)))) - (ok raw-name))) - -(get-name-or-err \"blockstack\") ;; Returns (ok (tuple (id 1337))) -(get-name-or-err \"non-existant\") ;; Returns (err 1) -``` - -### unwrap-err! -#### input: `(response A B), C` -#### output: `B` -#### signature: `(unwrap-err! response-input thrown-value)` -#### description: -The `unwrap-err!` function attempts to 'unpack' the first argument: if the argument is an `(err ...)` response, `unwrap-err!` returns the inner value of the `err`. If the supplied argument is an `(ok ...)` value, `unwrap-err!` _returns_ `thrown-value` from the current function and exits the current control-flow. -#### example: -```clarity -(unwrap-err! (err 1) false) ;; Returns 1 -``` - -### unwrap-panic -#### input: `(optional A) | (response A B)` -#### output: `A` -#### signature: `(unwrap-panic option-input)` -#### description: -The `unwrap` function attempts to 'unpack' its argument: if the argument is an option type, and the argument is a `(some ...)` option, this function returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, it returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `(none)` value, `unwrap` throws a runtime error, aborting any further processing of the current transaction. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(unwrap-panic (map-get? names-map { name: \"blockstack\" })) ;; Returns (tuple (id 1337)) -(unwrap-panic (map-get? names-map { name: \"non-existant\" })) ;; Throws a runtime exception -``` - -### unwrap-err-panic -#### input: `(response A B)` -#### output: `B` -#### signature: `(unwrap-err-panic response-input)` -#### description: -The `unwrap-err` function attempts to 'unpack' the first argument: if the argument is an `(err ...)` response, `unwrap` returns the inner value of the `err`. If the supplied argument is an `(ok ...)` value, `unwrap-err` throws a runtime error, aborting any further processing of the current transaction. -#### example: -```clarity -(unwrap-err-panic (err 1)) ;; Returns 1 -(unwrap-err-panic (ok 1)) ;; Throws a runtime exception -``` - -### match -#### input: `(optional A) name expression expression | (response A B) name expression name expression` -#### output: `C` -#### signature: `(match opt-input some-binding-name some-branch none-branch) | -(match-resp input ok-binding-name ok-branch err-binding-name err-branch)` -#### description: -The `match` function is used to test and destructure optional and response types. - -If the `input` is an optional, it tests whether the provided `input` is a `some` or `none` option, and evaluates `some-branch` or `none-branch` in each respective case. - -Within the `some-branch`, the _contained value_ of the `input` argument is bound to the provided `some-binding-name` name. - -Only _one_ of the branches will be evaluated (similar to `if` statements). - -If the `input` is a response, it tests whether the provided `input` is an `ok` or `err` response type, and evaluates `ok-branch` or `err-branch` in each respective case. - -Within the `ok-branch`, the _contained ok value_ of the `input` argument is bound to the provided `ok-binding-name` name. - -Within the `err-branch`, the _contained err value_ of the `input` argument is bound to the provided `err-binding-name` name. - -Only _one_ of the branches will be evaluated (similar to `if` statements). - -Note: Type checking requires that the type of both the ok and err parts of the response object be determinable. For situations in which one of the parts of a response is untyped, you should use `unwrap-panic` or `unwrap-err-panic` instead of `match`. -#### example: -```clarity - -(define-private (add-10 (x (optional int))) - (match x - value (+ 10 value) - 10)) -(add-10 (some 5)) ;; Returns 15 -(add-10 none) ;; Returns 10 - -(define-private (add-or-pass-err (x (response int (string-ascii 10))) (to-add int)) - (match x - value (ok (+ to-add value)) - err-value (err err-value))) -(add-or-pass-err (ok 5) 20) ;; Returns (ok 25) -(add-or-pass-err (err \"ERROR\") 20) ;; Returns (err \"ERROR\") -``` - -### try! -#### input: `(optional A) | (response A B)` -#### output: `A` -#### signature: `(try! option-input)` -#### description: -The `try!` function attempts to 'unpack' the first argument: if the argument is an option type, and the argument is a `(some ...)` option, `try!` returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, `try!` returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `none` value, `try!` _returns_ either `none` or the `(err ...)` value from the current function and exits the current control-flow. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(try! (define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(define-private (get-name-or-err (name (string-ascii 12))) - (let ((raw-name (unwrap! names-map { name: \"blockstack\" })) ;; Returns (tuple (id 1337)) -(define-private (checked-even (x int)) - (if (is-eq (mod x 2) 0) - (ok x) - (err false))) -(define-private (double-if-even (x int)) - (ok (* 2 (try! (checked-even x))))) -(double-if-even 10) ;; Returns (ok 20) -(double-if-even 3) ;; Returns (err false) -``` - -### is-ok -#### input: `(response A B)` -#### output: `bool` -#### signature: `(is-ok value)` -#### description: -`is-ok` tests a supplied response value, returning `true` if the response was `ok`, and `false` if it was an `err`. -#### example: -```clarity -(is-ok (ok 1)) ;; Returns true -(is-ok (err 1)) ;; Returns false -``` - -### is-none -#### input: `(optional A)` -#### output: `bool` -#### signature: `(is-none value)` -#### description: -`is-none` tests a supplied option value, returning `true` if the option value is `(none)`, and `false` if it is a `(some ...)`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(is-none (get id (map-get? names-map { name: \"blockstack\" }))) ;; Returns false -(is-none (get id (map-get? names-map { name: \"non-existant\" }))) ;; Returns true -``` - -### is-err -#### input: `(response A B)` -#### output: `bool` -#### signature: `(is-err value)` -#### description: -`is-err` tests a supplied response value, returning `true` if the response was an `err`, and `false` if it was an `ok`. -#### example: -```clarity -(is-err (ok 1)) ;; Returns false -(is-err (err 1)) ;; Returns true -``` - -### is-some -#### input: `(optional A)` -#### output: `bool` -#### signature: `(is-some value)` -#### description: -`is-some` tests a supplied option value, returning `true` if the option value is `(some ...)`, and `false` if it is a `none`. -#### example: -```clarity - -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(is-some (get id (map-get? names-map { name: \"blockstack\" }))) ;; Returns true -(is-some (get id (map-get? names-map { name: \"non-existant\" }))) ;; Returns false -``` - -### filter -#### input: `Function(A) -> bool, sequence_A` -#### output: `sequence_A` -#### signature: `(filter func sequence)` -#### description: -The `filter` function applies the input function `func` to each element of the input sequence, and returns the same sequence with any elements removed for which `func` returned `false`. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. ` -#### example: -```clarity - -(filter not (list true false true false)) ;; Returns (false false) -(define-private (is-a (char (string-utf8 1))) (is-eq char u\"a\")) -(filter is-a u\"acabd\") ;; Returns u\"aa\" -(define-private (is-zero (char (buff 1))) (is-eq char 0x00)) -(filter is-zero 0x00010002) ;; Returns 0x0000 -``` - -### ft-get-balance -#### input: `TokenName, principal` -#### output: `uint` -#### signature: `(ft-get-balance token-name principal)` -#### description: -`ft-get-balance` returns `token-name` balance of the principal `principal`. The token type must have been defined using `define-fungible-token`. -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-get-balance stackaroo 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns u100 -``` - -### nft-get-owner? -#### input: `AssetName, A` -#### output: `(optional principal)` -#### signature: `(nft-get-owner? asset-class asset-identifier)` -#### description: -`nft-get-owner?` returns the owner of an asset, identified by `asset-identifier`, or `none` if the asset does not exist. The asset type must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) -(nft-get-owner? stackaroo \"Roo\") ;; Returns (some SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) -(nft-get-owner? stackaroo \"Too\") ;; Returns none -``` - -### ft-transfer? -#### input: `TokenName, uint, principal, principal` -#### output: `(response bool uint)` -#### signature: `(ft-transfer? token-name amount sender recipient)` -#### description: -`ft-transfer?` is used to increase the token balance for the `recipient` principal for a token type defined using `define-fungible-token` by debiting the `sender` principal. In contrast to `stx-transfer?`, any user can transfer the assets. When used, relevant guards need to be added. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- amount to send is non-positive ` -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-transfer? stackaroo u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(ft-transfer? stackaroo u60 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u1) -``` - -### nft-transfer? -#### input: `AssetName, A, principal, principal` -#### output: `(response bool uint)` -#### signature: `(nft-transfer? asset-class asset-identifier sender recipient)` -#### description: -`nft-transfer?` is used to change the owner of an asset identified by `asset-identifier` from `sender` to `recipient`. The `asset-class` must have been defined by `define-non-fungible-token` and `asset-identifier` must be of the type specified in that definition. In contrast to `stx-transfer?`, any user can transfer the asset. When used, relevant guards need to be added. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not own the asset `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- asset identified by asset-identifier does not exist ` -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(nft-transfer? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(nft-transfer? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u1) -(nft-transfer? stackaroo \"Stacka\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u3) -``` - -### nft-mint? -#### input: `AssetName, A, principal` -#### output: `(response bool uint)` -#### signature: `(nft-mint? asset-class asset-identifier recipient)` -#### description: -`nft-mint?` is used to instantiate an asset and set that asset's owner to the `recipient` principal. The asset must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. - -If an asset identified by `asset-identifier` _already exists_, this function will return an error with the following error code: - -`(err u1)` - -Otherwise, on successfuly mint, it returns `(ok true)`. ` -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### ft-mint? -#### input: `TokenName, uint, principal` -#### output: `(response bool uint)` -#### signature: `(ft-mint? token-name amount recipient)` -#### description: -`ft-mint?` is used to increase the token balance for the `recipient` principal for a token type defined using `define-fungible-token`. The increased token balance is _not_ transfered from another principal, but rather minted. - -If a non-positive amount is provided to mint, this function returns `(err 1)`. Otherwise, on successfuly mint, it returns `(ok true)`. ` -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### ft-get-supply -#### input: `TokenName` -#### output: `uint` -#### signature: `(ft-get-supply token-name)` -#### description: -`ft-get-balance` returns `token-name` circulating supply. The token type must have been defined using `define-fungible-token`. -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-get-supply stackaroo) ;; Returns u100 -``` - -### ft-burn? -#### input: `TokenName, uint, principal` -#### output: `(response bool uint)` -#### signature: `(ft-burn? token-name amount sender)` -#### description: -`ft-burn?` is used to decrease the token balance for the `sender` principal for a token type defined using `define-fungible-token`. The decreased token balance is _not_ transfered to another principal, but rather destroyed, reducing the circulating supply. - -If a non-positive amount is provided to burn, this function returns `(err 1)`. Otherwise, on successfuly burn, it returns `(ok true)`. - -#### example: -```clarity - -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(ft-burn? stackaroo u50 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### nft-burn? -#### input: `AssetName, A, principal` -#### output: `(response bool uint)` -#### signature: `(nft-burn? asset-class asset-identifier recipient)` -#### description: -`nft-burn?` is used to burn an asset and remove that asset's owner from the `recipient` principal. The asset must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. - -If an asset identified by `asset-identifier` _doesn't exist_, this function will return an error with the following error code: - -`(err u1)` - -Otherwise, on successfuly burn, it returns `(ok true)`. ` -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(nft-burn? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### stx-get-balance -#### input: `principal` -#### output: `uint` -#### signature: `(stx-get-balance owner)` -#### description: -`stx-get-balance` is used to query the STX balance of the `owner` principal. - -This function returns the STX balance of the `owner` principal. In the event that the `owner` principal isn't materialized, it returns 0. - -#### example: -```clarity -(stx-get-balance 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns u0 -(stx-get-balance (as-contract tx-sender)) ;; Returns u1000 -``` - -### stx-transfer? -#### input: `uint, principal, principal` -#### output: `(response bool uint)` -#### signature: `(stx-transfer? amount sender recipient)` -#### description: -`stx-transfer?` is used to increase the STX balance for the `recipient` principal by debiting the `sender` principal. The `sender` principal _must_ be equal to the current context's `tx-sender`. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- amount to send is non-positive `(err u4)` -- the `sender` principal is not the current `tx-sender` - -#### example: -```clarity - -(as-contract - (stx-transfer? u60 tx-sender 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (ok true) -(as-contract - (stx-transfer? u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR tx-sender)) ;; Returns (err u4) -``` - -### stx-burn? -#### input: `uint, principal` -#### output: `(response bool uint)` -#### signature: `(stx-burn? amount sender)` -#### description: -`stx-burn?` debits the `sender` principal's STX holdings by `amount`, destroying the STX. The `sender` principal _must_ be equal to the current context's `tx-sender`. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u3)` -- amount to send is non-positive `(err u4)` -- the `sender` principal is not the current `tx-sender` - -#### example: -```clarity -(as-contract - (stx-burn? u60 tx-sender)) ;; Returns (ok true) -(as-contract - (stx-burn? u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (err u4) -``` - -### define-constant -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-constant name expression)` -#### description: -`define-constant` is used to define a private constant value in a smart contract. The expression passed into the definition is evaluated at contract launch, in the order that it is supplied in the contract. This can lead to undefined function or undefined variable errors in the event that a function or variable used in the expression has not been defined before the constant. - -Like other kinds of definition statements, `define-constant` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -#### example: -```clarity - -(define-constant four (+ 2 2)) -(+ 4 four) ;; Returns 8 -``` - -### define-private -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-private (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### description: -`define-private` is used to define _private_ functions for a smart contract. Private functions may not be called from other smart contracts, nor may they be invoked directly by users. Instead, these functions may only be invoked by other functions defined in the same smart contract. - -Like other kinds of definition statements, `define-private` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Private functions may return any type. -#### example: -```clarity -(define-private (max-of (i1 int) (i2 int)) - (if (> i1 i2) - i1 - i2)) -(max-of 4 6) ;; Returns 6 -``` - -### define-public -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-public (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### description: -`define-public` is used to define a _public_ function and transaction for a smart contract. Public functions are callable from other smart contracts and may be invoked directly by users by submitting a transaction to the Stacks blockchain. - -Like other kinds of definition statements, `define-public` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Public functions _must_ return a ResponseType (using either `ok` or `err`). Any datamap modifications performed by a public function is aborted if the function returns an `err` type. Public functions may be invoked by other contracts via `contract-call?`. -#### example: -```clarity -(define-public (hello-world (input int)) - (begin (print (+ 2 input)) - (ok input))) -``` - -### define-read-only -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-read-only (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### description: -`define-read-only` is used to define a _public read-only_ function for a smart contract. Such functions are callable from other smart contracts. - -Like other kinds of definition statements, `define-read-only` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Read-only functions may return any type. However, read-only functions may not perform any datamap modifications, or call any functions which perform such modifications. This is enforced both during type checks and during the execution of the function. Public read-only functions may be invoked by other contracts via `contract-call?`. -#### example: -```clarity -(define-read-only (just-return-one-hundred) - (* 10 10)) - ``` - -### define-map -#### input: `MapName, TypeDefinition, TypeDefinition` -#### output: `Not Applicable` -#### signature: `(define-map map-name key-type value-type)` -#### description: -`define-map` is used to define a new datamap for use in a smart contract. Such maps are only modifiable by the current smart contract. - -Maps are defined with a key type and value type, often these types are tuple types. - -Like other kinds of definition statements, `define-map` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). -#### example: -```clarity -(define-map squares { x: int } { square: int }) -(define-private (add-entry (x int)) - (map-insert squares { x: 2 } { square: (* x x) })) -(add-entry 1) -(add-entry 2) -(add-entry 3) -(add-entry 4) -(add-entry 5) -``` - -### define-data-var -#### input: `VarName, TypeDefinition, Value` -#### output: `Not Applicable` -#### signature: `(define-data-var var-name type value)` -#### description: -`define-data-var` is used to define a new persisted variable for use in a smart contract. Such variable are only modifiable by the current smart contract. - -Persisted variable are defined with a type and a value. - -Like other kinds of definition statements, `define-data-var` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). -#### example: -```clarity -(define-data-var size int 0) -(define-private (set-size (value int)) - (var-set size value)) -(set-size 1) -(set-size 2) -``` - -### define-fungible-token -#### input: `TokenName, ` -#### output: `Not Applicable` -#### signature: `(define-fungible-token token-name )` -#### description: -`define-fungible-token` is used to define a new fungible token class for use in the current contract. - -The second argument, if supplied, defines the total supply of the fungible token. This ensures that all calls to the `ft-mint?` function will never be able to create more than `total-supply` tokens. If any such call were to increase the total supply of tokens passed that amount, that invocation of `ft-mint?` will result in a runtime error and abort. - -Like other kinds of definition statements, `define-fungible-token` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Tokens defined using `define-fungible-token` may be used in `ft-transfer?`, `ft-mint?`, and `ft-get-balance` functions` -#### example: -```clarity -(define-fungible-token stacks) -(define-fungible-token limited-supply-stacks u100) -``` - -### define-non-fungible-token -#### input: `AssetName, TypeSignature` -#### output: `Not Applicable` -#### signature: `(define-non-fungible-token asset-name asset-identifier-type)` -#### description: -`define-non-fungible-token` is used to define a new non-fungible token class for use in the current contract. Individual assets are identified by their asset identifier, which must be of the type `asset-identifier-type`. Asset identifiers are _unique_ identifiers. - -Like other kinds of definition statements, `define-non-fungible-token` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Assets defined using `define-non-fungible-token` may be used in `nft-transfer?`, `nft-mint?`, and `nft-get-owner?` functions` -#### example: -```clarity -(define-non-fungible-token names (buff 50)) -``` - -### define-trait -#### input: `VarName, [MethodSignature]` -#### output: `Not Applicable` -#### signature: `(define-trait trait-name ((func1-name (arg1-type arg2-type ...) (return-type))))` -#### description: -`define-trait` is used to define a new trait definition for use in a smart contract. Other contracts can implement a given trait and then have their contract identifier being passed as function arguments in order to be called dynamically with `contract-call?`. - -Traits are defined with a name, and a list functions defined with a name, a list of argument types, and return type. - -Like other kinds of definition statements, `define-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -#### example: -```clarity -(define-trait token-trait - ((transfer? (principal principal uint) (response uint uint)) - (get-balance (principal) (response uint uint)))) -``` - -### use-trait -#### input: `VarName, TraitIdentifier` -#### output: `Not Applicable` -#### signature: `(use-trait trait-alias trait-identifier)` -#### description: -`use-trait` is used to bring a trait, defined in another contract, to the current contract. Subsequent references to an imported trait are signaled with the syntax ``. - -Traits import are defined with a name, used as an alias, and a trait identifier. Trait identifiers can either be using the sugared syntax (.token-a.token-trait), or be fully qualified ('SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait). - -Like other kinds of definition statements, `use-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put such a statement in the middle of a function body). -#### example: -```clarity -(use-trait token-a-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) -(define-public (forward-get-balance (user principal) (contract )) - (begin - (ok 1))) -``` - -### impl-trait -#### input: `TraitIdentifier` -#### output: `Not Applicable` -#### signature: `(impl-trait trait-identifier)` -#### description: -`impl-trait` can be use for asserting that a contract is fully implementing a given trait. Additional checks are being performed when the contract is being published, rejecting the deployment if the contract is violating the trait specification. - -Trait identifiers can either be using the sugared syntax (.token-a.token-trait), or be fully qualified ('SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait). - -Like other kinds of definition statements, `impl-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put such a statement in the middle of a function body). - -#### example: -```clarity -(impl-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) (define-public (get-balance (account principal)) (ok u0)) (define-public (transfer? (from principal) (to principal) (amount uint)) - (ok u0)) -``` \ No newline at end of file diff --git a/i18n/de/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md b/i18n/de/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md deleted file mode 100644 index fd62451198..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Keywords -description: See a detailed list of all keywords for the Clarity language. -tags: - - clarity ---- - -![](/img/keywords.jpg) -## Keyword reference - -Detailed list of all keywords for the Clarity language. - - -### contract-caller -#### output: `principal` -#### description: -Returns the caller of the current contract context. If this contract is the first one called by a signed transaction, the caller will be equal to the signing principal. If `contract-call?` was used to invoke a function from a new contract, `contract-caller` changes to the _calling_ contract's principal. If `as-contract` is used to change the `tx-sender` context, `contract-caller` _also_ changes to the same contract principal. -#### example: -```clarity -(print contract-caller) ;; Will print out a Stacks address of the transaction sender -``` - -### tx-sender -#### output: `principal` -#### description: -Returns the original sender of the current transaction, or if `as-contract` was called to modify the sending context, it returns that contract principal. -#### example: -```clarity -(print tx-sender) ;; Will print out a Stacks address of the transaction sender -``` - -### block-height -#### output: `uint` -#### description: -Returns the current block height of the Stacks blockchain as an uint -#### example: -```clarity -(> block-height 1000) ;; returns true if the current block-height has passed 1000 blocks. -``` - -### burn-block-height -#### output: `uint` -#### description: -Returns the current block height of the underlying burn blockchain as a uint -#### example: -```clarity -(> burn-block-height 1000) ;; returns true if the current height of the underlying burn blockchain has passed 1000 blocks. -``` - -### none -#### output: `(optional ?)` -#### description: -Represents the _none_ option indicating no value for a given optional (analogous to a null value). -#### example: -```clarity -(define-public (only-if-positive (a int)) - (if (> a 0) - (some a) - none)) -(only-if-positive 4) ;; Returns (some 4) -(only-if-positive (- 3)) ;; Returns none -``` - -### true -#### output: `bool` -#### description: -Boolean true constant. -#### example: -```clarity -(and true false) ;; Evaluates to false -(or false true) ;; Evaluates to true -``` - -### false -#### output: `bool` -#### description: -Boolean false constant. -#### example: -```clarity -(and true false) ;; Evaluates to false -(or false true) ;; Evaluates to true -``` - -### stx-liquid-supply -#### output: `uint` -#### description: -Returns the total number of micro-STX (uSTX) that are liquid in the system as of this block. -#### example: -```clarity -(print stx-liquid-supply) ;; Will print out the total number of liquid uSTX -``` - -### is-in-regtest -#### output: `bool` -#### description: -Returns whether or not the code is running in a regression test -#### example: -```clarity -(print is-in-regtest) ;; Will print 'true' if the code is running in a regression test -``` - diff --git a/i18n/de/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md b/i18n/de/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md deleted file mode 100644 index d22f991413..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Types -description: See a detailed list of all types for the Clarity language. -tags: - - clarity ---- - -## Clarity Type System - -The type system contains the following types: - -| Types | Notes | -| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `int` | signed 128-bit integer | -| `uint` | unsigned 128-bit integer | -| `bool` | boolean value (`true` or `false`) | -| `principal` | object representing a principal (whether a contract principal or standard principal) | -| `(buff max-len)` | byte buffer of 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` (u"A smiley face emoji \u{1F600} as a utf8 string") | -| `(list max-len entry-type)` | list of maximum length `max-len`, with entries of type `entry-type` | -| `{label-0: value-type-0, label-1: value-type-1, ...}` | tuple, group of data values with named fields | -| `(optional some-type)` | an option type for objects that can either be `(some value)` or `none` | -| `(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. | diff --git a/i18n/de/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md b/i18n/de/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md deleted file mode 100644 index e75e1d69b9..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Clarity overview -description: Overview and guides for getting started with Clarity -sidebar_label: Write smart contracts -sidebar_position: 2 ---- - -## Introduction - -Clarity is a **decidable** smart contract language that optimizes for predictability and security, designed for the Stacks blockchain. Smart contracts allow developers to encode essential business logic on a blockchain. - -## Smart contracts - -Smart contracts encode and enforce rules for modifying a particular set of data that is shared among people and entities who don't necessarily trust each other. For example, a smart contract can hold funds in escrow until multiple parties agree to release them, create its own ledger and keep track of its own novel tokens (fungible or non-fungible), and even help make supply chains more transparent. - -A smart contract execution can result in new transactions being written to the blockchain. Because smart contracts are programs that exist in a blockchain, anyone can query them, and anyone can submit transactions to execute them. - -Apps can take advantage of smart contracts to manage a global state that is visible to the public. Anyone can audit the blockchain to independently verify that an app's global shared state has been managed correctly according to the smart contract's rules. - -There is a [Clarity Visual Studio Code plugin][] available for syntax assistance and debugging. - -## Use cases - -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 (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 - -## Language design - -Clarity differs from most other smart contract languages in two essential ways: - -- The language is interpreted and broadcast on the blockchain as is (not compiled) -- The language is decidable (not Turing complete) - -Using an interpreted language ensures that the executed code is human-readable and auditable. A decidable language like Clarity makes it possible to determine precisely which code is executed, for any function. - -A Clarity smart contract consists of two parts, a data space and a set of functions. Only the associated smart contract may modify its corresponding data space on the blockchain. Functions may be private and thus callable only from within the smart contract, or public and thus callable from other contracts. Users call smart contracts' public functions by broadcasting a transaction on the blockchain which invokes the public function. Contracts can also call public functions from other smart contracts. - -Note some of the key Clarity language rules and limitations. - -- The only primitive types are booleans, integers, buffers, and principals. -- Recursion is illegal and there are no anonymous functions. -- Looping is only performed via `map`, `filter`, or `fold`. -- There is support for lists, however, the only variable length lists in the language appear as function inputs; there is no support for list operations like append or join. -- Variables are immutable. - -## Explore more - -For language details and references, see the following: - -- [Clarity language overview](./clarity-language/) -- [Understating Principals](principals) -- [Clarity Values](values) - -[Clarity Visual Studio Code plugin]: https://marketplace.visualstudio.com/items?itemName=HiroSystems.clarity-lsp diff --git a/i18n/de/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md b/i18n/de/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md deleted file mode 100644 index 2482d174a7..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md +++ /dev/null @@ -1,240 +0,0 @@ ---- -title: Principals -description: 'Clarity: Understanding Principals' -sidebar_position: 1 ---- - -## Introduction - -_Principals_ are a Clarity native type that represents an entity that can have a token balance. This section discusses principals and how they are used in the Clarity. - -## Principals and tx-sender - -Assets in the smart contracting language and blockchain are "owned" by objects of the principal type, meaning that any object of the principal type may own an asset. For the case of public-key hash and multi-signature Stacks addresses, a given principal can operate on their assets by issuing a signed transaction on the blockchain. _Smart contracts_ may also be principals (represented by the smart contract's identifier), however, there is no private key associated with the smart contract, and it cannot broadcast a signed transaction on the blockchain. - -A Clarity contract can use a globally defined `tx-sender` variable to obtain the current principal. The following example defines a transaction type that transfers `amount` microSTX from the sender to a recipient if amount is a multiple of 10, otherwise returning a 400 error code. - -```clarity -(define-public (transfer-to-recipient! (recipient principal) (amount uint)) - (if (is-eq (mod amount 10) 0) - (stx-transfer? amount tx-sender recipient) - (err u400))) -``` - -Clarity provides an additional variable to help smart contracts authenticate a transaction sender. The keyword `contract-caller` returns the principal that _called_ the current contract. If an inter-contract call occurred, `contract-caller` returns the last contract in the stack of callers. For example, suppose there are three contracts A, B, and C, each with an `invoke` function such that `A::invoke` calls `B::invoke` and `B::invoke` calls `C::invoke`. - -When a user Bob issues a transaction that calls `A::invoke`, the value of `contract-caller` in each successive invoke function's body would change: - -```clarity -in A::invoke, contract-caller = Bob -in B::invoke, contract-caller = A -in C::invoke, contract-caller = B -``` - -This allows contracts to make assertions and perform authorization checks using not only the `tx-sender` (which in this example, would always be "Bob"), but also using the `contract-caller`. This could be used to ensure that a particular function is only ever called directly and never called via an inter-contract call (by asserting that `tx-sender` and `contract-caller` are equal). We provide an example of a two different types of authorization checks in the rocket ship example below. - -## Smart contracts as principals - -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, for example: - -```clarity -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-name -``` - -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 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 qualified identifier for the contracts would be: - -```clarity -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-A -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-B -``` - -But, in the contract source code, if the developer wishes to call a function from `contract-A` in `contract-B`, they can write - -```clarity -(contract-call? .contract-A public-function-foo) -``` - -This allows the smart contract developer to modularize their applications across multiple smart contracts _without_ knowing the publishing key a priori. - -In order for a smart contract to operate on assets it owns, smart contracts may use the special `(as-contract ...)` function. This function executes the expression (passed as an argument) with the `tx-sender` set to the contract's principal, rather than the current sender. The `as-contract` function returns the value of the provided expression. - -For example, a smart contract that implements something like a "token faucet" could be implemented as so: - -```clarity -(define-map claimed-before - ((sender principal)) - ((claimed bool))) - -(define-constant err-already-claimed u1) -(define-constant err-faucet-empty u2) -(define-constant stx-amount u1) - -(define-public (claim-from-faucet) - (let ((requester tx-sender)) ;; set a local variable requester = tx-sender - (asserts! (is-none (map-get? claimed-before {sender: requester})) (err err-already-claimed)) - (unwrap! (as-contract (stx-transfer? stx-amount tx-sender requester)) (err err-faucet-empty)) - (map-set claimed-before {sender: requester} {claimed: true}) - (ok stx-amount))) -``` - -In this example, the public function `claim-from-faucet`: - -- Checks if the sender has claimed from the faucet before. -- Assigns the tx sender to a `requester` variable. -- Adds an entry to the tracking map. -- Uses `as-contract` to send 1 microstack - -Unlike other principals, there is no private key associated with a smart contract. As it lacks a private key, a Clarity smart contract cannot broadcast a signed transaction on the blockchain. - -## Example: Authorization checks - -The interactions between `tx-sender`, `contract-caller` and `as-contract` are subtle, but are important when performing authorization checks in a contract. In this example contract, we'll show two different kinds of authorization checks a contract may wish to perform, and then walk through how different ways in which contract functions may be called will pass or fail those checks. - -This contract defines a "rocket-ship" non-fungible-token that a principal may own and manage the authorized pilots. Pilots are principals that are allowed to "fly" the rocket ship. - -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. -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 be called _directly_ by the ship's owner, rather than through a inter-contract-call. - -The second type of check is more restrictive than the first check, and is helpful for guarding very sensitive routines --- it protects users from unknowingly calling a function on a malicious contract that subsequently tries to call sensitive functions on another contract. - -```clarity -;; -;; rockets-base.clar -;; - -(define-non-fungible-token rocket-ship uint) - -;; a map from rocket ships to their allowed -;; pilots -(define-map allowed-pilots - ((rocket-ship uint)) ((pilots (list 10 principal)))) - -;; implementing a contains function via fold -(define-private (contains-check - (y principal) - (to-check { p: principal, result: bool })) - (if (get result to-check) - to-check - { p: (get p to-check), - result: (is-eq (get p to-check) y) })) - -(define-private (contains (x principal) (find-in (list 10 principal))) - (get result (fold contains-check find-in - { p: x, result: false }))) - -(define-read-only (is-my-ship (ship uint)) - (is-eq (some tx-sender) (nft-get-owner? rocket-ship ship))) - -;; this function will print a message -;; (and emit an event) if the tx-sender was -;; an authorized flyer. -;; -;; here we use tx-sender, because we want -;; to allow the user to let other contracts -;; fly the ship on behalf of users - -(define-public (fly-ship (ship uint)) - (let ((pilots (default-to - (list) - (get pilots (map-get? allowed-pilots { rocket-ship: ship }))))) - (if (contains tx-sender pilots) - (begin (print "Flew the rocket-ship!") - (ok true)) - (begin (print "Tried to fly without permission!") - (ok false))))) -;; -;; Authorize a new pilot. - (ok true)) - (begin (print "Tried to fly without permission!") - (ok false))))) -;; -;; Authorize a new pilot. - (ok false))))) -;; -;; Authorize a new pilot. -;; -;; here we want to ensure that this function -;; was called _directly_ by the user by -;; checking that tx-sender and contract-caller are equal. -;; if any other contract is in the call stack, contract-caller -;; would be updated to a different principal. -;; -(define-public (authorize-pilot (ship uint) (pilot principal)) - (begin - ;; sender must equal caller: an intermediate contract is - ;; not issuing this call. - (asserts! (asserts! (is-eq tx-sender contract-caller) (err u1)) - ;; sender must own the rocket ship - (asserts! (is-eq (some tx-sender) - (nft-get-owner? rocket-ship ship)) (err u2)) - (let ((prev-pilots (default-to - (list) - (get pilots (map-get? allowed-pilots { rocket-ship: ship }))))) - ;; don't add a pilot already in the list - (asserts! (not (contains pilot prev-pilots)) (err u3)) - ;; append to the list, and check that it is less than - ;; the allowed maximum - (match (as-max-len? -``` - -### Extending functionality: Multi-flyer contract - -The authorization scheme for `fly-ship` allows pilots to fly rocket-ships from other contracts. This allows other contracts to provide new functionality built around calling that function. - -For example, we can create a contract that calls `fly-ship` for multiple rocket-ships in a single transaction: - -```clarity -;; -;; rockets-multi.clar -;; - -(define-private (call-fly (ship uint)) - (unwrap! (contract-call? .rockets-base fly-ship ship) false)) -;; try to fly all the ships, returning a list of whether -;; or not we were able to fly the supplied ships -(define-public (fly-all (ships (list 10 uint))) - (ok (map call-fly ships))) -``` - -### Authorization for Contract-Owned Assets - -The check in `authorize-pilot` protects users from malicious contracts, but how would such a scheme support contract-owned assets? This is what the `as-contract` function is used for. The `as-contract` function executes the supplied closure as if the sender of the transaction was the current contract, rather than the user -- it does this by updating `tx-sender` to the current contract principal. We can use this to, for example, create a smart contract rocket-ship-line: - -```clarity -;; -;; rockets-ship-line.clar -;; - -(define-constant line-ceo 'SP19Y6GRV9X778VFS1V8WT2H502WFK33XZXADJWZ) - -(define-data-var employed-pilots (list 10 principal) (list)) - -;; This function will: -;; * check that it is called by the line-ceo -;; * check that the rocket is owned by the contract -;; * authorize each employed pilot to the ship -(define-public (add-managed-rocket (ship uint)) - (begin - ;; 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 - (asserts! (contract-call? .rockets-base is-my-ship ship) (err u2)) - ;; register all of our pilots on the ship - (add-pilots-to ship))))) - -;; add all the pilots to a ship using fold -- -;; the fold checks the return type of previous calls, -;; skipping subsequent contract-calls if one fails. -(define-private (add-pilot-via-fold (pilot principal) (prior-result (response uint uint))) - (let ((ship (try! prior-result))) - (try! (contract-call? .rockets-base authorize-pilot ship pilot)) - (ok ship))) -(define-private (add-pilots-to (ship uint)) - (fold add-pilot-via-fold (var-get employed-pilots) (ok ship))) -``` - -In order for the contract to add each pilot to a new ship, the contract must call `authorize-pilot`. However, the contract wants to perform this action on behalf of a ship the _contract_ owns, not the transaction sender. To do this, the contract uses `as-contract`. diff --git a/i18n/de/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md b/i18n/de/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md deleted file mode 100644 index a01e37bc04..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Resources -description: 'Resources' -sidebar_position: 8 ---- - -# External resources - - -[Clarity book](https://book.clarity-lang.org/) - -[Clarity Universe](https://stacks.org/clarity-universe) - -[Hiro Clarity tutorials](https://docs.hiro.so/tutorials) diff --git a/i18n/de/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md b/i18n/de/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md deleted file mode 100644 index ed65829518..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Clarity development software -description: The following tools are useful when developing Clarity smart contracts -sidebar_position: 4 ---- - -## Language Server Protocol for Clarity (including Visual Studio Code extension) - -The Language Server Protocol (LSP) defines the protocol used between an editor or IDE and a language server that provides language features like auto complete, go to definition, find all references etc. - -This makes programming in Clarity easier and much more intuitive. - -![Clarity LSP Screenshot](https://raw.githubusercontent.com/hirosystems/clarity-lsp/21b64298ca117dc41358eb9dce4605cc4a448a4c/images/screenshot.png?raw=true) - - -Clarity LSP repository is available [here](https://github.com/hirosystems/clarity-lsp). The extension for Visual Studio Code can be downloaded directly from [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=HiroSystems.clarity-lsp), but can be and older version. For a more up to date version you can also download it from [open-vsx](https://open-vsx.org/extension/hirosystems/clarity-lsp). - -## Clarity REPL - -A read—eval—print loop (REPL), also termed an interactive toplevel or language shell, is a simple, interactive computer programming environment that takes single user inputs (that is, single expressions), evaluates (executes) them, and returns the result to the user; a program written in a REPL environment is executed piecewise. - -![Clarity-repl](https://github.com/hirosystems/clarity-repl/blob/develop/docs/images/screenshot.png?raw=true) - -Instructions on how to install Clarity REPL can be found [here](https://github.com/hirosystems/clarity-repl). - -## Clarinet - -Clarinet is a Clarity runtime packaged as a command line tool, designed to facilitate smart contract understanding, development, testing and deployment. Clarinet consists of a Clarity REPL and a testing harness, which, when used together allow you to rapidly develop and test a Clarity smart contract, with the need to deploy the contract to a local devnet or testnet. - -![Clarinet](https://github.com/hirosystems/clarinet/blob/develop/docs/images/demo.gif?raw=true) - -Installation instructions, including build from source instructions can be found [here](https://github.com/hirosystems/clarinet). If you prefer you can directly download the latest compiled realease for Windows, Mac and Linux [here](https://github.com/hirosystems/clarinet/releases). - -[Clarinet 101](https://www.youtube.com/playlist?list=PL5Ujm489LoJaAz9kUJm8lYUWdGJ2AnQTb) contains multiple Clarinet video tutorials - -### Getting started with Clarinet - -You can verify you have Clarinet installed by checking its version: - -```bash -$ clarinet --version -clarinet 0.70 -``` - -More detailed information on using Clarinet is available [here](https://book.clarity-lang.org/ch07-00-using-clarinet.html). However to get you started, the following commands are important to know. - -Create a new project and enter its directory: - -```bash -clarinet new my-project && cd my-project -``` - -Create a new contract inside `my-project`: - -```bash -clarinet contract new mycoolcontract -``` - -Check the syntax of Clarity: - -```bash -clarity check -``` - -To test your contract: - -```bash -clarinet test -``` - -Enter Clarinet's console: - -```bash -clarinet console -``` diff --git a/i18n/de/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md b/i18n/de/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md deleted file mode 100644 index 2754709092..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Tokens -description: Learn about token support within Clarity -sidebar_position: 3 ---- - -## Introduction - -A fundamental use of blockchain technology is the representation, store, and transfer of value between users of a blockchain. Cryptocurrency is a very common use of blockchain technology, and remains one of the primary drivers of adoption of blockchain technology. Cryptocurrencies are represented by blockchain tokens: individual units of value within a given blockchain ecosystem. Blockchain tokens can extend beyond just digital currency, however, and recent developments throughout the cryptocurrency community have demonstrated potential for the use of blockchain to tokenize and represent not just money but other tangible assets. - -A blockchain token is a digital asset that can be verifiably owned by a user of a blockchain. Blockchain tokens are governed by a set of rules that are defined by either the blockchain itself (in the case of native tokens) or by a smart contract on a blockchain. Rules can vary depending on the nature and the use of the token. - -Tokens on a blockchain fall into two general categories, depending on their properties: [fungible][] or [non-fungible][]. The following sections discuss the properties of both types of tokens, and provide information about implementation of the two types of tokens on Stacks. - -## Fungible tokens - -A core property of any token on a blockchain is fungibility. A fungible token is a token that's mutually interchangable or capable of mutual substitution. In other words, one quantity or part of a fungible token can be replaced by an equal quantity or part of the same fungible token. Fungible tokens are often used to represent real-world fungible assets like currency. The STX token is an example of a fungible token. Other examples include stablecoins, tokens that represent voting rights in a DAO, or tokens that algorithmically track the price of stocks. - -Fungible tokens form one of the most important value propositions for blockchain technology, the ability to store value and exchange that value through both internal and external transactions. Because fungible tokens can be divided into smaller parts and recombined into the same value representation, they serve a great utility for transferring value between blockchain users. - -The primary fungible token on the Stacks blockchain is the native token, STX. Because the Stacks blockchain allows for the creation of \[smart contracts\]\[\], other fungible tokens can be created on the Stacks blockchain as well. [SIP-010][] specifies the standard for fungible tokens on the Stacks blockchain. This specification defines the functions and traits that a fungible token on Stacks _must_ have. This specification defines the functions and traits that a fungible token on Stacks _must_ have. - -### Understanding the fungible token standard - -The [SIP-010][] standard is an interface definition that allows Stacks applications and wallets to interact with fungible tokens in a standard way. Supporting the standard reduces complexity for token creators to get their tokens into the ecosystem. Under the [SIP-010][] standard, fungible tokens must have the following characteristics: - -- Ability to transfer a specified amount of the token to a recipient (`transfer`). The recipient is required to be a Stacks principal. -- Ability to obtain the human-readable name of the token (`get-name`). -- Ability to obtain a short name (ticker symbol) for the token (`get-symbol`). -- Ability to get the number of decimals in the token representation (`get-decimals`). This is used to construct a representation of the token that humans would be familiar dealing with. For example, the US dollar has 2 decimals, if the base unit is cents. -- Ability to get the balance of the token for a particular Stacks principal (`get-balance-of`). -- Ability to get the total supply of the token (`get-total-supply`). -- A URI to metadata associated with the token (`get-token-uri`). This can resolve to off-chain metadata about the token or contract, such as an image icon for the token or a description. - -## Non-fungible tokens (NFTs) - -Non-fungible tokens (NFTs) are a type of token that are not interchangeable. NFTs have unique traits (usually in the form of attached metadata) that restrict the abillity to replace them with identical tokens. An NFT is a token that is unique, such as a piece of art, or ownership rights to a real-world asset such as a house. - -NFTs alone don't have an inherent value, like a currency. The value of an NFT is derived from the assets that the NFT represents. The use of NFTs are myriad, including digital art, collectibles, domain names, and representation of ownership of content rights. NFTs can be used as digital certificates that track the authenticty of real world items, or digitize the ownership rights to property. - -As with fungible tokens, NFTs on the Stacks blockchain are created with smart contracts. [SIP-009][] specifies the standard for NFTs on the Stacks blockchain. This specification defines the functions and traits that an NFT _must_ have, but most NFTs have more functions or traits attached than those solely described by the specification. By complying with this standard, non-fungible tokens on Stacks can be easily represented by wallets that support Stacks. - -### Understanding the non-fungible token standard - -The [SIP-009][] standard is an interface definition that the Stacks ecosystem aligned on. With support for this standard across wallets and tools, it becomes easy to interact with NFTs. Under the [SIP-009][] standard, NFT contract must have the following characteristics: - -- Ability to obtain the last token identifier (`get-last-token-id`). This id represents the upper limit of NFTs issued by the contract. -- A URI to metadata associated with a specific token identifier. (`get-token-uri`). This URI could resolve to a JSON file with information about the creator, associated media files, descriptions, signatures, and more. -- Ability to verify the owner for a given token identifier (`get-owner`). The owner resolves to a [Stacks principal](principals). -- Ability to transfer an NFT to a recipient (`transfer`). The recipient is required to be a Stacks principal. - -## Further reading - -- [The Difference Between Fungible and Non-Fungible Tokens](https://101blockchains.com/fungible-vs-non-fungible-tokens/) -- [Explain It Like I Am 5: NFTs](https://messari.io/article/explain-it-like-i-am-5-nfts) - -[fungible]: #fungible-tokens -[non-fungible]: #non-fungible-tokens-nfts -[SIP-010]: https://github.com/hstove/sips/blob/feat/sip-10-ft/sips/sip-010/sip-010-fungible-token-standard.md -[SIP-009]: https://github.com/stacksgov/sips/blob/main/sips/sip-009/sip-009-nft-standard.md diff --git a/i18n/de/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md b/i18n/de/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md deleted file mode 100644 index fc4765aa0c..0000000000 --- a/i18n/de/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md +++ /dev/null @@ -1,301 +0,0 @@ ---- -title: Clarity Values -description: Learn how to deal with Clarity Values in JavaScript -sidebar_position: 2 ---- - -## Introduction - -The Clarity language makes use of a strong static 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/hirosystems/stacks.js/tree/master/packages/transactions) library makes this easy, as we will demonstrate below. - -## Clarity Types - -Please see the following page for information on [Clarity Types](../write-smart-contracts/clarity-language/language-types). - -## Constructing Clarity Values and accessing their data - -Clarity values can be constructed with functions provided by the [@stacks/transactions](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library. These functions simply output javascript objects that contain a value and a numerical representation of the Clarity type information. The Clarity types are encoded as follows: - -```typescript -export enum ClarityType { - Int = 0, - UInt = 1, - Buffer = 2, - BoolTrue = 3, - BoolFalse = 4, - PrincipalStandard = 5, - PrincipalContract = 6, - ResponseOk = 7, - ResponseErr = 8, - OptionalNone = 9, - OptionalSome = 10, - List = 11, - Tuple = 12, - StringASCII = 13, - StringUTF8 = 14, -} -``` - -`ClarityValue` objects can be serialized and included in transactions that interact with published Clarity contracts. - -Here are examples of how to construct each type of Clarity value, and how to access its data if it has any: - -### Booleans - -```typescript -const t = trueCV(); -// { type: ClarityType.BoolTrue } - -const f = falseCV(); -// { type: ClarityType.BoolFalse } -``` - -Boolean Clarity Values don't contain any underlying data. They are simply objects with `type` information. - -### Optional Values - -```typescript -const nothing: NoneCV = noneCV(); -// { type: ClarityType.OptionalNone } - -const something: SomeCV = someCV(trueCV()); -// { type: ClarityType.OptionalSome, value: { type: 4 } } -``` - -Optional Clarity Values can either be nothing (an empty type that has no data), or something (a wrapped value). - -If you are dealing with a function or contract function that returns an `OptionalCV`, you should always check what type it is before trying to access its value. - -```typescript -const maybeVal: OptionalCV = await callReadOnlyFunction(...); - -if (maybeVal.type === ClarityType.OptionalSome) { - console.log(maybeVal.value); -} else if (maybeVal.type === ClarityType.OptionalNone) { - // deal with `none` value -} -``` - -### Buffers - -```typescript -const buffer = Buffer.from('foo'); -const bufCV: BufferCV = bufferCV(buffer); -// { type: ClarityType.Buffer, buffer: } -``` - -### Integers - -Clarity supports both integers and unsigned integers. - -```typescript -const i: IntCV = intCV(-10); -// { type: ClarityType.Int, value: BN { ... } } - -const u: UIntCV = uintCV(10); -// { type: ClarityType.UInt, value: BN { ... } } -``` - -Clarity value ints store their underlying data as `BigNum` values from the [bn.js](https://github.com/indutny/bn.js/) library. - -In order to display/print Clarity (u)int values, use the `cvToString(val)` method. - -If you wish to perform arithmetic operations using Clarity (u)int values, you must use methods from the `BigNum` api on their underlying `BigNum` values, and the construct a new Clarity value out of the result. For example: - -```typescript -const x = intCV(1); -const y = intCV(2); - -x.value.add(y.value); -// 3 -``` - -### Strings - -```typescript -const ascii: StringAsciiCV = stringAsciiCV('hello world'); -// { type: ClarityType.StringASCII, data: 'hello world' } - -const utf8: StringUtf8CV = stringUtf8CV('hello 🌾'); -// { type: ClarityType.StringUTF8, data: 'hello 🌾' } -``` - -Clarity supports both ascii and utf8 strings. - -### Principals - -```typescript -const address = 'SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B'; -const contractName = 'contract-name'; - -const spCV = standardPrincipalCV(address); -// { -// type: ClarityType.PrincipalStandard -// address: { -// type: StacksMessageType.Address, -// version: AddressVersion.MainnetSingleSig, -// hash160: "SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B" -// } -// } - -const cpCV = contractPrincipalCV(address, contractName); -// { -// type: ClarityType.PrincipalContract, -// contractName: { -// type: StacksMessageType.LengthPrefixedString, -// content: 'contract-name', -// lengthPrefixBytes: 1, -// maxLengthBytes: 128, -// }, -// address: { -// type: StacksMessageType.Address, -// version: AddressVersion.MainnetSingleSig, -// hash160: "SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B" -// } -// } -``` - -Both kinds of Clarity principal values contain `type` information and an `address` object. Contract principals also contain a `contractName`. - -### Response Values - -```typescript -const errCV = responseErrorCV(trueCV()); -// { type: ResponseErr, value: { type: ClarityType.BoolTrue } } - -const okCV = responseOkCV(falseCV()); -// { type: ResponseOk, value: { type: ClarityType.BoolFalse } } -``` - -Response Clarity Values will either have the type `ClarityType.ResponseOk` or `ClarityType.ResponseErr`. They both contain a Clarity Value. Often this value will be an integer error code if the response is an `Error`. - -### Tuples - -```typescript -const tupCV = tupleCV({ - a: intCV(1), - b: trueCV(), - c: falseCV(), -}); -// { -// type: ClarityType.Tuple, -// data: { -// a: { type: ClarityType.Int, value: BN { ... } }, -// b: { type: ClarityType.BoolTrue }, -// c: { type: ClarityType.BoolFalse }, -// } -// } - -console.log(tupCV.data['b']); -// { type: ClarityType.BoolTrue } -``` - -Tuples in Clarity are typed and contain named fields. The tuple above, for example, contains three fields with the names **a**, **b** and **c**, and the types of their values are `Int`, `Boolean` and `Boolean`, respectively. - -Clarity tuples are represented in JavaScript as objects and a tuple's data can be accessed by its `data` field, where the underlying JS object is stored. - -### Lists - -```typescript -const l = listCV([trueCV(), falseCV()]); -// { type: ClarityType.List, list: [{ type: ClarityType.BoolTrue }] } - -console.log(l.list[0]); -// { type: ClarityType.BoolTrue } -``` - -Lists, in Clarity, are homogeneous, meaning they can only contain elements of a singular (Clarity) type. Make sure to avoid constructing lists that have elements of multiple types. - -A Clarity lists underlying data can be accessed via its `list` field. - -## Using Clarity Values - -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](../understand-stacks/transactions#construction). - -## Utilizing Clarity Values from Transaction Responses - -`Read-only` Clarity functions can return Clarity values as a response. These `read-only` functions can be accessed easily in JavaScript via the [`callReadOnlyFunction()`](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions#calling-read-only-contract-function) function included in `@stacks/transactions`, which returns a `ClarityValue`. - -As mentioned above, `ClarityValues` are simply javascript objects containing a value and its associated Clarity type information. These object types are defined [here](https://github.com/hirosystems/stacks.js/tree/1f2b5fd8bdf1c2b5866e8171163594d7708a8c7a/packages/transactions/src/clarity/types). - -When you are calling a `read-only` contract function, you will always know what type the function will return, since functions in Clarity are strongly typed. - -It is common for Clarity functions to return values wrapped in a `Response`, in order to indicate if there was success or an error. - -Since every `ClarityValue` has a `type` field, the type of the result of a `read-only` function call can be checked and acted upon like so: - -```typescript -const contractAddress = 'ST3KC0MTNW34S1ZXD36JYKFD3JJMWA01M55DSJ4JE'; -const contractName = 'kv-store'; -const functionName = 'get-value'; -const buffer = bufferCVFromString('foo'); -const network = new StacksTestnet(); // for mainnet, use `StacksMainnet()` -const senderAddress = 'ST2F4BK4GZH6YFBNHYDDGN4T1RKBA7DA1BJZPJEJJ'; - -const options = { - contractAddress, - contractName, - functionName, - functionArgs: [buffer], - network, - senderAddress, -}; - -// make a read-only call to a contract function that -// returns a Response -const result: ResponseCV = await callReadOnlyFunction(options); - -if (result.type === ClarityType.ResponseOk) { - console.log(cvToString(result.value)); -} else if (result.type === ClarityType.ResponseErr) { - throw new Error(`kv-store contract error: ${result.value.data}`); -} -``` - -### ClarityValues to/from Hex - -If you receive a response from a transaction in the form of a `hex` string, you can deserialize it into a Clarity value like so: - -```javascript -import { hexToCV } from '@stacks/transactions'; - -let cv = hexToCV('hex_string'); -``` - -Similarly, you can convert a Clarity value to `hex` string like so: - -```javascript -import { cvToHex, trueCV } from '@stacks/transactions'; - -let trueHex = cvToHex(trueCV()); -``` - -## Debugging Clarity Values - -Sometimes you might receive a Clarity value that you were not expecting. Logging the value to your console won't always prove to be useful, unless you have memorized the Clarity value type enum values. - -In order to figure out what kind of value you are dealing with, you can use the `cvToString()` function to convert the Clarity value to a more easily readable string. - -For example, calling `cvToString()` on a large `tuple` might yield something like: - -``` -(tuple - (a -1) - (b u1) - (c 0x74657374) - (d true) - (e (some true)) - (f none) - (g SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B) - (h SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B.test) - (i (ok true)) - (j (err false)) - (k (list true false)) - (l (tuple (a true) (b false))) - (m "hello world") - (n u"hello \u{1234}"))` -``` diff --git a/i18n/es/docusaurus-plugin-content-docs/current/blockchain/index.md b/i18n/es/docusaurus-plugin-content-docs/current/blockchain/index.md deleted file mode 100644 index 13db24ec30..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/blockchain/index.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: Blockchain -description: Stacks Blockchain -sidebar_position: 6 ---- - -Below is a guide to start working locally with the Stacks Blockchain. - -Code repository is [here](https://github.com/stacks-network/stacks-blockchain). - -## Getting started with the Stacks Blockchain - -### Download and build stacks-blockchain - -The first step is to ensure that you have Rust and the support software installed. - -```bash -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -``` - -:::info -For building on Windows, follow the rustup installer instructions at https://rustup.rs/ -::: - -From there, you can clone the Stacks Blockchain repository: - -```bash -git clone --depth=1 https://github.com/stacks-network/stacks-blockchain.git - -cd stacks-blockchain -``` - -Then build the project: - -```bash -cargo build -``` - -Run the tests: - -```bash -cargo test testnet -- --test-threads=1 -``` - -### Encode and sign transactions - -Here, we have generated a keypair that will be used for signing the upcoming transactions: - -```bash -cargo run --bin blockstack-cli generate-sk --testnet - -# Output -# { -# secretKey: "b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001", -# publicKey: "02781d2d3a545afdb7f6013a8241b9e400475397516a0d0f76863c6742210539b5", -# stacksAddress: "ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH" -# } -``` - -This keypair is already registered in the `testnet-follower-conf.toml` file, so it can be used as presented here. - -We will interact with the following simple contract `kv-store`. In our examples, we will assume this contract is saved to `./kv-store.clar`: - -```scheme -(define-map store { key: (string-ascii 32) } { value: (string-ascii 32) }) - -(define-public (get-value (key (string-ascii 32))) - (match (map-get? store { key: key }) - entry (ok (get value entry)) - (err 0))) - -(define-public (set-value (key (string-ascii 32)) (value (string-ascii 32))) - (begin - (map-set store { key: key } { value: value }) - (ok true))) -``` - -We want to publish this contract on chain, then issue some transactions that interact with it by setting some keys and getting some values, so we can observe read and writes. - -Our first step is to generate and sign, using your private key, the transaction that will publish the contract `kv-store`. To do that, we will use the subcommand `blockstack-cli` that has the following usage: - -```bash -blockstack-cli (options) publish [publisher-secret-key-hex] [fee-rate] [nonce] [contract-name] [file-name.clar] -``` - -With the following arguments: - -```bash -cargo run --bin blockstack-cli publish b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 515 0 kv-store ./kv-store.clar --testnet -``` - -The `515` is the transaction fee, denominated in microSTX. Right now, the testnet requires one microSTX per byte minimum, and this transaction should be less than 515 bytes. The third argument `0` is a nonce, that must be increased monotonically with each new transaction. - -This command will output the **binary format** of the transaction. In our case, we want to pipe this output and dump it to a file that will be used later in this tutorial. - -```bash -cargo run --bin blockstack-cli publish b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 515 0 kv-store ./kv-store.clar --testnet | xxd -r -p > tx1.bin -``` - -### Run the testnet - -You can observe the state machine in action locally by running: - -```bash -cargo stacks-node start --config=./testnet/stacks-node/conf/testnet-follower-conf.toml -``` - -`testnet-follower-conf.toml` is a configuration file that you can use for setting genesis balances or configuring Event observers. You can grant an address an initial account balance by adding the following entries: - -``` -[[ustx_balance]] -address = "ST2VHM28V9E5QCRD6C73215KAPSBKQGPWTEE5CMQT" -amount = 100000000 -``` - -The `address` field is the Stacks testnet address, and the `amount` field is the number of microSTX to grant to it in the genesis block. The addresses of the private keys used in the tutorial below are already added. - -### Publish your contract - -Assuming that the testnet is running, we can publish our `kv-store` contract. - -In another terminal (or file explorer), you can move the `tx1.bin` generated earlier, to the mempool: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx1.bin http://localhost:20443/v2/transactions -``` - -In the terminal window running the testnet, you can observe the state machine's reactions. - -### Reading from / Writing to the contract - -Now that our contract has been published on chain, let's try to submit some read / write transactions. We will start by trying to read the value associated with the key `foo`. - -To do that, we will use the subcommand: - -```bash -cargo run --bin blockstack-cli contract-call --help -``` - -With the following arguments: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 1 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store get-value -e \"foo\" --testnet | xxd -r -p > tx2.bin -``` - -`contract-call` generates and signs a contract-call transaction. - -We can submit the transaction by moving it to the mempool path: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx2.bin http://localhost:20443/v2/transactions -``` - -Similarly, we can generate a transaction that would be setting the key `foo` to the value `bar`: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 2 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store set-value -e \"foo\" -e \"bar\" --testnet | xxd -r -p > tx3.bin -``` - -And submit it by moving it to the mempool path: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx3.bin http://localhost:20443/v2/transactions -``` - -Finally, we can issue a third transaction, reading the key `foo` again, for ensuring that the previous transaction has successfully updated the state machine: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 3 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store get-value -e \"foo\" --testnet | xxd -r -p > tx4.bin -``` - -And submit this last transaction by moving it to the mempool path: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx4.bin http://localhost:20443/v2/transactions -``` - -Congratulations, you can now [write your own smart contracts with Clarity](write-smart-contracts/). diff --git a/i18n/es/docusaurus-plugin-content-docs/current/blockchain/networks.md b/i18n/es/docusaurus-plugin-content-docs/current/blockchain/networks.md deleted file mode 100644 index fe9725352c..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/blockchain/networks.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Stacks Blockchain Networks -description: Stacks Blockchain Networks -sidebar_position: 3 ---- - -### Stacks Blockchain Networks - -- [x] **Krypton** is a Stacks 2 testnet with a fixed, two-minute block time, called `regtest`. Regtest is generally unstable for regular use, and is reset often. See the [regtest documentation](understand-stacks/testnet) for more information on using regtest. - -- [x] **Testnet** (old Xenon) is the Stacks 2 public testnet, which runs PoX against the Bitcoin testnet. It is the full implementation of the Stacks 2 blockchain, and should be considered a stable testnet for developing Clarity smart contracts. See the [testnet documentation](understand-stacks/testnet) for more information on the public testnet. - -- [x] **Mainnet** is the fully functional Stacks 2 blockchain, see the [Stacks overview](understand-stacks/) for information on running a Stacks node, mining, stacking, and writing Clarity smart contracts. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md b/i18n/es/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md deleted file mode 100644 index 14d3e15efe..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Stacks Blockchain API -description: Interacting with the Stacks 2.0 Blockchain via API -sidebar_position: 4 ---- - -## Introducción - -:::tip API Documentation Official API Documentation is available [here](https://stacks-network.github.io/stacks-blockchain/). ::: - - -The Stacks 2.0 Blockchain API allows you to query the Stacks 2.0 blockchain and interact with smart contracts. It was built to maintain pageable materialized views of the Stacks 2.0 Blockchain. - -:::caution The RESTful API is developed by Hiro. Hiro also hosts a public API node for easy onboarding. Using it requires you to trust the hosted server, but provides a faster onboarding experience. You can [run your own API server](https://docs.hiro.so/get-started/running-api-node) ::: - -The RESTful JSON API can be used without any authorization. The basepath for the API is: - -```bash -# for mainnet, replace `testnet` with `mainnet` -https://stacks-node-api.testnet.stacks.co/ -``` - -:::note This documentation only covers endpoints that are exposed on a Stacks node, referred to as the RPC API. For full documentation on the RESTful API, check out the [Hiro's API reference](https://docs.hiro.so/api). ::: - -### Stacks Node RPC API - -The [stacks-node implementation](https://github.com/stacks-network/stacks-blockchain/) exposes JSON RPC endpoints. - -All `/v2/` routes a proxied to a Hiro-hosted Stacks Node. For a trustless architecture, you should make these requests to a self-hosted node. - -## Proxied Stacks Node RPC API endpoints - -The Stacks 2.0 Blockchain API is centrally hosted. However, every running Stacks node exposes an RPC API, which allows you to interact with the underlying blockchain. Instead of using a centrally hosted API, you can directly access the RPC API of a locally hosted Node. - -:::tip -The Stacks Blockchain API proxies to Node RPC endpoints -::: - -While the Node RPC API doesn't give the same functionality as the hosted Stacks 2.0 Blockchain API, you get similar functionality in a way that is scoped to that specific node. The RPC API includes the following endpoints: - -- [POST /v2/transactions](https://docs.hiro.so/api#operation/post_core_node_transactions) -- [GET /v2/contracts/interface/{contract_address}/{contract_name}](https://docs.hiro.so/api#operation/get_contract_interface) -- [POST /v2/map_entry/{contract_address}/{contract_name}/{map_name}](https://docs.hiro.so/api#operation/get_contract_data_map_entry) -- [GET /v2/contracts/source/{contract_address}/{contract_name}](https://docs.hiro.so/api#operation/get_contract_source) -- [GET /v2/accounts/{principal}](https://docs.hiro.so/api#operation/get_account_info) -- [POST /v2/contracts/call-read/{contract_address}/{contract_name}/{function_name}](https://docs.hiro.so/api#operation/call_read_only_function) -- [GET /v2/fees/transfer](https://docs.hiro.so/api#operation/get_fee_transfer) -- [GET /v2/info](https://docs.hiro.so/api#operation/get_core_api_info) - -:::caution If you run a local node, it exposes an HTTP server on port `20443`. The info endpoint would be `localhost:20443/v2/info`. ::: diff --git a/i18n/es/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md b/i18n/es/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md deleted file mode 100644 index 71e3542302..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Stacks Releases -description: Stacks Blockchain Releases -sidebar_position: 2 ---- - -:::info -This page needs contributions. Help us improve it. -::: - -### Stacks Blockchain Releases - -All releases are published [here](https://github.com/stacks-network/stacks-blockchain/releases). Most important ones are described below. - -### Stacks 2.1 - -Scheduled for release at the end of 2022. - -More information on [what to expect with Stacks 2.1](https://stacks.org/stacks-21-what-to-expect). - -#### Stacks 2.05 -Activated on [Bitcoin block 713000](https://explorer.stacks.co/txid/0xece8e369310b5ff9b92ef11181ae0d2457ac0c821376d4a96c4998763e22ad04?chain=mainnet). - -This breaking change enables storage cost for list to be based on actual length and change in number of indexed I/O operations. More info on this [blog post](https://www.stacks.org/stacks-2-05?ref=docs-website). - -#### Stacks 2.0 -Activated on January 14th 2021 - -This hard fork enables Stacking, Clarity smart contracts, scalable transactions, and also building directly on Bitcoin. More info [here](https://forum.stacks.org/t/path-to-mainnet-for-stx-holders-things-to-know-ahead-of-stacks-2-0/11529). - -#### Stacks Genesis -Released on 2018, October 30th UTC+6 at Bitcoin block height 547921 - -This hard fork addresses registration of digital assets with Stacks token and also distribution of Stacks token to the existing purchasers. More info [here](https://blog.blockstack.org/the-launch-of-the-stacks-genesis-block/?ref=docs-website). - diff --git a/i18n/es/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md b/i18n/es/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md deleted file mode 100644 index 0f02c83e64..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Consejos para el despliegue -description: Aprende algunos métodos comunes para desplegar tu aplicación. ---- - -## Introducción - -Las aplicaciones de Stacks son aplicaciones web que autentifican a los usuarios con Stacks Auth y almacenan datos con Gaia. Ambas tecnologías pueden ser accesibles desde el lado del cliente. Como tal, las aplicaciones de Stacks tienden a ser simples en diseño y operación, dado que en muchos casos, no tienen que alojar nada aparte de los assets de la aplicación. - -## Donde hacer el despliegue tu aplicación - -Antes de que los usuarios puedan interactuar con tu aplicación, debes desplegarla en un servidor que sea accesible a través de internet. Desplegar requiere que: - -- Configure o personalice los archivos en el directorio `public`. -- Construya su aplicación para el despliegue. -- Copie los archivos generados por su aplicación en su servidor de producción. - -Si primero completó su aplicación con el generador de aplicaciones de Stacks, su aplicación ya contiene los bloques iniciales para configurar, construir y desplegar su aplicación. Por ejemplo, la plantilla de React genera un esquema con los siguientes bloques de construcción. - -| Archivos o Directorio | Descripción | -| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| node_modules/react-scripts | Un conjunto de scripts para que te ayude a iniciar proyectos React sin configuración, para que no tenga que configurar su proyecto usted mismo. | -| package.json | Contiene una sección de scripts que incluye una referencia a los react-scripts, que son una dependencia. Este script crea un directorio de compilación que contiene los archivos para el despliegue. | -| public/favicon.ico | Un ejemplo de ícono de atajo. | -| public/index.html | Página de entrada de una aplicación. | -| public/manifest.json | Un archivo JSON que describe tu aplicación web en el navegador. | -| cors | Contiene ejemplos de archivos de despliegue para la configuración de solicitudes de origen cruzado. | - -Si usa el generador para construir en JavasScript o Vue scaffolding, los archivos de configuración de su proyecto serán diferentes. - -Independientemente de cuál sea el andamio que utilice, debe personalizar y extender este andamio básico según su aplicación lo necesite. Por ejemplo, puede querer agregar más propiedades al archivo `manifest.json`. Dado que cada aplicación es diferente, Stacks Auth no puede dar instrucciones específicas sobre cómo hacerlo. Los pasos que usted tome son específicos de su aplicación. - -## Autenticación y despliegue en Stacks - -Cuando la aplicación autentifica a los usuarios con Stacks, la billetera de Stacks en la URL solicita un recurso (el manifiesto de la aplicación) de tu DApp. Una solicitud para un recurso fuera del origen (la billetera de Stacks) es llamada como una solicitud de _de origen cruzado_(CORs). Obtener datos de esta manera puede ser arriesgado, por lo que debe configurar la seguridad de su sitio web para permitir interacciones entre orígenes. - -Puedes pensar en las interacciones CORS como un edificio de apartamentos con seguridad. Por ejemplo, si necesita tomar prestado una escalera, podría preguntar a un vecino en el edificio que tiene uno. Probablemente la seguridad no tendría ningún problema con esta petición (es decir, el mismo origen, de su edificio). Sin embargo, si necesitaba una herramienta en particular, y la ordenó desde una tienda de hardware online (es decir, de origen cruzado, de otro sitio), La seguridad puede solicitar la identificación antes de permitir al hombre del delivery entrar en el edificio de apartamentos. (Créditos: Codecademy) - -La forma en que configure los CORs depende de la empresa que utilice para alojar su aplicación web. El generador de aplicaciones añade un directorio de `cors` a su aplicación de andamios. Este directorio contiene archivos para Netlify (`_headers` y `_redirects`) así como uno para Firebase (`firebase`). Las configuraciones en el directorio `cors` hacen que el archivo `manifest.json` de su aplicación sea accesible para otras aplicaciones (por ejemplo, para el navegador Stacks). Si está desplegando en un servicio distinto a Netlify o Firebase, debe configurar CORS en ese servicio para incluir las siguientes cabeceras al servir el `manifest.json`: - -```html -Access-Control-Allow-Origin: * Access-Control-Allow-Headers: "X-Requested-With, Content-Type, -Origin, Authorization, Accept, Client-Security-Token, Accept-Encoding" Access-Control-Allow-Methods: -"POST, GET, OPTIONS, DELETE, PUT" -``` - -Consulte la documentación de su servicio de hosting para aprender cómo configurar CORS en ese servicio. - -## Despliegue y Radiks - -Si está desplegando una aplicación Stacks que utiliza [Radiks](https://github.com/stacks-network/radiks), su implementación incluye un servidor y un componente de base de datos. Debe tener esto en cuenta al desplegar su aplicación. Puede que quieras elegir un servicio como [Heroku](https://www.heroku.com) o [Digital Ocean](https://www.digitalocean.com) si tu aplicación utiliza Radiks. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/build-apps/index.md b/i18n/es/docusaurus-plugin-content-docs/current/build-apps/index.md deleted file mode 100644 index e002fa02a0..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/build-apps/index.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Crea apps con Stacks -description: Identificación de usuarios, firma de transacciones y almacenamiento de datos en la cadena de bloques Stacks -sidebar_position: 3 -sidebar_label: Crear apps ---- - -## Introducción - -Las aplicaciones construidas con la cadena de bloques Stacks dan control a los usuarios sobre sus identidades, activos y datos digitales. - -A diferencia de la mayoría de las aplicaciones basadas en la nube, son "descentralizadas", ya que no dependen de ninguna plataforma, servidor o base de datos centralizada para funcionar. Más bien, usan la blockchain de Stacks para autenticar usuarios y facilitar la lectura y escritura de peticiones para ellos sin ningún punto único de fallo o confianza. - -Stacks proporciona tres funciones principales para construir aplicaciones: - - - -- **Autenticación**: Registrar e iniciar sesión con sus identidades en la blockchain de Stacks -- **Firma de transacciones**: Solicita a los usuarios que firmen y transmitan las transacciones a la blockchain de Stacks -- **Almacenamiento de datos**: Guardar y recuperar datos para los usuarios con [Gaia](../gaia) - - -Las tres integraciones se pueden utilizar juntas para crear nuevas y poderosas experiencias de usuario que rivalizan o superen las de las aplicaciones tradicionales, protegiendo al mismo tiempo los derechos digitales de los usuarios. - -Aunque la integración es posible para cualquier tipo de aplicación, la mayoría de los recursos disponibles aquí son para desarrolladores web con experiencia en JavaScript. Consulte [la documentación de desarrollo de Hiro](https://docs.hiro.so) para obtener más información sobre las bibliotecas de desarrollo de aplicaciones disponibles para Stacks. - -## [Referencias](references) - -[Autenticación](references/authentication) - -[BNS](references/bns) - -[Gaia](../gaia/) - diff --git a/i18n/es/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md b/i18n/es/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md deleted file mode 100644 index 0959d935ec..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: NoCodeClarity -description: Lanzar aplicaciones para la cadena de bloques de Stackas a través de plataformas sin código como Bubble. ---- - -## Introducción - -![](https://d1muf25xaso8hp.cloudfront.net/https%3A%2F%2Fs3.amazonaws.com%2Fappforest_uf%2Ff1653407713550x759333524803365600%2FLogo%2520of%2520NoCodeClarity.png?w=179&h=84&auto=compress&dpr=1&fit=max) - -[NoCodeClarity](https://nocodeclarity.com) permite a la gente crear aplicaciones para el blockchain de Stacks sin programar. - -## Plug-In de Stacks en bubble - -El [Stacks-No-Code-Plugin](https://bubble.io/plugin/the-stacks-plug-in-1645467277638x949839693014368300) fue lanzado en mayo de 2022 y se puede instalar fácilmente en Bubble con unos pocos clics permitiendo a los usuarios desplegar aplicaciones sin conocimientos de programación. [Bubble](https://bubble.io/blog/explaining-bubble-to-investors/) es la primera plataforma No Code en la que se lanzó el plugin de Stacks. Más plataformas están en la hoja de ruta de NoCodeClarity, fundada por Christopher Perceptions y Sergio Gongora. El plugin de Stacks fue creado a través del apoyo de la Fundación Stacks mediante una subvención en enero de 2022 y NoCodeClarity fue premiada con una subvención adicional de $100,000 en junio de 2022 para ampliar la hoja de ruta. - -También están disponibles [instrucciones](https://s3.amazonaws.com/appforest_uf/f1654202471526x991633667675927800/Instructions%20v2.docx.pdf) adicionales. Los tutoriales y las guías paso a paso serán publicadas pronto. - -El código de Stacks-No-Code-Plugin está [disponible públicamente en Github](https://github.com/nocodeclarity/Stacks-No-Code-Plugin). - -![](/img/bubble-stacks-plugin.png) - -## Página de demostración - -Una página de demostración está disponible [aquí](https://test-stacks-plugin.bubbleapps.io/version-test). - -## Vídeos NoCodeClarity - -NodeCodeClarity tiene su propio [canal de youtube](https://www.youtube.com/channel/UC9Ep0VQ-GQ-yDzt-wmIElRA). - -Vídeos: - -* [Configuración de NoCodeClarity](https://www.youtube.com/watch?v=WanXlpBGl0w) -* [NoCodeClarity - Parte 1 sobre el plugin](https://www.youtube.com/watch?v=o6d3hrzNqVI&t=248s) -* [NoCodeClarity - Parte 2 sobre el plugin](https://www.youtube.com/watch?v=0rzMdsrRg80) -* [Adelanto del template de la billetera No Code de Stacks](https://www.youtube.com/watch?v=Xe6Yv0rF6XM) \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md b/i18n/es/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md deleted file mode 100644 index dfbc975446..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Autenticación -description: Registrar e iniciar sesión de usuarios con identidades en la blockchain de Stacks ---- - -## Introducción - -Esta guía explica cómo se realiza la autenticación en el blockchain de Stacks. - -La autenticación proporciona una forma para que los usuarios se identifiquen a sí mismos en una aplicación mientras conservan el control total sobre sus credenciales y datos personales. Puede integrarse solo o utilizarse en conjunto con [la firma de transacciones](https://docs.hiro.so/get-started/transactions#signature-and-verification) y [el almacenamiento de datos](https://docs.stacks.co/gaia/overview), para lo cual es un requisito previo. - -Los usuarios que se registren en su aplicación pueden autenticarse posteriormente en cualquier otra aplicación con soporte para el [Blockchain Naming System (BNS)](bns) y viceversa. - -## Cómo funciona - -El flujo de autenticación con Stacks es similar al típico flujo cliente-servidor utilizado por los servicios de registro centralizado (por ejemplo, OAuth). Sin embargo, con Stacks el flujo de autentificación ocurre enteramente del lado del cliente. - -La aplicación almacena la clave de tránsito efímera durante la generación de solicitudes. La parte pública de la clave de tránsito se pasa en el token `authRequest`. El autenticador utiliza la porción pública de la clave para cifrar una _clave privada de la aplicación_ que se devuelve a través del `authResponse`. - -Estos tokens están basados en [un estándar JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) con soporte adicional para la curva `secp256k1` utilizada por Bitcoin y muchas otras criptomonedas. Se pasan a través de URL query strings. - -Cuando un usuario elige autenticar una aplicación, envía el token `authRequest` al autenticador a través de una URL query string con un parámetro igualmente nombrado: - -`https://wallet.hiro.so/...?authRequest=j902120cn829n1jnvoa...` - -Cuando el autenticador recibe la solicitud, genera un token `authResponse` para la aplicación usando una _clave de tránsito efímera_. La clave de tránsito efímera solo se utiliza para la instancia particular de la aplicación, en este caso, para firmar el `authRequest`. - -La aplicación almacena la clave de tránsito efímera durante la generación de solicitudes. La aplicación solicitante envía al autenticador un token `authRequest`. El autenticador utiliza la porción pública de la clave para cifrar una _clave privada de la aplicación_ que se devuelve a través del `authResponse`. - -El autenticador genera la clave privada de la aplicación desde _la clave privada de la dirección de identidad_ del usuario y el dominio de la aplicación. La clave privada de la aplicación cumple tres funciones: - -1. Se utiliza para crear credenciales que dan a la aplicación acceso a un bucket de almacenamiento en el hub de Gaia del usuario -2. Se utiliza en el cifrado de extremo a extremo de los archivos almacenados para la aplicación en el almacenamiento Gaia del usuario. -3. Sirve como un secreto criptográfico que las aplicaciones pueden usar para realizar otras funciones criptográficas. - -Por último, la clave privada de la aplicación es determinista, lo que significa que siempre se generará la misma clave privada para una dirección y un dominio de Stacks determinados. - -Las dos primeras de estas funciones son particularmente relevantes para el [almacenamiento de datos con Stacks.js](https://docs.stacks.co/docs/gaia). - -## Par de Claves - -La autenticación con Stacks hace un uso extensivo de la criptografía de clave pública en general y ECDSA con la curva `secp256k1` en particular. - -Las siguientes secciones describen los tres pares de claves públicas-privadas utilizados, incluyendo cómo se generan, dónde se utilizan y a quién se revelan las claves privadas. - -### Clave privada de tránsito - -La clave privada de tránsito es una clave efímera que se utiliza para cifrar los secretos que deben pasar del autenticador a la aplicación durante el proceso de autenticación. Es generado aleatoriamente por la aplicación al principio de la respuesta de autenticación. - -La clave pública que corresponde a la clave privada de tránsito está almacenada en un único elemento array en la clave `public_keys` del token de solicitud de autenticación. El autenticador encripta datos secretos como la clave privada de la aplicación utilizando esta clave pública y lo envía de vuelta a la aplicación cuando el usuario inició sesión en la aplicación. La clave privada de tránsito firma la solicitud de autenticación de la aplicación. - -### Clave privada de la dirección de identidad - -La clave privada de la dirección de identidad se deriva de la frase del llavero del usuario y es la clave privada del nombre de usuario de Stacks que el usuario elige utilizar para iniciar sesión a la aplicación. Es un secreto propiedad del usuario y nunca deja la instancia del autenticador del usuario. - -Esta clave privada firma el token de respuesta de autenticación para una aplicación para indicar que el usuario aprueba el inicio de sesión en esa aplicación. - -### Clave privada de la App - -La clave privada de la aplicación es una clave privada específica de la aplicación que es generada a partir de la clave privada de la dirección de identidad del usuario utilizando el `domain_name` como entrada. - -La clave privada de la aplicación es compartida de forma segura con la aplicación en cada autenticación, encriptada por el autenticador con la clave pública de tránsito. Debido a que la clave de tránsito sólo se almacena en el lado del cliente esto previene un ataque man-in-the-middle en el que un servidor o proveedor de Internet podría potencialmente espiar la clave privada de la aplicación. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/build-apps/references/bns.md b/i18n/es/docusaurus-plugin-content-docs/current/build-apps/references/bns.md deleted file mode 100644 index 7969f089c5..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/build-apps/references/bns.md +++ /dev/null @@ -1,244 +0,0 @@ ---- -title: Sistema de Nombres de Blockchain -description: Vincula los nombres de usuario de Stacks al estado off-chain ---- - -Sistema de Nombres de Blockchain (BNS) es un sistema de red que vincula los nombres de usuario de Stacks al estado off-chain sin depender de ningún punto central de control. - -La V1 de la blockchain de Stacks implementó BNS a través de operaciones de nombre de primer orden. En la V2 de Stacks. BNS es implementado a través de un contrato inteligente cargado durante el bloque de génesis. - -Los nombres en BNS tienen tres propiedades: - -- **Los nombres son únicos a nivel global.** El protocolo no permite colisiones de nombres, y todos los nodos que se comportan correctamente resuelven un nombre dado al mismo estado. -- **Los nombres tienen un significado humano.** Cada nombre es elegido por su creador. -- **Los nombres tienen una propiedad sólida.** Sólo el propietario del nombre puede cambiar el estado al que se resuelve. Específicamente, un nombre es propiedad de una o varias claves privadas ECDSA. - -La blockchain de Stacks asegura que la vista del BNS de cada nodo está sincronizada para todos los demás nodos del mundo, por lo que las consultas en un nodo seran las mismas en otros nodos. Los nodos de la blockchain de Stacks permiten al propietario de un nombre enlazar hasta 40Kb de estado off-chain a su nombre, el cual será replicado a todos los demás nodos de blockchain de Stacks a través de una red P2P. - -La mayor consecuencia para los desarrolladores es que en BNS, el estado del nombre de lectura es rápido y barato, pero el estado del nombre de la escritura es lento y costoso. Esto es porque registrar y modificar nombres requiere que una o más transacciones sean enviadas a la cadena de bloques subyacente, y los nodos BNS no los procesarán hasta que estén suficientemente confirmados. Los usuarios y desarrolladores necesitan adquirir y gastar la criptomoneda solicitada (STX) para enviar transacciones BNS. - -## Motivación detrás de los sistemas de nombres - -Nos basamos en nombrar sistemas en la vida cotidiana, y ellos juegan un papel crítico en muchas aplicaciones diferentes. Por ejemplo, cuando buscas un amigo en las redes sociales, está usando el sistema de nomenclatura de la plataforma para asociar su nombre a su perfil. Cuando buscas un sitio web, estás utilizando el Servicio de Nombre de Dominio para asociar el nombre de host a la dirección IP de su host. Cuando revisa una rama de Git, está usando su cliente Git para asociar el nombre de la rama a un commit hash. Cuando buscamos la clave PGP de alguien en un servidor de claves, esta asociando su clave ID a su clave pública. - -¿Qué tipo de cosas queremos que sean ciertas sobre los nombres? En BNS, los nombres son únicos globalmente, tienen significado humano y tienen una propiedad sólida. En BNS, los nombres son únicos globalmente, tienen significado humano y tienen una propiedad sólida. Sin embargo, si observas estos ejemplos, verás que cada uno de ellos solo garantiza _dos_ de estas propiedades. Esto limita lo útiles que pueden ser. - -- En DNS y redes sociales, los nombres son globalmente únicos y legibles, pero no tienen una propiedad sólida. El operador del sistema tiene la última palabra sobre a qué se asocia cada nombre. - - - **Problema**: Los clientes deben confiar en el sistema para hacer la elección correcta en cuanto a la asociación de un nombre determinado. Esto incluye confiar en que nadie más que los administradores del sistema pueden hacer estos cambios. - -- En Git, los nombres de ramas son legibles para el ser humano y tienen una propiedad sólida, pero no son únicos globalmente. Dos nodos Git diferentes pueden asociar el mismo nombre de rama a diferentes estados no relacionados del repositorio. - - - **Problema**: Dado que los nombres pueden referirse a estados conflictivos, los desarrolladores tienen que averiguar algún otro mecanismo para resolver ambigüedades. En el caso de Git, el usuario tiene que intervenir manualmente. - -- En PGP, los nombres son identificadores de clave. Son globalmente únicos y criptográficamente propios, pero no legibles por el ser humano. Los IDs de claves PGP se derivan de las claves a las que hacen referencia. - - **Problema**: Estos nombres son difíciles de recordar para la mayoría de los usuarios ya que no llevan información semántica relacionada con su uso en el sistema. - -Los nombres de BNS tienen las tres propiedades, y ninguno de estos problemas. Esto hace que sea una herramienta potente para construir todo tipo de aplicaciones de red. Con BNS, podemos hacer lo siguiente y más: - -- Construir servicios de nombre de dominios donde los nombres de host no puedan ser secuestrados. -- Construir plataformas de redes sociales donde los nombres de usuario no puedan ser robados por phishers. -- Construir sistemas de control de versiones donde las ramas del repositorio no entren en conflicto. -- Construir infraestructura de llaves públicas donde sea sencillo para los usuarios descubrir y recordar las claves de los demás. - -## Organización de los BNS - -Los nombres de BNS están organizados en una jerarquía de nombres global. Hay tres capas diferentes en esta jerarquía relacionadas con el nombramiento: - -- **Namespaces**. Estos son los nombres de nivel superior en la jerarquía. Una analogía con los namespaces de BNS son los DNS de dominios de nivel superior. Los namespaces de BNS existentes incluyen `.id`, `.podcast`, and `.helloworld`. Todos los otros nombres pertenecen exactamente a un namespace. Cualquiera puede crear un namespace, pero para que un namespace sea persistente, debe ser _publicado_ para que cualquiera pueda registrar nombres en él. Namespaces no son propiedad de sus creadores. - -- **Nombres BNS**. Son nombres cuyos registros se almacenan directamente en la blockchain. La propiedad y estado de estos nombres están controlados por el envío de transacciones de blockchain. Algunos ejemplos de nombres son `verified.podcast` and `muneeb.id`. Cualquiera puede crear un Nombre BNS, siempre y cuando el namespace que lo contenga ya exista. - -- **Subdominios BNS**. Estos son nombres cuyos registros se almacenan off-chain, pero están colectivamente anclados a la blockchain. La propiedad y el estado de estos nombres viven dentro de los datos de la red P2P. Mientras que los subdominios de BNS son propiedad de claves privadas separadas, el propietario de un nombre BNS debe difundir el estado de su subdominio. Algunos ejemplos de subdominios son `jude.personal.id` and `podsaveamerica.verified.podcast`. A diferencia de los namespace y los nombres de BNS, el estado de los subdominios BNS _no es_ parte de las reglas de consenso de la blockchain. - -Una matriz de comparación de características que resume las similitudes y diferencias entre estos objetos de nombre se presenta a continuación: - -| Características | **Namespaces** | **Nombres BNS** | **Subdominios BNS** | -| ------------------------------------------------ | -------------- | --------------- | ------------------- | -| Único a nivel global | X | X | X | -| Significado humano | X | X | X | -| Propiedad de una clave privada | | X | X | -| Cualquiera puede crearla | X | X | [1] | -| El propietario puede actualizar | | X | [1] | -| Estado alojado on-chain | X | X | | -| Estado alojado off-chain | | X | X | -| Comportamiento controlado por reglas de consenso | X | X | | -| Puede tener una fecha de vencimiento | | X | | - -[1] Requiere la cooperación de un propietario de nombre BNS para emitir sus transacciones - -## Namespaces - -Los namespaces son los objetos de nombre de nivel superior en BNS. - -Controlan algunas propiedades de los nombres que contienen: - -- Qué tan caros son para registrarse -- Cuánto tiempo duran antes de que tengan que renovarse -- Quién (si hay alguien) recibe las tarifas de registro del nombre -- Quien tiene permitido crear el namespace con sus nombres iniciales. - -En el momento de escribir este artículo, el namespace de BNS más grande es el `.id`. Los nombres en el namespace `.id` están diseñados para resolver identidades de usuario. Los nombres cortos en `.id` son más caros que los nombres largos, y tienen que ser renovados por sus propietarios cada dos años. Las tarifas de registro de nombres no son pagadas a nadie en particular---en su lugar son enviadas a un "agujero negro" donde no se pueden gastar (la intención es desalentar a los ocupantes de ID). - -A diferencia del DNS, _cualquiera_ puede crear un namespace y establecer sus propiedades. Los namespaces se crean por orden de llegada, y una vez creados, duran para siempre. - -Sin embargo, crear un namespace no es gratis. El creador del namespace debe _quemar la criptomoneda_ para hacerlo. Cuanto más corto sea el espacio de nombres, más criptomoneda debe ser quemado (es decir, los namespace cortos son más valiosos que los namespace largos). Por ejemplo, le cuesta a Blockstack PBC 40 BTC crear el namespace `.id` en 2015 (en la transacción `5f00b8e609821edd6f3369ee4ee86e03ea34b890e242236cdb66ef6c9c6a1b281`). - -Los namespace pueden tener entre 1 y 19 caracteres de longitud y están compuestos por los caracteres `a-z`, `0-9`, `-`, y `_`. - -## Subdominios - -Los nombres de BNS tienen una propiedad sólida porque el propietario de su clave privada puede generar transacciones válidas que que actualizan el hash y el propietario de su archivo de zona. Sin embargo, esto tiene el coste de de exigir al propietario del nombre que pague por la transacción subyacente en la blockchain. Además, este enfoque limita la tasa de registros y operaciones de nombres BNS y operaciones al ancho de banda de las transacciones de la blockchain subyacente. - -BNS supera esto con los subdominios. A **BNS subdomain** is a type of BNS name whose state and owner are stored outside of the blockchain, but whose existence and operation history are anchored to the blockchain. Al igual que sus contrapartes on-chain, los subdominios son globalmente únicos, tienen una propiedad sólida y son legibles por el ser humano. BNS les da su propio estado de nombre y claves públicas. A diferencia de los nombres on-chain, los subdominios pueden ser creados y gestionados económicamente, porque son emitidos a la red de BNS en lotes. Una sola transacción de la blockchain puede enviar hasta 120 operaciones de subdominio. - -Esto se logra almacenando registros de subdominios en los archivos de zona de nombres de BNS. An on-chain name owner broadcasts subdomain operations by encoding them as `TXT` records within a DNS zone file. Para transmitir el archivo de zonas, el propietario del nombre establece el nuevo hash del archivo de zona con una transacción de `NAME_UPDATE` y replica el archivo de zona. Esto, a su vez, replica todas las operaciones del subdominio que contiene, y ancla el conjunto de operaciones de subdominio a una transacción on-chain. Las reglas de consenso del nodo BNS aseguran que solo operaciones de subdominio válidas de transacciones _validas_ de `NAME_UPDATE` sean almacenadas. - -Por ejemplo, el nombre `verified.podcast` una vez escribió el hash del archivo de zona `247121450ca0e9af45e85a82e61cd525cd7ba023`, que es el hash del siguiente archivo de zona: - -```bash -$TTL 3600 -1yeardaily TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxeWVhcmRhaWx5CiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMXllYXJkYWlseS9oZWFkLmpzb24iCg==" -2dopequeens TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAyZG9wZXF1ZWVucwokVFRMIDM2MDAKX2h0dHAuX3RjcCBVUkkgMTAgMSAiaHR0cHM6Ly9waC5kb3Rwb2RjYXN0LmNvLzJkb3BlcXVlZW5zL2hlYWQuanNvbiIK" -10happier TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxMGhhcHBpZXIKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8xMGhhcHBpZXIvaGVhZC5qc29uIgo=" -31thoughts TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzMXRob3VnaHRzCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzF0aG91Z2h0cy9oZWFkLmpzb24iCg==" -359 TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzNTkKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8zNTkvaGVhZC5qc29uIgo=" -30for30 TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzMGZvcjMwCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzBmb3IzMC9oZWFkLmpzb24iCg==" -onea TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiBvbmVhCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vb25lYS9oZWFkLmpzb24iCg==" -10minuteteacher TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxMG1pbnV0ZXRlYWNoZXIKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8xMG1pbnV0ZXRlYWNoZXIvaGVhZC5qc29uIgo=" -36questionsthepodcastmusical TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzNnF1ZXN0aW9uc3RoZXBvZGNhc3RtdXNpY2FsCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzZxdWVzdGlvbnN0aGVwb2RjYXN0bXVzaWNhbC9oZWFkLmpzb24iCg==" -_http._tcp URI 10 1 "https://dotpodcast.co/" -``` - -Cada registro `TXT` en este archivo de zona codifica una creación de subdominio. Por ejemplo, `1yeardaily.verified.podcast` resuelve a: - -```json -{ - "address": "1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH", - "blockchain": "bitcoin", - "last_txid": "d87a22ebab3455b7399bfef8a41791935f94bc97aee55967edd5a87f22cce339", - "status": "registered_subdomain", - "zonefile_hash": "e7acc97fd42c48ed94fd4d41f674eddbee5557e3", - "zonefile_txt": "$ORIGIN 1yeardaily\n$TTL 3600\n_http._tcp URI 10 1 \"https://ph.dotpodcast.co/1yeardaily/head.json\"\n" -} -``` - -Esta información fue extraída del `1yeardaily` `TXT` en el archivo de la zona para `verified.podcast`. - -### Ciclo de vida del subdominio - -Ten en cuenta que `1yeardaily.verified.podcast` tiene un hash de clave pública diferente (dirección) que `verified.podcast`. Un nodo BNS sólo procesará una operación de subdominio posterior en `1yeardaily.verified.podcast` si incluye una firma de la clave privada de esta dirección. `verified.podcast` no puede generar actualizaciones; sólo el propietario de `1yeardaily.verified.podcast` puede hacerlo. - -El ciclo de vida de un subdominio y sus operaciones se muestran en la Figura 2. - -``` - creación de Actualización de Transferencia de - Subdominio Subdominio Subdominio -+----------------+ +----------------+ +----------------+ -| cicero | | cicero | | cicero | -| owner="1Et..." | firmado | owner="1Et..." | firmado | owner="1cJ..." | -| zf0="7e4..." |<--------| zf0="111..." |<--------| zf0="111..." |<---- ... -| seqn=0 | | seqn=1 | | seqn=2 | -| | | sig="xxxx" | | sig="xxxx" | -+----------------+ +----------------+ +----------------+ - | | | - | off-chain | | -~ ~ ~ ~ | ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~|~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ | ~ ~ ~ ~ ~ ~ ~ ... - | on-chain | | - V V (hash de V - archivo de zona ) -+----------------+ +----------------+ +----------------+ -| res_publica.id | | jude.id | | res_publica.id | -| NAME_UPDATE |<--------| NAME_UPDATE |<--------| NAME_UPDATE |<---- ... -+----------------+ +----------------+ +----------------+ - blockchain blockchain blockchain - block block block - - -Figura 2: Vida útil del subdominio con respecto a las operaciones de nombre on-chain. Una nueva -operación de subdominio solo será aceptada si tiene un número posterior de "sequence=" -y una firma válida en "sig=" sobre el cuerpo de la transacción. El campo "sig=" -incluye tanto la clave pública como la firma, y la clave pública debe tener un hash con el campo -"addr=" de la operación de subdominio anterior. - -Las transacciones de creación de subdominio y transferencia de subdominio para -"cicero.res_publica.id" son emitidas por el propietario de "res_publica.id" -Las transacciones de creación de subdominio y transferencia de subdominio para -"cicero.res_publica.id" son emitidas por el propietario de "res_publica.id" -Sin embargo, cualquier nombre on-chain ("jude.id" en este caso) puede transmitir una actualización de subdominio -para "cicero.res_publica.id." -``` - -Las operaciones de subdominios se ordenan por número de secuencia, comenzando en 0. Cada nueva operación de subdominio debe incluir: - -- El siguiente número de secuencia -- La clave pública que tiene el hash de la dirección de la transacción del subdominio anterior -- Una firma de la clave privada correspondiente sobre toda la operación del subdominio. - -Si se descubren dos operaciones de subdominio correctamente firmadas pero en conflicto (es decir, tienen el mismo número de secuencia), se acepta el que ocurre antes en el historial de blockchain. Las operaciones de subdominio no válidas son ignoradas. - -Combinado, esto garantiza que un nodo BNS con todos los archivos de zona con las operaciones de un subdominio determinado será capaz de determinar la secuencia válida de transiciones de estado por la que ha pasado, y determinar el archivo de zona actual y el hash de la clave pública del subdominio. - -### Creación y gestión de subdominios - -A diferencia de un nombre on-chain, un propietario de subdominio necesita la ayuda del propietario del nombre on-chain para transmitir sus operaciones de subdominio. En particular: - -- Una transacción de creación de subdominios solo puede ser procesada por el propietario del nombre on-chain que comparte su sufijo. Por ejemplo, solo el dueño de `res_publica.id` puede transmitir transacciones de creación de subdominios para nombres de subdominio que terminan en `.res_publica.id`. -- Una transacción de transferencia de subdominio sólo puede ser emitida por el propietario del nombre on-chain que la creó. Por ejemplo, el dueño de `cicero.res_publica.id` necesita al dueño de `res_publica.id` para transmitir una transacción de transferencia de subdominio para cambiar la clave pública `cicero.res_publica.id`. -- Para enviar una creación de subdominio o transferencia de subdominio, todos los archivos de zona del propietario del nombre on-chain deben estar presentes en la red de Atlas. Esto permite al nodo BNS demostrar la _ausencia_ de cualquier operación conflictiva de creación y operaciones de transferencia de subdominios al procesar nuevos archivos de zona. -- A subdomain update transaction can be broadcast by _any_ on-chain name owner, but the subdomain owner needs to find one who will cooperate. Por ejemplo, el dueño de `verified.podcast` puede transmitir una transacción de actualización de subdominio creada por el dueño de `cicero.res_publica.id`. - -Dicho esto, para crear un subdominio, el dueño del subdominio genera una operación de creación de subdominios para el nombre deseado y lo otorhga al propietario del nombre on-chain. - -Una vez creado, un propietario de subdominio puede usar cualquier propietario de nombre on-chain para transmitir una operación de actualización de subdominios. Para hacerlo, generan y firman la operación de subdominio solicitada y se la dan a un propietario de nombre on-chain, quien luego lo empaqueta con otras operaciones de subdominio en un archivo de zona DNS y lo transmite a la red. - -Si el propietario del subdominio quiere cambiar la dirección de su subdominio, necesita firmar una operación de transferencia de subdominio y dársela al propietario del nombre on-chain que creó el subdominio. Luego lo empaquetan en un archivo de zona y lo transmiten. - -### Registros de subdominio - -Because subdomain names are cheap, developers may be inclined to run subdomain registrars on behalf of their applications. For example, the name `personal.id` is used to register usernames without requiring them to spend any Bitcoin. - -We supply a reference implementation of a [BNS Subdomain Registrar](https://github.com/stacks-network/subdomain-registrar) to help developers broadcast subdomain operations. Users would still own their subdomain names; the registrar simply gives developers a convenient way for them to register and manage them in the context of a particular application. - -# Estándares BNS y DID - -Los nombres de BNS son compatibles con el emergente protocolo de especificación para identificadores descentralizados (DIDs) [Fundación de la Identidad Descentralizada](http://identity. foundation). - -Cada nombre en BNS tiene un DID asociado. El formato DID para BNS es: - -```bash - did:stack:v0:{address}-{index} -``` - -Dónde: - -- `{address}` es un hash de clave pública on-chain (por ejemplo una dirección de Bitcoin). -- `{index}` se refiere al nombre `nth` esta dirección creada. - -Por ejemplo, el DID para `personal.id` es `did:stack:v0:1dARRtzHPAFRNE7Yup2Md9w18XEQAtLiV-0`, porque el nombre `personal.id` fue el primer nombre creado por `1dARRtzHPAFRNE7Yup2Md9w18XEQAtLiV`. - -Otro ejemplo, el DID para `jude.id` es `did:stack:v0:16EMaNw3pkn3v6f2BgnSs53zAKH4Q8YJg-1`. Aquí, la dirección `16EMaNw3pkn3v6f2BgnSs53zAKH4Q8YJg` había creado un nombre anterior históricamente anterior a esta (que parece ser `abcdefgh123456.id`). - -El propósito de un DID es proporcionar un identificador eterno para una clave pública. La clave pública puede cambiar, pero el DID no. - -La blockchain de Stacks implementa un método DID propio para ser compatible con otros sistemas que usan DIDs para la resolución de clave pública. In order for a DID to be resolvable, all of the following must be true for a name: - -- El nombre debe existir -- El hash del archivo de zona del nombre debe ser el hash de un archivo de zona DNS bien formado -- El archivo de zona DNS debe estar presente en los datos del nodo de Stacks. -- El archivo de zona DNS debe contener un registro de recursos de `URI` que apunta a un JSON Web Token firmado -- La clave pública que firmó el JSON Web Token (y está incluida con él) debe hacer hash a la dirección que posee el nombre - -No todos los nombres tendrán DIDs que resuelvan claves públicas. Sin embargo, los nombres creados por herramientas estándar sí que tendrán DIDs. - -Una API RESTful está en desarrollo. - -## Codificación DID para subdominios - -Cada nombre y subdominio en BNS tiene un DID. La codificación es ligeramente diferente para los subdominios, por lo que el software puede determinar qué code-path tomar. - -- Para nombres BNS on-chain, la `{address}` es la misma que la dirección Bitcoin que posee el nombre. Actualmente, las dirección tanto del byte de la versión 0 como del byte de la versión 5 son soportadas (es decir, direcciones que empiezan con `1` o `3`, significando `p2pkh` y `p2sh` direcciones). - -- Para subdominios BNS off-chain, el `{address}` tiene la versión del byte 63 para subdominios propiedad de una sola clave privada, y la versión 50 del byte para subdominios propiedad de un conjunto m-of-n de claves privadas. Es decir, las direcciones DID de subdominio comienzan con `S` o `M`, respectivamente. - -El campo `{index}` para el DID de un subdominio es distinto del campo `{index}` para el DID de un nombre BNS, incluso si el mismo creó nombres y subdominios. Por ejemplo, el nombre `abcdefgh123456. d` tiene el DID `did:stack:v0:16EMaNw3pkn3v6f2BgnSs53zAKH4Q8YJg-0`, porque era el primer nombre creado por `16EMaNw3pkn3v6f2BgnSs53zAKH4Q8YJg`. Sin embargo, `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` _también_ creó `jude.statism.id` como su primer nombre de subdominio. El DID para `jude.statism.id` es `did:stack:v0:SSXMcDiCZ7yFSQSUj7mWzmDcdwYhq97p2i-0`. Tenga en cuenta que la dirección `SSXMcDiCZ7yFSQSUj7mWzmDcdwYhq97p2i`codifica el mismo hash de clave pública que la dirección `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` (la única diferencia entre estos dos strings es que la primera está codificada en base58checkcon la versión byte 0, y el segundo está codificado con la versión byte 63). diff --git a/i18n/es/docusaurus-plugin-content-docs/current/build-apps/references/references.md b/i18n/es/docusaurus-plugin-content-docs/current/build-apps/references/references.md deleted file mode 100644 index cafc2bebd1..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/build-apps/references/references.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Referencias -sidebar_label: Referencias ---- - -[Autenticación](./authentication) - -[Blockchain Naming System](./bns) - -[Ejemplo de aplicaciones en Hiro](https://docs.hiro.so/example-apps) \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/current/contribute/docs.md b/i18n/es/docusaurus-plugin-content-docs/current/contribute/docs.md deleted file mode 100644 index d28e84d26c..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/contribute/docs.md +++ /dev/null @@ -1,207 +0,0 @@ ---- -title: Contribuir a la documentación -description: Aprende cómo se construye este sitio y cómo puedes contribuir a él. ---- - -## Introducción - -Gracias por su interés en contribuir y ayudar a que estos documentos sean tan buenos como puedan ser. - -Este sitio de documentación está construido en la plataforma de código abierto [Discosaurus 2](https://docusaurus.io/) y la mayor parte de su contenido está escrito en archivos Markdown. Todo el código para este sitio es libre y de código abierto, ubicado en el [repositorio de GitHub aquí](https://github.com/stacks-network/docs). - -:::tip ¿No sabes qué es Markdown? ¿Quieres aprender? Aquí hay una [guía útil](https://guides.github.com/features/mastering-markdown/) para aprenderlo. - -¿No quieres aprenderlo? No es necesario. Escribe [en texto plano una observaciòn en Github](https://github.com/stacks-network/docs/issues/new?assignees=&labels=documentation&template=add-documentation.md&title=%5BAdd+docs%5D)::: - -:::info Necesitas una cuenta gratuita en [GitHub](https://www.github.com) para añadir o editar cualquier contenido. ::: - -Para editar cualquier página, solo haga clic en el botón *Editar esta página* en la parte inferior de cada página y envíe sus cambios en línea. - -Para añadir nuevo contenido, existen dos formas diferentes de hacerlo, la [forma fácil](#easy-way) y la [forma avanzada](#advanced-way). - -## Forma fácil - -[**Simplemente haga clic aquí e ingrese el texto del artículo que desea añadir.**](https://github.com/stacks-network/docs/issues/new?assignees=&labels=documentation&template=add-documentation.md&title=%5BAdd+docs%5D) - -Esto abrirá una observación en github usando nuestra plantilla. -## Forma avanzada - -Para cambios más avanzados puede seguir los siguientes pasos. - -También puede probar el sitio localmente utilizando este método. -### Pasos - -1. Haga un Fork del [repositorio de documentos](https://github.com/stacks-network/docs) haciendo clic en el botón *Fork* en la parte superior derecha de la pantalla. -2. Clona el fork a tu máquina local con este comando `git clone git@github.com:/docs.git stacks_docs` -3. Entre a la carpeta del proyecto `cd stacks_docs` -4. Crea una rama `git checkout -b feat/my-feature-branch`. -5. Opcionalmente puede previsualizar sus cambios en tiempo real con: - - `npm install` (para instalar dependencias). - - `npx docusaurus start` para iniciar una copia local del sitio. Un navegador web se abrirá en http://localhost:3000, para que pueda ver una vista previa de sus cambios en tiempo real. -6. Haga los cambios que desee y luego haga un commit con este tipo de mensaje: `git commit -am "feat: some new feature or content"`. -7. Haga Push a Github con `git push --set-upstream origin feature/my-feature-branch`. -8. Visite GitHub y haga su pull request. - -## Información adicional -### Ejecutando y construyendo el sitio en local (opcional) - -Puedes iniciar la página en local con el siguiente comando. Esto es suficiente para previsualizar tus cambios. -```bash -npx docusaurus start -``` - -Antes de ejecutar este comando por primera vez, debes de ejecutar `npm install` para instalar las dependencias. - -La página de docs será accesible en la siguiente url: [`http://localhost:3000`](http://localhost:3000). - - -Una vez finalizados los cambios, puedes construir un site entero con el siguiente comando (normalmente no es necesario): -```bash -npm run build -``` - -:::consejo `npx docusaurus start` solo se carga la lengua por defecto (inglés). Para testear todos los lenguajes puedes crear una versión con `npm run build` y luego previsualizarla con `npm run serve`. ::: - -### Una alternativa: trabajar en el navegador - -Como alternativa a trabajar en local, también puedes usar el IDE web gitpod que porvee un entorno para contrubuir directamente desde tu navegador. - -Solo necesitas un cuenta de GitHub y abrir [este link](https://gitpod.io/#https://github.com/stacks-network/docs). - -### Estructura de los ficheros - -Si te interesa añadir nuevo contenido de documentación en este sitio, los ficheros que relevantes están en `./docs/*`: - -```bash -docs/ - build-apps - contribute/ - faq/ - gaia/ - nodes-and-miners/ - noteworthy-contracts/ - references/ - understand-stack/ - write-smart-contracts/ -``` - -La ruta de este sitio está basada en archivos, es decir, si creaste una carpeta dentro de `/docs/gaia/` nombrada `testing` y en ella un archivo llamado `test1. d`, podrías navegar a `http://localhost:3000/gaia/testing/test1` y verías cualquier contenido en ese archivo de markdown. - -Todos los documentos en inglés se almacenan en la carpeta `/docs/`. - -Para añadir nuevos contenidos en inglés simplemente agregue un archivo markdown (.md) en cualquier subcarpeta en docs, y se mostrará automáticamente en la categoría de esa carpeta. - -Todos los documentos en otros idiomas se almacenan bajo la carpeta `i18n`, pero estos archivos nunca deben editarse usando GitHub, ya que son sobrescritos por Crowdin cada vez que se agregan nuevas traducciones. **Para hacer cambios en otros idiomas**, debes hacerlo usando Crowdin. Por favor, consulta [traducciones](translations) en su lugar. - -### Frontmatter - -Frontmatter es la parte superior de cualquier documento markdown que esté escrito en un idioma llamado [YAML](https://yaml.org/). Se verá así: - -```yaml ---- -title: Este es mi título de página -description: Una frase breve y concisa que describe lo que está en esta página ---- -``` - -Frontmatter nos da la capacidad de definir algunas cosas dentro de una página que el sitio puede usar, como un título de página o descripción de página. Al agregar cualquier nueva página, por favor incluya un `tittle` y `description`. - - - -### Usar "Commits Convencionales" - -Utilizamos los [Commits Convencionales](https://www.conventionalcommits.org/en/v1.0.0/) y la convención de nombres de commits. Utilízalo mientras contribuyes, por favor. - -### Bloques de código - -Para escribir un bloque de código, necesitas envolver tu código en ` ```language `, y termina tu bloque de código con ` ``` `. Aquí hay un ejemplo de ` ```clarity `. - -```clarity -(define-data-var counter int 0) - -(define-public (get-counter) - (ok (var-get counter))) -``` -### Avisos - -Puede utilizar los siguientes avisos para resaltar el contenido. - -```md -:::note -Algo de **contenido** con `formato` markdown. -::: - -:::tip -Algo de **contenido** con `formato` markdown. -::: - -:::info -Algo de **contenido** con `formato` markdown. -::: - -:::caution -Algo de **contenido** con `formato` markdown. -::: - -:::danger -Algo de **contenido** con `formato` markdown. -::: - -:::tip My personalized title -Some **content** with _markdown_ `syntax`. -::: -``` - -Se visualiza como: - -:::note - -Algo de **contenido** con `syntax` markdown. - -::: - -:::tip - -Algo de **contenido** con `syntax` markdown. - -::: - -:::info - -Algo de **contenido** con `syntax` markdown. - -::: - -:::caution - -Algo de **contenido** con `syntax` markdown. - -::: - -:::danger - -Algo de **contenido** con `syntax` markdown. - -::: - -:::tip My personalized title - -Algo de **contenido** con `syntax` markdown. - -::: \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/current/contribute/index.md b/i18n/es/docusaurus-plugin-content-docs/current/contribute/index.md deleted file mode 100644 index 546582b865..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/contribute/index.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Contribuir -description: Contribuir al ecosistema de Stacks. -sidebar_position: 10 -sidebar_label: "Contribuir" ---- - -Puedes contribuir al ecosistema de Stacks de múltiples maneras: - - - -### Documentación - -Contribuye a la documentación de Stacks en este sitio web. Más información [aquí](docs). - -### Traducciones - -Ayúdanos a llegar a más personas con traducciones. Más información [aquí](translations). - - - -### Artículos - -Escribe un artículo o un post en un blog sobre Stacks. Un buen lugar para comenzar es [Foro de Stacks](https://forum.stacks.org). - -### Github - -Si estas familiarizado con Github hay varios repositorios del ecosistema de Stacks al que puedes contribuir. - -- https://github.com/stacks-network/ diff --git a/i18n/es/docusaurus-plugin-content-docs/current/contribute/translations.md b/i18n/es/docusaurus-plugin-content-docs/current/contribute/translations.md deleted file mode 100644 index 0391e7e386..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/contribute/translations.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Contribuye en la traducción -description: '¿Quieres ayudar a traducir la documentación a tu propio idioma?' ---- - -## Ayuda con las traducciones - -Las traducciones se gestionan con Crowdin. -Cualquiera puede colaborar y no se requieren habilidades técnicas, ya que todo se hace en el navegador. - -Para ayudarte con la traducción, ve a [esta página](https://crowdin.com/project/docsstacksco), haz clic en cualquier idioma y empieza a traducir. - -Toda ayuda es bienvenida. - -:::caution -Por favor, no añadas ninguna traducción al repositorio de Github, ya que las páginas traducidas son reescritas desde Crowdin. Es necesario añadir las traducciones en Crodin en vez. -::: - -### Problemas comunes en las traducciones - -Al traducir en Crowdin, por favor traduce los textos y no el código html. - -Si accidentalmente modificas las etiquetas html, obtendrás errores como los que se muestran a continuación (`Seems like some formating tags are missing` o `Translation contains tag that source text doesn't have`). Estos errores evitarán que tu traducción se publique hasta que las etiquetas se dejen como en el texto original. - -![](/img/crowdin-qa-issue-formatting_tags_missing.png) ![](/img/crowdin-qa-issue-tag_source.png) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/faq/faq.md b/i18n/es/docusaurus-plugin-content-docs/current/faq/faq.md deleted file mode 100644 index 2c82636a0b..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/faq/faq.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: Preguntas frecuentes generales -description: Preguntas frecuentes -sidebar_label: "Preguntas Frecuentes" -sidebar_position: 10 ---- - -![](/img/glasses.png) - -## ¿Por qué mi transferencia sigue pendiente? - -Comúnmente es porque la comisión es demasiado baja o el [nonce](#what-is-nonce) es incorrecto. - -Puede encontrar más información [aquí](https://www.hiro.so/wallet-faq/why-is-my-stacks-transaction-pending). También hay [buenas prácticas y problemas conocidos](https://forum. stacks. org/t/transactions-in-mempool-best-practices-and-known-issues/11659) y [diagnóstico de transacciones pendientes](https://forum. stacks. org/t/diagnosing-pending-transactions/11908). - -También existe este [script](https://github.com/citycoins/scripts/blob/main/getnetworkstatus.js) para ver las primeras 200 transacciones o todas las transacciones en el mempool, para luego devolver los valores máximos y valores promedios de las comisiones. Hemos notado que usando 1.5-2x la cuota promedio en el mempool generalmente se procesará dentro de 6-10 bloques incluso durante una congestión alta. - -También existe este [script](https://github.com/citycoins/scripts/blob/main/gettxstatus.js) para rastrear una transacción pendiente hasta que alcance un estado final. - -## ¿Qué es el Nonce? - -Un nonce se utiliza para asegurarse de que cada transacción vaya en orden correcto. Nonce comienza en 0, por lo que la primera transacción desde una dirección debe ajustarse a nonce=0. Puede encontrar el nonce de su dirección de billetera buscando la dirección en cualquier [explorador de blockchain de Stacks](https://explorer. stacks. co/). También puede usar `$ stx balance
`. - -Si usted tiene un nonce de transacción que es menor que el nonce de su cuenta, la transacción no se podrá minar y (debería) desaparecer después de 256 bloques. Esto no afecta a las transacciones futuras y, por lo tanto, puede ser simplemente ignorado, están en el pasado. - -Si tienes un nonce de transacción que es igual al nonce de tu cuenta, entonces esa transacción es válida y debe ser la siguiente en línea a ser procesada a continuación. - -Si tienes un nonce de transacción que es mayor que el nonce de tu cuenta, entonces tiene que haber una cadena de transacciones comenzando con tu nonce de cuenta para que se pueda procesar. Por ejemplo: El nonce de tu cuenta es 10 pero la transacción pendiente tiene un nonce de 12. No será posible minar hasta que las transacciones con un nonce 10 y 11 sean procesadas. - -## ¿Qué es la Sustitución por comisión (RBF)? - -Una transacción de sustitución por comisión (RBF) a le dice a la blockchain que le gustaría reemplazar una transacción por otra, mientras se especifica una comisión que es mayor que la comisión de transacción original. Una transacción puede ser reemplazada con **cualquier otra transacción**, y no está limitada a la misma operación. - -Esto puede utilizarse para **cancelar eficazmente una transacción** reemplazándola por otra cosa, como una pequeña transferencia STX a otra dirección de nuestra propiedad. - -Esto puede utilizarse para **elevar la comisión por una transacción pendiente** para que sea considerada por los mineros durante periodos de alta congestión. Esto también puede utilizarse para _volver a enviar_ una transacción, en el sentido de que la transacción RBF recibe un nuevo txid y es considerada de nuevo (o más rápido) por los mineros. Por ejemplo: Yo envío mi transacción con 1 STX de comisión en el bloque 54,123. Por bloque 54,133 veo que mi tx no ha sido recogida, así que envío un RBF con 1.1 STX. Luego espero 10 bloques de nuevo, y envío un RBF otra vez si no se recibe. Hay que encontrar el equilibrio entre hacer esto con demasiada frecuencia y mantener un ritmo constante, pero se ha visto que ayuda a concretar las transacciones, especialmente cuando las nuevas llegan constantemente. - -La transacción de reemplazo necesita usar el mismo nonce que la transacción original con un aumento de comisión de al menos 0.000001 STX. Por ejemplo: Su transacción original tiene una comisión de 0.03 STX, la nueva transacción RBF debe tener una comisión de 0.030001 STX o superior. - -Las transacciones RBF se procesan de dos maneras: - -- Si los mineros escogen la transacción original antes de que la transacción RBF sea recibida, entonces la transacción original se procesa y la transacción de reemplazo pasa a un estado de no minable. Con el tiempo desaparecerá y no afectará a las transacciones futuras. -- Si los mineros recogen la transacción reemplazada entonces la nueva transacción se procesa en lugar del original, y el estado de la transacción original se establece en “droppped_replaced_by_fee”. Este estado no se muestra en el explorador pero puede verse al consultar el txid. - -Enviar múltiples transacciones para la misma acción puede ralentizar las cosas de varias maneras. - -- Si el total gastado en 2 o 3 transacciones es más de lo que se puede gastar en una sola transacción, las transacciones aparecen como no minables. -- Si las comisiones de las transacciones múltiples superan el saldo de STX, las transacciones serán no minables. - -## ¿Qué son los dominios .btc? - -[Esta publicación del foro](https://forum.stacks.org/t/btc-domains-are-live/12065) explica todos los beneficios de los dominios .btc. Actualmente se pueden comprar en [btc.us](https://btc.us/) - -## ¿Cuál es el trilema del blockchain? - -## Stacks vs. Solana vs. Polygon: ¿Cómo se comparan desde la perspectiva de un desarrollador? - -[Esta tema del blog responde a la pregunta](https://www.hiro.so/blog/stacks-vs-solana-vs-polygon-how-do-they-compare-from-a-developer-perspective). - -## ¿Qué significa la propuesta de Taro de Lightning para Stacks? - -[Esta tema del blog responde a la pregunta](https://www.hiro.so/blog/what-does-lightnings-taro-proposal-mean-for-stacks). - - -## ¿Es Stacks una [cadena PoS](https://en.wikipedia.org/wiki/Proof_of_stake)?[¹][] - -No. - -El acto de producción de bloques requiere un gasto extrínseco — no está vinculado a poseer el token nativo, como sería necesario en PoS. La única forma de producir bloques en la cadena de Stacks es transferir Bitcoin a una lista predeterminada aleatorizada de direcciones de Bitcoin. Además, la blockchain de Stacks puede bifurcarse, y existe un protocolo para clasificar las bifurcaciones según su calidad, independientemente del conjunto de mineros y de los tokens que posean. Estas dos propiedades lo distinguen aún más de las cadenas PoS, que no puede bifurcarse debido a la incapacidad de identificar un fork canónico sin confiar en que un tercero decrete un fork en particular como válido. La capacidad de bifurcarse permite que la blockchain de Stacks sobreviva a modos de fallo que harían colapsar una cadena PoS. - -## ¿Es Stacks una [cadena lateral o sidechain](https://en.bitcoin.it/wiki/Sidechain)?[¹][] - -No. - -Por dos razones fundamentales. - -Primero, el historial de todos los bloques de Stacks producidos se registra en Bitcoin. Esto significa que el acto de producir una bifurcación privada de Stacks es al menos tan duro como reordenar la cadena de Bitcoin. Esto a su vez hace que los ataques a la cadena que dependen de la creación de bifurcaciones privadas (como la minería egoísta y el doble gasto) sean mucho más difíciles de llevar a cabo de manera rentable, ya que todos los participantes honrados pueden ver el ataque antes de que ocurra y tener la oportunidad de aplicar contramedidas. Las cadenas laterales no ofrecen tal beneficio de seguridad. - -En segundo lugar, la blockchain de Stacks tiene su propio token; no vinculado a Bitcoin. Esto significa que la seguridad de la bifurcación canónica de la blockchain de Stacks está respaldada por el valor de toda su economía de tokens, mientras que la seguridad de la bifurcación canónica de una sidechain está respaldada únicamente por cualquier medida específica del sistema que incentive a sus validadores a producir bloques de forma honesta, o por la voluntad de los mineros de Bitcoin de procesar las solicitudes de peg-in (cualquiera que sea la garantía más débil). - - -## Es Stacks un [sistema de capa 2](https://academy.binance.com/en/glossary/layer-2) para Bitcoin?[¹][] - -No. - -La blockchain de Stacks es una cadena de bloques de capa 1, que utiliza un nuevo y único protocolo de minado llamado prueba de transferencia (PoX). Una blockchain de PoX corre en paralelo a otra blockchain (Bitcoin en caso de Stacks), la que utiliza como un medio de emisión fiable para sus cabeceras de bloque. Es un sistema soberano por derecho propio. El estado de la blockchain de Stacks es distinto de Bitcoin, y es totalmente mantenido por y para los nodos de Stacks. Las transacciones de Stacks están separadas de las transacciones de Bitcoin. Los sistemas de Capa 2 como Lightning están diseñados para ayudar a escalar las transacciones de pago de Bitcoin, mientras que Stacks está diseñado para llevar nuevos casos de uso a Bitcoin a través de contratos inteligentes. Stacks no está diseñada como una solución de escalabilidad de capa 2 de Bitcoin. - - -## ¿Es Stacks una [cadena de minería combinada](https://en.bitcoin.it/wiki/Merged_mining_specification)?[¹][] - -No. - -Los únicos productores de bloques en la cadena de Stacks son los mineros de Stacks. Los mineros de bitcoin no participan en la validación de bloques de Stacks y no reclaman recompensas de bloques de Stacks. Además, Stacks no es una [cadena de minado ciego](https://github.com/bitcoin/bips/blob/master/bip-0301.mediawiki), porque los ganadores de los bloques de STX son públicos y se eligen aleatoriamente (en lugar de los que ganan con la oferta más alta), y sus tokens se acuñan de acuerdo con un calendario que es independiente del grado de compromiso de los mineros o de los Bitcoin transferidos (en lugar de acuñarse sólo por medio de los pegs unidireccionales de los Bitcoin). Esto asegura que Stacks es capaz de avanzar sin la participación de los mineros de Bitcoin, y asegura que los mineros de Stacks son compensados adecuadamente por mantener el sistema vivo independientemente del volumen de transacciones. - -## ¿Cuál es la diferencia entre Stacks y Ethereum?[2][] -**Cálculo y almacenamiento** Stacks hace todo el cálculo y almacenamiento fuera de la blockchain, y utiliza el blockchain sólo como una “fuente compartida de verdad” entre clientes. Por el contrario, Ethereum hace todo el cálculo y la mayor parte del almacenamiento de aplicaciones en la propia blockchain. Como Ethereum, si dos nodos Stacks ven la misma blockchain subyacente, ejecutarán independientemente los mismos cálculos y producirán el mismo estado. A diferencia de Ethereum, no existe un blockchain específico para Stacks. - -**Lenguaje de programación y herramientas** El modelo de programación de Stacks se basa en ejecutar programas off-chain. Estos programas se pueden escribir y depurar en el lenguaje que se desee. Por el contrario, el modelo de programación de Ethereum se basa en la ejecución on-chain de “contratos inteligentes” Estos son escritos y depurados con todo un nuevo conjunto de herramientas, como Solidity y Serpent. - -**Escalabilidad de la computación on-chain** Stacks esta diseñado alrededor de un concepto de "cadena virtual", donde los nodos sólo necesitan alcanzar un consenso sobre la “cadena virtual” compartida en la que están interesados. Las cadenas virtuales no interactúan entre sí, y una sola blockchain puede albergar muchas cadenas virtuales. Aunque la cadena virtual específica de Stacks no es Turing completo (i.e. es una lista de instrucciones para construir la base de datos de nombres), es posible crear cadenas virtuales Turing completas como Ethereum. Estas cadenas virtuales pueden vivir en cualquier blockchain para el cual exista un driver, y los clientes de cadenas virtuales sólo necesitan ejecutar sus transacciones en cadena virtual (i.e. Stacks sólo procesan las transacciones en la cadena virtual de Stacks). - -Por el contrario, debido a que los contratos inteligentes funcionan en cadena y pueden llamarse unos a otros, todos los nodos Ethereum necesitan procesar todos los cálculos de los contratos inteligentes para llegar a un consenso. Esto puede resultar caro a medida que aumenta el número de contratos inteligentes en funcionamiento, lo que adopta la forma de aumento de la tasa del gas. - -**Escalabilidad de la computación Off-chain** Las aplicaciones Stacks son muy similares a las aplicaciones Web hoy en día y casi nunca necesitan interactuar con la blockchain. Para la mayoría de las aplicaciones de Stacks, la blockchain sólo se utiliza para autenticar el código y los datos de la aplicación antes de que el usuario lo ejecute. Por el contrario, las aplicaciones de Ethereum generalmente requieren un contrato inteligente específico de la aplicación, y deben interactuar con la blockchain para llevar a cabo sus operaciones. - - -[¹]: https://stacks.org/stacks-blockchain -[2]: https://forum.stacks.org/t/what-is-the-difference-between-blockstack-and-ethereum/781 diff --git a/i18n/es/docusaurus-plugin-content-docs/current/gaia/configuration.md b/i18n/es/docusaurus-plugin-content-docs/current/gaia/configuration.md deleted file mode 100644 index d5569bc8f0..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/gaia/configuration.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Configuración -description: Configurando Gaia Hub ---- - -## Archivos de configuración - -Los siguientes archivos de configuración existen en la carpeta `deploy/configs/gaia/`: - -``` -admin-config.json -hub-config.json -reader-config.json -``` - -## Servicio de administración de GAIA - -También puede utilizar el servicio de administración de GAIA para administrarlo de forma remota con un API Key. Requerirá instalar `npm` con una `apt install npm`. Una vez que `npm` esté instalado, puede continuar con los pasos en el [Servicio de administración de GAIA](https://github.com/stacks-network/gaia/blob/master/admin/README.md). - -## Selección de Controlador - -El centro de Gaia actualmente soporta los siguientes controladores: - -``` -'aws' == Amazon S3 -'azure' == Azure Blob Storage -'disco' == Disco local -'google-cloud' === Google Cloud Storage -``` - -Establezca el controlador que desea utilizar en el archivo [config.json](https://github.com/stacks-network/gaia/blob/master/hub/config.sample.json) con el parámetro `driver`. Muchos controladores aceptan adicionalmente el parámetro `bucket`, que controla el nombre del cubo en el que deben escribirse los archivos. - -Estos controladores pueden requerir que proporcione credenciales adicionales para realizar escrituras en los backends. Vea `config.sample.json` para ver los campos para esas credenciales. En algunos casos, el controlador puede usar una credencial configurada del sistema para el backend (p.ej. si ha iniciado sesión en su cuenta de AWS CLI, y ejecuta el hub desde ese entorno, no necesitará leer las credenciales de su `config.json`). - -_Nota:_ El controlador de disco requiere una interfaz de sistema de archivos similar a la de \*nix, y no funcionará correctamente al intentar ejecutarse en un entorno Windows. ::: - -## Nota sobre SSL - -Le recomendamos _encarecidamente_ que despliegue su hub Gaia con SSL habilitado. De lo contrario, los tokens utilizados para autenticarse con el Hub de Gaia pueden ser robados por atacantes, lo que podría permitirles ejecutar escrituras en tu nombre. -Las opciones de configuración están disponibles para ejecutar el hub con un nodo `https` en un servidor Node.js -De lo contrario, se puede utilizar un servidor web proxy inverso, como nginx o Apache. - -## Requiere URL correcta del Hub - -Si activa la opción `requireCorrectHubUrl` en el archivo `config.json`, su hub Gaia requerirá que las solicitudes de autenticación incluyan correctamente la `hubURL` con la que están intentando conectarse. Esto se utiliza para evitar que un hub malicioso de gaia utilice un token de autenticación para sí mismo en otros hubs de Gaia. - -Por defecto, el hub de Gaia validará que la URL proporcionada coincida con `https://${config.serverName}`, pero si hay múltiples URLs válidas para que los clientes puedan acceder al hub, puede incluir una lista en `config.json`: - -```javascript -{ - .... - serverName: "normalserver.com" - validHubUrls: [ "https://specialserver.com/", - "https://legacyurl.info" ] - .... -} -``` - -## El parámetro readURL - -Por defecto, los controladores de los hub de gaia devolverán URLs de lectura que apuntan directamente al contenido escrito. Por ejemplo, un controlador S3 devolvería la URL directamente al archivo S3. Sin embargo, si configura un CDN o dominio para apuntar a ese mismo bucket, puedes usar el parámetro `readURL` para decirle al hub de gaia que los archivos pueden ser leídos desde la URL dada. Por ejemplo, el `hub.blockstack.org` Gaia Hub está configurado para devolver una URL de lectura que se vea `https://gaia.blockstack.org/hub/`. - -Desactive este parámetro de configuración si no tiene intención de desplegar ningún caché. - -## Requisitos mínimos de pruebas - -El Hub de gaia también puede configurarse para que requiera un número mínimo de pruebas sociales en el perfil de un usuario para aceptar escrituras de ese usuario. Esto puede utilizarse como una especie de mecanismo de control de spam. Sin embargo, recomendamos para el funcionamiento más fluido de su hub de gaia, para establecer el `testsConfig.parallsRequired` la clave de configuración a `0`. - -## CDN & Hubs Duplicados - -- https://docs.microsoft.com/en-us/azure/storage/blobs/storage-https-custom-domain-cdn - -- La implementación del hub está diseñada para ejecutarse desde una única instancia de Node.js. Si la instancia del hub está fragmentada (por ejemplo, hubs replicados a través de balanceo de carga), entonces cualquier `bucket` (identificado por el segmento URI) debe ser servido por la misma instancia, Al menos un par de elementos del Gaia Hub dependen de esto: la invalidación de tokens en la memoria caché, y el comportamiento de contención del endpoint de recursos 409. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md b/i18n/es/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md deleted file mode 100644 index 748f978f6a..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Desplegar un Hub de Gaia -description: Guías y tutoriales ---- - -## Desplegar tu hub de GAIA - -Los tutoriales para desplegar tu propio hub GAIA están actualmente disponibles para [Linux](./setup-linux), [MacOS](./setup-mac) y [Amazon EC2 / CloudFormation](./gaia-on-ec2). - -Independientemente de en qué servidor se ejecute el Gaia Hub, el almacenamiento que usa actualmente puede ser desplegado en múltiples plataformas: - -- Disco local (el propio servidor) -- Amazon S3 -- Azure Blob Storage -- Google Cloud - -:::tip -El soporte para IPFS está en desarrollo. -::: \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md b/i18n/es/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md deleted file mode 100644 index e938409343..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Amazon EC2 -description: Utilice una plantilla para desplegar un hub de Gaia en Amazon EC2 -tags: - - tutorial - - gaia ---- - -## Introducción - -La plantilla proporcionada en esta página proporciona una forma fácil de desplegar un hub de Gaia directamente en Amazon EC2. Puede utilizar esta plantilla para desplegar su propio hub de Gaia en su cuenta de Amazon Web Services (AWS). Amazon EC2 es un proveedor de computación en la nube asequible y conveniente. La plantilla proporciona un despliegue de un solo clic para Amazon EC2 con S3 o EBS como proveedor de almacenamiento. - -## Pre requisitos - -Este procedimiento utiliza Amazon CloudFormation para configurar un proveedor de computación en la nube EC2 para ejecutar el servicio de Hub de Gaia con un proveedor S3 o EBS para el almacenamiento de archivos. Usted debe tener acceso a una cuenta AWS ya sea a través de su cuenta personal o a través de una cuenta corporativa. Esta cuenta debe tener permisos para crear recursos. - -Además, también debe poseer un nombre de dominio y ser capaz de actualizar los registros DNS asociados con ese nombre de dominio. - -## Pasos a seguir - -### Paso 1 - Crear Stack - -Utilice un enlace en la tabla para lanzar la plantilla [CloudFormation](https://console.aws.amazon.com/cloudformation/) en la región de AWS en donde desea desplegar un hub de Gaia. - -![Crear stack](/img/cloudformation-create-stack.png) - -### Paso 2 - Configurar stack usando la plantilla - -Debe configurar la plantilla con los valores adecuados para su hub y el dominio en el que se ejecuta. - -Seleccione `Template is ready` y `Amazon S3 URL` e introduzca la siguiente URL de Amazon S3: -``` -https://s3-external-1.amazonaws.com/cf-templates-vzldibfi2mw8-us-east-1/2022160J6G-cloudformation.yaml -``` - -Si lo prefiere, puede seleccionar `Template is ready` y `Upload a template file` para subir un archivo de plantilla `cloudformation.yaml`. - -El último archivo de `cloudformation.yaml` puede descargarse [aquí](https://raw.githubusercontent.com/stacks-network/gaia/master/deploy/cloudformation.yaml). En la mayoría de los navegadores puede hacer clic derecho en esa página y hacer clic en `Guardar página como` para descargar el archivo. Alternativamente, puede copiar/pegar el texto en un archivo de texto llamado `cloudformation.yaml`. - -Luego haz clic en `Next`. - -![Especificar plantilla](/img/cloudformation-specify-template.png) - -### Paso 3 - Especificar detalles de stack - -Especifique los detalles de stacks y luego haga clic en `Next`: ![Especificar plantilla](/img/cloudformation-specify-stack-details.png) - -| Campo | Valor | Notas | -| --------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Stack name | _un nombre único en tu cuenta AWS_ | e.j.: my_gaia_hub | -| DomainName | _tu-dominio_ | | -| EmailAddress | _tu dirección de correo electrónico_ | | -| GaiaBucketName | _S3 bucket name_ | La plantilla combina este nombre con el nombre del stack para crear un bucket de S3 único. La plantilla ignora este campo si GaiaStorageType está establecido en `disk`. | -| GaiaStorageType | `s3` o `disk` | Seleccione el GaiaStorageType que se utilizará como un backend para el Hub de Gaia. Seleccionar `s3` hace que la plantilla cree un bucket de S3 basado en el nombre dado en el campo anterior. Al seleccionar `disk`, la plantilla adjunta un volumen EBS independiente a la instancia EC2 para el almacenamiento del Hub. | -| InstaceType | t2.micro | Seleccione el tipo de instancia que desee. El valor predeterminado es `t2.micro`. | -| KeyName | | En la lista desplegable KeyName selecciona un [EC2 KeyPair](https://console. aws. amazon. com/ec2/v2/home? region=us-east-1#KeyPairs:) para habilitar el acceso SSH a la instancia EC2. Deberías descargar el archivo keyfile `.pem` para este par desde la consola EC2. Para más información vea la [documentación de EC2 key pair](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html#prepare-key-pair) | -| SSHLocation | 0.0.0.0/0 | Deje el campo SSHLocation con el valor predeterminado de `0.0.0.0/0` para habilitar el acceso SSH desde cualquier dirección IP. Si desea restringir el acceso SSH a la instancia de EC2 a una determinada IP, puede actualizar este campo. | -| SubnetId | _subnetId_ | Seleccione una subred pública | -| VpcId | _vpcid_ | | - -### Paso 4 - Configurar las opciones de stack - -Configure cualquier opción de stack que se ajuste a la configuración deseada y haga clic en `Next`. Todos estos campos son opcionales. - -![Especificar plantilla](/img/cloudformation-stack-options.png) - -### Paso 5 - Revisión - -Revise la configuración de su hub Gaia, selecciona la casilla de verificación para reconocer que AWS puede crear recursos IAM con nombres personalizados y haz clic en `Create stack`. - -![Especificar plantilla](/img/cloudformation-iam-resources.png) - -### Paso 6 - Recuperar la IP pública de tu Hub de Gaia - -Tu stack puede tardar varios minutos en lanzarse. Puede monitorear la pestaña Eventos de su hub para revisar el progreso actual del lanzamiento. Cuando el lanzamiento se haya completado, la pestaña Salidas muestra información sobre el hub. Seleccione PublicIP y cópielo para configurar su nombre de dominio. - -Crea un registro DNS `A` apuntando a la IP dada en tu dominio. - -Espere unos minutos para que el registro DNS se propague, y debería ser capaz de acceder al hub de Gaia con SSH. - -## Accediendo a tu hub de Gaia con SSH - -Para que el SSH entre directamente en el host de tu hub EC2 de Gaia, debes tener el keyfile usado en la creación de contenedores. Accede al host con el siguiente comando en tu terminal: - -```bash -ssh -i admin@ -``` - -:::tip Si sólo puede acceder a SSH con la IP pero no con el nombre DNS y desea hacerlo, puedes activarlo siguiendo estos pasos: - - Abre tu [Consola AWS](https://console.aws.amazon. om) - Haga clic en `Servicio` -> VPC - Abra sus VPCs - Seleccione su VPC conectado a su Gaia Hub - Haga clic en `Acciones` -> `Editar nombres de host DNS` -> Cambie `nombres de host DNS` a `Activar` -::: -## Representación gráfica de la plantilla de cloudformation - -![](/img/cloudformation-gaia-template1-designer.png) \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/current/gaia/gaia.md b/i18n/es/docusaurus-plugin-content-docs/current/gaia/gaia.md deleted file mode 100644 index 908fe80039..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/gaia/gaia.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Gaia -description: Arquitectura de almacenamiento descentralizado para datos fuera de la cadena -sidebar_position: 5 -tags: - - gaia ---- - -## Introducción - -Las aplicaciones construidas en la blockchain de Stacks almacenan datos fuera de cadena usando un sistema de almacenamiento llamado Gaia. - -Mientras que los metadatos transaccionales públicos se almacenan mejor en la blockchain de Stacks, los datos de las aplicaciones de los usuarios pueden almacenarse a menudo de forma más eficiente y privada en el almacenamiento de Gaia. - -Almacenar datos fuera de la blockchain asegura que las aplicaciones de Stacks pueden proporcionar a los usuarios un alto rendimiento y una alta disponibilidad para lecturas y escrituras de datos sin introducir partes de confianza centrales. - -:::tip El último whitepaper de GAIA (Mayo 2022) está disponible [aquí](https://dev1-gaia-hub.s3.amazonaws.com/GAIA_Whitepaper.pdf) ::: - -## Comprender a Gaia en la arquitectura de Stacks - -El siguiente diagrama representa la arquitectura de Stacks y el lugar de Gaia en él. - -![Arquitectura de Stacks](/img/architecture.png) - -Las Blockchains requieren un consenso entre un gran número de personas, por lo que pueden ser lentas. Adicionalmente, una blockchain no está diseñada para contener muchos datos. Esto significa que usar una blockchain por cada bit de datos que un usuario pueda escribir y almacenar es caro. Por ejemplo, imagínese si una aplicación estaba almacenando cada tweet en la cadena. - -La blockchain de Stacks aborda los problemas de rendimiento mediante un enfoque por capas. La capa base consiste en la blockchain de Stacks y el Blockchain Naming System (BNS). La Blockchain gobierna la propiedad de identidades en la red de Stacks. Las identidades pueden ser nombres como nombres de dominio, nombres de usuario o nombres de aplicaciones. - -Cuando se crea una identidad, su creación se registra en la blockchain de Stacks. Las identidades componen los datos principales almacenados en la blockchain de Stacks. Estas identidades corresponden a datos de enrutamiento en el stack de OSI. Los datos de enrutamiento se almacenan en la Red de Pares de Atlas, la segunda capa. Cada nodo del núcleo que se une a la red de Stacks es capaz de obtener una copia completa de estos datos de enrutamiento. Stacks utiliza los datos de enrutamiento para asociar identidades (nombres de dominio, nombres de usuario, y nombres de aplicación) con una ubicación de almacenamiento particular en la capa final, el Sistema de Almacenamiento de Gaia. - -Un sistema de almacenamiento Gaia consiste en un _centro de servicio_ y un recurso de almacenamiento en un proveedor de software en la nube. El proveedor de almacenamiento puede ser cualquier proveedor comercial como Azure, DigitalOcean, Amazon EC2, etcétera. Normalmente, el recurso de cómputo y el recurso de almacenamiento residen en el mismo proveedor de la nube, aunque esto no es un requisito. Gaia actualmente tiene soporte para controladores para S3, Azure Blob Storage, Google Cloud Platform y disco local, pero el modelo de controlador también permite otro soporte de backend. - -Gaia almacena datos como un simple almacén clave-valor. Cuando se crea una identidad, un almacén de datos correspondiente se asocia con esa identidad en Gaia. Cuando un usuario inicia sesión en una dApp, el proceso de autenticación da a la aplicación la URL de un hub de Gaia, que entonces escribe en el almacenamiento en nombre de ese usuario. - -La blockchain de Stacks almacena sólo datos de identidad. Los datos creados por las acciones de una identidad se almacenan en el sistema de almacenamiento de Gaia. Cada usuario tiene datos de perfil. Cuando un usuario interactúa con una dApp descentralizada, esa aplicación almacena los datos de la aplicación en nombre del usuario. Debido a que Gaia almacena datos de usuarios y aplicaciones fuera de la blockchain, una DApp de Stacks es normalmente más eficiente que DApps creadas en otras blockchains. - -## Control del usuario o ¿Cómo se descentraliza Gaia? - -Un hub de Gaia funciona como un servicio que escribe en el almacenamiento de datos. El almacenamiento en sí mismo es un simple almacén clave-valor. El servicio del Hub escribe en el almacenamiento de datos requiriendo un token de autenticación válido de un solicitante. Por lo general, el servicio del Hub se ejecuta en un recurso de cómputo y el almacenamiento propiamente dicho en un recurso de almacenamiento dedicado y separado. Por lo general, ambos recursos pertenecen al mismo proveedor de computación en la nube. - -![Gaiastorage](/img/gaia-storage.png) - -El enfoque de Gaia hacia la descentralización se centra en el control de los datos por parte del usuario y su almacenamiento. Los usuarios pueden elegir un proveedor de Hub de Gaia. Si un usuario puede elegir qué proveedor de hub de Gaia utilizar, entonces esa opción es toda la descentralización necesaria para permitir aplicaciones controladas por el usuario. Además, Gaia define una API uniforme para aplicaciones para acceder a esos datos. - -El control de los datos del usuario reside en la forma en que se accede a los datos del usuario. Cuando una aplicación obtiene un archivo `data.txt` para un usuario determinado `alice.id`, la búsqueda seguirá estos pasos: - -1. Obtenga el `zonefile` para `alice.id`. -2. Lea su URL de perfil desde su `zonefile`. -3. Busque el perfil de Alice. -4. _Verificar_ que el perfil esté firmado por la clave de `alice.id` -5. Encuentre la url de solo lectura de la sección `appsMeta` del perfil (por ejemplo, `https://example-app.gaia.alice.org`). -6. Obtenga el archivo de `https://example-app.gaia.alice.org/data.txt`. - -Debido a que `alice.id` tiene acceso a su [zonefile](https://docs.stacks.co/references/bns-contract#name-update), puede cambiar donde se almacena su perfil. Por ejemplo, puede hacer esto si el proveedor de servicios o el almacenamiento del perfil actual se ven comprometidos. Para cambiar donde se almacena su perfil, cambia su URL del hub de Gaia a otra URL del hub de Gaia. Si un usuario tiene suficientes recursos de cómputo y almacenamiento, puede ejecutar su propio Sistema de Almacenamiento de Gaia y eludir un proveedor comercial de hubs de Gaia. - -:::precaución -Los usuarios con identidades existentes aún no pueden migrar sus datos de un hub a otro. -::: - -Las aplicaciones que escriben directamente en nombre de `alice.id` no necesitan realizar una búsqueda. En su lugar, el [flujo de autenticación de Stacks](https://stacks.js.org) proporciona la URL del hub de gaia elegido por Alice a la aplicación. Este flujo de autenticación _también está_ bajo el control de Alice porque la billetera de Alice_ debe_ generar la respuesta de autenticación. - -## Entendiendo el almacenamiento de datos - -Un hub de Gaia almacena los datos escritos _exactamente_ como se ha dado. Ofreciendo garantías mínimas sobre los datos. No se asegura de que los datos tengan un formato válido, que contengan firmas válidas o que estén cifrados. Más bien, la filosofía del diseño es que estas preocupaciones son del lado del cliente. - -Las librerías de clientes (como [`Stacks.js`](https://stacks.js.org/)) son capaces de proporcionar estas garantías. Una definición liberal del [principio de extremo a extremo](https://en.wikipedia.org/wiki/End-to-end_principle) guía esta decisión de diseño. - -Cuando una aplicación escribe en un hub de Gaia, se pasan al hub de Gaia un token de autenticación, una clave, y los datos. - -![Gaia writes](/img/gaia-writes.png) - -El token asegura que la aplicación tenga la autorización para escribir en el hub en nombre del usuario. - -## Gaia versus otros sistemas de almacenamiento - -Así es como Gaia se compara contra otros sistemas de almacenamiento descentralizados. Las características que son comunes a todos los sistemas de almacenamiento se omiten por razones de brevedad. - -| Funcionalidades | [Gaia](https://github.com/stacks-network/gaia) | [Sia](https://sia.tech/) | [Storj](https://storj.io/) | [IPFS](https://ipfs.io/) | [DAT](https://datproject.org/) | [SSB](https://www.scuttlebutt.nz/) | -| ------------------------------------------------------- | ---------------------------------------------- | ------------------------ | -------------------------- | ------------------------ | ------------------------------ | ---------------------------------- | -| El usuario controla donde se alojan los datos | X | | | | | | -| Los datos se pueden ver en un navegador web normal | X | | | X | | | -| Datos de lectura/escritura | X | | | | X | X | -| Se pueden eliminar datos | X | | | | X | X | -| Los datos pueden ser listados | X | X | X | | X | X | -| Se recupera el espacio de datos borrados | X | X | X | X | | | -| Las búsquedas de datos tienen un rendimiento predecible | X | | X | | | | -| El permiso de escritura puede ser delegado | X | | | | | | -| El permiso de listado puede ser delegado | X | | | | | | -| Soporta múltiples backends de forma nativa | X | | X | | | | -| Los datos son direccionables globalmente | X | X | X | X | X | | -| Necesita una criptomoneda para funcionar | | X | X | | | | -| Los datos están orientados al contenido | | X | X | X | X | X | diff --git a/i18n/es/docusaurus-plugin-content-docs/current/gaia/setup-linux.md b/i18n/es/docusaurus-plugin-content-docs/current/gaia/setup-linux.md deleted file mode 100644 index f98f5b84e3..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/gaia/setup-linux.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: Linux -description: Pasos para configurar un hub GAIA en un servidor Linux (instalación nueva). Este ejemplo está usando Debian, pero debería funcionar en cualquier distribución de Linux. Utiliza docker compose por detras. -tags: - - tutorial - - gaia ---- - -Esta configuración configurará los siguientes 4 contenedores docker: - -- Nginx con certbot en los puertos TCP 80 y 443. -- Hub Gaia en el puerto TCP 3000. -- Gaia admin en el puerto TCP 8009. -- Gaia reader en el puerto TCP 8008 - -**1. Actualice el sistema e instale las dependencias y el software que usaremos para la prueba:** - -```bash -apt update && apt upgrade -y && apt install -y git vim gnupg jq -``` - -**2. Instala [docker](https://docs.docker.com/engine/install/debian/) y [docker-compose](https://docs.docker.com/compose/cli-command/#install-on-linux)** en tu sistema operativo. -Para nuestro ejemplo instalamos _docker_ con: - -```bash -curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg - -echo \ - "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian \ - $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null - -apt update && apt install -y docker-ce docker-ce-cli containerd.io -``` - -Instala _docker-compose_ descargando la [última versión](https://github.com/docker/compose/releases): - -```bash -VERSION_DC=$(curl --silent https://api.github.com/repos/docker/compose/releases/latest | jq .name -r) -DESTINATION_DC=~/.docker/cli-plugins -mkdir -p ${DESTINATION_DC} -curl -SL https://github.com/docker/compose/releases/download/${VERSION_DC}/docker-compose-linux-x86_64 -o ${DESTINATION_DC}/docker-compose -chmod +x ${DESTINATION_DC}/docker-compose -``` - -**3. Clona el repositorio de GAIA** e introduce su directorio de docker. - -```bash -git clone https://github.com/stacks-network/gaia.git && cd gaia/deploy/docker -``` - -**4. Copia y edita el archivo .env appropiado**. -En la carpeta `. deploy/docker/` son archivos de ejemplo diferentes para diferentes configuraciones como el uso de aws, azure o disco entre otros. En este ejemplo almacenaremos los datos localmente para que copiemos el archivo _de disco_ y actualicemos el dominio y los campos de correo electrónico. Por favor, cambie `gaia.site.com` y `gaiarocks@mydomain.com` como corresponda. Tenga en cuenta que necesita ambos para que el certificado SSL se cree correctamente. - -```bash -export MYGAIADOMAIN=gaia.site.com -export MYGAIAEMAIL=gaiarocks@mydomain.com -cp sample-disk.env disk.env -sed -i 's/my-domain.com/'"$MYGAIADOMAIN"'/g' disk.env -sed -i 's/my-email@example.com/'"$MYGAIAEMAIL"'/g' disk.env - -``` - -**5. Iniciar servicio GAIA HUB** - -Para iniciar GAIA HUB - -```bash -./gaiahub.sh start -``` - -Para detener GAIA HUB - -```bash -./gaiahub.sh stop -``` - -Para ver el estado de GAIA HUB - -```bash -./gaiahub.sh status -``` - -**6. Verificar que el servidor funciona localmente** con el siguiente comando: - -```bash -curl -sk http://localhost/hub_info | jq -``` - -Tu código debe parecerse a esto: - -```bash - { - "challenge_text": "[\"gaiahub\",\"0\",\"gaia-0\",\"blockstack_storage_please_sign\"]", - "latest_auth_version": "v1", - "max_file_upload_size_megabytes": 20, - "read_url_prefix": "https://gaia.site.com/reader/" - } -``` - -**7. Test your GAIA HUB** Running `gaia_test.js` will test your GAIA Hub, by trying to connect to it, uploading a file and downloading it again. - -Primero instale todas las dependencias requeridas con: - -```bash -npm install -``` - -Luego, desde la carpeta raíz del tipo de proyecto: - -```bash -node ./deploy/gaia_test.js https://yourgaiaurl -``` - -Un resultado correcto será algo así: - -``` -Will run a test for the GAIA HUB: https://gaia.mydomain.com -Generating some test keys... -Private key: 5aacc60fc2a429e1f02be139f3cac82061c6a980******************** -Public key: 025691f17f2ab80dc4af363bb9c7aac59e9e1db6ae8ff668202582a3f4ec9678ff -Address: 15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS -[DEBUG] connectToGaiaHub: https://gaia.mydomain.com/hub_info -[DEBUG] uploadToGaiaHub: uploading testing.txt to https://gaia.mydomain.com -File uploaded successfully. -Upload to gaia hub thinks it can read it from: https://gaia.mydomain.com/reader/15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS/testing.txt -Hub info thinks it can read it from : https://gaia.mydomain.com/reader/15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS/testing.txt -Let's now try to fetch the uploaded file... -Archivo guardado con éxito. Contenido del archivo: GAIA ROCKS! -``` diff --git a/i18n/es/docusaurus-plugin-content-docs/current/gaia/setup-mac.md b/i18n/es/docusaurus-plugin-content-docs/current/gaia/setup-mac.md deleted file mode 100644 index 44734faa87..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/gaia/setup-mac.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: MacOS -description: MacOS para pruebas/desarrollo local -tags: - - tutorial ---- - -Lo siguiente asume que tienes [Docker instalado](https://docs. docker. com/docker-for-mac/install/) - -- Recomendado tener instalado [MacOS Homebrew](https://docs.brew.sh/Installation) -- Usa Homebrew para instalar jq con `brew install jq` - -En su directorio de trabajo: - -**1. Clona una copia del [ repositorio de gaia](https://github.com/stacks-network/gaia):** - -```bash -$ git clone -b master --single-branch https://github.com/stacks-network/gaia -``` - -**2. Cambiar tu cwd:** - -```bash -$ cd gaia/deploy/docker -``` - -**3. Crear una copia de sample-disk.env y rellena los valores:** - -``` -$ cp sample-disk.env disk.env -# Cambia la variable DOMAIN_NAME a `localhost` -``` - -**4. Inicia un servidor:** - -``` -$ docker-compose -f docker-compose-base.yaml -f docker-compose-disk.yaml --env-file disk.env up -``` - -**5. Verificar que el servidor está respondiendo localmente:** - -``` -$ curl -sk https://localhost/hub_info | jq - { - "challenge_text": "[\"gaiahub\",\"0\",\"gaia-0\",\"blockstack_storage_please_sign\"]", - "latest_auth_version": "v1", - "max_file_upload_size_megabytes": 20, - "read_url_prefix": "https://localhost/reader/" - } -``` - -### Modificando la configuración de tu gaia-Hub - -Existen dos métodos: - -1. Editar el `gaia/deploy/configs/gaia/hub-config.json` usando `vim` u otro - -- requiere reiniciar los contenedores: `docker-compose -f docker-compose-base.yaml -f docker-compose-disk.yaml --env-file disk.env restart` - -2. Utilice el contenedor `admin` en ejecución para modificar cualquier valor de configuración, y también recargar el hub cuando se haya completado: - -- [GitHub - Gaia Admin README.md](https://github.com/stacks-network/gaia/blob/master/admin/README.md) - -``` -$ export API_KEY="hello" -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - -H 'Content-Type: application/json' \ - -X POST \ - --data-raw '{"serverName": "myserver"}' \ - http://localhost:8009/v1/admin/config - -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - -X POST \ - http://localhost:8009/v1/admin/reload - -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - http://localhost:8009/v1/admin/config | jq -``` diff --git a/i18n/es/docusaurus-plugin-content-docs/current/governance/_index.md b/i18n/es/docusaurus-plugin-content-docs/current/governance/_index.md deleted file mode 100644 index 2a0d9b8963..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/governance/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Gobernanza -description: Gobernanza -sidebar_position: 9 ---- - -Esta página necesita contribuciones. ¡Ayúdanos a escribirlo! \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/current/governance/index.md b/i18n/es/docusaurus-plugin-content-docs/current/governance/index.md deleted file mode 100644 index 62f93e24eb..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/governance/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Gobernanza -description: Gobernanza -sidebar_position: 9 ---- - -![](/img/stacks-governance.png) - -Esta página necesita contribuciones. ¡Ayúdanos a escribirlo! - -La gobernancia en la web 3 es impulsada por la comunidad. - -¿Cómo participar? - -[Sitio web de Recursos de Gobernanza](https://resources.stacksgov.com) - -[Github - Gobernanza de la Comunidad Stacks](https://github.com/stacksgov) - -:::tip Community Calls Las llamadas menusales comunitarias son grabadas y están disponibles [aquí](https://www.youtube.com/playlist?list=PLg717Ri_rTnwwYjQYlc7rIP6x2FaTNn7f) ::: diff --git a/i18n/es/docusaurus-plugin-content-docs/current/governance/sips.md b/i18n/es/docusaurus-plugin-content-docs/current/governance/sips.md deleted file mode 100644 index 46b9d90582..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/governance/sips.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: SIPs -description: SIPs -sidebar_position: 9 ---- - -## Propuestas de Mejora de Stacks (SIPs) - -Las propuestas de mejora de Stacks (SIPs) tienen como objetivo describir la implementación de la blockchain de Stacks, asi como proponer mejoras. - -El proceso SIP [(SIP-000)](https://github.com/stacksgov/sips/blob/main/sips/sip-000/sip-000-stacks-improvement-proposal-process.md) describe cómo hacer un SIP y conseguir que se ratifique. - -Deberían contener especificaciones técnicas concisas de las características o estándares y la justificación de las mismas. SIPs están destinados a ser el primer medio para proponer nuevas características, para recolectar las aportaciones de la comunidad sobre un tema que afecta a todo el sistema y para documentar las decisiones de diseño. - -Los SIPs se encuentran en el repositorio [stacksgov/sips](https://github.com/stacksgov/sips) como parte de la [organización de Gobernanza Communitaria de Stacks](https://github.com/stacksgov). - -Cualquiera en la comunidad de Stacks puede enviar un SIP. - -:::tip Las reuniones de las Convocatorias comunitarias de propuesta de mejoras de Stacks, SIP Meeting calls, están grabadas y disponibles [aquí](https://www.youtube.com/playlist?list=PLg717Ri_rTnx5kuaWqp3cUAtwQk_yzslT) - -Más detalles de las reuniones están disponibles [aquí](https://github.com/stacksgov/sips/issues/79) ::: - -## SIPS ratificados - -- [x] [SIP 001: Burn Election](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md) -- [x] [SIP 002: Clarity, un lenguaje para contratos inteligentes predecibles](https://github.com/stacksgov/sips/blob/main/sips/sip-002/sip-002-smart-contract-language.md) -- [x] [SIP 003: Red de pares](https://github.com/stacksgov/sips/blob/main/sips/sip-003/sip-003-peer-network.md) -- [x] [SIP 004: Compromiso criptográfico con las Vistas Materializadas](https://github.com/stacksgov/sips/blob/main/sips/sip-004/sip-004-materialized-view.md) -- [x] [SIP 005: Bloques, Transacciones, y cuentas](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md) -- [x] [SIP 006: Evaluación de los costes de ejecución de Clarity](https://github.com/stacksgov/sips/blob/main/sips/sip-006/sip-006-runtime-cost-assessment.md) -- [x] [SIP 007: Consenso de Stacking](https://github.com/stacksgov/sips/blob/main/sips/sip-007/sip-007-stacking-consensus.md) -- [x] [SIP 008: Análisis de Clarity y análisis de evaluación de costes](https://github.com/stacksgov/sips/blob/main/sips/sip-008/sip-008-analysis-cost-assessment.md) -- [x] [SIP 009: Definición de rasgos estándar para Tokens no Fungibles](https://github.com/stacksgov/sips/blob/main/sips/sip-009/sip-009-nft-standard.md) -- [x] [SIP 010: Definición de rasgos estándar para Tokens Fungibles](https://github.com/stacksgov/sips/blob/main/sips/sip-010/sip-010-fungible-token-standard.md) -- [x] [SIP 012: Selección del tamaño de quema para una actualización de la red para introducir nuevos límites de coste](https://github.com/stacksgov/sips/blob/main/sips/sip-012/sip-012-cost-limits-network-upgrade.md) -- [x] [SIP-016: Metadata for Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-016/sip-016-token-metadata.md) - -## Cómo implicarse - -Hay varias maneras en que puedes involucrarte en el proceso SIP: - -* **Únase a la llamada semanal de la reunión de SIP** listada [aquí](https://community.stacks.org/events). - -* **Editor SIP**. Los editores de SIP ayudan a los autores de SIP a asegurarse de que sus SIPs están bien formados y siguen el proceso correcto. Ayudan a que los SIP estén listos para una revisión profunda, impulsándolos desde el estado de "Borrador" hasta el estado de "Aceptado". Si quieres convertirte en un editor SIP, abra un "issue" con su nombre y correo electrónico para pedir que se añada a la lista de editores SIP. - -* **Únase al CAB** (Consejo consultivo de consideración). Los SIP entran en el ámbito de una o varias consideraciones. Una lista completa está en [este directorio de github](https://github.com/stacksgov/sips/tree/main/considerations). Actualmente son: Diversidad, Economía, Ética, Gobernanza y Técnica. Los miembros de los consejos consultivos de consideración SIP utilizan su experiencia en el campo para dar a los SIP Aceptados una lectura profunda, y dar a los autores cualquier comentario que ayude a hacer que el SIP sea viable. Si desea unirse al consejo, póngase en contacto con el presidente de la junta a través de la información de contacto listada. - -* **Comité directivo**. El Comité Directivo organiza los consejos consultivos de consideración y los votos para adelantar a los SIP recomendados para el estado de "Activación en Progreso" y luego para el estado "Ratificado" o "Rechazado". Una vez que están en proceso de activación, utilizan una sección de Activación de un SIP para determinar si el ecosistema de Stacks ha ratificado o rechazado el SIP. La incorporación a este comité requiere el consentimiento del consejo de la Fundación Stacks. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/intro.md b/i18n/es/docusaurus-plugin-content-docs/current/intro.md deleted file mode 100644 index 8716696a0a..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/intro.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_label: "Inicio" -sidebar_position: 1 ---- - -# Introducción de la documentación de Stacks - -Bienvenido a la documentación oficial de Stacks impulsada por la comunidad. - -Aprende sobre el minado de Stacks, el token STX y el lenguaje de programación de contratos inteligentes, Clarity. - -![](/img/Bitcoinet-L_2.svg) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md b/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md deleted file mode 100644 index 1d3d2b2d28..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Stacks en DigitalOcean -description: Una guía para configurar Stacks en DigitalOcean -sidebar_position: 4 -tags: - - tutorial ---- - -## Introducción - -Esta es una guía paso a paso para desplegar el [Stacks Blockchain en DigitalOcean](https://marketplace.digitalocean.com/apps/stacks-blockchain). El código está alojado en este [repositorio de Github](https://github.com/stacks-network/stacks-blockchain-docker). - -## Pasos - -#### Paso 1 - -Vaya a la página [Stacks Blockchain](https://marketplace.digitalocean.com/apps/stacks-blockchain) en el mercado de DigitalOcean. Haga clic en `Create Stacks Blockchain Droplet`. - -#### Paso 2 - -Choose a plan (it will only allow you to select a plan that meets the minimum requirements) and your prefered datacenter region. ![](/img/sh_digitalocean-choose-plan.png) - -#### Paso 3 - -Introduzca una contraseña de root o active las claves SSH si lo prefiere. - -![](/img/sh_digitalocean-choose-authentication.png) - -#### Paso 4 - -Puedes dejar el resto de las opciones tal y como están y hacer clic en `Create Droplet` - -#### Paso 5 - -Necesitarás esperar unos segundos para que el droplet se cree. Una vez creado haga clic en él para ver más información. - -![](/img/sh_digitalocean-creating-droplet.png) - -![](/img/sh_digitalocean-created-droplet.png) - -### Paso 6 - -¡Felicidades! ¡Felicidades! Ahora está ejecutando Stacks Blockchain. Puede hacer clic en `Console` para que una ventana de terminal abra o inicie sesión usando SSH a la IP pública a la que se le ha asignado con el usuario `root`. - -![](/img/sh_digitalocean-console-button.png) ![](/img/sh_digitalocean-console.png) - -## Empezando después de desplegar Stacks Blockchain - -Once droplet is launched, initial startup can take several minutes while BNS data is imported (this is a one time operation). - -To keep track of the progress, you can `ssh root@your_droplet_public_ipv4` to the host and run: `/opt/stacks-blockchain-docker/manage.sh -n mainnet -a logs`. - -Once the stacks blockchain starts to sync with peers, application ports will open and nginx port 80 will now start proxying requests. - -Use `http://your_droplet_public_ipv4` para acceder a los datos directamente, siendo la salida similar a: - -```json -{ - "server_version": "stacks-blockchain-api v3.0.3 (master:cd0c8aef)", - "status": "ready", - "chain_tip": { - "block_height": 16220, - "block_hash": "0x3123fba9c0de6b569573494cf83c1d5d198a66bfd5f48ef97949b6bf11ba13be", - "index_block_hash": "0xeec960fbbd6186b4ccac85ce12adba72be497d881f81e077305c90955b51a6ae" - } -} -``` - -All services are managed by a [systemd unit file](https://github.com/stacksfoundation/stacks-machine-images/blob/master/files/etc/systemd/system/stacks.service) that is set to start on boot. - -Manual control is also possible via the [manage.sh script](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/manage.sh) at `/opt/stacks-blockchain-docker/manage.sh` on the host. - -Full details on how to use the manage.sh script is [available here](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/README.md#quickstart). - -## Creación de API - -In addition to creating a Droplet from the Stacks Blockchain 1-Click App via the control panel, you can also use the [DigitalOcean API](https://digitalocean.com/docs/api). - -As an example, to create a 4GB Stacks Blockchain Droplet in the SFO2 region, you can use the following curl command. You’ll need to either save your [API access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/) to an environment variable or substitute it into the command below. - -```bash -curl -X POST -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer '$TOKEN'' -d \ - '{"name":"choose_a_name","region":"sfo2","size":"s-2vcpu-4gb","image":"stacksfoundation-stacksblockchain"}' \ - "https://api.digitalocean.com/v2/droplets" -``` diff --git a/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md b/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md deleted file mode 100644 index f25944c2c5..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Nodos y Mineros -description: Nodos y Mineros -sidebar_position: 7 ---- - -Aquí están todos los pasos para ejecutar nodos y mineros, tanto en mainnet como en testnet. - -## ¿Qué es un nodo de Stacks? - -## ¿Qué es un minero de Stacks? diff --git a/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md b/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md deleted file mode 100644 index 40397a51e0..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Miner costs and fees -description: Miner Cost and Fee Estimation -sidebar_position: 8 ---- - -## Configuring Cost and Fee Estimation - -Fee and cost estimators can be configured via the config section `[fee_estimation]`: - -``` -[fee_estimation] -cost_estimator = naive_pessimistic -fee_estimator = fuzzed_weighted_median_fee_rate -fee_rate_fuzzer_fraction = 0.1 -fee_rate_window_size = 5 -cost_metric = proportion_dot_product -log_error = true -enabled = true -``` - -Fee and cost estimators observe transactions on the network and use the observed costs of those transactions to build estimates for viable fee rates and expected execution costs for transactions. Estimators and metrics can be selected using the configuration fields above, though the default values are the only options currently. `log_error` controls whether or not the INFO logger will display information about the cost estimator accuracy as new costs are observed. Setting `enabled = false` turns off the cost estimators. Cost estimators are **not** consensus-critical components, but rather can be used by miners to rank transactions in the mempool or client to determine appropriate fee rates for transactions before broadcasting them. - -The `fuzzed_weighted_median_fee_rate` uses a median estimate from a window of the fees paid in the last `fee_rate_window_size` blocks. Estimates are then randomly "fuzzed" using uniform random fuzz of size up to `fee_rate_fuzzer_fraction` of the base estimate. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md b/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md deleted file mode 100644 index 3c74e8bd03..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md +++ /dev/null @@ -1,343 +0,0 @@ ---- -title: Mine mainnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 mainnet -sidebar_position: 5 -tags: - - tutorial ---- - -## Introducción - -Make sure you've followed the [run a node](run-a-node) procedure. Once completed it's only a few more steps to run a proof-of-burn miner on the mainnet. - -If you're interested in mining on the testnet, you can find instructions on how to do that [here](miner-testnet): - -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining): - -## Running bitcoind locally - -To participate as a miner on mainnet, you must have access to a mainnet bitcoin node. One way to accomplish this is to run bitcoind locally. [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements) - -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. - -Next, start bitcoind with the following configuration: - -```toml -server=1 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=1 -banscore=1 -bind=0.0.0.0:8333 -rpcbind=0.0.0.0:8332 -rpcport=8332 -``` - -Finally, start bitcoind as follows: - -```bash -bitcoind -conf=path/to/bitcoin.conf -``` - -It may take a few days for the node to synchronize with the Bitcoin mainnet. - -## Running a miner - -First, a keychain needs to be generated. With this keychain, we'll purchase some BTC from a crytpocurrency exchange, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. We'll use the `make_keychain` command. - -```bash -npx @stacks/cli make_keychain 2>/dev/null | json_pp > keychain.txt -``` - -After this runs, you should see some JSON in the new `keychain.txt` file that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -**Don't lose this information** - we'll need to use the `privateKey` field later on. - -The above BTC address will then need to be imported into the BTC network. - -```bash -bitcoin-cli -rpcport=8332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - - - -Once imported, we need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - - - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/mainnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `make_keychain` command. Replace the `seed` field with your private key. Save and close this configuration file. - -To run your miner, run this in the command line: - -```bash -stacks-node start --config=./testnet/stacks-node/conf/mainnet-miner-conf.toml -``` - -Your node should start. It will take some time to sync, and then your miner will be running. - -### Creating an optimized binary - -The steps above are great for trying to run a node temporarily. If you want to host a node on a server somewhere, you might want to generate an optimized binary. To do so, use the same configuration as above, but run: - -```bash -cd testnet/stacks-node -cargo build --release --bin stacks-node -``` - -The above code will compile an optimized binary. To use it, run: - -```bash -cd ../.. -./target/release/stacks-node start --config=./mainnet-miner-conf.toml -``` - -To read more about the technical details of mining on the Stacks 2.0 network, have a look at [the mining guide](../understand-stacks/mining). - -### Enable debug logging - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -STACKS_LOG_DEBUG=1 stacks-node mainnet -``` - -## Running a miner in Windows - -### Pre requisitos - -Make sure are [running a node](run-a-node) and [running bitcoind locally](#running-bitcoind-locally) before starting this tutorial. - -### Generate keychain and get mainnet tokens in Windows - -To setup the miner, first we need to generate a keychain. With this keychain, we'll purchase some BTC from a crytpocurrency exchange, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. To get a keychain, the simplest way is to use the `stacks-cli`. - -Generate a keychain: - -```bash -npm install --global @stacks/cli -stx make_keychain > cli_keychain.json -type cli_keychain.json -``` - -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -The above BTC address will then need to be imported into the BTC network. - -```bash -bitcoin-cli -rpcport=8332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - -Once imported, we need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Update configuration file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/mainnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Run the miner - -To start your miner, run this in the command line: - -```bash -stacks-node start --config=testnet/stacks-node/conf/mainnet-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](/img/windows-defender.png) - -Your node should start. It will take some time to sync, and then your miner will be running. - -### Enable debug logging in Windows - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=mainnet-miner-conf.toml -``` - -## Optional: Running with Docker - -Alternatively, you can run the mainnet node with Docker. - -:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: - -### Generate keychain and get tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null -``` - -We need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Update configuration file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/mainnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Start the miner - -:::info The ENV VARS `RUST_BACKTRACE` and `STACKS_LOG_DEBUG` are optional. If removed, debug logs will be disabled ::: - -```bash -docker run -d \ - --name stacks_miner \ - --rm \ - --network host \ - -e RUST_BACKTRACE="full" \ - -e STACKS_LOG_DEBUG="1" \ - -v "$(pwd)/testnet/stacks-node/conf/mainnet-miner-conf.toml:/src/stacks-node/mainnet-miner-conf.toml" \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain:latest \ -/bin/stacks-node start --config /src/stacks-node/mainnet-miner-conf.toml -``` - -You can review the node logs with this command: - -```bash -docker logs -f stacks_miner -``` - -## Optional: Running in Kubernetes with Helm - -In addition, you're also able to run a mainnet node in a Kubernetes cluster using the [stacks-blockchain Helm chart](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). - -Ensure you have the following prerequisites installed on your machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [minikube](https://minikube.sigs.k8s.io/docs/start/) (Only needed if standing up a local Kubernetes cluster) -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [helm](https://helm.sh/docs/intro/install/) - -### Generate keychain and get some tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null -``` - -We need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Install the chart and run the miner - -To install the chart with the release name `my-release` and run the node as a miner: - -```bash -minikube start # Only run this if standing up a local Kubernetes cluster -helm repo add blockstack https://charts.blockstack.xyz -helm install my-release blockstack/stacks-blockchain \ - --set config.node.miner=true \ - --set config.node.seed="replace-with-your-privateKey-from-generate-keychain-step" \ - --set config.burnchain.mode="mainnet" -``` - -You can review the node logs with this command: - -```bash -kubectl logs -l app.kubernetes.io/name=stacks-blockchain -``` - -For more information on the Helm chart and configuration options, please refer to the [chart's homepage](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). diff --git a/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md b/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md deleted file mode 100644 index f1a8345c66..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md +++ /dev/null @@ -1,336 +0,0 @@ ---- -title: Mine testnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 testnet -sidebar_position: 4 -tags: - - tutorial ---- - -## Introducción - -Make sure you've followed the [Run a node](run-a-node) procedure. Once completed it's only a few more steps to run a proof-of-burn miner on the testnet. - -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining). - -## Running bitcoind locally - -To participate as a miner on Testnet, you must have access to a testnet bitcoin node. One way to accomplish this is to run bitcoind locally. [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements) - -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. - -Next, start bitcoind with the following configuration: - -```toml -server=1 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password -testnet=1 -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=1 -banscore=1 - -[test] -bind=0.0.0.0:18333 -rpcbind=0.0.0.0:18332 -rpcport=18332 -``` - -Finally, start bitcoind as follows: - -```bash -bitcoind -conf=path/to/bitcoin.conf -``` - -It may take a few hours for the node to synchronize with the Bitcoin testnet. - -## Running a miner - -First, a keychain needs to be generated. With this keychain, we'll get some testnet BTC from a faucet, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. To get a keychain, the simplest way is to use the `stacks-cli`. - -```bash -npx @stacks/cli make_keychain -t 2>/dev/null | json_pp > keychain.txt -``` - -After this runs, you should see some JSON in the new `keychain.txt` file that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -**Don't lose this information** - we'll need to use the `privateKey` field later on. - -The above BTC address will then need to be imported into the BTC testnet network. - -```bash -bitcoin-cli -rpcport=18332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - -Once imported, we need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). You'll be sent `0.01` testnet BTC to that address. - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/testnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/testnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `make_keychain` command. Replace the `seed` field with your private key. Save and close this configuration file. - -To run your miner, run this in the command line: - -```bash -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. - -### Creating an optimized binary - -The steps above are great for trying to run a node temporarily. If you want to host a node on a server somewhere, you might want to generate an optimized binary. To do so, use the same configuration as above, but run: - -```bash -cd testnet/stacks-node -cargo build --release --bin stacks-node -``` - -The above code will compile an optimized binary. To use it, run: - -```bash -cd ../.. -./target/release/stacks-node start --config=./testnet/conf/testnet-follower-conf.toml -``` - -To read more about the technical details of mining on the Stacks 2.0 network, have a look at [the minig guide](../understand-stacks/mining): - -### Enable debug logging - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -STACKS_LOG_DEBUG=1 stacks-node testnet -``` - -## Running a miner in Windows - -### Pre requisitos - -Make sure are [running a testnet node](run-a-node) before starting this tutorial. - -### Generate keychain and get testnet tokens in Windows - -To setup the miner, first, we need to generate a keychain. With this keychain, we'll get some testnet BTC from a faucet, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. We'll use the `stx make-keychain` command, and pass `-t` to indicate that we want a testnet keychain. - -Generate a keychain: - -```bash -npm install --global @stacks/cli -stx make_keychain -t > cli_keychain.json -type cli_keychain.json -``` - -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -Request BTC from faucet: - -We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). - -### Update configuration file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/testnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/testnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Run the miner - -To start your miner, run this in the command line: - -```bash -stacks-node start --config=testnet/stacks-node/conf/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](/img/windows-defender.png) - - - -Your node should start. It will take some time to sync, and then your miner will be running. - -### Enable debug logging in Windows - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=testnet-miner-conf.toml -``` - -## Optional: Running with Docker - -Alternatively, you can run the testnet node with Docker. - -:::warning Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: - -### Generate keychain and get testnet tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` - -We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). - -### Update config file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/testnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/testnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Start the miner - -:::info The ENV VARS `RUST_BACKTRACE` and `STACKS_LOG_DEBUG` are optional. If removed, debug logs will be disabled ::: - -```bash -docker run -d \ - --name stacks_miner \ - --rm \ - --network host \ - -e RUST_BACKTRACE="full" \ - -e STACKS_LOG_DEBUG="1" \ - -v "$(pwd))/testnet/stacks-node/conf/testnet-miner-conf.toml:/src/stacks-node/testnet-miner-conf.toml" \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain:latest \ -/bin/stacks-node start --config /src/stacks-node/testnet-miner-conf.toml -``` - -You can review the node logs with this command: - -```bash -docker logs -f stacks_miner -``` - -## Optional: Running in Kubernetes with Helm - -In addition, you're also able to run a testnet node in a Kubernetes cluster using the [stacks-blockchain Helm chart](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). - -Ensure you have the following prerequisites installed on your machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [minikube](https://minikube.sigs.k8s.io/docs/start/) (Only needed if standing up a local Kubernetes cluster) -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [helm](https://helm.sh/docs/intro/install/) - -### Generate keychain and get some testnet tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` - -We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). - -### Install the chart and run the miner - -To install the chart with the release name `my-release` and run the node as a miner: - -```bash -minikube start # Only run this if standing up a local Kubernetes cluster -helm repo add blockstack https://charts.blockstack.xyz -helm install my-release blockstack/stacks-blockchain \ - --set config.node.miner=true \ - --set config.node.seed="replace-with-your-privateKey-from-generate-keychain-step" -``` - -You can review the node logs with this command: - -```bash -kubectl logs -l app.kubernetes.io/name=stacks-blockchain -``` - -For more information on the Helm chart and configuration options, please refer to the [chart's homepage](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). diff --git a/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md b/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md deleted file mode 100644 index 94d938c5ca..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md +++ /dev/null @@ -1,351 +0,0 @@ ---- -title: Run a node -description: Set up and run a Stacks node -sidebar_position: 1 -tags: - - tutorial ---- - -## Stacks Blockchain with Docker - -Run your own Stacks Blockchain node easily with just few commands. - -This tutorial describes a simple and effective [quickstart](#quickstart) to run a Stacks node using public scripts hosted in [Stacks Blockchain repository](https://github.com/stacks-network/stacks-blockchain-docker). Valid for mainnet, testnet and mocknet. - -## **Quickstart** - -1. **Clone the stacks-blockchain-docker repository locally** - -```bash -git clone https://github.com/stacks-network/stacks-blockchain-docker && cd stacks-blockchain-docker -``` - -2. **Optionally, create/copy `.env` file**. If file `.env` doesn't exist when launched it will be created from `sample.env` automatically. - -```bash -cp sample.env .env -``` - -_You may also use a symlink as an alternative to copying: `ln -s sample.env .env`_ - -3. **Optionally, ensure all images are up to date** - -```bash -./manage.sh -n -a pull -``` - -4. **Start the Services** - -```bash -./manage.sh -n -a start -``` - -- With optional proxy: - -```bash -./manage.sh -n -a start -f proxy -``` - -- With optional bitcoin node: - -```bash -./manage.sh -n -a start -f bitcoin -``` - -5. **Stop the Services** - -```bash -./manage.sh -n -a stop -``` - -6. **Retrieve Service Logs** - -```bash -./manage.sh -n -a logs -``` - -- Export docker log files to `./exported-logs`: - -This will create one log file for every running service, for example: postgres.log, stacks-blockain.log, stacks-blockchain-api.log and bitcoin-core.log. -Notice that each time you run this command the log files will be overwritten. - -```bash -./manage.sh -n -a logs export -``` - -7. **Restart all services** - -```bash -./manage.sh -n -a restart -``` - -- With optional proxy: - -```bash -./manage.sh -n -a restart -f proxy -``` - -8. **Delete** all data in `./persistent-data/` and/or data of the Bitcoin blockchain. - - This data is owned by root, so you will need to run it with sudo privileges so it can delete the data. - -```bash -$ sudo ./manage.sh -n -a reset - -Please confirm what persistent data you wish to delete: - -0. Cancel -1. Delete Persistent data for Stacks testnet only and leave Bitcoin blockchain data unaffected. -2. Delete Persistent data for Stacks testnet and Bitcoin blockchain data in ./persistent-data/blockchain-bitcoin -3. Delete Persistent data for Bitcoin blockchain data in ./persistent-data/blockchain-bitcoin only. -Please note that BNS data will never get deleted. - -Type 0, 1, 2 or 3: 2 - -Ok. Delete Stacks and Bitcoin data. -[ Success ] Persistent data deleted for Bitcoin blockchain. -[ Success ] Persistent data deleted for Stacks testnet. - -``` - -9. **Download BNS data to** `./persistent-data/bns-data` - -```bash -./manage.sh bns -``` - -10. **Export stacks-blockchain-api events** (_Not applicable for mocknet_) - -```bash -./manage.sh -n -a export -# check logs for completion -./manage.sh -n -a restart -``` - -11. **Replay stacks-blockchain-api events** (_Not applicable for mocknet_) - -```bash -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart -``` - -## **Running also a bitcoin node (Optional)** - -Stacks needs to use a Bitcoin node, and by default when you run a Stacks node you will be using a public Bitcoin node, which is configured in the `.env` file. Default values is `BITCOIN_NODE=bitcoin.mainnet.stacks.org`. - -However, you can optionaly run both nodes together and configured in a way that you Stacks node will use your own Bitcoin node instead of a public one. - -If you run the script with a bitcoin node it will download and build it directly from source for increased security. This process which only needs to happen once can take up to 20-30 minutes depending on the speed of your system. Also, once the bitcoin node is up and running it will need an additional time for sync for the first time (can be hours for testnet and days for mainnet). - -### Why run Stacks node with your own Bitcoin node? - -Because running your own Bitcoin node will give you higher security and improved perfomance. - -* **Improved perfomance**: The Bitcoin node will serve you blocks faster, as well as UTXOs for your miner (if you run one). -* **Higher security**: The Bitcoin node will also have validated all bitcoin transactions the Stacks node consumes. If you don't run your own Bitcoin node, you're relying on the SPV headers to vouch for the validity of Bitcoin blocks. - -The disadvantage of running your own Bitcoin node is that you need the extra space to store the Bitcoin blockchain (about 500GB) and the initial time it will take to download this data the first time. - -### Example - -You can run easily run your Stacks node with your own Bitcoin node by adding the flag `bitcoin`. This is available only for testnet and mainnet. - -Example: `./manage.sh -n mainnet -a start -f bitcoin` or `./manage.sh -n testnet -a start -f bitcoin` - -### Bitcoin node configuration - -In the `.env` file there is the variable `BITCOIN_BLOCKCHAIN_FOLDER`. As the bitcoin blockchain can be large (over 500GB) you optionally change this variable to any location of your choosing. If you have previously used the [bitcoin core application](https://bitcoin.org/en/bitcoin-core/) and already have the bitcoin blockchain synced, you can use the same data folder and avoid redownloading the entire bitcoin blockchain. - -## **Accessing the services** - -:::tip For networks other than `mocknet`, downloading the initial headers can take several minutes. Until the headers are downloaded, the `/v2/info` endpoints won't return any data. - -Use the command `./manage.sh -n -a logs` to check the sync progress. ::: - -**stacks-blockchain**: - -- Ports `20443-20444` are exposed to `localhost` - -```bash -curl -sL localhost:20443/v2/info | jq -``` - -**stacks-blockchain-api**: - -- Port `3999` are exposed to `localhost` - -```bash -curl -sL localhost:3999/v2/info | jq -``` - -**proxy**: - -- Port `80` is exposed to `localhost` - -```bash -curl -sL localhost/v2/info | jq -curl -sL localhost/ | jq -``` - ---- - -## Upgrades - -⚠️ For upgrades to running instances of this repo, you'll need to [run the event-replay](https://github.com/hirosystems/stacks-blockchain-api#event-replay): - -```bash -./manage.sh -n -a stop -./manage.sh -n -a export -./manage.sh -n -a import -./manage.sh -n -a restart -``` - ---- - -## **Workarounds to potential issues** - -_**Port(s) already in use**_: - -- 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. `3999` and edit your `.env` file to use the new port. - -```bash -netstat -anl | grep 3999 -``` - -``` -tcp46 0 0 *.3999 *.* LISTEN -``` - -_**Containers not starting (hanging on start)**_: - -- Occasionally, docker can get **stuck** and not allow new containers to start. If this happens, simply restart your docker daemon and try again. - -_**Database Issues**_: - -- For any of the various Postgres/sync issues, it may be easier to simply remove the persistent data dir. Note that doing so will result in a longer startup time as the data is repopulated. - -```bash -./manage.sh -n -a stop -./manage.sh -n -a reset -./manage.sh -n -a start -``` - -_**API Missing Parent Block Error**_: - -- If the Stacks blockchain is no longer syncing blocks, and the API reports an error similar to this:\ - `Error processing core node block message DB does not contain a parent block at height 1970 with index_hash 0x3367f1abe0ee35b10e77fbcaa00d3ca452355478068a0662ec492bb30ee0f13e"`,\ - The API (and by extension the DB) is out of sync with the blockchain. \ - The only known method to recover is to resync from genesis (**event-replay _may_ work, but in all likelihood will restore data to the same broken state**). - -- To attempt the event-replay - -```bash -./manage.sh -n -a stop -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart -``` - -- To wipe data and re-sync from genesis - -```bash -./manage.sh -n -a stop -./manage.sh -n -a reset -./manage.sh -n -a restart -``` - - -## **Requirements:** - -- [Docker](https://docs.docker.com/get-docker/) >= `17.09` -- [docker-compose](https://github.com/docker/compose/releases/) >= `1.27.4` -- [git](https://git-scm.com/downloads) -- [jq binary](https://stedolan.github.io/jq/download/) -- [sed](https://www.gnu.org/software/sed/) -- Machine with (at a minimum): - - 4GB memory - - 1 Vcpu - - 50GB storage (600GB if you optionally also run the bitcoin mainnet node) - -:::caution MacOS with an M1 processor is NOT recommended - -The way Docker for Mac on an Arm chip is designed makes the I/O incredibly slow, and blockchains are **_very_** heavy on I/O. This only seems to affect MacOS, other Arm based systems like Raspberry Pi's seem to work fine. - -::: - - -### Install/Update docker-compose - -:::note `docker-compose` executable is required, even though recent versions of Docker contain `compose` natively ::: - -- [Install Docker-compose](https://docs.docker.com/compose/install/) -- [Docker Desktop for Mac](https://docs.docker.com/docker-for-mac/install/) -- [Docker Desktop for Windows](https://docs.docker.com/docker-for-windows/install/) -- [Docker Engine for Linux](https://docs.docker.com/engine/install/#server) - -First, check if you have `docker-compose` installed locally. - -To do that, run this command in your terminal : - -```bash -docker-compose --version -``` - -Output should look something very similar to this : - -``` -docker-compose version 1.27.4, build 40524192 -``` - -If the command is not found, or the version is < `1.27.4`, run the following to install the latest to `/usr/local/bin/docker-compose`: - -```bash -#You will need to have jq installed, or this snippet won't run. -VERSION=$(curl --silent https://api.github.com/repos/docker/compose/releases/latest | jq .name -r) -DESTINATION=/usr/local/bin/docker-compose -sudo curl -L https://github.com/docker/compose/releases/download/${VERSION}/docker-compose-$(uname -s)-$(uname -m) -o $DESTINATION -sudo chmod 755 $DESTINATION -``` - -### Security note on docker - -The Docker daemon always runs as the root user so by default you will need root privileges to interact with it. - -The script `manage.sh` uses docker, so to avoid the requirement of needing to run the script with root privileges it is prefered to be able to *manage Docker as a non-root user*, following [these simple tests](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user). - -This will avoid the need of running the script with root privileges for all operations except the removal of data. - -### Configuration files you can edit - -The following files can be modified to personalize your node configuration, but generally most of them should be left as-is. All these files will be created from the sample copy if they don't exist at runtime (for example `.env` is created from `sample.env`). However these files will never be modified by the application once created and will never be pushed back to github, so your changes will be safe. - -* `.env` -* `./conf/mainnet/Config.toml` -* `./conf/mainnet/bitcoin.conf` -* `./conf/testnet/Config.toml` -* `./conf/testnet/bitcoin.conf` - -By default: - -- BNS data is **not** enabled/imported - - To enable, uncomment `# BNS_IMPORT_DIR=/bns-data` in `./env` - - Download BNS data: `./manage.sh bns` -- Fungible token metadata is **not** enabled - - To enable, uncomment `# STACKS_API_ENABLE_FT_METADATA=1` in `./env` -- Non-Fungible token metadata is **not** enabled - - To enable, uncomment `# STACKS_API_ENABLE_NFT_METADATA=1` in `./env` -- Verbose logging is **not** enabled - - To enable, uncomment `# VERBOSE=true` in `./env` -- Bitcoin blockchain folder is configured in `BITCOIN_BLOCKCHAIN_FOLDER` in `./env` - -### Local Data Dirs - -Directories will be created on first start that will store persistent data under `./persistent-data/` - -`` can be 1 of: - -- mainnet -- testnet -- mocknet diff --git a/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md b/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md deleted file mode 100644 index 8c268f3725..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md +++ /dev/null @@ -1,188 +0,0 @@ ---- -title: Running a mainnet node -description: Set up and run a mainnet node with Docker -sidebar_position: 3 -tags: - - tutorial ---- - -## Introducción - -This procedure demonstrates how to run a local mainnet node using Docker images. - -:::caution -This procedure focuses on Unix-like operating systems (Linux and MacOS). This procedure has not been tested on Windows. -::: - -## Prerrequisitos - -Running a node has no specialized hardware requirements. Users have been successful in running nodes on Raspberry Pi boards and other system-on-chip architectures. In order to complete this procedure, you must have the following software installed on the node host machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [curl](https://curl.se/download.html) -- [jq](https://stedolan.github.io/jq/download/) - -### Configuración del firewall - -In order for the API node services to work correctly, you must configure any network firewall rules to allow traffic on the ports discussed in this section. The details of network and firewall configuration are highly specific to your machine and network, so a detailed example isn't provided. - -The following ports must open on the host machine: - -Ingress: - -- stacks-blockchain (open to `0.0.0.0/0`): - - `20443 TCP` - - `20444 TCP` - -Egress: - -- `8332` -- `8333` -- `20443-20444` - -These egress ports are for syncing stacks-blockchain and Bitcoin headers. If they're not open, the sync will fail. - -## Paso 1: configuración inicial - -In order to run the mainnet node, you must download the Docker images and create a directory structure to hold the persistent data from the services. Download and configure the Docker images with the following commands: - -```sh -docker pull blockstack/stacks-blockchain -``` - -Create a directory structure for the service data with the following command: - -```sh -mkdir -p ./stacks-node/{persistent-data/stacks-blockchain/mainnet,config/mainnet} && cd stacks-node -``` - -## Paso 2: ejecutar Stacks blockchain - -First, create the `./config/mainnet/Config.toml` file and add the following content to the file using a text editor: - -```toml -[node] -working_dir = "/root/stacks-node/data" -rpc_bind = "0.0.0.0:20443" -p2p_bind = "0.0.0.0:20444" -bootstrap_node = "02da7a464ac770ae8337a343670778b93410f2f3fef6bea98dd1c3e9224459d36b@seed-0.mainnet.stacks.co:20444,02afeae522aab5f8c99a00ddf75fbcb4a641e052dd48836408d9cf437344b63516@seed-1.mainnet.stacks.co:20444,03652212ea76be0ed4cd83a25c06e57819993029a7b9999f7d63c36340b34a4e62@seed-2.mainnet.stacks.co:20444" -wait_time_for_microblocks = 10000 - -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "bitcoin.blockstack.com" -username = "blockstack" -password = "blockstacksystem" -rpc_port = 8332 -peer_port = 8333 - -[connection_options] -read_only_call_limit_write_length = 0 -read_only_call_limit_read_length = 100000 -read_only_call_limit_write_count = 0 -read_only_call_limit_read_count = 30 -read_only_call_limit_runtime = 1000000000 -``` - -Start the `stacks-blockchain` container with the following command: - -```sh -docker run -d --rm \ - --name stacks-blockchain \ - -v $(pwd)/persistent-data/stacks-blockchain/mainnet:/root/stacks-node/data \ - -v $(pwd)/config/mainnet:/src/stacks-node \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain \ -/bin/stacks-node start --config /src/stacks-node/Config.toml -``` - -You can verify the running `stacks-blockchain` container with the command: - -```sh -docker ps --filter name=stacks-blockchain -``` - -## Paso 3: verificar los servicios - -:::note -The initial burnchain header sync can take several minutes, until this is done the following commands will not work -::: - -To verify the `stacks-blockchain` burnchain header sync progress: - -```sh -docker logs stacks-blockchain -``` - -The output should be similar to the following: - -``` -INFO [1626290705.886954] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.2% (8000 out of 691034) -INFO [1626290748.103291] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.4% (10000 out of 691034) -INFO [1626290776.956535] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.7% (12000 out of 691034) -``` - -To verify the `stacks-blockchain` tip height is progressing use the following command: - -```sh -curl -sL localhost:20443/v2/info | jq -``` - -If the instance is running you should recieve terminal output similar to the following: - -```json -{ - "peer_version": 402653184, - "pox_consensus": "89d752034e73ed10d3b97e6bcf3cff53367b4166", - "burn_block_height": 666143, - "stable_pox_consensus": "707f26d9d0d1b4c62881a093c99f9232bc74e744", - "stable_burn_block_height": 666136, - "server_version": "stacks-node 2.0.11.1.0-rc1 (master:67dccdf, release build, linux [x86_64])", - "network_id": 1, - "parent_network_id": 3652501241, - "stacks_tip_height": 61, - "stacks_tip": "e08b2fe3dce36fd6d015c2a839c8eb0885cbe29119c1e2a581f75bc5814bce6f", - "stacks_tip_consensus_hash": "ad9f4cb6155a5b4f5dcb719d0f6bee043038bc63", - "genesis_chainstate_hash": "74237aa39aa50a83de11a4f53e9d3bb7d43461d1de9873f402e5453ae60bc59b", - "unanchored_tip": "74d172df8f8934b468c5b0af2efdefe938e9848772d69bcaeffcfe1d6c6ef041", - "unanchored_seq": 0, - "exit_at_block_height": null -} -``` - -## Detener el nodo mainnet - -Use the following commands to stop the local mainnet node: - -```sh -docker stop stacks-blockchain -``` - -## Opcional. Ejecutar un nodo de stacks con su propio nodo bitcoin - -It's encouraged to use your own bitcoin node when possible. - -To do this simply update the `stacks-node/config/mainnet/Config.toml` file with the details of your bitcoin node. For example: - -``` -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "localhost" -username = "rpc username" -password = "rpc password" -rpc_port = 8332 -peer_port = 8333 -``` - -The rpc configuration of your bitcoin node is out of the scope of this document, but you can find more information on how to set it up [here](https://developer.bitcoin.org/examples/intro.html). - -## Lecturas adicionales - - - -- [Running a Stacks API node](https://docs.hiro.so/get-started/running-api-node) -- [Running a Stacks testnet node](running-testnet-node) - diff --git a/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md b/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md deleted file mode 100644 index d30851f979..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: Ejecutar un nodo testnet -description: Configurar y ejecutar un nodo testnet con Docker -sidebar_position: 2 -tags: - - tutorial ---- - -## Introducción - -Este procedimiento demuestra cómo ejecutar un nodo local testnet usando imágenes Docker. - -:::caution -Este procedimiento se centra en sistemas operativos de tipo Unix (Linux y MacOS). Este procedimiento no ha sido probado en Windows. -::: - -## Pre requisitos - -Ejecutar un nodo no tiene requerimientos de hardware especiales. Los usuarios han tenido éxito ejecutando nodos en las dispostivos Raspberry Pi y otras arquitecturas de sistema on-chip. Para completar este procedimiento, debe tener instalado el siguiente software: - -- [Docker](https://docs.docker.com/get-docker/) -- [curl](https://curl.se/download.html) -- [jq](https://stedolan.github.io/jq/download/) - -### Configuración del firewall - -Para que los servicios del nodo API funcionen correctamente, debe configurar cualquier regla de firewall de red para permitir el tráfico en los puertos discutidos en esta sección. Los detalles de la configuración de red y firewall son muy específicos para su máquina y red, por lo que no se proporciona un ejemplo detallado. - -Los siguientes puertos deben abrirse en la máquina host: - -Entrada: - -- stacks-blockchain (abierto a `0.0.0.0/0`): - - `20443 TCP` - - `20444 TCP` - -Salida: - -- `18332` -- `18333` -- `20443-20444` - -These egress ports are for syncing stacks-blockchain and Bitcoin headers. Si no están abiertos, la sincronización fallará. - -## Paso 1: configuración inicial - -In order to run the testnet node, you must download the Docker images and create a directory structure to hold the persistent data from the services. Download and configure the Docker images with the following commands: - -```sh -docker pull blockstack/stacks-blockchain -``` - -Create a directory structure for the service data with the following command: - -```sh -mkdir -p ./stacks-node/persistent-data/stacks-blockchain/testnet && cd stacks-node -``` - -## Paso 2: ejecutar Stacks blockchain - -Start the stacks-blockchain container with the following command: - -```sh -docker run -d --rm \ - --name stacks-blockchain \ - -v $(pwd)/persistent-data/stacks-blockchain/testnet:/root/stacks-node/data \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain \ -/bin/stacks-node testnet -``` - -You can verify the running stacks-blockchain container with the command: - -```sh -docker ps --filter name=stacks-blockchain -``` - -## Paso 3: verificar los servicios - -:::info -The initial burnchain header sync can take several minutes, until this is done the following commands will not work -::: - -To verify the stacks-blockchain burnchain header sync progress: - -```sh -docker logs stacks-blockchain -``` - -The output should be similar to the following: - -``` -INFO [1626290705.886954] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.2% (8000 out of 2034380) -INFO [1626290748.103291] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.4% (10000 out of 2034380) -INFO [1626290776.956535] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.7% (12000 out of 2034380) -``` - -To verify the stacks-blockchain tip height is progressing use the following command: - -```sh -curl -sL localhost:20443/v2/info | jq -``` - -If the instance is running you should recieve terminal output similar to the following: - -```json -{ - "peer_version": 4207599105, - "pox_consensus": "12f7fa85e5099755a00b7eaecded1aa27af61748", - "burn_block_height": 2034380, - "stable_pox_consensus": "5cc4e0403ff6a1a4bd17dae9600c7c13d0b10bdf", - "stable_burn_block_height": 2034373, - "server_version": "stacks-node 2.0.11.2.0-rc1 (develop:7b6d3ee+, release build, linux [x86_64])", - "network_id": 2147483648, - "parent_network_id": 118034699, - "stacks_tip_height": 509, - "stacks_tip": "e0ee952e9891709d196080ca638ad07e6146d4c362e6afe4bb46f42d5fe584e8", - "stacks_tip_consensus_hash": "12f7fa85e5099755a00b7eaecded1aa27af61748", - "genesis_chainstate_hash": "74237aa39aa50a83de11a4f53e9d3bb7d43461d1de9873f402e5453ae60bc59b", - "unanchored_tip": "32bc86590f11504f17904ee7f5cb05bcf71a68a35f0bb3bc2d31aca726090842", - "unanchored_seq": 0, - "exit_at_block_height": null -} -``` - -## Detener el nodo testnet - -Utilice los siguientes comandos para detener el nodo local testnet: - -```sh -docker stop stacks-blockchain -``` - -## Lecturas adicionales - - - -- [Ejecutar un nodo API de Stacks](https://docs.hiro.so/get-started/running-api-node) -- [Ejecutando un nodo Stacks mainnet](running-mainnet-node) - diff --git a/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md b/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md deleted file mode 100644 index ea61c808e0..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md +++ /dev/null @@ -1,506 +0,0 @@ ---- -title: Configuración del nodo de Stacks -description: Parámetros de configuración y opciones para el binario stacks-node -sidebar_position: 6 ---- - -## Uso - -```bash -stacks-node sub-command [--subcommand-option ] -``` - -## Subcomandos - -:::caution The `stacks-node` binary may have deprecated commands that are not documented on this page. Los comandos obsoletos pueden ser accesibles hasta que sean eliminados completamente del código fuente. ::: - -### mocknet - -Start a node based on a fast local setup emulating a burnchain. Ideal for smart contract development. - -Ejemplo: - -```bash -stacks-node mocknet -``` - -### krypton - -Start a node that will join and stream blocks from the public krypton regtest, powered by Blockstack via [Proof of Transfer](../understand-stacks#consensus-mechanism). - -Ejemplo: - -```bash -stacks-node krypton -``` - -### testnet - -Start a node that will join and stream blocks from the public testnet. - -Ejemplo: - -```bash -stacks-node testnet -``` - -### mainnet - -Start a node that joins and streams blocks from the public mainnet. - -Ejemplo: - -```bash -stacks-node mainnet -``` - -### start - -Start a node with a config of your own. Can be used for joining a network, starting a new chain, or replacing default values used by the `mocknet` or `testnet` subcommands. - -#### Argumentos - -**--config**: relative or absolute path to the TOML config file. Required. - -Ejemplo: - -```bash -stacks-node start --config=/path/to/config.toml -``` - -See [Configuration File Options](#configuration-file-options) for more information. - -#### version - -Muestra información sobre la versión actual y el ciclo de lanzamiento. - -Ejemplo: - -```bash -stacks-node version -``` - -#### help - -Muestra un mensaje de ayuda. - -Ejemplo: - -```bash -stacks-node help -``` - -## Opciones de configuración - -The TOML configuration file has multiple sections under which an option may be placed. - -To see a list of example configurations, [please see this page](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf). - -### Sección: node - -Contains various configuration options pertaining to the stacks-node. - -Ejemplo: - -```toml -[node] -rpc_bind = "0.0.0.0:20443" -p2p_bind = "0.0.0.0:20444" -# Enter your private key here -seed = "replace-with-your-private-key" -miner = true -``` - -#### working_dir (optional) - -Absolute path to the directory which the stacks-node will use for storing various data. - -Ejemplo: - -```toml -working_dir = "/root/stacks-node" -``` - -#### rpc_bind - -Address and port stacks-node should bind to for RPC connections. - -Ejemplo: - -```toml -rpc_bind = "0.0.0.0:20443" -``` - -#### p2p_bind - -Address and port stacks-node should bind to for P2P connections. - -Ejemplo: - -```toml -p2p_bind = "0.0.0.0:20444" -``` - -#### data_url (optional) - -Address and port from which the stacks-node will be receiving incoming rpc connections. - -Ejemplo: - -```toml -data_url = "1.2.3.4:20443" -``` - -#### p2p_address (optional) - -Address and port from which the stacks-node will be receiving incoming p2p connections. - -Ejemplo: - -```toml -p2p_address = "1.2.3.4:20444" -``` - -#### bootstrap_node (optional) - -Public key, address, and port stacks-node should use to pull transaction data from when starting. - -Ejemplo: - -```toml -bootstrap_node = "047435c194e9b01b3d7f7a2802d6684a3af68d05bbf4ec8f17021980d777691f1d51651f7f1d566532c804da506c117bbf79ad62eea81213ba58f8808b4d9504ad@testnet.blockstack.org:20444" -``` - -#### wait_time_for_microblocks (optional) - -The amount of time (in milliseconds) that a node will wait before trying to mine a block, after catching up to the anchored chain tip. This gives the current leader time to broadcast microblocks that will get included in that mined block. - -Ejemplo: - -```toml -wait_time_for_microblocks = 15000 -``` - -#### seed (optional) - -The private key to use for mining. Only needed if `miner` is set to `true`. - -Ejemplo: - -```toml -seed = "replace-with-your-private-key" -``` - -#### local_peer_seed (optional) - -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. - -Ejemplo: - -```toml -local_peer_seed = "replace-with-your-private-key" -``` - -#### miner (optional) - -Determines whether the stacks-node is running a follower (`false`) or a miner (`true`). Defaults to `false` if omitted. - -Ejemplo: - -```toml -miner = true -``` - -#### mine_microblocks (optional) - -Determines whether the stacks-node will mine microblocks. Will only take effect if `miner` is set to `true`. - -Ejemplo: - -```toml -mine_microblocks = true -``` - -#### prometheus_bind (optional) - -Address and port stacks-node should open for Prometheus metrics collection. - -Ejemplo: - -```toml -prometheus_bind = "0.0.0.0:9153" -``` - -### Section: events_observer (optional) - -Contains options for watching events emitted by a local [stacks-blockchain-api](https://github.com/hirosystems/stacks-blockchain-api) service. - -:::info -This section can be repeated multiple times. -::: - -Ejemplo: - -```toml -[[events_observer]] -endpoint = "address-to-my-local.stacks-node-api.com:3700" -retry_count = 255 -events_keys = ["*"] -``` - -#### endpoint - -Address and port to a stacks-node-api to watch for events. - -Ejemplo: - -```toml -endpoint = "address-to-my-local.stacks-node-api.com:3700" -``` - -#### retry_count - -Number of times to retry sending events to the endpoint before failing. - -Ejemplo: - -```toml -retry_count = 255 -``` - -#### events_keys - -Event keys for which to watch. The emitted node events can be restricted by account, function name and event type. Asterix ("\*") can be used to emit all events. - -Examples: - -```toml -events_keys = ["*"] -``` - -```toml -events_keys = [ - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.store::print", - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.contract.ft-token", - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.contract.nft-token", - "stx" -] -``` - -### Section: connection_options (optional) - -Specifies configuration options for others connecting to the stacks node. - -Ejemplo: - -```toml -[connection_options] -public_ip_address = "1.2.3.4:20444" -download_interval = 60 -walk_interval = 30 -``` - -#### public_ip_address - -The advertised public IP of this stacks-node. - -Ejemplo: - -```toml -public_ip_address = "1.2.3.4:20444" -``` - -#### download_interval - -Time (in seconds) between attempts to download blocks. - -Ejemplo: - -```toml -download_interval = 60 -``` - -#### walk_interval - -Time (in seconds) between attempts to walk the neighborhood. - -Ejemplo: - -```toml -walk_interval = 30 -``` - -#### read_only_call_limit_read_length - -Total number of bytes allowed to be read by an individual read-only function call. - -Ejemplo: - -```toml -read_only_call_limit_read_length = 100000 -``` - -#### read_only_call_limit_read_count - -Total number of independent read operations permitted for an individual read-only function call. - -Ejemplo: - -```toml -read_only_call_limit_read_count = 30 -``` - -#### read_only_call_limit_runtime - -[Runtime cost](https://github.com/stacksgov/sips/blob/2d3fd9bf8da7a04f588d90ff6252173d7609d7bf/sips/sip-006/sip-006-runtime-cost-assessment.md#introduction) limit for an individual read-only function call. - -Ejemplo: - -```toml -read_only_call_limit_runtime = 1000000000 -``` - -### Sección: burnchain - -This section contains configuration options pertaining to the blockchain the stacks-node binds to on the backend for proof-of-transfer (BTC). - -Ejemplo: - -```toml -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "your.bitcoind.node.org" -rpc_port = 8332 -peer_port = 8333 -``` - -#### chain - -The blockchain stacks-node binds to on the backend for proof-of-transfer. Only value supported: `"bitcoin"`. - -Ejemplo: - -```toml -chain = "bitcoin" -``` - -#### mode - -The profile or test phase of which to run stacks-node. Valid values are `"mocknet"`, `"helium"`, `"neon"`, `"argon"`, `"krypton"`, `"xenon"`. - -Ejemplo: - -```toml -mode = "xenon" -``` - -#### peer_host - -Domain name of the host running the backend Bitcoin blockchain. It's required to either run a personal Bitcoin node locally, or to use a publicly hosted Bitcoin node. - -Ejemplo: - -```toml -peer_host = "your.bitcoind.node.org" -``` - -#### rpc_port - -peer_host's port stacks-node will connect to for RPC connections. - -Ejemplo: - -```toml -rpc_port = 8332 -``` - -#### peer_port - -peer_host's port stacks-node will connect to for P2P connections. - -Ejemplo: - -```toml -peer_port = 8333 -``` - -#### burn_fee_cap (optional) - -Maximum amount (in Satoshis) of "burn commitment" to broadcast for the next block's leader election. - -Ejemplo: - -```toml -burn_fee_cap = 30000 -``` - -#### satoshis_per_byte (optional) - -Amount (in Satoshis) per [virtual byte](https://en.bitcoin.it/wiki/Weight_units). This is used to compute the transaction fees. - -Ejemplo: - -```toml -satoshis_per_byte = 50 -``` - -So total transaction cost would be `(estimated_tx_size * satoshis_per_byte) + burn_fee_cap`. - -#### commit_anchor_block_within (optional) - -Sets the time period (in milliseconds) for commitments. Only used when `mode` is set to `"helium"`. - -Ejemplo: - -```toml -commit_anchor_block_within = 10000 -``` - -### Section: ustx_balance (testnet/regtest only) - -This section contains configuration options pertaining to the genesis block allocation for an address in micro-STX. If a user changes these values, their node may be in conflict with other nodes on the network and find themselves unable to sync with other nodes. - -:::info -This section can repeat multiple times, and thus is in double-brackets. Each section can define only one address. This section is ignored if running a node on mainnet. -::: - -Ejemplo: - -```toml -[[ustx_balance]] -address = "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6" -amount = 10000000000000000 - -[[ustx_balance]] -address = "ST11NJTTKGVT6D1HY4NJRVQWMQM7TVAR091EJ8P2Y" -amount = 10000000000000000 - -[[ustx_balance]] -address = "ST1HB1T8WRNBYB0Y3T7WXZS38NKKPTBR3EG9EPJKR" -amount = 10000000000000000 - -[[ustx_balance]] -address = "STRYYQQ9M8KAF4NS7WNZQYY59X93XEKR31JP64CP" -amount = 10000000000000000 -``` - -#### address - -Dirección que mantiene un balance micro-STX. - -Ejemplo: - -```toml -address = "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6" -``` - -#### amount - -El balance de micro-STX dado a la dirección al arranque del nodo. - -Ejemplo: - -```toml -amount = 10000000000000000 -``` diff --git a/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md b/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md deleted file mode 100644 index 094e3f03a1..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Verify Miner -description: Verify node is operating as miner -sidebar_position: 7 ---- - -You can verify that your node is operating as a miner by checking its log output to verify that it was able to find its Bitcoin UTXOs: - -```bash -$ head -n 100 /path/to/your/node/logs | grep -i utxo -INFO [1630127492.031042] [testnet/stacks-node/src/run_loop/neon.rs:146] [main] Miner node: checking UTXOs at address: -INFO [1630127492.062652] [testnet/stacks-node/src/run_loop/neon.rs:164] [main] UTXOs found - will run as a Miner node -``` \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json b/i18n/es/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json deleted file mode 100644 index 14b520b34d..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Contratos destacables", - "position": 4, - "link": { - "type": "generated-index", - "description": "Contratos específicos desplegados en Clarity que son dignos de mención." - } -} \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md b/i18n/es/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md deleted file mode 100644 index 734d6f2231..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md +++ /dev/null @@ -1,362 +0,0 @@ ---- -title: Contrato BNS -description: The Blockchain Naming System. ---- - -![](/img/satoshi-btc.png) - -## Introducción - -El Blockchain Naming System (BNS) se implementa como un contrato inteligente usando Clarity. - -A continuación se muestra una lista de funciones públicas y de sólo lectura así como códigos de error que pueden ser devueltos por esos métodos: -* [Funciones públicas](#public-functions) -* [Funciones de solo lectura](#read-only-functions) -* [Códigos de error](#error-codes) - -## Funciones públicas - - -### name-import - -#### Input: `(buff 20), (buff 48), principal, (buff 20)` -#### Output: `(response bool int)` -#### Firma: `(name-import namespace name beneficiary zonefile-hash)` -#### Descripción: -Importa nombre a un namespace revelado. Cada nombre importado recibe tanto un propietario como un estado fuera de la cadena. - -### name-preorder - -#### Input: `(buff 20), uint` -#### Output: `(response uint int)` -#### Firma: `(name-preorder hashed-salted-fqn stx-to-burn)` -#### Descripción: -Preordena un nombre diciendo a todos los nodos BNS el hash salt del nombre BNS. Se paga la cuota de registro a la dirección designada por el propietario del espacio de nombres. - -### name-register - -#### Input: `(buff 20), (buff 48), (buff 20), (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-register namespace name salt zonefile-hash)` -#### Descripción: -Revela la salt y el nombre a todos los nodos BNS, y asigna a el nombre un hash de clave pública inicial y un hash del archivo de zona. - -### name-renewal - -#### Input: `(buff 20), (buff 48), uint, (optional principal), (optional (buff 20))` -#### Output: `(response bool int)` -#### Signature: `(name-renewal namespace name stx-to-burn new-owner zonefile-hash)` -#### Descripción: -Depending in the namespace rules, a name can expire. For example, names in the .id namespace expire after 2 years. You need to send a name renewal every so often to keep your name. - -You will pay the registration cost of your name to the namespace's designated burn address when you renew it. When a name expires, it enters a \"grace period\". The period is set to 5000 blocks (a month) but can be configured for each namespace. - -It will stop resolving in the grace period, and all of the above operations will cease to be honored by the BNS consensus rules. You may, however, send a NAME_RENEWAL during this grace period to preserve your name. After the grace period, everybody can register that name again. If your name is in a namespace where names do not expire, then you never need to use this transaction. -### name-revoke - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(name-revoke namespace name)` -#### Descripción: -Makes a name unresolvable. The BNS consensus rules stipulate that once a name is revoked, no one can change its public key hash or its zone file hash. The name's zone file hash is set to null to prevent it from resolving. You should only do this if your private key is compromised, or if you want to render your name unusable for whatever reason. - -### name-transfer - -#### Input: `(buff 20), (buff 48), principal, (optional (buff 20))` -#### Output: `(response bool int)` -#### Signature: `(name-transfer namespace name new-owner zonefile-hash)` -#### Descripción: -Changes the name's public key hash. You would send a name transfer transaction if you wanted to: -* Change your private key -* Send the name to someone else or -* Update your zone file - -When transferring a name, you have the option to also clear the name's zone file hash (i.e. set it to null). This is useful for when you send the name to someone else, so the recipient's name does not resolve to your zone file. - -### name-update - -#### Input: `(buff 20), (buff 48), (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-update namespace name zonefile-hash)` -#### Descripción: -Changes the name's zone file hash. You would send a name update transaction if you wanted to change the name's zone file contents. For example, you would do this if you want to deploy your own Gaia hub and want other people to read from it. - -### namespace-preorder - -#### Input: `(buff 20), uint` -#### Output: `(response uint int)` -#### Signature: `(namespace-preorder hashed-salted-namespace stx-to-burn)` -#### Descripción: -Registers the salted hash of the namespace with BNS nodes, and burns the requisite amount of cryptocurrency. Additionally, this step proves to the BNS nodes that user has honored the BNS consensus rules by including a recent consensus hash in the transaction. Returns pre-order's expiration date (in blocks). - -### namespace-ready - -#### Input: `(buff 20)` -#### Output: `(response bool int)` -#### Signature: `(namespace-ready namespace)` -#### Descripción: -Launches the namespace and makes it available to the public. Once a namespace is launched, anyone can register a name in it if they pay the appropriate amount of cryptocurrency. - -### namespace-reveal - -#### Input: `(buff 20), (buff 20), uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, principal` -#### Output: `(response bool int)` -#### Signature: `(namespace-reveal namespace namespace-salt p-func-base p-func-coeff p-func-b1 p-func-b2 p-func-b3 p-func-b4 p-func-b5 p-func-b6 p-func-b7 p-func-b8 p-func-b9 p-func-b10 p-func-b11 p-func-b12 p-func-b13 p-func-b14 p-func-b15 p-func-b16 p-func-non-alpha-discount p-func-no-vowel-discount lifetime namespace-import)` -#### Descripción: -Reveals the salt and the namespace ID (after a namespace preorder). It reveals how long names last in this namespace before they expire or must be renewed, and it sets a price function for the namespace that determines how cheap or expensive names its will be. All of the parameters prefixed by `p` make up the `price function`. These parameters govern the pricing and lifetime of names in the namespace. - -The rules for a namespace are as follows: - -* a name can fall into one of 16 buckets, measured by length. Bucket 16 incorporates all names at least 16 characters long. - -* the pricing structure applies a multiplicative penalty for having numeric characters, or punctuation characters. - -* the price of a name in a bucket is `((coeff) * (base) ^ (bucket exponent)) / ((numeric discount multiplier) * (punctuation discount multiplier))` - -Ejemplo: - -* base = 10 -* coeff = 2 -* nonalpha discount: 10 -* no-vowel discount: 10 -* buckets 1, 2: 9 -* buckets 3, 4, 5, 6: 8 -* buckets 7, 8, 9, 10, 11, 12, 13, 14: 7 -* buckets 15, 16+: - - -## Funciones de solo lectura - -### can-name-be-registered - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(can-name-be-registered namespace name)` -#### Descripción: -Returns true if the provided name can be registered. - -### can-namespace-be-registered - -#### Input: `(buff 20)` -#### Output: `(response bool UnknownType)` -#### Signature: `(can-namespace-be-registered namespace)` -#### Descripción: -Returns true if the provided namespace is available. - -### can-receive-name - -#### Input: `principal` -#### Output: `(response bool int)` -#### Signature: `(can-receive-name owner)` -#### Descripción: -Returns true if the provided name can be received. That is, if it is not curretly owned, a previous lease is expired, and the name wasn't revoked. - -### get-name-price - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response uint int)` -#### Signature: `(get-name-price namespace name)` -#### Descripción: -Gets the price for a name. - -### get-namespace-price - -#### Input: `(buff 20)` -#### Output: `(response uint int)` -#### Signature: `(get-namespace-price namespace)` -#### Descripción: -Gets the price for a namespace. - -### get-namespace-properties - -#### Input: `(buff 20)` -#### Output: `(response (tuple (namespace (buff 20)) (properties (tuple (can-update-price-function bool) (launched-at (optional uint)) (lifetime uint) (namespace-import principal) (price-function (tuple (base uint) (buckets (list 16 uint)) (coeff uint) (no-vowel-discount uint) (nonalpha-discount uint))) (revealed-at uint)))) int)` -#### Signature: `(get-namespace-properties namespace)` -#### Descripción: -Get namespace properties. - -### is-name-lease-expired - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(is-name-lease-expired namespace name)` -#### Descripción: -Return true if the provided name lease is expired. - -### name-resolve - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response (tuple (lease-ending-at (optional uint)) (lease-started-at uint) (owner principal) (zonefile-hash (buff 20))) int)` -#### Signature: `(name-resolve namespace name)` -#### Descripción: -Get name registration details. - -### resolve-principal - -#### Input: `principal` -#### Output: `(response (tuple (name (buff 48)) (namespace (buff 20))) (tuple (code int) (name (optional (tuple (name (buff 48)) (namespace (buff 20)))))))` -#### Signature: `(resolve-principal owner)` -#### Descripción: -Returns the registered name that a principal owns if there is one. A principal can only own one name at a time. - -## Códigos de error - -### ERR_INSUFFICIENT_FUNDS -#### type: `int` -#### value: `4001` - -### ERR_NAMESPACE_ALREADY_EXISTS -#### type: `int` -#### value: `1006` - -### ERR_NAMESPACE_ALREADY_LAUNCHED -#### type: `int` -#### value: `1014` - -### ERR_NAMESPACE_BLANK -#### type: `int` -#### value: `1013` - -### ERR_NAMESPACE_CHARSET_INVALID -#### type: `int` -#### value: `1016` - -### ERR_NAMESPACE_HASH_MALFORMED -#### type: `int` -#### value: `1015` - -### ERR_NAMESPACE_NOT_FOUND -#### type: `int` -#### value: `1005` - -### ERR_NAMESPACE_NOT_LAUNCHED -#### type: `int` -#### value: `1007` - -### ERR_NAMESPACE_OPERATION_UNAUTHORIZED -#### type: `int` -#### value: `1011` - -### ERR_NAMESPACE_PREORDER_ALREADY_EXISTS -#### type: `int` -#### value: `1003` - -### ERR_NAMESPACE_PREORDER_CLAIMABILITY_EXPIRED -#### type: `int` -#### value: `1009` - -### ERR_NAMESPACE_PREORDER_EXPIRED -#### type: `int` -#### value: `1002` - -### ERR_NAMESPACE_PREORDER_LAUNCHABILITY_EXPIRED -#### type: `int` -#### value: `1010` - -### ERR_NAMESPACE_PREORDER_NOT_FOUND -#### type: `int` -#### value: `1001` - -### ERR_NAMESPACE_PRICE_FUNCTION_INVALID -#### type: `int` -#### value: `1008` - -### ERR_NAMESPACE_STX_BURNT_INSUFFICIENT -#### type: `int` -#### value: `1012` - -### ERR_NAMESPACE_UNAVAILABLE -#### type: `int` -#### value: `1004` - -### ERR_NAME_ALREADY_CLAIMED -#### type: `int` -#### value: `2011` - -### ERR_NAME_BLANK -#### type: `int` -#### value: `2010` - -### ERR_NAME_CHARSET_INVALID -#### type: `int` -#### value: `2022` - -### ERR_NAME_CLAIMABILITY_EXPIRED -#### type: `int` -#### value: `2012` - -### ERR_NAME_COULD_NOT_BE_MINTED -#### type: `int` -#### value: `2020` - -### ERR_NAME_COULD_NOT_BE_TRANSFERED -#### type: `int` -#### value: `2021` - -### ERR_NAME_EXPIRED -#### type: `int` -#### value: `2008` - -### ERR_NAME_GRACE_PERIOD -#### type: `int` -#### value: `2009` - -### ERR_NAME_HASH_MALFORMED -#### type: `int` -#### value: `2017` - -### ERR_NAME_NOT_FOUND -#### type: `int` -#### value: `2013` - -### ERR_NAME_NOT_RESOLVABLE -#### type: `int` -#### value: `2019` - -### ERR_NAME_OPERATION_UNAUTHORIZED -#### type: `int` -#### value: `2006` - -### ERR_NAME_PREORDERED_BEFORE_NAMESPACE_LAUNCH -#### type: `int` -#### value: `2018` - -### ERR_NAME_PREORDER_ALREADY_EXISTS -#### type: `int` -#### value: `2016` - -### ERR_NAME_PREORDER_EXPIRED -#### type: `int` -#### value: `2002` - -### ERR_NAME_PREORDER_FUNDS_INSUFFICIENT -#### type: `int` -#### value: `2003` - -### ERR_NAME_PREORDER_NOT_FOUND -#### type: `int` -#### value: `2001` - -### ERR_NAME_REVOKED -#### type: `int` -#### value: `2014` - -### ERR_NAME_STX_BURNT_INSUFFICIENT -#### type: `int` -#### value: `2007` - -### ERR_NAME_TRANSFER_FAILED -#### type: `int` -#### value: `2015` - -### ERR_NAME_UNAVAILABLE -#### type: `int` -#### value: `2004` - -### ERR_PANIC -#### type: `int` -#### value: `0` - -### ERR_PRINCIPAL_ALREADY_ASSOCIATED -#### type: `int` -#### value: `3001` diff --git a/i18n/es/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md b/i18n/es/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md deleted file mode 100644 index 27677548f2..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -title: Contrato de Stacking -description: Vea una lista detallada de todas las funciones y códigos de error del contrato de Stacking. ---- - -## Introducción - -El Stacking se implementa como un contrato inteligente utilizando Clarity. Siempre puede encontrar el identificador de contrato de Stacking usando el API de Stacks Blockchain [`v2/pox` endpoint](https://docs.hiro.so/api#operation/get_pox_info). - -A continuación se muestra una lista de funciones públicas y de sólo lectura así como códigos de error que pueden ser devueltos por esos métodos: - -* [Funciones públicas](#public-functions) -* [Funciones de solo lectura](#read-only-functions) -* [Códigos de error](#error-codes) - -## Funciones públicas - -### allow-contract-caller -#### input: `principal, (optional uint)` -#### output: `(response bool int)` -#### signature: `(allow-contract-caller caller until-burn-ht)` -#### descripción: -Give a contract-caller authorization to call stacking methods. Normally, stacking methods may only be invoked by _direct_ transactions (i.e., the `tx-sender` issues a direct `contract-call` to the stacking methods). - -By issuing an allowance, the tx-sender may call through the allowed contract. - -### delegate-stack-stx -#### input: `principal, uint, (tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint` -#### output: `(response (tuple (lock-amount uint) (stacker principal) (unlock-burn-height uint)) int)` -#### signature: `(delegate-stack-stx stacker amount-ustx pox-addr start-burn-ht lock-period)` -#### descripción: -As a delegate, stack the given principal's STX using `partial-stacked-by-cycle`. - -Once the delegate has stacked > minimum, the delegate should call `stack-aggregation-commit`. - -### delegate-stx -#### input: `uint, principal, (optional uint), (optional (tuple (hashbytes (buff 20)) (version (buff 1))))` -#### output: `(response bool int)` -#### signature: `(delegate-stx amount-ustx delegate-to until-burn-ht pox-addr)` -#### descripción: -Delegate to `delegate-to` the ability to stack from a given address. - -This method _does not_ lock the funds, rather, it allows the delegate to issue the stacking lock. - -The caller specifies: - -* amount-ustx: the total amount of ustx the delegate may be allowed to lock -* until-burn-ht: an optional burn height at which this delegation expiration -* pox-addr: an optional p2pkh or p2sh address to which any rewards *must* be sent - -### disallow-contract-caller -#### input: `principal` -#### output: `(response bool int)` -#### signature: `(disallow-contract-caller caller)` -#### descripción: -Revokes authorization from a contract to invoke stacking methods through contract-calls - -### reject-pox -#### entrada: -#### output: `(response bool int)` -#### signature: `(reject-pox)` -#### descripción: -Reject Stacking for this reward cycle. - -`tx-sender` votes all its uSTX for rejection. - -Note that unlike Stacking, rejecting PoX does not lock the tx-sender's tokens: PoX rejection acts like a coin vote. - -### revoke-delegate-stx -#### entrada: -#### output: `(response bool int)` -#### signature: `(revoke-delegate-stx)` -#### descripción: -Revoke a Stacking delegate relationship. A particular Stacker may only have one delegate, so this method does not take any parameters, and just revokes the Stacker's current delegate (if one exists). - -### stack-aggregation-commit -#### input: `(tuple (hashbytes (buff 20)) (version (buff 1))), uint` -#### output: `(response bool int)` -#### signature: `(stack-aggregation-commit pox-addr reward-cycle)` -#### descripción: -Commit partially stacked STX. - -This allows a stacker/delegate to lock fewer STX than the minimal threshold in multiple transactions, - -so long as: - -1. The pox-addr is the same. -2. This \"commit\" transaction is called _before_ the PoX anchor block. - -This ensures that each entry in the reward set returned to the stacks-node is greater than the threshold, - - but does not require it be all locked up within a single transaction - -### stack-stx -#### input: `uint, (tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint` -#### output: `(response (tuple (lock-amount uint) (stacker principal) (unlock-burn-height uint)) int)` -#### signature: `(stack-stx amount-ustx pox-addr start-burn-ht lock-period)` -#### descripción: -Lock up some uSTX for stacking! Note that the given amount here is in micro-STX (uSTX). - -The STX will be locked for the given number of reward cycles (lock-period). - -This is the self-service interface. tx-sender will be the Stacker. - -* The given stacker cannot currently be stacking. -* You will need the minimum uSTX threshold. This isn't determined until the reward cycle begins, but this method still requires stacking over the _absolute minimum_ amount, which can be obtained by calling `get-stacking-minimum`. -* The pox-addr argument must represent a valid reward address. Right now, this must be a Bitcoin p2pkh or p2sh address. It cannot be a native Segwit address, but it may be a p2wpkh-p2sh or p2wsh-p2sh address. - -The tokens will unlock and be returned to the Stacker (tx-sender) automatically. - -## Funciones de solo lectura - -### can-stack-stx -#### input: `(tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint, uint` -#### output: `(response bool int)` -#### signature: `(can-stack-stx pox-addr amount-ustx first-reward-cycle num-cycles)` -#### descripción: -Evaluate if a participant can stack an amount of STX for a given period. - -### get-pox-info -#### entrada: -#### output: `(response (tuple (current-rejection-votes uint) (first-burnchain-block-height uint) (min-amount-ustx uint) (prepare-cycle-length uint) (rejection-fraction uint) (reward-cycle-id uint) (reward-cycle-length uint) (total-liquid-supply-ustx uint)) UnknownType)` -#### signature: `(get-pox-info)` -#### descripción: -Returns information about PoX status. - -### get-pox-rejection -#### input: `principal, uint` -#### output: `(optional (tuple (amount uint)))` -#### signature: `(get-pox-rejection stacker reward-cycle)` -#### descripción: -Returns the amount of uSTX that a given principal used to reject a PoX cycle. - -### get-stacker-info -#### input: `principal` -#### output: `(optional (tuple (amount-ustx uint) (first-reward-cycle uint) (lock-period uint) (pox-addr (tuple (hashbytes (buff 20)) (version (buff 1))))))` -#### signature: `(get-stacker-info stacker)` -#### descripción: -Returns the _current_ stacking information for `stacker. If the information is expired, or if there's never been such a stacker, then returns none. - -### get-stacking-minimum -#### entrada: -#### output: `uint` -#### signature: `(get-stacking-minimum)` -#### descripción: -Returns the absolute minimum amount that could be validly Stacked (the threshold to Stack in a given reward cycle may be higher than this - -### get-total-ustx-stacked -#### input: `uint` -#### output: `uint` -#### signature: `(get-total-ustx-stacked reward-cycle)` -#### descripción: -Returns the amount of currently participating uSTX in the given cycle. - -### is-pox-active -#### input: `uint` -#### output: `bool` -#### signature: `(is-pox-active reward-cycle)` -#### descripción: -Returns whether or not PoX has been rejected at a given PoX cycle. -## Códigos de error - -### ERR_DELEGATION_EXPIRES_DURING_LOCK -#### type: `int` -#### value: `21` - -### ERR_DELEGATION_POX_ADDR_REQUIRED -#### type: `int` -#### value: `23` - -### ERR_DELEGATION_TOO_MUCH_LOCKED -#### type: `int` -#### value: `22` - -### ERR_INVALID_START_BURN_HEIGHT -#### type: `int` -#### value: `24` - -### ERR_NOT_ALLOWED -#### type: `int` -#### value: `19` - -### ERR_STACKING_ALREADY_DELEGATED -#### type: `int` -#### value: `20` - -### ERR_STACKING_ALREADY_REJECTED -#### type: `int` -#### value: `17` - -### ERR_STACKING_ALREADY_STACKED -#### type: `int` -#### value: `3` - -### ERR_STACKING_EXPIRED -#### type: `int` -#### value: `5` - -### ERR_STACKING_INSUFFICIENT_FUNDS -#### type: `int` -#### value: `1` - -### ERR_STACKING_INVALID_AMOUNT -#### type: `int` -#### value: `18` - -### ERR_STACKING_INVALID_LOCK_PERIOD -#### type: `int` -#### value: `2` - -### ERR_STACKING_INVALID_POX_ADDRESS -#### type: `int` -#### value: `13` - -### ERR_STACKING_NO_SUCH_PRINCIPAL -#### type: `int` -#### value: `4` - -### ERR_STACKING_PERMISSION_DENIED -#### type: `int` -#### value: `9` - -### ERR_STACKING_POX_ADDRESS_IN_USE -#### type: `int` -#### value: `12` - -### ERR_STACKING_STX_LOCKED -#### type: `int` -#### value: `6` - -### ERR_STACKING_THRESHOLD_NOT_MET -#### type: `int` -#### value: `11` - -### ERR_STACKING_UNREACHABLE -#### type: `int` -#### value: `255` \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md b/i18n/es/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md deleted file mode 100644 index a7b3815f7e..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: xBTC -description: Wrapped BTC on Stacks ---- - -![](/img/xbtc-icon.webp) - -## Introducción - -[Wrapped.com](https://www.wrapped.com) has brought Bitcoin (xBTC) to the Stacks ecosystem. - -xBTC is backed 1:1 by Bitcoin and empowers developers to expand the Bitcoin DeFi ecosystem. - -The reserves are publicly visible [here](https://open.wrapped.com/reserves/). - -## Contract - -[SP3DX3H4FEYZJZ586MFBS25ZW3HZDMEW92260R2PR.Wrapped-Bitcoin](https://explorer.stacks.co/txid/SP3DX3H4FEYZJZ586MFBS25ZW3HZDMEW92260R2PR.Wrapped-Bitcoin?chain=mainnet) - -## Examples of uses - -[Friedger Mining Pool](https://pool.friedger.de/) currrently supports Stacking rewards payments in xBTC (optional). - - -## More information - -* [Blog post announcement](https://www.stacks.co/blog/tokensoft-wrapped-fundamental-bitcoin-defi-building-blocks-xbtc) by Muneeb Ali - -* Video: [Why xBTC is Important For Bitcoin to Grow](https://www.youtube.com/watch?v=xIoadrfSdi4) \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/current/references/_category_.json b/i18n/es/docusaurus-plugin-content-docs/current/references/_category_.json deleted file mode 100644 index 87065cb7be..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/references/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Referencias", - "position": 9, - "link": { - "type": "generated-index", - "description": "Referencias de Stacks." - } -} \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/current/references/glossary.md b/i18n/es/docusaurus-plugin-content-docs/current/references/glossary.md deleted file mode 100644 index 0099a439aa..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/references/glossary.md +++ /dev/null @@ -1,215 +0,0 @@ ---- -title: Glosario -description: Una lista de términos comunmente utilizados en el ecosistema. ---- - -Una lista de términos comunmente utilizados en el ecosistema. - -#### Revisiones de Aplicación -Un mecanismo de incentivos para los desarrolladores de aplicaciones en la fase inicial (primeros cuatro años) del ecosistema y para impulsar el autodesarrollo del mercado. - -#### Atlas -Una red de pares proporciona un índice global para su descubrimiento. - -#### Bitcoin (BTC) address -A string of letters and numbers. `3E53XjqK4Cxt71BGeP2VhpcotM8LZ853C8` Sharing this address allows anyone to send Bitcoin to the address. - -#### bloque -A discrete group of records written to a blockchain that can effectively be identified and referenced by the use of headers that contain a digital fingerprint of the records each block contains. - -#### blockchain -A database created and shared by the members of a peer-to-peer computer network which each member of that network can independently trust due to the rules governing the database’s creation. A blockchain can therefore be used to replace centralized databases. - -#### Blockchain Name System (BNS) -Sustituto del DNS. Más información [aquí](../noteworthy-contracts/bns-contract). - -#### Blockstack Browser -A deprecated application for accessing identity and storage. - -#### Blockstack Owner Address - -Looks like a bitcoin address but starts with `ID` for example: `ID-1J3PUxY5uDShUnHRrMyU6yKtoHEUPhKULs` - -#### Burning -Burning a token means that the token is transferred to an address that is a black hole—one that is not owned by any entity and for which guessing the applicable private key is effectively impossible based on known mathematical principles. This effectively destroys the token by making it unavailable for future use and decreases the total number of tokens available from that point forward. - -#### consensus hash -A consensus hash is a cryptographic hash that each node calculates at each block. It is derived from the accepted state transitions in the last-processed block and a geometric series of prior-calculated consensus hashes. - -#### Consensus rules -"The rules governing the creation of new valid records in a blockchain database and the mining algorithms used for this purpose. - -#### control plane -The part of a network that carries signaling traffic and is responsible for routing. Control packets originate from or are destined for a router. Functions of the control plane include system configuration and management. - -#### core node -A server that runs Stacks Blockchain services. - -#### crypto-asset -A digital asset which utilises cryptography, peer-to-peer networking and a public ledger to regulate the creation of new units, verify transactions and secure the transactions without the intervention of any middleman. - -#### cryptography -The practise and study of encryption and decryption - encoding data so that it can only be decoded by specific individuals. A system for encrypting and decrypting data is a cryptosystem. - -#### DAO -Ver Organización Autónoma Desdentralizada. - -#### decentralized application (DApp) -A DApp is a service that enables direct interaction between end users and providers (e.g. connecting buyers and sellers in some marketplace, owners and stores in file storage). A term coined by Ethereum. See their glossary: http://ethdocs.org/en/latest/glossary.html#dapp" - -#### Organización Autónoma Descentralizada (DAO) -A type of contract or suite of contracts on the blockchain that is intented to codify, enforce or automate the processes of an organization. - -#### digital asset -Also referred to as a crypto-asset. Any set of unique digital information—including, for example, programs, decentralized programs, isolated chunks of programming code, collections of data, e-mail or web addresses or cryptocurrency tokens—that is capable of being stored and uniquely tracked on a computer network such as the Stacks network and over which a user can maintain control through that network. - -#### digital fingerprint -A digital fingerprint is a unique number of a fixed length that can be produced by running any set of digital information through something called a cryptographic hash function. Each set of digital information (including a digital asset, and the digital record of any network operation on that digital asset) should (as a practical matter) have a unique digital fingerprint, which allows that set of digital information to be identified. However, it is almost impossible to recreate a digital asset from its digital fingerprint. The Blockstack network uses industry-standard algorithms such as SHA-256 to create digital fingerprints. - -#### firma digital -A digital signature is a sequence of digital information combining a user’s private key and any digital information that the user wishes to sign. Any other party can use the user’s paired public key to verify that the digital signature is authentic, i.e. that the public key was generated from a particular piece of digital information and the user’s private key. - -#### distributed hash tables (DHT) -A form of network used to store some content in the form of key/value pairs. ... This experimental project try to avoid keeping all the blockchain, but instead prefers to store it in a DHT. - -#### ephemeral key -A cryptographic key is called ephemeral if it is generated for each execution of a key establishment process. - -#### fork -The term fork is used to refer both to any situation where there are two or more competing versions of a blockchain on a network (a situation that may arise and resolve itself in the ordinary course of network operations due to lags in communication between core nodes) and any software update that is proposed for adoption by the core nodes of a blockchain network that may result in a persistent fork on the network, with core nodes that adopt the update recognizing one version of the blockchain and those which do not recognizing another. - -#### Gaia -Decentralized storage architecture for off-chain data. More info [here](../gaia). - -#### bloque génesis -The genesis block is the first block of the Stacks blockchain, which will create the initial 1.32 billion Stacks Tokens. - -#### id.blockstack -An identifier in the Blockstack, for example meepers.id.blockstack. This is your name & identity that is registered in the .id namespace on Blockstack. Your personal data and storage are built around this ID. Apps that want to access your data use your permission and identity to find it. An id is usually a shorthand for a longer, hash ID string, for example ID-1Fj9kkw15P51Fj9kkw15P5xJmyefWhLKrQMKNPREfaqsJ" - -#### identidad - -A way to identify a person or an organization on the Stacks network. An identity is unique, both `meepers.id.blockstack` or `chad.id` are examples of IDs. - -#### identity management (IDM) -Identity management, also known as identity and access management is, in computer security, the security and business discipline that enables the right individuals to access the right resources at the right times and for the right reason". - -#### know your customer (KYC) -Or KYC, is a popular term used in the banking or financial field. KYC is a process where financial institutions, insurers and other companies obtain information about the identity and address of the customers as part of risk management. - -#### light clients -Clients that can independently validate the existence of transactions by downloading only block headers and not the entire blockchain. - -#### magic recovery code - -A long encrypted string, for example: `36mWivFdy0YPH2z31EflpQz/Y0UMrOrJ++lH=0EI7c3mop2JuRBm5WXxSTazJsUjOA...` Do not share the QR code that accompanied your recovery code either. This is a QR code: - -![](/img/qr-code.png) - -#### red de malla -A local network topology in which the infrastructure nodes (i.e. bridges, switches, and other infrastructure devices) connect directly, dynamically and non-hierarchically to as many other nodes as possible and cooperate with one another to efficiently route data from/to clients. - -#### minería -Mining generally refers to the process of performing certain functions for a network such as adding new records to a blockchain in exchange for mining rewards; it may also refer to other mechanisms whereby rewards (usually in the form of cryptocurrency) are provided for performing other tasks helpful to the network. - -#### mining power -A miner’s (or group of miners’) mining power is equal to the probability it will be selected to write a new block to the blockchain. Depending on the mechanism for mining, this is usually related to the overall share of computing power or cryptoassets the miner or miners possess relative to all miners for that blockchain. - -#### mining rewards -Mining rewards are newly issued tokens received by miners in exchange for adding new records to the blockchain or other activities beneficial to the network. - -#### nombre -An identifier or name. Names are a type of digital asset in the Stacks network. If you have signed into the Stacks Wallet, you might have created a name. If an application developer registered an application within Stacks, then they registered a name. Public Stacking pools can also have a name. - -#### network operation -A network operation is any change to the information about a digital asset (or smart contract) stored on a blockchain, including, for example, a change in the digital asset’s owner, or a change in the location at which it is stored on the network. How and when these network operations are performed for each digital asset is governed, on the Blockstack network, either by the Stacks Node software or a smart contract. - -#### NFT -Token no fungible. - -#### llave privada - -Private keys matches a corresponding public key. A public key also looks like a string of letters and numbers: - -![](/img/private.png) - -The exact format of the public and private key depend on the software you use to create them. - -#### proof-of-burn mining -The consensus algorithm used in the Stacks blockchain where miners destroy a proof-of-work-based cryptocurrency (currently Bitcoin) to get tokens; this enables the functionality where nodes can select between conflicting blockchain forks, as the blockchain fork with the most amount of cryptocurrency burned is considered to be the correct fork. - -#### proof-of-work -A proof-of-work system or proof-of-work mining is a mining mechanism where miners must expend computing power to solve complicated cryptographic puzzles, and prove that they have done so by writing the solution to the blockchain, in order to be allowed to add blocks to a blockchain. This is the mining system used, for example, by Bitcoin. - -#### clave pública -Public and private key pair comprise of two uniquely related cryptographic keys. It looks like a long random string of letters and numbers: `3048 0241 00C9 18FA CF8D EB2D EFD5 FD37 89B9 E069 EA97 FC20 …` The exact format of the public and private key depend on the software you use to create them. - -#### Public Key Infrastructure (PKI) -A system which returns a cryptographic public key associated with a name. - -#### replicated state machines (RSMs) -This is a model for reasoning about distributed computer programs -- any program (plus it's input) can be represented as a state machine, and when trying to get a distributed set of servers to agree on the output of an algorithm, you can model that process as N different state machines" - -#### Secret recovery Key, -Used to access an identity on the Stacks blockchain. A 24-word sequence of words for example: `applied binge crisp pictorial fiery` `dancing agreeable frogs light finish ping apple` - -#### Frase semilla - -Used to access Stacks Wallet software. The seed phrase consists of 24 words in a sequence. Both the word *and its position the sequence* are important. Write down your seed phrase and store it in a secure location such as a safe deposit box. When you write the seed phrase down, include its position, for example,`1-frog, 2-horse, 3-building` and so on until you reach a final position `24-ocean`. -#### contrato inteligente -A smart contract is a computer program written to a blockchain such as the Stacks blockchain by developers. This computer program defines the various network operations that can be performed on the digital assets on the blockchain, the computations that can be performed using the smart contract, along with defining various important properties of the respective digital assets like ownership rights and the cost in fuel required to register the digital assets. - -#### soft fork -A soft fork is a proposed update to the software governing the network that results in a post-update network that is compatible with the network as it existed prior to the update, because it restricts the network operations that can be performed after the update. - -#### Stacks (STX) address - - A STX address is a string of letters and numbers starting with an `SP` or `SM`, for example: `SM3KJBA4RZ7Z20KD2HBXNSXVPCR1D3CRAV6Q05MKT` If you created a software-only wallet with the Stacks Wallet software, the wallet has a single STX address which is also sometimes called the *wallet address*. You access a software wallet with a *seed phrase*. " - -#### Stacks blockchain -The Stacks blockchain is the custom blockchain being developed for use by the Stacks network that will use the Stacks token as its native currency and which will include the genesis block and subsequent blocks created by the mining activities described in the Stacks Network—Development of the Stacks network. - -#### Stacks Explorer -An application that allow you to view and search transactions in the blockchain. For example, https://explorer.stacks.co. - -#### Nodo de Stacks -A complete version of our open-source software available on Github at https://github.com/stacks-network/stacks-blockchain/ that governs the creation of the blockchain, the smart contracts that may be written to our blockchain, and other systems that make up the Stacks network, when run on the systems and devices of our users and developers. - -#### Monedero de Stacks -An application for accessing assets, identity and storage. Examples are the [Hiro Wallet](https://www.hiro.so/wallet), [xverse](https://www.xverse.app/) and [dcent](https://dcentwallet.com/). More information and example [here](../services-using-stacks/wallets). - -#### storage hub -A Gaia instance run by a hub provider or software. A Gaia hub stores data in a separate, addressed location. - -#### storage provider -A third-party company cloud or software provider that hosts one or more Gaia storage hubs. - -#### transacción -A transaction is a unit of work within a block. - -#### transaction fee -Fees paid by participants in a transaction to miners. - -#### two-sided market problem -Economic platforms having two distinct user groups that provide each other with network benefits. The Stacks platform is a classic two-sided market. - -#### username -A shorthand name for your id.blockstack. - -#### blockchain virtual -A layer that sits on top of a blockchain that introduces new functionality and operations without requiring changes to the underlying blockchain. - -#### wallet address -A wallet address is the form in which a public key can be presented and recorded on a blockchain. Wallet addresses are therefore used to assign the ownership of digital assets on the Blockstack network. - -#### watch-only wallet -A wallet without send and receive ability. You can view only balances and transaction history. - -#### web of trust mining -Web-of-trust mining provides incentive mechanisms for users where an initial trusted-set of unique users is curated in the genesis block and, in the future, the initial set of users can expand the web-of-trust after the network goes live. - -#### web3 -The exact definition is still under discussion, but it general refers to the 3rd generation of the web that is based on blockchain technology and incorporates decentralized and token-based economics. - -#### zone file -A Domain Name System (DNS) zone file is a text file that describes a DNS zone. A DNS zone is a subset, often a single domain, of the hierarchical domain name structure of the DNS. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/references/nft.md b/i18n/es/docusaurus-plugin-content-docs/current/references/nft.md deleted file mode 100644 index 553f32e1d8..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/references/nft.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: NFTs en Stacks -description: Una lista de sitios web que operan NFTs en Stacks ---- - -Lista de sitios web que operan NFTS en Stacks en orden alfabético. - -### [Byzantion](https://byzantion.xyz/) - -![captura de pantalla de página web](/img/sh_nft_byzantion.png) - -### [Gamma](https://gamma.io/) -![captura de pantalla de página web](/img/sh_nft_gamma.png) - -### [Megapont](https://www.megapont.com/) - -![captura de pantalla de página web](/img/sh_nft_megapont.png) - -### [StacksArt](https://www.stacksart.com/) - -![captura de pantalla de página web](/img/sh_nft_stacksart.png) - diff --git a/i18n/es/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md b/i18n/es/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md deleted file mode 100644 index 0648251ba4..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Sitios web con información Stacks -description: Un listado de sitios web en orden alfabético con muestran el estado y estadísticas de la red Stacks. ---- - -### [Haystack](https://haystack.tools/mempool) - -![website-screenshot](/img/sh_haystacks.png) - -### [Stacksdata](https://stacksdata.info/) - -![website-screenshot](/img/sh_stacksdata.png) - -### [Stacksonchain](https://stacksonchain.com) - -![website-screenshot](/img/sh_stacksonchain.png) - -### [Status Hiro](https://status.hiro.so/) - -![website-screenshot](/img/sh_statushiro.png) - -### [Stxstats](https://www.stxstats.co/) - -![website-screenshot](/img/sh_stxstats.png) - -### [Novuminsights](https://stacks.novuminsights.com/health) - -![website-screenshot](/img/sh_novuminsights.png) - -### [Onstacks](https://app.onstacks.com/) - -![website-screenshot](/img/sh_onstacks.png) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json b/i18n/es/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json deleted file mode 100644 index c4608227dc..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Servicios usando Stacks", - "position": 8, - "link": { - "type": "generated-index", - "description": "Una lista \"siempre incompleta\" de servicios que utilizan Stacks." - } -} \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md b/i18n/es/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md deleted file mode 100644 index c4a1864f64..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: DeFi -description: Sitios De-Fi en Stacks -sidebar_position: 2 ---- - -They are multiple De-Fi sites that operate on the Stacks blockchain. - -:::tip ¿Falta uno? -Por favor edita esta página para agregar cualquier sitio web relevante que falte. -::: - -## Alex - -[Alex](https://app.alexlab.co) ![](/img/sh_alex.png) - -## Arkadiko - -[Arkadiko](https://arkadiko.finance/) ![](/img/sh_arkadiko.png) - -## Catamaran Swaps - -[Catamaran Swaps](https://www.catamaranswaps.org/) permite el intercambio de activos digitales sin requirimiento de confianza. - -![](/img/sh_catamaran.png) - -## Lnswap - -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange - -![](/img/sh_lnswap.png) - -## Neoswap - -[Neoswap](https://neoswap.party) - -![](/img/sh_neoswap.png) - -## Stackswap - -[Stackswap](https://app.stackswap.org/v2) - -![](/img/sh_stackswap.png) - diff --git a/i18n/es/docusaurus-plugin-content-docs/current/services-using-stacks/more.md b/i18n/es/docusaurus-plugin-content-docs/current/services-using-stacks/more.md deleted file mode 100644 index e28ff4727e..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/services-using-stacks/more.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Más -description: Más servicios construidos en Stacks. -sidebar_position: 5 ---- - -Lista de sitios añadidos por la comunidad en orden alfabético. - -:::tip ¿Falta uno? -Por favor edita esta página para agregar cualquier sitio web relevante que falte. -::: - -## Citycoins - -[Citycoins](https://citycoins.co) - -![](/img/sh_citycoins.png) - -## Sigle - -[Sigle](https://www.sigle.io/) es una plataforma de escritura web 3 descentralizada y de código abierto. - -![](/img/sh_sigle.png) \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md b/i18n/es/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md deleted file mode 100644 index d24c66ba1e..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: NFTs -description: NFTs en Stacks -sidebar_position: 3 ---- - -Lista de sitios web que operan NFTS en Stacks en orden alfabético. - -:::tip ¿Falta uno? -Por favor edita esta página para agregar cualquier sitio web relevante que falte. -::: - -### [Byzantion](https://byzantion.xyz/) - -![captura de pantalla de página web](/img/sh_nft_byzantion.png) - -### [Gamma](https://gamma.io/) -![captura de pantalla de página web](/img/sh_nft_gamma.png) - -### [Megapont](https://www.megapont.com/) - -![captura de pantalla de página web](/img/sh_nft_megapont.png) - -### [StacksArt](https://www.stacksart.com/) - -![captura de pantalla de página web](/img/sh_nft_stacksart.png) - -### [Superfandom](https://superfandom.io/) - -![website-screenshot](/img/sh_superfandom.png) \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/current/services-using-stacks/other.md b/i18n/es/docusaurus-plugin-content-docs/current/services-using-stacks/other.md deleted file mode 100644 index 199fc41da5..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/services-using-stacks/other.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Other Stacks sites -description: A list of sites on alphabetical order built on Stacks. -sidebar_position: 4 ---- - -List of sites on alphabetical order added by the community. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Alex -[Alex](https://app.alexlab.co) - -## Sigle - -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md b/i18n/es/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md deleted file mode 100644 index 180d2da19d..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Sitios web con información Stacks -description: Status and stats of the Stacks network. -sidebar_position: 1 ---- - -Un listado de sitios web en orden alfabético con muestran el estado y estadísticas de la red Stacks. - -:::tip ¿Falta uno? -Por favor edita esta página para agregar cualquier sitio web relevante que falte. -::: - -### [Haystack](https://haystack.tools/mempool) - -![website-screenshot](/img/sh_haystacks.png) - -### [Stacksdata](https://stacksdata.info/) - -![website-screenshot](/img/sh_stacksdata.png) - -### [Stacksonchain](https://stacksonchain.com) - -![website-screenshot](/img/sh_stacksonchain.png) - -### [Status Hiro](https://status.hiro.so/) - -![website-screenshot](/img/sh_statushiro.png) - -### [Stxstats](https://www.stxstats.co/) - -![website-screenshot](/img/sh_stxstats.png) - -### [Novuminsights](https://stacks.novuminsights.com/health) - -![website-screenshot](/img/sh_novuminsights.png) - -### [Onstacks](https://app.onstacks.com/) - -![website-screenshot](/img/sh_onstacks.png) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md b/i18n/es/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md deleted file mode 100644 index d4b4cbf18c..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Swaps -description: A list of sites that allow Swaps -sidebar_position: 2 ---- - -They are multiple sites that allow you to make swaps using the Stacks blockchain. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Catamaran Swaps - -[Catamaran Swaps](https://www.catamaranswaps.org/) allows trustless exchange of digital assets. - -![](/img/sh_catamaran.png) - -## Lnswap - -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange - -![](/img/sh_lnswap.png) - -## Neoswap - -[Neoswap](https://neoswap.party) - -![](/img/sh_neoswap.png) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md b/i18n/es/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md deleted file mode 100644 index 9e9b57ec76..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Wallets -description: Wallets para Stacks -sidebar_position: 4 ---- - -Un listado de wallets de hardware y software para Stacks - -:::tip ¿Falta uno? -Por favor edita esta página para agregar cualquier sitio web relevante que falte. -::: - -## Blockchain.com - -[Blockchain.com](https://www.blockchain.com/wallet) - -![](/img/sh_blockchain.png) -## Boom - -[Boom](https://boom.money) - -![](/img/sh_boom.png) - -## Dcent wallet - -[D'CENT](https://dcentwallet.com) - -![](/img/sh_dcent.png) -## Hiro Wallet - -[Hiro Wallet](https://www.hiro.so/wallet) - -![](/img/sh_hirowallet.png) - -## Neptune - -[Neptune](https://neptunewallet.io) - -![](/img/sh_neptunewallet.png) - -## Xverse - -[Xverse](https://www.xverse.app/) - -![](/img/sh_xverse.png) - -## Wise - -[Wise](https://wiseapp.id) - -![](/img/sh_wiseapp.png) \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md b/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md deleted file mode 100644 index 8091b5b6bc..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md +++ /dev/null @@ -1,214 +0,0 @@ ---- -title: Cuentas -description: Guía de cuentas de Stacks 2.0 -sidebar_position: 5 ---- - -## Introducción - -Las cuentas Stacks 2.0 son entidades que poseen assets, como los tokens de Stacks (STX). Una cuenta contiene una dirección, clave privada, un nonce, y uno o más saldos de activos. - -:::tip El algoritmo de cifrado utilizado en Stacks 2.0 es **[secp256k1](https://en.bitcoinwiki.org/wiki/Secp256k1)**. - -Adicionalmente, [Ed25519](https://ed25519.cr.yp.to/) también se utiliza solo para la VRF (función aleatoria verificable). ::: - -Los assets no pueden dejar una cuenta sin una acción del propietario de la cuenta. Todos los cambios en los assets (y los saldos de la cuenta) requieren una transacción correspondiente. - -:::tip -El tipo de transacción no necesita ser una transferencia de tokens - el deploy del contrato y las llamadas de contrato pueden cambiar los balances de una cuenta -::: - -## Creación - -Una cuenta se genera a partir de una frase mnemónica de 24 palabras. Esto a menudo se le conoce como **la frase semilla**. La frase semilla proporciona acceso a las cuentas Stacks 2.0. - -:::danger -Si la frase de semilla se pierde, el acceso a la cuenta asociada no se puede recuperar. Ninguna persona u organización, incluyendo Blockstack, puede recuperar una frase de semilla perdida. -::: - -La forma más fácil de generar una nueva cuenta de Stacks 2.0 es utilizar la [CLI de Stacks](https://github.com/hirosystems/stacks.js/tree/master/packages/cli): - -```bash -# instalar CLI globalmente -npm install --global @stacks/cli - -# generate a new account and store details in a new file -# '-t' option makes this a testnet account -stx make_keychain -t > cli_keychain.json -``` - -`make_keychain` crea la siguiente línea: - -```js -{ - "mnemonic": "aaa bbb ccc ddd ...", - "keyInfo": { - "privateKey": "5a3f1f15245bb3fb...", - "address": "STJRM2AMVF90ER6G3RW1QTF85E3HZH37006D5ER1", - "btcAddress": "biwSd6KTEvJcyX2R8oyfgj5REuLzczMYC1", - "wif": "L4HXn7PLmzoNW...", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -| Campo | Descripción | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `mnemonic` | Una frase semilla de 24 palabras utilizada para acceder a la cuenta, generada usando [BIP39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) con 256 bits de entropía | -| `keyInfo.privateKey` | Clave privada para la cuenta. Requerida para transferencias de tokens y a menudo llamada como `senderKey` | -| `keyInfo.address` | Dirección Stack para la cuenta | -| `keyInfo.btcAddress` | Dirección BTC correspondiente para la cuenta. | -| `keyInfo.wif` | Clave privada de btcAddress en formato comprimido. | -| `keyInfo.index` | Nonce para la cuenta, iniciando en 0 | - -Ten en cuenta que existe una nueva cuenta automáticamente para cada nueva clave privada. No hay necesidad de instanciar manualmente una cuenta en la blockchain Stacks 2.0. - -:::tip Las direcciones se crean generando el [hash RIPEMD-160](https://en.wikipedia.org/wiki/RIPEMD#RIPEMD-160_hashes) del [SHA256](https://en.bitcoinwiki.org/wiki/SHA-256) de la clave pública. Las direcciones BTC están codificadas con [Base58Check](https://en.bitcoin.it/wiki/Base58Check_encoding). Para direcciones Stacks, se utiliza [c32check](https://github.com/stacks-network/c32check). Se puede obtener una dirección de una clave pública sin acceso a Internet, por ejemplo utilizando el método c32check `c32addressDecode`. ::: - -Alternativamente a la creación con CLI, se puede utilizar la librería [Stacks Transactions JS](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions): - -```js -import { - makeRandomPrivKey, - privateKeyToString, - getAddressFromPrivateKey, - TransactionVersion, -} from '@stacks/transactions'; - -const privateKey = makeRandomPrivKey(); - -// Obtener clave pública de privada -const publicKey = getPublicKey(privateKey); - -const stacksAddress = getAddressFromPrivateKey( - privateKeyToString(privateKey), - TransactionVersion: Testnet // quitar esta línea para direcciones Mainnet -); -``` - -Una segunda alternativa sería utilizar [stacks-gen](https://github.com/psq/stacks-gen). Esta herramienta generará todas las claves que necesita en un solo lugar, incluyendo los valores necesarios para llamar al contrato de staking, y también una clave WIF para usar con `bitcoind`. - -#### prerrequisito de stacks-gen - -Instalar [npx](https://github.com/npm/npx) si no está instalado. (npx comprobará si `` existe en \$PATH, o en los binarios locales del proyecto y lo ejecuta. Si `` no se encuentra, se instalará antes de la ejecución). - -``` -npm install -g npx -``` - -#### uso de stacks-gen - -``` -npx -q stacks-gen sk --testnet - -{ - "phrase": "guide air pet hat friend anchor harvest dog depart matter deny awkward sign almost speak short dragon rare private fame depart elevator snake chef", - "private": "0351764dc07ee1ad038ff49c0e020799f0a350dd0769017ea09460e150a6401901", - "public": "022d82baea2d041ac281bebafab11571f45db4f163a9e3f8640b1c804a4ac6f662", - "stacks": "ST16JQQNQXVNGR8RZ1D52TMH5MFHTXVPHRV6YE19C", - "stacking": "{ hashbytes: 0x4d2bdeb7eeeb0c231f0b4a2d5225a3e3aeeed1c6, version: 0x00 }", - "btc": "mnYzsxxW271GkmyMnRfiopEkaEpeqLtDy8", - "wif": "cMh9kwaCEttgTQYkyMUYQVbdm5ZarZdBHErcq7mXUChXXCo7CFEh" -} -``` - -:::tip El objeto stacking con hashbytes y una versión representa la dirección bitcoin derivada de la dirección de pilas. Lea más sobre el [formato de dirección bitcoin](stacking#bitcoin-address). ::: - -La documentación completa está disponible en [stacks-gen](https://github.com/psq/stacks-gen). - -## Consultas - -### Obtener el balance de Stacks (STX) y nonce - -El saldo STX y nonce se pueden obtener a través del endpoint [`GET /v2/accounts/`](https://docs.hiro.so/api#operation/get_account_info): - -```bash -# para mainnet, reemplazar `testnet` por `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/accounts/' -``` - -Ejemplo de respuesta: - -```js -{ - "balance": "0x0000000000000000002386f26f3f40ec", - "nonce": 17 -} -``` - -:::tip -La cadena de balance representa un entero sin signo de 128-bit (big-endian) en codificación hexadecimal -::: - -### Obtener los balances de todos los tokens - -Todos los balances de tokens se pueden obtener a través del endpoint [`GET /extended/v1/address//balances`](https://docs.hiro.so/api#operation/get_account_balance): - -```bash -# para mainnet, reemplazar `testnet` por `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/address//balances' -``` - -Ejemplo de respuesta: - -```js -{ - "stx": { - "balance": "0", - "total_sent": "0", - "total_received": "0" - }, - "fungible_tokens": {}, - "non_fungible_tokens": {} -} -``` - -:::tip Las cuentas Stacks no pueden contener bitcoins. La mejor manera de obtener los balances BTC correspondientes es derivar la dirección BTC de la dirección Stacks (usando [`c32check`](https://github.com/stacks-network/c32check#c32tob58-b58toc32)) y consultar la red Bitcoin. ::: - -### Obtener todos los eventos de los asset - -Todos los eventos de asset asociados con la cuenta se pueden obtener a través del endpoint [`GET /extended/v1/address//assets`](https://docs.hiro.so/api#operation/get_account_balance): - -```bash -# para mainnet, reemplazar `testnet` por `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/address//balances' -``` - -Ejemplo de respuesta: - -```js -{ - "limit": 20, - "offset": 0, - "total": 0, - "results": [ - { - "event_index": 5, - "event_type": "non_fungible_token_asset", - "asset": { - "asset_event_type": "transfer", - "asset_id": "ST2W14YX9SFVDB1ZGHSH40CX1YQAP9XKRAYSSVYAG.hello_world::hello-nft", - "sender": "SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR", - "recipient": "SM2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQVX8X0G", - "value": { - "hex": "0x0100000000000000000000000000000001", - "repr": "u1" - } - } - }, - { - "event_index": 3, - "event_type": "fungible_token_asset", - "asset": { - "asset_event_type": "mint", - "asset_id": "ST2W14YX9SFVDB1ZGHSH40CX1YQAP9XKRAYSSVYAG.hello_world::novel-token-19", - "sender": "", - "recipient": "SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR", - "amount": "12" - } - } - ] -} -``` diff --git a/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/index.md b/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/index.md deleted file mode 100644 index 4879a1c20c..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/index.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Comprende Stacks -description: Aprenda más sobre el blockchain Stacks 2.0 -sidebar_position: 1 ---- - -![](/img/SBC-L-2x-10.png) -## Introducción - -Stacks 2.0 es una cadena de bloques de transacciones blockchain de primera capa que se conecta a Bitcoin, permitiendo contratos inteligentes y aplicaciones descentralizadas. Los contratos inteligentes y las aplicaciones desarrollados en la plataforma de Stacks se integran de forma nativa con Bitcoin, incorporándo así su seguridad, estabilidad y poder económico. - -## Funcionalidades - -Obtenga más información sobre las características del blockchain Stacks 2.0. - - - -:::tip Check out the [technical specifications](technical-specs) for a brief overview ::: - - - - -Una comparación detallada [del blockchain Stacks con otras tecnologías de blockchain][Comparación del blockchain de Stacks con otras tecnologías de blockchain] está disponible en el blog de la Stacks Foundation. -### Mecanismo de consenso -![](/img/pages/stacking.svg) Stacks 2.0 implementa un nuevo mecanismo de minería llamado Prueba de Transferencia (PoX). PoX es un algoritmo de consenso entre dos blockchains que utiliza uno ya establecido (en este caso Bitcoin) para anclar uno nuevo (Stacks). Utiliza una blockchain bien establecida (en este caso Bitcoin) para asegurar una nueva blockchain (Stacks). - -PoX tiene una relación de 1:1 por bloque con Bitcoin, lo que significa que cualquier cosa que suceda en el blockchain de Stacks puede verificarse en la blockchain de Bitcoin. - -En lugar de gastar electricidad como prueba de trabajo, PoX reutiliza los bitcoins ya acuñados como "prueba de cómputo", y los mineros representan su costo de minería directamente en bitcoins. - - -[Leer más sobre "Proof of Transfer"](proof-of-transfer) -### Minería - -![](/img/pages/testnet-sm.svg) Minar es necesario para lograr que la red sea utilizable, fiable y segura. Los mineros verifican las transacciones entrantes, participan en el mecanismo de consenso y escriben nuevos bloques en el blockchain. - -Para incentivar la minería, los mineros reciben tókenes de Stacks (STX) recién acuñados al ganar la subasta que les permiten convertirse líderes de la próxima ronda. - -[Leer más sobre minería](mining) - -### Stacking - -Los bitcóines utilizados en las pujas de los mineros se envían a un conjunto de direcciones específicas pertenecientes a los poseedores de Stacks (STX) que participan activamente en el consenso ('Stackers'). Así, en lugar de ser destruidos, los bitcóines que se consumen durante en el proceso de minado se destinan a los poseedores de Stacks involucrados en el proceso como recompensa por conservar sus Stacks y participar en el algoritmo de Stacking. - -Quienes poseen Stacks tienen que bloquear sus tókenes (STX) durante un período de tiempo determinado. - -[Leer más sobre Stacking](stacking) - -### Contratos inteligentes - -![](/img/pages/write-smart-contracts-sm.svg) Clarity es un nuevo lenguaje que se utiliza en los contratos inteligentes del blockchain Stacks 2.0 y optimiza tanto su previsibilidad como su seguridad. The Clarity smart contract language optimizes for predictability and security. - -Stacks 2.0 fija los contratos inteligentes de Clarity en Bitcoin, lo que permite que dichos contratos operen basándose en las acciones que aparecen en el blockchain de Bitcoin. - -:::note The [Clarity open-source project](https://clarity-lang.org/) is supported by Stacks and [Algorand](https://www.algorand.com/) ::: - - -Clarity es diferente de otros lenguajes diseñados para escribir contratos inteligentes de varias maneras: - -- **Previsibilidad**: El lenguaje Clarity utiliza una sintaxis precisa e inequívoca que permite a los desarrolladores predecir exactamente cómo se ejecutarán sus contratos. -- **Seguridad**: El lenguaje Clarity permite que los usuarios establezcan sus propias condiciones para las transacciones, lo que garantiza que un contrato nunca pueda transferir inesperadamente en token de un usuario. -- **Sin compilador**: Los contratos escritos con Clarity se transmiten al blockchain de Stacks tal cual fueron creados por los desarrolladores. Esto garantiza que el código que los desarrolladores escribieron, analizaron y probaron, sea exactamente lo que se ejecuta. - -[Leer más sobre Clarity](../write-smart-contracts/clarity-language/) - -## Guías - -Lea una de nuestras guías para entender los pormenores del blockchain Stacks 2.0. - -* [Cuenta](../understand-stacks/accounts) -* [Transacciones](../understand-stacks/transactions) -* [Red](../understand-stacks/network) -* [Microbloques](../understand-stacks/microblocks) - -[Comparación del blockchain de Stacks con otras tecnologías de blockchain]: https://stacks.org/stacks-blockchain "" diff --git a/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md b/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md deleted file mode 100644 index 475befaa4b..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: Microbloques -description: Guía de Microbloques Stacks -sidebar_position: 8 ---- - -## Introducción - -Los microbloques son una característica a nivel de protocolo de la blockchain de Stacks que resuelven el desafío técnico de latencia de transacción. Porque cada bloque de Stacks está anclado a un bloque de Bitcoin a través del [mecanismo de consenso Proof-of-Transfer](../understand-stacks/proof-of-transfer), Stacks está necesariamente limitada a los mismos tiempos de bloques que la red Bitcoin. Los microbloques permiten a la blockchain de Stacks realizar transiciones de estado entre bloques de anclaje. - -Los microbloques son un potente mecanismo para que los desarrolladores creen aplicaciones de alta calidad y rendimiento en Stacks, mientras que todavía heredan la seguridad de Bitcoin. - -## Estados de la transacción - -El [modelo de producción de bloques de Stacks](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.) se describe en SIP-001. El estándar delimita el mecanismo mediante el cual los líderes de bloques elegidos pueden producir bloques en la blockchain de Stacks ya sea por lotes de transacciones o por transmisión de ellas. Los microbloques son el producto del modelo de transimisión. - -Si un líder de bloque ha elegido minar microbloques, el líder selecciona las transacciones del mempool y las empaqueta en microbloques durante el epoch actual. Los microbloques son bloques de transacciones incluidas por un minero después de que el bloque de anclaje anterior haya sido minado, pero antes de que el siguiente bloque sea seleccionado. Las transacciones incluidas en microbloques son procesadas por la red: sus resultados son conocidos. - -Considere una transacción desde la perspectiva del número de confirmaciones que el bloque tiene. Una transacción incluida en un microbloque podría tener el siguiente ejemplo de ciclo de vida: - -``` -La transacción 1 se transmite al mempool. Tiene 0 confirmaciones. -La transacción 1 está incluida en un microbloque. Todavía tiene 0 confirmaciones, pero los resultados de la transacción son conocidos -La transacción 1 está incluida en el próximo bloque de anclaje. Tiene 1 confirmación. -El próximo bloque de Stacks confirma el bloque anterior. La transacción 1 tiene 2 confirmaciones. -El próximo bloque de Stacks confirma el bloque anterior. La transacción 1 tiene 3 confirmaciones. -... -``` - -Considere una transacción similar que no está incluida en un microbloque: - -``` -La transacción 2 se transmite al mempool. Tiene 0 confirmaciones. -La transacción 2 está incluida en el próximo anclaje de bloque. Tiene 1 confirmación. -El próximo bloque de Stacks confirma el bloque anterior. La transacción 2 tiene 2 confirmaciones. -El próximo bloque de Stacks confirma el bloque anterior. La transacción 2 tiene 3 confirmaciones. -``` - -Los ciclos de vida de las dos transacciones son similares, pero la diferencia es el estado pendiente. Muchos wallets de Bitcoin muestran saldos de confirmación 0: el saldo de su wallet con cualquier transacción de mempool ya aplicada. Esto es útil porque te indica cuando has enviado o recibido una transacción. Con contratos inteligentes, mostrar el estado pendiente no es tan sencillo, porque los contratos inteligentes no solo transfieren entradas a salidas, pueden llamar a otros contratos, emitir eventos, o realizar otros cálculos. Una transacción procesada en un microbloque genera toda esa información. - -:::tip -Si una transacción es dependiente de un estado de la cadena que podría verse alterado por transacciones anteriores con graves -implicaciones, debería considerar cuidadosamente si debe realizarse usando microbloques. -::: - -## Habilitar microbloques - -Los mineros pueden elegir habilitar o desactivar microbloques en su configuración de minería. Como una mejor práctica, los mineros deben permitir minería microbloques. Cuando una aplicación o usuario envía una transacción, la transacción puede incluir un argumento que requiere que la transacción esté en un microbloque, un anclaje de bloque o en ninguna de ellas. - -### Transacciones - -Las transacciones incluyen una opción que controla si un minero debe incluirlas en microbloques o en anclajes de bloque. La opción de transacción del modo ancla es un argumento opcional que controla si una transacción debe incluirse en un anclaje de bloque o un microbloque, o es elegible para ambos. - -### Minería - -Los mineros Stacks deben habilitar microbloques en su configuración de minería para implementar la transmisión del modelo de bloques. Para más información, consultar [minando de microbloques](../understand-stacks/mining#microblocks). - -## Desarrollando con microbloques - -En la mayoría de los casos, la información de transacciones incluidas en microbloques debe ser tratada como información de cualquier otro bloque. Wallets y exploradores deben mostrar las consecuencias de las transacciones de microbloques como el estado actual de la red. Este Estado debe ser reconocido como tentativo. - -Una transacción de microbloque puede terminar siendo reorganizada en el siguiente bloque en lugar de ser confirmada como es. Debido a de esto, tu UI debería comunicar a los usuarios si los resultados de una transacción cambiaron, o si el bloque asociado a la transacción cambió. Este es el mismo resultado que si ocurriera un fork de 1 bloque. - -### Librerías Stacks.js - -Stacks.js proporciona el argumento [AnchorMode][] en objetos de transacción para que la aplicación pueda establecer la preferencia microbloques para las transacciones. - -### API - -:::danger El soporte de la API para microbloques es un trabajo en curso. Revise la [documentación de la API][microblocks_api] cuidadosamente para asegurarse de que está actualizado sobre los últimos detalles de implementación para microbloques. ::: - -La API de Stacks Blockchain expone microbloques a través de varios endpoints. Revisa la [Guía API de Stacks Blockchain][] para más detalles. - -## Buenas prácticas - -Trabajar con microbloques es una decisión de diseño que debes tomar para tu propia aplicación. Al trabajar con microbloques, se recomiendan las siguientes buenas prácticas. - -### Manejo de nonce - -Manejo de nonce con microbloques es desafiante porque la siguiente cuenta nonce debe tener en cuenta cualquier valor de nonce incluido en microbloques, que aún no puede ser incluido en un anclaje de bloque. La API de Stacks Blockchain [proporciona un endpoint][] para recuperar el siguiente nonce para un determinado principal. - -### Diseño de aplicación - -El estado de las transacciones en microbloques debe comunicarse cuidadosamente a los usuarios. Ninguna transacción es final hasta que se incluya en un anclaje de bloque y el diseño de tu aplicación debería reflejar esto. - -Las siguientes pautas se proporcionan como un conjunto inicial de buenas prácticas para el diseño UI al incorporar microbloques en su aplicación. - -#### Exploradores - -Mostrar estado pendiente, pero advertir que una transacción todavía está pendiente. Indique visualmente que los saldos mostrados dependen del estado pendiente. - -#### Billeteras - -Mostrar estado pendiente, pero advertir que una transacción todavía está pendiente. Indicate visually that displayed balances depend on pending state. - -#### Exchanges - -Continúe contando confirmaciones, los microbloques deben ser considerados pendientes. - -#### Aplicaciones - -La comunicación de microbloque es altamente dependiente de la aplicación. Para algunas aplicaciones, puede que esté bien mostrar una transacción pendiente o 0-confirmación confirmada. Por ejemplo, almacenar datos en la cadena, o consultar el contrato BNS. Para otras aplicaciones, como la transferencia del valor real, esperar a 3 confirmaciones sería prudente antes de mostrar el estado como confirmado. - -[AnchorMode]: https://stacks.js.org/enums/transactions.AnchorMode.html -[Guía API de Stacks Blockchain]: https://docs.hiro.so/get-started/stacks-blockchain-api#microblocks-support -[proporciona un endpoint]: https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling -[microblocks_api]: https://docs.hiro.so/api#tag/Microblocks diff --git a/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/mining.md b/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/mining.md deleted file mode 100644 index 49be4d93c7..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/mining.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Minería -description: Una guía para la minería en Stacks 2.0 -sidebar_position: 4 ---- - -## Introducción - -Esta guía destaca algunos detalles técnicos relacionados con la minería en la red Stacks 2.0. - -Para conocer los pasos sobre cómo configurar su propio minero, consulte [minero en tesnet](nodes-and-miners/miner-testnet.md) y [minero en mainnet](nodes-and-miners/miner-testnet.md). - -## Frecuencia de minería - -Un nuevo bloque de Stacks puede ser minado una vez por bloque de Bitcoin. To be considered for mining a block, a miner must have a block commit included in a Bitcoin block. If a miner wishes to update their commitment after submission, they may use Bitcoin Replace-By-Fee. - -## Coinbase rewards - -Los mineros reciben recompensas de monedas por los bloques que ganen. - -Los montos de recompensa son: - -- 1000 STX por bloque son liberados en los primeros 4 años de minería -- 500 STX por bloque son liberados durante los siguientes 4 años -- 250 STX por bloque son liberados durante los siguientes 4 años -- 125 STX por bloque son liberados desde entonces indefinidamente. - -Estos "halvings" se sincronizan con los halvings de Bitcoin. - -![coinbase rewards](/img/pages/coinbase-rewards.png) - -## Comisiones de las transacciones - -Los mineros reciben comisiones de Stacks por las transacciones extraídas en cualquier bloque que producen. - -Para las transacciones extraídas en microbloques, el minero que produce el microbloque recibe el 40% de las comisiones, mientras que el minero que confirma el microbloque recibe 60% de las comisiones. - -## Madurez de recompensa - -Las recompensas por bloque y las tarifas de transacción tardan 100 bloques en la blockchain de Bitcoin en madurar. Después de extraer con éxito un bloque, sus recompensas aparecen en su cuenta de Stacks después de ~ 24 horas. - -## Minería con proof-of-transfer - -Miners commit Bitcoin to **two** addresses in every leader block commit. The amount committed to each address must be the same. The addresses are chosen from the current reward set of stacking participants. Addresses are chosen using a verifiable-random-function, and determining the correct two addresses for a given block requires monitoring the Stacks chain. - -![mining with pox](/img/pages/mining-with-pox.png) - -## 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, 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. - -While there is no minimum BTC commitment enforced by the protocol, in practice, there's a floor constrained by [dust](https://unchained-capital.com/blog/dust-thermodynamics/)": basically, if the fees for a transaction exceed the value of the spent output, it's considered dust. How dust is [calculated](https://github.com/bitcoin/bitcoin/blob/master/src/policy/policy.cpp#L14) depends on a number of factors, we've found 5,500 satoshis to be good lower bound per [output](https://learnmeabitcoin.com/technical/output). Bitcoin transactions from Stacks miners contain two outputs (for Proof-of-Transfer), so a commitment of at least 11,000 satoshis / block is recommended. - -To calculate the amount of BTC to send miners should: - -- Guess the price BTC/STX for the next day (100 blocks later) -- Guess the total amount of BTCs committed by all miners - -## Microbloques - -La blockchain de Stacks produce bloques al mismo ritmo que la cadena de bloques de Bitcoin. Para proporcionar transacciones de menor latencia, los mineros pueden optar por habilitar microbloques. Los microbloques permiten al líder del bloque actual transmitir transacciones e incluir sus estais de transiciones en el epoch actual. - -If a block leader opts to produce microblocks, the next leader builds the chain tip off the last microblock that the current leader produces. - -El modelo de la trasmisión de bloques se describe en [SIP-001][]. - -[SIP-001]: https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md#operation-as-a-leader diff --git a/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/network.md b/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/network.md deleted file mode 100644 index 8e6783caf6..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/network.md +++ /dev/null @@ -1,146 +0,0 @@ ---- -title: Red -description: Guía de la red Stacks 2.0 -sidebar_position: 7 ---- - -## Tokens - -Los tokens de Stacks (STX) son los tokens nativos en la blockchain Stacks 2.0. La fracción más pequeña es un micro-STX. 1,000,000 micro-STX hacen un Stack (STX). - -Los montos de STX deben almacenarse como enteros (8 bytes de longitud), y representados en montos de micro-STX. Para propósitos de visualización, el micro-STX se divide entre 1,000,00 (precisión decimal de 6). - -## Comisiones - -Las comisiones se utilizan para compensar a los mineros por confirmar las transacciones en la blockchain Stacks 2.0. La comisión se calcula en base a la tasa estimada de comisión y al tamaño de la transacción en peso bruto en bytes. La tasa de comisión es una variable determinada por el mercado. Para la [testnet](testnet)se establece en 1 micro-STX. - -Las estimaciones de comisiones pueden obtenerse a través del endpoint [`GET /v2/fees/transfer`](https://docs.hiro.so/api#operation/get_fee_transfer): - -```bash -# para mainnet, reemplazar `testnet` por `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/fees/transfer' -``` - -La API responderá con la tasa de comisión (como entero): - -```json -1 -``` - -[La librería Stacks JS](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) soporta estimación de comisiones para: - -- transferencias de token (`estimateTransfer`) -- publicación de contrato (`estimateContractDeploy`) -- llamadas a contrato sin solo-lectura (`estimateContractFunctionCall`) - -:::tip For an implementation using a different language than JavaScript, please review [this reference implementation](https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/src/builders.ts#L97). ::: - -## Nonces - -Cada cuenta lleva una [propiedad nonce](https://en.wikipedia.org/wiki/Cryptographic_nonce) que indica el número de transacciones procesadas para la cuenta dada. Las nonces son códigos de un solo uso, comenzando en `0` para cuentas nuevas e incrementado en 1 en cada transacción. - -Los onces se añaden a todas las transacciones y ayudan a identificarlas con el fin de asegurar que las transacciones se procesan en orden y para evitar un proceso duplicado. - -:::tip -El mecanismo de consenso también asegura que las transacciones no sean "repetidas" de dos maneras. En primer lugar, los nodos consultan las transacciones no gastadas (UTXOs) en orden de satisfacer sus condiciones de gasto en una nueva transacción. En segundo lugar, mensajes son enviados entre nodos para revisar la secuencia de números. -::: - -Cuando se construye una nueva transacción de transferencia de tokens, se debe obtener y establecer el nonce más reciente de la cuenta. - -:::tip La API proporciona un endpoint para [simplificar el manejo de nonce](https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling). ::: - -## Confirmaciones - -La red Stacks 2.0 está anclada a la red bitcoin. Esto permite que las transacciones en Stacks hereden la misma finalidad y seguridad de la blockchain de Bitcoin. - -El tiempo para minar un bloque, para confirmar las transacciones, eventualmente coincidirá con el "tiempo de bloque" esperado de la red bitcoin: 10 minutos. - -:::tip Las transacciones también se pueden ser minadas en [microbloques](microblocks), reduciendo la latencia significativamente. ::: - -El tiempo del bloque está codificado y cambiará a lo largo de las fases de implementación de la [red de pruebas](testnet). El tiempo actual del bloque se puede obtener a través del endpoint [`GET /extended/v1/info/network_block_times`](https://docs.hiro.so/api#operation/get_network_block_times): - -```bash -# para mainnet, reemplazar `testnet` por `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/info/network_block_times' -``` - -La API responderá con el tiempo del bloque (en segundos): - -```js -{ - "testnet": { - "target_block_time": 120 - }, - "mainnet": { - "target_block_time": 600 - } -} -``` - -## Llamadas a funciones de solo-lectura - -Los contratos inteligentes pueden exponer las llamadas a funciones públicas. Para las funciones que hacen modificaciones de estado a la blockchain, las transacciones deben ser generadas y transmitidas. - -Sin embargo, para llamadas de solo-lectura, las transacciones **no son** requeridas. En su lugar, estas llamadas se pueden hacer utilizando la [API de Stacks Blockchain](https://docs.hiro.so/get-started/stacks-blockchain-api). - -:::caution Llamadas de contratos solo-lectura no requieren transacciones::: - -Se puede hacer una llamada de solo-lectura utilizando el endpoint [`POST /v2/contracts/call-read///`](https://docs.hiro.so/api#operation/call_read_only_function): - -```bash -# para mainnet, reemplazar `testnet` por `mainnet` -curl --location --request POST 'https://stacks-node-api.testnet.stacks. o/v2/contracts/call-read///' \ ---header 'Content-Type: application/json' \ ---data-raw '{ - "sender":.", - "arguments": [, -}' -``` - -Ejemplo de respuesta para una llamada exitosa: - -```js -{ - "okay": true, - "result": "" -} -``` - -:::tip Para establecer los argumentos de llamada a la función y leer el resultado, [Los valores de Claridad](../write-smart-contracts/values) necesitan ser serializados en una cadena hexadecimal. La librería [Stacks Transactions JS](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) soporta estas operaciones ::: - -## Consultas - -Los detalles de la red de Stacks 2.0 pueden ser consultados usando la [API de Stacks Blockchain](https://docs.hiro.so/get-started/stacks-blockchain-api). - -### Comprobación de estado - -El [comprobador de estado](https://stacks-status.com/) es un servicio que proporciona una interfaz de usuario para revisar rápidamente la salud de la blockchain de Stacks 2.0. - -### Información de la red - -La información de la red se puede obtener usando el endpoint [`GET /v2/info`](https://docs.hiro.so/api#operation/get_core_api_info): - -```bash -# para mainnet, reemplazar `testnet` por `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/info' -``` - -Ejemplo de respuesta: - -```js -{ - "peer_version": 385875968, - "burn_consensus": "826401d65cf3671210a3fb135d827d549c0b4d37", - "burn_block_height": 1972, - "stable_burn_consensus": "e27ea23f199076bc41a729d76a813e125b725f64", - "stable_burn_block_height": 1971, - "server_version": "blockstack-core 0.0.1 => 23.0.0.0 (master:bdd042242+, release build, linux [x86_64]", - "network_id": 2147483648, - "parent_network_id": 3669344250, - "stacks_tip_height": 933, - "stacks_tip": "1f601823fbcc5b6b2215b2ff59d2818fba61ee4a3cea426d8bc3dbb268005d8f", - "stacks_tip_burn_block": "54c56a9685545c45accf42b5dcb2787c97eda8185a1c794daf9b5a59d4807abc", - "unanchored_tip": "71948ee211dac3b241eb65d881637f649d0d49ac08ee4a41c29217d3026d7aae", - "exit_at_block_height": 28160 -} -``` diff --git a/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md b/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md deleted file mode 100644 index 63583b6076..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Prueba de transferencia -description: Conozca el mecanismo de consenso de prueba de transferencia -sidebar_position: 3 ---- - -## Visión general - -Los algoritmos de consenso para los *blockchains* requieren recursos computacionales o financieros para lograr que el *blockchain* sea seguro. La práctica general del consenso descentralizado consiste en lograr que sea prácticamente inviable que cualquier actor malicioso tenga suficiente poder computacional o participación en la propiedad para atacar la red. - -Los mecanismos de consenso populares en los *blockchain* modernos incluyen la prueba de trabajo, en la que los nodos dedican recursos computacionales, y la prueba de participación, en la que los nodos dedican recursos financieros para proteger la red. - -La prueba de quemado es un nuevo mecanismo de consenso en el que los mineros compiten por «quemar» (destruir) una criptomoneda obtenida por medio de la prueba de trabajo en reemplazo de los recursos informáticos. - -La prueba de transferencia (PoX) es una extensión del mecanismo de prueba de quemado. La Pox utiliza la criptomoneda obtenida por medio de la prueba de trabajo de un *blockchain* establecido para anclar uno nuevo. Sin embargo, a diferencia de la prueba de quemado, en lugar de quemar esta criptomoneda, los mineros la transfieren a otros participantes en la red. - -![Mecanismo de PoX](/img/pox-mechanism.png) - -Esto permite que los participantes de dicha red aseguren la red de la criptomoneda y ganen una recompensa en la criptomoneda base. Así, los *blockchain* que utilizan la prueba de transferencia están anclados a la cadena de prueba de trabajo elegida. Stacks utiliza [Bitcoin](#why-bitcoin) como su cadena de anclaje. - -![Participantes de la PoX](/img/pox-participants.png) - -## ¿Por qué Bitcoin? - -Hay una serie de razones por las que Stacks eligió a Bitcoin como el *blockchain* para generar consenso. Es el protocolo de *blockchain* más antiguo, lanzado en 2009, y se ha convertido en un activo reconocido fuera de la comunidad relacionada con las criptomonedas. BTC ha contado con una mayor capitalización en el mercado en comparación con cualquier otra criptomoneda durante la última década. - -Bitcoin defiende la simplicidad y la estabilidad, y ha superado la prueba del tiempo. Influir o atacar la red es inviable o poco práctico para cualquier posible *hacker*. Es una de las pocas criptomonedas que captan la atención pública. Bitcoin es un nombre popular y es reconocido como un activo por gobiernos, grandes corporaciones e instituciones bancarias tradicionales. Por último, Bitcoin se considera, en gran medida, una forma de almacenamiento de valor fiable y proporciona una amplia infraestructura para apoyar el mecanismo de consenso de prueba de transferencia. - -El SIP-001 proporciona una lista completa [de las razones por las que Bitcoin fue elegido para asegurar Stacks](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md). - -![btc-stacks](/img/pox-why-bitcoin.png) - -## Bloques y microbloques - -El *blockchain* de Stacks permite aumentar el rendimiento de las transacciones mediante un mecanismo denominado microbloques. Bitcoin y Stacks progresan al mismo tiempo, y sus bloques se confirman simultáneamente. En Stacks, esto se denomina «bloque de anclaje». Un bloque de transacciones de Stacks completo corresponde a una sola transacción en Bitcoin. Esto mejora significativamente la relación coste/byte para el procesamiento de las transacciones en Stacks. Debido a la creación simultánea de bloques, Bitcoin limita la velocidad con la que se crean los bloques en Stacks, evitando así ataques de denegación de servicio a dicha red. - -Sin embargo, entre los bloques de anclaje de Stacks que se asientan en *blockchain* Bitcoin, también hay un número variable de microbloques que permiten asentar rápidamente las transacciones de Stacks con un alto grado de confianza. Esto logra que el rendimiento de las transacciones de Stacks escale independientemente de Bitcoin, al mismo tiempo que las mismas se asienten periódicamente, pero de forma definitiva, en la cadena Bitcoin. El *blockchain* Stacks adopta un modelo de flujo de bloques en el que cada líder puede seleccionar y agrupar, de forma adaptativa, las transacciones en su bloque a medida que llegan al mempool. Por lo tanto, cuando se confirma un bloque de anclaje, se agrupan y procesan todas las transacciones en el flujo principal del microbloque. Este es un método sin precedentes que permite lograr escalabilidad sin crear un protocolo totalmente separado de Bitcoin. - -![stx-microblock](/img/stx-microblocks.png) - -## Desbloquear el capital de Bitcoin - -Stacks también desbloquea los cientos de miles de millones de capital en Bitcoin, y ofrece a los Bitcoiners nuevas oportunidades para utilizar y ganar BTC. Stacks acompaña al ecosistema de Bitcoin, y el trabajo conjunto de estas redes da lugar a formas totalmente novedosas a la hora de usar BTC. El ecosistema de Stacks pone a disposición de los poseedores de Bitcoin aplicaciones para criptomoneda interactivas. Además, al hacer stacking de los tókenes STX y al participar en el mecanismo de consenso PoX, los usuarios tienen la oportunidad de ganar BTC mientras aseguran la cadena Stacks. - -![Desbloquear Bitcoin](/img/pox-unlocking-btc.png) - -## Clarity y el estado Bitcoin - -Los contratos inteligentes de Clarity también tienen una visibilidad única en relación con el estado del *blockchain* Bitcoin. Esto significa que la lógica del contrato en un archivo de Clarity tiene la capacidad de activarse cuando se confirman ciertas transacciones de Bitcoin. Los contratos inteligentes en Clarity tienen pruebas de verificación de pago simple (SPV) integradas para Bitcoin que hacen que la interacción con el estado de Bitcoin sea mucho más sencilla para los desarrolladores. Además, los contratos en Clarity pueden bifurcarse de la cadena Bitcoin original. Por lo tanto, en el caso extremo en el que Bitcoin se bifurcase, los desarrolladores no tendrían que preocuparse por ajustar el despliegue de sus contratos inteligentes. - -## Vea también - -- [Lea el whitepaper completo de PoX](https://community.stacks.org/pox) -- [Ver al Presidente Ejecutivo de Hiro Muneeb Ali y Evangelista Joe Bender dar una visión general del revolucionario mecanismo de minería PoX de Stack](https://www.youtube.com/watch?v=NY_eUrIcWOY) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md b/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md deleted file mode 100644 index 19f2693ef0..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: Stacking -description: Introducción al mecanismo de recompensa de la prueba de transferencia -sidebar_position: 9 ---- - -## Introducción - -Stacking recompensa a los poseedores de tokens Stacks (STX) con bitcoins por brindar un valioso servicio a la red al bloquear sus tokens durante un tiempo determinado. - -![](/img/stacking.png) - -Stacking es una acción integrada, requerida por el mecanismo de "proof-of-transfer" (PoX). El mecanismo PoX es ejecutado por todos los mineros de la red Stacks 2.0. - -:::info El algoritmo de consenso de staking se implementa como un contrato inteligente, usando [Clarity](../write-smart-contracts/). [Lea más sobre el contrato](../noteworthy-contracts/stacking-contract). ::: - -## Flujo del Stacking - -El mecanismo de Stacking puede presentarse como un flujo de acciones: - -![Flujo del Stacking](/img/stacking-illustration.png) - -1. Realizar llamadas API para obtener detalles sobre el próximo ciclo de recompensas -2. Para una cuenta de Stacks específica, confirmar elegibilidad -3. Confirmar la dirección de recompensa de BTC y la duración del bloqueo -4. La transacción se transmite y los tokens STX se bloquean. Esto debe suceder antes de la fase de preparación del próximo ciclo de recompensas, los últimos 100 bloques de Bitcoin de la fase de recompensas en curso -5. El mecanismo de Staking ejecuta ciclos de recompensa y envía recompensas a la dirección de recompensa BTC establecida -6. Durante el período de bloqueo, se pueden obtener detalles sobre el tiempo de desbloqueo, recompensas y más -7. Una vez que pasa el período de bloqueo, los tokens son liberados y accesibles de nuevo -8. Muestra el historial de recompensas, incluyendo detalles como ganancias de ciclos de recompensa anteriores - -:::info Ten en cuenta que la duración de un ciclo de recompensa es de ~2 semanas. Esta duración se basa en el tiempo de bloque objetivo de la red (10 minutos) y puede ser mayor a veces debido a [variaciones de tiempo de confirmación](https://www.blockchain.com/charts/median-confirmation-time) de la red bitcoin. ::: - -## Flujo de delegación Staking - -El flujo de Staking es diferente para los casos de uso de la delegación: - -![Delegated tacking flow](/img/stacking-delegation-illustration.png) - -- Antes de que se pueda iniciar el Stacking para un poseedor de tokens, el delegador necesita que se le conceda permiso en nombre del propietario de la cuenta. El permiso está restringido a la cantidad máxima que el delegado puede delegar. La cantidad máxima no está limitada por los fondos disponibles y puede establecerse mucho más alta. Una cuenta sólo puede ser asociada con un solo delegador -- La cuenta tiene que definir la relación de delegación. Opcionalmente pueden restringir la dirección de recompensa de Bitcoin que debe ser utilizada para los pagos, y la altura del bloque de caducidad para el permiso, limitando así el tiempo que un delegador tiene permiso para delegar -- Los Delegadores deben bloquear Stacks de diferentes cuentas ("fase de pool") hasta que alcancen la cantidad mínima de Stacks requeridos para participar en Stacking -- Una vez que un delegador bloquea suficientes tokens STX, pueden finalizar y comprometer su participación en el próximo ciclo de recompensas -- Ciertas relaciones de delegación pueden permitir al titular de STX recibir el pago directamente del minero (paso 5/6) -- La terminación de la relación con la delegación puede ocurrir automáticamente según las reglas de vencimiento establecidas o mediante la revocación activa de los derechos de delegación - -## Minería de PoX - -La minería PoX es una modificación de la minería Proof-of-Burn (PoB) en lugar de enviar el bitcoin entregado a una dirección de quemado, se transfiere a los poseedores elegibles de STX que participan en el protocolo de Stacking. - -:::note -Un minero de PoX solo puede recibir tokens STX recién mintados cuando transfieren bitcoins a los dueños elegibles de tokens STX -::: - -![Mining flow](/img/pox-mining-flow.png) - -Los mineros ejecutan los nodos de Stacks con minería habilitada para participar en el mecanismo PoX. El nodo implementa el mecanismo PoX, que garantiza un manejo adecuado e incentivos a través de cuatro fases clave: - -- Registro: los mineros se registran para una futura elección enviando datos de consenso a la red -- Compromiso: los mineros registrados transfieren Bitcoin para participar en la elección. Los BTC comprometidos se envían a un conjunto titulares de tokens STX participantes -- Elección: una función aleatoria verificable elige un minero para escribir un nuevo bloque en la blockchain de Stacks -- Ensamblado: el minero elegido escribe el nuevo bloque y recolecta recompensas en forma de nuevos tokens STX - -## Elegibilidad del poseedor del token - -Los poseedores de tokens Stacks (STX) no reciben automáticamente recompensas de Stacking. En su lugar, deben hacer: - -- Comprometerse a participar antes de que comience un ciclo de recompensas -- Compromete la cantidad mínima de tokens STX para asegurar un slot de recompensas, o agrupe con otros para alcanzar el mínimo -- Bloquear tokens STX para un período específico -- Proporcionar una dirección de Bitcoin compatible para recibir recompensas (segwit nativo no es compatible) - -El siguiente diagrama describe cómo se determinan los tokens mínimos de STX por slot. Más información sobre [mínimos dinámicos para stacking](https://stacking.club) está disponible en stacking.club. - -![Dynamic minimum for individual eligibility](/img/stacking-dynamic-minimum.png) - -Los poseedores de token tienen una variedad de proveedores y herramientas para apoyar su participación en Stacking. El sitio web de Stacks contiene una [lista de proveedores de stacking y pools](https://stacks.org/stacking#earn). - -## Staking en el algoritmo de consenso de PoX - -El Stacking es una capacidad integrada de PoX y se produce a través de un conjunto de acciones en la blockchain de Stacks. Los [detalles completos de la implementación de proof-of-transfer](https://github.com/stacks-network/stacks-blockchain/blob/develop/sip/sip-007-stacking-consensus.md) están en SIP-007. A continuación se muestra un resumen de las acciones más relevantes del algoritmo. - -![PoX cycles](/img/pox-cycles.png) - -- El Stacking ocurre sobre ciclos de recompensa con una duración fija. En cada ciclo de recompensa, un conjunto de direcciones de Bitcoin asociadas con los participantes de staking reciben recompensas BTC -- Un ciclo de recompensa consta de dos fases: preparar y recompensar -- Durante la fase de preparación, los mineros deciden un bloque de anclaje y un conjunto de recompensas. Minar cualquier bifurcación descendiente del bloque ancla requiere transferir fondos de minería a las direcciones de recompensa apropiadas. El conjunto de recompensas es el conjunto de direcciones de Bitcoin que son elegibles para recibir fondos en el ciclo de recompensa -- Los mineros se registran como candidatos líderes para una futura elección enviando una transacción clave que quema criptomoneda. La transacción también registra la sugerencia de cadena preferida del líder (debe ser un descendiente del bloque ancla) y los fondos comprometidos a 2 direcciones del conjunto de recompensas -- Los poseedores de token se registran para el próximo ciclo de recompensas mediante la transmición un mensaje firmado que bloquea los tokens STX asociados durante un período de bloqueo especificado en el protocolo, especifica una dirección de Bitcoin para recibir los fondos, y vota en el tip de la cadena de Stacks -- Múltiples líderes pueden comprometerse con la misma tip de la cadena. El líder que gana la elección y los compañeros que también queman por ese líder comparten colectivamente la recompensa, proporcional a cuánto se quemó cada uno -- Los tokens bloqueadas de los tenedores de tokens se desbloquean automáticamente tan pronto como finaliza el período de bloqueo - -## Dirección de Bitcoin - -:::danger Debes proporcionar una dirección BTC en uno de dos formatos: - -* [Legacy (P2PKH)](https://en.bitcoin.it/wiki/Transaction#Pay-to-PubkeyHash), que comienza con `1`. - -* [ Segregated Witness / Segwit (P2SH)](https://en.bitcoin.it/wiki/Pay_to_script_hash), que comienza con `3`. El formato "Native Segwit" (que comienza con `bc1`), por ejemplo, no es compatible. ::: - -El contrato de stacking necesita un formato especial para la dirección de Bitcoin (la dirección de recompensa). Esto es necesario para asegurar que los mineros puedan construir correctamente la transacción de Bitcoin que contiene la dirección de recompensa. - -La dirección debe especificarse en el siguiente formato utilizando el lenguaje de Clarity: - -```clar -;; una tupla de una versión y buffer de hashbytes -(pox-addr (tuple (versión (buff 1)) (hashbytes (buff 20)))) -``` - -La `versión` del búfer debe representar qué tipo de dirección de bitcoin está siendo enviada. Puede ser uno de los siguientes: - -```js -SerializeP2PKH = 0x00, // hash160(public-key), igual que p2pkh de bitcoin -SerializeP2SH = 0x01, // hash160(multisig-redeem-script), al igual que el multisig p2sh de bitcoin, -SerializeP2WPKH = 0x02, // hash160(segwit-program-00(p2pkh)), igual que el p2sh-p2wpkh -SerializeP2WSH = 0x03, // hash160(segwit-program-00(public-keys)), igual que el p2sh-p2wsh de bitcoin -``` - -Los `hashbytes` son los 20 hash bytes de la dirección bitcoin. Puedes obtenerlo de una librería de bitcoin, por ejemplo usando [`bitcoinjs-lib`](https://github.com/bitcoinjs/bitcoinjs-lib): - -```js -const btc = require('bitcoinjs-lib'); -console.log( - '0x' + btc.address.fromBase58Check('1C56LYirKa3PFXFsvhSESgDy2acEHVAEt6').hash.toString('hex') -); -``` - -## Elegir la estrategia de Stacking adecuada - -[Aquí](https://blog.stacks.co/stacking-strategy) hay un artículo interesante que puede ayudarle a elegir la estrategia de staking adecuada. - - -## Where to Stacks? - -Puedes acumular solo, en un pool o en un exchange: -### Staking por tu cuenta - -Staking por su cuenta no es custodial. - -Staking por su cuenta requiere un mínimo de protocolo (cantidad cambia pero alrededor de 100.000 STX). - -[Hiro Wallet](https://www.hiro.so/wallet) permite hacer staking por tu cuenta. - -### Stacking on a pool - -Hacer stacking en un pool permite acumular sin el requisito del mínimo de protocolo. - -Algunos pools disponibles son: - -| Pool | Tipo | Pays rewards in | Fee | Cantidad mínima | -| --------------------------------------------------- | ------------- |:---------------:| --- |:---------------:| -| [Friedger's Pool](https://pool.friedger.de/) | Non custodial | STX or xBTC | No | 40 STX | -| [Planbetter](https://planbetter.org/) | Non custodial | BTC | 5% | 200 STX | -| [Stacked](https://staking.staked.us/stacks-staking) | Non custodial | BTC | | 100,000 STX | -| [Xverse](https://www.xverse.app/) | Non custodial | BTC | No | 100 STX | - -### Hacer Staking en un exchange - -Hacer Stacking en un exchange es custodial, lo que significa que confías tus Stacks al exchange. - -Varios exchanges permiten hacer stacking directamente en sus sitios. Ejemplos son [Okcoin](https://www.okcoin.com) y [Binance](https://www.binance.com/en/staking) - -## Estadísticas de stacking - -Puedes ver todo tipo de datos de stacking y estadísticas en [Stacking Club](https://stacking.club) \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md b/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md deleted file mode 100644 index d942d6af8f..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Stacks Blockchain API -description: Interacting with the Stacks 2.0 Blockchain via API ---- - -## Temporal page because of a Crowdin bug \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md b/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md deleted file mode 100644 index 70ae921c84..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Especificaciones técnicas -description: Resumen de las especificaciones técnicas de Stacks 2.0 -sidebar_position: 10 ---- - -## Consenso - -- Prueba de Transferencia (PoX) como se describe en [SIP-007](https://github.com/stacksgov/sips/blob/main/sips/sip-007/sip-007-stacking-consensus.md) -- La red pasará a la Prueba de Burn (PoB) como se describe en [SIP-001](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md) después de 10 años. [Más información sobre Proof-of-Burn en SIP-001](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md). -- Modelo de amenaza - - El 51% del poder de minería maliciosa en Stacks puede realizar un ataque de doble gasto - - El 51% del poder de minería maliciosa de Bitcoin puede reorganizar la cadena de Stacks -- Diferentes actores y sus funciones - - Los mineros de Stacks empaquetan transacciones en bloques, las minan a través de una transacción de Bitcoin, las propagan y, si ganan la carrera de bloques, agregan microbloques a su bloque ganador hasta que se mina el siguiente bloque. El siguiente bloque confirma el flujo de microbloques. - - Los holders de Stacks pueden alterar el cálculo de los límites de bloque (sujeto al veto de los mineros) y pueden votar para dashabilitar las recompensas de prueba de transferencia por un ciclo de recompensa. -- Las transacciones se consideran definitivas cuando finaliza la correspondiente transacción de "commit de bloque" en Bitcoin. Normalmente esto puede ser por 3-6 confirmaciones. -- Para obtener más información, consulte [Prueba de Transferencia](proof-of-transfer). - -## Minería en Prueba de transferencia - -- Coinbase reward schedule: - - 1000 STX/block for first 4 years - - 500 STX/block for following 4 years - - 250 STX/block for subsequent 4 years - - 125 STX/block in perpetuity after that -- Coinbase rewards accumulate for "missed sortitions": If a Bitcoin block has no sortition (at height N), then any Stacks block mined in a subsequent sortition that builds off of any Stacks chain tip that existed at the penultimate sortition (at height N-1) may claim its coinbase. This encourages miners to keep mining even if Bitcoin fees are high. -- Initial mining bonus: This is a special case of the above to incentivize early miners. Coinbase for all burnchain blocks between the first burn block height (to be chosen by independent miners as part of the Stacks 2.0 launch) and the first sortition winner accumulate and are distributed to miners over a fixed window (to be determined). For instance, say burn block height is 10,000 and first sortition is at block 10500 and distribution window is 100 blocks, then coinbase for the first 500 blocks (10,500 - 10,000) will be distributed evenly to miners who win sortition over the subsequent 100 blocks. -- 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 at least 11,000 satoshis (5,500 sats / [UTXO output](https://learnmeabitcoin.com/technical/utxo)); 2 outputs / block) to avoid "dust." -- For more details, see [Mining](mining). - -## Stacking - -- Stacking works in 2 phases - 1. Prepare phase: In this phase an "anchor block" is chosen. The qualifying set of addresses ("reward set") is determined based on the snapshot of the chain at the anchor block. Length of prepare phase is 100 blocks. Stacking commitments need to be confirmed before this phase starts - 2. Reward phase: In this phase miner BTC commitments are distributed amongst the reward set. Reward cycle length is 2000 BTC blocks (~2 weeks). -- 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/stacksgov/sips/blob/main/sips/sip-007/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.stacks.co/references/stacking-contract#delegate-stx). -- Only two types of BTC reward addresses are supported: [Legacy (P2PKH)](https://en.bitcoin.it/wiki/Transaction#Pay-to-PubkeyHash) or [Segregated Witness / Segwit (P2SH)](https://en.bitcoin.it/wiki/Pay_to_script_hash). Native Segwit is not supported. -- Further reading: [Stacking](stacking) - -## Cuentas y direcciones - -- Transactions in the Stacks blockchain originate from, are paid for by, and execute under the authority of accounts -- An account is fully specified by its address + nonce + assets -- 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 (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](accounts) - -## Transacciones - -- Transaction 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 - 2. _paying account_ is the account that is billed by the leader for the cost of validating and executing the transaction - 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 -- Transactions can be batched or streamed into blocks. The behavior can be controlled by the anchor mode of a transaction. With streaming ([microblocks](microblocks)), a faster confirmation time is possible. -- 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. -- Mempool limit for concurrent pending transactions is 25 per account -- Pending mempool transactions will be garbage-collected [256 blocks after receipt](https://github.com/stacks-network/stacks-blockchain/blob/master/src/core/mempool.rs#L62). With 10 minutes target block time, this would equal ~42 hours -- [Learn more about transaction encoding in SIP-005](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md#transaction-encoding) -- [Transaction signing and verification are described in SIP-005](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md#transaction-signing-and-verifying) -- All transactions impacting account balance are atomic, a transfer operation can not increment one account’s balance without decrementing another’s. However, transactions that perform multiple account actions (for example, transferring from multiple accounts) may partially complete. -- Transactions can include a memo string (max 34 bytes) - -## Vea también - -- [Read the full Stacks 2.0: Apps and Smart Contracts for Bitcoin whitepaper](https://cloudflare-ipfs.com/ipfs/QmaGgiVHymeDjAc3aF1AwyhiFFwN97pme5m536cHT4FsAW). - -- [Watch Aaron Blankstein video on Stacks whitepater v2](https://www.youtube.com/watch?v=Wd-Bfe8Sn-Y). \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md b/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md deleted file mode 100644 index d4e4fb8259..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Testnet -description: Prueba tus contratos inteligentes y aplicaciones -sidebar_position: 2 ---- - -## Acerca de Testnet - -The testnet is a separate blockchain from the Stacks mainnet analogous to a staging environment. Es una red utilizada por los desarrolladores para probar sus aplicaciones, contratos inteligentes o cambios en el protocolo en un entorno similar al de producción. Produce bloques aproximadamente a la misma velocidad que en mainnet; alrededor de 1 bloque cada 10 minutos en promedio. La red testnet de Stacks rara vez se reinicia. - -### Faucet - -El faucet de testnet proporciona Stacks Token (STX) gratis para probar. Estos no son los mismos que STX en mainnet y no tienen valor. Puedes obtener STX en el faucet del [Sandbox de Stacks Explorer ](https://explorer.stacks.co/sandbox/faucet?chain=testnet)o usando la [API](https://docs.hiro.so/api#tag/Faucets). - -Para obtener tokens STX desde el menú del explorador, vaya a la pestaña "Faucet" de la izquierda y haga clic en el botón "Solicitar STX". - -![](/img/stx_faucet.png) - -También puedes probar hacer [Stacking](stacking) dando clic en `I want to stack`. - -:::note -El Sandbox del explorador requiere iniciar sesión con una Stacks wallet -::: - -### Testnet API - -La API Stacks Blockchain para la red de pruebas testnet está disponible en esta URL base: - -```shell -https://stacks-node-api.testnet.stacks.co/ -``` - -![](/img/api_testnet_status.png) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md b/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md deleted file mode 100644 index 0cb083c6f9..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Transacciones -description: Guía de transacciones Stacks 2.0 -sidebar_position: 6 ---- - -## Introducción - -Las transacciones son la unidad fundamental de la ejecución en el blockchain de Stacks. Cada transacción se origina a partir de una [Cuenta Stacks 2.0](accounts), y se mantiene en el historial de la blockchain de Stacks para la eternidad. Esta guía te ayuda a entender las transacciones de Stacks 2.0. - -## Ciclo de vida - -Las transacciones pasan por fases antes de ser finalmente confirmadas, y disponibles para todos, en la red Stacks 2.0. - -![Transaction lifecycle](/img/tx-lifecycle.png) - -- **Generar**: Las transacciones se ensamblan según la especificación de la codificación. -- **Validar y firmar**: Las transacciones son validadas para confirmar que están bien formadas. Las firmas requeridas son llenadas. -- **Broadcast**: Las transacciones son enviadas a un nodo. -- **Registrar**: Un minero recibe transacciones, verifica y las agrega al ["mempool,"](https://academy.binance.com/en/glossary/mempool) un área de retención para todas las transacciones pendientes. -- **Procesar**: Los mineros revisan el mempool y seleccionan las transacciones para el siguiente bloque a ser extraído. Dependiendo del tipo de transacción, pueden ocurrir diferentes acciones durante este paso. Por ejemplo, se podrían verificar las condiciones posteriores para una transferencia de tokens, se podrían acuñar tokens definidos por contrato inteligente, o se podría intentar llamar a un método de contrato inteligente existente. -- **Confirma**: Los mineros minan con éxito bloques con un conjunto de transacciones. Las transacciones dentro de la red se propagan con éxito. - -:::note Una transacción puede tener uno de tres estados una vez registrado: `pending`, `success`, o `failed`. ::: - -## Tipos - -Stacks 2.0 soporta un conjunto de diferentes tipos de transacción: - -| **Tipo** | **Valor** | **Descripción** | -| ----------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Coinbase | `coinbase` | La primera transacción en un nuevo bloque (una entidad que contiene varias transacciones). Utilizado para registrar las recompensas del bloque. No se generan y transmiten de forma manual como otros tipos de transacciones. | -| Token transfer | `token_transfer` | Transferencia de asset de un remitente a un destinatario | -| Contract deploy | `smart_contract` | Instanciación del contrato | -| Contract call | `contract_call` | Llamada de contrato para una función pública que no sea de solo-lectura | -| Poison Microblock | `poison_microblock` | Castigar a los líderes que intencionalmente empaquetan microbloques equívocos | - -Un ejemplo de cada tipo de transacción se puede encontrar en la [definición de respuesta de la API Stacks Blockchain para transacciones](https://docs.hiro.so/api#operation/get_transaction_by_id). - -:::caution Llamadas de contratos solo-lectura **no** requieren transacciones. Lea más al respecto en la guía de red [](network#read-only-function-calls). ::: diff --git a/i18n/es/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md b/i18n/es/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md deleted file mode 100644 index fd45c80583..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Clarity Language -description: Overview of the Clarity language constructs -sidebar_label: Clarity Language -tags: - - clarity ---- - -## Clarity Type System - -The Clarity language uses a strong static type system. Function arguments and database schemas require specified types, and use of types is checked during contract launch. The type system does _not_ have a universal super type. - -## Public Functions - -Functions specified via `define-public` statements are _public_ functions and these are the only types of functions which may be called directly through signed blockchain transactions. In addition to being callable directly from a transaction (see the Stacks wire formats for more details on Stacks transactions), public functions may be called by other smart contracts. - -Public functions _must_ return a `(response ...)` type. This is used by Clarity to determine whether or not to materialize any changes from the execution of the function. If a function returns an `(err ...)` type, any mutations on the blockchain state from executing the function (and any function that it called during execution) will be aborted. - -In addition to functions defined via `define-public`, contracts may expose read-only functions. These functions, defined via `define-read-only`, are callable by other smart contracts, and may be queryable via public blockchain explorers. These functions _may not_ mutate any blockchain state. Unlike normal public functions, read-only functions may return any type. - -## Contract Calls - -A smart contract may call functions from other smart contracts using a `(contract-call?)` function. - -This function returns a response type result -- the return value of the called smart contract function. - -We distinguish 2 different types of `contract-call?`: - -### Static dispatch - -The callee is a known, invariant contract available on-chain when the caller contract is deployed. In this case, the callee's principal is provided as the first argument, followed by the name of the method and its arguments: - -```clarity -(contract-call? - .registrar - register-name - name-to-register) -``` - -### Dynamic dispatch - -The callee is passed as an argument, and typed as a trait reference (``). - -```clarity -(define-public (swap (token-a ) - (amount-a uint) - (owner-a principal) - (token-b ) - (amount-b uint) - (owner-b principal))) - (begin - (unwrap! (contract-call? token-a transfer-from? owner-a owner-b amount-a)) - (unwrap! (contract-call? token-b transfer-from? owner-b owner-a amount-b)))) -``` - -Traits can either be locally defined: - -```clarity -(define-trait can-transfer-tokens ( - (transfer-from? (principal principal uint) (response uint))) -``` - -Or imported from an existing contract: - -```clarity -(use-trait can-transfer-tokens - .contract-defining-trait.can-transfer-tokens) -``` - -Looking at trait conformance, callee contracts have two different paths. They can either be "compatible" with a trait by defining methods matching some of the methods defined in a trait, or explicitly declare conformance using the `impl-trait` statement: - -```clarity -(impl-trait .contract-defining-trait.can-transfer-tokens) -``` - -Explicit conformance should be prefered when adequate. It acts as a safeguard by helping the static analysis system to detect deviations in method signatures before contract deployment. - -The following limitations are imposed on contract calls: - -1. On static dispatches, callee smart contracts _must_ exist at the time of creation. -2. No cycles may exist in the call graph of a smart contract. This prevents recursion (and re-entrancy bugs). Such structures can be detected with static analysis of the call graph, and will be rejected by the network. -3. `contract-call?` are for inter-contract calls only. Attempts to execute when the caller is also the callee will abort the transaction. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md b/i18n/es/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md deleted file mode 100644 index 8fb14ca8f2..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md +++ /dev/null @@ -1,1387 +0,0 @@ ---- -title: Funciones -description: Vea una lista detallada de todas las funciones del lenguaje Clarity. -tags: - - clarity ---- - -## Funciones - -Lista detallada de todas las funciones de Clarity. - -### + (add) -#### entrada: `A` -#### salida: `int | uint` -#### firma: `(+ i1 i2...)` -#### descripción: -Adds a variable number of integer inputs and returns the result. In the event of an _overflow_, throws a runtime error. -#### ejemplo: -```clarity -(+ 1 2 3) ;; Returns 6 -(+ 2 3) ;; Returns 5 -(+ 1 2 3 4) ;; Returns 10 -(+ 9 -3) ;; Returns 6 -(+ -3 -2) ;; Returns -5 -``` - -### - (subtract) -#### entrada: `int, ... | uint, ...` -#### salida: `int | uint` -#### firma: `(- i1 i2...)` -#### descripción: -Subtracts a variable number of integer inputs and returns the result. In the event of an _underflow_, throws a runtime error. -#### ejemplo: -```clarity -(- 2 1 1) ;; Returns 0 -(- 0 3) ;; Returns -3 -(- 5 -3) ;; Returns 8 -(- -4 -5) ;; Returns 1 -``` - -### * (multiply) -#### entrada: `int, ... | uint, ...` -#### salida: `int | uint` -#### firma: `(* i1 i2...)` -#### descripción: -Multiplies a variable number of integer inputs and returns the result. In the event of an _overflow_, throws a runtime error. -#### ejemplo: -```clarity -(* 2 3) ;; Returns 6 -(* 5 2) ;; Returns 10 -(* 2 2 2) ;; Returns 8 -(* 3 -2) ;; Returns -6 -(* -1 -2) ;; Returns 2 -``` - -### / (divide) -#### entrada: `A` -#### salida: `int | uint` -#### signature: `(/ i1 i2...)` -#### descripción: -Divides a variable number of integer inputs and returns the _integer part_ of the result. In the event of _division by zero_, throws a runtime error. - -#### ejemplo: -```clarity -(/ 2 3) ;; Returns 0 -(/ 5 2) ;; Returns 2 -(/ 4 2 2) ;; Returns 1 -(/ -10 2) ;; Returns -5 -(/ -8 -2) ;; Returns 4 -(/ -9 4) ;; Returns -2 -``` - -### >= (greater than or equal) -#### entrada: `int, int | uint, uint` -#### salida: `bool` -#### firma: `(>= i1 i2)` -#### descripción: -Compares two integers, returning `true` if `i1` is greater than or equal to `i2` and `false` otherwise. -#### ejemplo: -```clarity -(>= 1 1) ;; Returns true -(>= 5 2) ;; Returns true -``` - -### <= (less than or equal) -#### entrada: `int, int | uint, uint` -#### output: `bool` -#### signature: `(<= i1 i2)` -#### descripción: -Compares two integers, returning true if `i1` is less than or equal to `i2` and `false` otherwise. -#### ejemplo: -```clarity -(<= 1 1) ;; Returns true -(<= 5 2) ;; Returns false -``` - -### < (less than) -#### entrada: `int, int | uint, uint` -#### output: `bool` -#### signature: `(< i1 i2)` -#### descripción: -Compares two integers, returning `true` if `i1` is less than `i2` and `false` otherwise. -#### ejemplo: -```clarity -(< 1 2) ;; Devuelve true -(< 5 2) ;; Devuelve false -``` - -### > (greater than) -#### entrada: `int, int | uint, uint` -#### output: `bool` -#### signature: `(> i1 i2)` -#### descripción: -Compares two integers, returning `true` if `i1` is greater than `i2` and false otherwise. -#### ejemplo: -```clarity -(> 1 2) ;; Returns false -(> 5 2) ;; Returns true -``` - -### to-int -#### entrada: `uint` -#### output: `int` -#### signature: `(to-int u)` -#### descripción: -Tries to convert the `uint` argument to an `int`. Will cause a runtime error and abort if the supplied argument is >= `pow(2, 127)`` -#### ejemplo: -```clarity -(to-int u238) ;; Returns 238 -``` - -### to-uint -#### input: `int` -#### output: `uint` -#### signature: `(to-uint i)` -#### descripción: -Tries to convert the `int` argument to a `uint`. Will cause a runtime error and abort if the supplied argument is negative. -#### ejemplo: -```clarity -(to-uint 238) ;; Returns u238 -``` - -### mod -#### entrada: `int, int | uint, uint` -#### salida: `int | uint` -#### signature: `(mod i1 i2)` -#### descripción: -Returns the integer remainder from integer dividing `i1` by `i2`. In the event of a division by zero, throws a runtime error. -#### ejemplo: -```clarity -(mod 2 3) ;; Returns 2 -(mod 5 2) ;; Returns 1 -(mod 7 1) ;; Returns 0 -``` - -### pow -#### entrada: `int, int | uint, uint` -#### salida: `int | uint` -#### firma: `(pow i1 i2)` -#### descripción: -Returns the result of raising `i1` to the power of `i2`. In the event of an _overflow_, throws a runtime error. -#### ejemplo: -```clarity -(pow 2 3) ;; Returns 8 -(pow 2 2) ;; Returns 4 -(pow 7 1) ;; Returns 7 -``` - -### sqrti -#### input: `int | uint` -#### salida: `int | uint` -#### firma: `(sqrti n)` -#### descripción: -Returns the largest integer that is less than or equal to the square root of `n`. Fails on a negative numbers. -#### ejemplo: -```clarity -(sqrti u11) ;; Returns u3 -(sqrti 1000000) ;; Returns 1000 -(sqrti u1) ;; Returns u1 -(sqrti 0) ;; Returns 0 -``` - -### log2 -#### input: `int | uint` -#### salida: `int | uint` -#### firma: `(log2 n)` -#### descripción: -Returns the _integer part_ of the power to which the number 2 must be raised to obtain the value `n`. Fails on zero or a negative number. -#### ejemplo: -```clarity -(log2 u8) ;; Returns u3 -(log2 8) ;; Returns 3 -(log2 u1) ;; Returns u0 -(log2 1000) ;; Returns 9 -``` - -### xor -#### entrada: `int, int | uint, uint` -#### salida: `int | uint` -#### firma: `(xor i1 i2)` -#### descripción: -Returns the result of bitwise exclusive or'ing `i1` with `i2`. -#### ejemplo: -```clarity -(xor 1 2) ;; Returns 3 -(xor 120 280) ;; Returns 352 -``` - -### and -#### entrada: `bool, ...` -#### salida: `bool` -#### firma: `(and b1 b2 ...)` -#### descripción: -Returns `true` if all boolean inputs are `true`. Importantly, the supplied arguments are evaluated in-order and lazily. Lazy evaluation means that if one of the arguments returns `false`, the function short-circuits, and no subsequent arguments are evaluated. -#### ejemplo: -```clarity -(and true false) ;; Returns false -(and (is-eq (+ 1 2) 1) (is-eq 4 4)) ;; Returns false -(and (is-eq (+ 1 2) 3) (is-eq 4 4)) ;; Returns true -``` - -### or -#### entrada: `bool, ...` -#### salida: `bool` -#### signature: `(or b1 b2 ...)` -#### descripción: -Returns `true` if any boolean inputs are `true`. Importantly, the supplied arguments are evaluated in-order and lazily. Importantly, the supplied arguments are evaluated in-order and lazily. -#### ejemplo: -```clarity -(or true false) ;; Returns true -(or (is-eq (+ 1 2) 1) (is-eq 4 4)) ;; Returns true -(or (is-eq (+ 1 2) 1) (is-eq 3 4)) ;; Returns false -(or (is-eq (+ 1 2) 3) (is-eq 4 4)) ;; Returns true -``` - -### not -#### input: `bool` -#### output: `bool` -#### signature: `(not b1)` -#### descripción: -Devuelve la inversa de la entrada booleana. -#### ejemplo: -```clarity -(not true) ;; Returns false -(not (is-eq 1 2)) ;; Returns true -``` - -### is-eq -#### input: `A, A, ...` -#### output: `bool` -#### signature: `(is-eq v1 v2...)` -#### descripción: -Compares the inputted values, returning `true` if they are all equal. Note that _unlike_ the `(and ...)` function, `(is-eq ...)` will _not_ short-circuit. All values supplied to is-eq _must_ be the same type. -#### ejemplo: -```clarity -(is-eq 1 1) ;; Returns true -(is-eq true false) ;; Returns false -(is-eq \"abc\" 234 234) ;; Throws type error -``` - -### if -#### input: `bool, A, A` -#### output: `A` -#### signature: `(if bool1 expr1 expr2)` -#### descripción: -The `if` function admits a boolean argument and two expressions which must return the same type. In the case that the boolean input is `true`, the `if` function evaluates and returns `expr1`. If the boolean input is `false`, the `if` function evaluates and returns `expr2`. -#### ejemplo: -```clarity -(if true 1 2) ;; Returns 1 -(if (> 1 2) 1 2) ;; Returns 2 -``` - -### let -#### entrada: `((name1 AnyType) (name2 AnyType) ...), AnyType, ... A` -#### salida: `A` -#### signature: `(asserts! bool-expr thrown-value)` -#### descripción: -The `let` function accepts a list of `variable name` and `expression` pairs, evaluating each expression and _binding_ it to the corresponding variable name. `let` bindings are sequential: when a `let` binding is evaluated, it may refer to prior binding. The _context_ created by this set of bindings is used for evaluating its body expressions. The let expression returns the value of the last such body expression. Note: intermediary statements returning a response type must be checked` -#### ejemplo: -```clarity -(let ((a 2) (b (+ 5 6 7))) (print a) (print b) (+ a b)) ;; Returns 20 -(let ((a 5) (c (+ a 1)) (d (+ c 1)) (b (+ a c d))) (print a) (print b) (+ a b)) ;; Returns 23 -``` - -### map -#### input: `Function(A, B, ..., N) -> X, sequence_A, sequence_B, ..., sequence_N` -#### output: `(list X)` -#### signature: `(map-get? map-name key-tuple)` -#### descripción: -Also, note that, no matter what kind of sequences the inputs are, the output is always a list. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. The `map` function applies the function `func` to each corresponding element of the input sequences, and outputs a _list_ of the same type containing the outputs from those function applications. -#### ejemplo: -```clarity -(map not (list true false true false)) ;; Returns (false true false true) -(map + (list 1 2 3) (list 1 2 3) (list 1 2 3)) ;; Returns (3 6 9) -(define-private (a-or-b (char (string-utf8 1))) (if (is-eq char u\"a\") u\"a\" u\"b\")) -(map a-or-b u\"aca\") ;; Returns (u\"a\" u\"b\" u\"a\") -(define-private (zero-or-one (char (buff 1))) (if (is-eq char 0x00) 0x00 0x01)) -(map zero-or-one 0x000102) ;; Returns (0x00 0x01 0x01) -``` - -### fold -#### input: `Function(A, B) -> B, sequence_A, B` -#### output: `B` -#### signature: `(fold func sequence_A initial_B)` -#### descripción: -The `fold` function condenses `sequence_A` into a value of type `B` by recursively applies the function `func` to each element of the input sequence _and_ the output of a previous application of `func`. - -`fold` uses `initial_B` in the initial application of `func`, along with the first element of `sequence_A`. The resulting value of type `B` is used for the next application of `func`, along with the next element of `sequence_A` and so on. `fold` returns the last value of type `B` returned by these successive applications `func`. - -Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. - -#### ejemplo: -```clarity -(fold * (list 2 2 2) 1) ;; Returns 8 -(fold * (list 2 2 2) 0) ;; Returns 0 -;; calculates (- 11 (- 7 (- 3 2))) -(fold - (list 3 7 11) 2) ;; Returns 5 -(define-private (concat-string (a (string-ascii 20)) (b (string-ascii 20))) (unwrap-panic (as-max-len? (concat a b) u20))) -(fold concat-string \"cdef\" \"ab\") ;; Returns \"fedcab\" -(fold concat-string (list \"cd\" \"ef\") \"ab\") ;; Returns \"efcdab\" -(define-private (concat-buff (a (buff 20)) (b (buff 20))) (unwrap-panic (as-max-len? (concat a b) u20))) -(fold concat-buff 0x03040506 0x0102) ;; Returns 0x060504030102 -``` - -### append -#### input: `list A, A` -#### output: `list` -#### signature: `(append (list 1 2 3 4) 5)` -#### descripción: -The `append` function takes a list and another value with the same entry type, and outputs a list of the same type with max_len += 1. -#### ejemplo: -```clarity -(append (list 1 2 3 4) 5) ;; Returns (1 2 3 4 5) -``` - -### concat -#### input: `sequence_A, sequence_A` -#### output: `sequence_A` -#### signature: `(concat sequence1 sequence2)` -#### descripción: -The `func` argument must be a literal function name. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. - -#### ejemplo: -```clarity -(concat (list 1 2) (list 3 4)) ;; Returns (1 2 3 4) -(concat \"hello \" \"world\") ;; Returns \"hello world\" -(concat 0x0102 0x0304) ;; Returns 0x01020304 -``` - -### as-max-len? -#### input: `sequence_A, uint` -#### output: `sequence_A` -#### signature: `(map func sequence_A sequence_B ... sequence_N)` -#### descripción: -The `as-max-len?` function takes a sequence argument and a uint-valued, literal length argument. The function returns an optional type. If the input sequence length is less than or equal to the supplied max_length, this returns `(some sequence)`, otherwise it returns `none`. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. ` -#### ejemplo: -```clarity -(as-max-len? (list 2 2 2) u3) ;; Returns (some (2 2 2)) -(as-max-len? (list 1 2 3) u2) ;; Returns none -(as-max-len? \"hello\" u10) ;; Returns (some \"hello\") -(as-max-len? 0x010203 u10) ;; Returns (some 0x010203) -``` - -### len -#### input: `sequence_A` -#### output: `uint` -#### signature: `(len sequence)` -#### descripción: -The `len` function returns the length of a given sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. ` -#### ejemplo: -```clarity -(len \"blockstack\") ;; Returns u10 -(len (list 1 2 3 4 5)) ;; Returns u5 -(len 0x010203) ;; Returns u3 -``` - -### element-at -#### input: `sequence_A, uint` -#### output: `(optional A)` -#### signature: `(element-at sequence index)` -#### descripción: -The `element-at` function returns the element at `index` in the provided sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. ` -#### ejemplo: -```clarity -(element-at \"blockstack\" u5) ;; Returns (some \"s\") -(element-at (list 1 2 3 4 5) u5) ;; Returns none -(element-at (list 1 2 3 4 5) (+ u1 u2)) ;; Returns (some 4) -(element-at \"abcd\" u1) ;; Returns (some \"b\") -(element-at 0xfb01 u1) ;; Returns (some 0x01) -``` - -### index-of -#### input: `sequence_A, A` -#### output: `(optional uint)` -#### signature: `(index-of sequence item)` -#### descripción: -The `index-of` function returns the first index at which `item` can be found, using `is-eq` checks, in the provided sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. If the target item is not found in the sequence (or if an empty string or buffer is supplied), this function returns `none`. -#### ejemplo: -```clarity -(index-of \"blockstack\" \"b\") ;; Returns (some u0) -(index-of \"blockstack\" \"k\") ;; Returns (some u4) -(index-of \"blockstack\" \"\") ;; Returns none -(index-of (list 1 2 3 4 5) 6) ;; Returns none -(index-of 0xfb01 0x01) ;; Returns (some u1) -``` - -### list -#### input: `A, ...` -#### output: `(list A)` -#### signature: `(list expr1 expr2 expr3 ...)` -#### descripción: -The `list` function constructs a list composed of the inputted values. Each supplied value must be of the same type. -#### ejemplo: -```clarity -(list (+ 1 2) 4 5) ;; Returns (3 4 5) -``` - -### var-get -#### input: `VarName` -#### output: `A` -#### signature: `(var-get var-name)` -#### descripción: -The `var-get` function looks up and returns an entry from a contract's data map. The value is looked up using `var-name`. -#### ejemplo: -```clarity -(define-data-var cursor int 6) -(var-get cursor) ;; Returns 6 -``` - -### var-set -#### input: `VarName, AnyType` -#### output: `bool` -#### signature: `(var-set var-name expr1)` -#### descripción: -The `var-set` function sets the value associated with the input variable to the inputted value. The function always returns `true`. -#### ejemplo: -```clarity -(define-data-var cursor int 6) -(var-get cursor) ;; Returns 6 -(var-set cursor (+ (var-get cursor) 1)) ;; Returns true -(var-get cursor) ;; Returns 7 -``` - -### map-get? -#### input: `MapName, tuple` -#### output: `(optional (tuple))` -#### signature: `(map-get? map-name key-tuple)` -#### descripción: -The `map-get?` function looks up and returns an entry from a contract's data map. The value is looked up using `key-tuple`. If there is no value associated with that key in the data map, the function returns a `none` option. Otherwise, it returns `(some value)`. -#### ejemplo: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(map-get? names-map (tuple (name \"blockstack\"))) ;; Returns (some (tuple (id 1337))) -(map-get? names-map { name: \"blockstack\" }) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-set -#### input: `MapName, tuple_A, tuple_B` -#### output: `bool` -#### signature: `(map-set map-name key-tuple value-tuple)` -#### descripción: -The `map-set` function sets the value associated with the input key to the inputted value. This function performs a _blind_ update; whether or not a value is already associated with the key, the function overwrites that existing association. - -Note: the `value-tuple` requires 1 additional byte for storage in the materialized blockchain state, and therefore the maximum size of a value that may be inserted into a map is MAX_CLARITY_VALUE - 1. -#### ejemplo: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-set names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-insert -#### input: `MapName, tuple_A, tuple_B` -#### output: `bool` -#### signature: `(map-insert map-name key-tuple value-tuple)` -#### descripción: -The `map-insert` function sets the value associated with the input key to the inputted value if and only if there is not already a value associated with the key in the map. If an insert occurs, the function returns `true`. If a value already existed for this key in the data map, the function returns `false`. - -Note: the `value-tuple` requires 1 additional byte for storage in the materialized blockchain state, and therefore the maximum size of a value that may be inserted into a map is MAX_CLARITY_VALUE - 1. -#### ejemplo: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns false -(map-insert names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-delete -#### input: `MapName, tuple` -#### output: `bool` -#### signature: `(map-delete map-name key-tuple)` -#### descripción: -The `map-delete` function removes the value associated with the input key for the given map. If an item exists and is removed, the function returns `true`. If a value did not exist for this key in the data map, the function returns `false`. -#### ejemplo: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-delete names-map { name: \"blockstack\" }) ;; Returns true -(map-delete names-map { name: \"blockstack\" }) ;; Returns false -(map-delete names-map (tuple (name \"blockstack\"))) ;; Same command, using a shorthand for constructing the tuple -``` - -### tuple -#### input: `(key-name A), (key-name-2 B), ...` -#### output: `(tuple (key-name A) (key-name-2 B) ...)` -#### signature: `(tuple (key0 expr0) (key1 expr1) ...)` -#### descripción: -The `tuple` special form constructs a typed tuple from the supplied key and expression pairs. A `get` function can use typed tuples as input to select specific values from a given tuple. Key names may not appear multiple times in the same tuple definition. Supplied expressions are evaluated and associated with the expressions' paired key name. - -There is a shorthand using curly brackets of the form {key0: expr0, key1: expr, ...}` -#### ejemplo: -```clarity -(tuple (name \"blockstack\") (id 1337)) ;; using tuple -{name: \"blockstack\", id: 1337} ;; using curly brackets -``` - -### get -#### input: `KeyName, (tuple) | (optional (tuple))` -#### output: `A` -#### signature: `(get key-name tuple)` -#### descripción: -The `get` function fetches the value associated with a given key from the supplied typed tuple. If an `Optional` value is supplied as the inputted tuple, `get` returns an `Optional` type of the specified key in the tuple. If the supplied option is a `(none)` option, get returns `(none)`. -#### ejemplo: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(get id (tuple (name \"blockstack\") (id 1337))) ;; Returns 1337 -(get id (map-get? names-map (tuple (name \"blockstack\")))) ;; Returns (some 1337) -(get id (map-get? names-map (tuple (name \"non-existent\")))) ;; Returns none -``` - -### merge -#### input: `tuple, tuple` -#### output: `tuple` -#### signature: `(merge tuple { key1: val1 })` -#### descripción: -The `merge` function returns a new tuple with the combined fields, without mutating the supplied tuples. -#### ejemplo: -```clarity -(define-map users { id: int } { name: (string-ascii 12), address: (optional principal) }) -(map-insert users { id: 1337 } { name: \"john\", address: none }) ;; Returns true -(let ((user (unwrap-panic (map-get? users { id: 1337 })))) -(merge user { address: (some 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) })) ;; Returns (tuple (address (some SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF)) (name \"john\")) -``` - -### begin -#### entrada: `AnyType, ... A` -#### output: `A` -#### signature: `(contract-call? .contract-name function-name arg0 arg1 ...)` -#### descripción: -The `begin` function evaluates each of its input expressions, returning the return value of the last such expression. Note: intermediary statements returning a response type must be checked. -#### ejemplo: -```clarity -(begin (+ 1 2) 4 5) ;; Returns 5 -``` - -### hash160 -#### input: `buff|uint|int` -#### output: `(buff 20)` -#### signature: `(hash160 value)` -#### descripción: -The `hash160` function computes `RIPEMD160(SHA256(x))` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### ejemplo: -```clarity -(hash160 0) ;; Returns 0xe4352f72356db555721651aa612e00379167b30f -``` - -### sha256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(sha256 value)` -#### description: -The `sha256` function computes `SHA256(x)` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### ejemplo: -```clarity -(sha256 0) ;; Returns 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb -``` - -### sha512 -#### input: `buff|uint|int` -#### output: `(buff 64)` -#### signature: `(sha512 value)` -#### descripción: -The `sha512` function computes `SHA512(x)` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### ejemplo: -```clarity -(sha512 1) ;; Returns 0x6fcee9a7b7a7b821d241c03c82377928bc6882e7a08c78a4221199bfa220cdc55212273018ee613317c8293bb8d1ce08d1e017508e94e06ab85a734c99c7cc34 -``` - -### sha512/256 -#### entrada: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(sha512/256 value)` -#### descripción: -The `sha512/256` function computes `SHA512/256(x)` (the SHA512 algorithm with the 512/256 initialization vector, truncated to 256 bits) of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### ejemplo: -```clarity -(sha512/256 1) ;; Returns 0x515a7e92e7c60522db968d81ff70b80818fc17aeabbec36baf0dda2812e94a86 -``` - -### keccak256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(keccak256 value)` -#### descripción: -The `keccak256` function computes `KECCAK256(value)` of the inputted value. Note that this differs from the `NIST SHA-3` (that is, FIPS 202) standard. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### ejemplo: -```clarity -(keccak256 0) ;; Returns 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4 -``` - -### secp256k1-recover? -#### input: `(buff 32), (buff 65)` -#### output: `(response (buff 33) uint)` -#### signature: `(secp256k1-recover? message-hash signature)` -#### descripción: -The `secp256k1-recover?` function recovers the public key used to sign the message which sha256 is `message-hash` with the provided `signature`. If the signature does not match, it will return the error code `(err u1).`. If the signature is invalid, it will return the error code `(err u2).`. The signature includes 64 bytes plus an additional recovery id (00..03) for a total of 65 bytes. -#### ejemplo: -```clarity -(secp256k1-recover? 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a1301) - ;; Returns (ok 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) - ``` - -### secp256k1-verify -#### input: `(buff 32), (buff 64) | (buff 65), (buff 33)` -#### output: `bool` -#### signature: `(secp256k1-verify message-hash signature public-key)` -#### descripción: -The `secp256k1-verify` function verifies that the provided signature of the message-hash was signed with the private key that generated the public key. The `message-hash` is the `sha256` of the message. The signature includes 64 bytes plus an optional additional recovery id (00..03) for a total of 64 or 65 bytes. -#### ejemplo: -```clarity -(secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a1301 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns true -(secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a13 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns true -(secp256k1-verify 0x0000000000000000000000000000000000000000000000000000000000000000 - 0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns false - ``` - -### print -#### input: `A` -#### output: `A` -#### signature: `(print expr)` -#### descripción: -The `print` function evaluates and returns its input expression. On Stacks Core nodes configured for development (as opposed to production mining nodes), this function prints the resulting value to `STDOUT` (standard output). -#### ejemplo: -```clarity -(print (+ 1 2 3)) ;; Returns 6 -``` - -### contract-call? -#### input: `ContractName, PublicFunctionName, Arg0, ...` -#### output: `(response A B)` -#### firma: `(contract-call? .contract-name function-name arg0 arg1 ...)` -#### descripción: -The `contract-call?` function executes the given public function of the given contract. You _may not_ use this function to call a public function defined in the current contract. If the public function returns _err_, any database changes resulting from calling `contract-call?` are aborted. If the function returns _ok_, database changes occurred. -#### ejemplo: -```clarity - -;; instantiate the sample-contracts/tokens.clar contract first! -(as-contract (contract-call? .tokens mint! u19)) ;; Returns (ok u19) -``` - -### as-contract -#### entrada: `A` -#### salida: `A` -#### firma: `(as-contract expr)` -#### descripción: -The `as-contract` function switches the current context's `tx-sender` value to the _contract's_ principal and executes `expr` with that context. It returns the resulting value of `expr`. -#### ejemplo: -```clarity -(as-contract tx-sender) ;; Returns S1G2081040G2081040G2081040G208105NK8PE5.docs-test -``` - -### contract-of -#### input: `Trait` -#### salida: `principal` -#### signature: `(contract-of .contract-name)` -#### descripción: -The `contract-of` function returns the principal of the contract implementing the trait. -#### ejemplo: -```clarity -(use-trait token-a-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) -(define-public (forward-get-balance (user principal) (contract )) - (begin - (ok (contract-of contract)))) ;; returns the principal of the contract implementing -``` - -### principal-of? -#### input: `(buff 33)` -#### output: `(response principal uint)` -#### signature: `(begin expr1 expr2 expr3 ... expr-last)` -#### description: -The `principal-of?` function returns the principal derived from the provided public key. If the `public-key` is invalid, it will return the error code `(err u1).`. ` -#### ejemplo: -```clarity -(principal-of? (principal-of? 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns (ok ST1AW6EKPGT61SQ9FNVDS17RKNWT8ZP582VF9HSCP) -``` - -### at-block -#### input: `(buff 32), A` -#### output: `A` -#### signature: `(at-block id-block-hash expr)` -#### descripción: -The `at-block` function evaluates the expression `expr` _as if_ it were evaluated at the end of the block indicated by the _block-hash_ argument. The `expr` closure must be read-only. - -This hash uniquely identifies Stacks blocks and is unique across Stacks forks. Note: The block identifying hash must be a hash returned by the `id-header-hash` block information property. While the hash returned by `header-hash` is unique within the context of a single fork, it is not unique across Stacks forks. - -The function returns the result of evaluating `expr`. - -#### ejemplo: -```clarity -(define-data-var data int 1) -(at-block 0x0000000000000000000000000000000000000000000000000000000000000000 block-height) ;; Returns u0 -(at-block (get-block-info? (define-data-var data int 1) -(at-block 0x0000000000000000000000000000000000000000000000000000000000000000 block-height) ;; Returns u0 -(at-block (get-block-info? id-header-hash 0) (var-get data)) ;; Throws NoSuchDataVariable because `data` wasn't initialized at block height 0 -``` - -### get-block-info? -#### input: `BlockInfoPropertyName, BlockHeightInt` -#### output: `(optional buff) | (optional uint)` -#### signature: `(get-block-info? signature: (get-block-info? prop-name block-height-expr)` -#### descripción: -The `get-block-info?` function fetches data for a block of the given block height. The value and type returned are determined by the specified `BlockInfoPropertyName`. If the provided `BlockHeightInt` does not correspond to an existing block prior to the current block, the function returns `none`. The currently available property names are `time`, `header-hash`, `burnchain-header-hash`, `id-header-hash`, `miner-address`, and `vrf-seed`. - -This is a Unix epoch timestamp in seconds which roughly corresponds to when the block was mined. The `time` property returns an integer value of the block header time field. **Warning**: this does not increase monotonically with each block and block times are accurate only to within two hours. See [BIP113](https://github.com/bitcoin/bips/blob/master/bip-0113.mediawiki) for more information. - -The `header-hash`, `burnchain-header-hash`, `id-header-hash`, and `vrf-seed` properties return a 32-byte buffer. - -The `miner-address` property returns a `principal` corresponding to the miner of the given block. - -The `id-header-hash` is the block identifier value that must be used as input to the `at-block` function. - -#### ejemplo: -```clarity -(get-block-info? time u0) ;; Returns (some u1557860301) -(get-block-info? header-hash u0) ;; Returns (some 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb) -(get-block-info? vrf-seed u0) ;; Returns (some 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4) -``` - -### err -#### input: `A` -#### output: `(response A B)` -#### signature: `(err value)` -#### descripción: -The `err` function constructs a response type from the input value. Use `err` for creating return values in public functions. An _err_ value indicates that any database changes during the processing of the function should be rolled back. -#### ejemplo: -```clarity -(err true) ;; Returns (err true) -``` - -### ok -#### entrada: `A` -#### output: `(response A B)` -#### signature: `(ok value)` -#### descripción: -The `ok` function constructs a response type from the input value. Use `ok` for creating return values in public functions. An _ok_ value indicates that any database changes during the processing of the function should materialize. -#### ejemplo: -```clarity -(ok 1) ;; Returns (ok 1) -``` - -### some -#### input: `A` -#### output: `(optional A)` -#### signature: `(some value)` -#### descripción: -The `some` function constructs a `optional` type from the input value. -#### ejemplo: -```clarity -(some 1) ;; Returns (some 1) -(is-none (some 2)) ;; Returns false -``` - -### default-to -#### input: `A, (optional A)` -#### output: `A` -#### signature: `(default-to default-value option-value)` -#### descripción: -The `default-to` function attempts to 'unpack' the second argument: if the argument is a `(some ...)` option, it returns the inner value of the option. If the second argument is a `(none)` value, `default-to` it returns the value of `default-value`. -#### ejemplo: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(default-to 0 (get id (map-get? names-map (tuple (name \"blockstack\"))))) ;; Returns 1337 -(default-to 0 (get id (map-get? names-map (tuple (name \"non-existant\"))))) ;; Returns 0 -``` - -### asserts! -#### input: `bool, C` -#### output: `bool` -#### firma: `(asserts! bool-expr thrown-value)` -#### descripción: -The `asserts!` function admits a boolean argument and asserts its evaluation: if bool-expr is `true`, `asserts!` returns `true` and proceeds in the program execution. If the supplied argument is returning a false value, `asserts!` _returns_ `thrown-value` and exits the current control-flow. -#### ejemplo: -```clarity -(asserts! (is-eq 1 1) (err 1)) ;; Devuelve true -``` - -### unwrap! -#### input: `(optional A) | (response A B), C` -#### output: `A` -#### firma: `(unwrap! | uint, ...` -#### descripción: -The `unwrap!` function attempts to 'unpack' the first argument: if the argument is an option type, and the argument is a `(some ...)` option, `unwrap!` returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, `unwrap!` returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `(none)` value, `unwrap!` _returns_ `thrown-value` from the current function and exits the current control-flow. -#### ejemplo: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(define-private (get-name-or-err (name (string-ascii 12))) - (let ((raw-name (unwrap! (map-get? names-map { name: name }) (err 1)))) - (ok raw-name))) - -(get-name-or-err \"blockstack\") ;; Returns (ok (tuple (id 1337))) -(get-name-or-err \"non-existant\") ;; Returns (err 1) -``` - -### unwrap-err! -#### input: `(response A B), C` -#### output: `B` -#### signature: `(unwrap-err! response-input thrown-value)` -#### descripción: -The `unwrap-err!` function attempts to 'unpack' the first argument: if the argument is an `(err ...)` response, `unwrap-err!` returns the inner value of the `err`. If the supplied argument is an `(ok ...)` value, `unwrap-err!` _returns_ `thrown-value` from the current function and exits the current control-flow. -#### ejemplo: -```clarity -(unwrap-err! (err 1) false) ;; Returns 1 -``` - -### unwrap-panic -#### input: `(optional A) | (response A B)` -#### output: `A` -#### signature: `(unwrap-panic option-input)` -#### descripción: -The `unwrap` function attempts to 'unpack' its argument: if the argument is an option type, and the argument is a `(some ...)` option, this function returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, it returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `(none)` value, `unwrap` throws a runtime error, aborting any further processing of the current transaction. -#### ejemplo: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(unwrap-panic (map-get? names-map { name: \"blockstack\" })) ;; Returns (tuple (id 1337)) -(unwrap-panic (map-get? names-map { name: \"non-existant\" })) ;; Throws a runtime exception -``` - -### unwrap-err-panic -#### entrada: `(response A B)` -#### salida: `B` -#### firma: `(unwrap-err-panic response-input)` -#### descripción: -The `unwrap-err` function attempts to 'unpack' the first argument: if the argument is an `(err ...)` response, `unwrap` returns the inner value of the `err`. If the supplied argument is an `(ok ...)` value, `unwrap-err` throws a runtime error, aborting any further processing of the current transaction. -#### ejemplo: -```clarity -(unwrap-err-panic (err 1)) ;; Returns 1 -(unwrap-err-panic (ok 1)) ;; Throws a runtime exception -``` - -### match -#### input: `(optional A) name expression expression | (response A B) name expression name expression` -#### output: `C` -#### signature: `(match opt-input some-binding-name some-branch none-branch) | -(match-resp input ok-binding-name ok-branch err-binding-name err-branch)` -#### descripción: -The `match` function is used to test and destructure optional and response types. - -If the `input` is an optional, it tests whether the provided `input` is a `some` or `none` option, and evaluates `some-branch` or `none-branch` in each respective case. - -Within the `some-branch`, the _contained value_ of the `input` argument is bound to the provided `some-binding-name` name. - -Only _one_ of the branches will be evaluated (similar to `if` statements). - -If the `input` is a response, it tests whether the provided `input` is an `ok` or `err` response type, and evaluates `ok-branch` or `err-branch` in each respective case. - -Within the `ok-branch`, the _contained ok value_ of the `input` argument is bound to the provided `ok-binding-name` name. - -Within the `err-branch`, the _contained err value_ of the `input` argument is bound to the provided `err-binding-name` name. - -Only _one_ of the branches will be evaluated (similar to `if` statements). - -Note: Type checking requires that the type of both the ok and err parts of the response object be determinable. For situations in which one of the parts of a response is untyped, you should use `unwrap-panic` or `unwrap-err-panic` instead of `match`. -#### ejemplo: -```clarity - -(define-private (add-10 (x (optional int))) - (match x - value (+ 10 value) - 10)) -(add-10 (some 5)) ;; Returns 15 -(add-10 none) ;; Returns 10 - -(define-private (add-or-pass-err (x (response int (string-ascii 10))) (to-add int)) - (match x - value (ok (+ to-add value)) - err-value (err err-value))) -(add-or-pass-err (ok 5) 20) ;; Returns (ok 25) -(add-or-pass-err (err \"ERROR\") 20) ;; Returns (err \"ERROR\") -``` - -### try! -#### input: `(optional A) | (response A B)` -#### output: `A` -#### firma: `(try! A` -#### descripción: -The `try!` function attempts to 'unpack' the first argument: if the argument is an option type, and the argument is a `(some ...)` option, `try!` returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, `try!` returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `none` value, `try!` _returns_ either `none` or the `(err ...)` value from the current function and exits the current control-flow. -#### ejemplo: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(try! (map-get? names-map { name: \"blockstack\" })) ;; Returns (tuple (id 1337)) -(define-private (checked-even (x int)) - (if (is-eq (mod x 2) 0) - (ok x) - (err false))) -(define-private (double-if-even (x int)) - (ok (* 2 (try! (checked-even x))))) -(double-if-even 10) ;; Returns (ok 20) -(double-if-even 3) ;; Returns (err false) -``` - -### is-ok -#### entrada: `(response A B)` -#### output: `bool` -#### signature: `(is-ok value)` -#### descripción: -`is-ok` tests a supplied response value, returning `true` if the response was `ok`, and `false` if it was an `err`. -#### ejemplo: -```clarity -(is-ok (ok 1)) ;; Returns true -(is-ok (err 1)) ;; Returns false -``` - -### is-none -#### input: `(optional A)` -#### output: `bool` -#### signature: `(is-none value)` -#### descripción: -`is-none` tests a supplied option value, returning `true` if the option value is `(none)`, and `false` if it is a `(some ...)`. -#### ejemplo: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(is-none (get id (map-get? names-map { name: \"blockstack\" }))) ;; Returns false -(is-none (get id (map-get? names-map { name: \"non-existant\" }))) ;; Returns true -``` - -### is-err -#### entrada: `(response A B)` -#### output: `bool` -#### signature: `(is-err value)` -#### descripción: -`is-err` tests a supplied response value, returning `true` if the response was an `err`, and `false` if it was an `ok`. -#### ejemplo: -```clarity -(is-err (ok 1)) ;; Returns false -(is-err (err 1)) ;; Returns true -``` - -### is-some -#### input: `(optional A)` -#### output: `bool` -#### signature: `(is-some value)` -#### descripción: -`is-some` tests a supplied option value, returning `true` if the option value is `(some ...)`, and `false` if it is a `none`. -#### ejemplo: -```clarity - -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(is-some (get id (map-get? names-map { name: \"blockstack\" }))) ;; Returns true -(is-some (get id (map-get? names-map { name: \"non-existant\" }))) ;; Returns false -``` - -### filter -#### input: `Function(A) -> bool, sequence_A` -#### output: `sequence_A` -#### signature: `(filter func sequence)` -#### descripción: -The `filter` function applies the input function `func` to each element of the input sequence, and returns the same sequence with any elements removed for which `func` returned `false`. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. ` -#### ejemplo: -```clarity - -(filter not (list true false true false)) ;; Returns (false false) -(define-private (is-a (char (string-utf8 1))) (is-eq char u\"a\")) -(filter is-a u\"acabd\") ;; Returns u\"aa\" -(define-private (is-zero (char (buff 1))) (is-eq char 0x00)) -(filter is-zero 0x00010002) ;; Returns 0x0000 -``` - -### ft-get-balance -#### input: `TokenName, principal` -#### output: `uint` -#### signature: `(ft-get-balance token-name principal)` -#### descripción: -`ft-get-balance` returns `token-name` balance of the principal `principal`. The token type must have been defined using `define-fungible-token`. -#### ejemplo: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-get-balance stackaroo 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns u100 -``` - -### nft-get-owner? -#### input: `AssetName, A` -#### output: `(optional principal)` -#### signature: `(nft-get-owner? The asset must have been defined using define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. -#### descripción: -`nft-burn?` is used to burn an asset and remove that asset's owner from the `recipient` principal. The asset must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. -#### ejemplo: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) -(nft-get-owner? stackaroo \"Roo\") ;; Returns (some SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) -(nft-get-owner? stackaroo \"Too\") ;; Returns none -``` - -### ft-transfer? -#### input: `TokenName, uint, principal, principal` -#### output: `(response bool uint)` -#### signature: `(ft-transfer? token-name amount sender recipient)` -#### descripción: -`ft-transfer?` is used to increase the token balance for the `recipient` principal for a token type defined using `define-fungible-token` by debiting the `sender` principal. In contrast to `stx-transfer?`, any user can transfer the assets. When used, relevant guards need to be added. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- amount to send is non-positive ` -#### ejemplo: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-transfer? stackaroo u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(ft-transfer? stackaroo u60 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u1) -``` - -### nft-transfer? -#### input: `AssetName, A, principal, principal` -#### output: `(response bool uint)` -#### signature: `(nft-transfer? asset-class asset-identifier sender recipient)` -#### descripción: -`nft-transfer?` is used to change the owner of an asset identified by `asset-identifier` from `sender` to `recipient`. The `asset-class` must have been defined by `define-non-fungible-token` and `asset-identifier` must be of the type specified in that definition. In contrast to `stx-transfer?`, any user can transfer the asset. When used, relevant guards need to be added. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not own the asset `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- asset identified by asset-identifier does not exist ` -#### ejemplo: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(nft-transfer? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(nft-transfer? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u1) -(nft-transfer? stackaroo \"Stacka\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u3) -``` - -### nft-mint? -#### input: `AssetName, A, principal` -#### output: `(response bool uint)` -#### signature: `(nft-mint? asset-class asset-identifier recipient)` -#### descripción: -`nft-burn?` is used to burn an asset and remove that asset's owner from the `recipient` principal. The asset must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. - -If an asset identified by `asset-identifier` _already exists_, this function will return an error with the following error code: - -`(err u1)` - -Otherwise, on successfuly mint, it returns `(ok true)`. ` -#### ejemplo: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### ft-mint? -#### input: `TokenName, uint, principal` -#### output: `(response bool uint)` -#### firma: `(ft-mint? token-name amount recipient)` -#### descripción: -`ft-mint?` is used to increase the token balance for the `recipient` principal for a token type defined using `define-fungible-token`. The increased token balance is _not_ transfered from another principal, but rather minted. - -If a non-positive amount is provided to mint, this function returns `(err 1)`. Otherwise, on successfuly mint, it returns `(ok true)`. ` -#### ejemplo: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### ft-get-supply -#### input: `TokenName` -#### output: `uint` -#### signature: `(ft-get-supply token-name)` -#### descripción: -`ft-get-balance` returns `token-name` circulating supply. The token type must have been defined using `define-fungible-token`. -#### ejemplo: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-get-supply stackaroo) ;; Returns u100 -``` - -### ft-burn? -#### input: `TokenName, uint, principal` -#### output: `(response bool uint)` -#### signature: `(ft-burn? token-name amount sender)` -#### descripción: -`ft-burn?` is used to decrease the token balance for the `sender` principal for a token type defined using `define-fungible-token`. The decreased token balance is _not_ transfered to another principal, but rather destroyed, reducing the circulating supply. - -If a non-positive amount is provided to burn, this function returns `(err 1)`. Otherwise, on successfuly burn, it returns `(ok true)`. - -#### ejemplo: -```clarity - -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(ft-burn? stackaroo u50 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### nft-burn? -#### input: `AssetName, A, principal` -#### output: `(response bool uint)` -#### signature: `(nft-burn? asset-class asset-identifier recipient)` -#### descripción: -`nft-burn?` is used to burn an asset and remove that asset's owner from the `recipient` principal. The asset must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. - -If an asset identified by `asset-identifier` _doesn't exist_, this function will return an error with the following error code: - -`(err u1)` - -Otherwise, on successfuly burn, it returns `(ok true)`. ` -#### ejemplo: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(nft-burn? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### stx-get-balance -#### input: `principal` -#### output: `uint` -#### signature: `(stx-get-balance owner)` -#### descripción: -`stx-get-balance` is used to query the STX balance of the `owner` principal. - -This function returns the STX balance of the `owner` principal. In the event that the `owner` principal isn't materialized, it returns 0. - -#### ejemplo: -```clarity -(stx-get-balance 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns u0 -(stx-get-balance (as-contract tx-sender)) ;; Returns u1000 -``` - -### stx-transfer? -#### input: `uint, principal, principal` -#### output: `(response bool uint)` -#### signature: `(stx-transfer? amount sender recipient)` -#### descripción: -`stx-transfer?` is used to increase the STX balance for the `recipient` principal by debiting the `sender` principal. The `sender` principal _must_ be equal to the current context's `tx-sender`. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- amount to send is non-positive `(err u4)` -- the `sender` principal is not the current `tx-sender` - -#### ejemplo: -```clarity - -(as-contract - (stx-transfer? u60 tx-sender 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (ok true) -(as-contract - (stx-transfer? u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR tx-sender)) ;; Returns (err u4) -``` - -### stx-burn? -#### input: `uint, principal` -#### output: `(response bool uint)` -#### signature: `(stx-burn? amount sender)` -#### descripción: -`stx-burn?` debits the `sender` principal's STX holdings by `amount`, destroying the STX. The `sender` principal _must_ be equal to the current context's `tx-sender`. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u3)` -- amount to send is non-positive `(err u4)` -- the `sender` principal is not the current `tx-sender` - -#### ejemplo: -```clarity -(as-contract - (stx-burn? u60 tx-sender)) ;; Returns (ok true) -(as-contract - (stx-burn? u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (err u4) -``` - -### define-constant -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-constant name expression)` -#### descripción: -`define-constant` is used to define a private constant value in a smart contract. The expression passed into the definition is evaluated at contract launch, in the order that it is supplied in the contract. This can lead to undefined function or undefined variable errors in the event that a function or variable used in the expression has not been defined before the constant. - -Like other kinds of definition statements, `define-constant` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -#### ejemplo: -```clarity - -(define-constant four (+ 2 2)) -(+ 4 four) ;; Returns 8 -``` - -### define-private -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-private (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### descripción: -`define-private` is used to define _private_ functions for a smart contract. Private functions may not be called from other smart contracts, nor may they be invoked directly by users. Instead, these functions may only be invoked by other functions defined in the same smart contract. - -Like other kinds of definition statements, `define-private` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Private functions may return any type. -#### ejemplo: -```clarity -(define-private (max-of (i1 int) (i2 int)) - (if (> i1 i2) - i1 - i2)) -(max-of 4 6) ;; Returns 6 -``` - -### define-public -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-public (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### descripción: -`define-public` is used to define a _public_ function and transaction for a smart contract. Public functions are callable from other smart contracts and may be invoked directly by users by submitting a transaction to the Stacks blockchain. - -Like other kinds of definition statements, `define-public` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Public functions _must_ return a ResponseType (using either `ok` or `err`). Any datamap modifications performed by a public function is aborted if the function returns an `err` type. Public functions may be invoked by other contracts via `contract-call?`. -#### ejemplo: -```clarity -(define-public (hello-world (input int)) - (begin (print (+ 2 input)) - (ok input))) -``` - -### define-read-only -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-read-only (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### descripción: -`define-read-only` is used to define a _public read-only_ function for a smart contract. Such functions are callable from other smart contracts. - -Like other kinds of definition statements, `define-read-only` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Read-only functions may return any type. However, read-only functions may not perform any datamap modifications, or call any functions which perform such modifications. This is enforced both during type checks and during the execution of the function. Public read-only functions may be invoked by other contracts via `contract-call?`. -#### ejemplo: -```clarity -(define-read-only (just-return-one-hundred) - (* 10 10)) - ``` - -### define-map -#### input: `MapName, TypeDefinition, TypeDefinition` -#### output: `Not Applicable` -#### signature: `(define-map map-name key-type value-type)` -#### descripción: -`define-map` is used to define a new datamap for use in a smart contract. Such maps are only modifiable by the current smart contract. - -Maps are defined with a key type and value type, often these types are tuple types. - -Like other kinds of definition statements, `define-map` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). -#### ejemplo: -```clarity -(define-map squares { x: int } { square: int }) -(define-private (add-entry (x int)) - (map-insert squares { x: 2 } { square: (* x x) })) -(add-entry 1) -(add-entry 2) -(add-entry 3) -(add-entry 4) -(add-entry 5) -``` - -### define-data-var -#### input: `VarName, TypeDefinition, Value` -#### output: `Not Applicable` -#### signature: `(define-data-var var-name type value)` -#### descripción: -`define-data-var` is used to define a new persisted variable for use in a smart contract. Such variable are only modifiable by the current smart contract. - -Persisted variable are defined with a type and a value. - -Like other kinds of definition statements, `define-data-var` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). -#### ejemplo: -```clarity -(define-data-var size int 0) -(define-private (set-size (value int)) - (var-set size value)) -(set-size 1) -(set-size 2) -``` - -### define-fungible-token -#### input: `TokenName, ` -#### output: `Not Applicable` -#### signature: `(define-fungible-token token-name )` -#### descripción: -`define-fungible-token` is used to define a new fungible token class for use in the current contract. - -The second argument, if supplied, defines the total supply of the fungible token. This ensures that all calls to the `ft-mint?` function will never be able to create more than `total-supply` tokens. If any such call were to increase the total supply of tokens passed that amount, that invocation of `ft-mint?` will result in a runtime error and abort. - -Like other kinds of definition statements, `define-fungible-token` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Tokens defined using `define-fungible-token` may be used in `ft-transfer?`, `ft-mint?`, and `ft-get-balance` functions` -#### ejemplo: -```clarity -(define-fungible-token stacks) -(define-fungible-token limited-supply-stacks u100) -``` - -### define-non-fungible-token -#### input: `AssetName, TypeSignature` -#### output: `Not Applicable` -#### signature: `(define-non-fungible-token asset-name asset-identifier-type)` -#### descripción: -`define-non-fungible-token` is used to define a new non-fungible token class for use in the current contract. Individual assets are identified by their asset identifier, which must be of the type `asset-identifier-type`. Asset identifiers are _unique_ identifiers. - -Like other kinds of definition statements, `define-non-fungible-token` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Assets defined using `define-non-fungible-token` may be used in `nft-transfer?`, `nft-mint?`, and `nft-get-owner?` functions` -#### ejemplo: -```clarity -(define-non-fungible-token names (buff 50)) -``` - -### define-trait -#### input: `VarName, [MethodSignature]` -#### output: `Not Applicable` -#### signature: `(define-trait trait-name ((func1-name (arg1-type arg2-type ...) (return-type))))` -#### descripción: -`define-trait` is used to define a new trait definition for use in a smart contract. Other contracts can implement a given trait and then have their contract identifier being passed as function arguments in order to be called dynamically with `contract-call?`. - -Traits are defined with a name, and a list functions defined with a name, a list of argument types, and return type. - -Like other kinds of definition statements, `define-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -#### ejemplo: -```clarity -(define-trait token-trait - ((transfer? (principal principal uint) (response uint uint)) - (get-balance (principal) (response uint uint)))) -``` - -### use-trait -#### input: `VarName, TraitIdentifier` -#### output: `Not Applicable` -#### signature: `(use-trait trait-alias trait-identifier)` -#### descripción: -`use-trait` is used to bring a trait, defined in another contract, to the current contract. Subsequent references to an imported trait are signaled with the syntax ``. - -Traits import are defined with a name, used as an alias, and a trait identifier. Trait identifiers can either be using the sugared syntax (.token-a.token-trait), or be fully qualified ('SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait). - -Like other kinds of definition statements, `use-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put such a statement in the middle of a function body). -#### ejemplo: -```clarity -(use-trait token-a-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) -(define-public (forward-get-balance (user principal) (contract )) - (begin - (ok 1))) -``` - -### impl-trait -#### input: `TraitIdentifier` -#### output: `Not Applicable` -#### signature: `(impl-trait trait-identifier)` -#### descripción: -`impl-trait` can be use for asserting that a contract is fully implementing a given trait. Additional checks are being performed when the contract is being published, rejecting the deployment if the contract is violating the trait specification. - -Trait identifiers can either be using the sugared syntax (.token-a.token-trait), or be fully qualified ('SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait). - -Like other kinds of definition statements, `impl-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put such a statement in the middle of a function body). - -#### ejemplo: -```clarity -(impl-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) -(define-public (get-balance (account principal)) - (ok u0)) -(define-public (transfer? (from principal) (to principal) (amount uint)) - (ok u0)) -``` \ No newline at end of file diff --git a/i18n/es/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md b/i18n/es/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md deleted file mode 100644 index 963934d563..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Palabras clave -description: Vea una lista detallada de todas las palabras clave para el lenguaje Clarity. -tags: - - clarity ---- - -![](/img/keywords.jpg) -## Referencia de palabra clave - -Detailed list of all keywords for the Clarity language. - - -### contract-caller -#### salida: `principal` -#### descripción: -Returns the caller of the current contract context. If this contract is the first one called by a signed transaction, the caller will be equal to the signing principal. If `contract-call?` was used to invoke a function from a new contract, `contract-caller` changes to the _calling_ contract's principal. If `as-contract` is used to change the `tx-sender` context, `contract-caller` _also_ changes to the same contract principal. -#### ejemplo: -```clarity -(print contract-caller) ;; Will print out a Stacks address of the transaction sender -``` - -### tx-sender -#### salida: `principal` -#### descripción: -Returns the original sender of the current transaction, or if `as-contract` was called to modify the sending context, it returns that contract principal. -#### ejemplo: -```clarity -(print tx-sender) ;; Will print out a Stacks address of the transaction sender -``` - -### block-height -#### output: `uint` -#### descripción: -Returns the current block height of the Stacks blockchain as an uint -#### ejemplo: -```clarity -(> block-height 1000) ;; returns true if the current block-height has passed 1000 blocks. -``` - -### burn-block-height -#### output: `uint` -#### descripción: -Returns the current block height of the underlying burn blockchain as a uint -#### ejemplo: -```clarity -(> burn-block-height 1000) ;; returns true if the current height of the underlying burn blockchain has passed 1000 blocks. -``` - -### none -#### output: `(optional ?)` -#### descripción: -Represents the _none_ option indicating no value for a given optional (analogous to a null value). -#### ejemplo: -```clarity -(define-public (only-if-positive (a int)) - (if (> a 0) - (some a) - none)) -(only-if-positive 4) ;; Returns (some 4) -(only-if-positive (- 3)) ;; Returns none -``` - -### true -#### output: `bool` -#### descripción: -Boolean true constant. -#### ejemplo: -```clarity -(and true false) ;; Evaluates to false -(or false true) ;; Evaluates to true -``` - -### false -#### output: `bool` -#### descripción: -Boolean false constant. -#### ejemplo: -```clarity -(and true false) ;; Evaluates to false -(or false true) ;; Evaluates to true -``` - -### stx-liquid-supply -#### output: `uint` -#### descripción: -Returns the total number of micro-STX (uSTX) that are liquid in the system as of this block. -#### ejemplo: -```clarity -(print stx-liquid-supply) ;; Will print out the total number of liquid uSTX -``` - -### is-in-regtest -#### output: `bool` -#### descripción: -Returns whether or not the code is running in a regression test -#### ejemplo: -```clarity -(print is-in-regtest) ;; Will print 'true' if the code is running in a regression test -``` - diff --git a/i18n/es/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md b/i18n/es/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md deleted file mode 100644 index e2c3453962..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Tipos -description: Vea una lista detallada de todos los tipos para el lenguaje Clarity. -tags: - - clarity ---- - -## Clarity Type System - -The type system contains the following types: - -| Tipos | Notas | -| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `int` | signed 128-bit integer | -| `uint` | unsigned 128-bit integer | -| `bool` | boolean value (`true` or `false`) | -| `principal` | object representing a principal (whether a contract principal or standard principal) | -| `(buff max-len)` | byte buffer of maximum length `max-len`. | -| `(string-ascii max-len)` | Cadena ASCII de longitud máxima `max-len` | -| `(string-utf8 max-len)` | UTF-8 string of maximum length `max-len` (u"A smiley face emoji \u{1F600} as a utf8 string") | -| `(list max-len entry-type)` | list of maximum length `max-len`, with entries of type `entry-type` | -| `{label-0: value-type-0, label-1: value-type-1, ...}` | tuple, group of data values with named fields | -| `(optional some-type)` | an option type for objects that can either be `(some value)` or `none` | -| `(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. | diff --git a/i18n/es/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md b/i18n/es/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md deleted file mode 100644 index ab09a9ad44..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Visión general de Clarity -description: Resumen y guías para comenzar con Clarity -sidebar_label: Escribe contratos inteligentes -sidebar_position: 2 ---- - -## Introducción - -Clarity is a **decidable** smart contract language that optimizes for predictability and security, designed for the Stacks blockchain. Smart contracts allow developers to encode essential business logic on a blockchain. - -## Contratos inteligentes - -Smart contracts encode and enforce rules for modifying a particular set of data that is shared among people and entities who don't necessarily trust each other. For example, a smart contract can hold funds in escrow until multiple parties agree to release them, create its own ledger and keep track of its own novel tokens (fungible or non-fungible), and even help make supply chains more transparent. - -A smart contract execution can result in new transactions being written to the blockchain. Because smart contracts are programs that exist in a blockchain, anyone can query them, and anyone can submit transactions to execute them. - -Apps can take advantage of smart contracts to manage a global state that is visible to the public. Anyone can audit the blockchain to independently verify that an app's global shared state has been managed correctly according to the smart contract's rules. - -There is a [Clarity Visual Studio Code plugin][] available for syntax assistance and debugging. - -## Casos de uso - -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 (for example pay to access) -- Non-fungible (for example collectibles) and fungible tokens (for example stablecoins) -- Plantillas de modelo de negocio (por ejemplo suscripciones) -- App-specific blockchains -- Decentralized Autonomous Organizations - -## Diseño del lenguaje - -Clarity differs from most other smart contract languages in two essential ways: - -- The language is interpreted and broadcast on the blockchain as is (not compiled) -- The language is decidable (not Turing complete) - -Using an interpreted language ensures that the executed code is human-readable and auditable. A decidable language like Clarity makes it possible to determine precisely which code is executed, for any function. - -A Clarity smart contract consists of two parts, a data space and a set of functions. Only the associated smart contract may modify its corresponding data space on the blockchain. Functions may be private and thus callable only from within the smart contract, or public and thus callable from other contracts. Users call smart contracts' public functions by broadcasting a transaction on the blockchain which invokes the public function. Contracts can also call public functions from other smart contracts. - -Tenga en cuenta algunas de las reglas y limitaciones del lenguaje Clarity. - -- The only primitive types are booleans, integers, buffers, and principals. -- Recursion is illegal and there are no anonymous functions. -- Looping is only performed via `map`, `filter`, or `fold`. -- There is support for lists, however, the only variable length lists in the language appear as function inputs; there is no support for list operations like append or join. -- Las variables son inmutables. - -## Explorar más - -Para más detalles y referencias del lenguaje, mira lo siguiente: - -- [Clarity language overview](./clarity-language/) -- [Understating Principals](principals) -- [Valores de Clarity](values) - -[Clarity Visual Studio Code plugin]: https://marketplace.visualstudio.com/items?itemName=HiroSystems.clarity-lsp diff --git a/i18n/es/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md b/i18n/es/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md deleted file mode 100644 index d854b416e6..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -title: Principals -description: 'Clarity: Entendiendo Principals' -sidebar_position: 1 ---- - -## Introducción - -_Principals_ are a Clarity native type that represents an entity that can have a token balance. This section discusses principals and how they are used in the Clarity. - -## Principals and tx-sender - -Assets in the smart contracting language and blockchain are "owned" by objects of the principal type, meaning that any object of the principal type may own an asset. For the case of public-key hash and multi-signature Stacks addresses, a given principal can operate on their assets by issuing a signed transaction on the blockchain. _Smart contracts_ may also be principals (represented by the smart contract's identifier), however, there is no private key associated with the smart contract, and it cannot broadcast a signed transaction on the blockchain. - -A Clarity contract can use a globally defined `tx-sender` variable to obtain the current principal. The following example defines a transaction type that transfers `amount` microSTX from the sender to a recipient if amount is a multiple of 10, otherwise returning a 400 error code. - -```clarity -(define-public (transfer-to-recipient! (define-public (transfer-to-recipient! (recipient principal) (amount uint)) - (if (is-eq (mod amount 10) 0) - (stx-transfer? amount tx-sender recipient) - (err u400))) amount tx-sender recipient) - (err u400))) -``` - -Clarity provides an additional variable to help smart contracts authenticate a transaction sender. The keyword `contract-caller` returns the principal that _called_ the current contract. If an inter-contract call occurred, `contract-caller` returns the last contract in the stack of callers. For example, suppose there are three contracts A, B, and C, each with an `invoke` function such that `A::invoke` calls `B::invoke` and `B::invoke` calls `C::invoke`. - -When a user Bob issues a transaction that calls `A::invoke`, the value of `contract-caller` in each successive invoke function's body would change: - -```clarity -in A::invoke, contract-caller = Bob -in B::invoke, contract-caller = A -in C::invoke, contract-caller = B -``` - -This allows contracts to make assertions and perform authorization checks using not only the `tx-sender` (which in this example, would always be "Bob"), but also using the `contract-caller`. This could be used to ensure that a particular function is only ever called directly and never called via an inter-contract call (by asserting that `tx-sender` and `contract-caller` are equal). We provide an example of a two different types of authorization checks in the rocket ship example below. - -## Smart contracts as principals - -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, for example: - -```clarity -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-name -``` - -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 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 qualified identifier for the contracts would be: - -```clarity -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-A -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-B -``` - -But, in the contract source code, if the developer wishes to call a function from `contract-A` in `contract-B`, they can write - -```clarity -(contract-call? (contract-call? .contract-A public-function-foo) -``` - -This allows the smart contract developer to modularize their applications across multiple smart contracts _without_ knowing the publishing key a priori. - -In order for a smart contract to operate on assets it owns, smart contracts may use the special `(as-contract ...)` function. This function executes the expression (passed as an argument) with the `tx-sender` set to the contract's principal, rather than the current sender. The `as-contract` function returns the value of the provided expression. - -For example, a smart contract that implements something like a "token faucet" could be implemented as so: - -```clarity -(define-map claimed-before - ((sender principal)) - ((claimed bool))) - -(define-constant err-already-claimed u1) -(define-constant err-faucet-empty u2) -(define-constant stx-amount u1) - -(define-public (claim-from-faucet) - (let ((requester tx-sender)) ;; declarar una varable local requester = tx-sender - (asserts! (is-none (map-get? claimed-before {sender: requester})) (err err-already-claimed)) - (unwrap! (as-contract (stx-transfer? stx-amount tx-sender requester)) (err err-faucet-empty)) - (map-set claimed-before {sender: requester} {claimed: true}) - (ok stx-amount))) -``` - -In this example, the public function `claim-from-faucet`: - -- Checks if the sender has claimed from the faucet before. -- Assigns the tx sender to a `requester` variable. -- Adds an entry to the tracking map. -- Uses `as-contract` to send 1 microstack - -Unlike other principals, there is no private key associated with a smart contract. As it lacks a private key, a Clarity smart contract cannot broadcast a signed transaction on the blockchain. - -## Example: Authorization checks - -The interactions between `tx-sender`, `contract-caller` and `as-contract` are subtle, but are important when performing authorization checks in a contract. In this example contract, we'll show two different kinds of authorization checks a contract may wish to perform, and then walk through how different ways in which contract functions may be called will pass or fail those checks. - -This contract defines a "rocket-ship" non-fungible-token that a principal may own and manage the authorized pilots. Pilots are principals that are allowed to "fly" the rocket ship. - -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. -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 be called _directly_ by the ship's owner, rather than through a inter-contract-call. - -The second type of check is more restrictive than the first check, and is helpful for guarding very sensitive routines --- it protects users from unknowingly calling a function on a malicious contract that subsequently tries to call sensitive functions on another contract. - -```clarity -;; -;; rockets-base.clar -;; - -(define-non-fungible-token rocket-ship uint) - -;; a map from rocket ships to their allowed -;; pilots -(define-map allowed-pilots - ((rocket-ship uint)) ((pilots (list 10 principal)))) - -;; implementing a contains function via fold -(define-private (contains-check - (y principal) - (to-check { p: principal, result: bool })) - (if (get result to-check) - to-check - { p: (get p to-check), - result: (is-eq (get p to-check) y) })) - -(define-private (contains (x principal) (find-in (list 10 principal))) - (get result (fold contains-check find-in - { p: x, result: false }))) - -(define-read-only (is-my-ship (ship uint)) - (is-eq (some tx-sender) (nft-get-owner? rocket-ship ship))) - -;; this function will print a message -;; (and emit an event) if the tx-sender was -;; an authorized flyer. -;; -;; here we use tx-sender, because we want -;; to allow the user to let other contracts -;; fly the ship on behalf of users - -(define-public (fly-ship (ship uint)) - (let ((pilots (default-to - (list) - (get pilots (map-get? allowed-pilots { rocket-ship: ship }))))) - (if (contains tx-sender pilots) - (begin (print "Flew the rocket-ship!") - (ok true)) - (begin (print "Tried to fly without permission!") - (ok false))))) -;; -;; Authorize a new pilot. -;; -;; here we want to ensure that this function -;; was called _directly_ by the user by -;; checking that tx-sender and contract-caller are equal. -;; if any other contract is in the call stack, contract-caller -;; would be updated to a different principal. -;; -(define-public (authorize-pilot (ship uint) (pilot principal)) - (begin - ;; sender must equal caller: an intermediate contract is - ;; not issuing this call. - (asserts! (is-eq tx-sender contract-caller) (err u1)) - ;; sender must own the rocket ship - (asserts! (is-eq (some tx-sender) - (nft-get-owner? rocket-ship ship)) (err u2)) - (let ((prev-pilots (default-to - (list) - (get pilots (map-get? allowed-pilots { rocket-ship: ship }))))) - ;; don't add a pilot already in the list - (asserts! (not (contains pilot prev-pilots)) (err u3)) - ;; append to the list, and check that it is less than - ;; the allowed maximum - (match (as-max-len? (append prev-pilots pilot) u10) - next-pilots - (ok (map-set allowed-pilots {rocket-ship: ship} {pilots: next-pilots})) - ;; too many pilots already - (err u4))))) -``` - -### Extending functionality: Multi-flyer contract - -The authorization scheme for `fly-ship` allows pilots to fly rocket-ships from other contracts. This allows other contracts to provide new functionality built around calling that function. - -For example, we can create a contract that calls `fly-ship` for multiple rocket-ships in a single transaction: - -```clarity -;; -;; rockets-multi.clar -;; - -(define-private (call-fly (ship uint)) - (unwrap! (contract-call? .rockets-base fly-ship ship) false)) -;; try to fly all the ships, returning a list of whether -;; or not we were able to fly the supplied ships -(define-public (fly-all (ships (list 10 uint))) - (ok (map call-fly ships))) -``` - -### Authorization for Contract-Owned Assets - -The check in `authorize-pilot` protects users from malicious contracts, but how would such a scheme support contract-owned assets? This is what the `as-contract` function is used for. The `as-contract` function executes the supplied closure as if the sender of the transaction was the current contract, rather than the user -- it does this by updating `tx-sender` to the current contract principal. We can use this to, for example, create a smart contract rocket-ship-line: - -```clarity -;; -;; rockets-ship-line.clar -;; - -(define-constant line-ceo 'SP19Y6GRV9X778VFS1V8WT2H502WFK33XZXADJWZ) - -(define-data-var employed-pilots (list 10 principal) (list)) - -;; This function will: -;; * check that it is called by the line-ceo -;; * check that the rocket is owned by the contract -;; * authorize each employed pilot to the ship -(define-public (add-managed-rocket (ship uint)) - (begin - ;; 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 - (asserts! (contract-call? .rockets-base is-my-ship ship) (err u2)) - ;; register all of our pilots on the ship - (add-pilots-to ship))))) - -;; add all the pilots to a ship using fold -- -;; the fold checks the return type of previous calls, -;; skipping subsequent contract-calls if one fails. -(define-private (add-pilot-via-fold (pilot principal) (prior-result (response uint uint))) - (let ((ship (try! prior-result))) - (try! (contract-call? .rockets-base authorize-pilot ship pilot)) - (ok ship))) -(define-private (add-pilots-to (ship uint)) - (fold add-pilot-via-fold (var-get employed-pilots) (ok ship))) -``` - -In order for the contract to add each pilot to a new ship, the contract must call `authorize-pilot`. However, the contract wants to perform this action on behalf of a ship the _contract_ owns, not the transaction sender. To do this, the contract uses `as-contract`. diff --git a/i18n/es/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md b/i18n/es/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md deleted file mode 100644 index 2c77a44bde..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Recursos -description: 'Recursos' -sidebar_position: 8 ---- - -# Recursos externos - - -[Libro de Clarity](https://book.clarity-lang.org/) - -[Universo de Clarity](https://stacks.org/clarity-universe) - -[Tutoriales Clarity de Hiro](https://docs.hiro.so/tutorials) diff --git a/i18n/es/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md b/i18n/es/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md deleted file mode 100644 index 3ee29373af..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Software de desarrollo de Clarity -description: Las siguientes herramientas son útiles para desarrollar contratos inteligentes con Clarity -sidebar_position: 4 ---- - -## Protocolo del Servidor de Idioma (LSP en inglés) para Clarity (incluyendo extensión de Visual Studio Code) - -The Language Server Protocol (LSP) defines the protocol used between an editor or IDE and a language server that provides language features like auto complete, go to definition, find all references etc. - -Esto hace que la programación en Clarity sea más fácil y mucho más intuitiva. - -![Clarity LSP Screenshot](https://raw.githubusercontent.com/hirosystems/clarity-lsp/21b64298ca117dc41358eb9dce4605cc4a448a4c/images/screenshot.png?raw=true) - - -El repositorio de Clarity LSP está disponible [aquí](https://github.com/hirosystems/clarity-lsp). La extensión para Visual Studio Code se puede descargar directamente desde [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=HiroSystems.clarity-lsp), pero podría ser una versión anterior. Para una versión más actualizada también puedes descargarla desde [open-vsx](https://open-vsx.org/extension/hirosystems/clarity-lsp). - -## Clarity REPL - -A read—eval—print loop (REPL), also termed an interactive toplevel or language shell, is a simple, interactive computer programming environment that takes single user inputs (that is, single expressions), evaluates (executes) them, and returns the result to the user; a program written in a REPL environment is executed piecewise. - -![Clarity-repl](https://github.com/hirosystems/clarity-repl/blob/develop/docs/images/screenshot.png?raw=true) - -Las instrucciones sobre cómo instalar Clarity REPL se pueden encontrar [aquí](https://github.com/hirosystems/clarity-repl). - -## Clarinet - -Clarinet is a Clarity runtime packaged as a command line tool, designed to facilitate smart contract understanding, development, testing and deployment. Clarinet consists of a Clarity REPL and a testing harness, which, when used together allow you to rapidly develop and test a Clarity smart contract, with the need to deploy the contract to a local devnet or testnet. - -![Clarinet](https://github.com/hirosystems/clarinet/blob/develop/docs/images/demo.gif?raw=true) - -Las instrucciones de instalación, incluyendo la compilación del código fuente se pueden encontrar [aquí](https://github.com/hirosystems/clarinet). If you prefer you can directly download the latest compiled realease for Windows, Mac and Linux [here](https://github.com/hirosystems/clarinet/releases). - -[Clarinet 101](https://www.youtube.com/playlist?list=PL5Ujm489LoJaAz9kUJm8lYUWdGJ2AnQTb) contains multiple Clarinet video tutorials - -### Primeros pasos con Clarinet - -Puede verificar que tiene instalado Clarinet comprobando su versión: - -```bash -$ clarinet --version -clarinet 0.70 -``` - -More detailed information on using Clarinet is available [here](https://book.clarity-lang.org/ch07-00-using-clarinet.html). However to get you started, the following commands are important to know. - -Crear un nuevo proyecto y entrar en su directorio: - -```bash -clarinet new my-project && cd my-project -``` - -Crear un nuevo contrato dentro de `mi-proyecto`: - -```bash -clarinet contract new mycoolcontract -``` - -Check the syntax of Clarity: - -```bash -clarity check -``` - -Para probar su contrato: - -```bash -clarinet test -``` - -Entrar en la consola de Clarinet: - -```bash -clarinet console -``` diff --git a/i18n/es/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md b/i18n/es/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md deleted file mode 100644 index 2f8e89394f..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Tokens -description: Aprende acerca del soporte de tokens en Clarity -sidebar_position: 3 ---- - -## Introducción - -A fundamental use of blockchain technology is the representation, store, and transfer of value between users of a blockchain. Cryptocurrency is a very common use of blockchain technology, and remains one of the primary drivers of adoption of blockchain technology. Cryptocurrencies are represented by blockchain tokens: individual units of value within a given blockchain ecosystem. Blockchain tokens can extend beyond just digital currency, however, and recent developments throughout the cryptocurrency community have demonstrated potential for the use of blockchain to tokenize and represent not just money but other tangible assets. - -A blockchain token is a digital asset that can be verifiably owned by a user of a blockchain. Blockchain tokens are governed by a set of rules that are defined by either the blockchain itself (in the case of native tokens) or by a smart contract on a blockchain. Rules can vary depending on the nature and the use of the token. - -Tokens on a blockchain fall into two general categories, depending on their properties: [fungible][] or [non-fungible][]. The following sections discuss the properties of both types of tokens, and provide information about implementation of the two types of tokens on Stacks. - -## Tokens fungibles - -A core property of any token on a blockchain is fungibility. A fungible token is a token that's mutually interchangable or capable of mutual substitution. In other words, one quantity or part of a fungible token can be replaced by an equal quantity or part of the same fungible token. Fungible tokens are often used to represent real-world fungible assets like currency. The STX token is an example of a fungible token. Other examples include stablecoins, tokens that represent voting rights in a DAO, or tokens that algorithmically track the price of stocks. - -Fungible tokens form one of the most important value propositions for blockchain technology, the ability to store value and exchange that value through both internal and external transactions. Because fungible tokens can be divided into smaller parts and recombined into the same value representation, they serve a great utility for transferring value between blockchain users. - -The primary fungible token on the Stacks blockchain is the native token, STX. Because the Stacks blockchain allows for the creation of \[smart contracts\]\[\], other fungible tokens can be created on the Stacks blockchain as well. [SIP-010][] specifies the standard for fungible tokens on the Stacks blockchain. This specification defines the functions and traits that a fungible token on Stacks _must_ have. By complying with this standard, fungible tokens on Stacks can be easily represented by wallets that support Stacks. - -### Understanding the fungible token standard - -The [SIP-010][] standard is an interface definition that allows Stacks applications and wallets to interact with fungible tokens in a standard way. Supporting the standard reduces complexity for token creators to get their tokens into the ecosystem. Under the [SIP-010][] standard, fungible tokens must have the following characteristics: - -- Ability to transfer a specified amount of the token to a recipient (`transfer`). The recipient is required to be a Stacks principal. -- Ability to obtain the human-readable name of the token (`get-name`). -- Ability to obtain a short name (ticker symbol) for the token (`get-symbol`). -- Ability to get the number of decimals in the token representation (`get-decimals`). This is used to construct a representation of the token that humans would be familiar dealing with. For example, the US dollar has 2 decimals, if the base unit is cents. -- Ability to get the balance of the token for a particular Stacks principal (`get-balance-of`). -- Ability to get the total supply of the token (`get-total-supply`). -- A URI to metadata associated with the token (`get-token-uri`). This can resolve to off-chain metadata about the token or contract, such as an image icon for the token or a description. - -## Tokens no fungibles (NFTs) - -Non-fungible tokens (NFTs) are a type of token that are not interchangeable. NFTs have unique traits (usually in the form of attached metadata) that restrict the abillity to replace them with identical tokens. An NFT is a token that is unique, such as a piece of art, or ownership rights to a real-world asset such as a house. - -NFTs alone don't have an inherent value, like a currency. The value of an NFT is derived from the assets that the NFT represents. The use of NFTs are myriad, including digital art, collectibles, domain names, and representation of ownership of content rights. NFTs can be used as digital certificates that track the authenticty of real world items, or digitize the ownership rights to property. - -As with fungible tokens, NFTs on the Stacks blockchain are created with smart contracts. [SIP-009][] specifies the standard for NFTs on the Stacks blockchain. This specification defines the functions and traits that an NFT _must_ have, but most NFTs have more functions or traits attached than those solely described by the specification. By complying with this standard, non-fungible tokens on Stacks can be easily represented by wallets that support Stacks. - -### Understanding the non-fungible token standard - -The [SIP-009][] standard is an interface definition that the Stacks ecosystem aligned on. With support for this standard across wallets and tools, it becomes easy to interact with NFTs. Under the [SIP-009][] standard, NFT contract must have the following characteristics: - -- Ability to obtain the last token identifier (`get-last-token-id`). This id represents the upper limit of NFTs issued by the contract. -- A URI to metadata associated with a specific token identifier. (`get-token-uri`). This URI could resolve to a JSON file with information about the creator, associated media files, descriptions, signatures, and more. -- Ability to verify the owner for a given token identifier (`get-owner`). The owner resolves to a [Stacks principal](principals). -- Ability to transfer an NFT to a recipient (`transfer`). The recipient is required to be a Stacks principal. - -## Lectura adicional - -- [La Diferencia entre tokens fungibles y no fungibles](https://101blockchains.com/fungible-vs-non-fungible-tokens/) -- [Explícalo como si tuviera 5 años: NFTs](https://messari.io/article/explain-it-like-i-am-5-nfts) - -[fungible]: #fungible-tokens -[non-fungible]: #non-fungible-tokens-nfts -[SIP-010]: https://github.com/hstove/sips/blob/feat/sip-10-ft/sips/sip-010/sip-010-fungible-token-standard.md -[SIP-009]: https://github.com/stacksgov/sips/blob/main/sips/sip-009/sip-009-nft-standard.md diff --git a/i18n/es/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md b/i18n/es/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md deleted file mode 100644 index 0d130a428d..0000000000 --- a/i18n/es/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md +++ /dev/null @@ -1,301 +0,0 @@ ---- -title: Valores de Clarity -description: Aprenda cómo tratar con Clarity Values en JavaScript -sidebar_position: 2 ---- - -## Introducción - -El lenguaje de Clarity hace uso de un sistema de tipo estático fuerte. 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/hirosystems/stacks.js/tree/master/packages/transactions) library makes this easy, as we will demonstrate below. - -## Tipos de Clarity - -Please see the following page for information on [Clarity Types](../write-smart-contracts/clarity-language/language-types). - -## Constructing Clarity Values and accessing their data - -Clarity values can be constructed with functions provided by the [@stacks/transactions](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library. These functions simply output javascript objects that contain a value and a numerical representation of the Clarity type information. The Clarity types are encoded as follows: - -```typescript -export enum ClarityType { - Int = 0, - UInt = 1, - Buffer = 2, - BoolTrue = 3, - BoolFalse = 4, - PrincipalStandard = 5, - PrincipalContract = 6, - ResponseOk = 7, - ResponseErr = 8, - OptionalNone = 9, - OptionalSome = 10, - List = 11, - Tuple = 12, - StringASCII = 13, - StringUTF8 = 14, -} -``` - -`ClarityValue` objects can be serialized and included in transactions that interact with published Clarity contracts. - -Here are examples of how to construct each type of Clarity value, and how to access its data if it has any: - -### Booleans - -```typescript -const t = trueCV(); -// { type: ClarityType.BoolTrue } - -const f = falseCV(); -// { type: ClarityType.BoolFalse } -``` - -Boolean Clarity Values don't contain any underlying data. They are simply objects with `type` information. - -### Optional Values - -```typescript -const nothing: NoneCV = noneCV(); -// { type: ClarityType.OptionalNone } - -const something: SomeCV = someCV(trueCV()); -// { type: ClarityType.OptionalSome, value: { type: 4 } } -``` - -Optional Clarity Values can either be nothing (an empty type that has no data), or something (a wrapped value). - -If you are dealing with a function or contract function that returns an `OptionalCV`, you should always check what type it is before trying to access its value. - -```typescript -const maybeVal: OptionalCV = await callReadOnlyFunction(...); - -if (maybeVal.type === ClarityType. OptionalSome) { - console.log(maybeVal.value); -} else if (maybeVal.type === ClarityType. OptionalNone) { - // deal with `none` value -} -``` - -### Buffers - -```typescript -const buffer = Buffer.from('foo'); -const bufCV: BufferCV = bufferCV(buffer); -// { type: ClarityType.Buffer, buffer: } -``` - -### Integers - -Clarity supports both integers and unsigned integers. - -```typescript -const i: IntCV = intCV(-10); -// { type: ClarityType.Int, value: BN { ... } } - -const u: UIntCV = uintCV(10); -// { type: ClarityType.UInt, value: BN { ... } } -``` - -Clarity value ints store their underlying data as `BigNum` values from the [bn.js](https://github.com/indutny/bn.js/) library. - -In order to display/print Clarity (u)int values, use the `cvToString(val)` method. - -If you wish to perform arithmetic operations using Clarity (u)int values, you must use methods from the `BigNum` api on their underlying `BigNum` values, and the construct a new Clarity value out of the result. For example: - -```typescript -const x = intCV(1); -const y = intCV(2); - -x.value.add(y.value); -// 3 -``` - -### Strings - -```typescript -const ascii: StringAsciiCV = stringAsciiCV('hello world'); -// { type: ClarityType.StringASCII, data: 'hello world' } - -const utf8: StringUtf8CV = stringUtf8CV('hello 🌾'); -// { type: ClarityType.StringUTF8, data: 'hello 🌾' } -``` - -Clarity supports both ascii and utf8 strings. - -### Principals - -```typescript -const address = 'SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B'; -const contractName = 'contract-name'; - -const spCV = standardPrincipalCV(address); -// { -// type: ClarityType.PrincipalStandard -// address: { -// type: StacksMessageType.Address, -// version: AddressVersion.MainnetSingleSig, -// hash160: "SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B" -// } -// } - -const cpCV = contractPrincipalCV(address, contractName); -// { -// type: ClarityType.PrincipalContract, -// contractName: { -// type: StacksMessageType.LengthPrefixedString, -// content: 'contract-name', -// lengthPrefixBytes: 1, -// maxLengthBytes: 128, -// }, -// address: { -// type: StacksMessageType.Address, -// version: AddressVersion.MainnetSingleSig, -// hash160: "SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B" -// } -// } -``` - -Both kinds of Clarity principal values contain `type` information and an `address` object. Contract principals also contain a `contractName`. - -### Response Values - -```typescript -const errCV = responseErrorCV(trueCV()); -// { type: ResponseErr, value: { type: ClarityType.BoolTrue } } - -const okCV = responseOkCV(falseCV()); -// { type: ResponseOk, value: { type: ClarityType.BoolFalse } } -``` - -Response Clarity Values will either have the type `ClarityType.ResponseOk` or `ClarityType.ResponseErr`. They both contain a Clarity Value. Often this value will be an integer error code if the response is an `Error`. - -### Tuples - -```typescript -const tupCV = tupleCV({ - a: intCV(1), - b: trueCV(), - c: falseCV(), -}); -// { -// type: ClarityType.Tuple, -// data: { -// a: { type: ClarityType.Int, value: BN { ... } }, -// b: { type: ClarityType.BoolTrue }, -// c: { type: ClarityType.BoolFalse }, -// } -// } - -console.log(tupCV.data['b']); -// { type: ClarityType.BoolTrue } -``` - -Tuples in Clarity are typed and contain named fields. The tuple above, for example, contains three fields with the names **a**, **b** and **c**, and the types of their values are `Int`, `Boolean` and `Boolean`, respectively. - -Clarity tuples are represented in JavaScript as objects and a tuple's data can be accessed by its `data` field, where the underlying JS object is stored. - -### Lists - -```typescript -const l = listCV([trueCV(), falseCV()]); -// { type: ClarityType.List, list: [{ type: ClarityType.BoolTrue }] } - -console.log(l.list[0]); -// { type: ClarityType.BoolTrue } -``` - -Lists, in Clarity, are homogeneous, meaning they can only contain elements of a singular (Clarity) type. Make sure to avoid constructing lists that have elements of multiple types. - -A Clarity lists underlying data can be accessed via its `list` field. - -## Using Clarity Values - -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](../understand-stacks/transactions#construction). - -## Utilizing Clarity Values from Transaction Responses - -`Read-only` Clarity functions can return Clarity values as a response. These `read-only` functions can be accessed easily in JavaScript via the [`callReadOnlyFunction()`](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions#calling-read-only-contract-function) function included in `@stacks/transactions`, which returns a `ClarityValue`. - -As mentioned above, `ClarityValues` are simply javascript objects containing a value and its associated Clarity type information. These object types are defined [here](https://github.com/hirosystems/stacks.js/tree/1f2b5fd8bdf1c2b5866e8171163594d7708a8c7a/packages/transactions/src/clarity/types). - -When you are calling a `read-only` contract function, you will always know what type the function will return, since functions in Clarity are strongly typed. - -It is common for Clarity functions to return values wrapped in a `Response`, in order to indicate if there was success or an error. - -Since every `ClarityValue` has a `type` field, the type of the result of a `read-only` function call can be checked and acted upon like so: - -```typescript -const contractAddress = 'ST3KC0MTNW34S1ZXD36JYKFD3JJMWA01M55DSJ4JE'; -const contractName = 'kv-store'; -const functionName = 'get-value'; -const buffer = bufferCVFromString('foo'); -const network = new StacksTestnet(); // for mainnet, use `StacksMainnet()` -const senderAddress = 'ST2F4BK4GZH6YFBNHYDDGN4T1RKBA7DA1BJZPJEJJ'; - -const options = { - contractAddress, - contractName, - functionName, - functionArgs: [buffer], - network, - senderAddress, -}; - -// make a read-only call to a contract function that -// returns a Response -const result: ResponseCV = await callReadOnlyFunction(options); - -if (result.type === ClarityType. ResponseOk) { - console.log(cvToString(result.value)); -} else if (result.type === ClarityType. ResponseErr) { - throw new Error(`kv-store contract error: ${result.value.data}`); -} -``` - -### ClarityValues to/from Hex - -If you receive a response from a transaction in the form of a `hex` string, you can deserialize it into a Clarity value like so: - -```javascript -import { hexToCV } from '@stacks/transactions'; - -let cv = hexToCV('hex_string'); -``` - -Similarly, you can convert a Clarity value to `hex` string like so: - -```javascript -import { cvToHex, trueCV } from '@stacks/transactions'; - -let trueHex = cvToHex(trueCV()); -``` - -## Debugging Clarity Values - -Sometimes you might receive a Clarity value that you were not expecting. Logging the value to your console won't always prove to be useful, unless you have memorized the Clarity value type enum values. - -In order to figure out what kind of value you are dealing with, you can use the `cvToString()` function to convert the Clarity value to a more easily readable string. - -For example, calling `cvToString()` on a large `tuple` might yield something like: - -``` -(tuple - (a -1) - (b u1) - (c 0x74657374) - (d true) - (e (some true)) - (f none) - (g SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B) - (h SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B.test) - (i (ok true)) - (j (err false)) - (k (list true false)) - (l (tuple (a true) (b false))) - (m "hello world") - (n u"hello \u{1234}"))` -``` diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/blockchain/index.md b/i18n/fr/docusaurus-plugin-content-docs/current/blockchain/index.md deleted file mode 100644 index 7bce272298..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/blockchain/index.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: Blochain -description: Blockchain Stacks -sidebar_position: 6 ---- - -Vous trouverez ci-dessous un guide pour commencer à travailler localement avec la blockchain. - -Le dépôt de code est [ici](https://github.com/stacks-network/stacks-blockchain). - -## Commencer avec la Blockchain Stacks - -### Download and build stacks-blockchain - -La première étape est de s'assurer que Rust et le logiciel de support sont installés. - -```bash -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -``` - -:::info -Pour compiler sous Windows, suivez les instructions de l'installateur de rustup sur https://rustup.rs/ -::: - -From there, you can clone the Stacks Blockchain repository: - -```bash -git clone --depth=1 https://github.com/stacks-network/stacks-blockchain.git - -cd stacks-blockchain -``` - -Puis construisez le projet : - -```bash -cargo build -``` - -Exécutez les tests : - -```bash -cargo test testnet -- --test-threads=1 -``` - -### Encoder et signer les transactions - -Ici, nous allons générer une paire de clés qui sera utilisée pour signer les opérations à venir : - -```bash -cargo run --bin blockstack-cli generate-sk --testnet - -# Output -# { -# secretKey: "b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001", -# publicKey: "02781d2d3a545afdb7f6013a8241b9e400475397516a0d0f76863c6742210539b5", -# stacksAddress: "ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH" -# } -``` - -Ce pavé numérique est déjà enregistré dans le fichier `testnet-follower-conf.toml` , donc il peut être utilisé comme présenté ici. - -Nous allons interagir avec le contrat simple suivant `kv-store`. In our examples, we will assume this contract is saved to `./kv-store.clar`: - -```scheme -(define-map store { key: (string-ascii 32) } { value: (string-ascii 32) }) - -(define-public (get-value (key (string-ascii 32))) - (match (map-get? store { key: key }) - entry (ok (get value entry)) - (err 0))) - -(define-public (set-value (key (string-ascii 32)) (value (string-ascii 32))) - (begin - (map-set store { key: key } { value: value }) - (ok true))) -``` - -Nous voulons publier ce contrat sur la chaîne, puis émettre des transactions qui interagissent avec lui en transférant des clés et en récupérer des valeurs, afin que nous puissions observer la lecture et l'écriture. - -Notre première étape est de générer et de signer, à l'aide de votre clé privée, la transaction qui publiera le contrat `kv-store`. Pour cela, nous utiliserons la sous-commande `blockstack-cli` qui a l'usage suivant : - -```bash -blockstack-cli (options) publish [publisher-secret-key-hex] [fee-rate] [nonce] [contract-name] [file-name.clar] -``` - -Avec les paramètres suivants: - -```bash -cargo run --bin blockstack-cli publish b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 515 0 kv-store ./kv-store.clar --testnet -``` - -Le `515` correspond aux frais de transaction, libellés en microSTX. Pour l'instant, le réseau de test nécessite un microSTX par octet minimum, et cette transaction devrait être inférieure à 515 octets. Le troisième argument `0` est une nonce, qui doit être augmenté de façon monotonique à chaque nouvelle transaction. - -Cette commande affichera le **format binaire** de la transaction. Dans notre cas, nous voulons récupérer cette sortie et la copier dans un fichier qui sera utilisé plus tard dans ce tutoriel. - -```bash -cargo run --bin blockstack-cli publish b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 515 0 kv-store ./kv-store.clar --testnet | xxd -r -p > tx1.bin -``` - -### Exécuter le testnet - -Vous pouvez observer la machine d'état en action (localement) en exécutant : - -```bash -cargo stacks-node start --config=./testnet/stacks-node/conf/testnet-follower-conf.toml -``` - -`testnet-follower-conf.toml` est un fichier de configuration que vous pouvez utiliser pour mettre en place des balances genesis ou configurer des observateurs d'événements. Vous pouvez accorder à une adresse un solde initial du compte en ajoutant les entrées suivantes: - -``` -[[ustx_balance]] -address = "ST2VHM28V9E5QCRD6C73215KAPSBKQGPWTEE5CMQT" -amount = 100000000 -``` - -Le champ `adresse` est l'adresse du réseau de test de Stacks, et le champ `amount` est le nombre de microSTX à y accorder dans le bloc genèse. Les adresses des clés privées utilisées dans le tutoriel ci-dessous sont déjà ajoutées. - -### Publiez votre contrat - -En supposant que le réseau de test fonctionne, nous pouvons publier notre contrat de `kv-store`. - -Dans un autre terminal (ou explorateur de fichiers), vous pouvez déplacer le `tx1.bin` généré plus tôt, vers le mempool: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx1.bin http://localhost:20443/v2/transactions -``` - -Dans la fenêtre de terminal exécutant le testnet, vous pouvez observer les réactions de la machine d'état. - -### Lecture depuis / Écriture vers le contrat - -Maintenant que notre contrat a été publié sur la chaîne, nous allons essayer de soumettre quelques transactions en lecture / écriture. Nous allons commencer par essayer de lire la valeur associée à la clé `foo`. - -Pour cela, nous utiliserons la sous-commande : - -```bash -cargo run --bin blockstack-cli contract-call --help -``` - -Avec les paramètres suivants: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 1 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store get-value -e \"foo\" --testnet | xxd -r -p > tx2.bin -``` - -`contract` génère et signe une transaction d'appels contractuels. - -Nous pouvons soumettre la transaction en la déplaçant dans le chemin de mempool : - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx2.bin http://localhost:20443/v2/transactions -``` - -De même, nous pouvons générer une transaction qui définirait la clé `foo` à la valeur `bar`: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 2 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store set-value -e \"foo\" -e \"bar\" --testnet | xxd -r -p > tx3.bin -``` - -Et soumettez-le en le déplaçant sur le chemin de mempool : - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx3.bin http://localhost:20443/v2/transactions -``` - -Enfin, nous pouvons effectuer une troisième transaction, en lisant à nouveau la clé `foo` . pour s'assurer que la transaction précédente a bien mis à jour la machine d'état : - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 3 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store get-value -e \"foo\" --testnet | xxd -r -p > tx4.bin -``` - -Et soumettez cette dernière transaction en la déplaçant dans le chemin de mempool : - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx4.bin http://localhost:20443/v2/transactions -``` - -Félicitations, vous pouvez maintenant [écrire vos propres contrats intelligents avec Clarity](write-smart-contracts/). diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/blockchain/networks.md b/i18n/fr/docusaurus-plugin-content-docs/current/blockchain/networks.md deleted file mode 100644 index 5118c6a802..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/blockchain/networks.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Les réseaux de la blockchain Stacks -description: Les réseaux de la blockchain Stacks -sidebar_position: 3 ---- - -### Les réseaux de la blockchain Stacks - -- [x] **Krypton** est un réseau de test Stacks 2 avec un temps de bloc fixe de deux minutes, appelé `regtest`. Regtest est généralement instable pour une utilisation régulière, et est souvent réinitialisé. Consultez la [documentation du regtest](understand-stacks/testnet) pour plus d'informations sur l'utilisation de regtest. - -- [x] **Testnet** (anciennement Xenon) est le réseau de test public de Stacks 2, qui tourne PoX (preuve de transaction) basé sur le réseau de test Bitcoin. C'est l'implémentation complète de la blockchain de Stacks 2, et devrait être considérée comme un réseau de test stable pour le développement de contrats intelligents Clarity . Reportez-vous à [la documentation du testnet](understand-stacks/testnet) pour plus d'informations sur le réseau testnet public. - -- [x] **Le réseau principal** est la blockchain de Stacks 2 entièrement fonctionnelle, voir la [vue d'ensemble des Stacks](understand-stacks/) pour plus d'informations sur l'exécution d'un noeud Stacks, le minage, le stacking et l'écriture de contrats intelligents Clarity . diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md b/i18n/fr/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md deleted file mode 100644 index a6cecdac65..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: API de la blockchain Stacks -description: Interagir avec la Blockchain Stacks 2.0 via l'API -sidebar_position: 4 ---- - -## Introduction - -:::tip API Documentation La documentation officielle de l'API est disponible [ici](https://stacks-network.github.io/stacks-blockchain/). ::: - - -L'API de la Blockchain Stacks 2.0 vous permet de interroger la blockchain Stacks 2.0 et d'interagir avec des contrats intelligents. Il a été construit pour maintenir des vues matérialisées paginables de la blockchain Stacks 2.0. - -:::prudence L'API RESTful est développée par Hiro. Hiro héberge également un noeud d'API public pour faciliter l'intégration. L'utiliser nécessite de faire confiance au serveur hébergé, mais offre une expérience d'intégration plus rapide. Vous pouvez [exécuter votre propre serveur API](https://docs.hiro.so/get-started/running-api-node) ::: - -L'API JSON RESTful peut être utilisée sans aucune autorisation. Le chemin de base de l'API est : - -```bash -# pour mainnet, remplacez `testnet` par `mainnet` -https://stacks-node-api.testnet.stacks.co/ -``` - -:::note Cette documentation ne couvre que les points de terminaison qui sont exposés sur un noeud Stacks, appelé l'API RPC. Pour une documentation complète sur l'API RESTful, consultez la [référence de l'API Hiro](https://docs.hiro.so/api). ::: - -### API RPC d'un noeud Stacks - -L' [implémentation de stacks-node](https://github.com/stacks-network/stacks-blockchain/) expose les points d'entrée JSON RPC. - -Tous les accès `/v2/` passent par un proxy Stacks hébergé par Hiro. Pour une architecture sans confiance, vous devriez faire ces requêtes à un noeud auto-hébergé. - -## Points d'entrée du proxy Hiro pour de l'API RPC Stacks - -L'API Stacks 2.0 Blockchain est hébergée de façon centralisée. Cependant, chaque nœud Stacks en cours d’exécution expose une API RPC, qui vous permet d’interagir avec la blockchain. Au lieu d'utiliser une API hébergée de manière centralisée, vous pouvez directement accéder à l'API RPC d'un noeud hébergé localement. - -:::tip -Les proxy API de la Blockchain Stacks vers les points RPC de Node -::: - -Bien que le noeud API RPC ne donne pas les mêmes fonctionnalités que ceux de la Blockchain Stacks API 2.0 , vous obtenez des fonctionnalités similaires d'une manière qui est étendue à ce noeud spécifique. L'API RPC inclut les points d'entrée suivants : - -- [POST /v2/transactions](https://docs.hiro.so/api#operation/post_core_node_transactions) -- [GET /v2/contracts/interface/{contract_address}/{contract_name}](https://docs.hiro.so/api#operation/get_contract_interface) -- [POST /v2/map_entry/{contract_address}/{contract_name}/{map_name}](https://docs.hiro.so/api#operation/get_contract_data_map_entry) -- [GET /v2/contracts/source/{contract_address}/{contract_name}](https://docs.hiro.so/api#operation/get_contract_source) -- [GET /v2/accounts/{principal}](https://docs.hiro.so/api#operation/get_account_info) -- [POST /v2/contracts/call-read/{contract_address}/{contract_name}/{function_name}](https://docs.hiro.so/api#operation/call_read_only_function) -- [GET /v2/fees/transfer](https://docs.hiro.so/api#operation/get_fee_transfer) -- [GET /v2/info](https://docs.hiro.so/api#operation/get_core_api_info) - -:::caution Si vous exécutez un noeud local, il expose un serveur HTTP sur le port `20443`. Le point d'accès info serait `localhost:20443/v2/info`. ::: diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md b/i18n/fr/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md deleted file mode 100644 index e95e5df252..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Le versions de Stacks -description: Versions de la Blockchain Stacks -sidebar_position: 2 ---- - -:::info -Cette page a besoin de contributions. Aidez-nous de l'améliorer. -::: - -### Versions de la Blockchain Stacks - -Toutes les versions sont publiées [ici](https://github.com/stacks-network/stacks-blockchain/releases). Les plus importants sont décrits ci-dessous. - -### Stacks 2.1 - -Disponible à la fin de 2022. - -Plus d'informations sur [à quoi s'attendre avec les piles 2.1](https://stacks.org/stacks-21-what-to-expect). - -#### Stacks 2.05 -Activé sur le [bloc Bitcoin 713000](https://explorer.stacks.co/txid/0xece8e369310b5ff9b92ef11181ae0d2457ac0c821376d4a96c4998763e22ad04?chain=mainnet). - -Cette modification permet de stocker les coûts de la liste en fonction de la longueur réelle et du nombre d'opérations d'E/S indexées. Plus d'infos sur cet [article de blog](https://www.stacks.org/stacks-2-05?ref=docs-website). - -#### Stacks 2.0 -Activée le 14 janvier 2021 - -Ce hardfork permet le stacking, les contrats intelligents Clarity et les transactions évolutives, ainsi que la construction directement sur Bitcoin. Plus d'informations [ici](https://forum.stacks.org/t/path-to-mainnet-for-stx-holders-things-to-know-ahead-of-stacks-2-0/11529). - -#### Stacks Genesis -Publié le 30 octobre 2018, UTC+6 à partir du bloc Bitcoin 547921 - -Ce hardfork traite de l'enregistrement d'actifs numériques avec jeton Stacks ainsi que la distribution de jetons Stacks aux acheteurs existants. Plus d'informations [ici](https://blog.blockstack.org/the-launch-of-the-stacks-genesis-block/?ref=docs-website). - diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md b/i18n/fr/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md deleted file mode 100644 index 0a324e6648..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Aides au déploiement -description: Apprenez quelques méthodes courantes pour déployer votre application. ---- - -## Introduction - -Les applications Stacks sont des applications web qui authentifient les utilisateurs avec Stacks Auth et stockent des données avec Gaia. Ces deux technologies sont accessibles du côté client. En tant que tel, les applications de Stacks tendent à être simples dans la conception et le fonctionnement. Dans de nombreux cas, ils n’ont pas à héberger quoi que ce soit en dehors des ressources de l’application. - -## Où déployer son application - -Avant que les utilisateurs puissent interagir avec votre application, vous devez le déployer sur un serveur accessible sur Internet. Le déploiement nécessite que vous : - -- Configuriez ou personnalisiez les fichiers dans le répertoire `public`. -- Construisiez votre site d'application pour le déploiement. -- Copiez vos fichiers d'application générés sur votre serveur de production. - -Si vous avez d'abord bâti votre application avec le générateur d'applications Stacks, votre application contient les blocs de départ pour configurer, construire et déployer votre application. Par exemple, le modèle React possède une structure avec les blocs de construction suivants. - -| Fichier ou dossier | Description | -| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| node_modules/react-scripts | Un ensemble de scripts pour vous aider à démarrer les projets React sans configuration, pour que vous n'ayez pas à configurer votre projet par vous-même. | -| package.json | Contient une section de scripts qui inclut une référence aux scripts de react, qui sont une dépendance. Ce script crée un répertoire de compilation contenant vos fichiers à déployer. | -| public/favicon.ico | Un exemple d'icône de raccourci. | -| public/index.html | Une page d'accueil pour une application. | -| public/manifest.json | Un fichier JSON qui décrit votre application Web au navigateur. | -| cors | Contient des exemples de fichiers de déploiement pour la configuration des requêtes multi-origines. | - -Si vous utilisez le générateur pour construire votre structure avec JavasScript ou Vue, les fichiers de configuration de votre projet seront différents. - -Quel que soit le langage que vous utilisez, vous devez personnaliser et étendre le squelette de base selon les besoins de votre application. Par exemple, vous pourriez vouloir ajouter plus de propriétés au fichier `manifest.json`. Comme chaque application est différente, Stacks Auth ne propose pas d'instructions spécifiques pour le faire. Les étapes que vous définissez sont spécifiques à votre application. - -## Authentification Stacks et déploiement - -When your application authenticates users with Stacks, the Stacks Wallet at on URL requests a resource (the app manifest) from your DApp. Une requête pour une ressource en dehors du domaine d'origine (le Portefeuille de Stacks) est appelée comme une requête _cross-origin_(CORs). Obtenir des données de cette manière peut être risqué, vous devez donc configurer la sécurité de votre site Web pour permettre des interactions entre les origines. - -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) - -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 Stacks 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`: - -```html -Access-Control-Allow-Origin: * Access-Control-Allow-Headers: "X-Requested-With, -Content-Type, Origin, Authorization, Accept, Client-Security-Token, -Accept-Encoding" Access-Control-Allow-Methods: "POST, GET, OPTIONS, DELETE, PUT" -``` - -Consult the documentation for your hosting service to learn how to configure CORS on that service. - -## Deployment and Radiks - -If you are deploying a Stacks application that uses [Radiks](https://github.com/stacks-network/radiks), your deployment includes a server and a database component. You must take this into account when deploying your application. You may want to choose a service such as [Heroku](https://www.heroku.com) or [Digital Ocean](https://www.digitalocean.com) if your app uses Radiks. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/build-apps/index.md b/i18n/fr/docusaurus-plugin-content-docs/current/build-apps/index.md deleted file mode 100644 index 23714cba5d..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/build-apps/index.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Build apps with Stacks -description: Authenticate users, sign transactions and store data with the Stacks blockchain -sidebar_position: 3 -sidebar_label: Build apps ---- - -## Introduction - -Apps built with the Stacks blockchain give users control over their digital identities, assets, and data. - -Unlike most cloud-based apps, they are "decentralized" since they don't depend on any centralized platform, server, or database to function. Rather, they use the Stacks blockchain to authenticate users and facilitate read and write requests for them without any single point of failure or trust. - -Stacks provides three main functions for building apps: - - - -- **Authentication**: Register and sign users in with identities on the Stacks blockchain -- **Transaction signing**: Prompt users to sign and broadcast transactions to the Stacks blockchain -- **Data storage**: Save and retrieve data for users with [Gaia](../gaia) - - -All three of these integrations can be used together to create powerful new user experiences that rival or exceed those of traditional apps—all while protecting your users' digital rights. - -While integration is possible for any type of app, most of the resources available here are for web developers experienced with JavaScript. See [Hiro developer docs](https://docs.hiro.so) for more information on the available app development libraries for Stacks. - -## [References](references) - -[Authentication](references/authentication) - -[BNS](references/bns) - -[Gaia](../gaia/) - diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md b/i18n/fr/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md deleted file mode 100644 index 727b4e2163..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: NoCodeClarity -description: Launch apps for the Stacks blockchain through no code platforms like Bubble. ---- - -## Introduction - -![](https://d1muf25xaso8hp.cloudfront.net/https%3A%2F%2Fs3.amazonaws.com%2Fappforest_uf%2Ff1653407713550x759333524803365600%2FLogo%2520of%2520NoCodeClarity.png?w=179&h=84&auto=compress&dpr=1&fit=max) - -[NoCodeClarity](https://nocodeclarity.com) allows people to create applications for the Stacks blockchain without coding. - -## Stacks Plug-In on bubble - -The [Stacks-No-Code-Plugin](https://bubble.io/plugin/the-stacks-plug-in-1645467277638x949839693014368300) released in May 2022 and it can easily be installed on Bubble with a few clicks allowing users to deploy applications with no coding knowledge. [Bubble](https://bubble.io/blog/explaining-bubble-to-investors/) is the first No Code platform that the Stacks plugin launched on. More platforms are in the roadmap of NoCodeClarity, founded by Christopher Perceptions and Sergio Gongora. The Stacks plugin was created through the support of the Stacks Foundation via a grant in January 2022 and NoCodeClarity was awarded a $100,000 grant in June 2022 to expand the roadmap. - -Additional [instructions](https://s3.amazonaws.com/appforest_uf/f1654202471526x991633667675927800/Instructions%20v2.docx.pdf) are also available. Tutorials and step by step guides will be released soon. - -The Stacks-No-Code-Plugin code is [publicly available on Github](https://github.com/nocodeclarity/Stacks-No-Code-Plugin). - -![](/img/bubble-stacks-plugin.png) - -## Demo page - -A demo page is available [here](https://test-stacks-plugin.bubbleapps.io/version-test). - -## NoCodeClarity videos - -NodeCodeClarity has their own [youtube channel](https://www.youtube.com/channel/UC9Ep0VQ-GQ-yDzt-wmIElRA). - -Videos: - -* [NoCodeClarity Setup](https://www.youtube.com/watch?v=WanXlpBGl0w) -* [NoCodeClarity - Part 1 of the plugin](https://www.youtube.com/watch?v=o6d3hrzNqVI&t=248s) -* [NoCodeClarity - Part 2 of the plugin](https://www.youtube.com/watch?v=0rzMdsrRg80) -* [Sneak Peek of the No Code Stacks Wallet Template](https://www.youtube.com/watch?v=Xe6Yv0rF6XM) \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md b/i18n/fr/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md deleted file mode 100644 index d5233aea7f..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Authentication -description: Inscription et se connection des utilisateurs avec des identités sur la blockchain de Stacks ---- - -## Introduction - -Ce guide explique comment l'authentification est effectuée sur la blockchain de Stacks. - -L'authentification permet aux utilisateurs de s'identifier à une application tout en conservant un contrôle total sur leurs identifiants et leurs informations personnelles. Elle peut être intégré seul ou utilisé en conjonction avec [la signature de transactions](https://docs.hiro.so/get-started/transactions#signature-and-verification) et [le stockage de données](https://docs.stacks.co/gaia/overview), pour lesquels il s'agit d'un prérequis. - -Les utilisateurs qui s'inscrivent à votre application peuvent ensuite s'authentifier à n'importe quelle autre application avec le support du [Blockchain Naming System](bns) et vice versa. - -## Comment ça fonctionne - -Le flux d'authentification avec Stacks est similaire au flux typique client-server utilisé par les services de connexion centralisée (par exemple, OAuth). Cependant, avec les stacks, le flux d'authentification est produit entièrement côté client. - -Une application et un authentificateur tels que [le Portefeuille Stacks](https://www.hiro.so/wallet/install-web), communiquent pendant le flux d'authentification en transmettant deux jetons. L'application initiatrice envoie à l'authentificateur un jeton `authRequest`. Une fois qu'un utilisateur approuve l'authentification, l'authentificateur répond à l'application avec un jeton `authResponse`. - -Ces jetons sont basés sur [une norme JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) avec une prise en charge supplémentaire de la courbe `secp256k1` utilisée par Bitcoin et de nombreuses autres crypto-monnaies. Ils sont passés via des requêtes d'URL. - -Lorsqu'un utilisateur choisit d'authentifier une application, il envoie le jeton `authRequest` à l'authentificateur via une requête URL avec un paramètre également nommé : - -`https://wallet.hiro.so/...?authRequest=j902120cn829n1jnvoa...` - -Lorsque l'authentificateur reçoit la requête, il génère un jeton `authResponse` pour l'application en utilisant une _clé de transit éphémère_. La clé de transit éphémère est juste utilisée pour l'instance particulière de l'application, dans ce cas, pour signer la `authRequest`. - -L'application stocke la clé de transit éphémère lors de la génération de la requête. La partie publique de la clé de transit est passée dans le jeton `authRequest`. L'authentificateur utilise la partie publique de la clé pour chiffrer une _clé privée de l'application_ qui est retournée via la `authResponse`. - -L'authentificateur génère la clé privée de l'application à partir de la _adresse privée de l'utilisateur_ et du domaine de l'application. La clé privée de l'application est utilisée pour trois fonctions : - -1. Elle est utilisés pour créer des informations d'identification qui permettent à l'application d'accéder à un seau de stockage (stockage temporaire) dans le hub Gaia de l'utilisateur -2. Il est utilisé pour le chiffrement de bout en bout des fichiers stockés pour l'application dans le stockage Gaia de l'utilisateur. -3. Il sert de secret cryptographique que les applications peuvent utiliser pour exécuter d'autres fonctions cryptographiques. - -Enfin, la clé privée de l'application est déterministe, ce qui signifie que la même clé privée sera toujours générée pour une adresse et un domaine donnés de Stacks. - -Les deux premières de ces fonctions sont particulièrement pertinentes pour le stockage de données [avec Stacks.js](https://docs.stacks.co/docs/gaia). - -## Paire de clés - -L'authentification avec Stacks utilise largement la cryptographie à clé publique en général et ECDSA avec la courbe `secp256k1` en particulier. - -Les sections suivantes décrivent les trois paires de clés publiques privées, y compris la façon dont elles sont générées, où elles sont utilisées et à qui les clés privées sont divulguées. - -### Clé privée de transit - -La clé de transit privé est une clé éphémère utilisée pour chiffrer les secrets qui doivent passer de l'authentificateur à l'application pendant le processus d'authentification . Elle est générée aléatoirement par l'application au début de la réponse d'authentification. - -La clé publique, qui correspond à la clé privée de transit, est stockée dans un simle élément "tableau" dans la clé `public_keys` du jeton de requête d'authentification. L'authentificateur crypte les données secrètes telles que la clé privée de l'application en utilisant cette clé publique et la renvoie à l'application lorsque l'utilisateur se connecte à l'application. La clé privée de transit signe la demande d'authentification de l'application. - -### Clé privée de l'adresse d'identité - -La clé privée de l'adresse d'identité est dérivée de la phrase porte-clés de l'utilisateur et est la clé privée du nom d'utilisateur dans Stacks que l'utilisateur choisit d'utiliser pour se connecter à l'application. C'est un secret qui appartient à l'utilisateur et qui ne quitte jamais l'instance de l'authentificateur. - -Cette clé privée signe le jeton de réponse d'authentification pour une application pour indiquer que l'utilisateur approuve la connexion à cette application. - -### Clé privée de l'application - -La clé privée de l'application est une clé privée spécifique à l'application qui est générée à partir de la clé privée de l'adresse de l'utilisateur en utilisant le `domain_name` en entrée. - -La clé privée de l'application est partagée de manière sécurisée avec l'application pour chaque authentification, chiffrée par l'authentificateur avec la clé publique de transit. Parce que la clé de transit n'est stockée que sur le côté client, cela empêche une attaque de l'homme du milieu où un serveur ou un fournisseur Internet pourrait potentiellement détourner la clé privée de l'application. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/build-apps/references/bns.md b/i18n/fr/docusaurus-plugin-content-docs/current/build-apps/references/bns.md deleted file mode 100644 index 0af4f6c20b..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/build-apps/references/bns.md +++ /dev/null @@ -1,247 +0,0 @@ ---- -title: Système de nommage de la blockchain -description: Lier les noms d'utilisateur aux états hors chaîne ---- - -Le système de nommage Blockchain (BNS) est un système de réseau qui lie les noms d'utilisateur "à l'état hors chaîne" sans s'appuyer sur aucun point de contrôle central. - -La blockchain de Stacks V1 a implémenté BNS à travers des opérations de noms de premier ordre (?). Dans les piles V2, le BNS a été remplacé par un contrat intelligent chargé durant le bloc genèse. - -Les noms dans BNS ont trois propriétés : - -- **Les noms sont globalement uniques.** Le protocole n'autorise pas les collisions de noms, et tous les noeuds de confiance résolvent un nom donné de la même façon. -- **Les noms sont en langage naturel.** Chaque nom est choisi par son créateur. -- **Les noms sont inaliénables.** Seul le propriétaire du nom peut changer l'état auquel il se réfère. Plus précisément, un nom est détenu par une ou plusieurs clés privées ECDSA. - -La blockchain Stacks assure que la vue BNS de chaque nœud est synchronisée avec tous les autres nœuds du monde, de sorte que les requêtes sur un nœud seront les mêmes sur les autres nœuds. Les nœuds de la blockchain Stacks permettent au propriétaire d'un nom de se lier jusqu'à 40 Ko d'état hors chaîne à leur nom, qui sera répliquée à tous les autres nœuds de blockchain de Stacks via un réseau P2P. - -La plus grande conséquence pour les développeurs est qu'en BNS, la lecture de l'état du nom est rapide et bon marché, mais l'écriture de l'état du nom est lente et coûteuse. C'est parce que l'enregistrement et la modification des noms nécessitent d'envoyer une ou plusieurs transactions à la blockchain sous-jacente, et les nœuds BNS ne les traiteront pas jusqu'à ce qu'ils soient suffisamment confirmés. Les utilisateurs et les développeurs ont besoin d'acquérir et de dépenser la cryptomonnaie requise (STX) pour envoyer des transactions BNS. - -## Raison d'être des systèmes de nommage - -Nous comptons sur les systèmes de nommage dans la vie de tous les jours, et ils jouent un rôle critique dans de nombreuses applications différentes. Par exemple, lorsque vous regardez un ami sur les réseaux sociaux, vous utilisez le système de nommage de la plate-forme pour lier leur nom à leur profil. Lorsque vous consultez un site Web, vous utilisez le Domain Name Service pour résoudre le nom d'hôte à l'adresse IP de son hôte. Lorsque vous consultez une branche Git, vous utilisez votre client Git pour résoudre le nom de la branche à un hachage de livraison. Lorsque vous regardez la clé PGP de quelqu'un sur un serveur de clés, vous résolvez son ID de clé à sa clé publique. - -Quelles sortes de choses voulons-nous être vraies en ce qui concerne les noms? En BNS, les noms sont globalement uniques, les noms ont un sens humain, et les noms sont inaliénables. Cependant, si vous regardez ces exemples, vous verrez que chacun d'eux garantit seulement _deux_ de ces propriétés. Cela limite leur utilité. - -- Dans le DNS et les médias sociaux, les noms sont globalement uniques et lisibles par l'homme, mais pas uniques. L'opérateur système a le dernier mot l'appartenance de chaque nom. - - - **Problème**: Les clients doivent faire confiance au système pour faire le bon choix dans ce qu'un nom donné signifie. Cela inclut la confiance que personne d'autre que les administrateurs système peuvent apporter ces modifications. - -- Dans Git, les noms de branches sont en langage humain et irrévocables, mais pas globalement uniques. Deux nœuds Git différents peuvent avoir le même nom de branche appartenant à différents dépôt non liés. - - - **Problème**: Puisque les noms peuvent faire référence à un état conflictuel, les développeurs doivent trouver un autre mécanisme pour résoudre les ambiguïtés. Dans le cas de Gitit , l'utilisateur doit intervenir manuellement. - -- En PGP, les noms sont des clés d'identification. Ils sont uniques au niveau mondial et sont détenus de manière cryptographique, mais pas lisibles par l'homme. Les identifiants de clés PGP sont dérivés des clés qu'ils référencent. - - **Problème**: Ces noms sont difficiles à retenir pour la plupart des utilisateurs puisqu'ils ne transmettent pas d'informations sémantiques relatives à leur utilisation dans le système. - -Les noms BNS ont les trois propriétés et aucun de ces problèmes. Cela en fait un outil puissant pour construire toutes sortes d'applications réseau. Avec BNS, nous pouvons faire ce qui suit et plus: - -- Construire des services de noms de domaine où les noms de domaine ne peuvent pas être détournés. -- Construire des plateformes de réseaux sociaux où les noms d'utilisateurs ne peuvent pas être volés par des hameçonneurs. -- Construire des systèmes de contrôle de version où les branches du dépôt ne sont pas en conflit. -- Construire une infrastructure à clé publique où il est facile pour les utilisateurs de découvrir et se souvenir des clés de chacun. - -## Organisation du BNS - -Les noms de BNS sont organisés en une hiérarchie globale de noms. Il y a trois couches différentes dans cette hiérarchie liée au nommage : - -- **Les espaces de nommage**. Ce sont les noms de premier niveau dans la hiérarchie. Une analogie avec les espaces de noms BNS sont des domaines de premier niveau DNS. Les espaces de noms BNS existants incluent `.id`, `.podcast`, et `.helloworld`. Tous les autres noms appartiennent à exactement un espace de noms. N'importe qui peut créer un espace de noms, mais afin que l'espace de noms soit maintenu, il doit être _launched_ pour que n'importe qui puisse y enregistrer des noms. Les espaces de nommage ne sont pas détenus par leurs créateurs. - -- **Les noms BNS**. Ce sont des noms dont les enregistrements sont stockés directement sur la blockchain . La propriété et l'état de ces noms sont contrôlés par l'envoi de transactions blockchain. Les exemples de noms incluent `verified.podcast` et `muneeb.id`. N'importe qui peut créer un nom BNS, à condition que l'espace de noms le contienne déjà. - -- **Les sous-domaines BNS**. Ce sont des noms dont les enregistrements sont stockés hors chaîne, mais sont ancrés collectivement dans la blockchain. La propriété et l'état de ces noms vivent dans les données du réseau P2P. Alors que les sous-domaines BNS sont détenus par des clés privées séparées, le propriétaire d'un nom BNS doit diffuser son état de sous-domaine. Les exemples de sous-domaines comprennent `jude.personal.id` et `podsaveamerica.verified.podcast`. Contrairement aux espaces de noms et noms BNS, l'état des sous-domaines BNS ne fait _pas_ partie des règles de consensus de la blockchain. - -Une matrice de comparaison de fonctionnalités résumant les similitudes et les différences entre ces objets de nom est présentée ci-dessous: - -| Fonctionalité | **Espaces de nommage** | **Noms BNS** | **Sous-domaines BNS** | -| ------------------------------------------------- | ---------------------- | ------------ | --------------------- | -| Globalement unique | X | X | X | -| Langage humain | X | X | X | -| Détenu par une clé privée | | X | X | -| Tout le monde peut créer | X | X | [1] | -| Le propriétaire peut mettre à jour | | X | [1] | -| État hébergé sur la chaîne | X | X | | -| Etat hébergé hors de la chaîne | | X | X | -| Comportement contrôlé par des règles de consensus | X | X | | -| Peut avoir une date d'expiration | | X | | - -[1] Nécessite la coopération d'un propriétaire du nom BNS pour diffuser ses transactions - -## Espaces de nommage - -Les espaces de noms sont les objets de nommage de premier niveau dans BNS. - -Ils contrôlent quelques propriétés inhérentes aux noms : - -- Combien coûte leur enregistrement -- La durée avant de nécessiter leur renouvellement -- Qui (le cas échéant) reçoit les frais d'enregistrement du nom -- Qui est autorisé à initialiser l'espace de noms avec ses noms initiaux. - -Au moment de cette écriture, le plus grand espace de noms BNS est l'espace de noms `.id` . Les noms de l'espace de noms `.id` sont destinés à résoudre les identités de l'utilisateur . Les noms abrégés en `.id` sont plus chers que les noms longs, et doivent être renouvelés par leurs propriétaires tous les deux ans. Les frais d'enregistrement d'un nom ne sont pas payés à qui que ce soit en particulier ---ils sont plutôt envoyés à un « trou noir » où ils sont rendus inutilisables (l'intention est de décourager les squatteurs d'identification). - -Contrairement aux DNS, _n'importe qui_ peut créer un espace de noms et définir ses propriétés. Les espaces de noms sont créés sur la base du premier arrivé, et une fois créés, ils durent pour toujours. - -Cependant, la création d'un espace de noms n'est pas libre. Le créateur d'espace de noms doit _brûler_ de la cryptomonnaie pour le faire. Plus l'espace de noms est court, plus la cryptomonnaie doit être brûlée (c'est-à-dire que les espaces de noms courts sont plus précieux que les espaces de noms longs). Par exemple, il a coûté à Blockstack PBC 40 BTC pour créer l'espace de noms `.id` en 2015 (dans la transaction `5f00b8e609821edd6f3369ee4ee86e03ea34b890e242236cdb66ef6c9c6a1b281`). - -Les espaces de noms peuvent contenir entre 1 et 19 caractères, et sont composés des caractères `a-z`, `0-9`, `-`, et `_`. - -## Sous-domaines - -Les noms des BNS sont fortement détenus car le propriétaire de sa clé privée peut générer des transactions valides qui mettent à jour le hachage et le propriétaire de son fichier de zone. Cependant, cela demande d'obliger le propriétaire du nom à payer la transaction sous-jacente dans la blockchain de . De plus, cette approche limite le taux d'enregistrement des noms BNS et les opérations à la bande passante transactionnelle de la blockchain sous-jacente. - -BNS surmonte cela avec des sous-domaines. Un **sous-domaine BNS** est un type de nom BNS dont l'état et le propriétaire sont stockés en dehors de la blockchain, mais dont l'existence et l'historique des opérations sont ancrées dans la blockchain . Comme leurs homologues sur la chaîne, les sous-domaines sont globalement uniques, fortement possédés et en langage humain. BNS leur donne leur propre état de nom et clés publiques. Contrairement aux noms on-chain, les sous-domaines peuvent être créés et gérés à coût réduit, car ils sont diffusés sur le réseau BNS en lots. Une seule transaction blockchain peut envoyer jusqu'à 120 opérations de sous-domaine . - -Ceci est réalisé en stockant les enregistrements de sous-domaine dans les fichiers de zone de noms BNS. Un propriétaire de noms on-chain diffuse des opérations de sous-domaine en les encodant en tant qu'enregistrements `TXT` dans un fichier de zone DNS. Pour diffuser le fichier de zone, le nom propriétaire définit le hachage du nouveau fichier de zone avec une transaction `NAME_UPDATE` et réplique le fichier de zone. Ceci réplique, à son tour, toutes les opérations du sous-domaine qu'elle contient, et ancre l'ensemble des opérations de sous-domaine à une transaction sur la chaîne. Les règles de consensus du noeud BNS assurent que seules opérations de sous-domaine valides de \_\_ `transactions NAME_UPDATE` valides ne seront jamais stockées. - -Par exemple, le nom `a été vérifié. odcast` une fois écrit le hachage du fichier de zone `247121450ca0e9af45e85a82e61cd525cd7ba023`, qui est le hachage du fichier de zone suivant : - -```bash -$TTL 3600 -1yeardaily TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxeWVhcmRhaWx5CiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMXllYXJkYWlseS9oZWFkLmpzb24iCg==" -2dopequeens TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAyZG9wZXF1ZWVucwokVFRMIDM2MDAKX2h0dHAuX3RjcCBVUkkgMTAgMSAiaHR0cHM6Ly9waC5kb3Rwb2RjYXN0LmNvLzJkb3BlcXVlZW5zL2hlYWQuanNvbiIK" -10happier TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxMGhhcHBpZXIKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8xMGhhcHBpZXIvaGVhZC5qc29uIgo=" -31thoughts TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzMXRob3VnaHRzCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzF0aG91Z2h0cy9oZWFkLmpzb24iCg==" -359 TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzNTkKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8zNTkvaGVhZC5qc29uIgo=" -30for30 TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzMGZvcjMwCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzBmb3IzMC9oZWFkLmpzb24iCg==" -onea TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiBvbmVhCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vb25lYS9oZWFkLmpzb24iCg==" -10minuteteacher TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxMG1pbnV0ZXRlYWNoZXIKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8xMG1pbnV0ZXRlYWNoZXIvaGVhZC5qc29uIgo=" -36questionsthepodcastmusical TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzNnF1ZXN0aW9uc3RoZXBvZGNhc3RtdXNpY2FsCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzZxdWVzdGlvbnN0aGVwb2RjYXN0bXVzaWNhbC9oZWFkLmpzb24iCg==" -_http._tcp URI 10 1 "https://dotpodcast.co/" -``` - -Chaque enregistrement `TXT` dans ce fichier de zone encode une création de sous-domaine. Par exemple, `1yeardaily.verified.podcast` se correspond à: - -```json -{ - "address": "1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH", - "blockchain": "bitcoin", - "last_txid": "d87a22ebab3455b7399bfef8a41791935f94bc97aee55967edd5a87f22cce339", - "status": "registered_subdomain", - "zonefile_hash": "e7acc97fd42c48ed94fd4d41f674eddbee5557e3", - "zonefile_txt": "$ORIGIN 1yeardaily\n$TTL 3600\n_http._tcp URI 10 1 \"https://ph.dotpodcast.co/1yeardaily/head.json\"\n" -} -``` - -Cette information a été extraite de l'enregistrement de la ressource `1yeardaily` `TXT` dans le fichier de zone pour `verified.podcast`. - -### Cycle de vie des sous-domaines - -Notez que `1yeardaily.verified.podcast` a une clé publique différente de `verified.podcast`. Un noeud BNS ne traitera une opération de sous-domaine ultérieure le `1yeardy. erified.podcast` que s'il contient une signature de la clé privée de cette adresse. `verified.podcast` ne peut pas générer mises à jour ; seul le propriétaire de `1yeardaily.verified.podcast`. peut le faire - -Le cycle de vie d'un sous-domaine et de ses opérations est affiché dans la figure 2. - -``` - subdomain subdomain subdomain - creation update transfer -+----------------+ +----------------+ +----------------+ -| cicero | | cicero | | cicero | -| owner="1Et..." | signed | owner="1Et..." | signed | owner="1cJ..." | -| zf0="7e4..." |<--------| zf0="111..." |<--------| zf0="111..." |<---- ... -| seqn=0 | | seqn=1 | | seqn=2 | -| | | sig="xxxx" | | sig="xxxx" | -+----------------+ +----------------+ +----------------+ - | | | - | off-chain | | -~ ~ ~ ~ | ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~|~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ | ~ ~ ~ ~ ~ ~ ~ ... - | on-chain | | - V V (zone file hash ) V -+----------------+ +----------------+ +----------------+ -| res_publica.id | | jude.id | | res_publica.id | -| NAME_UPDATE |<--------| NAME_UPDATE |<--------| NAME_UPDATE |<---- ... -+----------------+ +----------------+ +----------------+ - blockchain blockchain blockchain - block block block - - -Figure 2 : durée de vie du sous-domaine en ce qui concerne les opérations de noms on-chain . nouvelle -opération de sous-domaine ne sera acceptée que si elle a un numéro "séquence=" ultérieur, -et une signature valide en "sig=" sur le corps de la transaction. e champ "sig=" -inclut à la fois la clé publique et la signature, et la clé publique doit être hachée sur -le champ "addr=" de l'opération précédente de sous-domaine. - -Les transactions de création de sous-domaine et de transfert de sous-domaine pour -"cicero.res_publica.id" sont diffusées par le propriétaire de "res_publica.id". -Cependant, tout nom sur chaîne ("jude.id" dans ce cas) peut diffuser une mise à jour de sous-domaine -pour "cicero.res_publica.id". -``` - -Les opérations de sous-domaine sont ordonnées par numéro de séquence, à partir de 0. Chaque nouvelle opération de sous-domaine doit inclure : - -- Le numéro d'ordre suivant -- La clé publique qui hache à l'adresse de la précédente transaction de sous-domaine -- Une signature de la clé privée correspondante sur l'ensemble du sous-domaine opération. - -Si deux opérations de sous-domaine correctement signées mais conflictuelles sont découvertes (c.-à-d. ils ont le même numéro de séquence), celui qui se produit plus tôt dans l'histoire de la blockchain est accepté. Les opérations de sous-domaine non valides sont ignorées. - -Combiné, cela garantit qu'un noeud BNS avec tous les fichiers de zone avec les opérations d'un sous-domaine donné sera en mesure de déterminer la séquence valide de transitions d'état qu'il a soumises, et déterminez le fichier de zone actuel et le hachage de la clé publique pour le sous-domaine. - -### Création et gestion de sous-domaine - -Contrairement à un nom on-chaîne, un propriétaire de sous-domaine a besoin de l'aide du propriétaire de noms sur chaîne pour diffuser ses opérations de sous-domaine. En particulier : - -- Une transaction de création de sous-domaine ne peut être traitée que par le propriétaire du nom sur qui partage son suffixe. Par exemple, seul le propriétaire de `res_publica.id` peut diffuser des transactions de création de sous-domaine pour les noms de sous-domaine se terminant par `.res_publica.id`. -- Une transaction de transfert de sous-domaine ne peut être diffusée que par le propriétaire du nom sur la chaîne qui l'a créé. For example, the owner of `cicero.res_publica.id` needs the owner of `res_publica.id` to broadcast a subdomain-transfer transaction to change `cicero.res_publica.id`'s public key. -- In order to send a subdomain-creation or subdomain-transfer, all of an on-chain name owner's zone files must be present in the Atlas network. Cela permet au noeud BNS de prouver l'\_absence<0> de tout conflit d'opération de création ou de transfert de sous-domaines lors de la création des nouveaux fichiers de zones.

-- # Une transaction de mise à jour de sous-domaine peut être diffusée par _n'importe quel propriétaire de nom sur la chaîne,_ mais le propriétaire du sous-domaine doit trouver celui qui coopérera. Par exemple, le propriétaire de `verified.podcast` peut diffuser une transaction de mise à jour de sous-domaine créée par le propriétaire de `cicero.res_publica.id`. -- In order to send a subdomain-creation or subdomain-transfer, all of an on-chain name owner's zone files must be present in the Atlas network. This lets the BNS node prove the _absence_ of any conflicting subdomain-creation and subdomain-transfer operations when processing new zone files. -- A subdomain update transaction can be broadcast by _any_ on-chain name owner, but the subdomain owner needs to find one who will cooperate. For example, the owner of `verified.podcast` can broadcast a subdomain-update transaction created by the owner of `cicero.res_publica.id`. - -Cela dit, pour créer un sous-domaine, le propriétaire du sous-domaine génère une opération de création de sous-domaine pour le nom désiré et le donne au propriétaire du nom sur la chaîne. - -Une fois créé, un propriétaire de sous-domaine peut utiliser n'importe quel propriétaire de nom sur la chaîne pour diffuser une opération de mise à jour de sous-domaine. Pour ce faire, ils génèrent et signent l'opération de sous-domaine requise et la donnent à un propriétaire de nom sur la chaîne, qui l'empaquete alors avec d'autres opérations de sous-domaine dans un fichier de zone DNS et le diffuse sur le réseau. - -Si le sous-propriétaire du sous-domaine veut changer l'adresse de son sous-domaine, il a besoin de signer une opération de transfert de sous-domaine et la donner au propriétaire du nom sur chaîne qui a créé le sous-domaine. Ils l'empaquetent ensuite dans un fichier de zone et diffusent . - -### Enregistreurs de sous-domaine - -Parce que les noms de sous-domaine sont bon marché, les développeurs peuvent être enclins à exécuter des demandes d'enregistrement de sous-domaine pour le compte de leurs applications. Par exemple, le nom `personal.id` est utilisé pour enregistrer des noms d'utilisateur sans les obliger à faire une transaction Bitcoin. - -Nous fournissons une implémentation de référence d'un [Enregistrement BNS ](https://github.com/stacks-network/subdomain-registrar) pour aider les développeurs à diffuser des opérations de sous-domaine. Les utilisateurs posséderaient toujours leurs noms de sous-domaine; le bureau d’enregistrement donne simplement aux développeurs un moyen pratique de les enregistrer et de les gérer dans le contexte d’une application particulière. - -# Normes BNS et DID - -Les noms BNS sont conformes à la spécification de [de la Fondation d’identité décentralisée](http://identity.foundation) protocole pour les identifiants décentralisés (DID). - -Chaque nom dans BNS a un DID associé. Le format DID pour BNS est : - -```bash - did:stack:v0:{address}-{index} -``` - -Où : - -- `{address}` est un hachage de clé publique sur chaîne (par exemple une adresse Bitcoin). -- `{index}` fait référence au `nème` nom que cette adresse a créé. - -Par exemple, le DID pour `personal.id` est `did:stack:v0:1dARRtzHPAFRNE7Yup2Md9w18XEQAtLiV-0`, parce que le nom `personal.id` a été le tout premier nom créé par `1dARRtzHPAFRNE7Yup2Md9w18XEQAtLiV`. - -Comme autre exemple, le DID pour `jude.id` est `did:stack:v0:16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg-1`. Ici, l'adresse `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` avait créé un prénom plus tôt dans l'histoire avant celui-ci (qui se trouve être `abcdefgh123456. d`). - -Le but d'un DID est de fournir un identifiant éternel pour une clé publique. La clé publique peut changer, mais le DID ne changera pas. - -Stacks Blockchain implémente une méthode DID en elle-même afin d'être compatible avec d'autres systèmes qui utilisent DID pour la résolution de clé publique. Pour qu'un DID soit résolu, tout ce qui suit doit être vrai pour un nom : - -- Le nom doit exister -- Le hachage du fichier de zone du nom doit être le hachage d'un fichier de zone DNS bien formé -- Le fichier de zone DNS doit être présent dans les données du noeud Stacks. -- Le fichier de zone DNS doit contenir un enregistrement de la ressource `URI` qui pointe vers un jeton web JSON signé -- # La clé publique qui a signé le jeton Web JSON (et qui est inclus avec celui-ci) doit être hachée à l'adresse qui est propriétaire du nom -- The name's zone file hash must be the hash of a well-formed DNS zone file -- The DNS zone file must be present in the Stacks node's data. -- The DNS zone file must contain a `URI` resource record that points to a signed JSON Web Token -- The public key that signed the JSON Web Token (and is included with it) must hash to the address that owns the name - -Tous les noms n'auront pas forcément de DIDs qui seront résolus pour les clés publiques. Cependant, les noms créés par l'outil standard auront les DIDs qui le font. - -Une API RESTful est en cours de développement. - -## Encodage DID pour les sous-domaines - -Chaque nom et sous-domaine dans BNS a un DID. L'encodage est un peu différent pour les sous-domaines, donc le logiciel peut déterminer quel façon de coder choisir. - -- Pour les noms de BNS on-chain, le `{address}` est le même que l'adresse Bitcoin qui détient le nom. Actuellement, les adresses d'octets de version 0 et d'octets de version 5 sont prises en charge (c.-à-d. adresses commençant par `1` ou `3`, signifiant `p2pkh` et `p2sh` adresses). - -- Pour les sous-domaines BNS hors chaîne BNS, le `{address}` a un octet de version 63 pour sous-domaines appartenant à une seule clé privée, et l'octet de version 50 pour les sous-domaines appartenant à un ensemble m-of-n de clés privées. C'est-à-dire que les adresses DID de sous-domaine commencent par `S` ou `M`, respectivement. - -Le champ `{index}` pour un DID d'un sous-domaine est distinct du champ `{index}` pour le DID d'un BNS, même si la même chose crée des noms et des sous-domaines. Par exemple, le nom `abcdefgh123456. d` a le DID `did:stack:v0:16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg-0`, parce que c'était le prénom créé par `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg`. Cependant, `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` _a aussi_ créé `jude.statism.id` comme premier nom de sous-domaine. Le DID pour `jude.statism.id` est `did:stack:v0:SSXMcDiCZ7yFSQSUj7mWzmDcdwYhq97p2i-0`. Notez que l'adresse `SSXMcDiCZ7yFSQSUj7mWzmDcdwYhq97p2i` encode la même clé publique de hachage que l'adresse `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` (la seule différence entre ces deux chaînes est que le premier est codé en base58check avec la version byte 0, et la seconde est encodée avec la version byte 63). diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/build-apps/references/references.md b/i18n/fr/docusaurus-plugin-content-docs/current/build-apps/references/references.md deleted file mode 100644 index 98e9359790..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/build-apps/references/references.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: References -sidebar_label: References ---- - -[Authentification](./authentication) - -[Systeme de Noms sur Blockchain](./bns) - -[Exemple d'applications par Hiro](https://docs.hiro.so/example-apps) \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/contribute/docs.md b/i18n/fr/docusaurus-plugin-content-docs/current/contribute/docs.md deleted file mode 100644 index 77705451b8..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/contribute/docs.md +++ /dev/null @@ -1,207 +0,0 @@ ---- -title: Contribute to docs -description: Learn how this site is built, and how you can contribute to it. ---- - -## Introduction - -Thank you for your interest in contributing and helping make these docs as good as they can be. - -This docs site is built on the open source platform [Discosaurus 2](https://docusaurus.io/) and most of its content is written in Markdown files. All of the code for this site is free and open source, located at the [GitHub repository here](https://github.com/stacks-network/docs). - -:::tip Don't know what Markdown is? Want to learn? Here is a [helpful guide](https://guides.github.com/features/mastering-markdown/). - -Don't want to learn it? No need to. Write [in plain text an issue on Github](https://github.com/stacks-network/docs/issues/new?assignees=&labels=documentation&template=add-documentation.md&title=%5BAdd+docs%5D) ::: - -:::info You need a free [Github](https://www.github.com) account to add or edit any content. ::: - -To edit any page, just click on the *Edit this page* button at the bottom of each page and submit your changes online. - -To add new content, they are two different ways to do it, the [easy way](#easy-way) and the [advanced way](#advanced-way). - -## Easy way - -[**Simply click here and enter the text of the article you wish to add.**](https://github.com/stacks-network/docs/issues/new?assignees=&labels=documentation&template=add-documentation.md&title=%5BAdd+docs%5D) - -This will open up an issue on github using our template. -## Advanced way - -For more advanced changes you can follow the next steps. - -You can also test the site locally using this method. -### Steps - -1. Fork the [docs reposiroty](https://github.com/stacks-network/docs) by clicking on the *Fork* button in the upper right of the screen. -2. Clone your fork to your local machine with this command `git clone git@github.com:/docs.git stacks_docs` -3. Enter your project folder `cd stacks_docs` -4. Create a branch `git checkout -b feat/my-feature-branch`. -5. You can optionally preview your changes in real time with: - - `npm install` (to install dependencies). - - `npx docusaurus start` to start a local copy of the site. A web browser will open at http://localhost:3000, so you can see a preview of yourhanges in real time. -6. Make the changes you wish and then commit them with this kind of message: `git commit -am "feat: some new feature or content"`. -7. Push to to GitHub with `git push --set-upstream origin feature/my-feature-branch`. -8. Visit GitHub and make your pull request. - -## Aditional information -### Running and building the site locally (optional) - -You can start the page locally with the following command. This is enough to preview your changes. -```bash -npx docusaurus start -``` - -Before running this command for the first time you will need to run `npm install` to install dependencies. - -The docs site will be accessible at this url: [`http://localhost:3000`](http://localhost:3000). - - -After you finished your changes, you can also build the entire site with the following command (not usually needed): -```bash -npm run build -``` - -:::tip `npx docusaurus start` will only load the default language (english). To test all languages you can build with `npm run build` and then preview your build with `npm run serve`. ::: - -### An alternative: Working in browser - -As an alterative to working locally, you can also use the web IDE gitpod that provides an environment to contribute directly from within your browser. - -You only need to have a github account and open [this link](https://gitpod.io/#https://github.com/stacks-network/docs). - -### Folder structure of the site - -If you are interested in only adding new documentation content to the site, the files that will be important to you are located within `./docs/*`: - -```bash -docs/ - build-apps - contribute/ - faq/ - gaia/ - nodes-and-miners/ - noteworthy-contracts/ - references/ - understand-stack/ - write-smart-contracts/ -``` - -The routing for this site is file based, meaning if you created a folder within `/docs/gaia/` named `testing` and in it a file named `test1.md`, you would be able to navigate to `http://localhost:3000/gaia/testing/test1` and you would see whatever content is in that markdown file. - -All the docs in English are stored in the folder `/docs/`. - -To add new English content simply add a markdown file (.md) into any subfolder in docs, and it will be automatically displayed in the category of that folder. - -All the docs in other languages are stored under the folder `i18n`, but these files should never be edited using GitHub as they are overwritten by Crowdin every time new translations are added. **To make changes in other languages**, you must do so using Crowdin. Please refer to [translations](translations) instead. - -### Frontmatter - -Frontmatter is the top part of any markdown document that is written in a language called [YAML](https://yaml.org/). It looks like this: - -```yaml ---- -title: This is my page title -description: A short, concise sentence describing what is on this page ---- -``` - -Frontmatter gives us the ability to define some things within a page that the site can use, such as a page title or page description. When adding any new page, please include a `title` and `description`. - - - -### Use Conventional Commits - -We use the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) as and commits naming convention. Use it while contributing, please. - -### Code blocks - -To write a code block, you need to wrap your code in ` ```language `, and end your code block with ` ``` `. Here is an example of ` ```clarity `. - -```clarity -(define-data-var counter int 0) - -(define-public (get-counter) - (ok (var-get counter))) -``` -### Admonitions - -You can use the following admonitions to highlight content. - -```md -:::note -Some **content** with _markdown_ `syntax`. -::: - -:::tip -Some **content** with _markdown_ `syntax`. -::: - -:::info -Some **content** with _markdown_ `syntax`. -::: - -:::caution -Some **content** with _markdown_ `syntax`. -::: - -:::danger -Some **content** with _markdown_ `syntax`. -::: - -:::tip My personalized title -Some **content** with _markdown_ `syntax`. -::: -``` - -Which renders: - -:::note - -Some **content** with _markdown_ `syntax`. - -::: - -:::tip - -Some **content** with _markdown_ `syntax`. - -::: - -:::info - -Some **content** with _markdown_ `syntax`. - -::: - -:::caution - -Some **content** with _markdown_ `syntax`. - -::: - -:::danger - -Some **content** with _markdown_ `syntax`. - -::: - -:::tip My personalized title - -Some **content** with _markdown_ `syntax`. - -::: \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/contribute/index.md b/i18n/fr/docusaurus-plugin-content-docs/current/contribute/index.md deleted file mode 100644 index ac81d899bd..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/contribute/index.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Contribute -description: Contribute to the Stacks ecosystem. -sidebar_position: 10 -sidebar_label: "Contribute" ---- - -You can contribute to the Stacks ecosystem in multiple ways: - - - -### Documentation - -Contribute to the Stacks Docs on this website. More info [here](docs). - -### Translations - -Help us reach more people with translations. More details [here](translations). - - - -### Articles - -Write an article or a blog post about Stacks. A good place to start is [Stacks Forum](https://forum.stacks.org). - -### Github - -If you are familiar with Github they are multiple repositories of the Stack Ecosystem that you can contribute to. - -- https://github.com/stacks-network/ diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/contribute/translations.md b/i18n/fr/docusaurus-plugin-content-docs/current/contribute/translations.md deleted file mode 100644 index bd9a452333..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/contribute/translations.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Contribute with translations -description: Want to help tranlating these docs to your local language? ---- - -## Help with translations - -Translations are managed with Crowdin. -Anybody can colaborate and no technichal skills are required, as it's all done on the browser. - -To help with translation please go to [this page](https://crowdin.com/project/docsstacksco), click any language and start translating. - -All help is appreciated. - -:::caution -Please don't add any translations to the Github repository, as the translated pages get rewritten from Crowdin. Translations need to be added on Crodin intead. -::: - -### Common issues on translations - -When translating in Crowdin, please only translate the texts and not the html code. - -If you acccidently modify the html tags you will get errors like shown below (`Seems like some formating tags are missing` or `Translation contains tag that source text doesn't have`). These errors will prevent your translation getting published until the tags are left as they were in the original text. - -![](/img/crowdin-qa-issue-formatting_tags_missing.png) ![](/img/crowdin-qa-issue-tag_source.png) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/faq/faq.md b/i18n/fr/docusaurus-plugin-content-docs/current/faq/faq.md deleted file mode 100644 index c65bb3b369..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/faq/faq.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: General FAQs -description: Frequently Asked Questions -sidebar_label: "FAQ" -sidebar_position: 10 ---- - -![](/img/glasses.png) - -## Why is my transfer still pending? - -Commonly it's because your fee is too low or your [nonce](#what-is-nonce) is incorrect. - -More information can be found [here](https://www.hiro.so/wallet-faq/why-is-my-stacks-transaction-pending). There are also [best practices and known issues](https://forum.stacks.org/t/transactions-in-mempool-best-practices-and-known-issues/11659) and [diagnosing pending transactions](https://forum.stacks.org/t/diagnosing-pending-transactions/11908). - -There is also this [script](https://github.com/citycoins/scripts/blob/main/getnetworkstatus.js) to look at either the first 200 transactions or all the transactions in the mempool, to then return the maximum adn average fee values. We've noticed that using 1.5-2x the average fee in the mempool will generally get things processed within 6-10 blocks even during high congestion. - -There is also this [script](https://github.com/citycoins/scripts/blob/main/gettxstatus.js) to track a pending transaction until it reaches a final status. - -## What is Nonce? - -A nonce is used to make sure that every transaction goes in right order. Nonce starts at 0, so the very first transaction from an address should set to nonce=0. You can find the nonce of your wallet address by searching the address in any [Stacks blockchain explorer](https://explorer.stacks.co/). You can also user `$ stx balance
`. - -If you have a transaction nonce that is less than your account nonce, the transaction is unmineable and will (should) disappear after 256 blocks. This does not affect future transactions and therefore can be just ignored, they are in the past. - -If you have a transaction nonce that is equal to your account nonce, then that transaction is valid and should be the next in line to be processed next. - -If you have a transaction nonce that is higher than your account nonce, then there needs to be a chain of transactions starting with your account nonce in order for it to be processed. E.g. Your account nonce is 10 but the pending transaction has a nonce of 12. It will not be mineable until a transaction with nonces 10 and 11 are processed. - -## Whats a Replace-by-fee (RBF)? - -A replace-by-fee (RBF) transaction tells the blockchain that you would like to replace one transaction with another, while specifying a fee that is higher than the original transaction fee. A transaction can be replaced with **any other transaction**, and is not limited to the same operation. - -This can be used to effectively **cancel a transaction** by replacing it with something else, like a small STX transfer to another owned address. - -This can be used to **raise the fee for a pending transaction** so it is considered by miners during periods of high congestion. This can also be used to _resubmit_ a transaction, in the sense that the RBF transaction gets a new txid and gets considered again (or faster) by miners. E.g. I submit my transaction with 1 STX fee at block 54,123. By block 54,133 I see my tx hasn’t been picked up, so I RBF with 1.1 STX. Then wait 10 blocks again, and RBF again if not received. There’s a balance between doing this too often and keeping a consistent pace, but it has been seen to help get transactions through, especially when new ones are constantly flooding in. - -The replacement transaction needs to use the same nonce as the original transaction with a fee increase of at least 0.000001 STX. E.g. Your original transaction has a fee of 0.03 STX, the new RBF transaction must have a fee of 0.030001 STX or above. - -RBF transactions process in one of two ways: - -- If miners pick up the original transaction before the RBF transaction is received, then the original transaction is processed and the replacement transaction goes into an unmineable state. It will eventually disappear and doesn’t affect future transactions. -- If miners pick up the replaced transaction then the new transaction is processed instead of the original, and the status of the original transaction is set to “droppped_replaced_by_fee”. This status is not shown on the explorer but can be seen when querying the txid. - -Submitting multiple transactions for the same action can slow things down in a few ways. - -- If the total spent in 2 or 3 transactions is more than can be spent in a single transaction, the transactions appear unmineable. -- If the fees for multiple transactions exceed the STX balance, the transactions will be unmineable. - -## What are .btc domains? - -[This forum post](https://forum.stacks.org/t/btc-domains-are-live/12065) explains all the benefits of .btc domains. They can currently be purchased in [btc.us](https://btc.us/) - -## What is the blockchain trilemma? - -## Stacks vs. Solana vs. Polygon: How Do They Compare From a Developer Perspective? - -[This blog post answers the question](https://www.hiro.so/blog/stacks-vs-solana-vs-polygon-how-do-they-compare-from-a-developer-perspective). - -## What Does Lightning’s Taro Proposal Mean for Stacks? - -[This blog post answers the question](https://www.hiro.so/blog/what-does-lightnings-taro-proposal-mean-for-stacks). - - -## Is Stacks a [PoS chain](https://en.wikipedia.org/wiki/Proof_of_stake)?[¹][] - -No. - -The act of block production requires an extrinsic expenditure — it is not tied to owning the native token, as would be required in PoS. The only way to produce blocks in the Stacks chain is to transfer Bitcoin to a predetermined randomized list of Bitcoin addresses. Moreover, the Stacks blockchain can fork, and there exists a protocol to rank forks by quality independent of the set of miners and the tokens they hold. These two properties further distinguish it from PoS chains, which cannot fork due to the inability to identify a canonical fork without trusting a 3rd party to decree a particular fork as valid. The ability to fork allows the Stacks blockchain to survive failure modes that would crash a PoS chain. - -## Is Stacks a [sidechain](https://en.bitcoin.it/wiki/Sidechain)?[¹][] - -No. - -For two key reasons. - -First, the history of all Stacks blocks produced is recorded to Bitcoin. This means that the act of producing a private Stacks fork is at least as hard as reorging the Bitcoin chain. This in turn makes it so attacks on the chain that rely on creating private forks (such as selfish mining and double-spending) are much harder to carry out profitably, since all honest participants can see the attack coming before it happens and have a chance to apply countermeasures. Sidechains offer no such security benefit. - -Second, the Stacks blockchain has its own token; it does not represent pegged Bitcoin. This means that the safety of the canonical fork of the Stacks blockchain is underpinned by its entire token economy’s value, whereas the safety of a sidechain’s canonical fork is underpinned only by whatever system-specific measures incentivize its validators to produce blocks honestly, or the Bitcoin miners’ willingness to process peg-in requests (whichever is the weaker guarantee). - - -## Is Stacks a [layer-2 system](https://academy.binance.com/en/glossary/layer-2) for Bitcoin?[¹][] - -No. - -Stacks blockchain is a layer-1 blockchain, which uses a novel and unique mining protocol called proof-of-transfer (PoX). A PoX blockchain runs in parallel to another blockchain (Bitcoin in Stacks’ case), which it uses as a reliable broadcast medium for its block headers. It's a sovereign system in its own right. The Stacks blockchain state is distinct from Bitcoin, and is wholly maintained by and for Stacks nodes. Stacks transactions are separate from Bitcoin transactions. Layer-2 systems like Lightning are designed to help scale Bitcoin payment transactions, whereas Stacks is designed to bring new use-cases to Bitcoin through smart contracts. Stacks is not designed as a Bitcoin layer-2 scalability solution. - - -## Is Stacks a [merged-mined chain](https://en.bitcoin.it/wiki/Merged_mining_specification)?[¹][] - -No. - -The only block producers on the Stacks chain are Stacks miners. Bitcoin miners do not participate in Stacks block validation, and do not claim Stacks block rewards. Moreover, Stacks is not a [blind merged-mined chain](https://github.com/bitcoin/bips/blob/master/bip-0301.mediawiki), because STX block winners are public and randomly chosen (instead of highest-bid-wins), and its tokens are minted according to a schedule that is independent of the degree of miner commitment or Bitcoin transferred (instead of minted only by one-way pegs from Bitcoin). This ensures that Stacks is able to make forward progress without opt-in from Bitcoin miners, and it ensures that Stacks miners are adequately compensated for keeping the system alive regardless of transaction volume. - -## Whats the difference between Stacks and Ethereum?[²][] -**Computation and Storage** Stacks does all computation and storage outside of the blockchain, and uses the blockchain only as a “shared source of truth” between clients. By contrast, Ethereum does all computation and most application storage in the blockchain itself. Like Ethereum, if two Stacks nodes see the same underlying blockchain, they will independently run the same computations and produce the same state. Unlike Ethereum, there is no Stacks-specific blockchain. - -**Programming Language and Tooling** Stacks’s programming model is based on running off-chain programs. These programs can be written and debugged in any language you want. By contrast, Ethereum’s programming model is based on running on-chain “smart contracts.” These are written and debugged with a whole new set of tools, like Solidity and Serpent. These are written and debugged with a whole new set of tools, like Solidity and Serpent. - -**Scalability of On-chain Computation** Stacks is designed around a “virtual chain” concept, where nodes only need to reach consensus on the shared “virtual chain” they’re interested in. Virtual chains do not interact with one another, and a single blockchain can host many virtual chains. Although Stacks’s specific virtual chain is not Turing-complete (i.e. it’s a list of instructions to build the name database), it is possible to create Turing-complete virtual chains like Ethereum. These virtual chains can live in any blockchain for which there exists a driver, and virtual chain clients only need to execute their virtual chain transactions (i.e. Stacks only processes Stacks virtual chain transactions). - -By contrast, because smart contracts run on-chain and can call one another, all Ethereum nodes need to process all smart contracts’ computations in order to reach consensus. This can get expensive as the number of running smart contracts grow, which takes the form of gas fee increases. - -**Scalability of Off-chain Computation** Stacks applications are very similar to Web applications today and almost never need to interact with the blockchain. For most Stacks applications, the blockchain is only used to authenticate the application’s code and data before the user runs it. By contrast, Ethereum applications usually require an application-specific smart contract, and must interact with the blockchain to carry out its operations. - - -[¹]: https://stacks.org/stacks-blockchain -[²]: https://forum.stacks.org/t/what-is-the-difference-between-blockstack-and-ethereum/781 diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/gaia/configuration.md b/i18n/fr/docusaurus-plugin-content-docs/current/gaia/configuration.md deleted file mode 100644 index a6a530cd70..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/gaia/configuration.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Configuration -description: Configuring Gaia Hub ---- - -## Configuration files - -The following configuration files exist in the folder `deploy/configs/gaia/`: - -``` -admin-config.json -hub-config.json -reader-config.json -``` - -## GAIA Admin Service - -You can also use the GAIA Admin Service to remotely administer it with an API Key. It will require you to install `npm` with a `apt install npm`. Once `npm` is installed you can continue with the steps in the [GAIA Admin Service](https://github.com/stacks-network/gaia/blob/master/admin/README.md). - -## Driver Selection - -The Gaia hub currently supports the following drivers: - -``` -'aws' == Amazon S3 -'azure' == Azure Blob Storage -'disk' == Local disk -'google-cloud' === Google Cloud Storage -``` - -Set the driver you wish to use in your [config.json](https://github.com/stacks-network/gaia/blob/master/hub/config.sample.json) file with the `driver` parameter. Many drivers additionally accept the `bucket` parameter, which controls the bucket name that files should be written to. - -These driver may require you to provide additional credentials for performing writes to the backends. See `config.sample.json` for fields for those credentials. In some cases, the driver can use a system configured credential for the backend (e.g., if you are logged into your AWS CLI account, and run the hub from that environment, it won't need to read credentials from your `config.json`). - -_Note:_ The disk driver requires a \*nix like filesystem interface, and will not work correctly when trying to run in a Windows environment. ::: - -## Note on SSL - -We _strongly_ recommend that you deploy your Gaia hub with SSL enabled. Otherwise, the tokens used to authenticate with the Gaia hub may be stolen by attackers, which could allow them to execute writes on your behalf. -Configuration options are available to run the hub with an `https` Node.js server. -Otherwise, a reverse proxy web server such as nginx or Apache can be used. - -## Require Correct Hub URL - -If you turn on the `requireCorrectHubUrl` option in your `config.json` file, your Gaia hub will require that authentication requests correctly include the `hubURL` they are trying to connect with. This is used to prevent a malicious gaia hub from using an authentication token for itself on other Gaia hubs. - -By default, the Gaia hub will validate that the supplied URL matches `https://${config.serverName}`, but if there are multiple valid URLs for clients to reach the hub at, you can include a list in your `config.json`: - -```javascript -{ - .... - serverName: "normalserver.com" - validHubUrls: [ "https://specialserver.com/", - "https://legacyurl.info" ] - .... -} -``` - -## The readURL parameter - -By default, the gaia hub drivers will return read URLs which point directly at the written content. For example, an S3 driver would return the URL directly to the S3 file. However, if you configure a CDN or domain to point at that same bucket, you can use the `readURL` parameter to tell the gaia hub that files can be read from the given URL. For example, the `hub.blockstack.org` Gaia Hub is configured to return a read URL that looks like `https://gaia.blockstack.org/hub/`. - -Unset this configuration parameter if you do not intend to deploy any caching. - -## Minimum Proofs Requirement - -The gaia hub can also be configured to require a minimum number of social proofs in a user's profile to accept writes from that user. This can be used as a kind of spam-control mechanism. However, we recommend for the smoothest operation of your gaia hub, to set the `proofsConfig.proofsRequired` configuration key to `0`. - -## CDN & Replicated Hubs - -- https://docs.microsoft.com/en-us/azure/storage/blobs/storage-https-custom-domain-cdn - -- The hub implementation is designed to be ran from a single Node.js instance. If the hub instance is sharded (e.g. replicated hubs via load balancing), then any given `bucket` (identified by URI segment) must be served by the same instance, At least a couple elements of the Gaia Hub depend on this: token invalidation in-memory caching, and resource endpoint 409 contention behavior. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md b/i18n/fr/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md deleted file mode 100644 index 558cbb14f5..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Deploy Gaia Hub -description: Steps and tutorials ---- - -## Deploy your GAIA hub - -Tutorials to deploy your own GAIA hub are currently available for [Linux](./setup-linux), [MacOS](./setup-mac) and [Amazon EC2 / CloudFormation](./gaia-on-ec2). - -Regardless of what server the Gaia Hub runs on, the storage it uses can currently be deployed on multiple platforms: - -- Local disk (the server itself) -- Amazon S3 -- Azure Blob Storage -- Google Cloud - -:::tip -Support for IPFS is under development. -::: \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md b/i18n/fr/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md deleted file mode 100644 index 2067e7d57c..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Amazon EC2 -description: Use a template to deploy a Gaia hub on Amazon EC2 -tags: - - tutorial - - gaia ---- - -## Introduction - -The template provided on this page provides an easy way to deploy a Gaia hub directly to Amazon EC2. You can use this template to deploy your own Gaia hub to your Amazon Web Services (AWS) account. Amazon EC2 is an affordable and convenient cloud computing provider. The template provides a one-click deploy for Amazon EC2 with either S3 or EBS as a storage provider. - -## Prerequisites - -This procedure uses Amazon CloudFormation to configure an EC2 cloud compute provider to run the Gaia hub service with an S3 or EBS provider for file storage. You should have access to an AWS account either through your personal account or through a corporate account. This account should have permissions to create resources. - -Additionally, you must also own a domain name and be able to update the DNS records associated with that domain name. - -## Setup steps - -### Step 1 - Create Stack - -Use a link in the table to launch the [CloudFormation](https://console.aws.amazon.com/cloudformation/) template in the AWS region that you wish to deploy a Gaia hub. - -![Create stack](/img/cloudformation-create-stack.png) - -### Step 2 - Setup stack using template - -You need to configure the template with the appropiate values for your hub and domain it runs on. - -Select `Template is ready` and `Amazon S3 URL` and enter the following Amazon S3 URL: -``` -https://s3-external-1.amazonaws.com/cf-templates-vzldibfi2mw8-us-east-1/2022160J6G-cloudformation.yaml -``` - -If you prefer you can instead select `Template is ready` and `Upload a template file` to upload the template file `cloudformation.yaml`. - -The latest `cloudformation.yaml` file can be downloaded [here](https://raw.githubusercontent.com/stacks-network/gaia/master/deploy/cloudformation.yaml). On most browsers you can right-click on that page and click on `Save page as` to download the file. Alternatively, you can copy/paste the text into a text file called `cloudformation.yaml`. - -Then click `Next`. - -![Specify template](/img/cloudformation-specify-template.png) - -### Step 3 - Specify stack details - -Specify the stack details and then click `Next`: ![Specify template](/img/cloudformation-specify-stack-details.png) - -| Field | Value | Notes | -| --------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Stack name | _a unique name in your AWS account_ | e.g.: my_gaia_hub | -| DomainName | _your-domain_ | | -| EmailAddress | _your email address_ | | -| GaiaBucketName | _S3 bucket name_ | The template combines this name with the stack name to create a unique S3 bucket. The template ignores this field if GaiaStorageType is set to `disk`. | -| GaiaStorageType | `s3` or `disk` | Select the GaiaStorageType of which to use as a backend for the Gaia Hub. Selecting `s3` causes the template to create an S3 bucket based on the name given in the previous field. Selecting `disk` causes the template to attach a separate EBS volume to the EC2 instance for Hub storage. | -| InstaceType | t2.micro | Select the instance type you want. Default value is `t2.micro`. | -| KeyName | | In the KeyName drop-down, select an [EC2 KeyPair](https://console.aws.amazon.com/ec2/v2/home?region=us-east-1#KeyPairs:) to enable SSH access to the EC2 instance. You should download the `.pem` keyfile for this pair from the EC2 console. For more information see the [EC2 key pair documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html#prepare-key-pair) | -| SSHLocation | 0.0.0.0/0 | Leave the SSHLocation field with the default value of `0.0.0.0/0` to enable SSH access from any IP address. If you wish to restrict SSH access to the EC2 instance to a certain IP, you can update this field. | -| SubnetId | _subnetid_ | Select a public subnet | -| VpcId | _vpcid_ | | - -### Step 4 - Configure stack options - -Configure any stack options that fit your desired setup and click `Next`. All these fields are optional. - -![Specify template](/img/cloudformation-stack-options.png) - -### Step 5 - Review - -Review the configuration of your Gaia hub, select the checkbox to acknowledge that AWS may create IAM resources with custom names and click on `Create stack`. - -![Specify template](/img/cloudformation-iam-resources.png) - -### Step 6 - Retrieve the public IP of your Gaia hub - -Your stack can take several minutes to launch. You can monitor the Events tab of your hub to review the current progress of the launch. When the launch is complete, the Outputs tab displays information about the hub. Select the PublicIP and copy it to configure your domain name. - -Create an `A` DNS record pointing to the given IP in your domain. - -Wait a few minutes for the DNS record to propagate, and your should be able to access your Gaia hub with SSH. - -## Accessing your Gaia hub with SSH - -To SSH into your Gaia hub EC2 host directly, you must have the keyfile used in container creation. Access the host with the following command in your terminal: - -```bash -ssh -i admin@ -``` - -:::tip If you can only access SSH with the IP but not with the DNS name and you wish to do so, you can optionally activate it by following these steps: - - Open your [AWS Console](https://console.aws.amazon.com) - Click on `Service` -> VPC - Open Your VPCs - Select your VPC connected to your Gaia Hub - Click `Actions` -> `Edit DNS Hostnames` -> Change `DNS hostnames` to `Enable` -::: -## Graphical representation of the cloudformation template - -![](/img/cloudformation-gaia-template1-designer.png) \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/gaia/gaia.md b/i18n/fr/docusaurus-plugin-content-docs/current/gaia/gaia.md deleted file mode 100644 index 1070857350..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/gaia/gaia.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Gaia -description: Decentralized storage architecture for off-chain data -sidebar_position: 5 -tags: - - gaia ---- - -## Introduction - -Apps built with the Stacks blockchain store off-chain data using a storage system called Gaia. - -Whereas public transactional metadata is best stored on the Stacks blockchain, user application data can often be stored more efficiently and privately in Gaia storage. - -Storing data off of the blockchain ensures that Stacks applications can provide users with high performance and high availability for data reads and writes without introducing central trust parties. - -:::tip Latest whitepaper of GAIA (May 2022) is available [here](https://dev1-gaia-hub.s3.amazonaws.com/GAIA_Whitepaper.pdf) ::: - -## Understand Gaia in the Stacks architecture - -The following diagram depicts the Stacks architecture and Gaia's place in it: - -![Stacks Architecture](/img/architecture.png) - -Blockchains require consensus among large numbers of people, so they can be slow. Additionally, a blockchain is not designed to hold a lot of data. This means using a blockchain for every bit of data a user might write and store is expensive. For example, imagine if an application were storing every tweet in the chain. - -The Stacks blockchain addresses performance problems using a layered approach. The base layer consists of the Stacks blockchain and the Blockchain Naming System (BNS). The blockchain governs ownership of identities in the Stacks network. Identities can be names such as domain names, usernames, or application names. - -When an identity is created, its creation is recorded in the Stacks blockchain. Identities make up the primary data stored into the Stacks blockchain. These identities correspond to routing data in the OSI stack. The routing data is stored in the Atlas Peer Network, the second layer. Every core node that joins the Stacks Network is able to obtain an entire copy of this routing data. Stacks uses the routing data to associate identities (domain names, user names, and application names) with a particular storage location in the final layer, the Gaia Storage System. - -A Gaia Storage System consists of a _hub service_ and storage resource on a cloud software provider. The storage provider can be any commercial provider such as Azure, DigitalOcean, Amazon EC2, and so forth. Typically the compute resource and the storage resource reside same cloud vendor, though this is not a requirement. Gaia currently has driver support for S3, Azure Blob Storage, Google Cloud Platform and local disk, but the driver model allows for other backend support as well. - -Gaia stores data as a simple key-value store. When an identity is created, a corresponding data store is associated with that identity on Gaia. When a user logs into a dApp, the authentication process gives the application the URL of a Gaia hub, which then writes to storage on behalf of that user. - -The Stacks blockchain stores only identity data. Data created by the actions of an identity is stored in a Gaia Storage System. Each user has profile data. When a user interacts with a decentralized dApp that application stores application data on behalf of the user. Because Gaia stores user and application data off the blockchain, a Stacks DApp is typically more performant than DApps created on other blockchains. - -## User control or how is Gaia decentralized? - -A Gaia hub runs as a service which writes to data storage. The storage itself is a simple key-value store. The hub service writes to data storage by requiring a valid authentication token from a requestor. Typically, the hub service runs on a compute resource and the storage itself on separate, dedicated storage resource. Typically, both resources belong to the same cloud computing provider. - -![Gaiastorage](/img/gaia-storage.png) - -Gaia's approach to decentralization focuses on user control of data and its storage. Users can choose a Gaia hub provider. If a user can choose which Gaia hub provider to use, then that choice is all the decentralization required to enable user-controlled applications. Moreover, Gaia defines a uniform API for applications to access that data. - -The control of user data lies in the way that user data is accessed. When an application fetches a file `data.txt` for a given user `alice.id`, the lookup will follow these steps: - -1. Fetch the `zonefile` for `alice.id`. -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. Find the read-only url out of the profile's `appsMeta` section (e.g. `https://example-app.gaia.alice.org`). -6. Fetch the file from `https://example-app.gaia.alice.org/data.txt`. - -Because `alice.id` has access to her [zonefile](https://docs.stacks.co/references/bns-contract#name-update), 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. - -:::caution -Users with existing identities cannot yet migrate their data from one hub to another. -::: - -Applications writing directly on behalf of `alice.id` do not need to perform a lookup. Instead, the [Stacks authentication flow](https://stacks.js.org) provides Alice's chosen gaia hub URL to the application. This authentication flow _is also_ within Alice's control because Alice's wallet _must_ generate the authentication response. - -## Understand data storage - -A Gaia hub stores the written data _exactly_ as given. It offers minimal guarantees about the data. It does not ensure that data is validly formatted, contains valid signatures, or is encrypted. Rather, the design philosophy is that these concerns are client-side concerns. - -Client libraries (such as [`Stacks.js`](https://stacks.js.org/)) are capable of providing these guarantees. A liberal definition of the [end-to-end principle](https://en.wikipedia.org/wiki/End-to-end_principle) guides this design decision. - -When an application writes to a Gaia hub, an authentication token, key, and the data are passed to the Gaia hub. - -![Gaia writes](/img/gaia-writes.png) - -The token ensures the app has the authorization to write to the hub on the user's behalf. - -## Gaia versus other storage systems - -Here's how Gaia stacks up against other decentralized storage systems. Features that are common to all storage systems are omitted for brevity. - -| Features | [Gaia](https://github.com/stacks-network/gaia) | [Sia](https://sia.tech/) | [Storj](https://storj.io/) | [IPFS](https://ipfs.io/) | [DAT](https://datproject.org/) | [SSB](https://www.scuttlebutt.nz/) | -| ------------------------------------------ | ---------------------------------------------- | ------------------------ | -------------------------- | ------------------------ | ------------------------------ | ---------------------------------- | -| User controls where data is hosted | X | | | | | | -| Data can be viewed in a normal Web browser | X | | | X | | | -| Data is read/write | X | | | | X | X | -| Data can be deleted | X | | | | X | X | -| Data can be listed | X | X | X | | X | X | -| Deleted data space is reclaimed | X | X | X | X | | | -| Data lookups have predictable performance | X | | X | | | | -| Writes permission can be delegated | X | | | | | | -| Listing permission can be delegated | X | | | | | | -| Supports multiple backends natively | X | | X | | | | -| Data is globally addressable | X | X | X | X | X | | -| Needs a cryptocurrency to work | | X | X | | | | -| Data is content-addressed | | X | X | X | X | X | diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/gaia/setup-linux.md b/i18n/fr/docusaurus-plugin-content-docs/current/gaia/setup-linux.md deleted file mode 100644 index db427f890a..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/gaia/setup-linux.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: Linux -description: Steps to setup a GAIA hub on a Linux server (fresh install). This example is using Debian, but should work on any Linux distribution. It uses docker compose in the backgroud. -tags: - - tutorial - - gaia ---- - -This configuration will setup the following 4 docker containers: - -- Nginx with certbot on TCP ports 80 and 443. -- Gaia hub on TCP port 3000. -- Gaia admin on TCP port 8009. -- Gaia reader on TCP port 8008 - -**1. Update the system and install the dependencies and software we will use to test:** - -```bash -apt update && apt upgrade -y && apt install -y git vim gnupg jq -``` - -**2. Install [docker](https://docs.docker.com/engine/install/debian/) and [docker-compose](https://docs.docker.com/compose/cli-command/#install-on-linux)** in your OS. -For our example we install _docker_ with: - -```bash -curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg - -echo \ - "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian \ - $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null - -apt update && apt install -y docker-ce docker-ce-cli containerd.io -``` - -Install _docker-compose_ by downloading the [latest-release](https://github.com/docker/compose/releases): - -```bash -VERSION_DC=$(curl --silent https://api.github.com/repos/docker/compose/releases/latest | jq .name -r) -DESTINATION_DC=~/.docker/cli-plugins -mkdir -p ${DESTINATION_DC} -curl -SL https://github.com/docker/compose/releases/download/${VERSION_DC}/docker-compose-linux-x86_64 -o ${DESTINATION_DC}/docker-compose -chmod +x ${DESTINATION_DC}/docker-compose -``` - -**3. Clone the GAIA repository** and enter it's docker directory. - -```bash -git clone https://github.com/stacks-network/gaia.git && cd gaia/deploy/docker -``` - -**4. Copy and edit appropiate .env file**. -In the folder `./deploy/docker/` they are different sample files for different configurations like using aws, azure or disk among others. In this example we will store the data localy so we will copy the _disk_ file and update the domain and email fields. Please change `gaia.site.com` and `gaiarocks@mydomain.com` accordingly. Note you need both for the SSL certificate to be created correctly. - -```bash -export MYGAIADOMAIN=gaia.site.com -export MYGAIAEMAIL=gaiarocks@mydomain.com -cp sample-disk.env disk.env -sed -i 's/my-domain.com/'"$MYGAIADOMAIN"'/g' disk.env -sed -i 's/my-email@example.com/'"$MYGAIAEMAIL"'/g' disk.env - -``` - -**5. Start GAIA HUB service** - -To start GAIA HUB - -```bash -./gaiahub.sh start -``` - -To stop GAIA HUB - -```bash -./gaiahub.sh stop -``` - -To view GAIA HUB status - -```bash -./gaiahub.sh status -``` - -**6. Verify server works locally** with the following command: - -```bash -curl -sk http://localhost/hub_info | jq -``` - -A correct result should look similar to this: - -```bash - { - "challenge_text": "[\"gaiahub\",\"0\",\"gaia-0\",\"blockstack_storage_please_sign\"]", - "latest_auth_version": "v1", - "max_file_upload_size_megabytes": 20, - "read_url_prefix": "https://gaia.site.com/reader/" - } -``` - -**7. Test your GAIA HUB** Running `gaia_test.js` will test your GAIA Hub, by trying to connect to it, uploading a file and downloading it again. - -First install all required dependencies with: - -```bash -npm install -``` - -Then, from the root folder of the project type: - -```bash -node ./deploy/gaia_test.js https://yourgaiaurl -``` - -A correct result will be something like this: - -``` -Will run a test for the GAIA HUB: https://gaia.mydomain.com -Generating some test keys... -Private key: 5aacc60fc2a429e1f02be139f3cac82061c6a980******************** -Public key: 025691f17f2ab80dc4af363bb9c7aac59e9e1db6ae8ff668202582a3f4ec9678ff -Address: 15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS -[DEBUG] connectToGaiaHub: https://gaia.mydomain.com/hub_info -[DEBUG] uploadToGaiaHub: uploading testing.txt to https://gaia.mydomain.com -File uploaded successfully. -Upload to gaia hub thinks it can read it from: https://gaia.mydomain.com/reader/15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS/testing.txt -Hub info thinks it can read it from : https://gaia.mydomain.com/reader/15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS/testing.txt -Let's now try to fetch the uploaded file... -File fetched successfully. Contents of file: GAIA ROCKS! -``` diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/gaia/setup-mac.md b/i18n/fr/docusaurus-plugin-content-docs/current/gaia/setup-mac.md deleted file mode 100644 index 808833b212..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/gaia/setup-mac.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: MacOS -description: MacOS for local testing/development -tags: - - tutorial ---- - -The following assumes you have [Docker Installed](https://docs.docker.com/docker-for-mac/install/) - -- Recommended to also have [MacOS Homebrew](https://docs.brew.sh/Installation) installed -- Use Homebrew to install jq with `brew install jq` - -In your working directory: - -**1. Clone a copy of the [gaia repo](https://github.com/stacks-network/gaia):** - -```bash -$ git clone -b master --single-branch https://github.com/stacks-network/gaia -``` - -**2. Change your cwd:** - -```bash -$ cd gaia/deploy/docker -``` - -**3. Create a copy of sample-disk.env and fill out the values:** - -``` -$ cp sample-disk.env disk.env -# Update the DOMAIN_NAME variable to `localhost` -``` - -**4. Start the server:** - -``` -$ docker-compose -f docker-compose-base.yaml -f docker-compose-disk.yaml --env-file disk.env up -``` - -**5. Verify the server is responding locally:** - -``` -$ curl -sk https://localhost/hub_info | jq - { - "challenge_text": "[\"gaiahub\",\"0\",\"gaia-0\",\"blockstack_storage_please_sign\"]", - "latest_auth_version": "v1", - "max_file_upload_size_megabytes": 20, - "read_url_prefix": "https://localhost/reader/" - } -``` - -### Modifying the configuration for your gaia-hub - -Two methods exist: - -1. Edit the `gaia/deploy/configs/gaia/hub-config.json` using `vim` or other - -- requires a restart of the containers: `docker-compose -f docker-compose-base.yaml -f docker-compose-disk.yaml --env-file disk.env restart` - -2. Use the running `admin` container to modify any config values, and also reload the hub when complete: - -- [GitHub - Gaia Admin README.md](https://github.com/stacks-network/gaia/blob/master/admin/README.md) - -``` -$ export API_KEY="hello" -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - -H 'Content-Type: application/json' \ - -X POST \ - --data-raw '{"serverName": "myserver"}' \ - http://localhost:8009/v1/admin/config - -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - -X POST \ - http://localhost:8009/v1/admin/reload - -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - http://localhost:8009/v1/admin/config | jq -``` diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/governance/_index.md b/i18n/fr/docusaurus-plugin-content-docs/current/governance/_index.md deleted file mode 100644 index 1ecdf67871..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/governance/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Governance -description: Governance -sidebar_position: 9 ---- - -This page needs contributions. Help us write it! \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/governance/index.md b/i18n/fr/docusaurus-plugin-content-docs/current/governance/index.md deleted file mode 100644 index 91b0215b5f..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/governance/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Governance -description: Governance -sidebar_position: 9 ---- - -![](/img/stacks-governance.png) - -This page needs contributions. Help us write it! - -Governance in web3 is driven by the community. - -How can I get involved ? - -[Governance Resources website](https://resources.stacksgov.com) - -[Github - Stack Community Governance](https://github.com/stacksgov) - -:::tip Community Calls Monthly community calls are recorded and available [here](https://www.youtube.com/playlist?list=PLg717Ri_rTnwwYjQYlc7rIP6x2FaTNn7f) ::: diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/governance/sips.md b/i18n/fr/docusaurus-plugin-content-docs/current/governance/sips.md deleted file mode 100644 index 29ac1ae1ed..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/governance/sips.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: SIPs -description: SIPs -sidebar_position: 9 ---- - -## Stacks Improvement Proposals (SIPs) - -Stacks improvement proposals (SIPs) are aimed at describing the implementation of the Stacks blockchain, as well as proposing improvements. - -The SIP process [(SIP-000)](https://github.com/stacksgov/sips/blob/main/sips/sip-000/sip-000-stacks-improvement-proposal-process.md) describes how to make a SIP and get it ratified. - -They should contain concise technical specifications of features or standards and the rationale behind it. SIPs are intended to be the primary medium for proposing new features, for collecting community input on a system-wide issue, and for documenting design decisions. - -The SIPs are located in the [stacksgov/sips](https://github.com/stacksgov/sips) repository as part of the [Stacks Community Governance organization](https://github.com/stacksgov). - -Anyone in the Stacks community can submit a SIP. - -:::tip Stacks Improvement Proposals Community Calls SIP Meeting calls are recorded and available [here](https://www.youtube.com/playlist?list=PLg717Ri_rTnx5kuaWqp3cUAtwQk_yzslT) - -More details of the meetings are available [here](https://github.com/stacksgov/sips/issues/79) ::: - -## Ratified SIPSs - -- [x] [SIP 001: Burn Election](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md) -- [x] [SIP 002: Clarity, a language for predictable smart contracts](https://github.com/stacksgov/sips/blob/main/sips/sip-002/sip-002-smart-contract-language.md) -- [x] [SIP 003: Peer Network](https://github.com/stacksgov/sips/blob/main/sips/sip-003/sip-003-peer-network.md) -- [x] [SIP 004: Cryptographic Committment to Materialized Views](https://github.com/stacksgov/sips/blob/main/sips/sip-004/sip-004-materialized-view.md) -- [x] [SIP 005: Blocks, Transactions, and Accounts](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md) -- [x] [SIP 006: Clarity Execution Cost Assessment](https://github.com/stacksgov/sips/blob/main/sips/sip-006/sip-006-runtime-cost-assessment.md) -- [x] [SIP 007: Stacking Consensus](https://github.com/stacksgov/sips/blob/main/sips/sip-007/sip-007-stacking-consensus.md) -- [x] [SIP 008: Clarity Parsing and Analysis Cost Assessment](https://github.com/stacksgov/sips/blob/main/sips/sip-008/sip-008-analysis-cost-assessment.md) -- [x] [SIP 009: Standard Trait Definition for Non-Fungible Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-009/sip-009-nft-standard.md) -- [x] [SIP 010: Standard Trait Definition for Fungible Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-010/sip-010-fungible-token-standard.md) -- [x] [SIP 012: Burn Height Selection for a Network Upgrade to Introduce New Cost-Limits](https://github.com/stacksgov/sips/blob/main/sips/sip-012/sip-012-cost-limits-network-upgrade.md) -- [x] [SIP-016: Metadata for Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-016/sip-016-token-metadata.md) - -## How to Get Involved - -There are several ways you can get involved with the SIP process: - -* **Join the weekly SIP Meeting call** listed [here](https://community.stacks.org/events). - -* **SIP Editor**. SIP editors help SIP authors make sure their SIPs are well-formed and follow the right process. They help get SIPs ready for deep review by advancing it them from Draft to Accepted status. If you want to become a SIP editor, open an issue with your name and email to ask to be added to the list of SIP editors. - -* **Join a CAB** (Consideration Advisory Board). SIPs fall under the purview of one or more considerations. A full list is in [this github](https://github.com/stacksgov/sips/tree/main/considerations) directory. Currently they are: Diversity, Economics, Ethics, Governance and Technical. Members of SIP consideration advisory boards use their domain expertise to give Accepted SIPs a deep read, and give the authors any/all feedback to help make the SIP workable. If you want to join a board, reach out to the board's chairperson via the listed contact information. - -* **Steering Committee**. The Steering Committee organizes the consideration advisory boards and votes to advance Recommended SIPs to Activation-in-Progress status, and then to either Ratified or Rejected status. Once they are in the process of being activated, they use a SIP's Activation section to determine whether or not the Stacks ecosystem has ratified or rejected the SIP. Joining this committee requires the consent of the Stacks Foundation board. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/intro.md b/i18n/fr/docusaurus-plugin-content-docs/current/intro.md deleted file mode 100644 index 7d38997514..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/intro.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_label: "Home" -sidebar_position: 1 ---- - -# Introduction a la Documentation de Stacks - -Bienvenue à la documentation officielle de Stacks, apportée par la communautée. - -Découvre le minage de Stacks, le jeton STX et le language de programmes Clarity. - -![](/img/Bitcoinet-L_2.svg) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md b/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md deleted file mode 100644 index dd7194f504..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Stacks on DigitalOcean -description: A guide to setup Stacks on DigitalOcean -sidebar_position: 4 -tags: - - tutorial ---- - -## Introduction - -This is a step by step guide to deploy the [Stacks Blockchain on DigitalOcean](https://marketplace.digitalocean.com/apps/stacks-blockchain). Code is hosted on this [Github repository](https://github.com/stacks-network/stacks-blockchain-docker). - -## Steps - -#### Step 1 - -Go to the [Stacks Blockchain page](https://marketplace.digitalocean.com/apps/stacks-blockchain) in DigitalOcean's marketplace. Click on `Create Stacks Blockchain Droplet`. - -#### Step 2 - -Choose a plan (it will only allow you to select a plan that meets the minimum requirements) and your prefered datacenter region. ![](/img/sh_digitalocean-choose-plan.png) - -#### Step 3 - -Enter a root password or enable SSH keys if your prefer. - -![](/img/sh_digitalocean-choose-authentication.png) - -#### Step 4 - -You can leave the rest of the options as they are and click on `Create Droplet` - -#### Step 5 - -You will need to wait a few seconds for the droplet to get created. Once created click on it to see more information. - -![](/img/sh_digitalocean-creating-droplet.png) - -![](/img/sh_digitalocean-created-droplet.png) - -### Step 6 - -Congratulations! You are now running the Stacks Blockchain. You can click on `Console` for a terminal window to open or login using SSH to the public IP you've been assigned to with user `root`. - -![](/img/sh_digitalocean-console-button.png) ![](/img/sh_digitalocean-console.png) - -## Getting started after deploying Stacks Blockchain - -Once droplet is launched, initial startup can take several minutes while BNS data is imported (this is a one time operation). - -To keep track of the progress, you can `ssh root@your_droplet_public_ipv4` to the host and run: `/opt/stacks-blockchain-docker/manage.sh -n mainnet -a logs`. - -Once the stacks blockchain starts to sync with peers, application ports will open and nginx port 80 will now start proxying requests. - -Use `http://your_droplet_public_ipv4` to access the data directly, with output being similar to: - -```json -{ - "server_version": "stacks-blockchain-api v3.0.3 (master:cd0c8aef)", - "status": "ready", - "chain_tip": { - "block_height": 16220, - "block_hash": "0x3123fba9c0de6b569573494cf83c1d5d198a66bfd5f48ef97949b6bf11ba13be", - "index_block_hash": "0xeec960fbbd6186b4ccac85ce12adba72be497d881f81e077305c90955b51a6ae" - } -} -``` - -All services are managed by a [systemd unit file](https://github.com/stacksfoundation/stacks-machine-images/blob/master/files/etc/systemd/system/stacks.service) that is set to start on boot. - -Manual control is also possible via the [manage.sh script](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/manage.sh) at `/opt/stacks-blockchain-docker/manage.sh` on the host. - -Full details on how to use the manage.sh script is [available here](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/README.md#quickstart). - -## API Creation - -In addition to creating a Droplet from the Stacks Blockchain 1-Click App via the control panel, you can also use the [DigitalOcean API](https://digitalocean.com/docs/api). - -As an example, to create a 4GB Stacks Blockchain Droplet in the SFO2 region, you can use the following curl command. You’ll need to either save your [API access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/) to an environment variable or substitute it into the command below. - -```bash -curl -X POST -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer '$TOKEN'' -d \ - '{"name":"choose_a_name","region":"sfo2","size":"s-2vcpu-4gb","image":"stacksfoundation-stacksblockchain"}' \ - "https://api.digitalocean.com/v2/droplets" -``` diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md b/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md deleted file mode 100644 index b6cbb9754a..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Nodes and Miners -description: Nodes and Miners -sidebar_position: 7 ---- - -Here are all the steps to run nodes and miners, both on mainnet and testnet. - -## What's a Stacks node? - -## What's a Stacks miner? diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md b/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md deleted file mode 100644 index 40397a51e0..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Miner costs and fees -description: Miner Cost and Fee Estimation -sidebar_position: 8 ---- - -## Configuring Cost and Fee Estimation - -Fee and cost estimators can be configured via the config section `[fee_estimation]`: - -``` -[fee_estimation] -cost_estimator = naive_pessimistic -fee_estimator = fuzzed_weighted_median_fee_rate -fee_rate_fuzzer_fraction = 0.1 -fee_rate_window_size = 5 -cost_metric = proportion_dot_product -log_error = true -enabled = true -``` - -Fee and cost estimators observe transactions on the network and use the observed costs of those transactions to build estimates for viable fee rates and expected execution costs for transactions. Estimators and metrics can be selected using the configuration fields above, though the default values are the only options currently. `log_error` controls whether or not the INFO logger will display information about the cost estimator accuracy as new costs are observed. Setting `enabled = false` turns off the cost estimators. Cost estimators are **not** consensus-critical components, but rather can be used by miners to rank transactions in the mempool or client to determine appropriate fee rates for transactions before broadcasting them. - -The `fuzzed_weighted_median_fee_rate` uses a median estimate from a window of the fees paid in the last `fee_rate_window_size` blocks. Estimates are then randomly "fuzzed" using uniform random fuzz of size up to `fee_rate_fuzzer_fraction` of the base estimate. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md b/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md deleted file mode 100644 index 305ad0b5ca..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md +++ /dev/null @@ -1,343 +0,0 @@ ---- -title: Mine mainnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 mainnet -sidebar_position: 5 -tags: - - tutorial ---- - -## Introduction - -Make sure you've followed the [run a node](run-a-node) procedure. Une fois terminé, il ne reste plus que quelques étapes pour faire fonctionner un mineur Proof-of-Burn sur le réseau principal. - -If you're interested in mining on the testnet, you can find instructions on how to do that [here](miner-testnet): - -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining): - -## Running bitcoind locally - -To participate as a miner on mainnet, you must have access to a mainnet bitcoin node. One way to accomplish this is to run bitcoind locally. [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements) - -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. - -Next, start bitcoind with the following configuration: - -```toml -server=1 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=1 -banscore=1 -bind=0.0.0.0:8333 -rpcbind=0.0.0.0:8332 -rpcport=8332 -``` - -Finally, start bitcoind as follows: - -```bash -bitcoind -conf=path/to/bitcoin.conf -``` - -It may take a few days for the node to synchronize with the Bitcoin mainnet. - -## Exécution d'un mineur - -First, a keychain needs to be generated. With this keychain, we'll purchase some BTC from a crytpocurrency exchange, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. We'll use the `make_keychain` command. - -```bash -npx @stacks/cli make_keychain 2>/dev/null | json_pp > keychain.txt -``` - -After this runs, you should see some JSON in the new `keychain.txt` file that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -**Don't lose this information** - we'll need to use the `privateKey` field later on. - -The above BTC address will then need to be imported into the BTC network. - -```bash -bitcoin-cli -rpcport=8332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - - - -Once imported, we need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - - - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/mainnet-miner-conf.toml). - -Mettez à jour les propriétés suivantes : - -```toml -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `make_keychain` command. Replace the `seed` field with your private key. Save and close this configuration file. - -To run your miner, run this in the command line: - -```bash -stacks-node start --config=./testnet/stacks-node/conf/mainnet-miner-conf.toml -``` - -Your node should start. It will take some time to sync, and then your miner will be running. - -### Creating an optimized binary - -The steps above are great for trying to run a node temporarily. If you want to host a node on a server somewhere, you might want to generate an optimized binary. To do so, use the same configuration as above, but run: - -```bash -cd testnet/stacks-node -cargo build --release --bin stacks-node -``` - -The above code will compile an optimized binary. To use it, run: - -```bash -cd ../.. -./target/release/stacks-node start --config=./mainnet-miner-conf.toml -``` - -To read more about the technical details of mining on the Stacks 2.0 network, have a look at [the mining guide](../understand-stacks/mining). - -### Enable debug logging - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -STACKS_LOG_DEBUG=1 stacks-node mainnet -``` - -## Running a miner in Windows - -### Prerequisites - -Make sure are [running a node](run-a-node) and [running bitcoind locally](#running-bitcoind-locally) before starting this tutorial. - -### Generate keychain and get mainnet tokens in Windows - -To setup the miner, first we need to generate a keychain. With this keychain, we'll purchase some BTC from a crytpocurrency exchange, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. To get a keychain, the simplest way is to use the `stacks-cli`. - -Generate a keychain: - -```bash -npm install --global @stacks/cli -stx make_keychain > cli_keychain.json -type cli_keychain.json -``` - -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -The above BTC address will then need to be imported into the BTC network. - -```bash -bitcoin-cli -rpcport=8332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - -Once imported, we need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Update configuration file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/mainnet-miner-conf.toml). - -Mettez à jour les propriétés suivantes : - -```toml -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Run the miner - -To start your miner, run this in the command line: - -```bash -stacks-node start --config=testnet/stacks-node/conf/mainnet-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](/img/windows-defender.png) - -Your node should start. It will take some time to sync, and then your miner will be running. - -### Enable debug logging in Windows - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=mainnet-miner-conf.toml -``` - -## Optional: Running with Docker - -Alternatively, you can run the mainnet node with Docker. - -:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: - -### Generate keychain and get tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null -``` - -We need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Update configuration file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/mainnet-miner-conf.toml). - -Mettez à jour les propriétés suivantes : - -```toml -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Start the miner - -:::info The ENV VARS `RUST_BACKTRACE` and `STACKS_LOG_DEBUG` are optional. If removed, debug logs will be disabled ::: - -```bash -docker run -d \ - --name stacks_miner \ - --rm \ - --network host \ - -e RUST_BACKTRACE="full" \ - -e STACKS_LOG_DEBUG="1" \ - -v "$(pwd)/testnet/stacks-node/conf/mainnet-miner-conf.toml:/src/stacks-node/mainnet-miner-conf.toml" \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain:latest \ -/bin/stacks-node start --config /src/stacks-node/mainnet-miner-conf.toml -``` - -You can review the node logs with this command: - -```bash -docker logs -f stacks_miner -``` - -## Optional: Running in Kubernetes with Helm - -In addition, you're also able to run a mainnet node in a Kubernetes cluster using the [stacks-blockchain Helm chart](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). - -Ensure you have the following prerequisites installed on your machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [minikube](https://minikube.sigs.k8s.io/docs/start/) (Only needed if standing up a local Kubernetes cluster) -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [helm](https://helm.sh/docs/intro/install/) - -### Generate keychain and get some tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null -``` - -We need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Install the chart and run the miner - -To install the chart with the release name `my-release` and run the node as a miner: - -```bash -minikube start # Only run this if standing up a local Kubernetes cluster -helm repo add blockstack https://charts.blockstack.xyz -helm install my-release blockstack/stacks-blockchain \ - --set config.node.miner=true \ - --set config.node.seed="replace-with-your-privateKey-from-generate-keychain-step" \ - --set config.burnchain.mode="mainnet" -``` - -You can review the node logs with this command: - -```bash -kubectl logs -l app.kubernetes.io/name=stacks-blockchain -``` - -For more information on the Helm chart and configuration options, please refer to the [chart's homepage](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md b/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md deleted file mode 100644 index fbc4c25f00..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md +++ /dev/null @@ -1,336 +0,0 @@ ---- -title: Mine testnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 testnet -sidebar_position: 4 -tags: - - tutorial ---- - -## Introduction - -Make sure you've followed the [Run a node](run-a-node) procedure. Once completed it's only a few more steps to run a proof-of-burn miner on the testnet. - -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining). - -## Running bitcoind locally - -To participate as a miner on Testnet, you must have access to a testnet bitcoin node. One way to accomplish this is to run bitcoind locally. [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements) - -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. - -Next, start bitcoind with the following configuration: - -```toml -server=1 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password -testnet=1 -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=1 -banscore=1 - -[test] -bind=0.0.0.0:18333 -rpcbind=0.0.0.0:18332 -rpcport=18332 -``` - -Finally, start bitcoind as follows: - -```bash -bitcoind -conf=path/to/bitcoin.conf -``` - -It may take a few hours for the node to synchronize with the Bitcoin testnet. - -## Exécution d'un mineur - -First, a keychain needs to be generated. With this keychain, we'll get some testnet BTC from a faucet, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. To get a keychain, the simplest way is to use the `stacks-cli`. - -```bash -npx @stacks/cli make_keychain -t 2>/dev/null | json_pp > keychain.txt -``` - -After this runs, you should see some JSON in the new `keychain.txt` file that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -**Don't lose this information** - we'll need to use the `privateKey` field later on. - -The above BTC address will then need to be imported into the BTC testnet network. - -```bash -bitcoin-cli -rpcport=18332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - -Once imported, we need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). You'll be sent `0.01` testnet BTC to that address. - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/testnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/testnet-miner-conf.toml). - -Mettez à jour les propriétés suivantes : - -```toml -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `make_keychain` command. Replace the `seed` field with your private key. Save and close this configuration file. - -To run your miner, run this in the command line: - -```bash -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. - -### Creating an optimized binary - -The steps above are great for trying to run a node temporarily. If you want to host a node on a server somewhere, you might want to generate an optimized binary. To do so, use the same configuration as above, but run: - -```bash -cd testnet/stacks-node -cargo build --release --bin stacks-node -``` - -The above code will compile an optimized binary. To use it, run: - -```bash -cd ../.. -./target/release/stacks-node start --config=./testnet/conf/testnet-follower-conf.toml -``` - -To read more about the technical details of mining on the Stacks 2.0 network, have a look at [the minig guide](../understand-stacks/mining): - -### Enable debug logging - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -STACKS_LOG_DEBUG=1 stacks-node testnet -``` - -## Running a miner in Windows - -### Prerequisites - -Make sure are [running a testnet node](run-a-node) before starting this tutorial. - -### Generate keychain and get testnet tokens in Windows - -To setup the miner, first, we need to generate a keychain. With this keychain, we'll get some testnet BTC from a faucet, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. We'll use the `stx make-keychain` command, and pass `-t` to indicate that we want a testnet keychain. - -Generate a keychain: - -```bash -npm install --global @stacks/cli -stx make_keychain -t > cli_keychain.json -type cli_keychain.json -``` - -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -Request BTC from faucet: - -We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). - -### Update configuration file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/testnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/testnet-miner-conf.toml). - -Mettez à jour les propriétés suivantes : - -```toml -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Run the miner - -To start your miner, run this in the command line: - -```bash -stacks-node start --config=testnet/stacks-node/conf/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](/img/windows-defender.png) - - - -Your node should start. It will take some time to sync, and then your miner will be running. - -### Enable debug logging in Windows - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=testnet-miner-conf.toml -``` - -## Optional: Running with Docker - -Alternatively, you can run the testnet node with Docker. - -:::warning Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: - -### Generate keychain and get testnet tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` - -We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). - -### Update config file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/testnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/testnet-miner-conf.toml). - -Mettez à jour les propriétés suivantes : - -```toml -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Start the miner - -:::info The ENV VARS `RUST_BACKTRACE` and `STACKS_LOG_DEBUG` are optional. If removed, debug logs will be disabled ::: - -```bash -docker run -d \ - --name stacks_miner \ - --rm \ - --network host \ - -e RUST_BACKTRACE="full" \ - -e STACKS_LOG_DEBUG="1" \ - -v "$(pwd))/testnet/stacks-node/conf/testnet-miner-conf.toml:/src/stacks-node/testnet-miner-conf.toml" \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain:latest \ -/bin/stacks-node start --config /src/stacks-node/testnet-miner-conf.toml -``` - -You can review the node logs with this command: - -```bash -docker logs -f stacks_miner -``` - -## Optional: Running in Kubernetes with Helm - -In addition, you're also able to run a testnet node in a Kubernetes cluster using the [stacks-blockchain Helm chart](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). - -Ensure you have the following prerequisites installed on your machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [minikube](https://minikube.sigs.k8s.io/docs/start/) (Only needed if standing up a local Kubernetes cluster) -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [helm](https://helm.sh/docs/intro/install/) - -### Generate keychain and get some testnet tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` - -We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). - -### Install the chart and run the miner - -To install the chart with the release name `my-release` and run the node as a miner: - -```bash -minikube start # Only run this if standing up a local Kubernetes cluster -helm repo add blockstack https://charts.blockstack.xyz -helm install my-release blockstack/stacks-blockchain \ - --set config.node.miner=true \ - --set config.node.seed="replace-with-your-privateKey-from-generate-keychain-step" -``` - -You can review the node logs with this command: - -```bash -kubectl logs -l app.kubernetes.io/name=stacks-blockchain -``` - -For more information on the Helm chart and configuration options, please refer to the [chart's homepage](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md b/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md deleted file mode 100644 index 94d938c5ca..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md +++ /dev/null @@ -1,351 +0,0 @@ ---- -title: Run a node -description: Set up and run a Stacks node -sidebar_position: 1 -tags: - - tutorial ---- - -## Stacks Blockchain with Docker - -Run your own Stacks Blockchain node easily with just few commands. - -This tutorial describes a simple and effective [quickstart](#quickstart) to run a Stacks node using public scripts hosted in [Stacks Blockchain repository](https://github.com/stacks-network/stacks-blockchain-docker). Valid for mainnet, testnet and mocknet. - -## **Quickstart** - -1. **Clone the stacks-blockchain-docker repository locally** - -```bash -git clone https://github.com/stacks-network/stacks-blockchain-docker && cd stacks-blockchain-docker -``` - -2. **Optionally, create/copy `.env` file**. If file `.env` doesn't exist when launched it will be created from `sample.env` automatically. - -```bash -cp sample.env .env -``` - -_You may also use a symlink as an alternative to copying: `ln -s sample.env .env`_ - -3. **Optionally, ensure all images are up to date** - -```bash -./manage.sh -n -a pull -``` - -4. **Start the Services** - -```bash -./manage.sh -n -a start -``` - -- With optional proxy: - -```bash -./manage.sh -n -a start -f proxy -``` - -- With optional bitcoin node: - -```bash -./manage.sh -n -a start -f bitcoin -``` - -5. **Stop the Services** - -```bash -./manage.sh -n -a stop -``` - -6. **Retrieve Service Logs** - -```bash -./manage.sh -n -a logs -``` - -- Export docker log files to `./exported-logs`: - -This will create one log file for every running service, for example: postgres.log, stacks-blockain.log, stacks-blockchain-api.log and bitcoin-core.log. -Notice that each time you run this command the log files will be overwritten. - -```bash -./manage.sh -n -a logs export -``` - -7. **Restart all services** - -```bash -./manage.sh -n -a restart -``` - -- With optional proxy: - -```bash -./manage.sh -n -a restart -f proxy -``` - -8. **Delete** all data in `./persistent-data/` and/or data of the Bitcoin blockchain. - - This data is owned by root, so you will need to run it with sudo privileges so it can delete the data. - -```bash -$ sudo ./manage.sh -n -a reset - -Please confirm what persistent data you wish to delete: - -0. Cancel -1. Delete Persistent data for Stacks testnet only and leave Bitcoin blockchain data unaffected. -2. Delete Persistent data for Stacks testnet and Bitcoin blockchain data in ./persistent-data/blockchain-bitcoin -3. Delete Persistent data for Bitcoin blockchain data in ./persistent-data/blockchain-bitcoin only. -Please note that BNS data will never get deleted. - -Type 0, 1, 2 or 3: 2 - -Ok. Delete Stacks and Bitcoin data. -[ Success ] Persistent data deleted for Bitcoin blockchain. -[ Success ] Persistent data deleted for Stacks testnet. - -``` - -9. **Download BNS data to** `./persistent-data/bns-data` - -```bash -./manage.sh bns -``` - -10. **Export stacks-blockchain-api events** (_Not applicable for mocknet_) - -```bash -./manage.sh -n -a export -# check logs for completion -./manage.sh -n -a restart -``` - -11. **Replay stacks-blockchain-api events** (_Not applicable for mocknet_) - -```bash -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart -``` - -## **Running also a bitcoin node (Optional)** - -Stacks needs to use a Bitcoin node, and by default when you run a Stacks node you will be using a public Bitcoin node, which is configured in the `.env` file. Default values is `BITCOIN_NODE=bitcoin.mainnet.stacks.org`. - -However, you can optionaly run both nodes together and configured in a way that you Stacks node will use your own Bitcoin node instead of a public one. - -If you run the script with a bitcoin node it will download and build it directly from source for increased security. This process which only needs to happen once can take up to 20-30 minutes depending on the speed of your system. Also, once the bitcoin node is up and running it will need an additional time for sync for the first time (can be hours for testnet and days for mainnet). - -### Why run Stacks node with your own Bitcoin node? - -Because running your own Bitcoin node will give you higher security and improved perfomance. - -* **Improved perfomance**: The Bitcoin node will serve you blocks faster, as well as UTXOs for your miner (if you run one). -* **Higher security**: The Bitcoin node will also have validated all bitcoin transactions the Stacks node consumes. If you don't run your own Bitcoin node, you're relying on the SPV headers to vouch for the validity of Bitcoin blocks. - -The disadvantage of running your own Bitcoin node is that you need the extra space to store the Bitcoin blockchain (about 500GB) and the initial time it will take to download this data the first time. - -### Example - -You can run easily run your Stacks node with your own Bitcoin node by adding the flag `bitcoin`. This is available only for testnet and mainnet. - -Example: `./manage.sh -n mainnet -a start -f bitcoin` or `./manage.sh -n testnet -a start -f bitcoin` - -### Bitcoin node configuration - -In the `.env` file there is the variable `BITCOIN_BLOCKCHAIN_FOLDER`. As the bitcoin blockchain can be large (over 500GB) you optionally change this variable to any location of your choosing. If you have previously used the [bitcoin core application](https://bitcoin.org/en/bitcoin-core/) and already have the bitcoin blockchain synced, you can use the same data folder and avoid redownloading the entire bitcoin blockchain. - -## **Accessing the services** - -:::tip For networks other than `mocknet`, downloading the initial headers can take several minutes. Until the headers are downloaded, the `/v2/info` endpoints won't return any data. - -Use the command `./manage.sh -n -a logs` to check the sync progress. ::: - -**stacks-blockchain**: - -- Ports `20443-20444` are exposed to `localhost` - -```bash -curl -sL localhost:20443/v2/info | jq -``` - -**stacks-blockchain-api**: - -- Port `3999` are exposed to `localhost` - -```bash -curl -sL localhost:3999/v2/info | jq -``` - -**proxy**: - -- Port `80` is exposed to `localhost` - -```bash -curl -sL localhost/v2/info | jq -curl -sL localhost/ | jq -``` - ---- - -## Upgrades - -⚠️ For upgrades to running instances of this repo, you'll need to [run the event-replay](https://github.com/hirosystems/stacks-blockchain-api#event-replay): - -```bash -./manage.sh -n -a stop -./manage.sh -n -a export -./manage.sh -n -a import -./manage.sh -n -a restart -``` - ---- - -## **Workarounds to potential issues** - -_**Port(s) already in use**_: - -- 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. `3999` and edit your `.env` file to use the new port. - -```bash -netstat -anl | grep 3999 -``` - -``` -tcp46 0 0 *.3999 *.* LISTEN -``` - -_**Containers not starting (hanging on start)**_: - -- Occasionally, docker can get **stuck** and not allow new containers to start. If this happens, simply restart your docker daemon and try again. - -_**Database Issues**_: - -- For any of the various Postgres/sync issues, it may be easier to simply remove the persistent data dir. Note that doing so will result in a longer startup time as the data is repopulated. - -```bash -./manage.sh -n -a stop -./manage.sh -n -a reset -./manage.sh -n -a start -``` - -_**API Missing Parent Block Error**_: - -- If the Stacks blockchain is no longer syncing blocks, and the API reports an error similar to this:\ - `Error processing core node block message DB does not contain a parent block at height 1970 with index_hash 0x3367f1abe0ee35b10e77fbcaa00d3ca452355478068a0662ec492bb30ee0f13e"`,\ - The API (and by extension the DB) is out of sync with the blockchain. \ - The only known method to recover is to resync from genesis (**event-replay _may_ work, but in all likelihood will restore data to the same broken state**). - -- To attempt the event-replay - -```bash -./manage.sh -n -a stop -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart -``` - -- To wipe data and re-sync from genesis - -```bash -./manage.sh -n -a stop -./manage.sh -n -a reset -./manage.sh -n -a restart -``` - - -## **Requirements:** - -- [Docker](https://docs.docker.com/get-docker/) >= `17.09` -- [docker-compose](https://github.com/docker/compose/releases/) >= `1.27.4` -- [git](https://git-scm.com/downloads) -- [jq binary](https://stedolan.github.io/jq/download/) -- [sed](https://www.gnu.org/software/sed/) -- Machine with (at a minimum): - - 4GB memory - - 1 Vcpu - - 50GB storage (600GB if you optionally also run the bitcoin mainnet node) - -:::caution MacOS with an M1 processor is NOT recommended - -The way Docker for Mac on an Arm chip is designed makes the I/O incredibly slow, and blockchains are **_very_** heavy on I/O. This only seems to affect MacOS, other Arm based systems like Raspberry Pi's seem to work fine. - -::: - - -### Install/Update docker-compose - -:::note `docker-compose` executable is required, even though recent versions of Docker contain `compose` natively ::: - -- [Install Docker-compose](https://docs.docker.com/compose/install/) -- [Docker Desktop for Mac](https://docs.docker.com/docker-for-mac/install/) -- [Docker Desktop for Windows](https://docs.docker.com/docker-for-windows/install/) -- [Docker Engine for Linux](https://docs.docker.com/engine/install/#server) - -First, check if you have `docker-compose` installed locally. - -To do that, run this command in your terminal : - -```bash -docker-compose --version -``` - -Output should look something very similar to this : - -``` -docker-compose version 1.27.4, build 40524192 -``` - -If the command is not found, or the version is < `1.27.4`, run the following to install the latest to `/usr/local/bin/docker-compose`: - -```bash -#You will need to have jq installed, or this snippet won't run. -VERSION=$(curl --silent https://api.github.com/repos/docker/compose/releases/latest | jq .name -r) -DESTINATION=/usr/local/bin/docker-compose -sudo curl -L https://github.com/docker/compose/releases/download/${VERSION}/docker-compose-$(uname -s)-$(uname -m) -o $DESTINATION -sudo chmod 755 $DESTINATION -``` - -### Security note on docker - -The Docker daemon always runs as the root user so by default you will need root privileges to interact with it. - -The script `manage.sh` uses docker, so to avoid the requirement of needing to run the script with root privileges it is prefered to be able to *manage Docker as a non-root user*, following [these simple tests](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user). - -This will avoid the need of running the script with root privileges for all operations except the removal of data. - -### Configuration files you can edit - -The following files can be modified to personalize your node configuration, but generally most of them should be left as-is. All these files will be created from the sample copy if they don't exist at runtime (for example `.env` is created from `sample.env`). However these files will never be modified by the application once created and will never be pushed back to github, so your changes will be safe. - -* `.env` -* `./conf/mainnet/Config.toml` -* `./conf/mainnet/bitcoin.conf` -* `./conf/testnet/Config.toml` -* `./conf/testnet/bitcoin.conf` - -By default: - -- BNS data is **not** enabled/imported - - To enable, uncomment `# BNS_IMPORT_DIR=/bns-data` in `./env` - - Download BNS data: `./manage.sh bns` -- Fungible token metadata is **not** enabled - - To enable, uncomment `# STACKS_API_ENABLE_FT_METADATA=1` in `./env` -- Non-Fungible token metadata is **not** enabled - - To enable, uncomment `# STACKS_API_ENABLE_NFT_METADATA=1` in `./env` -- Verbose logging is **not** enabled - - To enable, uncomment `# VERBOSE=true` in `./env` -- Bitcoin blockchain folder is configured in `BITCOIN_BLOCKCHAIN_FOLDER` in `./env` - -### Local Data Dirs - -Directories will be created on first start that will store persistent data under `./persistent-data/` - -`` can be 1 of: - -- mainnet -- testnet -- mocknet diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md b/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md deleted file mode 100644 index 09db354d0d..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md +++ /dev/null @@ -1,188 +0,0 @@ ---- -title: Running a mainnet node -description: Set up and run a mainnet node with Docker -sidebar_position: 3 -tags: - - tutorial ---- - -## Introduction - -This procedure demonstrates how to run a local mainnet node using Docker images. - -:::caution -This procedure focuses on Unix-like operating systems (Linux and MacOS). This procedure has not been tested on Windows. -::: - -## Prerequisites - -Running a node has no specialized hardware requirements. Users have been successful in running nodes on Raspberry Pi boards and other system-on-chip architectures. In order to complete this procedure, you must have the following software installed on the node host machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [curl](https://curl.se/download.html) -- [jq](https://stedolan.github.io/jq/download/) - -### Firewall configuration - -In order for the API node services to work correctly, you must configure any network firewall rules to allow traffic on the ports discussed in this section. The details of network and firewall configuration are highly specific to your machine and network, so a detailed example isn't provided. - -The following ports must open on the host machine: - -Ingress: - -- stacks-blockchain (open to `0.0.0.0/0`): - - `20443 TCP` - - `20444 TCP` - -Egress: - -- `8332` -- `8333` -- `20443-20444` - -These egress ports are for syncing stacks-blockchain and Bitcoin headers. If they're not open, the sync will fail. - -## Step 1: initial setup - -In order to run the mainnet node, you must download the Docker images and create a directory structure to hold the persistent data from the services. Download and configure the Docker images with the following commands: - -```sh -docker pull blockstack/stacks-blockchain -``` - -Create a directory structure for the service data with the following command: - -```sh -mkdir -p ./stacks-node/{persistent-data/stacks-blockchain/mainnet,config/mainnet} && cd stacks-node -``` - -## Step 2: running Stacks blockchain - -First, create the `./config/mainnet/Config.toml` file and add the following content to the file using a text editor: - -```toml -[node] -working_dir = "/root/stacks-node/data" -rpc_bind = "0.0.0.0:20443" -p2p_bind = "0.0.0.0:20444" -bootstrap_node = "02da7a464ac770ae8337a343670778b93410f2f3fef6bea98dd1c3e9224459d36b@seed-0.mainnet.stacks.co:20444,02afeae522aab5f8c99a00ddf75fbcb4a641e052dd48836408d9cf437344b63516@seed-1.mainnet.stacks.co:20444,03652212ea76be0ed4cd83a25c06e57819993029a7b9999f7d63c36340b34a4e62@seed-2.mainnet.stacks.co:20444" -wait_time_for_microblocks = 10000 - -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "bitcoin.blockstack.com" -username = "blockstack" -password = "blockstacksystem" -rpc_port = 8332 -peer_port = 8333 - -[connection_options] -read_only_call_limit_write_length = 0 -read_only_call_limit_read_length = 100000 -read_only_call_limit_write_count = 0 -read_only_call_limit_read_count = 30 -read_only_call_limit_runtime = 1000000000 -``` - -Start the `stacks-blockchain` container with the following command: - -```sh -docker run -d --rm \ - --name stacks-blockchain \ - -v $(pwd)/persistent-data/stacks-blockchain/mainnet:/root/stacks-node/data \ - -v $(pwd)/config/mainnet:/src/stacks-node \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain \ -/bin/stacks-node start --config /src/stacks-node/Config.toml -``` - -You can verify the running `stacks-blockchain` container with the command: - -```sh -docker ps --filter name=stacks-blockchain -``` - -## Step 3: verifying the services - -:::note -The initial burnchain header sync can take several minutes, until this is done the following commands will not work -::: - -To verify the `stacks-blockchain` burnchain header sync progress: - -```sh -docker logs stacks-blockchain -``` - -The output should be similar to the following: - -``` -INFO [1626290705.886954] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.2% (8000 out of 691034) -INFO [1626290748.103291] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.4% (10000 out of 691034) -INFO [1626290776.956535] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.7% (12000 out of 691034) -``` - -To verify the `stacks-blockchain` tip height is progressing use the following command: - -```sh -curl -sL localhost:20443/v2/info | jq -``` - -If the instance is running you should recieve terminal output similar to the following: - -```json -{ - "peer_version": 402653184, - "pox_consensus": "89d752034e73ed10d3b97e6bcf3cff53367b4166", - "burn_block_height": 666143, - "stable_pox_consensus": "707f26d9d0d1b4c62881a093c99f9232bc74e744", - "stable_burn_block_height": 666136, - "server_version": "stacks-node 2.0.11.1.0-rc1 (master:67dccdf, release build, linux [x86_64])", - "network_id": 1, - "parent_network_id": 3652501241, - "stacks_tip_height": 61, - "stacks_tip": "e08b2fe3dce36fd6d015c2a839c8eb0885cbe29119c1e2a581f75bc5814bce6f", - "stacks_tip_consensus_hash": "ad9f4cb6155a5b4f5dcb719d0f6bee043038bc63", - "genesis_chainstate_hash": "74237aa39aa50a83de11a4f53e9d3bb7d43461d1de9873f402e5453ae60bc59b", - "unanchored_tip": "74d172df8f8934b468c5b0af2efdefe938e9848772d69bcaeffcfe1d6c6ef041", - "unanchored_seq": 0, - "exit_at_block_height": null -} -``` - -## Stopping the mainnet node - -Use the following commands to stop the local mainnet node: - -```sh -docker stop stacks-blockchain -``` - -## Optional. Run stacks node with own bitcoin node - -It's encouraged to use your own bitcoin node when possible. - -To do this simply update the `stacks-node/config/mainnet/Config.toml` file with the details of your bitcoin node. For example: - -``` -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "localhost" -username = "rpc username" -password = "rpc password" -rpc_port = 8332 -peer_port = 8333 -``` - -The rpc configuration of your bitcoin node is out of the scope of this document, but you can find more information on how to set it up [here](https://developer.bitcoin.org/examples/intro.html). - -## Additional reading - - - -- [Running a Stacks API node](https://docs.hiro.so/get-started/running-api-node) -- [Running a Stacks testnet node](running-testnet-node) - diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md b/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md deleted file mode 100644 index da01ce2ea1..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: Running a testnet node -description: Set up and run a testnet node with Docker -sidebar_position: 2 -tags: - - tutorial ---- - -## Introduction - -This procedure demonstrates how to run a local testnet node using Docker images. - -:::caution -This procedure focuses on Unix-like operating systems (Linux and MacOS). This procedure has not been tested on Windows. -::: - -## Prerequisites - -Running a node has no specialized hardware requirements. Users have been successful in running nodes on Raspberry Pi boards and other system-on-chip architectures. In order to complete this procedure, you must have the following software installed on the node host machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [curl](https://curl.se/download.html) -- [jq](https://stedolan.github.io/jq/download/) - -### Firewall configuration - -In order for the API node services to work correctly, you must configure any network firewall rules to allow traffic on the ports discussed in this section. The details of network and firewall configuration are highly specific to your machine and network, so a detailed example isn't provided. - -The following ports must open on the host machine: - -Ingress: - -- stacks-blockchain (open to `0.0.0.0/0`): - - `20443 TCP` - - `20444 TCP` - -Egress: - -- `18332` -- `18333` -- `20443-20444` - -These egress ports are for syncing stacks-blockchain and Bitcoin headers. If they're not open, the sync will fail. - -## Step 1: initial setup - -In order to run the testnet node, you must download the Docker images and create a directory structure to hold the persistent data from the services. Download and configure the Docker images with the following commands: - -```sh -docker pull blockstack/stacks-blockchain -``` - -Create a directory structure for the service data with the following command: - -```sh -mkdir -p ./stacks-node/persistent-data/stacks-blockchain/testnet && cd stacks-node -``` - -## Step 2: running Stacks blockchain - -Start the stacks-blockchain container with the following command: - -```sh -docker run -d --rm \ - --name stacks-blockchain \ - -v $(pwd)/persistent-data/stacks-blockchain/testnet:/root/stacks-node/data \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain \ -/bin/stacks-node testnet -``` - -You can verify the running stacks-blockchain container with the command: - -```sh -docker ps --filter name=stacks-blockchain -``` - -## Step 3: verifying the services - -:::info -The initial burnchain header sync can take several minutes, until this is done the following commands will not work -::: - -To verify the stacks-blockchain burnchain header sync progress: - -```sh -docker logs stacks-blockchain -``` - -The output should be similar to the following: - -``` -INFO [1626290705.886954] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.2% (8000 out of 2034380) -INFO [1626290748.103291] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.4% (10000 out of 2034380) -INFO [1626290776.956535] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.7% (12000 out of 2034380) -``` - -To verify the stacks-blockchain tip height is progressing use the following command: - -```sh -curl -sL localhost:20443/v2/info | jq -``` - -If the instance is running you should recieve terminal output similar to the following: - -```json -{ - "peer_version": 4207599105, - "pox_consensus": "12f7fa85e5099755a00b7eaecded1aa27af61748", - "burn_block_height": 2034380, - "stable_pox_consensus": "5cc4e0403ff6a1a4bd17dae9600c7c13d0b10bdf", - "stable_burn_block_height": 2034373, - "server_version": "stacks-node 2.0.11.2.0-rc1 (develop:7b6d3ee+, release build, linux [x86_64])", - "network_id": 2147483648, - "parent_network_id": 118034699, - "stacks_tip_height": 509, - "stacks_tip": "e0ee952e9891709d196080ca638ad07e6146d4c362e6afe4bb46f42d5fe584e8", - "stacks_tip_consensus_hash": "12f7fa85e5099755a00b7eaecded1aa27af61748", - "genesis_chainstate_hash": "74237aa39aa50a83de11a4f53e9d3bb7d43461d1de9873f402e5453ae60bc59b", - "unanchored_tip": "32bc86590f11504f17904ee7f5cb05bcf71a68a35f0bb3bc2d31aca726090842", - "unanchored_seq": 0, - "exit_at_block_height": null -} -``` - -## Stopping the testnet node - -Use the following commands to stop the local testnet node: - -```sh -docker stop stacks-blockchain -``` - -## Additional reading - - - -- [Running a Stacks API node](https://docs.hiro.so/get-started/running-api-node) -- [Running a Stacks mainnet node](running-mainnet-node) - diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md b/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md deleted file mode 100644 index 89af343dc6..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md +++ /dev/null @@ -1,506 +0,0 @@ ---- -title: Stacks Node Configuration -description: Configuration parameters and options for the stacks-node binary -sidebar_position: 6 ---- - -## Usage - -```bash -stacks-node sub-command [--subcommand-option ] -``` - -## Subcommands - -:::caution The `stacks-node` binary may have deprecated commands that are not documented on this page. Deprecated commands may be accessible until they are fully removed from the sources. ::: - -### mocknet - -Start a node based on a fast local setup emulating a burnchain. Ideal for smart contract development. - -Example: - -```bash -stacks-node mocknet -``` - -### krypton - -Start a node that will join and stream blocks from the public krypton regtest, powered by Blockstack via [Proof of Transfer](../understand-stacks#consensus-mechanism). - -Example: - -```bash -stacks-node krypton -``` - -### testnet - -Start a node that will join and stream blocks from the public testnet. - -Example: - -```bash -stacks-node testnet -``` - -### mainnet - -Start a node that joins and streams blocks from the public mainnet. - -Example: - -```bash -stacks-node mainnet -``` - -### start - -Start a node with a config of your own. Can be used for joining a network, starting a new chain, or replacing default values used by the `mocknet` or `testnet` subcommands. - -#### Arguments - -**--config**: relative or absolute path to the TOML config file. Required. - -Example: - -```bash -stacks-node start --config=/path/to/config.toml -``` - -See [Configuration File Options](#configuration-file-options) for more information. - -#### version - -Displays information about the current version and the release cycle. - -Example: - -```bash -stacks-node version -``` - -#### help - -Displays a help message. - -Example: - -```bash -stacks-node help -``` - -## Configuration File Options - -The TOML configuration file has multiple sections under which an option may be placed. - -To see a list of example configurations, [please see this page](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf). - -### Section: node - -Contains various configuration options pertaining to the stacks-node. - -Example: - -```toml -[node] -rpc_bind = "0.0.0.0:20443" -p2p_bind = "0.0.0.0:20444" -# Enter your private key here -seed = "replace-with-your-private-key" -miner = true -``` - -#### working_dir (optional) - -Absolute path to the directory which the stacks-node will use for storing various data. - -Example: - -```toml -working_dir = "/root/stacks-node" -``` - -#### rpc_bind - -Address and port stacks-node should bind to for RPC connections. - -Example: - -```toml -rpc_bind = "0.0.0.0:20443" -``` - -#### p2p_bind - -Address and port stacks-node should bind to for P2P connections. - -Example: - -```toml -p2p_bind = "0.0.0.0:20444" -``` - -#### data_url (optional) - -Address and port from which the stacks-node will be receiving incoming rpc connections. - -Example: - -```toml -data_url = "1.2.3.4:20443" -``` - -#### p2p_address (optional) - -Address and port from which the stacks-node will be receiving incoming p2p connections. - -Example: - -```toml -p2p_address = "1.2.3.4:20444" -``` - -#### bootstrap_node (optional) - -Public key, address, and port stacks-node should use to pull transaction data from when starting. - -Example: - -```toml -bootstrap_node = "047435c194e9b01b3d7f7a2802d6684a3af68d05bbf4ec8f17021980d777691f1d51651f7f1d566532c804da506c117bbf79ad62eea81213ba58f8808b4d9504ad@testnet.blockstack.org:20444" -``` - -#### wait_time_for_microblocks (optional) - -The amount of time (in milliseconds) that a node will wait before trying to mine a block, after catching up to the anchored chain tip. This gives the current leader time to broadcast microblocks that will get included in that mined block. - -Example: - -```toml -wait_time_for_microblocks = 15000 -``` - -#### seed (optional) - -The private key to use for mining. Only needed if `miner` is set to `true`. - -Example: - -```toml -seed = "replace-with-your-private-key" -``` - -#### local_peer_seed (optional) - -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. - -Example: - -```toml -local_peer_seed = "replace-with-your-private-key" -``` - -#### miner (optional) - -Determines whether the stacks-node is running a follower (`false`) or a miner (`true`). Defaults to `false` if omitted. - -Example: - -```toml -miner = true -``` - -#### mine_microblocks (optional) - -Determines whether the stacks-node will mine microblocks. Will only take effect if `miner` is set to `true`. - -Example: - -```toml -mine_microblocks = true -``` - -#### prometheus_bind (optional) - -Address and port stacks-node should open for Prometheus metrics collection. - -Example: - -```toml -prometheus_bind = "0.0.0.0:9153" -``` - -### Section: events_observer (optional) - -Contains options for watching events emitted by a local [stacks-blockchain-api](https://github.com/hirosystems/stacks-blockchain-api) service. - -:::info -This section can be repeated multiple times. -::: - -Example: - -```toml -[[events_observer]] -endpoint = "address-to-my-local.stacks-node-api.com:3700" -retry_count = 255 -events_keys = ["*"] -``` - -#### endpoint - -Address and port to a stacks-node-api to watch for events. - -Example: - -```toml -endpoint = "address-to-my-local.stacks-node-api.com:3700" -``` - -#### retry_count - -Number of times to retry sending events to the endpoint before failing. - -Example: - -```toml -retry_count = 255 -``` - -#### events_keys - -Event keys for which to watch. The emitted node events can be restricted by account, function name and event type. Asterix ("\*") can be used to emit all events. - -Examples: - -```toml -events_keys = ["*"] -``` - -```toml -events_keys = [ - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.store::print", - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.contract.ft-token", - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.contract.nft-token", - "stx" -] -``` - -### Section: connection_options (optional) - -Specifies configuration options for others connecting to the stacks node. - -Example: - -```toml -[connection_options] -public_ip_address = "1.2.3.4:20444" -download_interval = 60 -walk_interval = 30 -``` - -#### public_ip_address - -The advertised public IP of this stacks-node. - -Example: - -```toml -public_ip_address = "1.2.3.4:20444" -``` - -#### download_interval - -Time (in seconds) between attempts to download blocks. - -Example: - -```toml -download_interval = 60 -``` - -#### walk_interval - -Time (in seconds) between attempts to walk the neighborhood. - -Example: - -```toml -walk_interval = 30 -``` - -#### read_only_call_limit_read_length - -Total number of bytes allowed to be read by an individual read-only function call. - -Example: - -```toml -read_only_call_limit_read_length = 100000 -``` - -#### read_only_call_limit_read_count - -Total number of independent read operations permitted for an individual read-only function call. - -Example: - -```toml -read_only_call_limit_read_count = 30 -``` - -#### read_only_call_limit_runtime - -[Runtime cost](https://github.com/stacksgov/sips/blob/2d3fd9bf8da7a04f588d90ff6252173d7609d7bf/sips/sip-006/sip-006-runtime-cost-assessment.md#introduction) limit for an individual read-only function call. - -Example: - -```toml -read_only_call_limit_runtime = 1000000000 -``` - -### Section: burnchain - -This section contains configuration options pertaining to the blockchain the stacks-node binds to on the backend for proof-of-transfer (BTC). - -Example: - -```toml -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "your.bitcoind.node.org" -rpc_port = 8332 -peer_port = 8333 -``` - -#### chain - -The blockchain stacks-node binds to on the backend for proof-of-transfer. Only value supported: `"bitcoin"`. - -Example: - -```toml -chain = "bitcoin" -``` - -#### mode - -The profile or test phase of which to run stacks-node. Valid values are `"mocknet"`, `"helium"`, `"neon"`, `"argon"`, `"krypton"`, `"xenon"`. - -Example: - -```toml -mode = "xenon" -``` - -#### peer_host - -Domain name of the host running the backend Bitcoin blockchain. It's required to either run a personal Bitcoin node locally, or to use a publicly hosted Bitcoin node. - -Example: - -```toml -peer_host = "your.bitcoind.node.org" -``` - -#### rpc_port - -peer_host's port stacks-node will connect to for RPC connections. - -Example: - -```toml -rpc_port = 8332 -``` - -#### peer_port - -peer_host's port stacks-node will connect to for P2P connections. - -Example: - -```toml -peer_port = 8333 -``` - -#### burn_fee_cap (optional) - -Maximum amount (in Satoshis) of "burn commitment" to broadcast for the next block's leader election. - -Example: - -```toml -burn_fee_cap = 30000 -``` - -#### satoshis_per_byte (optional) - -Amount (in Satoshis) per [virtual byte](https://en.bitcoin.it/wiki/Weight_units). This is used to compute the transaction fees. - -Example: - -```toml -satoshis_per_byte = 50 -``` - -So total transaction cost would be `(estimated_tx_size * satoshis_per_byte) + burn_fee_cap`. - -#### commit_anchor_block_within (optional) - -Sets the time period (in milliseconds) for commitments. Only used when `mode` is set to `"helium"`. - -Example: - -```toml -commit_anchor_block_within = 10000 -``` - -### Section: ustx_balance (testnet/regtest only) - -This section contains configuration options pertaining to the genesis block allocation for an address in micro-STX. If a user changes these values, their node may be in conflict with other nodes on the network and find themselves unable to sync with other nodes. - -:::info -This section can repeat multiple times, and thus is in double-brackets. Each section can define only one address. This section is ignored if running a node on mainnet. -::: - -Example: - -```toml -[[ustx_balance]] -address = "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6" -amount = 10000000000000000 - -[[ustx_balance]] -address = "ST11NJTTKGVT6D1HY4NJRVQWMQM7TVAR091EJ8P2Y" -amount = 10000000000000000 - -[[ustx_balance]] -address = "ST1HB1T8WRNBYB0Y3T7WXZS38NKKPTBR3EG9EPJKR" -amount = 10000000000000000 - -[[ustx_balance]] -address = "STRYYQQ9M8KAF4NS7WNZQYY59X93XEKR31JP64CP" -amount = 10000000000000000 -``` - -#### address - -Address which maintains a micro-STX balance. - -Example: - -```toml -address = "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6" -``` - -#### amount - -The balance of micro-STX given to the address at the start of the node. - -Example: - -```toml -amount = 10000000000000000 -``` diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md b/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md deleted file mode 100644 index 094e3f03a1..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Verify Miner -description: Verify node is operating as miner -sidebar_position: 7 ---- - -You can verify that your node is operating as a miner by checking its log output to verify that it was able to find its Bitcoin UTXOs: - -```bash -$ head -n 100 /path/to/your/node/logs | grep -i utxo -INFO [1630127492.031042] [testnet/stacks-node/src/run_loop/neon.rs:146] [main] Miner node: checking UTXOs at address: -INFO [1630127492.062652] [testnet/stacks-node/src/run_loop/neon.rs:164] [main] UTXOs found - will run as a Miner node -``` \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json b/i18n/fr/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json deleted file mode 100644 index f5de305558..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Noteworthy Contracts", - "position": 4, - "link": { - "type": "generated-index", - "description": "Specific deployed Clarity Contracts worth mentioning." - } -} \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md b/i18n/fr/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md deleted file mode 100644 index 99723a9ff2..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md +++ /dev/null @@ -1,362 +0,0 @@ ---- -title: BNS Contract -description: The Blockchain Naming System. ---- - -![](/img/satoshi-btc.png) - -## Introduction - -The Blockchain Naming System (BNS) is implemented as a smart contract using Clarity. - -Below is a list of public and read-only functions as well as error codes that can be returned by those methods: -* [Public functions](#public-functions) -* [Read-only functions](#read-only-functions) -* [Error codes](#error-codes) - -## Public functions - - -### name-import - -#### Input: `(buff 20), (buff 48), principal, (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-import namespace name beneficiary zonefile-hash)` -#### Description: -Imports name to a revealed namespace. Each imported name is given both an owner and some off-chain state. - -### name-preorder - -#### Input: `(buff 20), uint` -#### Output: `(response uint int)` -#### Signature: `(name-preorder hashed-salted-fqn stx-to-burn)` -#### Description: -Preorders a name by telling all BNS nodes the salted hash of the BNS name. It pays the registration fee to the namespace owner's designated address. - -### name-register - -#### Input: `(buff 20), (buff 48), (buff 20), (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-register namespace name salt zonefile-hash)` -#### Description: -Reveals the salt and the name to all BNS nodes, and assigns the name an initial public key hash and zone file hash. - -### name-renewal - -#### Input: `(buff 20), (buff 48), uint, (optional principal), (optional (buff 20))` -#### Output: `(response bool int)` -#### Signature: `(name-renewal namespace name stx-to-burn new-owner zonefile-hash)` -#### Description: -Depending in the namespace rules, a name can expire. For example, names in the .id namespace expire after 2 years. You need to send a name renewal every so often to keep your name. - -You will pay the registration cost of your name to the namespace's designated burn address when you renew it. When a name expires, it enters a \"grace period\". The period is set to 5000 blocks (a month) but can be configured for each namespace. - -It will stop resolving in the grace period, and all of the above operations will cease to be honored by the BNS consensus rules. You may, however, send a NAME_RENEWAL during this grace period to preserve your name. After the grace period, everybody can register that name again. If your name is in a namespace where names do not expire, then you never need to use this transaction. -### name-revoke - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(name-revoke namespace name)` -#### Description: -Makes a name unresolvable. The BNS consensus rules stipulate that once a name is revoked, no one can change its public key hash or its zone file hash. The name's zone file hash is set to null to prevent it from resolving. You should only do this if your private key is compromised, or if you want to render your name unusable for whatever reason. - -### name-transfer - -#### Input: `(buff 20), (buff 48), principal, (optional (buff 20))` -#### Output: `(response bool int)` -#### Signature: `(name-transfer namespace name new-owner zonefile-hash)` -#### Description: -Changes the name's public key hash. You would send a name transfer transaction if you wanted to: -* Change your private key -* Send the name to someone else or -* Update your zone file - -When transferring a name, you have the option to also clear the name's zone file hash (i.e. set it to null). This is useful for when you send the name to someone else, so the recipient's name does not resolve to your zone file. - -### name-update - -#### Input: `(buff 20), (buff 48), (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-update namespace name zonefile-hash)` -#### Description: -Changes the name's zone file hash. You would send a name update transaction if you wanted to change the name's zone file contents. For example, you would do this if you want to deploy your own Gaia hub and want other people to read from it. - -### namespace-preorder - -#### Input: `(buff 20), uint` -#### Output: `(response uint int)` -#### Signature: `(namespace-preorder hashed-salted-namespace stx-to-burn)` -#### Description: -Registers the salted hash of the namespace with BNS nodes, and burns the requisite amount of cryptocurrency. Additionally, this step proves to the BNS nodes that user has honored the BNS consensus rules by including a recent consensus hash in the transaction. Returns pre-order's expiration date (in blocks). - -### namespace-ready - -#### Input: `(buff 20)` -#### Output: `(response bool int)` -#### Signature: `(namespace-ready namespace)` -#### Description: -Launches the namespace and makes it available to the public. Once a namespace is launched, anyone can register a name in it if they pay the appropriate amount of cryptocurrency. - -### namespace-reveal - -#### Input: `(buff 20), (buff 20), uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, principal` -#### Output: `(response bool int)` -#### Signature: `(namespace-reveal namespace namespace-salt p-func-base p-func-coeff p-func-b1 p-func-b2 p-func-b3 p-func-b4 p-func-b5 p-func-b6 p-func-b7 p-func-b8 p-func-b9 p-func-b10 p-func-b11 p-func-b12 p-func-b13 p-func-b14 p-func-b15 p-func-b16 p-func-non-alpha-discount p-func-no-vowel-discount lifetime namespace-import)` -#### Description: -Reveals the salt and the namespace ID (after a namespace preorder). It reveals how long names last in this namespace before they expire or must be renewed, and it sets a price function for the namespace that determines how cheap or expensive names its will be.All of the parameters prefixed by `p` make up the `price function`. These parameters govern the pricing and lifetime of names in the namespace. - -The rules for a namespace are as follows: - -* a name can fall into one of 16 buckets, measured by length. Bucket 16 incorporates all names at least 16 characters long. - -* the pricing structure applies a multiplicative penalty for having numeric characters, or punctuation characters. - -* the price of a name in a bucket is `((coeff) * (base) ^ (bucket exponent)) / ((numeric discount multiplier) * (punctuation discount multiplier))` - -Example: - -* base = 10 -* coeff = 2 -* nonalpha discount: 10 -* no-vowel discount: 10 -* buckets 1, 2: 9 -* buckets 3, 4, 5, 6: 8 -* buckets 7, 8, 9, 10, 11, 12, 13, 14: 7 -* buckets 15, 16+: - - -## Read-only functions - -### can-name-be-registered - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(can-name-be-registered namespace name)` -#### Description: -Returns true if the provided name can be registered. - -### can-namespace-be-registered - -#### Input: `(buff 20)` -#### Output: `(response bool UnknownType)` -#### Signature: `(can-namespace-be-registered namespace)` -#### Description: -Returns true if the provided namespace is available. - -### can-receive-name - -#### Input: `principal` -#### Output: `(response bool int)` -#### Signature: `(can-receive-name owner)` -#### Description: -Returns true if the provided name can be received. That is, if it is not curretly owned, a previous lease is expired, and the name wasn't revoked. - -### get-name-price - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response uint int)` -#### Signature: `(get-name-price namespace name)` -#### Description: -Gets the price for a name. - -### get-namespace-price - -#### Input: `(buff 20)` -#### Output: `(response uint int)` -#### Signature: `(get-namespace-price namespace)` -#### Description: -Gets the price for a namespace. - -### get-namespace-properties - -#### Input: `(buff 20)` -#### Output: `(response (tuple (namespace (buff 20)) (properties (tuple (can-update-price-function bool) (launched-at (optional uint)) (lifetime uint) (namespace-import principal) (price-function (tuple (base uint) (buckets (list 16 uint)) (coeff uint) (no-vowel-discount uint) (nonalpha-discount uint))) (revealed-at uint)))) int)` -#### Signature: `(get-namespace-properties namespace)` -#### Description: -Get namespace properties. - -### is-name-lease-expired - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(is-name-lease-expired namespace name)` -#### Description: -Return true if the provided name lease is expired. - -### name-resolve - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response (tuple (lease-ending-at (optional uint)) (lease-started-at uint) (owner principal) (zonefile-hash (buff 20))) int)` -#### Signature: `(name-resolve namespace name)` -#### Description: -Get name registration details. - -### resolve-principal - -#### Input: `principal` -#### Output: `(response (tuple (name (buff 48)) (namespace (buff 20))) (tuple (code int) (name (optional (tuple (name (buff 48)) (namespace (buff 20)))))))` -#### Signature: `(resolve-principal owner)` -#### Description: -Returns the registered name that a principal owns if there is one. A principal can only own one name at a time. - -## Error codes - -### ERR_INSUFFICIENT_FUNDS -#### type: `int` -#### value: `4001` - -### ERR_NAMESPACE_ALREADY_EXISTS -#### type: `int` -#### value: `1006` - -### ERR_NAMESPACE_ALREADY_LAUNCHED -#### type: `int` -#### value: `1014` - -### ERR_NAMESPACE_BLANK -#### type: `int` -#### value: `1013` - -### ERR_NAMESPACE_CHARSET_INVALID -#### type: `int` -#### value: `1016` - -### ERR_NAMESPACE_HASH_MALFORMED -#### type: `int` -#### value: `1015` - -### ERR_NAMESPACE_NOT_FOUND -#### type: `int` -#### value: `1005` - -### ERR_NAMESPACE_NOT_LAUNCHED -#### type: `int` -#### value: `1007` - -### ERR_NAMESPACE_OPERATION_UNAUTHORIZED -#### type: `int` -#### value: `1011` - -### ERR_NAMESPACE_PREORDER_ALREADY_EXISTS -#### type: `int` -#### value: `1003` - -### ERR_NAMESPACE_PREORDER_CLAIMABILITY_EXPIRED -#### type: `int` -#### value: `1009` - -### ERR_NAMESPACE_PREORDER_EXPIRED -#### type: `int` -#### value: `1002` - -### ERR_NAMESPACE_PREORDER_LAUNCHABILITY_EXPIRED -#### type: `int` -#### value: `1010` - -### ERR_NAMESPACE_PREORDER_NOT_FOUND -#### type: `int` -#### value: `1001` - -### ERR_NAMESPACE_PRICE_FUNCTION_INVALID -#### type: `int` -#### value: `1008` - -### ERR_NAMESPACE_STX_BURNT_INSUFFICIENT -#### type: `int` -#### value: `1012` - -### ERR_NAMESPACE_UNAVAILABLE -#### type: `int` -#### value: `1004` - -### ERR_NAME_ALREADY_CLAIMED -#### type: `int` -#### value: `2011` - -### ERR_NAME_BLANK -#### type: `int` -#### value: `2010` - -### ERR_NAME_CHARSET_INVALID -#### type: `int` -#### value: `2022` - -### ERR_NAME_CLAIMABILITY_EXPIRED -#### type: `int` -#### value: `2012` - -### ERR_NAME_COULD_NOT_BE_MINTED -#### type: `int` -#### value: `2020` - -### ERR_NAME_COULD_NOT_BE_TRANSFERED -#### type: `int` -#### value: `2021` - -### ERR_NAME_EXPIRED -#### type: `int` -#### value: `2008` - -### ERR_NAME_GRACE_PERIOD -#### type: `int` -#### value: `2009` - -### ERR_NAME_HASH_MALFORMED -#### type: `int` -#### value: `2017` - -### ERR_NAME_NOT_FOUND -#### type: `int` -#### value: `2013` - -### ERR_NAME_NOT_RESOLVABLE -#### type: `int` -#### value: `2019` - -### ERR_NAME_OPERATION_UNAUTHORIZED -#### type: `int` -#### value: `2006` - -### ERR_NAME_PREORDERED_BEFORE_NAMESPACE_LAUNCH -#### type: `int` -#### value: `2018` - -### ERR_NAME_PREORDER_ALREADY_EXISTS -#### type: `int` -#### value: `2016` - -### ERR_NAME_PREORDER_EXPIRED -#### type: `int` -#### value: `2002` - -### ERR_NAME_PREORDER_FUNDS_INSUFFICIENT -#### type: `int` -#### value: `2003` - -### ERR_NAME_PREORDER_NOT_FOUND -#### type: `int` -#### value: `2001` - -### ERR_NAME_REVOKED -#### type: `int` -#### value: `2014` - -### ERR_NAME_STX_BURNT_INSUFFICIENT -#### type: `int` -#### value: `2007` - -### ERR_NAME_TRANSFER_FAILED -#### type: `int` -#### value: `2015` - -### ERR_NAME_UNAVAILABLE -#### type: `int` -#### value: `2004` - -### ERR_PANIC -#### type: `int` -#### value: `0` - -### ERR_PRINCIPAL_ALREADY_ASSOCIATED -#### type: `int` -#### value: `3001` diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md b/i18n/fr/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md deleted file mode 100644 index ce1b1ba859..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -title: Stacking Contract -description: See a detailed list of all functions and error codes of the Stacking contract. ---- - -## Introduction - -Stacking is implemented as a smart contract using Clarity. You can always find the Stacking contract identifier using the Stacks Blockchain API [`v2/pox` endpoint](https://docs.hiro.so/api#operation/get_pox_info). - -Below is a list of public and read-only functions as well as error codes that can be returned by those methods: - -* [Public functions](#public-functions) -* [Read-only functions](#read-only-functions) -* [Error codes](#error-codes) - -## Public functions - -### allow-contract-caller -#### input: `principal, (optional uint)` -#### output: `(response bool int)` -#### signature: `(allow-contract-caller caller until-burn-ht)` -#### description: -Give a contract-caller authorization to call stacking methods. Normally, stacking methods may only be invoked by _direct_ transactions (i.e., the `tx-sender` issues a direct `contract-call` to the stacking methods). - -By issuing an allowance, the tx-sender may call through the allowed contract. - -### delegate-stack-stx -#### input: `principal, uint, (tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint` -#### output: `(response (tuple (lock-amount uint) (stacker principal) (unlock-burn-height uint)) int)` -#### signature: `(delegate-stack-stx stacker amount-ustx pox-addr start-burn-ht lock-period)` -#### description: -As a delegate, stack the given principal's STX using `partial-stacked-by-cycle`. - -Once the delegate has stacked > minimum, the delegate should call `stack-aggregation-commit`. - -### delegate-stx -#### input: `uint, principal, (optional uint), (optional (tuple (hashbytes (buff 20)) (version (buff 1))))` -#### output: `(response bool int)` -#### signature: `(delegate-stx amount-ustx delegate-to until-burn-ht pox-addr)` -#### description: -Delegate to `delegate-to` the ability to stack from a given address. - -This method _does not_ lock the funds, rather, it allows the delegate to issue the stacking lock. - -The caller specifies: - -* amount-ustx: the total amount of ustx the delegate may be allowed to lock -* until-burn-ht: an optional burn height at which this delegation expiration -* pox-addr: an optional p2pkh or p2sh address to which any rewards *must* be sent - -### disallow-contract-caller -#### input: `principal` -#### output: `(response bool int)` -#### signature: `(disallow-contract-caller caller)` -#### description: -Revokes authorization from a contract to invoke stacking methods through contract-calls - -### reject-pox -#### input: -#### output: `(response bool int)` -#### signature: `(reject-pox)` -#### description: -Reject Stacking for this reward cycle. - -`tx-sender` votes all its uSTX for rejection. - -Note that unlike Stacking, rejecting PoX does not lock the tx-sender's tokens: PoX rejection acts like a coin vote. - -### revoke-delegate-stx -#### input: -#### output: `(response bool int)` -#### signature: `(revoke-delegate-stx)` -#### description: -Revoke a Stacking delegate relationship. A particular Stacker may only have one delegate, so this method does not take any parameters, and just revokes the Stacker's current delegate (if one exists). - -### stack-aggregation-commit -#### input: `(tuple (hashbytes (buff 20)) (version (buff 1))), uint` -#### output: `(response bool int)` -#### signature: `(stack-aggregation-commit pox-addr reward-cycle)` -#### description: -Commit partially stacked STX. - -This allows a stacker/delegate to lock fewer STX than the minimal threshold in multiple transactions, - -so long as: - -1. The pox-addr is the same. -2. This \"commit\" transaction is called _before_ the PoX anchor block. - -This ensures that each entry in the reward set returned to the stacks-node is greater than the threshold, - - but does not require it be all locked up within a single transaction - -### stack-stx -#### input: `uint, (tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint` -#### output: `(response (tuple (lock-amount uint) (stacker principal) (unlock-burn-height uint)) int)` -#### signature: `(stack-stx amount-ustx pox-addr start-burn-ht lock-period)` -#### description: -Lock up some uSTX for stacking! Note that the given amount here is in micro-STX (uSTX). - -The STX will be locked for the given number of reward cycles (lock-period). - -This is the self-service interface. tx-sender will be the Stacker. - -* The given stacker cannot currently be stacking. -* You will need the minimum uSTX threshold. This isn't determined until the reward cycle begins, but this method still requires stacking over the _absolute minimum_ amount, which can be obtained by calling `get-stacking-minimum`. -* The pox-addr argument must represent a valid reward address. Right now, this must be a Bitcoin p2pkh or p2sh address. It cannot be a native Segwit address, but it may be a p2wpkh-p2sh or p2wsh-p2sh address. - -The tokens will unlock and be returned to the Stacker (tx-sender) automatically. - -## Read-only functions - -### can-stack-stx -#### input: `(tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint, uint` -#### output: `(response bool int)` -#### signature: `(can-stack-stx pox-addr amount-ustx first-reward-cycle num-cycles)` -#### description: -Evaluate if a participant can stack an amount of STX for a given period. - -### get-pox-info -#### input: -#### output: `(response (tuple (current-rejection-votes uint) (first-burnchain-block-height uint) (min-amount-ustx uint) (prepare-cycle-length uint) (rejection-fraction uint) (reward-cycle-id uint) (reward-cycle-length uint) (total-liquid-supply-ustx uint)) UnknownType)` -#### signature: `(get-pox-info)` -#### description: -Returns information about PoX status. - -### get-pox-rejection -#### input: `principal, uint` -#### output: `(optional (tuple (amount uint)))` -#### signature: `(get-pox-rejection stacker reward-cycle)` -#### description: -Returns the amount of uSTX that a given principal used to reject a PoX cycle. - -### get-stacker-info -#### input: `principal` -#### output: `(optional (tuple (amount-ustx uint) (first-reward-cycle uint) (lock-period uint) (pox-addr (tuple (hashbytes (buff 20)) (version (buff 1))))))` -#### signature: `(get-stacker-info stacker)` -#### description: -Returns the _current_ stacking information for `stacker. If the information is expired, or if there's never been such a stacker, then returns none. - -### get-stacking-minimum -#### input: -#### output: `uint` -#### signature: `(get-stacking-minimum)` -#### description: -Returns the absolute minimum amount that could be validly Stacked (the threshold to Stack in a given reward cycle may be higher than this - -### get-total-ustx-stacked -#### input: `uint` -#### output: `uint` -#### signature: `(get-total-ustx-stacked reward-cycle)` -#### description: -Returns the amount of currently participating uSTX in the given cycle. - -### is-pox-active -#### input: `uint` -#### output: `bool` -#### signature: `(is-pox-active reward-cycle)` -#### description: -Returns whether or not PoX has been rejected at a given PoX cycle. -## Error codes - -### ERR_DELEGATION_EXPIRES_DURING_LOCK -#### type: `int` -#### value: `21` - -### ERR_DELEGATION_POX_ADDR_REQUIRED -#### type: `int` -#### value: `23` - -### ERR_DELEGATION_TOO_MUCH_LOCKED -#### type: `int` -#### value: `22` - -### ERR_INVALID_START_BURN_HEIGHT -#### type: `int` -#### value: `24` - -### ERR_NOT_ALLOWED -#### type: `int` -#### value: `19` - -### ERR_STACKING_ALREADY_DELEGATED -#### type: `int` -#### value: `20` - -### ERR_STACKING_ALREADY_REJECTED -#### type: `int` -#### value: `17` - -### ERR_STACKING_ALREADY_STACKED -#### type: `int` -#### value: `3` - -### ERR_STACKING_EXPIRED -#### type: `int` -#### value: `5` - -### ERR_STACKING_INSUFFICIENT_FUNDS -#### type: `int` -#### value: `1` - -### ERR_STACKING_INVALID_AMOUNT -#### type: `int` -#### value: `18` - -### ERR_STACKING_INVALID_LOCK_PERIOD -#### type: `int` -#### value: `2` - -### ERR_STACKING_INVALID_POX_ADDRESS -#### type: `int` -#### value: `13` - -### ERR_STACKING_NO_SUCH_PRINCIPAL -#### type: `int` -#### value: `4` - -### ERR_STACKING_PERMISSION_DENIED -#### type: `int` -#### value: `9` - -### ERR_STACKING_POX_ADDRESS_IN_USE -#### type: `int` -#### value: `12` - -### ERR_STACKING_STX_LOCKED -#### type: `int` -#### value: `6` - -### ERR_STACKING_THRESHOLD_NOT_MET -#### type: `int` -#### value: `11` - -### ERR_STACKING_UNREACHABLE -#### type: `int` -#### value: `255` \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md b/i18n/fr/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md deleted file mode 100644 index 5f38edfb57..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: xBTC -description: Wrapped BTC on Stacks ---- - -![](/img/xbtc-icon.webp) - -## Introduction - -[Wrapped.com](https://www.wrapped.com) has brought Bitcoin (xBTC) to the Stacks ecosystem. - -xBTC is backed 1:1 by Bitcoin and empowers developers to expand the Bitcoin DeFi ecosystem. - -The reserves are publicly visible [here](https://open.wrapped.com/reserves/). - -## Contract - -[SP3DX3H4FEYZJZ586MFBS25ZW3HZDMEW92260R2PR.Wrapped-Bitcoin](https://explorer.stacks.co/txid/SP3DX3H4FEYZJZ586MFBS25ZW3HZDMEW92260R2PR.Wrapped-Bitcoin?chain=mainnet) - -## Examples of uses - -[Friedger Mining Pool](https://pool.friedger.de/) currrently supports Stacking rewards payments in xBTC (optional). - - -## More information - -* [Blog post announcement](https://www.stacks.co/blog/tokensoft-wrapped-fundamental-bitcoin-defi-building-blocks-xbtc) by Muneeb Ali - -* Video: [Why xBTC is Important For Bitcoin to Grow](https://www.youtube.com/watch?v=xIoadrfSdi4) \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/references/_category_.json b/i18n/fr/docusaurus-plugin-content-docs/current/references/_category_.json deleted file mode 100644 index 3805ab0783..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/references/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "References", - "position": 9, - "link": { - "type": "generated-index", - "description": "Stacks references." - } -} \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/references/glossary.md b/i18n/fr/docusaurus-plugin-content-docs/current/references/glossary.md deleted file mode 100644 index f97908371a..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/references/glossary.md +++ /dev/null @@ -1,215 +0,0 @@ ---- -title: Glossary -description: A comprehensive list of terms used within the ecosystem. ---- - -A comprehensive list of terms used within the ecosystem. - -#### App Review -An incentive mechanism for application developers in the early stage (first four years) of the ecosystem and helps with bootstrapping the two-sided market. - -#### Atlas -A peer network provide a global index for discovery. - -#### Bitcoin (BTC) address -A string of letters and numbers. `3E53XjqK4Cxt71BGeP2VhpcotM8LZ853C8` Sharing this address allows anyone to send Bitcoin to the address. - -#### block -A discrete group of records written to a blockchain that can effectively be identified and referenced by the use of headers that contain a digital fingerprint of the records each block contains. - -#### blockchain -A database created and shared by the members of a peer-to-peer computer network which each member of that network can independently trust due to the rules governing the database’s creation. A blockchain can therefore be used to replace centralized databases. - -#### Blockchain Name System (BNS) -Replacement for DNS. More info [here](../noteworthy-contracts/bns-contract). - -#### Blockstack Browser -A deprecated application for accessing identity and storage. - -#### Blockstack Owner Address - -Looks like a bitcoin address but starts with `ID` for example: `ID-1J3PUxY5uDShUnHRrMyU6yKtoHEUPhKULs` - -#### Burning -Burning a token means that the token is transferred to an address that is a black hole—one that is not owned by any entity and for which guessing the applicable private key is effectively impossible based on known mathematical principles. This effectively destroys the token by making it unavailable for future use and decreases the total number of tokens available from that point forward. - -#### consensus hash -A consensus hash is a cryptographic hash that each node calculates at each block. It is derived from the accepted state transitions in the last-processed block and a geometric series of prior-calculated consensus hashes. - -#### Consensus rules -"The rules governing the creation of new valid records in a blockchain database and the mining algorithms used for this purpose. - -#### control plane -The part of a network that carries signaling traffic and is responsible for routing. Control packets originate from or are destined for a router. Functions of the control plane include system configuration and management. - -#### core node -A server that runs Stacks Blockchain services. - -#### crypto-asset -A digital asset which utilises cryptography, peer-to-peer networking and a public ledger to regulate the creation of new units, verify transactions and secure the transactions without the intervention of any middleman. - -#### cryptography -The practise and study of encryption and decryption - encoding data so that it can only be decoded by specific individuals. A system for encrypting and decrypting data is a cryptosystem. - -#### DAO -See Decentralized Autonomous Organization. - -#### decentralized application (DApp) -A DApp is a service that enables direct interaction between end users and providers (e.g. connecting buyers and sellers in some marketplace, owners and stores in file storage). A term coined by Ethereum. See their glossary: http://ethdocs.org/en/latest/glossary.html#dapp" - -#### Decentralized Autonomous Organization -A type of contract or suite of contracts on the blockchain that is intented to codify, enforce or automate the processes of an organization. - -#### digital asset -Also referred to as a crypto-asset. Any set of unique digital information—including, for example, programs, decentralized programs, isolated chunks of programming code, collections of data, e-mail or web addresses or cryptocurrency tokens—that is capable of being stored and uniquely tracked on a computer network such as the Stacks network and over which a user can maintain control through that network. - -#### digital fingerprint -A digital fingerprint is a unique number of a fixed length that can be produced by running any set of digital information through something called a cryptographic hash function. Each set of digital information (including a digital asset, and the digital record of any network operation on that digital asset) should (as a practical matter) have a unique digital fingerprint, which allows that set of digital information to be identified. However, it is almost impossible to recreate a digital asset from its digital fingerprint. The Blockstack network uses industry-standard algorithms such as SHA-256 to create digital fingerprints. - -#### digital signature -A digital signature is a sequence of digital information combining a user’s private key and any digital information that the user wishes to sign. Any other party can use the user’s paired public key to verify that the digital signature is authentic, i.e. that the public key was generated from a particular piece of digital information and the user’s private key. - -#### distributed hash tables (DHT) -A form of network used to store some content in the form of key/value pairs. ... This experimental project try to avoid keeping all the blockchain, but instead prefers to store it in a DHT. - -#### ephemeral key -A cryptographic key is called ephemeral if it is generated for each execution of a key establishment process. - -#### fork -The term fork is used to refer both to any situation where there are two or more competing versions of a blockchain on a network (a situation that may arise and resolve itself in the ordinary course of network operations due to lags in communication between core nodes) and any software update that is proposed for adoption by the core nodes of a blockchain network that may result in a persistent fork on the network, with core nodes that adopt the update recognizing one version of the blockchain and those which do not recognizing another. - -#### Gaia -Decentralized storage architecture for off-chain data. More info [here](../gaia). - -#### genesis block -The genesis block is the first block of the Stacks blockchain, which will create the initial 1.32 billion Stacks Tokens. - -#### id.blockstack -An identifier in the Blockstack, for example meepers.id.blockstack. This is your name & identity that is registered in the .id namespace on Blockstack. Your personal data and storage are built around this ID. Apps that want to access your data use your permission and identity to find it. An id is usually a shorthand for a longer, hash ID string, for example ID-1Fj9kkw15P51Fj9kkw15P5xJmyefWhLKrQMKNPREfaqsJ" - -#### identity - -A way to identify a person or an organization on the Stacks network. An identity is unique, both `meepers.id.blockstack` or `chad.id` are examples of IDs. - -#### identity management (IDM) -Identity management, also known as identity and access management is, in computer security, the security and business discipline that enables the right individuals to access the right resources at the right times and for the right reason". - -#### know your customer (KYC) -Or KYC, is a popular term used in the banking or financial field. KYC is a process where financial institutions, insurers and other companies obtain information about the identity and address of the customers as part of risk management. - -#### light clients -Clients that can independently validate the existence of transactions by downloading only block headers and not the entire blockchain. - -#### magic recovery code - -A long encrypted string, for example: `36mWivFdy0YPH2z31EflpQz/Y0UMrOrJ++lH=0EI7c3mop2JuRBm5WXxSTazJsUjOA...` Do not share the QR code that accompanied your recovery code either. This is a QR code: - -![](/img/qr-code.png) - -#### mesh network -A local network topology in which the infrastructure nodes (i.e. bridges, switches, and other infrastructure devices) connect directly, dynamically and non-hierarchically to as many other nodes as possible and cooperate with one another to efficiently route data from/to clients. - -#### mining -Mining generally refers to the process of performing certain functions for a network such as adding new records to a blockchain in exchange for mining rewards; it may also refer to other mechanisms whereby rewards (usually in the form of cryptocurrency) are provided for performing other tasks helpful to the network. - -#### mining power -A miner’s (or group of miners’) mining power is equal to the probability it will be selected to write a new block to the blockchain. Depending on the mechanism for mining, this is usually related to the overall share of computing power or cryptoassets the miner or miners possess relative to all miners for that blockchain. - -#### mining rewards -Mining rewards are newly issued tokens received by miners in exchange for adding new records to the blockchain or other activities beneficial to the network. - -#### name -An identifier or name. Names are a type of digital asset in the Stacks network. If you have signed into the Stacks Wallet, you might have created a name. If an application developer registered an application within Stacks, then they registered a name. Public Stacking pools can also have a name. - -#### network operation -A network operation is any change to the information about a digital asset (or smart contract) stored on a blockchain, including, for example, a change in the digital asset’s owner, or a change in the location at which it is stored on the network. How and when these network operations are performed for each digital asset is governed, on the Blockstack network, either by the Stacks Node software or a smart contract. - -#### NFT -Non fungible token. - -#### private key - -Private keys matches a corresponding public key. A public key also looks like a string of letters and numbers: - -![](/img/private.png) - -The exact format of the public and private key depend on the software you use to create them. - -#### proof-of-burn mining -The consensus algorithm used in the Stacks blockchain where miners destroy a proof-of-work-based cryptocurrency (currently Bitcoin) to get tokens; this enables the functionality where nodes can select between conflicting blockchain forks, as the blockchain fork with the most amount of cryptocurrency burned is considered to be the correct fork. - -#### proof-of-work -A proof-of-work system or proof-of-work mining is a mining mechanism where miners must expend computing power to solve complicated cryptographic puzzles, and prove that they have done so by writing the solution to the blockchain, in order to be allowed to add blocks to a blockchain. This is the mining system used, for example, by Bitcoin. - -#### public key -Public and private key pair comprise of two uniquely related cryptographic keys. It looks like a long random string of letters and numbers: `3048 0241 00C9 18FA CF8D EB2D EFD5 FD37 89B9 E069 EA97 FC20 …` The exact format of the public and private key depend on the software you use to create them. - -#### Public Key Infrastructure (PKI) -A system which returns a cryptographic public key associated with a name. - -#### replicated state machines (RSMs) -This is a model for reasoning about distributed computer programs -- any program (plus it's input) can be represented as a state machine, and when trying to get a distributed set of servers to agree on the output of an algorithm, you can model that process as N different state machines" - -#### Secret recovery Key, -Used to access an identity on the Stacks blockchain. A 24-word sequence of words for example: `applied binge crisp pictorial fiery` `dancing agreeable frogs light finish ping apple` - -#### seed phrase - -Used to access Stacks Wallet software. The seed phrase consists of 24 words in a sequence. Both the word *and its position the sequence* are important. Write down your seed phrase and store it in a secure location such as a safe deposit box. When you write the seed phrase down, include its position, for example,`1-frog, 2-horse, 3-building` and so on until you reach a final position `24-ocean`. -#### smart contract -A smart contract is a computer program written to a blockchain such as the Stacks blockchain by developers. This computer program defines the various network operations that can be performed on the digital assets on the blockchain, the computations that can be performed using the smart contract, along with defining various important properties of the respective digital assets like ownership rights and the cost in fuel required to register the digital assets. - -#### soft fork -A soft fork is a proposed update to the software governing the network that results in a post-update network that is compatible with the network as it existed prior to the update, because it restricts the network operations that can be performed after the update. - -#### Stacks (STX) address - - A STX address is a string of letters and numbers starting with an `SP` or `SM`, for example: `SM3KJBA4RZ7Z20KD2HBXNSXVPCR1D3CRAV6Q05MKT` If you created a software-only wallet with the Stacks Wallet software, the wallet has a single STX address which is also sometimes called the *wallet address*. You access a software wallet with a *seed phrase*. " - -#### Stacks blockchain -The Stacks blockchain is the custom blockchain being developed for use by the Stacks network that will use the Stacks token as its native currency and which will include the genesis block and subsequent blocks created by the mining activities described in the Stacks Network—Development of the Stacks network. - -#### Stacks Explorer -An application that allow you to view and search transactions in the blockchain. For example, https://explorer.stacks.co. - -#### Stacks node -A complete version of our open-source software available on Github at https://github.com/stacks-network/stacks-blockchain/ that governs the creation of the blockchain, the smart contracts that may be written to our blockchain, and other systems that make up the Stacks network, when run on the systems and devices of our users and developers. - -#### Stacks wallet -An application for accessing assets, identity and storage. Examples are the [Hiro Wallet](https://www.hiro.so/wallet), [xverse](https://www.xverse.app/) and [dcent](https://dcentwallet.com/). More information and example [here](../services-using-stacks/wallets). - -#### storage hub -A Gaia instance run by a hub provider or software. A Gaia hub stores data in a separate, addressed location. - -#### storage provider -A third-party company cloud or software provider that hosts one or more Gaia storage hubs. - -#### transaction -A transaction is a unit of work within a block. - -#### transaction fee -Fees paid by participants in a transaction to miners. - -#### two-sided market problem -Economic platforms having two distinct user groups that provide each other with network benefits. The Stacks platform is a classic two-sided market. - -#### username -A shorthand name for your id.blockstack. - -#### virtual blockchain -A layer that sits on top of a blockchain that introduces new functionality and operations without requiring changes to the underlying blockchain. - -#### wallet address -A wallet address is the form in which a public key can be presented and recorded on a blockchain. Wallet addresses are therefore used to assign the ownership of digital assets on the Blockstack network. - -#### watch-only wallet -A wallet without send and receive ability. You can view only balances and transaction history. - -#### web of trust mining -Web-of-trust mining provides incentive mechanisms for users where an initial trusted-set of unique users is curated in the genesis block and, in the future, the initial set of users can expand the web-of-trust after the network goes live. - -#### web3 -The exact definition is still under discussion, but it general refers to the 3rd generation of the web that is based on blockchain technology and incorporates decentralized and token-based economics. - -#### zone file -A Domain Name System (DNS) zone file is a text file that describes a DNS zone. A DNS zone is a subset, often a single domain, of the hierarchical domain name structure of the DNS. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/references/nft.md b/i18n/fr/docusaurus-plugin-content-docs/current/references/nft.md deleted file mode 100644 index 033ee0a71a..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/references/nft.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: NFTs on Stacks -description: A list of sites that operate NFTs on Stacks ---- - -List of sites that operate NFTS on Stacks on alphabetical order. - -### [Byzantion](https://byzantion.xyz/) - -![website-screenshot](/img/sh_nft_byzantion.png) - -### [Gamma](https://gamma.io/) -![website-screenshot](/img/sh_nft_gamma.png) - -### [Megapont](https://www.megapont.com/) - -![website-screenshot](/img/sh_nft_megapont.png) - -### [StacksArt](https://www.stacksart.com/) - -![website-screenshot](/img/sh_nft_stacksart.png) - diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md b/i18n/fr/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md deleted file mode 100644 index dc6e507d5e..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Stacks info sites -description: A list of sites on alphabetical order that display status and stats of the Stacks network. ---- - -### [Haystack](https://haystack.tools/mempool) - -![website-screenshot](/img/sh_haystacks.png) - -### [Stacksdata](https://stacksdata.info/) - -![website-screenshot](/img/sh_stacksdata.png) - -### [Stacksonchain](https://stacksonchain.com) - -![website-screenshot](/img/sh_stacksonchain.png) - -### [Status Hiro](https://status.hiro.so/) - -![website-screenshot](/img/sh_statushiro.png) - -### [Stxstats](https://www.stxstats.co/) - -![website-screenshot](/img/sh_stxstats.png) - -### [Novuminsights](https://stacks.novuminsights.com/health) - -![website-screenshot](/img/sh_novuminsights.png) - -### [Onstacks](https://app.onstacks.com/) - -![website-screenshot](/img/sh_onstacks.png) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json b/i18n/fr/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json deleted file mode 100644 index ebd63f366c..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Services using Stacks", - "position": 8, - "link": { - "type": "generated-index", - "description": "An 'always incomplete' list of services that use Stacks." - } -} \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md b/i18n/fr/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md deleted file mode 100644 index 51defacba7..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: DeFi -description: De-Fi sites on Stacks -sidebar_position: 2 ---- - -They are multiple De-Fi sites that operate on the Stacks blockchain. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Alex - -[Alex](https://app.alexlab.co) ![](/img/sh_alex.png) - -## Arkadiko - -[Arkadiko](https://arkadiko.finance/) ![](/img/sh_arkadiko.png) - -## Catamaran Swaps - -[Catamaran Swaps](https://www.catamaranswaps.org/) allows trustless exchange of digital assets. - -![](/img/sh_catamaran.png) - -## Lnswap - -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange - -![](/img/sh_lnswap.png) - -## Neoswap - -[Neoswap](https://neoswap.party) - -![](/img/sh_neoswap.png) - -## Stackswap - -[Stackswap](https://app.stackswap.org/v2) - -![](/img/sh_stackswap.png) - diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/services-using-stacks/more.md b/i18n/fr/docusaurus-plugin-content-docs/current/services-using-stacks/more.md deleted file mode 100644 index df0b3e2254..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/services-using-stacks/more.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: More -description: More services built on Stacks. -sidebar_position: 5 ---- - -List of sites on alphabetical order added by the community. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Citycoins - -[Citycoins](https://citycoins.co) - -![](/img/sh_citycoins.png) - -## Sigle - -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. - -![](/img/sh_sigle.png) \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md b/i18n/fr/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md deleted file mode 100644 index bfa0505dc9..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: NFTs -description: NFTs on Stacks -sidebar_position: 3 ---- - -List of sites that operate NFTS on Stacks on alphabetical order. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -### [Byzantion](https://byzantion.xyz/) - -![website-screenshot](/img/sh_nft_byzantion.png) - -### [Gamma](https://gamma.io/) -![website-screenshot](/img/sh_nft_gamma.png) - -### [Megapont](https://www.megapont.com/) - -![website-screenshot](/img/sh_nft_megapont.png) - -### [StacksArt](https://www.stacksart.com/) - -![website-screenshot](/img/sh_nft_stacksart.png) - -### [Superfandom](https://superfandom.io/) - -![website-screenshot](/img/sh_superfandom.png) \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/services-using-stacks/other.md b/i18n/fr/docusaurus-plugin-content-docs/current/services-using-stacks/other.md deleted file mode 100644 index 199fc41da5..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/services-using-stacks/other.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Other Stacks sites -description: A list of sites on alphabetical order built on Stacks. -sidebar_position: 4 ---- - -List of sites on alphabetical order added by the community. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Alex -[Alex](https://app.alexlab.co) - -## Sigle - -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md b/i18n/fr/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md deleted file mode 100644 index 35ced8dac6..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Stacks info sites -description: Status and stats of the Stacks network. -sidebar_position: 1 ---- - -A list of sites on alphabetical order that display status and stats of the Stacks network. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -### [Haystack](https://haystack.tools/mempool) - -![website-screenshot](/img/sh_haystacks.png) - -### [Stacksdata](https://stacksdata.info/) - -![website-screenshot](/img/sh_stacksdata.png) - -### [Stacksonchain](https://stacksonchain.com) - -![website-screenshot](/img/sh_stacksonchain.png) - -### [Status Hiro](https://status.hiro.so/) - -![website-screenshot](/img/sh_statushiro.png) - -### [Stxstats](https://www.stxstats.co/) - -![website-screenshot](/img/sh_stxstats.png) - -### [Novuminsights](https://stacks.novuminsights.com/health) - -![website-screenshot](/img/sh_novuminsights.png) - -### [Onstacks](https://app.onstacks.com/) - -![website-screenshot](/img/sh_onstacks.png) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md b/i18n/fr/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md deleted file mode 100644 index d4b4cbf18c..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Swaps -description: A list of sites that allow Swaps -sidebar_position: 2 ---- - -They are multiple sites that allow you to make swaps using the Stacks blockchain. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Catamaran Swaps - -[Catamaran Swaps](https://www.catamaranswaps.org/) allows trustless exchange of digital assets. - -![](/img/sh_catamaran.png) - -## Lnswap - -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange - -![](/img/sh_lnswap.png) - -## Neoswap - -[Neoswap](https://neoswap.party) - -![](/img/sh_neoswap.png) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md b/i18n/fr/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md deleted file mode 100644 index e5ea6c5b45..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Wallets -description: Wallets for Stacks -sidebar_position: 4 ---- - -A list of hardware and software wallets for Stacks - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Blockchain.com - -[Blockchain.com](https://www.blockchain.com/wallet) - -![](/img/sh_blockchain.png) -## Boom - -[Boom](https://boom.money) - -![](/img/sh_boom.png) - -## Dcent wallet - -[D'CENT](https://dcentwallet.com) - -![](/img/sh_dcent.png) -## Hiro Wallet - -[Hiro Wallet](https://www.hiro.so/wallet) - -![](/img/sh_hirowallet.png) - -## Neptune - -[Neptune](https://neptunewallet.io) - -![](/img/sh_neptunewallet.png) - -## Xverse - -[Xverse](https://www.xverse.app/) - -![](/img/sh_xverse.png) - -## Wise - -[Wise](https://wiseapp.id) - -![](/img/sh_wiseapp.png) \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md b/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md deleted file mode 100644 index bd2c361985..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md +++ /dev/null @@ -1,214 +0,0 @@ ---- -title: Accounts -description: Guide to Stacks 2.0 accounts -sidebar_position: 5 ---- - -## Introduction - -Stacks 2.0 accounts are entities that own assets, like Stacks (STX) tokens. An account has an address, private key, nonce, and one or more asset balances. - -:::tip The encryption algorithm used in Stacks 2.0 is **[secp256k1](https://en.bitcoinwiki.org/wiki/Secp256k1)**. - -Additionally, [Ed25519](https://ed25519.cr.yp.to/) is also used just for the VRF (Verifiable Random Function). ::: - -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. - -:::tip -The transaction type doesn't need to be a token transfer - contract deploy and contract call transactions can change the balances of an account -::: - -## Creation - -An account is generated from a 24-word mnemonic phrase. This is often referred to as the **seed phrase**. The seed phrase provides access to Stacks 2.0 accounts. - -:::danger -If the seed phrase is lost, access to the associated account cannot be restored. No person or organization, including Blockstack, can recover a lost seed phrase. -::: - -The easiest way to generate a new Stacks 2.0 account is to use the [Stacks CLI](https://github.com/hirosystems/stacks.js/tree/master/packages/cli): - -```bash -# install CLI globally -npm install --global @stacks/cli - -# generate a new account and store details in a new file -# '-t' option makes this a testnet account -stx make_keychain -t > cli_keychain.json -``` - -`make_keychain` creates the following file: - -```js -{ - "mnemonic": "aaa bbb ccc ddd ...", - "keyInfo": { - "privateKey": "5a3f1f15245bb3fb...", - "address": "STJRM2AMVF90ER6G3RW1QTF85E3HZH37006D5ER1", - "btcAddress": "biwSd6KTEvJcyX2R8oyfgj5REuLzczMYC1", - "wif": "L4HXn7PLmzoNW...", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -| Field | Description | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `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.privateKey` | Private key for the account. Required for token transfers and often referred to as `senderKey` | -| `keyInfo.address` | Stacks address for the account | -| `keyInfo.btcAddress` | Corresponding BTC address for the account. | -| `keyInfo.wif` | Private key of the btcAddress in compressed format. | -| `keyInfo.index` | Nonce for the account, starting at 0 | - -Note that a new account automatically exists for each new private key. There is no need to manually instantiate an account on the Stacks 2.0 blockchain. - -:::tip Addresses are created by generating the [RIPEMD-160 hash](https://en.wikipedia.org/wiki/RIPEMD#RIPEMD-160_hashes) of the [SHA256](https://en.bitcoinwiki.org/wiki/SHA-256) of the public key. BTC addresses are encoded with [Base58Check](https://en.bitcoin.it/wiki/Base58Check_encoding). For Stacks addresses, [c32check](https://github.com/stacks-network/c32check) is used. Deriving an address from a public key can be done without internet access, for instance using the c32check `c32addressDecode` method. ::: - -Alternatively to the CLI creation, the [Stacks Transactions JS](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library can be used: - -```js -import { - makeRandomPrivKey, - privateKeyToString, - getAddressFromPrivateKey, - TransactionVersion, -} from '@stacks/transactions'; - -const privateKey = makeRandomPrivKey(); - -// Get public key from private -const publicKey = getPublicKey(privateKey); - -const stacksAddress = getAddressFromPrivateKey( - privateKeyToString(privateKey), - TransactionVersion.Testnet // remove for Mainnet addresses -); -``` - -A second alternative would be to use [stacks-gen](https://github.com/psq/stacks-gen). This tool will generate all the keys you need in one place, including the values needed for calling the stacking contract, and also a WIF key for use with `bitcoind`. - -#### stacks-gen prerequisite - -Install [npx](https://github.com/npm/npx) if not already installed. (npx will check whether `` exists in \$PATH, or in the local project binaries, and execute that. If `` is not found, it will be installed prior to execution). - -``` -npm install -g npx -``` - -#### stacks-gen usage - -``` -npx -q stacks-gen sk --testnet - -{ - "phrase": "guide air pet hat friend anchor harvest dog depart matter deny awkward sign almost speak short dragon rare private fame depart elevator snake chef", - "private": "0351764dc07ee1ad038ff49c0e020799f0a350dd0769017ea09460e150a6401901", - "public": "022d82baea2d041ac281bebafab11571f45db4f163a9e3f8640b1c804a4ac6f662", - "stacks": "ST16JQQNQXVNGR8RZ1D52TMH5MFHTXVPHRV6YE19C", - "stacking": "{ hashbytes: 0x4d2bdeb7eeeb0c231f0b4a2d5225a3e3aeeed1c6, version: 0x00 }", - "btc": "mnYzsxxW271GkmyMnRfiopEkaEpeqLtDy8", - "wif": "cMh9kwaCEttgTQYkyMUYQVbdm5ZarZdBHErcq7mXUChXXCo7CFEh" -} -``` - -:::tip The stacking object with hashbytes and a version represents the bitcoin address derived from the Stacks address. Read more about the [bitcoin address format](stacking#bitcoin-address). ::: - -Full documentation available at [stacks-gen](https://github.com/psq/stacks-gen). - -## Querying - -### Get Stacks (STX) balance and nonce - -STX balance and nonce can be obtained through the [`GET /v2/accounts/`](https://docs.hiro.so/api#operation/get_account_info) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/accounts/' -``` - -Sample response: - -```js -{ - "balance": "0x0000000000000000002386f26f3f40ec", - "nonce": 17 -} -``` - -:::tip -The balance string represents an unsigned 128-bit integer (big-endian) in hex encoding -::: - -### Get all token balances - -All token balances can be obtained through the [`GET /extended/v1/address//balances`](https://docs.hiro.so/api#operation/get_account_balance) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/address//balances' -``` - -Sample response: - -```js -{ - "stx": { - "balance": "0", - "total_sent": "0", - "total_received": "0" - }, - "fungible_tokens": {}, - "non_fungible_tokens": {} -} -``` - -:::tip Stacks accounts cannot hold bitcoins. The best way to obtain corresponding BTC balances is to derive the BTC address from the Stacks address (using [`c32check`](https://github.com/stacks-network/c32check#c32tob58-b58toc32)) and query the Bitcoin network. ::: - -### Get all asset events - -All asset events associated with the account can be obtained through the [`GET /extended/v1/address//assets`](https://docs.hiro.so/api#operation/get_account_balance) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/address//assets' -``` - -Sample response: - -```js -{ - "limit": 20, - "offset": 0, - "total": 0, - "results": [ - { - "event_index": 5, - "event_type": "non_fungible_token_asset", - "asset": { - "asset_event_type": "transfer", - "asset_id": "ST2W14YX9SFVDB1ZGHSH40CX1YQAP9XKRAYSSVYAG.hello_world::hello-nft", - "sender": "SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR", - "recipient": "SM2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQVX8X0G", - "value": { - "hex": "0x0100000000000000000000000000000001", - "repr": "u1" - } - } - }, - { - "event_index": 3, - "event_type": "fungible_token_asset", - "asset": { - "asset_event_type": "mint", - "asset_id": "ST2W14YX9SFVDB1ZGHSH40CX1YQAP9XKRAYSSVYAG.hello_world::novel-token-19", - "sender": "", - "recipient": "SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR", - "amount": "12" - } - } - ] -} -``` diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/index.md b/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/index.md deleted file mode 100644 index 1533219df9..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/index.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Understand Stacks -description: Learn more about the Stacks 2.0 blockchain -sidebar_position: 1 ---- - -![](/img/SBC-L-2x-10.png) -## Introduction - -Stacks 2.0 is a layer-1 blockchain that connects to Bitcoin and brings smart contracts and decentralized apps to it. Smart contracts and apps developed on the Stacks platform are natively integrated with the security, stability, and economic power of Bitcoin. - -## Capabilities - -Read more about the features provided by the Stacks 2.0 blockchain. - - - -:::tip Check out the [technical specifications](technical-specs) for a brief overview ::: - - - - -A detailed [comparison of the Stacks blockchain to other blockchain technologies][] is available at the Stacks Foundation blog. -### Consensus mechanism -![](/img/pages/stacking.svg) Stacks 2.0 implements a new mining mechanism called Proof of Transfer ("PoX"). PoX is a consensus algorithm between two blockchains. It uses an established blockchain (in this case Bitcoin) to secure a new blockchain (Stacks). - -PoX connects to Bitcoin with a 1:1 block ratio, meaning anything that happens on the Stacks blockchain can be verified on the Bitcoin Blockchain. - -Instead of burning electricity on proof of work, PoX reuses already minted bitcoins as "proof of computation" and miners represent their cost of mining in bitcoins directly. - - -[Read more about Proof of Transfer](proof-of-transfer) -### Mining - -![](/img/pages/testnet-sm.svg) Mining is required to make the network usable, trustworthy, and secure. Miners verify incoming transactions, participate in the consensus mechanism, and write new blocks to the blockchain. - -To incentivize mining, miners receive freshly minted Stacks (STX) tokens if they win the bid for becoming the leader of the next round. - -[Read more about Mining](mining) - -### Stacking - -Bitcoins used for miner bids are sent to a set of specific addresses corresponding to Stacks (STX) tokens holders that are actively participating in consensus ("Stackers"). Thus, rather than being destroyed, the bitcoins consumed in the mining process go to productive Stacks holders as a reward based on their holdings of Stacks and participation in the Stacking algorithm. - -Stackers have to lock up their Stacks (STX) tokens for a certain period of time. - -[Read more about Stacking](stacking) - -### Smart contracts - -![](/img/pages/write-smart-contracts-sm.svg) Clarity is a new language for smart contracts on the Stacks 2.0 blockchain. The Clarity smart contract language optimizes for predictability and security. - -Stacks 2.0 anchors clarity smart contracts to Bitcoin making it possible for smart contracts to operate based on actions seen on the bitcoin blockchain. - -:::note The [Clarity open-source project](https://clarity-lang.org/) is supported by Stacks and [Algorand](https://www.algorand.com/) ::: - - -Clarity is distinct from other languages designed for writing smart contracts in a few ways: - -- **Predictability**: The Clarity language uses precise and unambiguous syntax that allows developers to predict exactly how their contracts will be executed. -- **Security**: The Clarity language allows users to supply their own conditions for transactions that ensure that a contract may never unexpectedly transfer a token owned by a user. -- **No compiler**: Contracts written in Clarity are broadcasted on the Stacks blockchain exactly as they are written by developers. This ensures that the code developers wrote, analyzed, and tested, is exactly what gets executed. - -[Read more about Clarity](../write-smart-contracts/clarity-language/) - -## Guides - -Read one of our guides to understand the ins and outs of the Stacks 2.0 blockchain. - -* [Account](../understand-stacks/accounts) -* [Transactions](../understand-stacks/transactions) -* [Network](../understand-stacks/network) -* [Microblocks](../understand-stacks/microblocks) - -[comparison of the Stacks blockchain to other blockchain technologies]: https://stacks.org/stacks-blockchain diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md b/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md deleted file mode 100644 index de64c617f4..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: Microblocks -description: Guide to Stacks Microblocks -sidebar_position: 8 ---- - -## Introduction - -Microblocks are a protocol-level feature of the Stacks blockchain that solve the technical challenge of transaction latency. Because each Stacks block is anchored to a Bitcoin block through the [Proof-of-Transfer consensus mechanism](../understand-stacks/proof-of-transfer), Stacks is necessarily limited to the same block times as the Bitcoin network. Microblocks allow the Stacks blockchain to perform state transitions between anchor blocks. - -Microblocks are a powerful mechanism for developers to create performant, high quality applications on Stacks, while still inheriting the security of Bitcoin. - -## Transaction states - -The [Stacks block production model](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.) is described in SIP-001. The standard outlines the mechanism by which elected block leaders can produce blocks on the Stacks blockchain either by batching transactions or by streaming them. Microblocks are the product of the streaming model. - -If a block leader has elected to mine microblocks, the leader selects transactions from the mempool and package them into microblocks during the current epoch. Microblocks are blocks of transactions included by a miner after the previous anchor block has been mined, but before the next block is selected. Transactions included in microblocks are processed by the network: their results are known. - -Consider a transaction from the perspective of the number of block confirmations it has. A transaction included in a microblock might have the following example lifecycle: - -``` -Transaction 1 is broadcast to the mempool. It has 0 confirmations. -Transaction 1 is included in a microblock. It still has 0 confirmations, but the results of the transaction are known -Transaction 1 is included in the next anchor block. It has 1 confirmation. -The next Stacks block confirms the previous block. Transaction 1 has 2 confirmations. -The next Stacks block confirms the previous block. Transaction 1 has 3 confirmations. -... -``` - -Consider a similar transaction that is not included in a microblock: - -``` -Transaction 2 is broadcast to the mempool. It has 0 confirmations. -Transaction 2 is included in the next anchor block. It has 1 confirmation. -The next Stacks block confirms the previous block. Transaction 2 has 2 confirmations. -The next Stacks block confirms the previous block. Transaction 2 has 3 confirmations. -``` - -The lifecycles of the two transactions are similar, but the difference is pending state. Many Bitcoin wallets display 0-confirmation balances: your wallet balance with any mempool transactions already applied. This is useful because it tells you when you've sent a transaction or received one. With smart contracts, displaying pending state is not as straightforward, because smart contracts do not just transfer inputs to outputs, they may call other contracts, emit events, or perform other computations. A transaction processed in a microblock generates all that information. - -:::tip -If a transaction is dependent on a chain state that could by altered by previous transactions with serious -implications, you should carefully consider whether it should be performed using microblocks. -::: - -## Enabling microblocks - -Miners can choose to enable or disable microblocks in their mining configuration. As a best practice, miners should enable microblock mining. When an application or user submits a transaction, the transaction can include an argument that requires the transaction to be in a microblock, an anchor block, or in either. - -### Transactions - -Transactions include an option that controls if a miner should include them in microblocks or in anchor blocks. The anchor mode transaction option is an optional argument that controls whether a transaction must be included in an anchor block or a microblock, or is eligible for either. - -### Mining - -Stacks miners must enable microblocks in their miner configuration to implement the block streaming model. For more information, see [mining microblocks](../understand-stacks/mining#microblocks). - -## Developing with microblocks - -In most cases, information from transactions included in microblocks should be treated like information from any other block. Wallets and explorers should display the consequences of microblock transactions as the current state of the network. This state should be acknowledged as tentative. - -A microblock transaction can end up being reorganized in the next block rather than just being confirmed as-is. Because of this, your UI should communicate to users if the outputs of a transaction changed, or if the transaction's associated block changed. This is the same outcome as if a 1-block fork occurred. - -### Stacks.js libraries - -Stacks.js provides the [AnchorMode][] argument on transaction objects so that your application can set the microblocks preference for transactions. - -### API - -:::danger API support for microblocks is a work-in-progress. Review the [API documentation][microblocks_api] carefully to ensure that you are up-to-date on the latest implementation details for microblocks. ::: - -The Stacks Blockchain API exposes microblocks through several endpoints. Please review the [Stacks Blockchain API guide][] for more details. - -## Best practices - -Working with microblocks is a design decision that you must make for your own application. When working with microblocks, the following best practices are recommended. - -### Handling nonce - -Nonce handling with microblocks is challenging because the next account nonce must take into account any nonce values included in microblocks, which may not yet be included in an anchor block. The Stacks Blockchain API [provides an endpoint][] to retrieve the next nonce for a given principal. - -### Application design - -The state of microblock transactions should be carefully communicated to users. No transaction is final until it's included in an anchor block, and your application design should reflect this. - -The following guidelines are provided as an initial set of best practices for UI design when incorporating microblocks into your application. - -#### Explorers - -Display pending state, but warn that a transaction is still pending. Indicate visually that displayed balances depend on pending state. - -#### Wallets - -Display pending state, but warn that a transaction is still pending. Indicate visually that displayed balances depend on pending state. - -#### Exchanges - -Continue to count confirmations, microblocks should be considered pending. - -#### Applications - -Microblock communication is highly app-dependent. For some applications, displaying a pending or 0-confirmation transaction as confirmed may be fine. For example, storing data on the chain, or querying the BNS contract. For other applications, such as the transfer of real value, waiting for 3-confirmations would be prudent before displaying the state as confirmed. - -[AnchorMode]: https://stacks.js.org/enums/transactions.AnchorMode.html -[Stacks Blockchain API guide]: https://docs.hiro.so/get-started/stacks-blockchain-api#microblocks-support -[provides an endpoint]: https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling -[microblocks_api]: https://docs.hiro.so/api#tag/Microblocks diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/mining.md b/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/mining.md deleted file mode 100644 index fa1f56ed3f..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/mining.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Mining -description: A guide to mining on Stacks 2.0 -sidebar_position: 4 ---- - -## Introduction - -This guide highlights some technical details related to mining on the Stacks 2.0 network. - -For steps on how to setup your own miner please refer to [miner on tesnet](nodes-and-miners/miner-testnet.md) and [miner on mainnet](nodes-and-miners/miner-testnet.md). - -## Mining frequency - -A new Stacks block may be mined once per Bitcoin block. To be considered for mining a block, a miner must have a block commit included in a Bitcoin block. If a miner wishes to update their commitment after submission, they may use Bitcoin Replace-By-Fee. - -## Coinbase rewards - -Miners receive coinbase rewards for blocks they win. - -The reward amounts are: - -- 1000 STX per block are released in the first 4 years of mining -- 500 STX per block are released during the following 4 years -- 250 STX per block are released during the following 4 years -- 125 STX per block are released from then on indefinitely. - -These "halvings" are synchronized with Bitcoin halvings. - -![coinbase rewards](/img/pages/coinbase-rewards.png) - -## Transaction fees - -Miners receive Stacks fees for transactions mined in any block they produce. - -For transactions mined in microblocks, the miner that produces the microblock receives 40% of the fees, while the miner that confirms the microblock receives 60% of the fees. - -## Reward maturity - -Block rewards and transaction fees take 100 blocks on the Bitcoin blockchain to mature. After successfully mining a block your rewards appear in your Stacks account after ~24 hours. - -## Mining with proof-of-transfer - -Miners commit Bitcoin to **two** addresses in every leader block commit. The amount committed to each address must be the same. The addresses are chosen from the current reward set of stacking participants. Addresses are chosen using a verifiable-random-function, and determining the correct two addresses for a given block requires monitoring the Stacks chain. - -![mining with pox](/img/pages/mining-with-pox.png) - -## 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, 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. - -While there is no minimum BTC commitment enforced by the protocol, in practice, there's a floor constrained by [dust](https://unchained-capital.com/blog/dust-thermodynamics/)": basically, if the fees for a transaction exceed the value of the spent output, it's considered dust. How dust is [calculated](https://github.com/bitcoin/bitcoin/blob/master/src/policy/policy.cpp#L14) depends on a number of factors, we've found 5,500 satoshis to be good lower bound per [output](https://learnmeabitcoin.com/technical/output). Bitcoin transactions from Stacks miners contain two outputs (for Proof-of-Transfer), so a commitment of at least 11,000 satoshis / block is recommended. - -To calculate the amount of BTC to send miners should: - -- Guess the price BTC/STX for the next day (100 blocks later) -- Guess the total amount of BTCs committed by all miners - -## Microblocks - -The Stacks blockchain produces blocks at the same rate as the Bitcoin blockchain. In order to provide lower latency transactions, miners can opt to enable microblocks. Microblocks allow the current block leader to stream transactions and include their state transitions in the current epoch. - -If a block leader opts to produce microblocks, the next leader builds the chain tip off the last microblock that the current leader produces. - -The block streaming model is described in [SIP-001][]. - -[SIP-001]: https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md#operation-as-a-leader diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/network.md b/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/network.md deleted file mode 100644 index 6efcc385ec..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/network.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: Network -description: Guide to the Stacks 2.0 network -sidebar_position: 7 ---- - -## Tokens - -Stacks (STX) tokens are the native tokens on the Stacks 2.0 blockchain. The smallest fraction is one micro-STX. 1,000,000 micro-STX make one Stacks (STX). - -STX amounts should be stored as integers (8 bytes long), and represent the amount of micro-STX. For display purposes, micro-STX are divided by 1,000,000 (decimal precision of 6). - -## 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 in bytes. The fee rate is a market determined variable. For the [testnet](testnet), it is set to 1 micro-STX. - -Fee estimates can obtained through the [`GET /v2/fees/transfer`](https://docs.hiro.so/api#operation/get_fee_transfer) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/fees/transfer' -``` - -The API will respond with the fee rate (as integer): - -```json -1 -``` - -[The Stacks Transactions JS library](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) supports fee estimation for: - -- token transfers (`estimateTransfer`) -- contract deploys (`estimateContractDeploy`) -- non read-only contract calls (`estimateContractFunctionCall`) - -:::tip For an implementation using a different language than JavaScript, please review [this reference implementation](https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/src/builders.ts#L97). ::: - -## Nonces - -Every account carries a [nonce property](https://en.wikipedia.org/wiki/Cryptographic_nonce) that indicates the number of transactions processed for the given account. Nonces are one-time codes, starting at `0` for new accounts, and incremented by 1 on every transaction. - -Nonces are added to all transactions and help identify them in order to ensure transactions are processed in order and to avoid duplicated processing. - -:::tip -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 is constructed, the most recent nonce of the account needs to fetched and set. - -:::tip The API provides an endpoint to [simplify nonce handling](https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling). ::: - -## Confirmations - -The Stacks 2.0 network is anchored onto the bitcoin network. This allows transactions on Stacks to inherit the same finality and security of the Bitcoin blockchain. - -The time to mine a block, to confirm transactions, will eventually match the expected "block time" of the bitcoin network: 10 minutes. - -:::tip Transactions can also be mined in [microblocks](microblocks), reducing the latency significantly. ::: - -The block time is hardcoded and will change throughout the implementation phases of the [testnet](testnet). The current block time can be obtained through the [`GET /extended/v1/info/network_block_times`](https://docs.hiro.so/api#operation/get_network_block_times) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/info/network_block_times' -``` - -The API will respond with the block time (in seconds): - -```js -{ - "testnet": { - "target_block_time": 120 - }, - "mainnet": { - "target_block_time": 600 - } -} -``` - -## Read-only function calls - -Smart contracts can expose public function calls. For functions that make state modifications to the blockchain, transactions need to be generated and broadcasted. - -However, for read-only function calls, transactions are **not** required. Instead, these calls can be done using the [Stacks Blockchain API](https://docs.hiro.so/get-started/stacks-blockchain-api). - -:::tip -Read-only function calls do not require transaction fees -::: - -A read-only contract call can be done using the [`POST /v2/contracts/call-read///`](https://docs.hiro.so/api#operation/call_read_only_function) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl --location --request POST 'https://stacks-node-api.testnet.stacks.co/v2/contracts/call-read///' \ ---header 'Content-Type: application/json' \ ---data-raw '{ - "sender": ".", - "arguments": [, ...] -}' -``` - -Sample response for a successful call: - -```js -{ - "okay": true, - "result": "" -} -``` - -:::tip To set the function call arguments and read the result, [Clarity values](../write-smart-contracts/values) need to be serialized into a hexadecimal string. The [Stacks Transactions JS](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library supports these operations ::: - -## Querying - -Stacks 2.0 network details can be queried using the [Stacks Blockchain API](https://docs.hiro.so/get-started/stacks-blockchain-api). - -### Health check - -The [status checker](https://stacks-status.com/) is a service that provides a user interface to quickly review the health of the Stacks 2.0 blockchain. - -### Network info - -The network information can be obtained using the [`GET /v2/info`](https://docs.hiro.so/api#operation/get_core_api_info) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/info' -``` - -Sample response: - -```js -{ - "peer_version": 385875968, - "burn_consensus": "826401d65cf3671210a3fb135d827d549c0b4d37", - "burn_block_height": 1972, - "stable_burn_consensus": "e27ea23f199076bc41a729d76a813e125b725f64", - "stable_burn_block_height": 1971, - "server_version": "blockstack-core 0.0.1 => 23.0.0.0 (master:bdd042242+, release build, linux [x86_64]", - "network_id": 2147483648, - "parent_network_id": 3669344250, - "stacks_tip_height": 933, - "stacks_tip": "1f601823fbcc5b6b2215b2ff59d2818fba61ee4a3cea426d8bc3dbb268005d8f", - "stacks_tip_burn_block": "54c56a9685545c45accf42b5dcb2787c97eda8185a1c794daf9b5a59d4807abc", - "unanchored_tip": "71948ee211dac3b241eb65d881637f649d0d49ac08ee4a41c29217d3026d7aae", - "exit_at_block_height": 28160 -} -``` diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md b/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md deleted file mode 100644 index c933f7af68..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Proof of Transfer -description: Understand the proof-of-transfer consensus mechanism -sidebar_position: 3 ---- - -## Overview - -Consensus algorithms for blockchains require compute or financial resources to secure the blockchain. The general practice of decentralized consensus is to make it practically infeasible for any single malicious actor to have enough computing power or ownership stake to attack the network. - -Popular consensus mechanisms in modern blockchains include proof-of-work, in which nodes dedicate computing resources, and proof-of-stake, in which nodes dedicate financial resources to secure the network. - -Proof-of-burn is a novel consensus mechanism where miners compete by ‘burning’ (destroying) a proof-of-work cryptocurrency as a proxy for computing resources. - -Proof-of-transfer (PoX) is an extension of the proof-of-burn mechanism. 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. - -![PoX mechanism](/img/pox-mechanism.png) - -This allows network participants to secure the PoX cryptocurrency network and earn a reward in the base cryptocurrency. Thus, proof-of-transfer blockchains are anchored on their chosen proof-of-work chain. Stacks uses [Bitcoin](#why-bitcoin) as its anchor chain. - -![PoX participants](/img/pox-participants.png) - -## Why Bitcoin? - -There are a number of reasons that Stacks chose Bitcoin as the blockchain to power consensus. It's the oldest blockchain protocol, having launched in 2009, and has become a recognized asset outside of the cryptocurrency community. BTC has held the highest market capitalization of any cryptocurrency for the past decade. - -Bitcoin champions simplicity and stability, and has stood the test of time. Influencing or attacking the network is infeasible or impractical for any potential hackers. It's one of the only cryptocurrencies to capture public attention. Bitcoin is a household name, and is recognized as an asset by governments, large corporations, and legacy banking institutions. Lastly, Bitcoin is largely considered a reliable store of value, and provides extensive infrastructure to support the proof-of-transfer consensus mechanism. - -SIP-001 provides a full [list of reasons why Bitcoin was chosen to secure Stacks](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md). - -![btc-stacks](/img/pox-why-bitcoin.png) - -## Blocks and microblocks - -The Stacks blockchain allows for increased transaction throughput using a mechanism called microblocks. Bitcoin and Stacks progress in lockstep, and their blocks are confirmed simultaneously. On Stacks, this is referred to as an ‘anchor block’. An entire block of Stacks transactions corresponds to a single Bitcoin transaction. This significantly improves cost/byte ratio for processing Stacks transactions. Because of simultaneous block production, Bitcoin acts as a rate-limiter for creating Stacks blocks, thereby preventing denial-of-service attacks on its peer network. - -However, in between Stacks anchor blocks settling on the Bitcoin blockchain, there are also a varying number of microblocks that allow rapid settlement of Stacks transactions with a high degree of confidence. This allows Stacks transaction throughput to scale independently of Bitcoin, while still periodically establishing finality with the Bitcoin chain. The Stacks blockchain adopts a block streaming model whereby each leader can adaptively select and package transactions into their block as they arrive in the mempool. Therefore when an anchor block is confirmed, all of the transactions in the parent microblock stream are packaged and processed. This is an unprecedented method for achieving scalability without creating a totally separate protocol from Bitcoin. - -![stx-microblock](/img/stx-microblocks.png) - -## Unlocking Bitcoin capital - -Stacks also unlocks the hundreds of billions in capital in Bitcoin, and gives Bitcoiners new opportunities to use and earn BTC. Stacks is a accompaniment to the Bitcoin ecosystem, and the two networks working in tandem enables totally novel ways of using BTC. The Stacks ecosystem makes interactive cryptocurrency applications available to Bitcoin holders. Additionally, By stacking STX tokens and participating in the PoX consensus mechanism, users have the opportunity to earn BTC while securing the Stacks chain. - -![Unlocking Bitcoin](/img/pox-unlocking-btc.png) - -## Clarity and the Bitcoin state - -Clarity smart contracts also have unique visibility into the state of the Bitcoin blockchain. This means that contract logic in a Clarity file has the ability to trigger when specific Bitcoin transactions are confirmed. Clarity smart contracts have a built in Simple Payment Verification (SPV) proofs for Bitcoin that make interacting with Bitcoin’s state much simpler for developers. Additionally, Clarity contracts can fork with the original Bitcoin chain. Therefore, in an edge case where Bitcoin forks, developers wouldn’t have to worry about adjusting the deployment of their smart contracts. - -## See also - -- [Read the full PoX whitepaper](https://community.stacks.org/pox) -- [Watch Executive Chair of Hiro Muneeb Ali and Evangelist Joe Bender give an overview of Stack's breakthrough PoX mining mechanism](https://www.youtube.com/watch?v=NY_eUrIcWOY) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md b/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md deleted file mode 100644 index 5f3863e8dd..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: Stacking -description: Introduction to the reward mechanism of Proof-of-Transfer -sidebar_position: 9 ---- - -## Introduction - -Stacking rewards Stacks (STX) token holders with bitcoin for providing a valuable service to the network by locking up their tokens for a certain time. - -![](/img/stacking.png) - -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. - -:::info The Stacking consensus algorithm is implemented as a smart contract, using [Clarity](../write-smart-contracts/). [Read more about the contract](../noteworthy-contracts/stacking-contract). ::: - -## Stacking flow - -The Stacking mechanism can be presented as a flow of actions: - -![Stacking flow](/img/stacking-illustration.png) - -1. Make API calls to get details about the upcoming reward cycle -2. For a specific Stacks account, confirm eligibility -3. Confirm the BTC reward address and the lockup duration -4. The transaction is broadcasted and the STX tokens are locked. This needs to happen before the prepare phase of the next reward cycle, the last 100 Bitcoin blocks of the ongoing reward phase -5. The Stacking mechanism executes reward cycles and sends out rewards to the set BTC reward address -6. During the lockup period, details about unlocking timing, rewards and more can be obtained -7. Once the lockup period is passed, the tokens are released and accessible again -8. Display reward history, including details like earnings for previous reward cycles - -:::info Keep in mind that the target duration for a reward cycles is ~2 weeks. This duration is based on the target block time of the network (10 minutes) and can be higher at times due to [confirmation time variances](https://www.blockchain.com/charts/median-confirmation-time) of the bitcoin network. ::: - -## Stacking delegation flow - -The Stacking flow is different for delegation use cases: - -![Delegated tacking flow](/img/stacking-delegation-illustration.png) - -- Before Stacking can be initiated for a token holder, the delegator needs to be granted permission to Stack on behalf of the account owner. The permission is restricted to the maximum amount the delegator is allowed to Stack. The maximum amount is not limited by the available funds and can be set much higher. An account can only be associated with one single delegator -- The account has to define the delegation relationship. They can optionally restrict the Bitcoin reward address that must be used for payouts, and the expiration burn block height for the permission, thus limiting the time a delegator has permission to Stack -- Delegators have to lock Stacks from different accounts ("pooling phase") until they reach the minimum amount of Stacks required to participate in Stacking -- Once a delegator locks enough STX tokens, they can finalize and commit their participation in the next reward cycle -- Certain delegation relationships may allow the STX holder to receive the payout directly from the miner (step 5/6) -- The termination of the delegation relationship can either happen automatically based on set expiration rules or by actively revoking delegation rights - -## PoX mining - -PoX mining is a modification of Proof-of-Burn (PoB) mining, where instead of sending the committed Bitcoin to a burn address, it's transferred to eligible STX holders that participate in the stacking protocol. - -:::note -A PoX miner can only receive newly minted STX tokens when they transfer Bitcoin to eligible owners of STX tokens -::: - -![Mining flow](/img/pox-mining-flow.png) - -Miners run Stacks nodes with mining enabled to participate in the PoX mechanism. The node implements the PoX mechanism, which ensures proper handling and incentives through four key phases: - -- Registration: miners register for a future election by sending consensus data to the network -- Commitment: registered miners transfer Bitcoin to participate in the election. Committed BTC are sent to a set participating STX token holders -- Election: a verifiable random function chooses one miner to write a new block on the Stacks blockchain -- Assembly: the elected miner writes the new block and collects rewards in form of new STX tokens - -## Token holder eligibility - -Stacks (STX) token holders don't automatically receive stacking rewards. Instead, they must: - -- Commit to participation before a reward cycle begins -- Commit the minimum amount of STX tokens to secure a reward slot, or pool with others to reach the minimum -- Lock up STX tokens for a specified period -- Provide a supported Bitcoin address to receive rewards (native segwit is not supported) - -The following diagram describes how the minimum STX tokens per slot is determined. More information on [dynamic minimums for stacking](https://stacking.club) is available at stacking.club. - -![Dynamic minimum for individual eligibility](/img/stacking-dynamic-minimum.png) - -Token holders have a variety of providers and tools to support their participation in Stacking. The Stacks website contains a [list of stacking providers and pools](https://stacks.org/stacking#earn). - -## Stacking in the PoX consensus algorithm - -Stacking is a built-in capability of PoX and occurs through a set of actions on the Stacks blockchain. The [full proof-of-transfer implementation details](https://github.com/stacks-network/stacks-blockchain/blob/develop/sip/sip-007-stacking-consensus.md) are in SIP-007. Below is a summary of the most relevant actions of the algorithm. - -![PoX cycles](/img/pox-cycles.png) - -- Stacking happens over reward cycles with a fixed length. In each reward cycle, a set of Bitcoin addresses associated with stacking participants receive BTC rewards -- A reward cycle consists of two phases: prepare and reward -- During the prepare phase, miners decide on an anchor block and a reward set. Mining any descendant forks of the anchor block requires transferring mining funds to the appropriate reward addresses. The reward set is the set of Bitcoin addresses which are eligible to receive funds in the reward cycle -- Miners register as leader candidates for a future election by sending a key transaction that burns cryptocurrency. The transaction also registers the leader's preferred chain tip (must be a descendant of the anchor block) and commitment of funds to 2 addresses from the reward set -- Token holders register for the next rewards cycle by broadcasting a signed message that locks up associated STX tokens for a protocol-specified lockup period, specifies a Bitcoin address to receive the funds, and votes on a Stacks chain tip -- Multiple leaders can commit to the same chain tip. The leader that wins the election and the peers who also burn for that leader collectively share the reward, proportional to how much each one burned -- Token holders' locked up tokens automatically unlock as soon as the lockup period finishes - -## Bitcoin address - -:::danger You must provide a BTC address in one of two formats: - -* [Legacy (P2PKH)](https://en.bitcoin.it/wiki/Transaction#Pay-to-PubkeyHash), which starts with `1`. - -* [Segregated Witness / Segwit (P2SH)](https://en.bitcoin.it/wiki/Pay_to_script_hash), which starts with `3`. The "Native Segwit" format (which starts with `bc1`), for example, is not supported. ::: - -The Stacking contract needs a special format for the Bitcoin address (the reward address). This is required to ensure that miners are able to correctly construct the Bitcoin transaction containing the reward address. - -The address must be specified in the following format using the Clarity language: - -```clar -;; a tuple of a version and hashbytes buffer -(pox-addr (tuple (version (buff 1)) (hashbytes (buff 20)))) -``` - -The `version` buffer must represent what kind of bitcoin address is being submitted. It can be one of the following: - -```js -SerializeP2PKH = 0x00, // hash160(public-key), same as bitcoin's p2pkh -SerializeP2SH = 0x01, // hash160(multisig-redeem-script), same as bitcoin's multisig p2sh -SerializeP2WPKH = 0x02, // hash160(segwit-program-00(p2pkh)), same as bitcoin's p2sh-p2wpkh -SerializeP2WSH = 0x03, // hash160(segwit-program-00(public-keys)), same as bitcoin's p2sh-p2wsh -``` - -The `hashbytes` are the 20 hash bytes of the bitcoin address. You can obtain that from a bitcoin library, for instance using [`bitcoinjs-lib`](https://github.com/bitcoinjs/bitcoinjs-lib): - -```js -const btc = require('bitcoinjs-lib'); -console.log( - '0x' + btc.address.fromBase58Check('1C56LYirKa3PFXFsvhSESgDy2acEHVAEt6').hash.toString('hex') -); -``` - -## Choosing the right Stacking strategy - -[Here](https://blog.stacks.co/stacking-strategy) is an interesting article that may help you choose the right Stacking stategy. - - -## Where to Stacks? - -You can Stack on your own, on a pool or on an exchange: -### Stacking on your own - -Stacking on your own is non-custodial. - -Stacking on your own requires a protocol minimum (amount changes but about 100,000 STX). - -[Hiro Wallet](https://www.hiro.so/wallet) allows stacking on your own. - -### Stacking on a pool - -Stacking on a pool allows Stacking without the requirement of the protocol minumum. - -Some available pools are: - -| Pool | Type | Pays rewards in | Fee | Minimum amount | -| --------------------------------------------------- | ------------- |:---------------:| --- |:--------------:| -| [Friedger's Pool](https://pool.friedger.de/) | Non custodial | STX or xBTC | No | 40 STX | -| [Planbetter](https://planbetter.org/) | Non custodial | BTC | 5% | 200 STX | -| [Stacked](https://staking.staked.us/stacks-staking) | Non custodial | BTC | | 100,000 STX | -| [Xverse](https://www.xverse.app/) | Non custodial | BTC | No | 100 STX | - -### Stacking on an exchange - -Stacking on an exchange is custodial, meaning you are trusting the exchange with your Stacks. - -Several exchanges allow Stacking directly on their sites. Examples are [Okcoin](https://www.okcoin.com) and [Binance](https://www.binance.com/en/staking) - -## Stacking statistics - -You can view all sorts of Stacking data and statistics on [Stacking Club](https://stacking.club) \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md b/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md deleted file mode 100644 index d942d6af8f..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Stacks Blockchain API -description: Interacting with the Stacks 2.0 Blockchain via API ---- - -## Temporal page because of a Crowdin bug \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md b/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md deleted file mode 100644 index e370129d1d..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Technical Specifications -description: Summary of technical specifications of Stacks 2.0 -sidebar_position: 10 ---- - -## Consensus - -- Proof of Transfer (PoX) as described in [SIP-007](https://github.com/stacksgov/sips/blob/main/sips/sip-007/sip-007-stacking-consensus.md) -- Network will transition to Proof of Burn (PoB) as described in [SIP-001](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md) after 10 years. [Learn more about Proof-of-Burn in SIP-001](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md). -- Threat model - - 51% of malicious Stacks mining power can perform a double-spend attack - - 51% of malicious Bitcoin mining power can reorg the Stacks chain -- Different actors and their roles - - Stacks Miners package transactions into blocks, mine them through a Bitcoin transaction, propagate them, and if they win the block race, append microblocks to their winning block until the next block is mined. The next block confirms the microblock stream. - - Stacks Holders may alter the calculation of block limits (subject to a miner veto) and may vote to disable Proof-of-Transfer rewards for a reward cycle. -- Transactions are considered final when the corresponding "block commit" transaction on Bitcoin is finalized. Typically this can by 3-6 confirmations. -- For more details, see [Proof of Transfer](proof-of-transfer). - -## Proof of Transfer Mining - -- Coinbase reward schedule: - - 1000 STX/block for first 4 years - - 500 STX/block for following 4 years - - 250 STX/block for subsequent 4 years - - 125 STX/block in perpetuity after that -- Coinbase rewards accumulate for "missed sortitions": If a Bitcoin block has no sortition (at height N), then any Stacks block mined in a subsequent sortition that builds off of any Stacks chain tip that existed at the penultimate sortition (at height N-1) may claim its coinbase. This encourages miners to keep mining even if Bitcoin fees are high. -- Initial mining bonus: This is a special case of the above to incentivize early miners. Coinbase for all burnchain blocks between the first burn block height (to be chosen by independent miners as part of the Stacks 2.0 launch) and the first sortition winner accumulate and are distributed to miners over a fixed window (to be determined). For instance, say burn block height is 10,000 and first sortition is at block 10500 and distribution window is 100 blocks, then coinbase for the first 500 blocks (10,500 - 10,000) will be distributed evenly to miners who win sortition over the subsequent 100 blocks. -- 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 at least 11,000 satoshis (5,500 sats / [UTXO output](https://learnmeabitcoin.com/technical/utxo)); 2 outputs / block) to avoid "dust." -- For more details, see [Mining](mining). - -## Stacking - -- Stacking works in 2 phases - 1. Prepare phase: In this phase an "anchor block" is chosen. The qualifying set of addresses ("reward set") is determined based on the snapshot of the chain at the anchor block. Length of prepare phase is 100 blocks. Stacking commitments need to be confirmed before this phase starts - 2. Reward phase: In this phase miner BTC commitments are distributed amongst the reward set. Reward cycle length is 2000 BTC blocks (~2 weeks). -- 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/stacksgov/sips/blob/main/sips/sip-007/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.stacks.co/references/stacking-contract#delegate-stx). -- Only two types of BTC reward addresses are supported: [Legacy (P2PKH)](https://en.bitcoin.it/wiki/Transaction#Pay-to-PubkeyHash) or [Segregated Witness / Segwit (P2SH)](https://en.bitcoin.it/wiki/Pay_to_script_hash). Native Segwit is not supported. -- Further reading: [Stacking](stacking) - -## Accounts and Addresses - -- Transactions in the Stacks blockchain originate from, are paid for by, and execute under the authority of accounts -- An account is fully specified by its address + nonce + assets -- 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 (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](accounts) - -## Transactions - -- Transaction 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 - 2. _paying account_ is the account that is billed by the leader for the cost of validating and executing the transaction - 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 -- Transactions can be batched or streamed into blocks. The behavior can be controlled by the anchor mode of a transaction. With streaming ([microblocks](microblocks)), a faster confirmation time is possible. -- 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. -- Mempool limit for concurrent pending transactions is 25 per account -- Pending mempool transactions will be garbage-collected [256 blocks after receipt](https://github.com/stacks-network/stacks-blockchain/blob/master/src/core/mempool.rs#L62). With 10 minutes target block time, this would equal ~42 hours -- [Learn more about transaction encoding in SIP-005](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md#transaction-encoding) -- [Transaction signing and verification are described in SIP-005](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md#transaction-signing-and-verifying) -- All transactions impacting account balance are atomic, a transfer operation can not increment one account’s balance without decrementing another’s. However, transactions that perform multiple account actions (for example, transferring from multiple accounts) may partially complete. -- Transactions can include a memo string (max 34 bytes) - -## See also - -- [Read the full Stacks 2.0: Apps and Smart Contracts for Bitcoin whitepaper](https://cloudflare-ipfs.com/ipfs/QmaGgiVHymeDjAc3aF1AwyhiFFwN97pme5m536cHT4FsAW). - -- [Watch Aaron Blankstein video on Stacks whitepater v2](https://www.youtube.com/watch?v=Wd-Bfe8Sn-Y). \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md b/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md deleted file mode 100644 index 59934a5bde..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Testnet -description: Test your smart contracts and apps -sidebar_position: 2 ---- - -## About testnet - -The testnet is a separate blockchain from the Stacks mainnet analogous to a staging environment. It's a network used by developers to test their apps, smart contracts, or changes to the protocol in a production-like environment. It produces blocks at roughly the same rate as mainnet; about 1 block every 10 minutes on average. The Stacks testnet is rarely reset. - -### Faucet - -The testnet faucet provides you with free Stacks Token (STX) to test with. These are not the same as STX on mainnet and have no value. You can get STX from the faucet on the [Stacks Explorer Sandbox](https://explorer.stacks.co/sandbox/faucet?chain=testnet), or using the [API](https://docs.hiro.so/api#tag/Faucets). - -To get STX tokens from within the Explorer Sandbox, navigate to the "Faucet" tab on the left and click "Request STX" button. - -![](/img/stx_faucet.png) - -You can also try out [Stacking](stacking) by clicking on `I want to stack`. - -:::note -The Explorer Sandbox requires you to login with a Stacks wallet -::: - -### Testnet API - -The hosted Stacks Blockchain API for the testnet is available at this base URL: - -```shell -https://stacks-node-api.testnet.stacks.co/ -``` - -![](/img/api_testnet_status.png) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md b/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md deleted file mode 100644 index 2ff6072384..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Transactions -description: Guide to Stacks 2.0 transactions -sidebar_position: 6 ---- - -## Introduction - -Transactions are the fundamental unit of execution in the Stacks blockchain. Each transaction is originated from a [Stacks 2.0 account](accounts), and is retained in the Stacks blockchain history for eternity. This guide helps you understand Stacks 2.0 transactions. - -## Lifecycle - -Transactions go through phases before being finally confirmed, and available for all, on the Stacks 2.0 network. - -![Transaction lifecycle](/img/tx-lifecycle.png) - -- **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/en/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. - -:::note A transaction can have one of three states once it is registered: `pending`, `success`, or `failed`. ::: - -## Types - -The Stacks 2.0 supports a set of different transaction types: - -| **Type** | **Value** | **Description** | -| ----------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Coinbase | `coinbase` | The first transaction in a new block (an entity holding several transactions). Used to register for block rewards. These are not manually generated and broadcasted like other types of transactions. | -| Token transfer | `token_transfer` | Asset transfer from a sender to a recipient | -| Contract deploy | `smart_contract` | Contract instantiation | -| Contract call | `contract_call` | Contract call for a public, non read-only function | -| Poison Microblock | `poison_microblock` | Punish leaders who intentionally equivocate about the microblocks they package | - -A sample of each transaction type can be found in the [Stacks Blockchain API response definition for transactions](https://docs.hiro.so/api#operation/get_transaction_by_id). - -:::caution Read-only contract call calls do **not** require transactions. Read more about it in the [network guide](network#read-only-function-calls). ::: diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md b/i18n/fr/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md deleted file mode 100644 index fd45c80583..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Clarity Language -description: Overview of the Clarity language constructs -sidebar_label: Clarity Language -tags: - - clarity ---- - -## Clarity Type System - -The Clarity language uses a strong static type system. Function arguments and database schemas require specified types, and use of types is checked during contract launch. The type system does _not_ have a universal super type. - -## Public Functions - -Functions specified via `define-public` statements are _public_ functions and these are the only types of functions which may be called directly through signed blockchain transactions. In addition to being callable directly from a transaction (see the Stacks wire formats for more details on Stacks transactions), public functions may be called by other smart contracts. - -Public functions _must_ return a `(response ...)` type. This is used by Clarity to determine whether or not to materialize any changes from the execution of the function. If a function returns an `(err ...)` type, any mutations on the blockchain state from executing the function (and any function that it called during execution) will be aborted. - -In addition to functions defined via `define-public`, contracts may expose read-only functions. These functions, defined via `define-read-only`, are callable by other smart contracts, and may be queryable via public blockchain explorers. These functions _may not_ mutate any blockchain state. Unlike normal public functions, read-only functions may return any type. - -## Contract Calls - -A smart contract may call functions from other smart contracts using a `(contract-call?)` function. - -This function returns a response type result -- the return value of the called smart contract function. - -We distinguish 2 different types of `contract-call?`: - -### Static dispatch - -The callee is a known, invariant contract available on-chain when the caller contract is deployed. In this case, the callee's principal is provided as the first argument, followed by the name of the method and its arguments: - -```clarity -(contract-call? - .registrar - register-name - name-to-register) -``` - -### Dynamic dispatch - -The callee is passed as an argument, and typed as a trait reference (``). - -```clarity -(define-public (swap (token-a ) - (amount-a uint) - (owner-a principal) - (token-b ) - (amount-b uint) - (owner-b principal))) - (begin - (unwrap! (contract-call? token-a transfer-from? owner-a owner-b amount-a)) - (unwrap! (contract-call? token-b transfer-from? owner-b owner-a amount-b)))) -``` - -Traits can either be locally defined: - -```clarity -(define-trait can-transfer-tokens ( - (transfer-from? (principal principal uint) (response uint))) -``` - -Or imported from an existing contract: - -```clarity -(use-trait can-transfer-tokens - .contract-defining-trait.can-transfer-tokens) -``` - -Looking at trait conformance, callee contracts have two different paths. They can either be "compatible" with a trait by defining methods matching some of the methods defined in a trait, or explicitly declare conformance using the `impl-trait` statement: - -```clarity -(impl-trait .contract-defining-trait.can-transfer-tokens) -``` - -Explicit conformance should be prefered when adequate. It acts as a safeguard by helping the static analysis system to detect deviations in method signatures before contract deployment. - -The following limitations are imposed on contract calls: - -1. On static dispatches, callee smart contracts _must_ exist at the time of creation. -2. No cycles may exist in the call graph of a smart contract. This prevents recursion (and re-entrancy bugs). Such structures can be detected with static analysis of the call graph, and will be rejected by the network. -3. `contract-call?` are for inter-contract calls only. Attempts to execute when the caller is also the callee will abort the transaction. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md b/i18n/fr/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md deleted file mode 100644 index a6011cca8b..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md +++ /dev/null @@ -1,1388 +0,0 @@ ---- -title: Functions -description: See a detailed list of all functions for the Clarity language. -tags: - - clarity ---- - -## Functions - -Detailed list of all functions for the Clarity language. - -### + (add) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(+ i1 i2...)` -#### description: -Adds a variable number of integer inputs and returns the result. In the event of an _overflow_, throws a runtime error. -#### example: -```clarity -(+ 1 2 3) ;; Returns 6 -(+ 2 3) ;; Returns 5 -(+ 1 2 3 4) ;; Returns 10 -(+ 9 -3) ;; Returns 6 -(+ -3 -2) ;; Returns -5 -``` - -### - (subtract) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(- i1 i2...)` -#### description: -Subtracts a variable number of integer inputs and returns the result. In the event of an _underflow_, throws a runtime error. -#### example: -```clarity -(- 2 1 1) ;; Returns 0 -(- 0 3) ;; Returns -3 -(- 5 -3) ;; Returns 8 -(- -4 -5) ;; Returns 1 -``` - -### * (multiply) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(* i1 i2...)` -#### description: -Multiplies a variable number of integer inputs and returns the result. In the event of an _overflow_, throws a runtime error. -#### example: -```clarity -(* 2 3) ;; Returns 6 -(* 5 2) ;; Returns 10 -(* 2 2 2) ;; Returns 8 -(* 3 -2) ;; Returns -6 -(* -1 -2) ;; Returns 2 -``` - -### / (divide) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(/ i1 i2...)` -#### description: -Divides a variable number of integer inputs and returns the _integer part_ of the result. In the event of _division by zero_, throws a runtime error. - -#### example: -```clarity -(/ 2 3) ;; Returns 0 -(/ 5 2) ;; Returns 2 -(/ 4 2 2) ;; Returns 1 -(/ -10 2) ;; Returns -5 -(/ -8 -2) ;; Returns 4 -(/ -9 4) ;; Returns -2 -``` - -### >= (greater than or equal) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(>= i1 i2)` -#### description: -Compares two integers, returning `true` if `i1` is greater than or equal to `i2` and `false` otherwise. -#### example: -```clarity -(>= 1 1) ;; Returns true -(>= 5 2) ;; Returns true -``` - -### <= (less than or equal) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(<= i1 i2)` -#### description: -Compares two integers, returning true if `i1` is less than or equal to `i2` and `false` otherwise. -#### example: -```clarity -(<= 1 1) ;; Returns true -(<= 5 2) ;; Returns false -``` - -### < (less than) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(< i1 i2)` -#### description: -Compares two integers, returning `true` if `i1` is less than `i2` and `false` otherwise. -#### example: -```clarity -(< 1 2) ;; Returns true -(< 5 2) ;; Returns false -``` - -### > (greater than) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(> i1 i2)` -#### description: -Compares two integers, returning `true` if `i1` is greater than `i2` and false otherwise. -#### example: -```clarity -(> 1 2) ;; Returns false -(> 5 2) ;; Returns true -``` - -### to-int -#### input: `uint` -#### output: `int` -#### signature: `(to-int u)` -#### description: -Tries to convert the `uint` argument to an `int`. Will cause a runtime error and abort if the supplied argument is >= `pow(2, 127)`` -#### example: -```clarity -(to-int u238) ;; Returns 238 -``` - -### to-uint -#### input: `int` -#### output: `uint` -#### signature: `(to-uint i)` -#### description: -Tries to convert the `int` argument to a `uint`. Will cause a runtime error and abort if the supplied argument is negative. -#### example: -```clarity -(to-uint 238) ;; Returns u238 -``` - -### mod -#### input: `int, int | uint, uint` -#### output: `int | uint` -#### signature: `(mod i1 i2)` -#### description: -Returns the integer remainder from integer dividing `i1` by `i2`. In the event of a division by zero, throws a runtime error. -#### example: -```clarity -(mod 2 3) ;; Returns 2 -(mod 5 2) ;; Returns 1 -(mod 7 1) ;; Returns 0 -``` - -### pow -#### input: `int, int | uint, uint` -#### output: `int | uint` -#### signature: `(pow i1 i2)` -#### description: -Returns the result of raising `i1` to the power of `i2`. In the event of an _overflow_, throws a runtime error. -#### example: -```clarity -(pow 2 3) ;; Returns 8 -(pow 2 2) ;; Returns 4 -(pow 7 1) ;; Returns 7 -``` - -### sqrti -#### input: `int | uint` -#### output: `int | uint` -#### signature: `(sqrti n)` -#### description: -Returns the largest integer that is less than or equal to the square root of `n`. Fails on a negative numbers. -#### example: -```clarity -(sqrti u11) ;; Returns u3 -(sqrti 1000000) ;; Returns 1000 -(sqrti u1) ;; Returns u1 -(sqrti 0) ;; Returns 0 -``` - -### log2 -#### input: `int | uint` -#### output: `int | uint` -#### signature: `(log2 n)` -#### description: -Returns the _integer part_ of the power to which the number 2 must be raised to obtain the value `n`. Fails on zero or a negative number. -#### example: -```clarity -(log2 u8) ;; Returns u3 -(log2 8) ;; Returns 3 -(log2 u1) ;; Returns u0 -(log2 1000) ;; Returns 9 -``` - -### xor -#### input: `int, int | uint, uint` -#### output: `int | uint` -#### signature: `(xor i1 i2)` -#### description: -Returns the result of bitwise exclusive or'ing `i1` with `i2`. -#### example: -```clarity -(xor 1 2) ;; Returns 3 -(xor 120 280) ;; Returns 352 -``` - -### and -#### input: `bool, ...` -#### output: `bool` -#### signature: `(and b1 b2 ...)` -#### description: -Returns `true` if all boolean inputs are `true`. Importantly, the supplied arguments are evaluated in-order and lazily. Lazy evaluation means that if one of the arguments returns `false`, the function short-circuits, and no subsequent arguments are evaluated. -#### example: -```clarity -(and true false) ;; Returns false -(and (is-eq (+ 1 2) 1) (is-eq 4 4)) ;; Returns false -(and (is-eq (+ 1 2) 3) (is-eq 4 4)) ;; Returns true -``` - -### or -#### input: `bool, ...` -#### output: `bool` -#### signature: `(or b1 b2 ...)` -#### description: -Returns `true` if any boolean inputs are `true`. Importantly, the supplied arguments are evaluated in-order and lazily. Importantly, the supplied arguments are evaluated in-order and lazily. -#### example: -```clarity -(or true false) ;; Returns true -(or (is-eq (+ 1 2) 1) (is-eq 4 4)) ;; Returns true -(or (is-eq (+ 1 2) 1) (is-eq 3 4)) ;; Returns false -(or (is-eq (+ 1 2) 3) (is-eq 4 4)) ;; Returns true -``` - -### not -#### input: `bool` -#### output: `bool` -#### signature: `(not b1)` -#### description: -Returns the inverse of the boolean input. -#### example: -```clarity -(not true) ;; Returns false -(not (is-eq 1 2)) ;; Returns true -``` - -### is-eq -#### input: `A, A, ...` -#### output: `bool` -#### signature: `(is-eq v1 v2...)` -#### description: -Compares the inputted values, returning `true` if they are all equal. Note that _unlike_ the `(and ...)` function, `(is-eq ...)` will _not_ short-circuit. All values supplied to is-eq _must_ be the same type. -#### example: -```clarity -(is-eq 1 1) ;; Returns true -(is-eq true false) ;; Returns false -(is-eq \"abc\" 234 234) ;; Throws type error -``` - -### if -#### input: `bool, A, A` -#### output: `A` -#### signature: `(if bool1 expr1 expr2)` -#### description: -The `if` function admits a boolean argument and two expressions which must return the same type. In the case that the boolean input is `true`, the `if` function evaluates and returns `expr1`. If the boolean input is `false`, the `if` function evaluates and returns `expr2`. -#### example: -```clarity -(if true 1 2) ;; Returns 1 -(if (> 1 2) 1 2) ;; Returns 2 -``` - -### let -#### input: `((name1 AnyType) (name2 AnyType) ...), AnyType, ... A` -#### output: `A` -#### signature: `(let ((name1 expr1) (name2 expr2) ...) expr-body1 expr-body2 ... expr-body-last)` -#### description: -The `let` function accepts a list of `variable name` and `expression` pairs, evaluating each expression and _binding_ it to the corresponding variable name. `let` bindings are sequential: when a `let` binding is evaluated, it may refer to prior binding. The _context_ created by this set of bindings is used for evaluating its body expressions. The let expression returns the value of the last such body expression. Note: intermediary statements returning a response type must be checked` -#### example: -```clarity -(let ((a 2) (b (+ 5 6 7))) (print a) (print b) (+ a b)) ;; Returns 20 -(let ((a 5) (c (+ a 1)) (d (+ c 1)) (b (+ a c d))) (print a) (print b) (+ a b)) ;; Returns 23 -``` - -### map -#### input: `Function(A, B, ..., N) -> X, sequence_A, sequence_B, ..., sequence_N` -#### output: `(list X)` -#### signature: `(map func sequence_A sequence_B ... sequence_N)` -#### description: -Also, note that, no matter what kind of sequences the inputs are, the output is always a list. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. The `map` function applies the function `func` to each corresponding element of the input sequences, and outputs a _list_ of the same type containing the outputs from those function applications. -#### example: -```clarity -(map not (list true false true false)) ;; Returns (false true false true) -(map + (list 1 2 3) (list 1 2 3) (list 1 2 3)) ;; Returns (3 6 9) -(define-private (a-or-b (char (string-utf8 1))) (if (is-eq char u\"a\") u\"a\" u\"b\")) -(map a-or-b u\"aca\") ;; Returns (u\"a\" u\"b\" u\"a\") -(define-private (zero-or-one (char (buff 1))) (if (is-eq char 0x00) 0x00 0x01)) -(map zero-or-one 0x000102) ;; Returns (0x00 0x01 0x01) -``` - -### fold -#### input: `Function(A, B) -> B, sequence_A, B` -#### output: `B` -#### signature: `(fold func sequence_A initial_B)` -#### description: -The `fold` function condenses `sequence_A` into a value of type `B` by recursively applies the function `func` to each element of the input sequence _and_ the output of a previous application of `func`. - -`fold` uses `initial_B` in the initial application of `func`, along with the first element of `sequence_A`. The resulting value of type `B` is used for the next application of `func`, along with the next element of `sequence_A` and so on. `fold` returns the last value of type `B` returned by these successive applications `func`. - -Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. - -#### example: -```clarity -(fold * (list 2 2 2) 1) ;; Returns 8 -(fold * (list 2 2 2) 0) ;; Returns 0 -;; calculates (- 11 (- 7 (- 3 2))) -(fold - (list 3 7 11) 2) ;; Returns 5 -(define-private (concat-string (a (string-ascii 20)) (b (string-ascii 20))) (unwrap-panic (as-max-len? (concat a b) u20))) -(fold concat-string \"cdef\" \"ab\") ;; Returns \"fedcab\" -(fold concat-string (list \"cd\" \"ef\") \"ab\") ;; Returns \"efcdab\" -(define-private (concat-buff (a (buff 20)) (b (buff 20))) (unwrap-panic (as-max-len? (concat a b) u20))) -(fold concat-buff 0x03040506 0x0102) ;; Returns 0x060504030102 -``` - -### append -#### input: `list A, A` -#### output: `list` -#### signature: `(append (list 1 2 3 4) 5)` -#### description: -The `append` function takes a list and another value with the same entry type, and outputs a list of the same type with max_len += 1. -#### example: -```clarity -(append (list 1 2 3 4) 5) ;; Returns (1 2 3 4 5) -``` - -### concat -#### input: `sequence_A, sequence_A` -#### output: `sequence_A` -#### signature: `(concat sequence1 sequence2)` -#### description: -The `func` argument must be a literal function name. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. - -#### example: -```clarity -(concat (list 1 2) (list 3 4)) ;; Returns (1 2 3 4) -(concat \"hello \" \"world\") ;; Returns \"hello world\" -(concat 0x0102 0x0304) ;; Returns 0x01020304 -``` - -### as-max-len? -#### input: `sequence_A, uint` -#### output: `sequence_A` -#### signature: `(as-max-len? sequence max_length)` -#### description: -The `as-max-len?` function takes a sequence argument and a uint-valued, literal length argument. The function returns an optional type. If the input sequence length is less than or equal to the supplied max_length, this returns `(some sequence)`, otherwise it returns `none`. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. ` -#### example: -```clarity -(as-max-len? (list 2 2 2) u3) ;; Returns (some (2 2 2)) -(as-max-len? (list 1 2 3) u2) ;; Returns none -(as-max-len? \"hello\" u10) ;; Returns (some \"hello\") -(as-max-len? 0x010203 u10) ;; Returns (some 0x010203) -``` - -### len -#### input: `sequence_A` -#### output: `uint` -#### signature: `(len sequence)` -#### description: -The `len` function returns the length of a given sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. ` -#### example: -```clarity -(len \"blockstack\") ;; Returns u10 -(len (list 1 2 3 4 5)) ;; Returns u5 -(len 0x010203) ;; Returns u3 -``` - -### element-at -#### input: `sequence_A, uint` -#### output: `(optional A)` -#### signature: `(element-at sequence index)` -#### description: -The `element-at` function returns the element at `index` in the provided sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. ` -#### example: -```clarity -(element-at \"blockstack\" u5) ;; Returns (some \"s\") -(element-at (list 1 2 3 4 5) u5) ;; Returns none -(element-at (list 1 2 3 4 5) (+ u1 u2)) ;; Returns (some 4) -(element-at \"abcd\" u1) ;; Returns (some \"b\") -(element-at 0xfb01 u1) ;; Returns (some 0x01) -``` - -### index-of -#### input: `sequence_A, A` -#### output: `(optional uint)` -#### signature: `(index-of sequence item)` -#### description: -The `index-of` function returns the first index at which `item` can be found, using `is-eq` checks, in the provided sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. If the target item is not found in the sequence (or if an empty string or buffer is supplied), this function returns `none`. -#### example: -```clarity -(index-of \"blockstack\" \"b\") ;; Returns (some u0) -(index-of \"blockstack\" \"k\") ;; Returns (some u4) -(index-of \"blockstack\" \"\") ;; Returns none -(index-of (list 1 2 3 4 5) 6) ;; Returns none -(index-of 0xfb01 0x01) ;; Returns (some u1) -``` - -### list -#### input: `A, ...` -#### output: `(list A)` -#### signature: `(list expr1 expr2 expr3 ...)` -#### description: -The `list` function constructs a list composed of the inputted values. Each supplied value must be of the same type. -#### example: -```clarity -(list (+ 1 2) 4 5) ;; Returns (3 4 5) -``` - -### var-get -#### input: `VarName` -#### output: `A` -#### signature: `(var-get var-name)` -#### description: -The `var-get` function looks up and returns an entry from a contract's data map. The value is looked up using `var-name`. -#### example: -```clarity -(define-data-var cursor int 6) -(var-get cursor) ;; Returns 6 -``` - -### var-set -#### input: `VarName, AnyType` -#### output: `bool` -#### signature: `(var-set var-name expr1)` -#### description: -The `var-set` function sets the value associated with the input variable to the inputted value. The function always returns `true`. -#### example: -```clarity -(define-data-var cursor int 6) -(var-get cursor) ;; Returns 6 -(var-set cursor (+ (var-get cursor) 1)) ;; Returns true -(var-get cursor) ;; Returns 7 -``` - -### map-get? -#### input: `MapName, tuple` -#### output: `(optional (tuple))` -#### signature: `(map-get? map-name key-tuple)` -#### description: -The `map-get?` function looks up and returns an entry from a contract's data map. The value is looked up using `key-tuple`. If there is no value associated with that key in the data map, the function returns a `none` option. Otherwise, it returns `(some value)`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(map-get? names-map (tuple (name \"blockstack\"))) ;; Returns (some (tuple (id 1337))) -(map-get? names-map { name: \"blockstack\" }) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-set -#### input: `MapName, tuple_A, tuple_B` -#### output: `bool` -#### signature: `(map-set map-name key-tuple value-tuple)` -#### description: -The `map-set` function sets the value associated with the input key to the inputted value. This function performs a _blind_ update; whether or not a value is already associated with the key, the function overwrites that existing association. - -Note: the `value-tuple` requires 1 additional byte for storage in the materialized blockchain state, and therefore the maximum size of a value that may be inserted into a map is MAX_CLARITY_VALUE - 1. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-set names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-insert -#### input: `MapName, tuple_A, tuple_B` -#### output: `bool` -#### signature: `(map-insert map-name key-tuple value-tuple)` -#### description: -The `map-insert` function sets the value associated with the input key to the inputted value if and only if there is not already a value associated with the key in the map. If an insert occurs, the function returns `true`. If a value already existed for this key in the data map, the function returns `false`. - -Note: the `value-tuple` requires 1 additional byte for storage in the materialized blockchain state, and therefore the maximum size of a value that may be inserted into a map is MAX_CLARITY_VALUE - 1. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns false -(map-insert names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-delete -#### input: `MapName, tuple` -#### output: `bool` -#### signature: `(map-delete map-name key-tuple)` -#### description: -The `map-delete` function removes the value associated with the input key for the given map. If an item exists and is removed, the function returns `true`. If a value did not exist for this key in the data map, the function returns `false`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-delete names-map { name: \"blockstack\" }) ;; Returns true -(map-delete names-map { name: \"blockstack\" }) ;; Returns false -(map-delete names-map (tuple (name \"blockstack\"))) ;; Same command, using a shorthand for constructing the tuple -``` - -### tuple -#### input: `(key-name A), (key-name-2 B), ...` -#### output: `(tuple (key-name A) (key-name-2 B) ...)` -#### signature: `(tuple (key0 expr0) (key1 expr1) ...)` -#### description: -The `tuple` special form constructs a typed tuple from the supplied key and expression pairs. A `get` function can use typed tuples as input to select specific values from a given tuple. Key names may not appear multiple times in the same tuple definition. Supplied expressions are evaluated and associated with the expressions' paired key name. - -There is a shorthand using curly brackets of the form {key0: expr0, key1: expr, ...}` -#### example: -```clarity -(tuple (name \"blockstack\") (id 1337)) ;; using tuple -{name: \"blockstack\", id: 1337} ;; using curly brackets -``` - -### get -#### input: `KeyName, (tuple) | (optional (tuple))` -#### output: `A` -#### signature: `(get key-name tuple)` -#### description: -The `get` function fetches the value associated with a given key from the supplied typed tuple. If an `Optional` value is supplied as the inputted tuple, `get` returns an `Optional` type of the specified key in the tuple. If the supplied option is a `(none)` option, get returns `(none)`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(get id (tuple (name \"blockstack\") (id 1337))) ;; Returns 1337 -(get id (map-get? names-map (tuple (name \"blockstack\")))) ;; Returns (some 1337) -(get id (map-get? names-map (tuple (name \"non-existent\")))) ;; Returns none -``` - -### merge -#### input: `tuple, tuple` -#### output: `tuple` -#### signature: `(merge tuple { key1: val1 })` -#### description: -The `merge` function returns a new tuple with the combined fields, without mutating the supplied tuples. -#### example: -```clarity -(define-map users { id: int } { name: (string-ascii 12), address: (optional principal) }) -(map-insert users { id: 1337 } { name: \"john\", address: none }) ;; Returns true -(let ((user (unwrap-panic (map-get? users { id: 1337 })))) -(merge user { address: (some 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) })) ;; Returns (tuple (address (some SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF)) (name \"john\")) -``` - -### begin -#### input: `AnyType, ... A` -#### output: `A` -#### signature: `(begin expr1 expr2 expr3 ... expr-last)` -#### description: -The `begin` function evaluates each of its input expressions, returning the return value of the last such expression. Note: intermediary statements returning a response type must be checked. -#### example: -```clarity -(begin (+ 1 2) 4 5) ;; Returns 5 -``` - -### hash160 -#### input: `buff|uint|int` -#### output: `(buff 20)` -#### signature: `(hash160 value)` -#### description: -The `hash160` function computes `RIPEMD160(SHA256(x))` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(hash160 0) ;; Returns 0xe4352f72356db555721651aa612e00379167b30f -``` - -### sha256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(sha256 value)` -#### description: -The `sha256` function computes `SHA256(x)` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(sha256 0) ;; Returns 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb -``` - -### sha512 -#### input: `buff|uint|int` -#### output: `(buff 64)` -#### signature: `(sha512 value)` -#### description: -The `sha512` function computes `SHA512(x)` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(sha512 1) ;; Returns 0x6fcee9a7b7a7b821d241c03c82377928bc6882e7a08c78a4221199bfa220cdc55212273018ee613317c8293bb8d1ce08d1e017508e94e06ab85a734c99c7cc34 -``` - -### sha512/256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(sha512/256 value)` -#### description: -The `sha512/256` function computes `SHA512/256(x)` (the SHA512 algorithm with the 512/256 initialization vector, truncated to 256 bits) of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(sha512/256 1) ;; Returns 0x515a7e92e7c60522db968d81ff70b80818fc17aeabbec36baf0dda2812e94a86 -``` - -### keccak256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(keccak256 value)` -#### description: -The `keccak256` function computes `KECCAK256(value)` of the inputted value. Note that this differs from the `NIST SHA-3` (that is, FIPS 202) standard. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(keccak256 0) ;; Returns 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4 -``` - -### secp256k1-recover? -#### input: `(buff 32), (buff 65)` -#### output: `(response (buff 33) uint)` -#### signature: `(secp256k1-recover? message-hash signature)` -#### description: -The `secp256k1-recover?` function recovers the public key used to sign the message which sha256 is `message-hash` with the provided `signature`. If the signature does not match, it will return the error code `(err u1).`. If the signature is invalid, it will return the error code `(err u2).`. The signature includes 64 bytes plus an additional recovery id (00..03) for a total of 65 bytes. -#### example: -```clarity -(secp256k1-recover? 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a1301) - ;; Returns (ok 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) - ``` - -### secp256k1-verify -#### input: `(buff 32), (buff 64) | (buff 65), (buff 33)` -#### output: `bool` -#### signature: `(secp256k1-verify message-hash signature public-key)` -#### description: -The `secp256k1-verify` function verifies that the provided signature of the message-hash was signed with the private key that generated the public key. The `message-hash` is the `sha256` of the message. The signature includes 64 bytes plus an optional additional recovery id (00..03) for a total of 64 or 65 bytes. -#### example: -```clarity -(secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a1301 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns true -(secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a13 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns true -(secp256k1-verify 0x0000000000000000000000000000000000000000000000000000000000000000 - 0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns false - ``` - -### print -#### input: `A` -#### output: `A` -#### signature: `(print expr)` -#### description: -The `print` function evaluates and returns its input expression. On Stacks Core nodes configured for development (as opposed to production mining nodes), this function prints the resulting value to `STDOUT` (standard output). -#### example: -```clarity -(print (+ 1 2 3)) ;; Returns 6 -``` - -### contract-call? -#### input: `ContractName, PublicFunctionName, Arg0, ...` -#### output: `(response A B)` -#### signature: `(contract-call? .contract-name function-name arg0 arg1 ...)` -#### description: -The `contract-call?` function executes the given public function of the given contract. You _may not_ use this function to call a public function defined in the current contract. If the public function returns _err_, any database changes resulting from calling `contract-call?` are aborted. If the function returns _ok_, database changes occurred. -#### example: -```clarity - -;; instantiate the sample-contracts/tokens.clar contract first! -(as-contract (contract-call? .tokens mint! u19)) ;; Returns (ok u19) -``` - -### as-contract -#### input: `A` -#### output: `A` -#### signature: `(as-contract expr)` -#### description: -The `as-contract` function switches the current context's `tx-sender` value to the _contract's_ principal and executes `expr` with that context. It returns the resulting value of `expr`. -#### example: -```clarity -(as-contract tx-sender) ;; Returns S1G2081040G2081040G2081040G208105NK8PE5.docs-test -``` - -### contract-of -#### input: `Trait` -#### output: `principal` -#### signature: `(contract-of .contract-name)` -#### description: -The `contract-of` function returns the principal of the contract implementing the trait. -#### example: -```clarity -(use-trait token-a-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) -(define-public (forward-get-balance (user principal) (contract )) - (begin - (ok (contract-of contract)))) ;; returns the principal of the contract implementing -``` - -### principal-of? -#### input: `(buff 33)` -#### output: `(response principal uint)` -#### signature: `(principal-of? public-key)` -#### description: -The `principal-of?` function returns the principal derived from the provided public key. If the `public-key` is invalid, it will return the error code `(err u1).`. ` -#### example: -```clarity -(principal-of? 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns (ok ST1AW6EKPGT61SQ9FNVDS17RKNWT8ZP582VF9HSCP) -``` - -### at-block -#### input: `(buff 32), A` -#### output: `A` -#### signature: `(at-block id-block-hash expr)` -#### description: -The `at-block` function evaluates the expression `expr` _as if_ it were evaluated at the end of the block indicated by the _block-hash_ argument. The `expr` closure must be read-only. - -This hash uniquely identifies Stacks blocks and is unique across Stacks forks. Note: The block identifying hash must be a hash returned by the `id-header-hash` block information property. While the hash returned by `header-hash` is unique within the context of a single fork, it is not unique across Stacks forks. - -The function returns the result of evaluating `expr`. - -#### example: -```clarity -(define-data-var data int 1) -(at-block 0x0000000000000000000000000000000000000000000000000000000000000000 block-height) ;; Returns u0 -(at-block (get-block-info? id-header-hash 0) (var-get data)) ;; Throws NoSuchDataVariable because `data` wasn't initialized at block height 0 -``` - -### get-block-info? -#### input: `BlockInfoPropertyName, BlockHeightInt` -#### output: `(optional buff) | (optional uint)` -#### signature: `(get-block-info? prop-name block-height-expr)` -#### description: -The `get-block-info?` function fetches data for a block of the given block height. The value and type returned are determined by the specified `BlockInfoPropertyName`. If the provided `BlockHeightInt` does not correspond to an existing block prior to the current block, the function returns `none`. The currently available property names are `time`, `header-hash`, `burnchain-header-hash`, `id-header-hash`, `miner-address`, and `vrf-seed`. - -This is a Unix epoch timestamp in seconds which roughly corresponds to when the block was mined. The `time` property returns an integer value of the block header time field. **Warning**: this does not increase monotonically with each block and block times are accurate only to within two hours. See [BIP113](https://github.com/bitcoin/bips/blob/master/bip-0113.mediawiki) for more information. - -The `header-hash`, `burnchain-header-hash`, `id-header-hash`, and `vrf-seed` properties return a 32-byte buffer. - -The `miner-address` property returns a `principal` corresponding to the miner of the given block. - -The `id-header-hash` is the block identifier value that must be used as input to the `at-block` function. - -#### example: -```clarity -(get-block-info? time u0) ;; Returns (some u1557860301) -(get-block-info? header-hash u0) ;; Returns (some 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb) -(get-block-info? vrf-seed u0) ;; Returns (some 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4) -``` - -### err -#### input: `A` -#### output: `(response A B)` -#### signature: `(err value)` -#### description: -The `err` function constructs a response type from the input value. Use `err` for creating return values in public functions. An _err_ value indicates that any database changes during the processing of the function should be rolled back. -#### example: -```clarity -(err true) ;; Returns (err true) -``` - -### ok -#### input: `A` -#### output: `(response A B)` -#### signature: `(ok value)` -#### description: -The `ok` function constructs a response type from the input value. Use `ok` for creating return values in public functions. An _ok_ value indicates that any database changes during the processing of the function should materialize. -#### example: -```clarity -(ok 1) ;; Returns (ok 1) -``` - -### some -#### input: `A` -#### output: `(optional A)` -#### signature: `(some value)` -#### description: -The `some` function constructs a `optional` type from the input value. -#### example: -```clarity -(some 1) ;; Returns (some 1) -(is-none (some 2)) ;; Returns false -``` - -### default-to -#### input: `A, (optional A)` -#### output: `A` -#### signature: `(default-to default-value option-value)` -#### description: -The `default-to` function attempts to 'unpack' the second argument: if the argument is a `(some ...)` option, it returns the inner value of the option. If the second argument is a `(none)` value, `default-to` it returns the value of `default-value`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(default-to 0 (get id (map-get? names-map (tuple (name \"blockstack\"))))) ;; Returns 1337 -(default-to 0 (get id (map-get? names-map (tuple (name \"non-existant\"))))) ;; Returns 0 -``` - -### asserts! -#### input: `bool, C` -#### output: `bool` -#### signature: `(asserts! bool-expr thrown-value)` -#### description: -The `asserts!` function admits a boolean argument and asserts its evaluation: if bool-expr is `true`, `asserts!` returns `true` and proceeds in the program execution. If the supplied argument is returning a false value, `asserts!` _returns_ `thrown-value` and exits the current control-flow. -#### example: -```clarity -(asserts! (is-eq 1 1) (err 1)) ;; Returns true -``` - -### unwrap! -#### input: `(optional A) | (response A B), C` -#### output: `A` -#### signature: `(unwrap! option-input thrown-value)` -#### description: -The `unwrap!` function attempts to 'unpack' the first argument: if the argument is an option type, and the argument is a `(some ...)` option, `unwrap!` returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, `unwrap!` returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `(none)` value, `unwrap!` _returns_ `thrown-value` from the current function and exits the current control-flow. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(define-private (get-name-or-err (name (string-ascii 12))) - (let ((raw-name (unwrap! (define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(define-private (get-name-or-err (name (string-ascii 12))) - (let ((raw-name (unwrap! names-map { name: name }) (err 1)))) - (ok raw-name))) - -(get-name-or-err \"blockstack\") ;; Returns (ok (tuple (id 1337))) -(get-name-or-err \"non-existant\") ;; Returns (err 1) -``` - -### unwrap-err! -#### input: `(response A B), C` -#### output: `B` -#### signature: `(unwrap-err! response-input thrown-value)` -#### description: -The `unwrap-err!` function attempts to 'unpack' the first argument: if the argument is an `(err ...)` response, `unwrap-err!` returns the inner value of the `err`. If the supplied argument is an `(ok ...)` value, `unwrap-err!` _returns_ `thrown-value` from the current function and exits the current control-flow. -#### example: -```clarity -(unwrap-err! (err 1) false) ;; Returns 1 -``` - -### unwrap-panic -#### input: `(optional A) | (response A B)` -#### output: `A` -#### signature: `(unwrap-panic option-input)` -#### description: -The `unwrap` function attempts to 'unpack' its argument: if the argument is an option type, and the argument is a `(some ...)` option, this function returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, it returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `(none)` value, `unwrap` throws a runtime error, aborting any further processing of the current transaction. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(unwrap-panic (map-get? names-map { name: \"blockstack\" })) ;; Returns (tuple (id 1337)) -(unwrap-panic (map-get? names-map { name: \"non-existant\" })) ;; Throws a runtime exception -``` - -### unwrap-err-panic -#### input: `(response A B)` -#### output: `B` -#### signature: `(unwrap-err-panic response-input)` -#### description: -The `unwrap-err` function attempts to 'unpack' the first argument: if the argument is an `(err ...)` response, `unwrap` returns the inner value of the `err`. If the supplied argument is an `(ok ...)` value, `unwrap-err` throws a runtime error, aborting any further processing of the current transaction. -#### example: -```clarity -(unwrap-err-panic (err 1)) ;; Returns 1 -(unwrap-err-panic (ok 1)) ;; Throws a runtime exception -``` - -### match -#### input: `(optional A) name expression expression | (response A B) name expression name expression` -#### output: `C` -#### signature: `(match opt-input some-binding-name some-branch none-branch) | -(match-resp input ok-binding-name ok-branch err-binding-name err-branch)` -#### description: -The `match` function is used to test and destructure optional and response types. - -If the `input` is an optional, it tests whether the provided `input` is a `some` or `none` option, and evaluates `some-branch` or `none-branch` in each respective case. - -Within the `some-branch`, the _contained value_ of the `input` argument is bound to the provided `some-binding-name` name. - -Only _one_ of the branches will be evaluated (similar to `if` statements). - -If the `input` is a response, it tests whether the provided `input` is an `ok` or `err` response type, and evaluates `ok-branch` or `err-branch` in each respective case. - -Within the `ok-branch`, the _contained ok value_ of the `input` argument is bound to the provided `ok-binding-name` name. - -Within the `err-branch`, the _contained err value_ of the `input` argument is bound to the provided `err-binding-name` name. - -Only _one_ of the branches will be evaluated (similar to `if` statements). - -Note: Type checking requires that the type of both the ok and err parts of the response object be determinable. For situations in which one of the parts of a response is untyped, you should use `unwrap-panic` or `unwrap-err-panic` instead of `match`. -#### example: -```clarity - -(define-private (add-10 (x (optional int))) - (match x - value (+ 10 value) - 10)) -(add-10 (some 5)) ;; Returns 15 -(add-10 none) ;; Returns 10 - -(define-private (add-or-pass-err (x (response int (string-ascii 10))) (to-add int)) - (match x - value (ok (+ to-add value)) - err-value (err err-value))) -(add-or-pass-err (ok 5) 20) ;; Returns (ok 25) -(add-or-pass-err (err \"ERROR\") 20) ;; Returns (err \"ERROR\") -``` - -### try! -#### input: `(optional A) | (response A B)` -#### output: `A` -#### signature: `(try! option-input)` -#### description: -The `try!` function attempts to 'unpack' the first argument: if the argument is an option type, and the argument is a `(some ...)` option, `try!` returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, `try!` returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `none` value, `try!` _returns_ either `none` or the `(err ...)` value from the current function and exits the current control-flow. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(try! (define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(define-private (get-name-or-err (name (string-ascii 12))) - (let ((raw-name (unwrap! names-map { name: \"blockstack\" })) ;; Returns (tuple (id 1337)) -(define-private (checked-even (x int)) - (if (is-eq (mod x 2) 0) - (ok x) - (err false))) -(define-private (double-if-even (x int)) - (ok (* 2 (try! (checked-even x))))) -(double-if-even 10) ;; Returns (ok 20) -(double-if-even 3) ;; Returns (err false) -``` - -### is-ok -#### input: `(response A B)` -#### output: `bool` -#### signature: `(is-ok value)` -#### description: -`is-ok` tests a supplied response value, returning `true` if the response was `ok`, and `false` if it was an `err`. -#### example: -```clarity -(is-ok (ok 1)) ;; Returns true -(is-ok (err 1)) ;; Returns false -``` - -### is-none -#### input: `(optional A)` -#### output: `bool` -#### signature: `(is-none value)` -#### description: -`is-none` tests a supplied option value, returning `true` if the option value is `(none)`, and `false` if it is a `(some ...)`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(is-none (get id (map-get? names-map { name: \"blockstack\" }))) ;; Returns false -(is-none (get id (map-get? names-map { name: \"non-existant\" }))) ;; Returns true -``` - -### is-err -#### input: `(response A B)` -#### output: `bool` -#### signature: `(is-err value)` -#### description: -`is-err` tests a supplied response value, returning `true` if the response was an `err`, and `false` if it was an `ok`. -#### example: -```clarity -(is-err (ok 1)) ;; Returns false -(is-err (err 1)) ;; Returns true -``` - -### is-some -#### input: `(optional A)` -#### output: `bool` -#### signature: `(is-some value)` -#### description: -`is-some` tests a supplied option value, returning `true` if the option value is `(some ...)`, and `false` if it is a `none`. -#### example: -```clarity - -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(is-some (get id (map-get? names-map { name: \"blockstack\" }))) ;; Returns true -(is-some (get id (map-get? names-map { name: \"non-existant\" }))) ;; Returns false -``` - -### filter -#### input: `Function(A) -> bool, sequence_A` -#### output: `sequence_A` -#### signature: `(filter func sequence)` -#### description: -The `filter` function applies the input function `func` to each element of the input sequence, and returns the same sequence with any elements removed for which `func` returned `false`. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. ` -#### example: -```clarity - -(filter not (list true false true false)) ;; Returns (false false) -(define-private (is-a (char (string-utf8 1))) (is-eq char u\"a\")) -(filter is-a u\"acabd\") ;; Returns u\"aa\" -(define-private (is-zero (char (buff 1))) (is-eq char 0x00)) -(filter is-zero 0x00010002) ;; Returns 0x0000 -``` - -### ft-get-balance -#### input: `TokenName, principal` -#### output: `uint` -#### signature: `(ft-get-balance token-name principal)` -#### description: -`ft-get-balance` returns `token-name` balance of the principal `principal`. The token type must have been defined using `define-fungible-token`. -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-get-balance stackaroo 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns u100 -``` - -### nft-get-owner? -#### input: `AssetName, A` -#### output: `(optional principal)` -#### signature: `(nft-get-owner? asset-class asset-identifier)` -#### description: -`nft-get-owner?` returns the owner of an asset, identified by `asset-identifier`, or `none` if the asset does not exist. The asset type must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) -(nft-get-owner? stackaroo \"Roo\") ;; Returns (some SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) -(nft-get-owner? stackaroo \"Too\") ;; Returns none -``` - -### ft-transfer? -#### input: `TokenName, uint, principal, principal` -#### output: `(response bool uint)` -#### signature: `(ft-transfer? token-name amount sender recipient)` -#### description: -`ft-transfer?` is used to increase the token balance for the `recipient` principal for a token type defined using `define-fungible-token` by debiting the `sender` principal. In contrast to `stx-transfer?`, any user can transfer the assets. When used, relevant guards need to be added. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- amount to send is non-positive ` -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-transfer? stackaroo u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(ft-transfer? stackaroo u60 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u1) -``` - -### nft-transfer? -#### input: `AssetName, A, principal, principal` -#### output: `(response bool uint)` -#### signature: `(nft-transfer? asset-class asset-identifier sender recipient)` -#### description: -`nft-transfer?` is used to change the owner of an asset identified by `asset-identifier` from `sender` to `recipient`. The `asset-class` must have been defined by `define-non-fungible-token` and `asset-identifier` must be of the type specified in that definition. In contrast to `stx-transfer?`, any user can transfer the asset. When used, relevant guards need to be added. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not own the asset `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- asset identified by asset-identifier does not exist ` -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(nft-transfer? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(nft-transfer? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u1) -(nft-transfer? stackaroo \"Stacka\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u3) -``` - -### nft-mint? -#### input: `AssetName, A, principal` -#### output: `(response bool uint)` -#### signature: `(nft-mint? asset-class asset-identifier recipient)` -#### description: -`nft-mint?` is used to instantiate an asset and set that asset's owner to the `recipient` principal. The asset must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. - -If an asset identified by `asset-identifier` _already exists_, this function will return an error with the following error code: - -`(err u1)` - -Otherwise, on successfuly mint, it returns `(ok true)`. ` -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### ft-mint? -#### input: `TokenName, uint, principal` -#### output: `(response bool uint)` -#### signature: `(ft-mint? token-name amount recipient)` -#### description: -`ft-mint?` is used to increase the token balance for the `recipient` principal for a token type defined using `define-fungible-token`. The increased token balance is _not_ transfered from another principal, but rather minted. - -If a non-positive amount is provided to mint, this function returns `(err 1)`. Otherwise, on successfuly mint, it returns `(ok true)`. ` -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### ft-get-supply -#### input: `TokenName` -#### output: `uint` -#### signature: `(ft-get-supply token-name)` -#### description: -`ft-get-balance` returns `token-name` circulating supply. The token type must have been defined using `define-fungible-token`. -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-get-supply stackaroo) ;; Returns u100 -``` - -### ft-burn? -#### input: `TokenName, uint, principal` -#### output: `(response bool uint)` -#### signature: `(ft-burn? token-name amount sender)` -#### description: -`ft-burn?` is used to decrease the token balance for the `sender` principal for a token type defined using `define-fungible-token`. The decreased token balance is _not_ transfered to another principal, but rather destroyed, reducing the circulating supply. - -If a non-positive amount is provided to burn, this function returns `(err 1)`. Otherwise, on successfuly burn, it returns `(ok true)`. - -#### example: -```clarity - -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(ft-burn? stackaroo u50 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### nft-burn? -#### input: `AssetName, A, principal` -#### output: `(response bool uint)` -#### signature: `(nft-burn? asset-class asset-identifier recipient)` -#### description: -`nft-burn?` is used to burn an asset and remove that asset's owner from the `recipient` principal. The asset must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. - -If an asset identified by `asset-identifier` _doesn't exist_, this function will return an error with the following error code: - -`(err u1)` - -Otherwise, on successfuly burn, it returns `(ok true)`. ` -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(nft-burn? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### stx-get-balance -#### input: `principal` -#### output: `uint` -#### signature: `(stx-get-balance owner)` -#### description: -`stx-get-balance` is used to query the STX balance of the `owner` principal. - -This function returns the STX balance of the `owner` principal. In the event that the `owner` principal isn't materialized, it returns 0. - -#### example: -```clarity -(stx-get-balance 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns u0 -(stx-get-balance (as-contract tx-sender)) ;; Returns u1000 -``` - -### stx-transfer? -#### input: `uint, principal, principal` -#### output: `(response bool uint)` -#### signature: `(stx-transfer? amount sender recipient)` -#### description: -`stx-transfer?` is used to increase the STX balance for the `recipient` principal by debiting the `sender` principal. The `sender` principal _must_ be equal to the current context's `tx-sender`. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- amount to send is non-positive `(err u4)` -- the `sender` principal is not the current `tx-sender` - -#### example: -```clarity - -(as-contract - (stx-transfer? u60 tx-sender 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (ok true) -(as-contract - (stx-transfer? u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR tx-sender)) ;; Returns (err u4) -``` - -### stx-burn? -#### input: `uint, principal` -#### output: `(response bool uint)` -#### signature: `(stx-burn? amount sender)` -#### description: -`stx-burn?` debits the `sender` principal's STX holdings by `amount`, destroying the STX. The `sender` principal _must_ be equal to the current context's `tx-sender`. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u3)` -- amount to send is non-positive `(err u4)` -- the `sender` principal is not the current `tx-sender` - -#### example: -```clarity -(as-contract - (stx-burn? u60 tx-sender)) ;; Returns (ok true) -(as-contract - (stx-burn? u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (err u4) -``` - -### define-constant -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-constant name expression)` -#### description: -`define-constant` is used to define a private constant value in a smart contract. The expression passed into the definition is evaluated at contract launch, in the order that it is supplied in the contract. This can lead to undefined function or undefined variable errors in the event that a function or variable used in the expression has not been defined before the constant. - -Like other kinds of definition statements, `define-constant` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -#### example: -```clarity - -(define-constant four (+ 2 2)) -(+ 4 four) ;; Returns 8 -``` - -### define-private -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-private (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### description: -`define-private` is used to define _private_ functions for a smart contract. Private functions may not be called from other smart contracts, nor may they be invoked directly by users. Instead, these functions may only be invoked by other functions defined in the same smart contract. - -Like other kinds of definition statements, `define-private` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Private functions may return any type. -#### example: -```clarity -(define-private (max-of (i1 int) (i2 int)) - (if (> i1 i2) - i1 - i2)) -(max-of 4 6) ;; Returns 6 -``` - -### define-public -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-public (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### description: -`define-public` is used to define a _public_ function and transaction for a smart contract. Public functions are callable from other smart contracts and may be invoked directly by users by submitting a transaction to the Stacks blockchain. - -Like other kinds of definition statements, `define-public` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Public functions _must_ return a ResponseType (using either `ok` or `err`). Any datamap modifications performed by a public function is aborted if the function returns an `err` type. Public functions may be invoked by other contracts via `contract-call?`. -#### example: -```clarity -(define-public (hello-world (input int)) - (begin (print (+ 2 input)) - (ok input))) -``` - -### define-read-only -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-read-only (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### description: -`define-read-only` is used to define a _public read-only_ function for a smart contract. Such functions are callable from other smart contracts. - -Like other kinds of definition statements, `define-read-only` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Read-only functions may return any type. However, read-only functions may not perform any datamap modifications, or call any functions which perform such modifications. This is enforced both during type checks and during the execution of the function. Public read-only functions may be invoked by other contracts via `contract-call?`. -#### example: -```clarity -(define-read-only (just-return-one-hundred) - (* 10 10)) - ``` - -### define-map -#### input: `MapName, TypeDefinition, TypeDefinition` -#### output: `Not Applicable` -#### signature: `(define-map map-name key-type value-type)` -#### description: -`define-map` is used to define a new datamap for use in a smart contract. Such maps are only modifiable by the current smart contract. - -Maps are defined with a key type and value type, often these types are tuple types. - -Like other kinds of definition statements, `define-map` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). -#### example: -```clarity -(define-map squares { x: int } { square: int }) -(define-private (add-entry (x int)) - (map-insert squares { x: 2 } { square: (* x x) })) -(add-entry 1) -(add-entry 2) -(add-entry 3) -(add-entry 4) -(add-entry 5) -``` - -### define-data-var -#### input: `VarName, TypeDefinition, Value` -#### output: `Not Applicable` -#### signature: `(define-data-var var-name type value)` -#### description: -`define-data-var` is used to define a new persisted variable for use in a smart contract. Such variable are only modifiable by the current smart contract. - -Persisted variable are defined with a type and a value. - -Like other kinds of definition statements, `define-data-var` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). -#### example: -```clarity -(define-data-var size int 0) -(define-private (set-size (value int)) - (var-set size value)) -(set-size 1) -(set-size 2) -``` - -### define-fungible-token -#### input: `TokenName, ` -#### output: `Not Applicable` -#### signature: `(define-fungible-token token-name )` -#### description: -`define-fungible-token` is used to define a new fungible token class for use in the current contract. - -The second argument, if supplied, defines the total supply of the fungible token. This ensures that all calls to the `ft-mint?` function will never be able to create more than `total-supply` tokens. If any such call were to increase the total supply of tokens passed that amount, that invocation of `ft-mint?` will result in a runtime error and abort. - -Like other kinds of definition statements, `define-fungible-token` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Tokens defined using `define-fungible-token` may be used in `ft-transfer?`, `ft-mint?`, and `ft-get-balance` functions` -#### example: -```clarity -(define-fungible-token stacks) -(define-fungible-token limited-supply-stacks u100) -``` - -### define-non-fungible-token -#### input: `AssetName, TypeSignature` -#### output: `Not Applicable` -#### signature: `(define-non-fungible-token asset-name asset-identifier-type)` -#### description: -`define-non-fungible-token` is used to define a new non-fungible token class for use in the current contract. Individual assets are identified by their asset identifier, which must be of the type `asset-identifier-type`. Asset identifiers are _unique_ identifiers. - -Like other kinds of definition statements, `define-non-fungible-token` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Assets defined using `define-non-fungible-token` may be used in `nft-transfer?`, `nft-mint?`, and `nft-get-owner?` functions` -#### example: -```clarity -(define-non-fungible-token names (buff 50)) -``` - -### define-trait -#### input: `VarName, [MethodSignature]` -#### output: `Not Applicable` -#### signature: `(define-trait trait-name ((func1-name (arg1-type arg2-type ...) (return-type))))` -#### description: -`define-trait` is used to define a new trait definition for use in a smart contract. Other contracts can implement a given trait and then have their contract identifier being passed as function arguments in order to be called dynamically with `contract-call?`. - -Traits are defined with a name, and a list functions defined with a name, a list of argument types, and return type. - -Like other kinds of definition statements, `define-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -#### example: -```clarity -(define-trait token-trait - ((transfer? (principal principal uint) (response uint uint)) - (get-balance (principal) (response uint uint)))) -``` - -### use-trait -#### input: `VarName, TraitIdentifier` -#### output: `Not Applicable` -#### signature: `(use-trait trait-alias trait-identifier)` -#### description: -`use-trait` is used to bring a trait, defined in another contract, to the current contract. Subsequent references to an imported trait are signaled with the syntax ``. - -Traits import are defined with a name, used as an alias, and a trait identifier. Trait identifiers can either be using the sugared syntax (.token-a.token-trait), or be fully qualified ('SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait). - -Like other kinds of definition statements, `use-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put such a statement in the middle of a function body). -#### example: -```clarity -(use-trait token-a-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) -(define-public (forward-get-balance (user principal) (contract )) - (begin - (ok 1))) -``` - -### impl-trait -#### input: `TraitIdentifier` -#### output: `Not Applicable` -#### signature: `(impl-trait trait-identifier)` -#### description: -`impl-trait` can be use for asserting that a contract is fully implementing a given trait. Additional checks are being performed when the contract is being published, rejecting the deployment if the contract is violating the trait specification. - -Trait identifiers can either be using the sugared syntax (.token-a.token-trait), or be fully qualified ('SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait). - -Like other kinds of definition statements, `impl-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put such a statement in the middle of a function body). - -#### example: -```clarity -(impl-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) (define-public (get-balance (account principal)) (ok u0)) (define-public (transfer? (from principal) (to principal) (amount uint)) - (ok u0)) -``` \ No newline at end of file diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md b/i18n/fr/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md deleted file mode 100644 index fd62451198..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Keywords -description: See a detailed list of all keywords for the Clarity language. -tags: - - clarity ---- - -![](/img/keywords.jpg) -## Keyword reference - -Detailed list of all keywords for the Clarity language. - - -### contract-caller -#### output: `principal` -#### description: -Returns the caller of the current contract context. If this contract is the first one called by a signed transaction, the caller will be equal to the signing principal. If `contract-call?` was used to invoke a function from a new contract, `contract-caller` changes to the _calling_ contract's principal. If `as-contract` is used to change the `tx-sender` context, `contract-caller` _also_ changes to the same contract principal. -#### example: -```clarity -(print contract-caller) ;; Will print out a Stacks address of the transaction sender -``` - -### tx-sender -#### output: `principal` -#### description: -Returns the original sender of the current transaction, or if `as-contract` was called to modify the sending context, it returns that contract principal. -#### example: -```clarity -(print tx-sender) ;; Will print out a Stacks address of the transaction sender -``` - -### block-height -#### output: `uint` -#### description: -Returns the current block height of the Stacks blockchain as an uint -#### example: -```clarity -(> block-height 1000) ;; returns true if the current block-height has passed 1000 blocks. -``` - -### burn-block-height -#### output: `uint` -#### description: -Returns the current block height of the underlying burn blockchain as a uint -#### example: -```clarity -(> burn-block-height 1000) ;; returns true if the current height of the underlying burn blockchain has passed 1000 blocks. -``` - -### none -#### output: `(optional ?)` -#### description: -Represents the _none_ option indicating no value for a given optional (analogous to a null value). -#### example: -```clarity -(define-public (only-if-positive (a int)) - (if (> a 0) - (some a) - none)) -(only-if-positive 4) ;; Returns (some 4) -(only-if-positive (- 3)) ;; Returns none -``` - -### true -#### output: `bool` -#### description: -Boolean true constant. -#### example: -```clarity -(and true false) ;; Evaluates to false -(or false true) ;; Evaluates to true -``` - -### false -#### output: `bool` -#### description: -Boolean false constant. -#### example: -```clarity -(and true false) ;; Evaluates to false -(or false true) ;; Evaluates to true -``` - -### stx-liquid-supply -#### output: `uint` -#### description: -Returns the total number of micro-STX (uSTX) that are liquid in the system as of this block. -#### example: -```clarity -(print stx-liquid-supply) ;; Will print out the total number of liquid uSTX -``` - -### is-in-regtest -#### output: `bool` -#### description: -Returns whether or not the code is running in a regression test -#### example: -```clarity -(print is-in-regtest) ;; Will print 'true' if the code is running in a regression test -``` - diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md b/i18n/fr/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md deleted file mode 100644 index d22f991413..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Types -description: See a detailed list of all types for the Clarity language. -tags: - - clarity ---- - -## Clarity Type System - -The type system contains the following types: - -| Types | Notes | -| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `int` | signed 128-bit integer | -| `uint` | unsigned 128-bit integer | -| `bool` | boolean value (`true` or `false`) | -| `principal` | object representing a principal (whether a contract principal or standard principal) | -| `(buff max-len)` | byte buffer of 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` (u"A smiley face emoji \u{1F600} as a utf8 string") | -| `(list max-len entry-type)` | list of maximum length `max-len`, with entries of type `entry-type` | -| `{label-0: value-type-0, label-1: value-type-1, ...}` | tuple, group of data values with named fields | -| `(optional some-type)` | an option type for objects that can either be `(some value)` or `none` | -| `(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. | diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md b/i18n/fr/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md deleted file mode 100644 index e75e1d69b9..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Clarity overview -description: Overview and guides for getting started with Clarity -sidebar_label: Write smart contracts -sidebar_position: 2 ---- - -## Introduction - -Clarity is a **decidable** smart contract language that optimizes for predictability and security, designed for the Stacks blockchain. Smart contracts allow developers to encode essential business logic on a blockchain. - -## Smart contracts - -Smart contracts encode and enforce rules for modifying a particular set of data that is shared among people and entities who don't necessarily trust each other. For example, a smart contract can hold funds in escrow until multiple parties agree to release them, create its own ledger and keep track of its own novel tokens (fungible or non-fungible), and even help make supply chains more transparent. - -A smart contract execution can result in new transactions being written to the blockchain. Because smart contracts are programs that exist in a blockchain, anyone can query them, and anyone can submit transactions to execute them. - -Apps can take advantage of smart contracts to manage a global state that is visible to the public. Anyone can audit the blockchain to independently verify that an app's global shared state has been managed correctly according to the smart contract's rules. - -There is a [Clarity Visual Studio Code plugin][] available for syntax assistance and debugging. - -## Use cases - -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 (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 - -## Language design - -Clarity differs from most other smart contract languages in two essential ways: - -- The language is interpreted and broadcast on the blockchain as is (not compiled) -- The language is decidable (not Turing complete) - -Using an interpreted language ensures that the executed code is human-readable and auditable. A decidable language like Clarity makes it possible to determine precisely which code is executed, for any function. - -A Clarity smart contract consists of two parts, a data space and a set of functions. Only the associated smart contract may modify its corresponding data space on the blockchain. Functions may be private and thus callable only from within the smart contract, or public and thus callable from other contracts. Users call smart contracts' public functions by broadcasting a transaction on the blockchain which invokes the public function. Contracts can also call public functions from other smart contracts. - -Note some of the key Clarity language rules and limitations. - -- The only primitive types are booleans, integers, buffers, and principals. -- Recursion is illegal and there are no anonymous functions. -- Looping is only performed via `map`, `filter`, or `fold`. -- There is support for lists, however, the only variable length lists in the language appear as function inputs; there is no support for list operations like append or join. -- Variables are immutable. - -## Explore more - -For language details and references, see the following: - -- [Clarity language overview](./clarity-language/) -- [Understating Principals](principals) -- [Clarity Values](values) - -[Clarity Visual Studio Code plugin]: https://marketplace.visualstudio.com/items?itemName=HiroSystems.clarity-lsp diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md b/i18n/fr/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md deleted file mode 100644 index 2482d174a7..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md +++ /dev/null @@ -1,240 +0,0 @@ ---- -title: Principals -description: 'Clarity: Understanding Principals' -sidebar_position: 1 ---- - -## Introduction - -_Principals_ are a Clarity native type that represents an entity that can have a token balance. This section discusses principals and how they are used in the Clarity. - -## Principals and tx-sender - -Assets in the smart contracting language and blockchain are "owned" by objects of the principal type, meaning that any object of the principal type may own an asset. For the case of public-key hash and multi-signature Stacks addresses, a given principal can operate on their assets by issuing a signed transaction on the blockchain. _Smart contracts_ may also be principals (represented by the smart contract's identifier), however, there is no private key associated with the smart contract, and it cannot broadcast a signed transaction on the blockchain. - -A Clarity contract can use a globally defined `tx-sender` variable to obtain the current principal. The following example defines a transaction type that transfers `amount` microSTX from the sender to a recipient if amount is a multiple of 10, otherwise returning a 400 error code. - -```clarity -(define-public (transfer-to-recipient! (recipient principal) (amount uint)) - (if (is-eq (mod amount 10) 0) - (stx-transfer? amount tx-sender recipient) - (err u400))) -``` - -Clarity provides an additional variable to help smart contracts authenticate a transaction sender. The keyword `contract-caller` returns the principal that _called_ the current contract. If an inter-contract call occurred, `contract-caller` returns the last contract in the stack of callers. For example, suppose there are three contracts A, B, and C, each with an `invoke` function such that `A::invoke` calls `B::invoke` and `B::invoke` calls `C::invoke`. - -When a user Bob issues a transaction that calls `A::invoke`, the value of `contract-caller` in each successive invoke function's body would change: - -```clarity -in A::invoke, contract-caller = Bob -in B::invoke, contract-caller = A -in C::invoke, contract-caller = B -``` - -This allows contracts to make assertions and perform authorization checks using not only the `tx-sender` (which in this example, would always be "Bob"), but also using the `contract-caller`. This could be used to ensure that a particular function is only ever called directly and never called via an inter-contract call (by asserting that `tx-sender` and `contract-caller` are equal). We provide an example of a two different types of authorization checks in the rocket ship example below. - -## Smart contracts as principals - -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, for example: - -```clarity -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-name -``` - -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 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 qualified identifier for the contracts would be: - -```clarity -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-A -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-B -``` - -But, in the contract source code, if the developer wishes to call a function from `contract-A` in `contract-B`, they can write - -```clarity -(contract-call? .contract-A public-function-foo) -``` - -This allows the smart contract developer to modularize their applications across multiple smart contracts _without_ knowing the publishing key a priori. - -In order for a smart contract to operate on assets it owns, smart contracts may use the special `(as-contract ...)` function. This function executes the expression (passed as an argument) with the `tx-sender` set to the contract's principal, rather than the current sender. The `as-contract` function returns the value of the provided expression. - -For example, a smart contract that implements something like a "token faucet" could be implemented as so: - -```clarity -(define-map claimed-before - ((sender principal)) - ((claimed bool))) - -(define-constant err-already-claimed u1) -(define-constant err-faucet-empty u2) -(define-constant stx-amount u1) - -(define-public (claim-from-faucet) - (let ((requester tx-sender)) ;; set a local variable requester = tx-sender - (asserts! (is-none (map-get? claimed-before {sender: requester})) (err err-already-claimed)) - (unwrap! (as-contract (stx-transfer? stx-amount tx-sender requester)) (err err-faucet-empty)) - (map-set claimed-before {sender: requester} {claimed: true}) - (ok stx-amount))) -``` - -In this example, the public function `claim-from-faucet`: - -- Checks if the sender has claimed from the faucet before. -- Assigns the tx sender to a `requester` variable. -- Adds an entry to the tracking map. -- Uses `as-contract` to send 1 microstack - -Unlike other principals, there is no private key associated with a smart contract. As it lacks a private key, a Clarity smart contract cannot broadcast a signed transaction on the blockchain. - -## Example: Authorization checks - -The interactions between `tx-sender`, `contract-caller` and `as-contract` are subtle, but are important when performing authorization checks in a contract. In this example contract, we'll show two different kinds of authorization checks a contract may wish to perform, and then walk through how different ways in which contract functions may be called will pass or fail those checks. - -This contract defines a "rocket-ship" non-fungible-token that a principal may own and manage the authorized pilots. Pilots are principals that are allowed to "fly" the rocket ship. - -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. -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 be called _directly_ by the ship's owner, rather than through a inter-contract-call. - -The second type of check is more restrictive than the first check, and is helpful for guarding very sensitive routines --- it protects users from unknowingly calling a function on a malicious contract that subsequently tries to call sensitive functions on another contract. - -```clarity -;; -;; rockets-base.clar -;; - -(define-non-fungible-token rocket-ship uint) - -;; a map from rocket ships to their allowed -;; pilots -(define-map allowed-pilots - ((rocket-ship uint)) ((pilots (list 10 principal)))) - -;; implementing a contains function via fold -(define-private (contains-check - (y principal) - (to-check { p: principal, result: bool })) - (if (get result to-check) - to-check - { p: (get p to-check), - result: (is-eq (get p to-check) y) })) - -(define-private (contains (x principal) (find-in (list 10 principal))) - (get result (fold contains-check find-in - { p: x, result: false }))) - -(define-read-only (is-my-ship (ship uint)) - (is-eq (some tx-sender) (nft-get-owner? rocket-ship ship))) - -;; this function will print a message -;; (and emit an event) if the tx-sender was -;; an authorized flyer. -;; -;; here we use tx-sender, because we want -;; to allow the user to let other contracts -;; fly the ship on behalf of users - -(define-public (fly-ship (ship uint)) - (let ((pilots (default-to - (list) - (get pilots (map-get? allowed-pilots { rocket-ship: ship }))))) - (if (contains tx-sender pilots) - (begin (print "Flew the rocket-ship!") - (ok true)) - (begin (print "Tried to fly without permission!") - (ok false))))) -;; -;; Authorize a new pilot. - (ok true)) - (begin (print "Tried to fly without permission!") - (ok false))))) -;; -;; Authorize a new pilot. - (ok false))))) -;; -;; Authorize a new pilot. -;; -;; here we want to ensure that this function -;; was called _directly_ by the user by -;; checking that tx-sender and contract-caller are equal. -;; if any other contract is in the call stack, contract-caller -;; would be updated to a different principal. -;; -(define-public (authorize-pilot (ship uint) (pilot principal)) - (begin - ;; sender must equal caller: an intermediate contract is - ;; not issuing this call. - (asserts! (asserts! (is-eq tx-sender contract-caller) (err u1)) - ;; sender must own the rocket ship - (asserts! (is-eq (some tx-sender) - (nft-get-owner? rocket-ship ship)) (err u2)) - (let ((prev-pilots (default-to - (list) - (get pilots (map-get? allowed-pilots { rocket-ship: ship }))))) - ;; don't add a pilot already in the list - (asserts! (not (contains pilot prev-pilots)) (err u3)) - ;; append to the list, and check that it is less than - ;; the allowed maximum - (match (as-max-len? -``` - -### Extending functionality: Multi-flyer contract - -The authorization scheme for `fly-ship` allows pilots to fly rocket-ships from other contracts. This allows other contracts to provide new functionality built around calling that function. - -For example, we can create a contract that calls `fly-ship` for multiple rocket-ships in a single transaction: - -```clarity -;; -;; rockets-multi.clar -;; - -(define-private (call-fly (ship uint)) - (unwrap! (contract-call? .rockets-base fly-ship ship) false)) -;; try to fly all the ships, returning a list of whether -;; or not we were able to fly the supplied ships -(define-public (fly-all (ships (list 10 uint))) - (ok (map call-fly ships))) -``` - -### Authorization for Contract-Owned Assets - -The check in `authorize-pilot` protects users from malicious contracts, but how would such a scheme support contract-owned assets? This is what the `as-contract` function is used for. The `as-contract` function executes the supplied closure as if the sender of the transaction was the current contract, rather than the user -- it does this by updating `tx-sender` to the current contract principal. We can use this to, for example, create a smart contract rocket-ship-line: - -```clarity -;; -;; rockets-ship-line.clar -;; - -(define-constant line-ceo 'SP19Y6GRV9X778VFS1V8WT2H502WFK33XZXADJWZ) - -(define-data-var employed-pilots (list 10 principal) (list)) - -;; This function will: -;; * check that it is called by the line-ceo -;; * check that the rocket is owned by the contract -;; * authorize each employed pilot to the ship -(define-public (add-managed-rocket (ship uint)) - (begin - ;; 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 - (asserts! (contract-call? .rockets-base is-my-ship ship) (err u2)) - ;; register all of our pilots on the ship - (add-pilots-to ship))))) - -;; add all the pilots to a ship using fold -- -;; the fold checks the return type of previous calls, -;; skipping subsequent contract-calls if one fails. -(define-private (add-pilot-via-fold (pilot principal) (prior-result (response uint uint))) - (let ((ship (try! prior-result))) - (try! (contract-call? .rockets-base authorize-pilot ship pilot)) - (ok ship))) -(define-private (add-pilots-to (ship uint)) - (fold add-pilot-via-fold (var-get employed-pilots) (ok ship))) -``` - -In order for the contract to add each pilot to a new ship, the contract must call `authorize-pilot`. However, the contract wants to perform this action on behalf of a ship the _contract_ owns, not the transaction sender. To do this, the contract uses `as-contract`. diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md b/i18n/fr/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md deleted file mode 100644 index a01e37bc04..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Resources -description: 'Resources' -sidebar_position: 8 ---- - -# External resources - - -[Clarity book](https://book.clarity-lang.org/) - -[Clarity Universe](https://stacks.org/clarity-universe) - -[Hiro Clarity tutorials](https://docs.hiro.so/tutorials) diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md b/i18n/fr/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md deleted file mode 100644 index ed65829518..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Clarity development software -description: The following tools are useful when developing Clarity smart contracts -sidebar_position: 4 ---- - -## Language Server Protocol for Clarity (including Visual Studio Code extension) - -The Language Server Protocol (LSP) defines the protocol used between an editor or IDE and a language server that provides language features like auto complete, go to definition, find all references etc. - -This makes programming in Clarity easier and much more intuitive. - -![Clarity LSP Screenshot](https://raw.githubusercontent.com/hirosystems/clarity-lsp/21b64298ca117dc41358eb9dce4605cc4a448a4c/images/screenshot.png?raw=true) - - -Clarity LSP repository is available [here](https://github.com/hirosystems/clarity-lsp). The extension for Visual Studio Code can be downloaded directly from [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=HiroSystems.clarity-lsp), but can be and older version. For a more up to date version you can also download it from [open-vsx](https://open-vsx.org/extension/hirosystems/clarity-lsp). - -## Clarity REPL - -A read—eval—print loop (REPL), also termed an interactive toplevel or language shell, is a simple, interactive computer programming environment that takes single user inputs (that is, single expressions), evaluates (executes) them, and returns the result to the user; a program written in a REPL environment is executed piecewise. - -![Clarity-repl](https://github.com/hirosystems/clarity-repl/blob/develop/docs/images/screenshot.png?raw=true) - -Instructions on how to install Clarity REPL can be found [here](https://github.com/hirosystems/clarity-repl). - -## Clarinet - -Clarinet is a Clarity runtime packaged as a command line tool, designed to facilitate smart contract understanding, development, testing and deployment. Clarinet consists of a Clarity REPL and a testing harness, which, when used together allow you to rapidly develop and test a Clarity smart contract, with the need to deploy the contract to a local devnet or testnet. - -![Clarinet](https://github.com/hirosystems/clarinet/blob/develop/docs/images/demo.gif?raw=true) - -Installation instructions, including build from source instructions can be found [here](https://github.com/hirosystems/clarinet). If you prefer you can directly download the latest compiled realease for Windows, Mac and Linux [here](https://github.com/hirosystems/clarinet/releases). - -[Clarinet 101](https://www.youtube.com/playlist?list=PL5Ujm489LoJaAz9kUJm8lYUWdGJ2AnQTb) contains multiple Clarinet video tutorials - -### Getting started with Clarinet - -You can verify you have Clarinet installed by checking its version: - -```bash -$ clarinet --version -clarinet 0.70 -``` - -More detailed information on using Clarinet is available [here](https://book.clarity-lang.org/ch07-00-using-clarinet.html). However to get you started, the following commands are important to know. - -Create a new project and enter its directory: - -```bash -clarinet new my-project && cd my-project -``` - -Create a new contract inside `my-project`: - -```bash -clarinet contract new mycoolcontract -``` - -Check the syntax of Clarity: - -```bash -clarity check -``` - -To test your contract: - -```bash -clarinet test -``` - -Enter Clarinet's console: - -```bash -clarinet console -``` diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md b/i18n/fr/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md deleted file mode 100644 index 2754709092..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Tokens -description: Learn about token support within Clarity -sidebar_position: 3 ---- - -## Introduction - -A fundamental use of blockchain technology is the representation, store, and transfer of value between users of a blockchain. Cryptocurrency is a very common use of blockchain technology, and remains one of the primary drivers of adoption of blockchain technology. Cryptocurrencies are represented by blockchain tokens: individual units of value within a given blockchain ecosystem. Blockchain tokens can extend beyond just digital currency, however, and recent developments throughout the cryptocurrency community have demonstrated potential for the use of blockchain to tokenize and represent not just money but other tangible assets. - -A blockchain token is a digital asset that can be verifiably owned by a user of a blockchain. Blockchain tokens are governed by a set of rules that are defined by either the blockchain itself (in the case of native tokens) or by a smart contract on a blockchain. Rules can vary depending on the nature and the use of the token. - -Tokens on a blockchain fall into two general categories, depending on their properties: [fungible][] or [non-fungible][]. The following sections discuss the properties of both types of tokens, and provide information about implementation of the two types of tokens on Stacks. - -## Fungible tokens - -A core property of any token on a blockchain is fungibility. A fungible token is a token that's mutually interchangable or capable of mutual substitution. In other words, one quantity or part of a fungible token can be replaced by an equal quantity or part of the same fungible token. Fungible tokens are often used to represent real-world fungible assets like currency. The STX token is an example of a fungible token. Other examples include stablecoins, tokens that represent voting rights in a DAO, or tokens that algorithmically track the price of stocks. - -Fungible tokens form one of the most important value propositions for blockchain technology, the ability to store value and exchange that value through both internal and external transactions. Because fungible tokens can be divided into smaller parts and recombined into the same value representation, they serve a great utility for transferring value between blockchain users. - -The primary fungible token on the Stacks blockchain is the native token, STX. Because the Stacks blockchain allows for the creation of \[smart contracts\]\[\], other fungible tokens can be created on the Stacks blockchain as well. [SIP-010][] specifies the standard for fungible tokens on the Stacks blockchain. This specification defines the functions and traits that a fungible token on Stacks _must_ have. This specification defines the functions and traits that a fungible token on Stacks _must_ have. - -### Understanding the fungible token standard - -The [SIP-010][] standard is an interface definition that allows Stacks applications and wallets to interact with fungible tokens in a standard way. Supporting the standard reduces complexity for token creators to get their tokens into the ecosystem. Under the [SIP-010][] standard, fungible tokens must have the following characteristics: - -- Ability to transfer a specified amount of the token to a recipient (`transfer`). The recipient is required to be a Stacks principal. -- Ability to obtain the human-readable name of the token (`get-name`). -- Ability to obtain a short name (ticker symbol) for the token (`get-symbol`). -- Ability to get the number of decimals in the token representation (`get-decimals`). This is used to construct a representation of the token that humans would be familiar dealing with. For example, the US dollar has 2 decimals, if the base unit is cents. -- Ability to get the balance of the token for a particular Stacks principal (`get-balance-of`). -- Ability to get the total supply of the token (`get-total-supply`). -- A URI to metadata associated with the token (`get-token-uri`). This can resolve to off-chain metadata about the token or contract, such as an image icon for the token or a description. - -## Non-fungible tokens (NFTs) - -Non-fungible tokens (NFTs) are a type of token that are not interchangeable. NFTs have unique traits (usually in the form of attached metadata) that restrict the abillity to replace them with identical tokens. An NFT is a token that is unique, such as a piece of art, or ownership rights to a real-world asset such as a house. - -NFTs alone don't have an inherent value, like a currency. The value of an NFT is derived from the assets that the NFT represents. The use of NFTs are myriad, including digital art, collectibles, domain names, and representation of ownership of content rights. NFTs can be used as digital certificates that track the authenticty of real world items, or digitize the ownership rights to property. - -As with fungible tokens, NFTs on the Stacks blockchain are created with smart contracts. [SIP-009][] specifies the standard for NFTs on the Stacks blockchain. This specification defines the functions and traits that an NFT _must_ have, but most NFTs have more functions or traits attached than those solely described by the specification. By complying with this standard, non-fungible tokens on Stacks can be easily represented by wallets that support Stacks. - -### Understanding the non-fungible token standard - -The [SIP-009][] standard is an interface definition that the Stacks ecosystem aligned on. With support for this standard across wallets and tools, it becomes easy to interact with NFTs. Under the [SIP-009][] standard, NFT contract must have the following characteristics: - -- Ability to obtain the last token identifier (`get-last-token-id`). This id represents the upper limit of NFTs issued by the contract. -- A URI to metadata associated with a specific token identifier. (`get-token-uri`). This URI could resolve to a JSON file with information about the creator, associated media files, descriptions, signatures, and more. -- Ability to verify the owner for a given token identifier (`get-owner`). The owner resolves to a [Stacks principal](principals). -- Ability to transfer an NFT to a recipient (`transfer`). The recipient is required to be a Stacks principal. - -## Further reading - -- [The Difference Between Fungible and Non-Fungible Tokens](https://101blockchains.com/fungible-vs-non-fungible-tokens/) -- [Explain It Like I Am 5: NFTs](https://messari.io/article/explain-it-like-i-am-5-nfts) - -[fungible]: #fungible-tokens -[non-fungible]: #non-fungible-tokens-nfts -[SIP-010]: https://github.com/hstove/sips/blob/feat/sip-10-ft/sips/sip-010/sip-010-fungible-token-standard.md -[SIP-009]: https://github.com/stacksgov/sips/blob/main/sips/sip-009/sip-009-nft-standard.md diff --git a/i18n/fr/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md b/i18n/fr/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md deleted file mode 100644 index fc4765aa0c..0000000000 --- a/i18n/fr/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md +++ /dev/null @@ -1,301 +0,0 @@ ---- -title: Clarity Values -description: Learn how to deal with Clarity Values in JavaScript -sidebar_position: 2 ---- - -## Introduction - -The Clarity language makes use of a strong static 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/hirosystems/stacks.js/tree/master/packages/transactions) library makes this easy, as we will demonstrate below. - -## Clarity Types - -Please see the following page for information on [Clarity Types](../write-smart-contracts/clarity-language/language-types). - -## Constructing Clarity Values and accessing their data - -Clarity values can be constructed with functions provided by the [@stacks/transactions](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library. These functions simply output javascript objects that contain a value and a numerical representation of the Clarity type information. The Clarity types are encoded as follows: - -```typescript -export enum ClarityType { - Int = 0, - UInt = 1, - Buffer = 2, - BoolTrue = 3, - BoolFalse = 4, - PrincipalStandard = 5, - PrincipalContract = 6, - ResponseOk = 7, - ResponseErr = 8, - OptionalNone = 9, - OptionalSome = 10, - List = 11, - Tuple = 12, - StringASCII = 13, - StringUTF8 = 14, -} -``` - -`ClarityValue` objects can be serialized and included in transactions that interact with published Clarity contracts. - -Here are examples of how to construct each type of Clarity value, and how to access its data if it has any: - -### Booleans - -```typescript -const t = trueCV(); -// { type: ClarityType.BoolTrue } - -const f = falseCV(); -// { type: ClarityType.BoolFalse } -``` - -Boolean Clarity Values don't contain any underlying data. They are simply objects with `type` information. - -### Optional Values - -```typescript -const nothing: NoneCV = noneCV(); -// { type: ClarityType.OptionalNone } - -const something: SomeCV = someCV(trueCV()); -// { type: ClarityType.OptionalSome, value: { type: 4 } } -``` - -Optional Clarity Values can either be nothing (an empty type that has no data), or something (a wrapped value). - -If you are dealing with a function or contract function that returns an `OptionalCV`, you should always check what type it is before trying to access its value. - -```typescript -const maybeVal: OptionalCV = await callReadOnlyFunction(...); - -if (maybeVal.type === ClarityType.OptionalSome) { - console.log(maybeVal.value); -} else if (maybeVal.type === ClarityType.OptionalNone) { - // deal with `none` value -} -``` - -### Buffers - -```typescript -const buffer = Buffer.from('foo'); -const bufCV: BufferCV = bufferCV(buffer); -// { type: ClarityType.Buffer, buffer: } -``` - -### Integers - -Clarity supports both integers and unsigned integers. - -```typescript -const i: IntCV = intCV(-10); -// { type: ClarityType.Int, value: BN { ... } } - -const u: UIntCV = uintCV(10); -// { type: ClarityType.UInt, value: BN { ... } } -``` - -Clarity value ints store their underlying data as `BigNum` values from the [bn.js](https://github.com/indutny/bn.js/) library. - -In order to display/print Clarity (u)int values, use the `cvToString(val)` method. - -If you wish to perform arithmetic operations using Clarity (u)int values, you must use methods from the `BigNum` api on their underlying `BigNum` values, and the construct a new Clarity value out of the result. For example: - -```typescript -const x = intCV(1); -const y = intCV(2); - -x.value.add(y.value); -// 3 -``` - -### Strings - -```typescript -const ascii: StringAsciiCV = stringAsciiCV('hello world'); -// { type: ClarityType.StringASCII, data: 'hello world' } - -const utf8: StringUtf8CV = stringUtf8CV('hello 🌾'); -// { type: ClarityType.StringUTF8, data: 'hello 🌾' } -``` - -Clarity supports both ascii and utf8 strings. - -### Principals - -```typescript -const address = 'SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B'; -const contractName = 'contract-name'; - -const spCV = standardPrincipalCV(address); -// { -// type: ClarityType.PrincipalStandard -// address: { -// type: StacksMessageType.Address, -// version: AddressVersion.MainnetSingleSig, -// hash160: "SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B" -// } -// } - -const cpCV = contractPrincipalCV(address, contractName); -// { -// type: ClarityType.PrincipalContract, -// contractName: { -// type: StacksMessageType.LengthPrefixedString, -// content: 'contract-name', -// lengthPrefixBytes: 1, -// maxLengthBytes: 128, -// }, -// address: { -// type: StacksMessageType.Address, -// version: AddressVersion.MainnetSingleSig, -// hash160: "SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B" -// } -// } -``` - -Both kinds of Clarity principal values contain `type` information and an `address` object. Contract principals also contain a `contractName`. - -### Response Values - -```typescript -const errCV = responseErrorCV(trueCV()); -// { type: ResponseErr, value: { type: ClarityType.BoolTrue } } - -const okCV = responseOkCV(falseCV()); -// { type: ResponseOk, value: { type: ClarityType.BoolFalse } } -``` - -Response Clarity Values will either have the type `ClarityType.ResponseOk` or `ClarityType.ResponseErr`. They both contain a Clarity Value. Often this value will be an integer error code if the response is an `Error`. - -### Tuples - -```typescript -const tupCV = tupleCV({ - a: intCV(1), - b: trueCV(), - c: falseCV(), -}); -// { -// type: ClarityType.Tuple, -// data: { -// a: { type: ClarityType.Int, value: BN { ... } }, -// b: { type: ClarityType.BoolTrue }, -// c: { type: ClarityType.BoolFalse }, -// } -// } - -console.log(tupCV.data['b']); -// { type: ClarityType.BoolTrue } -``` - -Tuples in Clarity are typed and contain named fields. The tuple above, for example, contains three fields with the names **a**, **b** and **c**, and the types of their values are `Int`, `Boolean` and `Boolean`, respectively. - -Clarity tuples are represented in JavaScript as objects and a tuple's data can be accessed by its `data` field, where the underlying JS object is stored. - -### Lists - -```typescript -const l = listCV([trueCV(), falseCV()]); -// { type: ClarityType.List, list: [{ type: ClarityType.BoolTrue }] } - -console.log(l.list[0]); -// { type: ClarityType.BoolTrue } -``` - -Lists, in Clarity, are homogeneous, meaning they can only contain elements of a singular (Clarity) type. Make sure to avoid constructing lists that have elements of multiple types. - -A Clarity lists underlying data can be accessed via its `list` field. - -## Using Clarity Values - -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](../understand-stacks/transactions#construction). - -## Utilizing Clarity Values from Transaction Responses - -`Read-only` Clarity functions can return Clarity values as a response. These `read-only` functions can be accessed easily in JavaScript via the [`callReadOnlyFunction()`](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions#calling-read-only-contract-function) function included in `@stacks/transactions`, which returns a `ClarityValue`. - -As mentioned above, `ClarityValues` are simply javascript objects containing a value and its associated Clarity type information. These object types are defined [here](https://github.com/hirosystems/stacks.js/tree/1f2b5fd8bdf1c2b5866e8171163594d7708a8c7a/packages/transactions/src/clarity/types). - -When you are calling a `read-only` contract function, you will always know what type the function will return, since functions in Clarity are strongly typed. - -It is common for Clarity functions to return values wrapped in a `Response`, in order to indicate if there was success or an error. - -Since every `ClarityValue` has a `type` field, the type of the result of a `read-only` function call can be checked and acted upon like so: - -```typescript -const contractAddress = 'ST3KC0MTNW34S1ZXD36JYKFD3JJMWA01M55DSJ4JE'; -const contractName = 'kv-store'; -const functionName = 'get-value'; -const buffer = bufferCVFromString('foo'); -const network = new StacksTestnet(); // for mainnet, use `StacksMainnet()` -const senderAddress = 'ST2F4BK4GZH6YFBNHYDDGN4T1RKBA7DA1BJZPJEJJ'; - -const options = { - contractAddress, - contractName, - functionName, - functionArgs: [buffer], - network, - senderAddress, -}; - -// make a read-only call to a contract function that -// returns a Response -const result: ResponseCV = await callReadOnlyFunction(options); - -if (result.type === ClarityType.ResponseOk) { - console.log(cvToString(result.value)); -} else if (result.type === ClarityType.ResponseErr) { - throw new Error(`kv-store contract error: ${result.value.data}`); -} -``` - -### ClarityValues to/from Hex - -If you receive a response from a transaction in the form of a `hex` string, you can deserialize it into a Clarity value like so: - -```javascript -import { hexToCV } from '@stacks/transactions'; - -let cv = hexToCV('hex_string'); -``` - -Similarly, you can convert a Clarity value to `hex` string like so: - -```javascript -import { cvToHex, trueCV } from '@stacks/transactions'; - -let trueHex = cvToHex(trueCV()); -``` - -## Debugging Clarity Values - -Sometimes you might receive a Clarity value that you were not expecting. Logging the value to your console won't always prove to be useful, unless you have memorized the Clarity value type enum values. - -In order to figure out what kind of value you are dealing with, you can use the `cvToString()` function to convert the Clarity value to a more easily readable string. - -For example, calling `cvToString()` on a large `tuple` might yield something like: - -``` -(tuple - (a -1) - (b u1) - (c 0x74657374) - (d true) - (e (some true)) - (f none) - (g SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B) - (h SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B.test) - (i (ok true)) - (j (err false)) - (k (list true false)) - (l (tuple (a true) (b false))) - (m "hello world") - (n u"hello \u{1234}"))` -``` diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/blockchain/index.md b/i18n/hi/docusaurus-plugin-content-docs/current/blockchain/index.md deleted file mode 100644 index 13db24ec30..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/blockchain/index.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: Blockchain -description: Stacks Blockchain -sidebar_position: 6 ---- - -Below is a guide to start working locally with the Stacks Blockchain. - -Code repository is [here](https://github.com/stacks-network/stacks-blockchain). - -## Getting started with the Stacks Blockchain - -### Download and build stacks-blockchain - -The first step is to ensure that you have Rust and the support software installed. - -```bash -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -``` - -:::info -For building on Windows, follow the rustup installer instructions at https://rustup.rs/ -::: - -From there, you can clone the Stacks Blockchain repository: - -```bash -git clone --depth=1 https://github.com/stacks-network/stacks-blockchain.git - -cd stacks-blockchain -``` - -Then build the project: - -```bash -cargo build -``` - -Run the tests: - -```bash -cargo test testnet -- --test-threads=1 -``` - -### Encode and sign transactions - -Here, we have generated a keypair that will be used for signing the upcoming transactions: - -```bash -cargo run --bin blockstack-cli generate-sk --testnet - -# Output -# { -# secretKey: "b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001", -# publicKey: "02781d2d3a545afdb7f6013a8241b9e400475397516a0d0f76863c6742210539b5", -# stacksAddress: "ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH" -# } -``` - -This keypair is already registered in the `testnet-follower-conf.toml` file, so it can be used as presented here. - -We will interact with the following simple contract `kv-store`. In our examples, we will assume this contract is saved to `./kv-store.clar`: - -```scheme -(define-map store { key: (string-ascii 32) } { value: (string-ascii 32) }) - -(define-public (get-value (key (string-ascii 32))) - (match (map-get? store { key: key }) - entry (ok (get value entry)) - (err 0))) - -(define-public (set-value (key (string-ascii 32)) (value (string-ascii 32))) - (begin - (map-set store { key: key } { value: value }) - (ok true))) -``` - -We want to publish this contract on chain, then issue some transactions that interact with it by setting some keys and getting some values, so we can observe read and writes. - -Our first step is to generate and sign, using your private key, the transaction that will publish the contract `kv-store`. To do that, we will use the subcommand `blockstack-cli` that has the following usage: - -```bash -blockstack-cli (options) publish [publisher-secret-key-hex] [fee-rate] [nonce] [contract-name] [file-name.clar] -``` - -With the following arguments: - -```bash -cargo run --bin blockstack-cli publish b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 515 0 kv-store ./kv-store.clar --testnet -``` - -The `515` is the transaction fee, denominated in microSTX. Right now, the testnet requires one microSTX per byte minimum, and this transaction should be less than 515 bytes. The third argument `0` is a nonce, that must be increased monotonically with each new transaction. - -This command will output the **binary format** of the transaction. In our case, we want to pipe this output and dump it to a file that will be used later in this tutorial. - -```bash -cargo run --bin blockstack-cli publish b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 515 0 kv-store ./kv-store.clar --testnet | xxd -r -p > tx1.bin -``` - -### Run the testnet - -You can observe the state machine in action locally by running: - -```bash -cargo stacks-node start --config=./testnet/stacks-node/conf/testnet-follower-conf.toml -``` - -`testnet-follower-conf.toml` is a configuration file that you can use for setting genesis balances or configuring Event observers. You can grant an address an initial account balance by adding the following entries: - -``` -[[ustx_balance]] -address = "ST2VHM28V9E5QCRD6C73215KAPSBKQGPWTEE5CMQT" -amount = 100000000 -``` - -The `address` field is the Stacks testnet address, and the `amount` field is the number of microSTX to grant to it in the genesis block. The addresses of the private keys used in the tutorial below are already added. - -### Publish your contract - -Assuming that the testnet is running, we can publish our `kv-store` contract. - -In another terminal (or file explorer), you can move the `tx1.bin` generated earlier, to the mempool: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx1.bin http://localhost:20443/v2/transactions -``` - -In the terminal window running the testnet, you can observe the state machine's reactions. - -### Reading from / Writing to the contract - -Now that our contract has been published on chain, let's try to submit some read / write transactions. We will start by trying to read the value associated with the key `foo`. - -To do that, we will use the subcommand: - -```bash -cargo run --bin blockstack-cli contract-call --help -``` - -With the following arguments: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 1 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store get-value -e \"foo\" --testnet | xxd -r -p > tx2.bin -``` - -`contract-call` generates and signs a contract-call transaction. - -We can submit the transaction by moving it to the mempool path: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx2.bin http://localhost:20443/v2/transactions -``` - -Similarly, we can generate a transaction that would be setting the key `foo` to the value `bar`: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 2 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store set-value -e \"foo\" -e \"bar\" --testnet | xxd -r -p > tx3.bin -``` - -And submit it by moving it to the mempool path: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx3.bin http://localhost:20443/v2/transactions -``` - -Finally, we can issue a third transaction, reading the key `foo` again, for ensuring that the previous transaction has successfully updated the state machine: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 3 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store get-value -e \"foo\" --testnet | xxd -r -p > tx4.bin -``` - -And submit this last transaction by moving it to the mempool path: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx4.bin http://localhost:20443/v2/transactions -``` - -Congratulations, you can now [write your own smart contracts with Clarity](write-smart-contracts/). diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/blockchain/networks.md b/i18n/hi/docusaurus-plugin-content-docs/current/blockchain/networks.md deleted file mode 100644 index fe9725352c..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/blockchain/networks.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Stacks Blockchain Networks -description: Stacks Blockchain Networks -sidebar_position: 3 ---- - -### Stacks Blockchain Networks - -- [x] **Krypton** is a Stacks 2 testnet with a fixed, two-minute block time, called `regtest`. Regtest is generally unstable for regular use, and is reset often. See the [regtest documentation](understand-stacks/testnet) for more information on using regtest. - -- [x] **Testnet** (old Xenon) is the Stacks 2 public testnet, which runs PoX against the Bitcoin testnet. It is the full implementation of the Stacks 2 blockchain, and should be considered a stable testnet for developing Clarity smart contracts. See the [testnet documentation](understand-stacks/testnet) for more information on the public testnet. - -- [x] **Mainnet** is the fully functional Stacks 2 blockchain, see the [Stacks overview](understand-stacks/) for information on running a Stacks node, mining, stacking, and writing Clarity smart contracts. diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md b/i18n/hi/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md deleted file mode 100644 index cf4f84a2da..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Stacks Blockchain API -description: Interacting with the Stacks 2.0 Blockchain via API -sidebar_position: 4 ---- - -## Introduction - -:::tip API Documentation Official API Documentation is available [here](https://stacks-network.github.io/stacks-blockchain/). ::: - - -The Stacks 2.0 Blockchain API allows you to query the Stacks 2.0 blockchain and interact with smart contracts. It was built to maintain pageable materialized views of the Stacks 2.0 Blockchain. - -:::caution The RESTful API is developed by Hiro. Hiro also hosts a public API node for easy onboarding. Using it requires you to trust the hosted server, but provides a faster onboarding experience. You can [run your own API server](https://docs.hiro.so/get-started/running-api-node) ::: - -The RESTful JSON API can be used without any authorization. The basepath for the API is: - -```bash -# for mainnet, replace `testnet` with `mainnet` -https://stacks-node-api.testnet.stacks.co/ -``` - -:::note This documentation only covers endpoints that are exposed on a Stacks node, referred to as the RPC API. For full documentation on the RESTful API, check out the [Hiro's API reference](https://docs.hiro.so/api). ::: - -### Stacks Node RPC API - -The [stacks-node implementation](https://github.com/stacks-network/stacks-blockchain/) exposes JSON RPC endpoints. - -All `/v2/` routes a proxied to a Hiro-hosted Stacks Node. For a trustless architecture, you should make these requests to a self-hosted node. - -## Proxied Stacks Node RPC API endpoints - -The Stacks 2.0 Blockchain API is centrally hosted. However, every running Stacks node exposes an RPC API, which allows you to interact with the underlying blockchain. Instead of using a centrally hosted API, you can directly access the RPC API of a locally hosted Node. - -:::tip -The Stacks Blockchain API proxies to Node RPC endpoints -::: - -While the Node RPC API doesn't give the same functionality as the hosted Stacks 2.0 Blockchain API, you get similar functionality in a way that is scoped to that specific node. The RPC API includes the following endpoints: - -- [POST /v2/transactions](https://docs.hiro.so/api#operation/post_core_node_transactions) -- [GET /v2/contracts/interface/{contract_address}/{contract_name}](https://docs.hiro.so/api#operation/get_contract_interface) -- [POST /v2/map_entry/{contract_address}/{contract_name}/{map_name}](https://docs.hiro.so/api#operation/get_contract_data_map_entry) -- [GET /v2/contracts/source/{contract_address}/{contract_name}](https://docs.hiro.so/api#operation/get_contract_source) -- [GET /v2/accounts/{principal}](https://docs.hiro.so/api#operation/get_account_info) -- [POST /v2/contracts/call-read/{contract_address}/{contract_name}/{function_name}](https://docs.hiro.so/api#operation/call_read_only_function) -- [GET /v2/fees/transfer](https://docs.hiro.so/api#operation/get_fee_transfer) -- [GET /v2/info](https://docs.hiro.so/api#operation/get_core_api_info) - -:::caution If you run a local node, it exposes an HTTP server on port `20443`. The info endpoint would be `localhost:20443/v2/info`. ::: diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md b/i18n/hi/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md deleted file mode 100644 index 71e3542302..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Stacks Releases -description: Stacks Blockchain Releases -sidebar_position: 2 ---- - -:::info -This page needs contributions. Help us improve it. -::: - -### Stacks Blockchain Releases - -All releases are published [here](https://github.com/stacks-network/stacks-blockchain/releases). Most important ones are described below. - -### Stacks 2.1 - -Scheduled for release at the end of 2022. - -More information on [what to expect with Stacks 2.1](https://stacks.org/stacks-21-what-to-expect). - -#### Stacks 2.05 -Activated on [Bitcoin block 713000](https://explorer.stacks.co/txid/0xece8e369310b5ff9b92ef11181ae0d2457ac0c821376d4a96c4998763e22ad04?chain=mainnet). - -This breaking change enables storage cost for list to be based on actual length and change in number of indexed I/O operations. More info on this [blog post](https://www.stacks.org/stacks-2-05?ref=docs-website). - -#### Stacks 2.0 -Activated on January 14th 2021 - -This hard fork enables Stacking, Clarity smart contracts, scalable transactions, and also building directly on Bitcoin. More info [here](https://forum.stacks.org/t/path-to-mainnet-for-stx-holders-things-to-know-ahead-of-stacks-2-0/11529). - -#### Stacks Genesis -Released on 2018, October 30th UTC+6 at Bitcoin block height 547921 - -This hard fork addresses registration of digital assets with Stacks token and also distribution of Stacks token to the existing purchasers. More info [here](https://blog.blockstack.org/the-launch-of-the-stacks-genesis-block/?ref=docs-website). - diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md b/i18n/hi/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md deleted file mode 100644 index 25ec969824..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Deploy tips -description: Learn some common methods for deploying your application. ---- - -## Introduction - -Stacks applications are web applications that authenticate users with Stacks Auth and store data with Gaia. Both of these technologies can be accessed on the client side. As such, Stacks apps tend to be simple in design and operation, since in many cases, they don’t have to host anything besides the application’s assets. - -## Where to deploy your application - -Before users can interact with your application, you must deploy it on a server that is accessible over the internet. Deploying requires that you: - -- Configure or customize the files in the `public` directory. -- Build your application site for deployment. -- Copy your generated application files to your production server. - -If you first populated your application with the Stacks application generator, your application contains the starting blocks for configuring, building, and deploying your app. For example, the React template builds out a scaffolding with the following building blocks. - -| File or Directory | Description | -| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| node_modules/react-scripts | A set of scripts for that helps you kick off React projects without configuring, so you do not have to set up your project by yourself. | -| package.json | Contains a scripts section that includes a reference to the react-scripts, which are a dependency. This script creates a build directory containing your files for deployment. | -| public/favicon.ico | An example shortcut icon. | -| public/index.html | An entry page for an application. | -| public/manifest.json | A JSON file that describes your web application to the browser. | -| cors | Contains example deployment files for cross-origin request configuration. | - -If you use the generator to build JavasScript or Vue scaffolding, your project configuration files will be different. - -Regardless of which scaffolding you use, you must customize and extend this basic scaffolding as needed by your application. For example, you may want to add more properties to the `manifest.json` file. Since every application is different, Stacks Auth cannot give you specific instructions on how to do this. The steps you take are specific to your application. - -## Stacks Authentication and deployment - -When your application authenticates users with Stacks, the Stacks Wallet at on URL requests a resource (the app manifest) from your DApp. A request for a resource outside of the origin (the Stacks Wallet) 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 (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) - -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 Stacks 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`: - -```html -Access-Control-Allow-Origin: * Access-Control-Allow-Headers: "X-Requested-With, Content-Type, -Origin, Authorization, Accept, Client-Security-Token, Accept-Encoding" Access-Control-Allow-Methods: -"POST, GET, OPTIONS, DELETE, PUT" -``` - -Consult the documentation for your hosting service to learn how to configure CORS on that service. - -## Deployment and Radiks - -If you are deploying a Stacks application that uses [Radiks](https://github.com/stacks-network/radiks), your deployment includes a server and a database component. You must take this into account when deploying your application. You may want to choose a service such as [Heroku](https://www.heroku.com) or [Digital Ocean](https://www.digitalocean.com) if your app uses Radiks. diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/build-apps/index.md b/i18n/hi/docusaurus-plugin-content-docs/current/build-apps/index.md deleted file mode 100644 index 23714cba5d..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/build-apps/index.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Build apps with Stacks -description: Authenticate users, sign transactions and store data with the Stacks blockchain -sidebar_position: 3 -sidebar_label: Build apps ---- - -## Introduction - -Apps built with the Stacks blockchain give users control over their digital identities, assets, and data. - -Unlike most cloud-based apps, they are "decentralized" since they don't depend on any centralized platform, server, or database to function. Rather, they use the Stacks blockchain to authenticate users and facilitate read and write requests for them without any single point of failure or trust. - -Stacks provides three main functions for building apps: - - - -- **Authentication**: Register and sign users in with identities on the Stacks blockchain -- **Transaction signing**: Prompt users to sign and broadcast transactions to the Stacks blockchain -- **Data storage**: Save and retrieve data for users with [Gaia](../gaia) - - -All three of these integrations can be used together to create powerful new user experiences that rival or exceed those of traditional apps—all while protecting your users' digital rights. - -While integration is possible for any type of app, most of the resources available here are for web developers experienced with JavaScript. See [Hiro developer docs](https://docs.hiro.so) for more information on the available app development libraries for Stacks. - -## [References](references) - -[Authentication](references/authentication) - -[BNS](references/bns) - -[Gaia](../gaia/) - diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md b/i18n/hi/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md deleted file mode 100644 index 727b4e2163..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: NoCodeClarity -description: Launch apps for the Stacks blockchain through no code platforms like Bubble. ---- - -## Introduction - -![](https://d1muf25xaso8hp.cloudfront.net/https%3A%2F%2Fs3.amazonaws.com%2Fappforest_uf%2Ff1653407713550x759333524803365600%2FLogo%2520of%2520NoCodeClarity.png?w=179&h=84&auto=compress&dpr=1&fit=max) - -[NoCodeClarity](https://nocodeclarity.com) allows people to create applications for the Stacks blockchain without coding. - -## Stacks Plug-In on bubble - -The [Stacks-No-Code-Plugin](https://bubble.io/plugin/the-stacks-plug-in-1645467277638x949839693014368300) released in May 2022 and it can easily be installed on Bubble with a few clicks allowing users to deploy applications with no coding knowledge. [Bubble](https://bubble.io/blog/explaining-bubble-to-investors/) is the first No Code platform that the Stacks plugin launched on. More platforms are in the roadmap of NoCodeClarity, founded by Christopher Perceptions and Sergio Gongora. The Stacks plugin was created through the support of the Stacks Foundation via a grant in January 2022 and NoCodeClarity was awarded a $100,000 grant in June 2022 to expand the roadmap. - -Additional [instructions](https://s3.amazonaws.com/appforest_uf/f1654202471526x991633667675927800/Instructions%20v2.docx.pdf) are also available. Tutorials and step by step guides will be released soon. - -The Stacks-No-Code-Plugin code is [publicly available on Github](https://github.com/nocodeclarity/Stacks-No-Code-Plugin). - -![](/img/bubble-stacks-plugin.png) - -## Demo page - -A demo page is available [here](https://test-stacks-plugin.bubbleapps.io/version-test). - -## NoCodeClarity videos - -NodeCodeClarity has their own [youtube channel](https://www.youtube.com/channel/UC9Ep0VQ-GQ-yDzt-wmIElRA). - -Videos: - -* [NoCodeClarity Setup](https://www.youtube.com/watch?v=WanXlpBGl0w) -* [NoCodeClarity - Part 1 of the plugin](https://www.youtube.com/watch?v=o6d3hrzNqVI&t=248s) -* [NoCodeClarity - Part 2 of the plugin](https://www.youtube.com/watch?v=0rzMdsrRg80) -* [Sneak Peek of the No Code Stacks Wallet Template](https://www.youtube.com/watch?v=Xe6Yv0rF6XM) \ No newline at end of file diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md b/i18n/hi/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md deleted file mode 100644 index c856cec484..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Authentication -description: Register and sign in users with identities on the Stacks blockchain ---- - -## Introduction - -This guide explains how authentication is performed on the Stacks blockchain. - -Authentication provides a way for users to identify themselves to an app while retaining complete control over their credentials and personal details. It can be integrated alone or used in conjunction with [transaction signing](https://docs.hiro.so/get-started/transactions#signature-and-verification) and [data storage](https://docs.stacks.co/gaia/overview), for which it is a prerequisite. - -Users who register for your app can subsequently authenticate to any other app with support for the [Blockchain Naming System](bns) and vice versa. - -## How it works - -The authentication flow with Stacks is similar to the typical client-server flow used by centralized sign in services (for example, OAuth). However, with Stacks the authentication flow happens entirely client-side. - -An app and authenticator, such as [the Stacks Wallet](https://www.hiro.so/wallet/install-web), communicate during the authentication flow by passing back and forth two tokens. The requesting app sends the authenticator an `authRequest` token. Once a user approves authentication, the authenticator responds to the app with an `authResponse` token. - -These tokens are are based on [a JSON Web Token (JWT) standard](https://tools.ietf.org/html/rfc7519) with additional support for the `secp256k1` curve used by Bitcoin and many other cryptocurrencies. They are passed via URL query strings. - -When a user chooses to authenticate an app, it sends the `authRequest` token to the authenticator via a URL query string with an equally named parameter: - -`https://wallet.hiro.so/...?authRequest=j902120cn829n1jnvoa...` - -When the authenticator receives the request, it generates an `authResponse` token for the app using an _ephemeral transit key_ . The ephemeral transit key is just used for the particular instance of the app, in this case, to sign the `authRequest`. - -The app stores the ephemeral transit key during request generation. The public portion of the transit key is passed in the `authRequest` token. The authenticator uses the public portion of the key to encrypt an _app private key_ which is returned via the `authResponse`. - -The authenticator generates the app private key from the user's _identity address private key_ and the app's domain. The app private key serves three functions: - -1. It is used to create credentials that give the app access to a storage bucket in the user's Gaia hub -2. It is used in the end-to-end encryption of files stored for the app in the user's Gaia storage. -3. It serves as a cryptographic secret that apps can use to perform other cryptographic functions. - -Finally, the app private key is deterministic, meaning that the same private key will always be generated for a given Stacks address and domain. - -The first two of these functions are particularly relevant to [data storage with Stacks.js](https://docs.stacks.co/docs/gaia). - -## Key pairs - -Authentication with Stacks makes extensive use of public key cryptography generally and ECDSA with the `secp256k1` curve in particular. - -The following sections describe the three public-private key pairs used, including how they're generated, where they're used and to whom private keys are disclosed. - -### Transit private key - -The transit private is an ephemeral key that is used to encrypt secrets that need to be passed from the authenticator to the app during the authentication process. It is randomly generated by the app at the beginning of the authentication response. - -The public key that corresponds to the transit private key is stored in a single element array in the `public_keys` key of the authentication request token. The authenticator encrypts secret data such as the app private key using this public key and sends it back to the app when the user signs in to the app. The transit private key signs the app authentication request. - -### Identity address private key - -The identity address private key is derived from the user's keychain phrase and is the private key of the Stacks username that the user chooses to use to sign in to the app. It is a secret owned by the user and never leaves the user's instance of the authenticator. - -This private key signs the authentication response token for an app to indicate that the user approves sign in to that app. - -### App private key - -The app private key is an app-specific private key that is generated from the user's identity address private key using the `domain_name` as input. - -The app private key is securely shared with the app on each authentication, encrypted by the authenticator with the transit public key. Because the transit key is only stored on the client side, this prevents a man-in-the-middle attack where a server or internet provider could potentially snoop on the app private key. diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/build-apps/references/bns.md b/i18n/hi/docusaurus-plugin-content-docs/current/build-apps/references/bns.md deleted file mode 100644 index 32b045dc83..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/build-apps/references/bns.md +++ /dev/null @@ -1,241 +0,0 @@ ---- -title: Blockchain Naming System -description: Binds Stacks usernames to off-chain state ---- - -Blockchain Naming System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of control. - -The Stacks V1 blockchain implemented BNS through first-order name operations. In Stacks V2, BNS is instead implemented through a smart-contract loaded during the genesis block. - -Names in BNS have three properties: - -- **Names are globally unique.** The protocol does not allow name collisions, and all well-behaved nodes resolve a given name to the same state. -- **Names are human-meaningful.** Each name is chosen by its creator. -- **Names are strongly owned.** Only the name's owner can change the state it resolves to. Specifically, a name is owned by one or more ECDSA private keys. - -The Stacks blockchain insures that each node's BNS view is synchronized to all of the other nodes in the world, so queries on one node will be the same on other nodes. Stacks blockchain nodes allow a name's owner to bind up to 40Kb of off-chain state to their name, which will be replicated to all other Stacks blockchain nodes via a P2P network. - -The biggest consequence for developers is that in BNS, reading name state is fast and cheap but writing name state is slow and expensive. This is because registering and modifying names requires one or more transactions to be sent to the underlying blockchain, and BNS nodes will not process them until they are sufficiently confirmed. Users and developers need to acquire and spend the requisite cryptocurrency (STX) to send BNS transactions. - -## Motivation behind naming systems - -We rely on naming systems in everyday life, and they play a critical role in many different applications. For example, when you look up a friend on social media, you are using the platform's naming system to resolve their name to their profile. When you look up a website, you are using the Domain Name Service to resolve the hostname to its host's IP address. When you check out a Git branch, you are using your Git client to resolve the branch name to a commit hash. When you look up someone's PGP key on a keyserver, you are resolving their key ID to their public key. - -What kinds of things do we want to be true about names? In BNS, names are globally unique, names are human-meaningful, and names are strongly owned. However, if you look at these examples, you'll see that each of them only guarantees _two_ of these properties. This limits how useful they can be. - -- In DNS and social media, names are globally unique and human-readable, but not strongly owned. The system operator has the final say as to what each names resolves to. - - - **Problem**: Clients must trust the system to make the right choice in what a given name resolves to. This includes trusting that no one but the system administrators can make these changes. - -- In Git, branch names are human-meaningful and strongly owned, but not globally unique. Two different Git nodes may resolve the same branch name to different unrelated repository states. - - - **Problem**: Since names can refer to conflicting state, developers have to figure out some other mechanism to resolve ambiguities. In Git's case, the user has to manually intervene. - -- In PGP, names are key IDs. They are are globally unique and cryptographically owned, but not human-readable. PGP key IDs are derived from the keys they reference. - - **Problem**: These names are difficult for most users to remember since they do not carry semantic information relating to their use in the system. - -BNS names have all three properties, and none of these problems. This makes it a powerful tool for building all kinds of network applications. With BNS, we can do the following and more: - -- Build domain name services where hostnames can't be hijacked. -- Build social media platforms where user names can't be stolen by phishers. -- Build version control systems where repository branches do not conflict. -- Build public-key infrastructure where it's easy for users to discover and remember each other's keys. - -## Organization of BNS - -BNS names are organized into a global name hierarchy. There are three different layers in this hierarchy related to naming: - -- **Namespaces**. These are the top-level names in the hierarchy. An analogy to BNS namespaces are DNS top-level domains. Existing BNS namespaces include `.id`, `.podcast`, and `.helloworld`. All other names belong to exactly one namespace. Anyone can create a namespace, but in order for the namespace to be persisted, it must be _launched_ so that anyone can register names in it. Namespaces are not owned by their creators. - -- **BNS names**. These are names whose records are stored directly on the blockchain. The ownership and state of these names are controlled by sending blockchain transactions. Example names include `verified.podcast` and `muneeb.id`. Anyone can create a BNS name, as long as the namespace that contains it exists already. - -- **BNS subdomains**. These are names whose records are stored off-chain, but are collectively anchored to the blockchain. The ownership and state for these names lives within the P2P network data. While BNS subdomains are owned by separate private keys, a BNS name owner must broadcast their subdomain state. Example subdomains include `jude.personal.id` and `podsaveamerica.verified.podcast`. Unlike BNS namespaces and names, the state of BNS subdomains is _not_ part of the blockchain consensus rules. - -A feature comparison matrix summarizing the similarities and differences between these name objects is presented below: - -| Feature | **Namespaces** | **BNS names** | **BNS Subdomains** | -| -------------------------------------- | -------------- | ------------- | ------------------ | -| Globally unique | X | X | X | -| Human-meaningful | X | X | X | -| Owned by a private key | | X | X | -| Anyone can create | X | X | [1] | -| Owner can update | | X | [1] | -| State hosted on-chain | X | X | | -| State hosted off-chain | | X | X | -| Behavior controlled by consensus rules | X | X | | -| May have an expiration date | | X | | - -[1] Requires the cooperation of a BNS name owner to broadcast its transactions - -## Namespaces - -Namespaces are the top-level naming objects in BNS. - -They control a few properties about the names within them: - -- How expensive they are to register -- How long they last before they have to be renewed -- Who (if anyone) receives the name registration fees -- Who is allowed to seed the namespace with its initial names. - -At the time of this writing, by far the largest BNS namespace is the `.id` namespace. Names in the `.id` namespace are meant for resolving user identities. Short names in `.id` are more expensive than long names, and have to be renewed by their owners every two years. Name registration fees are not paid to anyone in particular---they are instead sent to a "black hole" where they are rendered unspendable (the intention is to discourage ID squatters). - -Unlike DNS, _anyone_ can create a namespace and set its properties. Namespaces are created on a first-come first-serve basis, and once created, they last 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 (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`). - -Namespaces can be between 1 and 19 characters long, and are composed of the characters `a-z`, `0-9`, `-`, and `_`. - -## Subdomains - -BNS names are strongly owned because the owner of its private key can generate valid transactions that update its zone file hash and owner. However, this comes at the cost of requiring a name owner to pay for the underlying transaction in the blockchain. Moreover, this approach limits the rate of BNS name registrations and operations to the underlying blockchain's transaction bandwidth. - -BNS overcomes this with subdomains. A **BNS subdomain** is a type of BNS name whose state and owner are stored outside of the blockchain, but whose existence and operation history are anchored to the blockchain. Like their on-chain counterparts, subdomains are globally unique, strongly owned, and human-readable. BNS gives them their own name state and public keys. Unlike on-chain names, subdomains can be created and managed cheaply, because they are broadcast to the BNS network in batches. A single blockchain transaction can send up to 120 subdomain operations. - -This is achieved by storing subdomain records in the BNS name zone files. An on-chain name owner broadcasts subdomain operations by encoding them as `TXT` records within a DNS zone file. To broadcast the zone file, the name owner sets the new zone file hash with a `NAME_UPDATE` transaction and replicates the zone file. This, in turn, replicates all subdomain operations it contains, and anchors the set of subdomain operations to an on-chain transaction. The BNS node's consensus rules ensure that only valid subdomain operations from _valid_ `NAME_UPDATE` transactions will ever be stored. - -For example, the name `verified.podcast` once wrote the zone file hash `247121450ca0e9af45e85a82e61cd525cd7ba023`, which is the hash of the following zone file: - -```bash -$TTL 3600 -1yeardaily TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxeWVhcmRhaWx5CiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMXllYXJkYWlseS9oZWFkLmpzb24iCg==" -2dopequeens TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAyZG9wZXF1ZWVucwokVFRMIDM2MDAKX2h0dHAuX3RjcCBVUkkgMTAgMSAiaHR0cHM6Ly9waC5kb3Rwb2RjYXN0LmNvLzJkb3BlcXVlZW5zL2hlYWQuanNvbiIK" -10happier TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxMGhhcHBpZXIKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8xMGhhcHBpZXIvaGVhZC5qc29uIgo=" -31thoughts TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzMXRob3VnaHRzCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzF0aG91Z2h0cy9oZWFkLmpzb24iCg==" -359 TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzNTkKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8zNTkvaGVhZC5qc29uIgo=" -30for30 TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzMGZvcjMwCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzBmb3IzMC9oZWFkLmpzb24iCg==" -onea TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiBvbmVhCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vb25lYS9oZWFkLmpzb24iCg==" -10minuteteacher TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxMG1pbnV0ZXRlYWNoZXIKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8xMG1pbnV0ZXRlYWNoZXIvaGVhZC5qc29uIgo=" -36questionsthepodcastmusical TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzNnF1ZXN0aW9uc3RoZXBvZGNhc3RtdXNpY2FsCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzZxdWVzdGlvbnN0aGVwb2RjYXN0bXVzaWNhbC9oZWFkLmpzb24iCg==" -_http._tcp URI 10 1 "https://dotpodcast.co/" -``` - -Each `TXT` record in this zone file encodes a subdomain-creation. For example, `1yeardaily.verified.podcast` resolves to: - -```json -{ - "address": "1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH", - "blockchain": "bitcoin", - "last_txid": "d87a22ebab3455b7399bfef8a41791935f94bc97aee55967edd5a87f22cce339", - "status": "registered_subdomain", - "zonefile_hash": "e7acc97fd42c48ed94fd4d41f674eddbee5557e3", - "zonefile_txt": "$ORIGIN 1yeardaily\n$TTL 3600\n_http._tcp URI 10 1 \"https://ph.dotpodcast.co/1yeardaily/head.json\"\n" -} -``` - -This information was extracted from the `1yeardaily` `TXT` resource record in the zone file for `verified.podcast`. - -### Subdomain Lifecycle - -Note that `1yeardaily.verified.podcast` has a different public key hash (address) than `verified.podcast`. A BNS node will only process a subsequent subdomain operation on `1yeardaily.verified.podcast` if it includes a signature from this address's private key. `verified.podcast` cannot generate updates; only the owner of `1yeardaily.verified.podcast can do so`. - -The lifecycle of a subdomain and its operations is shown in Figure 2. - -``` - subdomain subdomain subdomain - creation update transfer -+----------------+ +----------------+ +----------------+ -| cicero | | cicero | | cicero | -| owner="1Et..." | signed | owner="1Et..." | signed | owner="1cJ..." | -| zf0="7e4..." |<--------| zf0="111..." |<--------| zf0="111..." |<---- ... -| seqn=0 | | seqn=1 | | seqn=2 | -| | | sig="xxxx" | | sig="xxxx" | -+----------------+ +----------------+ +----------------+ - | | | - | off-chain | | -~ ~ ~ ~ | ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~|~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ | ~ ~ ~ ~ ~ ~ ~ ... - | on-chain | | - V V (zone file hash ) V -+----------------+ +----------------+ +----------------+ -| res_publica.id | | jude.id | | res_publica.id | -| NAME_UPDATE |<--------| NAME_UPDATE |<--------| NAME_UPDATE |<---- ... -+----------------+ +----------------+ +----------------+ - blockchain blockchain blockchain - block block block - - -Figure 2: Subdomain lifetime with respect to on-chain name operations .A new -subdomain operation will only be accepted if it has a later "sequence=" number, -and a valid signature in "sig=" over the transaction body .The "sig=" field -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." -However, any on-chain name ("jude.id" in this case) can broadcast a subdomain -update for "cicero.res_publica.id." -``` - -Subdomain operations are ordered by sequence number, starting at 0. Each new subdomain operation must include: - -- The next sequence number -- The public key that hashes to the previous subdomain transaction's address -- A signature from the corresponding private key over the entire subdomain operation. - -If two correctly signed but conflicting subdomain operations are discovered (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 subdomain's operations will be able to determine the valid sequence of state-transitions it has undergone, and determine the current zone file and public key hash for the subdomain. - -### Subdomain Creation and Management - -Unlike an on-chain name, a subdomain owner needs an on-chain name owner's help to broadcast their subdomain operations. In particular: - -- A subdomain-creation transaction can only be processed by the owner of the on-chain name that shares its suffix. For example, only the owner of `res_publica.id` can broadcast subdomain-creation transactions for subdomain names ending in `.res_publica.id`. -- A subdomain-transfer transaction can only be broadcast by the owner of the on-chain name that created it. For example, the owner of `cicero.res_publica.id` needs the owner of `res_publica.id` to broadcast a subdomain-transfer transaction to change `cicero.res_publica.id`'s public key. -- In order to send a subdomain-creation or subdomain-transfer, all of an on-chain name owner's zone files must be present in the Atlas network. This lets the BNS node prove the _absence_ of any conflicting subdomain-creation and subdomain-transfer operations when processing new zone files. -- A subdomain update transaction can be broadcast by _any_ on-chain name owner, but the subdomain owner needs to find one who will cooperate. For example, the owner of `verified.podcast` can broadcast a subdomain-update transaction created by the owner of `cicero.res_publica.id`. - -That said, to create a subdomain, the subdomain owner generates a subdomain-creation operation for their desired name and gives it to the on-chain name owner. - -Once created, a subdomain owner can use any on-chain name owner to broadcast a subdomain-update operation. To do so, they generate and sign the requisite subdomain operation and give it to an on-chain name owner, who then packages it with other subdomain operations into a DNS zone file and broadcasts it to the network. - -If the subdomain owner wants to change the address of their subdomain, they need to sign a subdomain-transfer operation and give it to the on-chain name owner who created the subdomain. They then package it into a zone file and broadcast it. - -### Subdomain Registrars - -Because subdomain names are cheap, developers may be inclined to run subdomain registrars on behalf of their applications. For example, the name `personal.id` is used to register usernames without requiring them to spend any Bitcoin. - -We supply a reference implementation of a [BNS Subdomain Registrar](https://github.com/stacks-network/subdomain-registrar) to help developers broadcast subdomain operations. Users would still own their subdomain names; the registrar simply gives developers a convenient way for them to register and manage them in the context of a particular application. - -# BNS and DID Standards - -BNS names are compliant with the emerging [Decentralized Identity Foundation](http://identity.foundation) protocol specification for decentralized identifiers (DIDs). - -Each name in BNS has an associated DID. The DID format for BNS is: - -```bash - did:stack:v0:{address}-{index} -``` - -Where: - -- `{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 `did:stack:v0:1dARRtzHPAFRNE7Yup2Md9w18XEQAtLiV-0`, because the name `personal.id` was the first-ever name created by `1dARRtzHPAFRNE7Yup2Md9w18XEQAtLiV`. - -As another example, the DID for `jude.id` is `did:stack:v0:16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg-1`. Here, the address `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` had created one earlier name in history prior to this one (which happens to be `abcdefgh123456.id`). - -The purpose of a DID is to provide an eternal identifier for a public key. The public key may change, but the DID will not. - -Stacks Blockchain implements a DID method of its own in order to be compatible with other systems that use DIDs for public key resolution. In order for a DID to be resolvable, all of the following must be true for a name: - -- The name must exist -- The name's zone file hash must be the hash of a well-formed DNS zone file -- The DNS zone file must be present in the Stacks node's data. -- The DNS zone file must contain a `URI` resource record that points to a signed JSON Web Token -- The public key that signed the JSON Web Token (and is included with it) must hash to the address that owns the name - -Not all names will have DIDs that resolve to public keys. However, names created by standard tooling will have DIDs that do. - -A RESTful API is under development. - -## DID Encoding for Subdomains - -Every name and subdomain in BNS has a DID. The encoding is slightly different 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 (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 subdomains owned by a single private key, and version byte 50 for subdomains owned by a m-of-n set of private keys. That is, subdomain DID addresses start with `S` or `M`, respectively. - -The `{index}` field for a subdomain's DID is distinct from the `{index}` field for a BNS name's DID, even if the same created both names and subdomains. For example, the name `abcdefgh123456.id` has the DID `did:stack:v0:16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg-0`, because it was the first name created by `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg`. However, `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` _also_ created `jude.statism.id` as its first subdomain name. The DID for `jude.statism.id` is `did:stack:v0:SSXMcDiCZ7yFSQSUj7mWzmDcdwYhq97p2i-0`. Note that the address `SSXMcDiCZ7yFSQSUj7mWzmDcdwYhq97p2i` encodes the same public key hash as the address `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` (the only difference between these two strings is that the first is base58check-encoded with version byte 0, and the second is encoded with version byte 63). diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/build-apps/references/references.md b/i18n/hi/docusaurus-plugin-content-docs/current/build-apps/references/references.md deleted file mode 100644 index babe5e119a..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/build-apps/references/references.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: References -sidebar_label: References ---- - -[Authentication](./authentication) - -[Blockchain Naming System](./bns) - -[Hiro example apps](https://docs.hiro.so/example-apps) \ No newline at end of file diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/contribute/docs.md b/i18n/hi/docusaurus-plugin-content-docs/current/contribute/docs.md deleted file mode 100644 index 77705451b8..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/contribute/docs.md +++ /dev/null @@ -1,207 +0,0 @@ ---- -title: Contribute to docs -description: Learn how this site is built, and how you can contribute to it. ---- - -## Introduction - -Thank you for your interest in contributing and helping make these docs as good as they can be. - -This docs site is built on the open source platform [Discosaurus 2](https://docusaurus.io/) and most of its content is written in Markdown files. All of the code for this site is free and open source, located at the [GitHub repository here](https://github.com/stacks-network/docs). - -:::tip Don't know what Markdown is? Want to learn? Here is a [helpful guide](https://guides.github.com/features/mastering-markdown/). - -Don't want to learn it? No need to. Write [in plain text an issue on Github](https://github.com/stacks-network/docs/issues/new?assignees=&labels=documentation&template=add-documentation.md&title=%5BAdd+docs%5D) ::: - -:::info You need a free [Github](https://www.github.com) account to add or edit any content. ::: - -To edit any page, just click on the *Edit this page* button at the bottom of each page and submit your changes online. - -To add new content, they are two different ways to do it, the [easy way](#easy-way) and the [advanced way](#advanced-way). - -## Easy way - -[**Simply click here and enter the text of the article you wish to add.**](https://github.com/stacks-network/docs/issues/new?assignees=&labels=documentation&template=add-documentation.md&title=%5BAdd+docs%5D) - -This will open up an issue on github using our template. -## Advanced way - -For more advanced changes you can follow the next steps. - -You can also test the site locally using this method. -### Steps - -1. Fork the [docs reposiroty](https://github.com/stacks-network/docs) by clicking on the *Fork* button in the upper right of the screen. -2. Clone your fork to your local machine with this command `git clone git@github.com:/docs.git stacks_docs` -3. Enter your project folder `cd stacks_docs` -4. Create a branch `git checkout -b feat/my-feature-branch`. -5. You can optionally preview your changes in real time with: - - `npm install` (to install dependencies). - - `npx docusaurus start` to start a local copy of the site. A web browser will open at http://localhost:3000, so you can see a preview of yourhanges in real time. -6. Make the changes you wish and then commit them with this kind of message: `git commit -am "feat: some new feature or content"`. -7. Push to to GitHub with `git push --set-upstream origin feature/my-feature-branch`. -8. Visit GitHub and make your pull request. - -## Aditional information -### Running and building the site locally (optional) - -You can start the page locally with the following command. This is enough to preview your changes. -```bash -npx docusaurus start -``` - -Before running this command for the first time you will need to run `npm install` to install dependencies. - -The docs site will be accessible at this url: [`http://localhost:3000`](http://localhost:3000). - - -After you finished your changes, you can also build the entire site with the following command (not usually needed): -```bash -npm run build -``` - -:::tip `npx docusaurus start` will only load the default language (english). To test all languages you can build with `npm run build` and then preview your build with `npm run serve`. ::: - -### An alternative: Working in browser - -As an alterative to working locally, you can also use the web IDE gitpod that provides an environment to contribute directly from within your browser. - -You only need to have a github account and open [this link](https://gitpod.io/#https://github.com/stacks-network/docs). - -### Folder structure of the site - -If you are interested in only adding new documentation content to the site, the files that will be important to you are located within `./docs/*`: - -```bash -docs/ - build-apps - contribute/ - faq/ - gaia/ - nodes-and-miners/ - noteworthy-contracts/ - references/ - understand-stack/ - write-smart-contracts/ -``` - -The routing for this site is file based, meaning if you created a folder within `/docs/gaia/` named `testing` and in it a file named `test1.md`, you would be able to navigate to `http://localhost:3000/gaia/testing/test1` and you would see whatever content is in that markdown file. - -All the docs in English are stored in the folder `/docs/`. - -To add new English content simply add a markdown file (.md) into any subfolder in docs, and it will be automatically displayed in the category of that folder. - -All the docs in other languages are stored under the folder `i18n`, but these files should never be edited using GitHub as they are overwritten by Crowdin every time new translations are added. **To make changes in other languages**, you must do so using Crowdin. Please refer to [translations](translations) instead. - -### Frontmatter - -Frontmatter is the top part of any markdown document that is written in a language called [YAML](https://yaml.org/). It looks like this: - -```yaml ---- -title: This is my page title -description: A short, concise sentence describing what is on this page ---- -``` - -Frontmatter gives us the ability to define some things within a page that the site can use, such as a page title or page description. When adding any new page, please include a `title` and `description`. - - - -### Use Conventional Commits - -We use the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) as and commits naming convention. Use it while contributing, please. - -### Code blocks - -To write a code block, you need to wrap your code in ` ```language `, and end your code block with ` ``` `. Here is an example of ` ```clarity `. - -```clarity -(define-data-var counter int 0) - -(define-public (get-counter) - (ok (var-get counter))) -``` -### Admonitions - -You can use the following admonitions to highlight content. - -```md -:::note -Some **content** with _markdown_ `syntax`. -::: - -:::tip -Some **content** with _markdown_ `syntax`. -::: - -:::info -Some **content** with _markdown_ `syntax`. -::: - -:::caution -Some **content** with _markdown_ `syntax`. -::: - -:::danger -Some **content** with _markdown_ `syntax`. -::: - -:::tip My personalized title -Some **content** with _markdown_ `syntax`. -::: -``` - -Which renders: - -:::note - -Some **content** with _markdown_ `syntax`. - -::: - -:::tip - -Some **content** with _markdown_ `syntax`. - -::: - -:::info - -Some **content** with _markdown_ `syntax`. - -::: - -:::caution - -Some **content** with _markdown_ `syntax`. - -::: - -:::danger - -Some **content** with _markdown_ `syntax`. - -::: - -:::tip My personalized title - -Some **content** with _markdown_ `syntax`. - -::: \ No newline at end of file diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/contribute/index.md b/i18n/hi/docusaurus-plugin-content-docs/current/contribute/index.md deleted file mode 100644 index ac81d899bd..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/contribute/index.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Contribute -description: Contribute to the Stacks ecosystem. -sidebar_position: 10 -sidebar_label: "Contribute" ---- - -You can contribute to the Stacks ecosystem in multiple ways: - - - -### Documentation - -Contribute to the Stacks Docs on this website. More info [here](docs). - -### Translations - -Help us reach more people with translations. More details [here](translations). - - - -### Articles - -Write an article or a blog post about Stacks. A good place to start is [Stacks Forum](https://forum.stacks.org). - -### Github - -If you are familiar with Github they are multiple repositories of the Stack Ecosystem that you can contribute to. - -- https://github.com/stacks-network/ diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/contribute/translations.md b/i18n/hi/docusaurus-plugin-content-docs/current/contribute/translations.md deleted file mode 100644 index bd9a452333..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/contribute/translations.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Contribute with translations -description: Want to help tranlating these docs to your local language? ---- - -## Help with translations - -Translations are managed with Crowdin. -Anybody can colaborate and no technichal skills are required, as it's all done on the browser. - -To help with translation please go to [this page](https://crowdin.com/project/docsstacksco), click any language and start translating. - -All help is appreciated. - -:::caution -Please don't add any translations to the Github repository, as the translated pages get rewritten from Crowdin. Translations need to be added on Crodin intead. -::: - -### Common issues on translations - -When translating in Crowdin, please only translate the texts and not the html code. - -If you acccidently modify the html tags you will get errors like shown below (`Seems like some formating tags are missing` or `Translation contains tag that source text doesn't have`). These errors will prevent your translation getting published until the tags are left as they were in the original text. - -![](/img/crowdin-qa-issue-formatting_tags_missing.png) ![](/img/crowdin-qa-issue-tag_source.png) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/faq/faq.md b/i18n/hi/docusaurus-plugin-content-docs/current/faq/faq.md deleted file mode 100644 index dde584e583..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/faq/faq.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: General FAQs -description: Frequently Asked Questions -sidebar_label: "FAQ" -sidebar_position: 10 ---- - -![](/img/glasses.png) - -## Why is my transfer still pending? - -Commonly it's because your fee is too low or your [nonce](#what-is-nonce) is incorrect. - -More information can be found [here](https://www.hiro.so/wallet-faq/why-is-my-stacks-transaction-pending). There are also [best practices and known issues](https://forum.stacks.org/t/transactions-in-mempool-best-practices-and-known-issues/11659) and [diagnosing pending transactions](https://forum.stacks.org/t/diagnosing-pending-transactions/11908). - -There is also this [script](https://github.com/citycoins/scripts/blob/main/getnetworkstatus.js) to look at either the first 200 transactions or all the transactions in the mempool, to then return the maximum adn average fee values. We've noticed that using 1.5-2x the average fee in the mempool will generally get things processed within 6-10 blocks even during high congestion. - -There is also this [script](https://github.com/citycoins/scripts/blob/main/gettxstatus.js) to track a pending transaction until it reaches a final status. - -## What is Nonce? - -A nonce is used to make sure that every transaction goes in right order. Nonce starts at 0, so the very first transaction from an address should set to nonce=0. You can find the nonce of your wallet address by searching the address in any [Stacks blockchain explorer](https://explorer.stacks.co/). You can also user `$ stx balance
`. - -If you have a transaction nonce that is less than your account nonce, the transaction is unmineable and will (should) disappear after 256 blocks. This does not affect future transactions and therefore can be just ignored, they are in the past. - -If you have a transaction nonce that is equal to your account nonce, then that transaction is valid and should be the next in line to be processed next. - -If you have a transaction nonce that is higher than your account nonce, then there needs to be a chain of transactions starting with your account nonce in order for it to be processed. E.g. Your account nonce is 10 but the pending transaction has a nonce of 12. It will not be mineable until a transaction with nonces 10 and 11 are processed. - -## Whats a Replace-by-fee (RBF)? - -A replace-by-fee (RBF) transaction tells the blockchain that you would like to replace one transaction with another, while specifying a fee that is higher than the original transaction fee. A transaction can be replaced with **any other transaction**, and is not limited to the same operation. - -This can be used to effectively **cancel a transaction** by replacing it with something else, like a small STX transfer to another owned address. - -This can be used to **raise the fee for a pending transaction** so it is considered by miners during periods of high congestion. This can also be used to _resubmit_ a transaction, in the sense that the RBF transaction gets a new txid and gets considered again (or faster) by miners. E.g. I submit my transaction with 1 STX fee at block 54,123. By block 54,133 I see my tx hasn’t been picked up, so I RBF with 1.1 STX. Then wait 10 blocks again, and RBF again if not received. There’s a balance between doing this too often and keeping a consistent pace, but it has been seen to help get transactions through, especially when new ones are constantly flooding in. - -The replacement transaction needs to use the same nonce as the original transaction with a fee increase of at least 0.000001 STX. E.g. Your original transaction has a fee of 0.03 STX, the new RBF transaction must have a fee of 0.030001 STX or above. - -RBF transactions process in one of two ways: - -- If miners pick up the original transaction before the RBF transaction is received, then the original transaction is processed and the replacement transaction goes into an unmineable state. It will eventually disappear and doesn’t affect future transactions. -- If miners pick up the replaced transaction then the new transaction is processed instead of the original, and the status of the original transaction is set to “droppped_replaced_by_fee”. This status is not shown on the explorer but can be seen when querying the txid. - -Submitting multiple transactions for the same action can slow things down in a few ways. - -- If the total spent in 2 or 3 transactions is more than can be spent in a single transaction, the transactions appear unmineable. -- If the fees for multiple transactions exceed the STX balance, the transactions will be unmineable. - -## What are .btc domains? - -[This forum post](https://forum.stacks.org/t/btc-domains-are-live/12065) explains all the benefits of .btc domains. They can currently be purchased in [btc.us](https://btc.us/) - -## What is the blockchain trilemma? - -## Stacks vs. Solana vs. Polygon: How Do They Compare From a Developer Perspective? - -[This blog post answers the question](https://www.hiro.so/blog/stacks-vs-solana-vs-polygon-how-do-they-compare-from-a-developer-perspective). - -## What Does Lightning’s Taro Proposal Mean for Stacks? - -[This blog post answers the question](https://www.hiro.so/blog/what-does-lightnings-taro-proposal-mean-for-stacks). - - -## Is Stacks a [PoS chain](https://en.wikipedia.org/wiki/Proof_of_stake)?[¹][] - -No. - -The act of block production requires an extrinsic expenditure — it is not tied to owning the native token, as would be required in PoS. The only way to produce blocks in the Stacks chain is to transfer Bitcoin to a predetermined randomized list of Bitcoin addresses. Moreover, the Stacks blockchain can fork, and there exists a protocol to rank forks by quality independent of the set of miners and the tokens they hold. These two properties further distinguish it from PoS chains, which cannot fork due to the inability to identify a canonical fork without trusting a 3rd party to decree a particular fork as valid. The ability to fork allows the Stacks blockchain to survive failure modes that would crash a PoS chain. - -## Is Stacks a [sidechain](https://en.bitcoin.it/wiki/Sidechain)?[¹][] - -No. - -For two key reasons. - -First, the history of all Stacks blocks produced is recorded to Bitcoin. This means that the act of producing a private Stacks fork is at least as hard as reorging the Bitcoin chain. This in turn makes it so attacks on the chain that rely on creating private forks (such as selfish mining and double-spending) are much harder to carry out profitably, since all honest participants can see the attack coming before it happens and have a chance to apply countermeasures. Sidechains offer no such security benefit. - -Second, the Stacks blockchain has its own token; it does not represent pegged Bitcoin. This means that the safety of the canonical fork of the Stacks blockchain is underpinned by its entire token economy’s value, whereas the safety of a sidechain’s canonical fork is underpinned only by whatever system-specific measures incentivize its validators to produce blocks honestly, or the Bitcoin miners’ willingness to process peg-in requests (whichever is the weaker guarantee). - - -## Is Stacks a [layer-2 system](https://academy.binance.com/en/glossary/layer-2) for Bitcoin?[¹][] - -No. - -Stacks blockchain is a layer-1 blockchain, which uses a novel and unique mining protocol called proof-of-transfer (PoX). A PoX blockchain runs in parallel to another blockchain (Bitcoin in Stacks’ case), which it uses as a reliable broadcast medium for its block headers. It's a sovereign system in its own right. The Stacks blockchain state is distinct from Bitcoin, and is wholly maintained by and for Stacks nodes. Stacks transactions are separate from Bitcoin transactions. Layer-2 systems like Lightning are designed to help scale Bitcoin payment transactions, whereas Stacks is designed to bring new use-cases to Bitcoin through smart contracts. Stacks is not designed as a Bitcoin layer-2 scalability solution. - - -## Is Stacks a [merged-mined chain](https://en.bitcoin.it/wiki/Merged_mining_specification)?[¹][] - -No. - -The only block producers on the Stacks chain are Stacks miners. Bitcoin miners do not participate in Stacks block validation, and do not claim Stacks block rewards. Moreover, Stacks is not a [blind merged-mined chain](https://github.com/bitcoin/bips/blob/master/bip-0301.mediawiki), because STX block winners are public and randomly chosen (instead of highest-bid-wins), and its tokens are minted according to a schedule that is independent of the degree of miner commitment or Bitcoin transferred (instead of minted only by one-way pegs from Bitcoin). This ensures that Stacks is able to make forward progress without opt-in from Bitcoin miners, and it ensures that Stacks miners are adequately compensated for keeping the system alive regardless of transaction volume. - -## Whats the difference between Stacks and Ethereum?[²][] -**Computation and Storage** Stacks does all computation and storage outside of the blockchain, and uses the blockchain only as a “shared source of truth” between clients. By contrast, Ethereum does all computation and most application storage in the blockchain itself. Like Ethereum, if two Stacks nodes see the same underlying blockchain, they will independently run the same computations and produce the same state. Unlike Ethereum, there is no Stacks-specific blockchain. - -**Programming Language and Tooling** Stacks’s programming model is based on running off-chain programs. These programs can be written and debugged in any language you want. By contrast, Ethereum’s programming model is based on running on-chain “smart contracts.” These are written and debugged with a whole new set of tools, like Solidity and Serpent. - -**Scalability of On-chain Computation** Stacks is designed around a “virtual chain” concept, where nodes only need to reach consensus on the shared “virtual chain” they’re interested in. Virtual chains do not interact with one another, and a single blockchain can host many virtual chains. Although Stacks’s specific virtual chain is not Turing-complete (i.e. it’s a list of instructions to build the name database), it is possible to create Turing-complete virtual chains like Ethereum. These virtual chains can live in any blockchain for which there exists a driver, and virtual chain clients only need to execute their virtual chain transactions (i.e. Stacks only processes Stacks virtual chain transactions). - -By contrast, because smart contracts run on-chain and can call one another, all Ethereum nodes need to process all smart contracts’ computations in order to reach consensus. This can get expensive as the number of running smart contracts grow, which takes the form of gas fee increases. - -**Scalability of Off-chain Computation** Stacks applications are very similar to Web applications today and almost never need to interact with the blockchain. For most Stacks applications, the blockchain is only used to authenticate the application’s code and data before the user runs it. By contrast, Ethereum applications usually require an application-specific smart contract, and must interact with the blockchain to carry out its operations. - - -[¹]: https://stacks.org/stacks-blockchain -[²]: https://forum.stacks.org/t/what-is-the-difference-between-blockstack-and-ethereum/781 diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/gaia/configuration.md b/i18n/hi/docusaurus-plugin-content-docs/current/gaia/configuration.md deleted file mode 100644 index 9fa365d7bf..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/gaia/configuration.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Configuration -description: Configuring Gaia Hub ---- - -## Configuration files - -The following configuration files exist in the folder `deploy/configs/gaia/`: - -``` -admin-config.json -hub-config.json -reader-config.json -``` - -## GAIA Admin Service - -You can also use the GAIA Admin Service to remotely administer it with an API Key. It will require you to install `npm` with a `apt install npm`. Once `npm` is installed you can continue with the steps in the [GAIA Admin Service](https://github.com/stacks-network/gaia/blob/master/admin/README.md). - -## Driver Selection - -The Gaia hub currently supports the following drivers: - -``` -'aws' == Amazon S3 -'azure' == Azure Blob Storage -'disk' == Local disk -'google-cloud' === Google Cloud Storage -``` - -Set the driver you wish to use in your [config.json](https://github.com/stacks-network/gaia/blob/master/hub/config.sample.json) file with the `driver` parameter. Many drivers additionally accept the `bucket` parameter, which controls the bucket name that files should be written to. - -These driver may require you to provide additional credentials for performing writes to the backends. See `config.sample.json` for fields for those credentials. In some cases, the driver can use a system configured credential for the backend (e.g., if you are logged into your AWS CLI account, and run the hub from that environment, it won't need to read credentials from your `config.json`). - -:::caution -The disk driver requires a \*nix like filesystem interface, and will not work correctly when trying to run in a Windows environment. -::: - -## Note on SSL - -We _strongly_ recommend that you deploy your Gaia hub with SSL enabled. Otherwise, the tokens used to authenticate with the Gaia hub may be stolen by attackers, which could allow them to execute writes on your behalf. -Configuration options are available to run the hub with an `https` Node.js server. -Otherwise, a reverse proxy web server such as nginx or Apache can be used. - -## Require Correct Hub URL - -If you turn on the `requireCorrectHubUrl` option in your `config.json` file, your Gaia hub will require that authentication requests correctly include the `hubURL` they are trying to connect with. This is used to prevent a malicious gaia hub from using an authentication token for itself on other Gaia hubs. - -By default, the Gaia hub will validate that the supplied URL matches `https://${config.serverName}`, but if there are multiple valid URLs for clients to reach the hub at, you can include a list in your `config.json`: - -```javascript -{ - .... - serverName: "normalserver.com" - validHubUrls: [ "https://specialserver.com/", - "https://legacyurl.info" ] - .... -} -``` - -## The readURL parameter - -By default, the gaia hub drivers will return read URLs which point directly at the written content. For example, an S3 driver would return the URL directly to the S3 file. However, if you configure a CDN or domain to point at that same bucket, you can use the `readURL` parameter to tell the gaia hub that files can be read from the given URL. For example, the `hub.blockstack.org` Gaia Hub is configured to return a read URL that looks like `https://gaia.blockstack.org/hub/`. - -Unset this configuration parameter if you do not intend to deploy any caching. - -## Minimum Proofs Requirement - -The gaia hub can also be configured to require a minimum number of social proofs in a user's profile to accept writes from that user. This can be used as a kind of spam-control mechanism. However, we recommend for the smoothest operation of your gaia hub, to set the `proofsConfig.proofsRequired` configuration key to `0`. - -## CDN & Replicated Hubs - -- https://docs.microsoft.com/en-us/azure/storage/blobs/storage-https-custom-domain-cdn - -- The hub implementation is designed to be ran from a single Node.js instance. If the hub instance is sharded (e.g. replicated hubs via load balancing), then any given `bucket` (identified by URI segment) must be served by the same instance, At least a couple elements of the Gaia Hub depend on this: token invalidation in-memory caching, and resource endpoint 409 contention behavior. diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md b/i18n/hi/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md deleted file mode 100644 index 558cbb14f5..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Deploy Gaia Hub -description: Steps and tutorials ---- - -## Deploy your GAIA hub - -Tutorials to deploy your own GAIA hub are currently available for [Linux](./setup-linux), [MacOS](./setup-mac) and [Amazon EC2 / CloudFormation](./gaia-on-ec2). - -Regardless of what server the Gaia Hub runs on, the storage it uses can currently be deployed on multiple platforms: - -- Local disk (the server itself) -- Amazon S3 -- Azure Blob Storage -- Google Cloud - -:::tip -Support for IPFS is under development. -::: \ No newline at end of file diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md b/i18n/hi/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md deleted file mode 100644 index 2067e7d57c..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Amazon EC2 -description: Use a template to deploy a Gaia hub on Amazon EC2 -tags: - - tutorial - - gaia ---- - -## Introduction - -The template provided on this page provides an easy way to deploy a Gaia hub directly to Amazon EC2. You can use this template to deploy your own Gaia hub to your Amazon Web Services (AWS) account. Amazon EC2 is an affordable and convenient cloud computing provider. The template provides a one-click deploy for Amazon EC2 with either S3 or EBS as a storage provider. - -## Prerequisites - -This procedure uses Amazon CloudFormation to configure an EC2 cloud compute provider to run the Gaia hub service with an S3 or EBS provider for file storage. You should have access to an AWS account either through your personal account or through a corporate account. This account should have permissions to create resources. - -Additionally, you must also own a domain name and be able to update the DNS records associated with that domain name. - -## Setup steps - -### Step 1 - Create Stack - -Use a link in the table to launch the [CloudFormation](https://console.aws.amazon.com/cloudformation/) template in the AWS region that you wish to deploy a Gaia hub. - -![Create stack](/img/cloudformation-create-stack.png) - -### Step 2 - Setup stack using template - -You need to configure the template with the appropiate values for your hub and domain it runs on. - -Select `Template is ready` and `Amazon S3 URL` and enter the following Amazon S3 URL: -``` -https://s3-external-1.amazonaws.com/cf-templates-vzldibfi2mw8-us-east-1/2022160J6G-cloudformation.yaml -``` - -If you prefer you can instead select `Template is ready` and `Upload a template file` to upload the template file `cloudformation.yaml`. - -The latest `cloudformation.yaml` file can be downloaded [here](https://raw.githubusercontent.com/stacks-network/gaia/master/deploy/cloudformation.yaml). On most browsers you can right-click on that page and click on `Save page as` to download the file. Alternatively, you can copy/paste the text into a text file called `cloudformation.yaml`. - -Then click `Next`. - -![Specify template](/img/cloudformation-specify-template.png) - -### Step 3 - Specify stack details - -Specify the stack details and then click `Next`: ![Specify template](/img/cloudformation-specify-stack-details.png) - -| Field | Value | Notes | -| --------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Stack name | _a unique name in your AWS account_ | e.g.: my_gaia_hub | -| DomainName | _your-domain_ | | -| EmailAddress | _your email address_ | | -| GaiaBucketName | _S3 bucket name_ | The template combines this name with the stack name to create a unique S3 bucket. The template ignores this field if GaiaStorageType is set to `disk`. | -| GaiaStorageType | `s3` or `disk` | Select the GaiaStorageType of which to use as a backend for the Gaia Hub. Selecting `s3` causes the template to create an S3 bucket based on the name given in the previous field. Selecting `disk` causes the template to attach a separate EBS volume to the EC2 instance for Hub storage. | -| InstaceType | t2.micro | Select the instance type you want. Default value is `t2.micro`. | -| KeyName | | In the KeyName drop-down, select an [EC2 KeyPair](https://console.aws.amazon.com/ec2/v2/home?region=us-east-1#KeyPairs:) to enable SSH access to the EC2 instance. You should download the `.pem` keyfile for this pair from the EC2 console. For more information see the [EC2 key pair documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html#prepare-key-pair) | -| SSHLocation | 0.0.0.0/0 | Leave the SSHLocation field with the default value of `0.0.0.0/0` to enable SSH access from any IP address. If you wish to restrict SSH access to the EC2 instance to a certain IP, you can update this field. | -| SubnetId | _subnetid_ | Select a public subnet | -| VpcId | _vpcid_ | | - -### Step 4 - Configure stack options - -Configure any stack options that fit your desired setup and click `Next`. All these fields are optional. - -![Specify template](/img/cloudformation-stack-options.png) - -### Step 5 - Review - -Review the configuration of your Gaia hub, select the checkbox to acknowledge that AWS may create IAM resources with custom names and click on `Create stack`. - -![Specify template](/img/cloudformation-iam-resources.png) - -### Step 6 - Retrieve the public IP of your Gaia hub - -Your stack can take several minutes to launch. You can monitor the Events tab of your hub to review the current progress of the launch. When the launch is complete, the Outputs tab displays information about the hub. Select the PublicIP and copy it to configure your domain name. - -Create an `A` DNS record pointing to the given IP in your domain. - -Wait a few minutes for the DNS record to propagate, and your should be able to access your Gaia hub with SSH. - -## Accessing your Gaia hub with SSH - -To SSH into your Gaia hub EC2 host directly, you must have the keyfile used in container creation. Access the host with the following command in your terminal: - -```bash -ssh -i admin@ -``` - -:::tip If you can only access SSH with the IP but not with the DNS name and you wish to do so, you can optionally activate it by following these steps: - - Open your [AWS Console](https://console.aws.amazon.com) - Click on `Service` -> VPC - Open Your VPCs - Select your VPC connected to your Gaia Hub - Click `Actions` -> `Edit DNS Hostnames` -> Change `DNS hostnames` to `Enable` -::: -## Graphical representation of the cloudformation template - -![](/img/cloudformation-gaia-template1-designer.png) \ No newline at end of file diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/gaia/gaia.md b/i18n/hi/docusaurus-plugin-content-docs/current/gaia/gaia.md deleted file mode 100644 index 1070857350..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/gaia/gaia.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Gaia -description: Decentralized storage architecture for off-chain data -sidebar_position: 5 -tags: - - gaia ---- - -## Introduction - -Apps built with the Stacks blockchain store off-chain data using a storage system called Gaia. - -Whereas public transactional metadata is best stored on the Stacks blockchain, user application data can often be stored more efficiently and privately in Gaia storage. - -Storing data off of the blockchain ensures that Stacks applications can provide users with high performance and high availability for data reads and writes without introducing central trust parties. - -:::tip Latest whitepaper of GAIA (May 2022) is available [here](https://dev1-gaia-hub.s3.amazonaws.com/GAIA_Whitepaper.pdf) ::: - -## Understand Gaia in the Stacks architecture - -The following diagram depicts the Stacks architecture and Gaia's place in it: - -![Stacks Architecture](/img/architecture.png) - -Blockchains require consensus among large numbers of people, so they can be slow. Additionally, a blockchain is not designed to hold a lot of data. This means using a blockchain for every bit of data a user might write and store is expensive. For example, imagine if an application were storing every tweet in the chain. - -The Stacks blockchain addresses performance problems using a layered approach. The base layer consists of the Stacks blockchain and the Blockchain Naming System (BNS). The blockchain governs ownership of identities in the Stacks network. Identities can be names such as domain names, usernames, or application names. - -When an identity is created, its creation is recorded in the Stacks blockchain. Identities make up the primary data stored into the Stacks blockchain. These identities correspond to routing data in the OSI stack. The routing data is stored in the Atlas Peer Network, the second layer. Every core node that joins the Stacks Network is able to obtain an entire copy of this routing data. Stacks uses the routing data to associate identities (domain names, user names, and application names) with a particular storage location in the final layer, the Gaia Storage System. - -A Gaia Storage System consists of a _hub service_ and storage resource on a cloud software provider. The storage provider can be any commercial provider such as Azure, DigitalOcean, Amazon EC2, and so forth. Typically the compute resource and the storage resource reside same cloud vendor, though this is not a requirement. Gaia currently has driver support for S3, Azure Blob Storage, Google Cloud Platform and local disk, but the driver model allows for other backend support as well. - -Gaia stores data as a simple key-value store. When an identity is created, a corresponding data store is associated with that identity on Gaia. When a user logs into a dApp, the authentication process gives the application the URL of a Gaia hub, which then writes to storage on behalf of that user. - -The Stacks blockchain stores only identity data. Data created by the actions of an identity is stored in a Gaia Storage System. Each user has profile data. When a user interacts with a decentralized dApp that application stores application data on behalf of the user. Because Gaia stores user and application data off the blockchain, a Stacks DApp is typically more performant than DApps created on other blockchains. - -## User control or how is Gaia decentralized? - -A Gaia hub runs as a service which writes to data storage. The storage itself is a simple key-value store. The hub service writes to data storage by requiring a valid authentication token from a requestor. Typically, the hub service runs on a compute resource and the storage itself on separate, dedicated storage resource. Typically, both resources belong to the same cloud computing provider. - -![Gaiastorage](/img/gaia-storage.png) - -Gaia's approach to decentralization focuses on user control of data and its storage. Users can choose a Gaia hub provider. If a user can choose which Gaia hub provider to use, then that choice is all the decentralization required to enable user-controlled applications. Moreover, Gaia defines a uniform API for applications to access that data. - -The control of user data lies in the way that user data is accessed. When an application fetches a file `data.txt` for a given user `alice.id`, the lookup will follow these steps: - -1. Fetch the `zonefile` for `alice.id`. -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. Find the read-only url out of the profile's `appsMeta` section (e.g. `https://example-app.gaia.alice.org`). -6. Fetch the file from `https://example-app.gaia.alice.org/data.txt`. - -Because `alice.id` has access to her [zonefile](https://docs.stacks.co/references/bns-contract#name-update), 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. - -:::caution -Users with existing identities cannot yet migrate their data from one hub to another. -::: - -Applications writing directly on behalf of `alice.id` do not need to perform a lookup. Instead, the [Stacks authentication flow](https://stacks.js.org) provides Alice's chosen gaia hub URL to the application. This authentication flow _is also_ within Alice's control because Alice's wallet _must_ generate the authentication response. - -## Understand data storage - -A Gaia hub stores the written data _exactly_ as given. It offers minimal guarantees about the data. It does not ensure that data is validly formatted, contains valid signatures, or is encrypted. Rather, the design philosophy is that these concerns are client-side concerns. - -Client libraries (such as [`Stacks.js`](https://stacks.js.org/)) are capable of providing these guarantees. A liberal definition of the [end-to-end principle](https://en.wikipedia.org/wiki/End-to-end_principle) guides this design decision. - -When an application writes to a Gaia hub, an authentication token, key, and the data are passed to the Gaia hub. - -![Gaia writes](/img/gaia-writes.png) - -The token ensures the app has the authorization to write to the hub on the user's behalf. - -## Gaia versus other storage systems - -Here's how Gaia stacks up against other decentralized storage systems. Features that are common to all storage systems are omitted for brevity. - -| Features | [Gaia](https://github.com/stacks-network/gaia) | [Sia](https://sia.tech/) | [Storj](https://storj.io/) | [IPFS](https://ipfs.io/) | [DAT](https://datproject.org/) | [SSB](https://www.scuttlebutt.nz/) | -| ------------------------------------------ | ---------------------------------------------- | ------------------------ | -------------------------- | ------------------------ | ------------------------------ | ---------------------------------- | -| User controls where data is hosted | X | | | | | | -| Data can be viewed in a normal Web browser | X | | | X | | | -| Data is read/write | X | | | | X | X | -| Data can be deleted | X | | | | X | X | -| Data can be listed | X | X | X | | X | X | -| Deleted data space is reclaimed | X | X | X | X | | | -| Data lookups have predictable performance | X | | X | | | | -| Writes permission can be delegated | X | | | | | | -| Listing permission can be delegated | X | | | | | | -| Supports multiple backends natively | X | | X | | | | -| Data is globally addressable | X | X | X | X | X | | -| Needs a cryptocurrency to work | | X | X | | | | -| Data is content-addressed | | X | X | X | X | X | diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/gaia/setup-linux.md b/i18n/hi/docusaurus-plugin-content-docs/current/gaia/setup-linux.md deleted file mode 100644 index db427f890a..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/gaia/setup-linux.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: Linux -description: Steps to setup a GAIA hub on a Linux server (fresh install). This example is using Debian, but should work on any Linux distribution. It uses docker compose in the backgroud. -tags: - - tutorial - - gaia ---- - -This configuration will setup the following 4 docker containers: - -- Nginx with certbot on TCP ports 80 and 443. -- Gaia hub on TCP port 3000. -- Gaia admin on TCP port 8009. -- Gaia reader on TCP port 8008 - -**1. Update the system and install the dependencies and software we will use to test:** - -```bash -apt update && apt upgrade -y && apt install -y git vim gnupg jq -``` - -**2. Install [docker](https://docs.docker.com/engine/install/debian/) and [docker-compose](https://docs.docker.com/compose/cli-command/#install-on-linux)** in your OS. -For our example we install _docker_ with: - -```bash -curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg - -echo \ - "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian \ - $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null - -apt update && apt install -y docker-ce docker-ce-cli containerd.io -``` - -Install _docker-compose_ by downloading the [latest-release](https://github.com/docker/compose/releases): - -```bash -VERSION_DC=$(curl --silent https://api.github.com/repos/docker/compose/releases/latest | jq .name -r) -DESTINATION_DC=~/.docker/cli-plugins -mkdir -p ${DESTINATION_DC} -curl -SL https://github.com/docker/compose/releases/download/${VERSION_DC}/docker-compose-linux-x86_64 -o ${DESTINATION_DC}/docker-compose -chmod +x ${DESTINATION_DC}/docker-compose -``` - -**3. Clone the GAIA repository** and enter it's docker directory. - -```bash -git clone https://github.com/stacks-network/gaia.git && cd gaia/deploy/docker -``` - -**4. Copy and edit appropiate .env file**. -In the folder `./deploy/docker/` they are different sample files for different configurations like using aws, azure or disk among others. In this example we will store the data localy so we will copy the _disk_ file and update the domain and email fields. Please change `gaia.site.com` and `gaiarocks@mydomain.com` accordingly. Note you need both for the SSL certificate to be created correctly. - -```bash -export MYGAIADOMAIN=gaia.site.com -export MYGAIAEMAIL=gaiarocks@mydomain.com -cp sample-disk.env disk.env -sed -i 's/my-domain.com/'"$MYGAIADOMAIN"'/g' disk.env -sed -i 's/my-email@example.com/'"$MYGAIAEMAIL"'/g' disk.env - -``` - -**5. Start GAIA HUB service** - -To start GAIA HUB - -```bash -./gaiahub.sh start -``` - -To stop GAIA HUB - -```bash -./gaiahub.sh stop -``` - -To view GAIA HUB status - -```bash -./gaiahub.sh status -``` - -**6. Verify server works locally** with the following command: - -```bash -curl -sk http://localhost/hub_info | jq -``` - -A correct result should look similar to this: - -```bash - { - "challenge_text": "[\"gaiahub\",\"0\",\"gaia-0\",\"blockstack_storage_please_sign\"]", - "latest_auth_version": "v1", - "max_file_upload_size_megabytes": 20, - "read_url_prefix": "https://gaia.site.com/reader/" - } -``` - -**7. Test your GAIA HUB** Running `gaia_test.js` will test your GAIA Hub, by trying to connect to it, uploading a file and downloading it again. - -First install all required dependencies with: - -```bash -npm install -``` - -Then, from the root folder of the project type: - -```bash -node ./deploy/gaia_test.js https://yourgaiaurl -``` - -A correct result will be something like this: - -``` -Will run a test for the GAIA HUB: https://gaia.mydomain.com -Generating some test keys... -Private key: 5aacc60fc2a429e1f02be139f3cac82061c6a980******************** -Public key: 025691f17f2ab80dc4af363bb9c7aac59e9e1db6ae8ff668202582a3f4ec9678ff -Address: 15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS -[DEBUG] connectToGaiaHub: https://gaia.mydomain.com/hub_info -[DEBUG] uploadToGaiaHub: uploading testing.txt to https://gaia.mydomain.com -File uploaded successfully. -Upload to gaia hub thinks it can read it from: https://gaia.mydomain.com/reader/15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS/testing.txt -Hub info thinks it can read it from : https://gaia.mydomain.com/reader/15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS/testing.txt -Let's now try to fetch the uploaded file... -File fetched successfully. Contents of file: GAIA ROCKS! -``` diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/gaia/setup-mac.md b/i18n/hi/docusaurus-plugin-content-docs/current/gaia/setup-mac.md deleted file mode 100644 index 808833b212..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/gaia/setup-mac.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: MacOS -description: MacOS for local testing/development -tags: - - tutorial ---- - -The following assumes you have [Docker Installed](https://docs.docker.com/docker-for-mac/install/) - -- Recommended to also have [MacOS Homebrew](https://docs.brew.sh/Installation) installed -- Use Homebrew to install jq with `brew install jq` - -In your working directory: - -**1. Clone a copy of the [gaia repo](https://github.com/stacks-network/gaia):** - -```bash -$ git clone -b master --single-branch https://github.com/stacks-network/gaia -``` - -**2. Change your cwd:** - -```bash -$ cd gaia/deploy/docker -``` - -**3. Create a copy of sample-disk.env and fill out the values:** - -``` -$ cp sample-disk.env disk.env -# Update the DOMAIN_NAME variable to `localhost` -``` - -**4. Start the server:** - -``` -$ docker-compose -f docker-compose-base.yaml -f docker-compose-disk.yaml --env-file disk.env up -``` - -**5. Verify the server is responding locally:** - -``` -$ curl -sk https://localhost/hub_info | jq - { - "challenge_text": "[\"gaiahub\",\"0\",\"gaia-0\",\"blockstack_storage_please_sign\"]", - "latest_auth_version": "v1", - "max_file_upload_size_megabytes": 20, - "read_url_prefix": "https://localhost/reader/" - } -``` - -### Modifying the configuration for your gaia-hub - -Two methods exist: - -1. Edit the `gaia/deploy/configs/gaia/hub-config.json` using `vim` or other - -- requires a restart of the containers: `docker-compose -f docker-compose-base.yaml -f docker-compose-disk.yaml --env-file disk.env restart` - -2. Use the running `admin` container to modify any config values, and also reload the hub when complete: - -- [GitHub - Gaia Admin README.md](https://github.com/stacks-network/gaia/blob/master/admin/README.md) - -``` -$ export API_KEY="hello" -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - -H 'Content-Type: application/json' \ - -X POST \ - --data-raw '{"serverName": "myserver"}' \ - http://localhost:8009/v1/admin/config - -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - -X POST \ - http://localhost:8009/v1/admin/reload - -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - http://localhost:8009/v1/admin/config | jq -``` diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/governance/_index.md b/i18n/hi/docusaurus-plugin-content-docs/current/governance/_index.md deleted file mode 100644 index 1ecdf67871..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/governance/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Governance -description: Governance -sidebar_position: 9 ---- - -This page needs contributions. Help us write it! \ No newline at end of file diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/governance/index.md b/i18n/hi/docusaurus-plugin-content-docs/current/governance/index.md deleted file mode 100644 index 91b0215b5f..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/governance/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Governance -description: Governance -sidebar_position: 9 ---- - -![](/img/stacks-governance.png) - -This page needs contributions. Help us write it! - -Governance in web3 is driven by the community. - -How can I get involved ? - -[Governance Resources website](https://resources.stacksgov.com) - -[Github - Stack Community Governance](https://github.com/stacksgov) - -:::tip Community Calls Monthly community calls are recorded and available [here](https://www.youtube.com/playlist?list=PLg717Ri_rTnwwYjQYlc7rIP6x2FaTNn7f) ::: diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/governance/sips.md b/i18n/hi/docusaurus-plugin-content-docs/current/governance/sips.md deleted file mode 100644 index 29ac1ae1ed..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/governance/sips.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: SIPs -description: SIPs -sidebar_position: 9 ---- - -## Stacks Improvement Proposals (SIPs) - -Stacks improvement proposals (SIPs) are aimed at describing the implementation of the Stacks blockchain, as well as proposing improvements. - -The SIP process [(SIP-000)](https://github.com/stacksgov/sips/blob/main/sips/sip-000/sip-000-stacks-improvement-proposal-process.md) describes how to make a SIP and get it ratified. - -They should contain concise technical specifications of features or standards and the rationale behind it. SIPs are intended to be the primary medium for proposing new features, for collecting community input on a system-wide issue, and for documenting design decisions. - -The SIPs are located in the [stacksgov/sips](https://github.com/stacksgov/sips) repository as part of the [Stacks Community Governance organization](https://github.com/stacksgov). - -Anyone in the Stacks community can submit a SIP. - -:::tip Stacks Improvement Proposals Community Calls SIP Meeting calls are recorded and available [here](https://www.youtube.com/playlist?list=PLg717Ri_rTnx5kuaWqp3cUAtwQk_yzslT) - -More details of the meetings are available [here](https://github.com/stacksgov/sips/issues/79) ::: - -## Ratified SIPSs - -- [x] [SIP 001: Burn Election](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md) -- [x] [SIP 002: Clarity, a language for predictable smart contracts](https://github.com/stacksgov/sips/blob/main/sips/sip-002/sip-002-smart-contract-language.md) -- [x] [SIP 003: Peer Network](https://github.com/stacksgov/sips/blob/main/sips/sip-003/sip-003-peer-network.md) -- [x] [SIP 004: Cryptographic Committment to Materialized Views](https://github.com/stacksgov/sips/blob/main/sips/sip-004/sip-004-materialized-view.md) -- [x] [SIP 005: Blocks, Transactions, and Accounts](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md) -- [x] [SIP 006: Clarity Execution Cost Assessment](https://github.com/stacksgov/sips/blob/main/sips/sip-006/sip-006-runtime-cost-assessment.md) -- [x] [SIP 007: Stacking Consensus](https://github.com/stacksgov/sips/blob/main/sips/sip-007/sip-007-stacking-consensus.md) -- [x] [SIP 008: Clarity Parsing and Analysis Cost Assessment](https://github.com/stacksgov/sips/blob/main/sips/sip-008/sip-008-analysis-cost-assessment.md) -- [x] [SIP 009: Standard Trait Definition for Non-Fungible Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-009/sip-009-nft-standard.md) -- [x] [SIP 010: Standard Trait Definition for Fungible Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-010/sip-010-fungible-token-standard.md) -- [x] [SIP 012: Burn Height Selection for a Network Upgrade to Introduce New Cost-Limits](https://github.com/stacksgov/sips/blob/main/sips/sip-012/sip-012-cost-limits-network-upgrade.md) -- [x] [SIP-016: Metadata for Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-016/sip-016-token-metadata.md) - -## How to Get Involved - -There are several ways you can get involved with the SIP process: - -* **Join the weekly SIP Meeting call** listed [here](https://community.stacks.org/events). - -* **SIP Editor**. SIP editors help SIP authors make sure their SIPs are well-formed and follow the right process. They help get SIPs ready for deep review by advancing it them from Draft to Accepted status. If you want to become a SIP editor, open an issue with your name and email to ask to be added to the list of SIP editors. - -* **Join a CAB** (Consideration Advisory Board). SIPs fall under the purview of one or more considerations. A full list is in [this github](https://github.com/stacksgov/sips/tree/main/considerations) directory. Currently they are: Diversity, Economics, Ethics, Governance and Technical. Members of SIP consideration advisory boards use their domain expertise to give Accepted SIPs a deep read, and give the authors any/all feedback to help make the SIP workable. If you want to join a board, reach out to the board's chairperson via the listed contact information. - -* **Steering Committee**. The Steering Committee organizes the consideration advisory boards and votes to advance Recommended SIPs to Activation-in-Progress status, and then to either Ratified or Rejected status. Once they are in the process of being activated, they use a SIP's Activation section to determine whether or not the Stacks ecosystem has ratified or rejected the SIP. Joining this committee requires the consent of the Stacks Foundation board. diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/intro.md b/i18n/hi/docusaurus-plugin-content-docs/current/intro.md deleted file mode 100644 index 84f1eaa649..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/intro.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_label: "Home" -sidebar_position: 1 ---- - -# Stacks Docs Introduction - -Welcome to the community driven official Stacks Documentation. - -Learn about Stacks mining, the STX token, and the Clarity smart contract language. - -![](/img/Bitcoinet-L_2.svg) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md b/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md deleted file mode 100644 index dd7194f504..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Stacks on DigitalOcean -description: A guide to setup Stacks on DigitalOcean -sidebar_position: 4 -tags: - - tutorial ---- - -## Introduction - -This is a step by step guide to deploy the [Stacks Blockchain on DigitalOcean](https://marketplace.digitalocean.com/apps/stacks-blockchain). Code is hosted on this [Github repository](https://github.com/stacks-network/stacks-blockchain-docker). - -## Steps - -#### Step 1 - -Go to the [Stacks Blockchain page](https://marketplace.digitalocean.com/apps/stacks-blockchain) in DigitalOcean's marketplace. Click on `Create Stacks Blockchain Droplet`. - -#### Step 2 - -Choose a plan (it will only allow you to select a plan that meets the minimum requirements) and your prefered datacenter region. ![](/img/sh_digitalocean-choose-plan.png) - -#### Step 3 - -Enter a root password or enable SSH keys if your prefer. - -![](/img/sh_digitalocean-choose-authentication.png) - -#### Step 4 - -You can leave the rest of the options as they are and click on `Create Droplet` - -#### Step 5 - -You will need to wait a few seconds for the droplet to get created. Once created click on it to see more information. - -![](/img/sh_digitalocean-creating-droplet.png) - -![](/img/sh_digitalocean-created-droplet.png) - -### Step 6 - -Congratulations! You are now running the Stacks Blockchain. You can click on `Console` for a terminal window to open or login using SSH to the public IP you've been assigned to with user `root`. - -![](/img/sh_digitalocean-console-button.png) ![](/img/sh_digitalocean-console.png) - -## Getting started after deploying Stacks Blockchain - -Once droplet is launched, initial startup can take several minutes while BNS data is imported (this is a one time operation). - -To keep track of the progress, you can `ssh root@your_droplet_public_ipv4` to the host and run: `/opt/stacks-blockchain-docker/manage.sh -n mainnet -a logs`. - -Once the stacks blockchain starts to sync with peers, application ports will open and nginx port 80 will now start proxying requests. - -Use `http://your_droplet_public_ipv4` to access the data directly, with output being similar to: - -```json -{ - "server_version": "stacks-blockchain-api v3.0.3 (master:cd0c8aef)", - "status": "ready", - "chain_tip": { - "block_height": 16220, - "block_hash": "0x3123fba9c0de6b569573494cf83c1d5d198a66bfd5f48ef97949b6bf11ba13be", - "index_block_hash": "0xeec960fbbd6186b4ccac85ce12adba72be497d881f81e077305c90955b51a6ae" - } -} -``` - -All services are managed by a [systemd unit file](https://github.com/stacksfoundation/stacks-machine-images/blob/master/files/etc/systemd/system/stacks.service) that is set to start on boot. - -Manual control is also possible via the [manage.sh script](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/manage.sh) at `/opt/stacks-blockchain-docker/manage.sh` on the host. - -Full details on how to use the manage.sh script is [available here](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/README.md#quickstart). - -## API Creation - -In addition to creating a Droplet from the Stacks Blockchain 1-Click App via the control panel, you can also use the [DigitalOcean API](https://digitalocean.com/docs/api). - -As an example, to create a 4GB Stacks Blockchain Droplet in the SFO2 region, you can use the following curl command. You’ll need to either save your [API access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/) to an environment variable or substitute it into the command below. - -```bash -curl -X POST -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer '$TOKEN'' -d \ - '{"name":"choose_a_name","region":"sfo2","size":"s-2vcpu-4gb","image":"stacksfoundation-stacksblockchain"}' \ - "https://api.digitalocean.com/v2/droplets" -``` diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md b/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md deleted file mode 100644 index b6cbb9754a..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Nodes and Miners -description: Nodes and Miners -sidebar_position: 7 ---- - -Here are all the steps to run nodes and miners, both on mainnet and testnet. - -## What's a Stacks node? - -## What's a Stacks miner? diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md b/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md deleted file mode 100644 index 40397a51e0..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Miner costs and fees -description: Miner Cost and Fee Estimation -sidebar_position: 8 ---- - -## Configuring Cost and Fee Estimation - -Fee and cost estimators can be configured via the config section `[fee_estimation]`: - -``` -[fee_estimation] -cost_estimator = naive_pessimistic -fee_estimator = fuzzed_weighted_median_fee_rate -fee_rate_fuzzer_fraction = 0.1 -fee_rate_window_size = 5 -cost_metric = proportion_dot_product -log_error = true -enabled = true -``` - -Fee and cost estimators observe transactions on the network and use the observed costs of those transactions to build estimates for viable fee rates and expected execution costs for transactions. Estimators and metrics can be selected using the configuration fields above, though the default values are the only options currently. `log_error` controls whether or not the INFO logger will display information about the cost estimator accuracy as new costs are observed. Setting `enabled = false` turns off the cost estimators. Cost estimators are **not** consensus-critical components, but rather can be used by miners to rank transactions in the mempool or client to determine appropriate fee rates for transactions before broadcasting them. - -The `fuzzed_weighted_median_fee_rate` uses a median estimate from a window of the fees paid in the last `fee_rate_window_size` blocks. Estimates are then randomly "fuzzed" using uniform random fuzz of size up to `fee_rate_fuzzer_fraction` of the base estimate. diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md b/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md deleted file mode 100644 index 468a01df66..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md +++ /dev/null @@ -1,343 +0,0 @@ ---- -title: Mine mainnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 mainnet -sidebar_position: 5 -tags: - - tutorial ---- - -## Introduction - -Make sure you've followed the [run a node](run-a-node) procedure. Once completed it's only a few more steps to run a proof-of-burn miner on the mainnet. - -If you're interested in mining on the testnet, you can find instructions on how to do that [here](miner-testnet): - -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining): - -## Running bitcoind locally - -To participate as a miner on mainnet, you must have access to a mainnet bitcoin node. One way to accomplish this is to run bitcoind locally. [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements) - -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. - -Next, start bitcoind with the following configuration: - -```toml -server=1 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=1 -banscore=1 -bind=0.0.0.0:8333 -rpcbind=0.0.0.0:8332 -rpcport=8332 -``` - -Finally, start bitcoind as follows: - -```bash -bitcoind -conf=path/to/bitcoin.conf -``` - -It may take a few days for the node to synchronize with the Bitcoin mainnet. - -## Running a miner - -First, a keychain needs to be generated. With this keychain, we'll purchase some BTC from a crytpocurrency exchange, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. We'll use the `make_keychain` command. - -```bash -npx @stacks/cli make_keychain 2>/dev/null | json_pp > keychain.txt -``` - -After this runs, you should see some JSON in the new `keychain.txt` file that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -**Don't lose this information** - we'll need to use the `privateKey` field later on. - -The above BTC address will then need to be imported into the BTC network. - -```bash -bitcoin-cli -rpcport=8332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - - - -Once imported, we need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - - - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/mainnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `make_keychain` command. Replace the `seed` field with your private key. Save and close this configuration file. - -To run your miner, run this in the command line: - -```bash -stacks-node start --config=./testnet/stacks-node/conf/mainnet-miner-conf.toml -``` - -Your node should start. It will take some time to sync, and then your miner will be running. - -### Creating an optimized binary - -The steps above are great for trying to run a node temporarily. If you want to host a node on a server somewhere, you might want to generate an optimized binary. To do so, use the same configuration as above, but run: - -```bash -cd testnet/stacks-node -cargo build --release --bin stacks-node -``` - -The above code will compile an optimized binary. To use it, run: - -```bash -cd ../.. -./target/release/stacks-node start --config=./mainnet-miner-conf.toml -``` - -To read more about the technical details of mining on the Stacks 2.0 network, have a look at [the mining guide](../understand-stacks/mining). - -### Enable debug logging - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -STACKS_LOG_DEBUG=1 stacks-node mainnet -``` - -## Running a miner in Windows - -### Prerequisites - -Make sure are [running a node](run-a-node) and [running bitcoind locally](#running-bitcoind-locally) before starting this tutorial. - -### Generate keychain and get mainnet tokens in Windows - -To setup the miner, first we need to generate a keychain. With this keychain, we'll purchase some BTC from a crytpocurrency exchange, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. We'll use the `stx make-keychain` command. - -Generate a keychain: - -```bash -npm install --global @stacks/cli -stx make_keychain > cli_keychain.json -type cli_keychain.json -``` - -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -The above BTC address will then need to be imported into the BTC network. - -```bash -bitcoin-cli -rpcport=8332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - -Once imported, we need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Update configuration file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/mainnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Run the miner - -To start your miner, run this in the command line: - -```bash -stacks-node start --config=testnet/stacks-node/conf/mainnet-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](/img/windows-defender.png) - -Your node should start. It will take some time to sync, and then your miner will be running. - -### Enable debug logging in Windows - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=mainnet-miner-conf.toml -``` - -## Optional: Running with Docker - -Alternatively, you can run the mainnet node with Docker. - -:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: - -### Generate keychain and get tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null -``` - -We need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Update configuration file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/mainnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Start the miner - -:::info The ENV VARS `RUST_BACKTRACE` and `STACKS_LOG_DEBUG` are optional. If removed, debug logs will be disabled ::: - -```bash -docker run -d \ - --name stacks_miner \ - --rm \ - --network host \ - -e RUST_BACKTRACE="full" \ - -e STACKS_LOG_DEBUG="1" \ - -v "$(pwd)/testnet/stacks-node/conf/mainnet-miner-conf.toml:/src/stacks-node/mainnet-miner-conf.toml" \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain:latest \ -/bin/stacks-node start --config /src/stacks-node/mainnet-miner-conf.toml -``` - -You can review the node logs with this command: - -```bash -docker logs -f stacks_miner -``` - -## Optional: Running in Kubernetes with Helm - -In addition, you're also able to run a mainnet node in a Kubernetes cluster using the [stacks-blockchain Helm chart](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). - -Ensure you have the following prerequisites installed on your machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [minikube](https://minikube.sigs.k8s.io/docs/start/) (Only needed if standing up a local Kubernetes cluster) -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [helm](https://helm.sh/docs/intro/install/) - -### Generate keychain and get some tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null -``` - -We need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Install the chart and run the miner - -To install the chart with the release name `my-release` and run the node as a miner: - -```bash -minikube start # Only run this if standing up a local Kubernetes cluster -helm repo add blockstack https://charts.blockstack.xyz -helm install my-release blockstack/stacks-blockchain \ - --set config.node.miner=true \ - --set config.node.seed="replace-with-your-privateKey-from-generate-keychain-step" \ - --set config.burnchain.mode="mainnet" -``` - -You can review the node logs with this command: - -```bash -kubectl logs -l app.kubernetes.io/name=stacks-blockchain -``` - -For more information on the Helm chart and configuration options, please refer to the [chart's homepage](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md b/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md deleted file mode 100644 index b572df3ba2..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md +++ /dev/null @@ -1,336 +0,0 @@ ---- -title: Mine testnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 testnet -sidebar_position: 4 -tags: - - tutorial ---- - -## Introduction - -Make sure you've followed the [Run a node](run-a-node) procedure. Once completed it's only a few more steps to run a proof-of-burn miner on the testnet. - -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining). - -## Running bitcoind locally - -To participate as a miner on Testnet, you must have access to a testnet bitcoin node. One way to accomplish this is to run bitcoind locally. [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements) - -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. - -Next, start bitcoind with the following configuration: - -```toml -server=1 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password -testnet=1 -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=1 -banscore=1 - -[test] -bind=0.0.0.0:18333 -rpcbind=0.0.0.0:18332 -rpcport=18332 -``` - -Finally, start bitcoind as follows: - -```bash -bitcoind -conf=path/to/bitcoin.conf -``` - -It may take a few hours for the node to synchronize with the Bitcoin testnet. - -## Running a miner - -First, a keychain needs to be generated. With this keychain, we'll get some testnet BTC from a faucet, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. We'll use the `make_keychain` command, and pass `-t` to indicate that we want a testnet keychain. - -```bash -npx @stacks/cli make_keychain -t 2>/dev/null | json_pp > keychain.txt -``` - -After this runs, you should see some JSON in the new `keychain.txt` file that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -**Don't lose this information** - we'll need to use the `privateKey` field later on. - -The above BTC address will then need to be imported into the BTC testnet network. - -```bash -bitcoin-cli -rpcport=18332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - -Once imported, we need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). You'll be sent `0.01` testnet BTC to that address. - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/testnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/testnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `make_keychain` command. Replace the `seed` field with your private key. Save and close this configuration file. - -To run your miner, run this in the command line: - -```bash -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. - -### Creating an optimized binary - -The steps above are great for trying to run a node temporarily. If you want to host a node on a server somewhere, you might want to generate an optimized binary. To do so, use the same configuration as above, but run: - -```bash -cd testnet/stacks-node -cargo build --release --bin stacks-node -``` - -The above code will compile an optimized binary. To use it, run: - -```bash -cd ../.. -./target/release/stacks-node start --config=./testnet/conf/testnet-follower-conf.toml -``` - -To read more about the technical details of mining on the Stacks 2.0 network, have a look at [the minig guide](../understand-stacks/mining): - -### Enable debug logging - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -STACKS_LOG_DEBUG=1 stacks-node testnet -``` - -## Running a miner in Windows - -### Prerequisites - -Make sure are [running a testnet node](run-a-node) before starting this tutorial. - -### Generate keychain and get testnet tokens in Windows - -To setup the miner, first, we need to generate a keychain. With this keychain, we'll get some testnet BTC from a faucet, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. We'll use the `stx make-keychain` command, and pass `-t` to indicate that we want a testnet keychain. - -Generate a keychain: - -```bash -npm install --global @stacks/cli -stx make_keychain -t > cli_keychain.json -type cli_keychain.json -``` - -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -Request BTC from faucet: - -We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). You'll be sent 0.01 testnet BTC to that address. - -### Update configuration file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/testnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/testnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Run the miner - -To start your miner, run this in the command line: - -```bash -stacks-node start --config=testnet/stacks-node/conf/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](/img/windows-defender.png) - - - -Your node should start. It will take some time to sync, and then your miner will be running. - -### Enable debug logging in Windows - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=testnet-miner-conf.toml -``` - -## Optional: Running with Docker - -Alternatively, you can run the testnet node with Docker. - -:::warning Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: - -### Generate keychain and get testnet tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` - -We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). You'll be sent 0.01 testnet BTC to that address. - -### Update config file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/testnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/testnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Start the miner - -:::info The ENV VARS `RUST_BACKTRACE` and `STACKS_LOG_DEBUG` are optional. If removed, debug logs will be disabled ::: - -```bash -docker run -d \ - --name stacks_miner \ - --rm \ - --network host \ - -e RUST_BACKTRACE="full" \ - -e STACKS_LOG_DEBUG="1" \ - -v "$(pwd))/testnet/stacks-node/conf/testnet-miner-conf.toml:/src/stacks-node/testnet-miner-conf.toml" \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain:latest \ -/bin/stacks-node start --config /src/stacks-node/testnet-miner-conf.toml -``` - -You can review the node logs with this command: - -```bash -docker logs -f stacks_miner -``` - -## Optional: Running in Kubernetes with Helm - -In addition, you're also able to run a testnet node in a Kubernetes cluster using the [stacks-blockchain Helm chart](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). - -Ensure you have the following prerequisites installed on your machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [minikube](https://minikube.sigs.k8s.io/docs/start/) (Only needed if standing up a local Kubernetes cluster) -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [helm](https://helm.sh/docs/intro/install/) - -### Generate keychain and get some testnet tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` - -We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). You'll be sent 0.01 testnet BTC to that address. - -### Install the chart and run the miner - -To install the chart with the release name `my-release` and run the node as a miner: - -```bash -minikube start # Only run this if standing up a local Kubernetes cluster -helm repo add blockstack https://charts.blockstack.xyz -helm install my-release blockstack/stacks-blockchain \ - --set config.node.miner=true \ - --set config.node.seed="replace-with-your-privateKey-from-generate-keychain-step" -``` - -You can review the node logs with this command: - -```bash -kubectl logs -l app.kubernetes.io/name=stacks-blockchain -``` - -For more information on the Helm chart and configuration options, please refer to the [chart's homepage](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md b/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md deleted file mode 100644 index 94d938c5ca..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md +++ /dev/null @@ -1,351 +0,0 @@ ---- -title: Run a node -description: Set up and run a Stacks node -sidebar_position: 1 -tags: - - tutorial ---- - -## Stacks Blockchain with Docker - -Run your own Stacks Blockchain node easily with just few commands. - -This tutorial describes a simple and effective [quickstart](#quickstart) to run a Stacks node using public scripts hosted in [Stacks Blockchain repository](https://github.com/stacks-network/stacks-blockchain-docker). Valid for mainnet, testnet and mocknet. - -## **Quickstart** - -1. **Clone the stacks-blockchain-docker repository locally** - -```bash -git clone https://github.com/stacks-network/stacks-blockchain-docker && cd stacks-blockchain-docker -``` - -2. **Optionally, create/copy `.env` file**. If file `.env` doesn't exist when launched it will be created from `sample.env` automatically. - -```bash -cp sample.env .env -``` - -_You may also use a symlink as an alternative to copying: `ln -s sample.env .env`_ - -3. **Optionally, ensure all images are up to date** - -```bash -./manage.sh -n -a pull -``` - -4. **Start the Services** - -```bash -./manage.sh -n -a start -``` - -- With optional proxy: - -```bash -./manage.sh -n -a start -f proxy -``` - -- With optional bitcoin node: - -```bash -./manage.sh -n -a start -f bitcoin -``` - -5. **Stop the Services** - -```bash -./manage.sh -n -a stop -``` - -6. **Retrieve Service Logs** - -```bash -./manage.sh -n -a logs -``` - -- Export docker log files to `./exported-logs`: - -This will create one log file for every running service, for example: postgres.log, stacks-blockain.log, stacks-blockchain-api.log and bitcoin-core.log. -Notice that each time you run this command the log files will be overwritten. - -```bash -./manage.sh -n -a logs export -``` - -7. **Restart all services** - -```bash -./manage.sh -n -a restart -``` - -- With optional proxy: - -```bash -./manage.sh -n -a restart -f proxy -``` - -8. **Delete** all data in `./persistent-data/` and/or data of the Bitcoin blockchain. - - This data is owned by root, so you will need to run it with sudo privileges so it can delete the data. - -```bash -$ sudo ./manage.sh -n -a reset - -Please confirm what persistent data you wish to delete: - -0. Cancel -1. Delete Persistent data for Stacks testnet only and leave Bitcoin blockchain data unaffected. -2. Delete Persistent data for Stacks testnet and Bitcoin blockchain data in ./persistent-data/blockchain-bitcoin -3. Delete Persistent data for Bitcoin blockchain data in ./persistent-data/blockchain-bitcoin only. -Please note that BNS data will never get deleted. - -Type 0, 1, 2 or 3: 2 - -Ok. Delete Stacks and Bitcoin data. -[ Success ] Persistent data deleted for Bitcoin blockchain. -[ Success ] Persistent data deleted for Stacks testnet. - -``` - -9. **Download BNS data to** `./persistent-data/bns-data` - -```bash -./manage.sh bns -``` - -10. **Export stacks-blockchain-api events** (_Not applicable for mocknet_) - -```bash -./manage.sh -n -a export -# check logs for completion -./manage.sh -n -a restart -``` - -11. **Replay stacks-blockchain-api events** (_Not applicable for mocknet_) - -```bash -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart -``` - -## **Running also a bitcoin node (Optional)** - -Stacks needs to use a Bitcoin node, and by default when you run a Stacks node you will be using a public Bitcoin node, which is configured in the `.env` file. Default values is `BITCOIN_NODE=bitcoin.mainnet.stacks.org`. - -However, you can optionaly run both nodes together and configured in a way that you Stacks node will use your own Bitcoin node instead of a public one. - -If you run the script with a bitcoin node it will download and build it directly from source for increased security. This process which only needs to happen once can take up to 20-30 minutes depending on the speed of your system. Also, once the bitcoin node is up and running it will need an additional time for sync for the first time (can be hours for testnet and days for mainnet). - -### Why run Stacks node with your own Bitcoin node? - -Because running your own Bitcoin node will give you higher security and improved perfomance. - -* **Improved perfomance**: The Bitcoin node will serve you blocks faster, as well as UTXOs for your miner (if you run one). -* **Higher security**: The Bitcoin node will also have validated all bitcoin transactions the Stacks node consumes. If you don't run your own Bitcoin node, you're relying on the SPV headers to vouch for the validity of Bitcoin blocks. - -The disadvantage of running your own Bitcoin node is that you need the extra space to store the Bitcoin blockchain (about 500GB) and the initial time it will take to download this data the first time. - -### Example - -You can run easily run your Stacks node with your own Bitcoin node by adding the flag `bitcoin`. This is available only for testnet and mainnet. - -Example: `./manage.sh -n mainnet -a start -f bitcoin` or `./manage.sh -n testnet -a start -f bitcoin` - -### Bitcoin node configuration - -In the `.env` file there is the variable `BITCOIN_BLOCKCHAIN_FOLDER`. As the bitcoin blockchain can be large (over 500GB) you optionally change this variable to any location of your choosing. If you have previously used the [bitcoin core application](https://bitcoin.org/en/bitcoin-core/) and already have the bitcoin blockchain synced, you can use the same data folder and avoid redownloading the entire bitcoin blockchain. - -## **Accessing the services** - -:::tip For networks other than `mocknet`, downloading the initial headers can take several minutes. Until the headers are downloaded, the `/v2/info` endpoints won't return any data. - -Use the command `./manage.sh -n -a logs` to check the sync progress. ::: - -**stacks-blockchain**: - -- Ports `20443-20444` are exposed to `localhost` - -```bash -curl -sL localhost:20443/v2/info | jq -``` - -**stacks-blockchain-api**: - -- Port `3999` are exposed to `localhost` - -```bash -curl -sL localhost:3999/v2/info | jq -``` - -**proxy**: - -- Port `80` is exposed to `localhost` - -```bash -curl -sL localhost/v2/info | jq -curl -sL localhost/ | jq -``` - ---- - -## Upgrades - -⚠️ For upgrades to running instances of this repo, you'll need to [run the event-replay](https://github.com/hirosystems/stacks-blockchain-api#event-replay): - -```bash -./manage.sh -n -a stop -./manage.sh -n -a export -./manage.sh -n -a import -./manage.sh -n -a restart -``` - ---- - -## **Workarounds to potential issues** - -_**Port(s) already in use**_: - -- 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. `3999` and edit your `.env` file to use the new port. - -```bash -netstat -anl | grep 3999 -``` - -``` -tcp46 0 0 *.3999 *.* LISTEN -``` - -_**Containers not starting (hanging on start)**_: - -- Occasionally, docker can get **stuck** and not allow new containers to start. If this happens, simply restart your docker daemon and try again. - -_**Database Issues**_: - -- For any of the various Postgres/sync issues, it may be easier to simply remove the persistent data dir. Note that doing so will result in a longer startup time as the data is repopulated. - -```bash -./manage.sh -n -a stop -./manage.sh -n -a reset -./manage.sh -n -a start -``` - -_**API Missing Parent Block Error**_: - -- If the Stacks blockchain is no longer syncing blocks, and the API reports an error similar to this:\ - `Error processing core node block message DB does not contain a parent block at height 1970 with index_hash 0x3367f1abe0ee35b10e77fbcaa00d3ca452355478068a0662ec492bb30ee0f13e"`,\ - The API (and by extension the DB) is out of sync with the blockchain. \ - The only known method to recover is to resync from genesis (**event-replay _may_ work, but in all likelihood will restore data to the same broken state**). - -- To attempt the event-replay - -```bash -./manage.sh -n -a stop -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart -``` - -- To wipe data and re-sync from genesis - -```bash -./manage.sh -n -a stop -./manage.sh -n -a reset -./manage.sh -n -a restart -``` - - -## **Requirements:** - -- [Docker](https://docs.docker.com/get-docker/) >= `17.09` -- [docker-compose](https://github.com/docker/compose/releases/) >= `1.27.4` -- [git](https://git-scm.com/downloads) -- [jq binary](https://stedolan.github.io/jq/download/) -- [sed](https://www.gnu.org/software/sed/) -- Machine with (at a minimum): - - 4GB memory - - 1 Vcpu - - 50GB storage (600GB if you optionally also run the bitcoin mainnet node) - -:::caution MacOS with an M1 processor is NOT recommended - -The way Docker for Mac on an Arm chip is designed makes the I/O incredibly slow, and blockchains are **_very_** heavy on I/O. This only seems to affect MacOS, other Arm based systems like Raspberry Pi's seem to work fine. - -::: - - -### Install/Update docker-compose - -:::note `docker-compose` executable is required, even though recent versions of Docker contain `compose` natively ::: - -- [Install Docker-compose](https://docs.docker.com/compose/install/) -- [Docker Desktop for Mac](https://docs.docker.com/docker-for-mac/install/) -- [Docker Desktop for Windows](https://docs.docker.com/docker-for-windows/install/) -- [Docker Engine for Linux](https://docs.docker.com/engine/install/#server) - -First, check if you have `docker-compose` installed locally. - -To do that, run this command in your terminal : - -```bash -docker-compose --version -``` - -Output should look something very similar to this : - -``` -docker-compose version 1.27.4, build 40524192 -``` - -If the command is not found, or the version is < `1.27.4`, run the following to install the latest to `/usr/local/bin/docker-compose`: - -```bash -#You will need to have jq installed, or this snippet won't run. -VERSION=$(curl --silent https://api.github.com/repos/docker/compose/releases/latest | jq .name -r) -DESTINATION=/usr/local/bin/docker-compose -sudo curl -L https://github.com/docker/compose/releases/download/${VERSION}/docker-compose-$(uname -s)-$(uname -m) -o $DESTINATION -sudo chmod 755 $DESTINATION -``` - -### Security note on docker - -The Docker daemon always runs as the root user so by default you will need root privileges to interact with it. - -The script `manage.sh` uses docker, so to avoid the requirement of needing to run the script with root privileges it is prefered to be able to *manage Docker as a non-root user*, following [these simple tests](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user). - -This will avoid the need of running the script with root privileges for all operations except the removal of data. - -### Configuration files you can edit - -The following files can be modified to personalize your node configuration, but generally most of them should be left as-is. All these files will be created from the sample copy if they don't exist at runtime (for example `.env` is created from `sample.env`). However these files will never be modified by the application once created and will never be pushed back to github, so your changes will be safe. - -* `.env` -* `./conf/mainnet/Config.toml` -* `./conf/mainnet/bitcoin.conf` -* `./conf/testnet/Config.toml` -* `./conf/testnet/bitcoin.conf` - -By default: - -- BNS data is **not** enabled/imported - - To enable, uncomment `# BNS_IMPORT_DIR=/bns-data` in `./env` - - Download BNS data: `./manage.sh bns` -- Fungible token metadata is **not** enabled - - To enable, uncomment `# STACKS_API_ENABLE_FT_METADATA=1` in `./env` -- Non-Fungible token metadata is **not** enabled - - To enable, uncomment `# STACKS_API_ENABLE_NFT_METADATA=1` in `./env` -- Verbose logging is **not** enabled - - To enable, uncomment `# VERBOSE=true` in `./env` -- Bitcoin blockchain folder is configured in `BITCOIN_BLOCKCHAIN_FOLDER` in `./env` - -### Local Data Dirs - -Directories will be created on first start that will store persistent data under `./persistent-data/` - -`` can be 1 of: - -- mainnet -- testnet -- mocknet diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md b/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md deleted file mode 100644 index 09db354d0d..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md +++ /dev/null @@ -1,188 +0,0 @@ ---- -title: Running a mainnet node -description: Set up and run a mainnet node with Docker -sidebar_position: 3 -tags: - - tutorial ---- - -## Introduction - -This procedure demonstrates how to run a local mainnet node using Docker images. - -:::caution -This procedure focuses on Unix-like operating systems (Linux and MacOS). This procedure has not been tested on Windows. -::: - -## Prerequisites - -Running a node has no specialized hardware requirements. Users have been successful in running nodes on Raspberry Pi boards and other system-on-chip architectures. In order to complete this procedure, you must have the following software installed on the node host machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [curl](https://curl.se/download.html) -- [jq](https://stedolan.github.io/jq/download/) - -### Firewall configuration - -In order for the API node services to work correctly, you must configure any network firewall rules to allow traffic on the ports discussed in this section. The details of network and firewall configuration are highly specific to your machine and network, so a detailed example isn't provided. - -The following ports must open on the host machine: - -Ingress: - -- stacks-blockchain (open to `0.0.0.0/0`): - - `20443 TCP` - - `20444 TCP` - -Egress: - -- `8332` -- `8333` -- `20443-20444` - -These egress ports are for syncing stacks-blockchain and Bitcoin headers. If they're not open, the sync will fail. - -## Step 1: initial setup - -In order to run the mainnet node, you must download the Docker images and create a directory structure to hold the persistent data from the services. Download and configure the Docker images with the following commands: - -```sh -docker pull blockstack/stacks-blockchain -``` - -Create a directory structure for the service data with the following command: - -```sh -mkdir -p ./stacks-node/{persistent-data/stacks-blockchain/mainnet,config/mainnet} && cd stacks-node -``` - -## Step 2: running Stacks blockchain - -First, create the `./config/mainnet/Config.toml` file and add the following content to the file using a text editor: - -```toml -[node] -working_dir = "/root/stacks-node/data" -rpc_bind = "0.0.0.0:20443" -p2p_bind = "0.0.0.0:20444" -bootstrap_node = "02da7a464ac770ae8337a343670778b93410f2f3fef6bea98dd1c3e9224459d36b@seed-0.mainnet.stacks.co:20444,02afeae522aab5f8c99a00ddf75fbcb4a641e052dd48836408d9cf437344b63516@seed-1.mainnet.stacks.co:20444,03652212ea76be0ed4cd83a25c06e57819993029a7b9999f7d63c36340b34a4e62@seed-2.mainnet.stacks.co:20444" -wait_time_for_microblocks = 10000 - -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "bitcoin.blockstack.com" -username = "blockstack" -password = "blockstacksystem" -rpc_port = 8332 -peer_port = 8333 - -[connection_options] -read_only_call_limit_write_length = 0 -read_only_call_limit_read_length = 100000 -read_only_call_limit_write_count = 0 -read_only_call_limit_read_count = 30 -read_only_call_limit_runtime = 1000000000 -``` - -Start the `stacks-blockchain` container with the following command: - -```sh -docker run -d --rm \ - --name stacks-blockchain \ - -v $(pwd)/persistent-data/stacks-blockchain/mainnet:/root/stacks-node/data \ - -v $(pwd)/config/mainnet:/src/stacks-node \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain \ -/bin/stacks-node start --config /src/stacks-node/Config.toml -``` - -You can verify the running `stacks-blockchain` container with the command: - -```sh -docker ps --filter name=stacks-blockchain -``` - -## Step 3: verifying the services - -:::note -The initial burnchain header sync can take several minutes, until this is done the following commands will not work -::: - -To verify the `stacks-blockchain` burnchain header sync progress: - -```sh -docker logs stacks-blockchain -``` - -The output should be similar to the following: - -``` -INFO [1626290705.886954] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.2% (8000 out of 691034) -INFO [1626290748.103291] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.4% (10000 out of 691034) -INFO [1626290776.956535] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.7% (12000 out of 691034) -``` - -To verify the `stacks-blockchain` tip height is progressing use the following command: - -```sh -curl -sL localhost:20443/v2/info | jq -``` - -If the instance is running you should recieve terminal output similar to the following: - -```json -{ - "peer_version": 402653184, - "pox_consensus": "89d752034e73ed10d3b97e6bcf3cff53367b4166", - "burn_block_height": 666143, - "stable_pox_consensus": "707f26d9d0d1b4c62881a093c99f9232bc74e744", - "stable_burn_block_height": 666136, - "server_version": "stacks-node 2.0.11.1.0-rc1 (master:67dccdf, release build, linux [x86_64])", - "network_id": 1, - "parent_network_id": 3652501241, - "stacks_tip_height": 61, - "stacks_tip": "e08b2fe3dce36fd6d015c2a839c8eb0885cbe29119c1e2a581f75bc5814bce6f", - "stacks_tip_consensus_hash": "ad9f4cb6155a5b4f5dcb719d0f6bee043038bc63", - "genesis_chainstate_hash": "74237aa39aa50a83de11a4f53e9d3bb7d43461d1de9873f402e5453ae60bc59b", - "unanchored_tip": "74d172df8f8934b468c5b0af2efdefe938e9848772d69bcaeffcfe1d6c6ef041", - "unanchored_seq": 0, - "exit_at_block_height": null -} -``` - -## Stopping the mainnet node - -Use the following commands to stop the local mainnet node: - -```sh -docker stop stacks-blockchain -``` - -## Optional. Run stacks node with own bitcoin node - -It's encouraged to use your own bitcoin node when possible. - -To do this simply update the `stacks-node/config/mainnet/Config.toml` file with the details of your bitcoin node. For example: - -``` -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "localhost" -username = "rpc username" -password = "rpc password" -rpc_port = 8332 -peer_port = 8333 -``` - -The rpc configuration of your bitcoin node is out of the scope of this document, but you can find more information on how to set it up [here](https://developer.bitcoin.org/examples/intro.html). - -## Additional reading - - - -- [Running a Stacks API node](https://docs.hiro.so/get-started/running-api-node) -- [Running a Stacks testnet node](running-testnet-node) - diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md b/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md deleted file mode 100644 index da01ce2ea1..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: Running a testnet node -description: Set up and run a testnet node with Docker -sidebar_position: 2 -tags: - - tutorial ---- - -## Introduction - -This procedure demonstrates how to run a local testnet node using Docker images. - -:::caution -This procedure focuses on Unix-like operating systems (Linux and MacOS). This procedure has not been tested on Windows. -::: - -## Prerequisites - -Running a node has no specialized hardware requirements. Users have been successful in running nodes on Raspberry Pi boards and other system-on-chip architectures. In order to complete this procedure, you must have the following software installed on the node host machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [curl](https://curl.se/download.html) -- [jq](https://stedolan.github.io/jq/download/) - -### Firewall configuration - -In order for the API node services to work correctly, you must configure any network firewall rules to allow traffic on the ports discussed in this section. The details of network and firewall configuration are highly specific to your machine and network, so a detailed example isn't provided. - -The following ports must open on the host machine: - -Ingress: - -- stacks-blockchain (open to `0.0.0.0/0`): - - `20443 TCP` - - `20444 TCP` - -Egress: - -- `18332` -- `18333` -- `20443-20444` - -These egress ports are for syncing stacks-blockchain and Bitcoin headers. If they're not open, the sync will fail. - -## Step 1: initial setup - -In order to run the testnet node, you must download the Docker images and create a directory structure to hold the persistent data from the services. Download and configure the Docker images with the following commands: - -```sh -docker pull blockstack/stacks-blockchain -``` - -Create a directory structure for the service data with the following command: - -```sh -mkdir -p ./stacks-node/persistent-data/stacks-blockchain/testnet && cd stacks-node -``` - -## Step 2: running Stacks blockchain - -Start the stacks-blockchain container with the following command: - -```sh -docker run -d --rm \ - --name stacks-blockchain \ - -v $(pwd)/persistent-data/stacks-blockchain/testnet:/root/stacks-node/data \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain \ -/bin/stacks-node testnet -``` - -You can verify the running stacks-blockchain container with the command: - -```sh -docker ps --filter name=stacks-blockchain -``` - -## Step 3: verifying the services - -:::info -The initial burnchain header sync can take several minutes, until this is done the following commands will not work -::: - -To verify the stacks-blockchain burnchain header sync progress: - -```sh -docker logs stacks-blockchain -``` - -The output should be similar to the following: - -``` -INFO [1626290705.886954] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.2% (8000 out of 2034380) -INFO [1626290748.103291] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.4% (10000 out of 2034380) -INFO [1626290776.956535] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.7% (12000 out of 2034380) -``` - -To verify the stacks-blockchain tip height is progressing use the following command: - -```sh -curl -sL localhost:20443/v2/info | jq -``` - -If the instance is running you should recieve terminal output similar to the following: - -```json -{ - "peer_version": 4207599105, - "pox_consensus": "12f7fa85e5099755a00b7eaecded1aa27af61748", - "burn_block_height": 2034380, - "stable_pox_consensus": "5cc4e0403ff6a1a4bd17dae9600c7c13d0b10bdf", - "stable_burn_block_height": 2034373, - "server_version": "stacks-node 2.0.11.2.0-rc1 (develop:7b6d3ee+, release build, linux [x86_64])", - "network_id": 2147483648, - "parent_network_id": 118034699, - "stacks_tip_height": 509, - "stacks_tip": "e0ee952e9891709d196080ca638ad07e6146d4c362e6afe4bb46f42d5fe584e8", - "stacks_tip_consensus_hash": "12f7fa85e5099755a00b7eaecded1aa27af61748", - "genesis_chainstate_hash": "74237aa39aa50a83de11a4f53e9d3bb7d43461d1de9873f402e5453ae60bc59b", - "unanchored_tip": "32bc86590f11504f17904ee7f5cb05bcf71a68a35f0bb3bc2d31aca726090842", - "unanchored_seq": 0, - "exit_at_block_height": null -} -``` - -## Stopping the testnet node - -Use the following commands to stop the local testnet node: - -```sh -docker stop stacks-blockchain -``` - -## Additional reading - - - -- [Running a Stacks API node](https://docs.hiro.so/get-started/running-api-node) -- [Running a Stacks mainnet node](running-mainnet-node) - diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md b/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md deleted file mode 100644 index 89af343dc6..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md +++ /dev/null @@ -1,506 +0,0 @@ ---- -title: Stacks Node Configuration -description: Configuration parameters and options for the stacks-node binary -sidebar_position: 6 ---- - -## Usage - -```bash -stacks-node sub-command [--subcommand-option ] -``` - -## Subcommands - -:::caution The `stacks-node` binary may have deprecated commands that are not documented on this page. Deprecated commands may be accessible until they are fully removed from the sources. ::: - -### mocknet - -Start a node based on a fast local setup emulating a burnchain. Ideal for smart contract development. - -Example: - -```bash -stacks-node mocknet -``` - -### krypton - -Start a node that will join and stream blocks from the public krypton regtest, powered by Blockstack via [Proof of Transfer](../understand-stacks#consensus-mechanism). - -Example: - -```bash -stacks-node krypton -``` - -### testnet - -Start a node that will join and stream blocks from the public testnet. - -Example: - -```bash -stacks-node testnet -``` - -### mainnet - -Start a node that joins and streams blocks from the public mainnet. - -Example: - -```bash -stacks-node mainnet -``` - -### start - -Start a node with a config of your own. Can be used for joining a network, starting a new chain, or replacing default values used by the `mocknet` or `testnet` subcommands. - -#### Arguments - -**--config**: relative or absolute path to the TOML config file. Required. - -Example: - -```bash -stacks-node start --config=/path/to/config.toml -``` - -See [Configuration File Options](#configuration-file-options) for more information. - -#### version - -Displays information about the current version and the release cycle. - -Example: - -```bash -stacks-node version -``` - -#### help - -Displays a help message. - -Example: - -```bash -stacks-node help -``` - -## Configuration File Options - -The TOML configuration file has multiple sections under which an option may be placed. - -To see a list of example configurations, [please see this page](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf). - -### Section: node - -Contains various configuration options pertaining to the stacks-node. - -Example: - -```toml -[node] -rpc_bind = "0.0.0.0:20443" -p2p_bind = "0.0.0.0:20444" -# Enter your private key here -seed = "replace-with-your-private-key" -miner = true -``` - -#### working_dir (optional) - -Absolute path to the directory which the stacks-node will use for storing various data. - -Example: - -```toml -working_dir = "/root/stacks-node" -``` - -#### rpc_bind - -Address and port stacks-node should bind to for RPC connections. - -Example: - -```toml -rpc_bind = "0.0.0.0:20443" -``` - -#### p2p_bind - -Address and port stacks-node should bind to for P2P connections. - -Example: - -```toml -p2p_bind = "0.0.0.0:20444" -``` - -#### data_url (optional) - -Address and port from which the stacks-node will be receiving incoming rpc connections. - -Example: - -```toml -data_url = "1.2.3.4:20443" -``` - -#### p2p_address (optional) - -Address and port from which the stacks-node will be receiving incoming p2p connections. - -Example: - -```toml -p2p_address = "1.2.3.4:20444" -``` - -#### bootstrap_node (optional) - -Public key, address, and port stacks-node should use to pull transaction data from when starting. - -Example: - -```toml -bootstrap_node = "047435c194e9b01b3d7f7a2802d6684a3af68d05bbf4ec8f17021980d777691f1d51651f7f1d566532c804da506c117bbf79ad62eea81213ba58f8808b4d9504ad@testnet.blockstack.org:20444" -``` - -#### wait_time_for_microblocks (optional) - -The amount of time (in milliseconds) that a node will wait before trying to mine a block, after catching up to the anchored chain tip. This gives the current leader time to broadcast microblocks that will get included in that mined block. - -Example: - -```toml -wait_time_for_microblocks = 15000 -``` - -#### seed (optional) - -The private key to use for mining. Only needed if `miner` is set to `true`. - -Example: - -```toml -seed = "replace-with-your-private-key" -``` - -#### local_peer_seed (optional) - -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. - -Example: - -```toml -local_peer_seed = "replace-with-your-private-key" -``` - -#### miner (optional) - -Determines whether the stacks-node is running a follower (`false`) or a miner (`true`). Defaults to `false` if omitted. - -Example: - -```toml -miner = true -``` - -#### mine_microblocks (optional) - -Determines whether the stacks-node will mine microblocks. Will only take effect if `miner` is set to `true`. - -Example: - -```toml -mine_microblocks = true -``` - -#### prometheus_bind (optional) - -Address and port stacks-node should open for Prometheus metrics collection. - -Example: - -```toml -prometheus_bind = "0.0.0.0:9153" -``` - -### Section: events_observer (optional) - -Contains options for watching events emitted by a local [stacks-blockchain-api](https://github.com/hirosystems/stacks-blockchain-api) service. - -:::info -This section can be repeated multiple times. -::: - -Example: - -```toml -[[events_observer]] -endpoint = "address-to-my-local.stacks-node-api.com:3700" -retry_count = 255 -events_keys = ["*"] -``` - -#### endpoint - -Address and port to a stacks-node-api to watch for events. - -Example: - -```toml -endpoint = "address-to-my-local.stacks-node-api.com:3700" -``` - -#### retry_count - -Number of times to retry sending events to the endpoint before failing. - -Example: - -```toml -retry_count = 255 -``` - -#### events_keys - -Event keys for which to watch. The emitted node events can be restricted by account, function name and event type. Asterix ("\*") can be used to emit all events. - -Examples: - -```toml -events_keys = ["*"] -``` - -```toml -events_keys = [ - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.store::print", - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.contract.ft-token", - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.contract.nft-token", - "stx" -] -``` - -### Section: connection_options (optional) - -Specifies configuration options for others connecting to the stacks node. - -Example: - -```toml -[connection_options] -public_ip_address = "1.2.3.4:20444" -download_interval = 60 -walk_interval = 30 -``` - -#### public_ip_address - -The advertised public IP of this stacks-node. - -Example: - -```toml -public_ip_address = "1.2.3.4:20444" -``` - -#### download_interval - -Time (in seconds) between attempts to download blocks. - -Example: - -```toml -download_interval = 60 -``` - -#### walk_interval - -Time (in seconds) between attempts to walk the neighborhood. - -Example: - -```toml -walk_interval = 30 -``` - -#### read_only_call_limit_read_length - -Total number of bytes allowed to be read by an individual read-only function call. - -Example: - -```toml -read_only_call_limit_read_length = 100000 -``` - -#### read_only_call_limit_read_count - -Total number of independent read operations permitted for an individual read-only function call. - -Example: - -```toml -read_only_call_limit_read_count = 30 -``` - -#### read_only_call_limit_runtime - -[Runtime cost](https://github.com/stacksgov/sips/blob/2d3fd9bf8da7a04f588d90ff6252173d7609d7bf/sips/sip-006/sip-006-runtime-cost-assessment.md#introduction) limit for an individual read-only function call. - -Example: - -```toml -read_only_call_limit_runtime = 1000000000 -``` - -### Section: burnchain - -This section contains configuration options pertaining to the blockchain the stacks-node binds to on the backend for proof-of-transfer (BTC). - -Example: - -```toml -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "your.bitcoind.node.org" -rpc_port = 8332 -peer_port = 8333 -``` - -#### chain - -The blockchain stacks-node binds to on the backend for proof-of-transfer. Only value supported: `"bitcoin"`. - -Example: - -```toml -chain = "bitcoin" -``` - -#### mode - -The profile or test phase of which to run stacks-node. Valid values are `"mocknet"`, `"helium"`, `"neon"`, `"argon"`, `"krypton"`, `"xenon"`. - -Example: - -```toml -mode = "xenon" -``` - -#### peer_host - -Domain name of the host running the backend Bitcoin blockchain. It's required to either run a personal Bitcoin node locally, or to use a publicly hosted Bitcoin node. - -Example: - -```toml -peer_host = "your.bitcoind.node.org" -``` - -#### rpc_port - -peer_host's port stacks-node will connect to for RPC connections. - -Example: - -```toml -rpc_port = 8332 -``` - -#### peer_port - -peer_host's port stacks-node will connect to for P2P connections. - -Example: - -```toml -peer_port = 8333 -``` - -#### burn_fee_cap (optional) - -Maximum amount (in Satoshis) of "burn commitment" to broadcast for the next block's leader election. - -Example: - -```toml -burn_fee_cap = 30000 -``` - -#### satoshis_per_byte (optional) - -Amount (in Satoshis) per [virtual byte](https://en.bitcoin.it/wiki/Weight_units). This is used to compute the transaction fees. - -Example: - -```toml -satoshis_per_byte = 50 -``` - -So total transaction cost would be `(estimated_tx_size * satoshis_per_byte) + burn_fee_cap`. - -#### commit_anchor_block_within (optional) - -Sets the time period (in milliseconds) for commitments. Only used when `mode` is set to `"helium"`. - -Example: - -```toml -commit_anchor_block_within = 10000 -``` - -### Section: ustx_balance (testnet/regtest only) - -This section contains configuration options pertaining to the genesis block allocation for an address in micro-STX. If a user changes these values, their node may be in conflict with other nodes on the network and find themselves unable to sync with other nodes. - -:::info -This section can repeat multiple times, and thus is in double-brackets. Each section can define only one address. This section is ignored if running a node on mainnet. -::: - -Example: - -```toml -[[ustx_balance]] -address = "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6" -amount = 10000000000000000 - -[[ustx_balance]] -address = "ST11NJTTKGVT6D1HY4NJRVQWMQM7TVAR091EJ8P2Y" -amount = 10000000000000000 - -[[ustx_balance]] -address = "ST1HB1T8WRNBYB0Y3T7WXZS38NKKPTBR3EG9EPJKR" -amount = 10000000000000000 - -[[ustx_balance]] -address = "STRYYQQ9M8KAF4NS7WNZQYY59X93XEKR31JP64CP" -amount = 10000000000000000 -``` - -#### address - -Address which maintains a micro-STX balance. - -Example: - -```toml -address = "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6" -``` - -#### amount - -The balance of micro-STX given to the address at the start of the node. - -Example: - -```toml -amount = 10000000000000000 -``` diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md b/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md deleted file mode 100644 index 094e3f03a1..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Verify Miner -description: Verify node is operating as miner -sidebar_position: 7 ---- - -You can verify that your node is operating as a miner by checking its log output to verify that it was able to find its Bitcoin UTXOs: - -```bash -$ head -n 100 /path/to/your/node/logs | grep -i utxo -INFO [1630127492.031042] [testnet/stacks-node/src/run_loop/neon.rs:146] [main] Miner node: checking UTXOs at address: -INFO [1630127492.062652] [testnet/stacks-node/src/run_loop/neon.rs:164] [main] UTXOs found - will run as a Miner node -``` \ No newline at end of file diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json b/i18n/hi/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json deleted file mode 100644 index f5de305558..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Noteworthy Contracts", - "position": 4, - "link": { - "type": "generated-index", - "description": "Specific deployed Clarity Contracts worth mentioning." - } -} \ No newline at end of file diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md b/i18n/hi/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md deleted file mode 100644 index 99723a9ff2..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md +++ /dev/null @@ -1,362 +0,0 @@ ---- -title: BNS Contract -description: The Blockchain Naming System. ---- - -![](/img/satoshi-btc.png) - -## Introduction - -The Blockchain Naming System (BNS) is implemented as a smart contract using Clarity. - -Below is a list of public and read-only functions as well as error codes that can be returned by those methods: -* [Public functions](#public-functions) -* [Read-only functions](#read-only-functions) -* [Error codes](#error-codes) - -## Public functions - - -### name-import - -#### Input: `(buff 20), (buff 48), principal, (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-import namespace name beneficiary zonefile-hash)` -#### Description: -Imports name to a revealed namespace. Each imported name is given both an owner and some off-chain state. - -### name-preorder - -#### Input: `(buff 20), uint` -#### Output: `(response uint int)` -#### Signature: `(name-preorder hashed-salted-fqn stx-to-burn)` -#### Description: -Preorders a name by telling all BNS nodes the salted hash of the BNS name. It pays the registration fee to the namespace owner's designated address. - -### name-register - -#### Input: `(buff 20), (buff 48), (buff 20), (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-register namespace name salt zonefile-hash)` -#### Description: -Reveals the salt and the name to all BNS nodes, and assigns the name an initial public key hash and zone file hash. - -### name-renewal - -#### Input: `(buff 20), (buff 48), uint, (optional principal), (optional (buff 20))` -#### Output: `(response bool int)` -#### Signature: `(name-renewal namespace name stx-to-burn new-owner zonefile-hash)` -#### Description: -Depending in the namespace rules, a name can expire. For example, names in the .id namespace expire after 2 years. You need to send a name renewal every so often to keep your name. - -You will pay the registration cost of your name to the namespace's designated burn address when you renew it. When a name expires, it enters a \"grace period\". The period is set to 5000 blocks (a month) but can be configured for each namespace. - -It will stop resolving in the grace period, and all of the above operations will cease to be honored by the BNS consensus rules. You may, however, send a NAME_RENEWAL during this grace period to preserve your name. After the grace period, everybody can register that name again. If your name is in a namespace where names do not expire, then you never need to use this transaction. -### name-revoke - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(name-revoke namespace name)` -#### Description: -Makes a name unresolvable. The BNS consensus rules stipulate that once a name is revoked, no one can change its public key hash or its zone file hash. The name's zone file hash is set to null to prevent it from resolving. You should only do this if your private key is compromised, or if you want to render your name unusable for whatever reason. - -### name-transfer - -#### Input: `(buff 20), (buff 48), principal, (optional (buff 20))` -#### Output: `(response bool int)` -#### Signature: `(name-transfer namespace name new-owner zonefile-hash)` -#### Description: -Changes the name's public key hash. You would send a name transfer transaction if you wanted to: -* Change your private key -* Send the name to someone else or -* Update your zone file - -When transferring a name, you have the option to also clear the name's zone file hash (i.e. set it to null). This is useful for when you send the name to someone else, so the recipient's name does not resolve to your zone file. - -### name-update - -#### Input: `(buff 20), (buff 48), (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-update namespace name zonefile-hash)` -#### Description: -Changes the name's zone file hash. You would send a name update transaction if you wanted to change the name's zone file contents. For example, you would do this if you want to deploy your own Gaia hub and want other people to read from it. - -### namespace-preorder - -#### Input: `(buff 20), uint` -#### Output: `(response uint int)` -#### Signature: `(namespace-preorder hashed-salted-namespace stx-to-burn)` -#### Description: -Registers the salted hash of the namespace with BNS nodes, and burns the requisite amount of cryptocurrency. Additionally, this step proves to the BNS nodes that user has honored the BNS consensus rules by including a recent consensus hash in the transaction. Returns pre-order's expiration date (in blocks). - -### namespace-ready - -#### Input: `(buff 20)` -#### Output: `(response bool int)` -#### Signature: `(namespace-ready namespace)` -#### Description: -Launches the namespace and makes it available to the public. Once a namespace is launched, anyone can register a name in it if they pay the appropriate amount of cryptocurrency. - -### namespace-reveal - -#### Input: `(buff 20), (buff 20), uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, principal` -#### Output: `(response bool int)` -#### Signature: `(namespace-reveal namespace namespace-salt p-func-base p-func-coeff p-func-b1 p-func-b2 p-func-b3 p-func-b4 p-func-b5 p-func-b6 p-func-b7 p-func-b8 p-func-b9 p-func-b10 p-func-b11 p-func-b12 p-func-b13 p-func-b14 p-func-b15 p-func-b16 p-func-non-alpha-discount p-func-no-vowel-discount lifetime namespace-import)` -#### Description: -Reveals the salt and the namespace ID (after a namespace preorder). It reveals how long names last in this namespace before they expire or must be renewed, and it sets a price function for the namespace that determines how cheap or expensive names its will be.All of the parameters prefixed by `p` make up the `price function`. These parameters govern the pricing and lifetime of names in the namespace. - -The rules for a namespace are as follows: - -* a name can fall into one of 16 buckets, measured by length. Bucket 16 incorporates all names at least 16 characters long. - -* the pricing structure applies a multiplicative penalty for having numeric characters, or punctuation characters. - -* the price of a name in a bucket is `((coeff) * (base) ^ (bucket exponent)) / ((numeric discount multiplier) * (punctuation discount multiplier))` - -Example: - -* base = 10 -* coeff = 2 -* nonalpha discount: 10 -* no-vowel discount: 10 -* buckets 1, 2: 9 -* buckets 3, 4, 5, 6: 8 -* buckets 7, 8, 9, 10, 11, 12, 13, 14: 7 -* buckets 15, 16+: - - -## Read-only functions - -### can-name-be-registered - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(can-name-be-registered namespace name)` -#### Description: -Returns true if the provided name can be registered. - -### can-namespace-be-registered - -#### Input: `(buff 20)` -#### Output: `(response bool UnknownType)` -#### Signature: `(can-namespace-be-registered namespace)` -#### Description: -Returns true if the provided namespace is available. - -### can-receive-name - -#### Input: `principal` -#### Output: `(response bool int)` -#### Signature: `(can-receive-name owner)` -#### Description: -Returns true if the provided name can be received. That is, if it is not curretly owned, a previous lease is expired, and the name wasn't revoked. - -### get-name-price - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response uint int)` -#### Signature: `(get-name-price namespace name)` -#### Description: -Gets the price for a name. - -### get-namespace-price - -#### Input: `(buff 20)` -#### Output: `(response uint int)` -#### Signature: `(get-namespace-price namespace)` -#### Description: -Gets the price for a namespace. - -### get-namespace-properties - -#### Input: `(buff 20)` -#### Output: `(response (tuple (namespace (buff 20)) (properties (tuple (can-update-price-function bool) (launched-at (optional uint)) (lifetime uint) (namespace-import principal) (price-function (tuple (base uint) (buckets (list 16 uint)) (coeff uint) (no-vowel-discount uint) (nonalpha-discount uint))) (revealed-at uint)))) int)` -#### Signature: `(get-namespace-properties namespace)` -#### Description: -Get namespace properties. - -### is-name-lease-expired - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(is-name-lease-expired namespace name)` -#### Description: -Return true if the provided name lease is expired. - -### name-resolve - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response (tuple (lease-ending-at (optional uint)) (lease-started-at uint) (owner principal) (zonefile-hash (buff 20))) int)` -#### Signature: `(name-resolve namespace name)` -#### Description: -Get name registration details. - -### resolve-principal - -#### Input: `principal` -#### Output: `(response (tuple (name (buff 48)) (namespace (buff 20))) (tuple (code int) (name (optional (tuple (name (buff 48)) (namespace (buff 20)))))))` -#### Signature: `(resolve-principal owner)` -#### Description: -Returns the registered name that a principal owns if there is one. A principal can only own one name at a time. - -## Error codes - -### ERR_INSUFFICIENT_FUNDS -#### type: `int` -#### value: `4001` - -### ERR_NAMESPACE_ALREADY_EXISTS -#### type: `int` -#### value: `1006` - -### ERR_NAMESPACE_ALREADY_LAUNCHED -#### type: `int` -#### value: `1014` - -### ERR_NAMESPACE_BLANK -#### type: `int` -#### value: `1013` - -### ERR_NAMESPACE_CHARSET_INVALID -#### type: `int` -#### value: `1016` - -### ERR_NAMESPACE_HASH_MALFORMED -#### type: `int` -#### value: `1015` - -### ERR_NAMESPACE_NOT_FOUND -#### type: `int` -#### value: `1005` - -### ERR_NAMESPACE_NOT_LAUNCHED -#### type: `int` -#### value: `1007` - -### ERR_NAMESPACE_OPERATION_UNAUTHORIZED -#### type: `int` -#### value: `1011` - -### ERR_NAMESPACE_PREORDER_ALREADY_EXISTS -#### type: `int` -#### value: `1003` - -### ERR_NAMESPACE_PREORDER_CLAIMABILITY_EXPIRED -#### type: `int` -#### value: `1009` - -### ERR_NAMESPACE_PREORDER_EXPIRED -#### type: `int` -#### value: `1002` - -### ERR_NAMESPACE_PREORDER_LAUNCHABILITY_EXPIRED -#### type: `int` -#### value: `1010` - -### ERR_NAMESPACE_PREORDER_NOT_FOUND -#### type: `int` -#### value: `1001` - -### ERR_NAMESPACE_PRICE_FUNCTION_INVALID -#### type: `int` -#### value: `1008` - -### ERR_NAMESPACE_STX_BURNT_INSUFFICIENT -#### type: `int` -#### value: `1012` - -### ERR_NAMESPACE_UNAVAILABLE -#### type: `int` -#### value: `1004` - -### ERR_NAME_ALREADY_CLAIMED -#### type: `int` -#### value: `2011` - -### ERR_NAME_BLANK -#### type: `int` -#### value: `2010` - -### ERR_NAME_CHARSET_INVALID -#### type: `int` -#### value: `2022` - -### ERR_NAME_CLAIMABILITY_EXPIRED -#### type: `int` -#### value: `2012` - -### ERR_NAME_COULD_NOT_BE_MINTED -#### type: `int` -#### value: `2020` - -### ERR_NAME_COULD_NOT_BE_TRANSFERED -#### type: `int` -#### value: `2021` - -### ERR_NAME_EXPIRED -#### type: `int` -#### value: `2008` - -### ERR_NAME_GRACE_PERIOD -#### type: `int` -#### value: `2009` - -### ERR_NAME_HASH_MALFORMED -#### type: `int` -#### value: `2017` - -### ERR_NAME_NOT_FOUND -#### type: `int` -#### value: `2013` - -### ERR_NAME_NOT_RESOLVABLE -#### type: `int` -#### value: `2019` - -### ERR_NAME_OPERATION_UNAUTHORIZED -#### type: `int` -#### value: `2006` - -### ERR_NAME_PREORDERED_BEFORE_NAMESPACE_LAUNCH -#### type: `int` -#### value: `2018` - -### ERR_NAME_PREORDER_ALREADY_EXISTS -#### type: `int` -#### value: `2016` - -### ERR_NAME_PREORDER_EXPIRED -#### type: `int` -#### value: `2002` - -### ERR_NAME_PREORDER_FUNDS_INSUFFICIENT -#### type: `int` -#### value: `2003` - -### ERR_NAME_PREORDER_NOT_FOUND -#### type: `int` -#### value: `2001` - -### ERR_NAME_REVOKED -#### type: `int` -#### value: `2014` - -### ERR_NAME_STX_BURNT_INSUFFICIENT -#### type: `int` -#### value: `2007` - -### ERR_NAME_TRANSFER_FAILED -#### type: `int` -#### value: `2015` - -### ERR_NAME_UNAVAILABLE -#### type: `int` -#### value: `2004` - -### ERR_PANIC -#### type: `int` -#### value: `0` - -### ERR_PRINCIPAL_ALREADY_ASSOCIATED -#### type: `int` -#### value: `3001` diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md b/i18n/hi/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md deleted file mode 100644 index ce1b1ba859..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -title: Stacking Contract -description: See a detailed list of all functions and error codes of the Stacking contract. ---- - -## Introduction - -Stacking is implemented as a smart contract using Clarity. You can always find the Stacking contract identifier using the Stacks Blockchain API [`v2/pox` endpoint](https://docs.hiro.so/api#operation/get_pox_info). - -Below is a list of public and read-only functions as well as error codes that can be returned by those methods: - -* [Public functions](#public-functions) -* [Read-only functions](#read-only-functions) -* [Error codes](#error-codes) - -## Public functions - -### allow-contract-caller -#### input: `principal, (optional uint)` -#### output: `(response bool int)` -#### signature: `(allow-contract-caller caller until-burn-ht)` -#### description: -Give a contract-caller authorization to call stacking methods. Normally, stacking methods may only be invoked by _direct_ transactions (i.e., the `tx-sender` issues a direct `contract-call` to the stacking methods). - -By issuing an allowance, the tx-sender may call through the allowed contract. - -### delegate-stack-stx -#### input: `principal, uint, (tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint` -#### output: `(response (tuple (lock-amount uint) (stacker principal) (unlock-burn-height uint)) int)` -#### signature: `(delegate-stack-stx stacker amount-ustx pox-addr start-burn-ht lock-period)` -#### description: -As a delegate, stack the given principal's STX using `partial-stacked-by-cycle`. - -Once the delegate has stacked > minimum, the delegate should call `stack-aggregation-commit`. - -### delegate-stx -#### input: `uint, principal, (optional uint), (optional (tuple (hashbytes (buff 20)) (version (buff 1))))` -#### output: `(response bool int)` -#### signature: `(delegate-stx amount-ustx delegate-to until-burn-ht pox-addr)` -#### description: -Delegate to `delegate-to` the ability to stack from a given address. - -This method _does not_ lock the funds, rather, it allows the delegate to issue the stacking lock. - -The caller specifies: - -* amount-ustx: the total amount of ustx the delegate may be allowed to lock -* until-burn-ht: an optional burn height at which this delegation expiration -* pox-addr: an optional p2pkh or p2sh address to which any rewards *must* be sent - -### disallow-contract-caller -#### input: `principal` -#### output: `(response bool int)` -#### signature: `(disallow-contract-caller caller)` -#### description: -Revokes authorization from a contract to invoke stacking methods through contract-calls - -### reject-pox -#### input: -#### output: `(response bool int)` -#### signature: `(reject-pox)` -#### description: -Reject Stacking for this reward cycle. - -`tx-sender` votes all its uSTX for rejection. - -Note that unlike Stacking, rejecting PoX does not lock the tx-sender's tokens: PoX rejection acts like a coin vote. - -### revoke-delegate-stx -#### input: -#### output: `(response bool int)` -#### signature: `(revoke-delegate-stx)` -#### description: -Revoke a Stacking delegate relationship. A particular Stacker may only have one delegate, so this method does not take any parameters, and just revokes the Stacker's current delegate (if one exists). - -### stack-aggregation-commit -#### input: `(tuple (hashbytes (buff 20)) (version (buff 1))), uint` -#### output: `(response bool int)` -#### signature: `(stack-aggregation-commit pox-addr reward-cycle)` -#### description: -Commit partially stacked STX. - -This allows a stacker/delegate to lock fewer STX than the minimal threshold in multiple transactions, - -so long as: - -1. The pox-addr is the same. -2. This \"commit\" transaction is called _before_ the PoX anchor block. - -This ensures that each entry in the reward set returned to the stacks-node is greater than the threshold, - - but does not require it be all locked up within a single transaction - -### stack-stx -#### input: `uint, (tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint` -#### output: `(response (tuple (lock-amount uint) (stacker principal) (unlock-burn-height uint)) int)` -#### signature: `(stack-stx amount-ustx pox-addr start-burn-ht lock-period)` -#### description: -Lock up some uSTX for stacking! Note that the given amount here is in micro-STX (uSTX). - -The STX will be locked for the given number of reward cycles (lock-period). - -This is the self-service interface. tx-sender will be the Stacker. - -* The given stacker cannot currently be stacking. -* You will need the minimum uSTX threshold. This isn't determined until the reward cycle begins, but this method still requires stacking over the _absolute minimum_ amount, which can be obtained by calling `get-stacking-minimum`. -* The pox-addr argument must represent a valid reward address. Right now, this must be a Bitcoin p2pkh or p2sh address. It cannot be a native Segwit address, but it may be a p2wpkh-p2sh or p2wsh-p2sh address. - -The tokens will unlock and be returned to the Stacker (tx-sender) automatically. - -## Read-only functions - -### can-stack-stx -#### input: `(tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint, uint` -#### output: `(response bool int)` -#### signature: `(can-stack-stx pox-addr amount-ustx first-reward-cycle num-cycles)` -#### description: -Evaluate if a participant can stack an amount of STX for a given period. - -### get-pox-info -#### input: -#### output: `(response (tuple (current-rejection-votes uint) (first-burnchain-block-height uint) (min-amount-ustx uint) (prepare-cycle-length uint) (rejection-fraction uint) (reward-cycle-id uint) (reward-cycle-length uint) (total-liquid-supply-ustx uint)) UnknownType)` -#### signature: `(get-pox-info)` -#### description: -Returns information about PoX status. - -### get-pox-rejection -#### input: `principal, uint` -#### output: `(optional (tuple (amount uint)))` -#### signature: `(get-pox-rejection stacker reward-cycle)` -#### description: -Returns the amount of uSTX that a given principal used to reject a PoX cycle. - -### get-stacker-info -#### input: `principal` -#### output: `(optional (tuple (amount-ustx uint) (first-reward-cycle uint) (lock-period uint) (pox-addr (tuple (hashbytes (buff 20)) (version (buff 1))))))` -#### signature: `(get-stacker-info stacker)` -#### description: -Returns the _current_ stacking information for `stacker. If the information is expired, or if there's never been such a stacker, then returns none. - -### get-stacking-minimum -#### input: -#### output: `uint` -#### signature: `(get-stacking-minimum)` -#### description: -Returns the absolute minimum amount that could be validly Stacked (the threshold to Stack in a given reward cycle may be higher than this - -### get-total-ustx-stacked -#### input: `uint` -#### output: `uint` -#### signature: `(get-total-ustx-stacked reward-cycle)` -#### description: -Returns the amount of currently participating uSTX in the given cycle. - -### is-pox-active -#### input: `uint` -#### output: `bool` -#### signature: `(is-pox-active reward-cycle)` -#### description: -Returns whether or not PoX has been rejected at a given PoX cycle. -## Error codes - -### ERR_DELEGATION_EXPIRES_DURING_LOCK -#### type: `int` -#### value: `21` - -### ERR_DELEGATION_POX_ADDR_REQUIRED -#### type: `int` -#### value: `23` - -### ERR_DELEGATION_TOO_MUCH_LOCKED -#### type: `int` -#### value: `22` - -### ERR_INVALID_START_BURN_HEIGHT -#### type: `int` -#### value: `24` - -### ERR_NOT_ALLOWED -#### type: `int` -#### value: `19` - -### ERR_STACKING_ALREADY_DELEGATED -#### type: `int` -#### value: `20` - -### ERR_STACKING_ALREADY_REJECTED -#### type: `int` -#### value: `17` - -### ERR_STACKING_ALREADY_STACKED -#### type: `int` -#### value: `3` - -### ERR_STACKING_EXPIRED -#### type: `int` -#### value: `5` - -### ERR_STACKING_INSUFFICIENT_FUNDS -#### type: `int` -#### value: `1` - -### ERR_STACKING_INVALID_AMOUNT -#### type: `int` -#### value: `18` - -### ERR_STACKING_INVALID_LOCK_PERIOD -#### type: `int` -#### value: `2` - -### ERR_STACKING_INVALID_POX_ADDRESS -#### type: `int` -#### value: `13` - -### ERR_STACKING_NO_SUCH_PRINCIPAL -#### type: `int` -#### value: `4` - -### ERR_STACKING_PERMISSION_DENIED -#### type: `int` -#### value: `9` - -### ERR_STACKING_POX_ADDRESS_IN_USE -#### type: `int` -#### value: `12` - -### ERR_STACKING_STX_LOCKED -#### type: `int` -#### value: `6` - -### ERR_STACKING_THRESHOLD_NOT_MET -#### type: `int` -#### value: `11` - -### ERR_STACKING_UNREACHABLE -#### type: `int` -#### value: `255` \ No newline at end of file diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md b/i18n/hi/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md deleted file mode 100644 index 5f38edfb57..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: xBTC -description: Wrapped BTC on Stacks ---- - -![](/img/xbtc-icon.webp) - -## Introduction - -[Wrapped.com](https://www.wrapped.com) has brought Bitcoin (xBTC) to the Stacks ecosystem. - -xBTC is backed 1:1 by Bitcoin and empowers developers to expand the Bitcoin DeFi ecosystem. - -The reserves are publicly visible [here](https://open.wrapped.com/reserves/). - -## Contract - -[SP3DX3H4FEYZJZ586MFBS25ZW3HZDMEW92260R2PR.Wrapped-Bitcoin](https://explorer.stacks.co/txid/SP3DX3H4FEYZJZ586MFBS25ZW3HZDMEW92260R2PR.Wrapped-Bitcoin?chain=mainnet) - -## Examples of uses - -[Friedger Mining Pool](https://pool.friedger.de/) currrently supports Stacking rewards payments in xBTC (optional). - - -## More information - -* [Blog post announcement](https://www.stacks.co/blog/tokensoft-wrapped-fundamental-bitcoin-defi-building-blocks-xbtc) by Muneeb Ali - -* Video: [Why xBTC is Important For Bitcoin to Grow](https://www.youtube.com/watch?v=xIoadrfSdi4) \ No newline at end of file diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/references/_category_.json b/i18n/hi/docusaurus-plugin-content-docs/current/references/_category_.json deleted file mode 100644 index 3805ab0783..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/references/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "References", - "position": 9, - "link": { - "type": "generated-index", - "description": "Stacks references." - } -} \ No newline at end of file diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/references/glossary.md b/i18n/hi/docusaurus-plugin-content-docs/current/references/glossary.md deleted file mode 100644 index 1027a52c96..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/references/glossary.md +++ /dev/null @@ -1,215 +0,0 @@ ---- -title: Glossary -description: A comprehensive list of terms used within the ecosystem. ---- - -A comprehensive list of terms used within the ecosystem. - -#### App Review -An incentive mechanism for application developers in the early stage (first four years) of the ecosystem and helps with bootstrapping the two-sided market. - -#### Atlas -A peer network provide a global index for discovery. - -#### Bitcoin (BTC) address -A string of letters and numbers. `3E53XjqK4Cxt71BGeP2VhpcotM8LZ853C8` Sharing this address allows anyone to send Bitcoin to the address. - -#### block -A discrete group of records written to a blockchain that can effectively be identified and referenced by the use of headers that contain a digital fingerprint of the records each block contains. - -#### blockchain -A database created and shared by the members of a peer-to-peer computer network which each member of that network can independently trust due to the rules governing the database’s creation. A blockchain can therefore be used to replace centralized databases. - -#### Blockchain Name System (BNS) -Replacement for DNS. More info [here](../noteworthy-contracts/bns-contract). - -#### Blockstack Browser -A deprecated application for accessing identity and storage. - -#### Blockstack Owner Address - -Looks like a bitcoin address but starts with `ID` for example: `ID-1J3PUxY5uDShUnHRrMyU6yKtoHEUPhKULs` - -#### Burning -Burning a token means that the token is transferred to an address that is a black hole—one that is not owned by any entity and for which guessing the applicable private key is effectively impossible based on known mathematical principles. This effectively destroys the token by making it unavailable for future use and decreases the total number of tokens available from that point forward. - -#### consensus hash -A consensus hash is a cryptographic hash that each node calculates at each block. It is derived from the accepted state transitions in the last-processed block and a geometric series of prior-calculated consensus hashes. - -#### Consensus rules -"The rules governing the creation of new valid records in a blockchain database and the mining algorithms used for this purpose. - -#### control plane -The part of a network that carries signaling traffic and is responsible for routing. Control packets originate from or are destined for a router. Functions of the control plane include system configuration and management. - -#### core node -A server that runs Stacks Blockchain services. - -#### crypto-asset -A digital asset which utilises cryptography, peer-to-peer networking and a public ledger to regulate the creation of new units, verify transactions and secure the transactions without the intervention of any middleman. - -#### cryptography -The practise and study of encryption and decryption - encoding data so that it can only be decoded by specific individuals. A system for encrypting and decrypting data is a cryptosystem. - -#### DAO -See Decentralized Autonomous Organization. - -#### decentralized application (DApp) -A DApp is a service that enables direct interaction between end users and providers (e.g. connecting buyers and sellers in some marketplace, owners and stores in file storage). A term coined by Ethereum. See their glossary: http://ethdocs.org/en/latest/glossary.html#dapp" - -#### Decentralized Autonomous Organization -A type of contract or suite of contracts on the blockchain that is intented to codify, enforce or automate the processes of an organization. - -#### digital asset -Also referred to as a crypto-asset. Any set of unique digital information—including, for example, programs, decentralized programs, isolated chunks of programming code, collections of data, e-mail or web addresses or cryptocurrency tokens—that is capable of being stored and uniquely tracked on a computer network such as the Stacks network and over which a user can maintain control through that network. - -#### digital fingerprint -A digital fingerprint is a unique number of a fixed length that can be produced by running any set of digital information through something called a cryptographic hash function. Each set of digital information (including a digital asset, and the digital record of any network operation on that digital asset) should (as a practical matter) have a unique digital fingerprint, which allows that set of digital information to be identified. However, it is almost impossible to recreate a digital asset from its digital fingerprint. The Blockstack network uses industry-standard algorithms such as SHA-256 to create digital fingerprints. - -#### digital signature -A digital signature is a sequence of digital information combining a user’s private key and any digital information that the user wishes to sign. Any other party can use the user’s paired public key to verify that the digital signature is authentic, i.e. that the public key was generated from a particular piece of digital information and the user’s private key. - -#### distributed hash tables (DHT) -A form of network used to store some content in the form of key/value pairs. ... This experimental project try to avoid keeping all the blockchain, but instead prefers to store it in a DHT. - -#### ephemeral key -A cryptographic key is called ephemeral if it is generated for each execution of a key establishment process. - -#### fork -The term fork is used to refer both to any situation where there are two or more competing versions of a blockchain on a network (a situation that may arise and resolve itself in the ordinary course of network operations due to lags in communication between core nodes) and any software update that is proposed for adoption by the core nodes of a blockchain network that may result in a persistent fork on the network, with core nodes that adopt the update recognizing one version of the blockchain and those which do not recognizing another. - -#### Gaia -Decentralized storage architecture for off-chain data. More info [here](../gaia). - -#### genesis block -The genesis block is the first block of the Stacks blockchain, which will create the initial 1.32 billion Stacks Tokens. - -#### id.blockstack -An identifier in the Blockstack, for example meepers.id.blockstack. This is your name & identity that is registered in the .id namespace on Blockstack. Your personal data and storage are built around this ID. Apps that want to access your data use your permission and identity to find it. An id is usually a shorthand for a longer, hash ID string, for example ID-1Fj9kkw15P51Fj9kkw15P5xJmyefWhLKrQMKNPREfaqsJ" - -#### identity - -A way to identify a person or an organization on the Stacks network. An identity is unique, both `meepers.id.blockstack` or `chad.id` are examples of IDs. - -#### identity management (IDM) -Identity management, also known as identity and access management is, in computer security, the security and business discipline that enables the right individuals to access the right resources at the right times and for the right reason". - -#### know your customer (KYC) -Or KYC, is a popular term used in the banking or financial field. KYC is a process where financial institutions, insurers and other companies obtain information about the identity and address of the customers as part of risk management. - -#### light clients -Clients that can independently validate the existence of transactions by downloading only block headers and not the entire blockchain. - -#### magic recovery code - -A long encrypted string, for example: `36mWivFdy0YPH2z31EflpQz/Y0UMrOrJ++lH=0EI7c3mop2JuRBm5WXxSTazJsUjOA...` Do not share the QR code that accompanied your recovery code either. This is a QR code: - -![](/img/qr-code.png) - -#### mesh network -A local network topology in which the infrastructure nodes (i.e. bridges, switches, and other infrastructure devices) connect directly, dynamically and non-hierarchically to as many other nodes as possible and cooperate with one another to efficiently route data from/to clients. - -#### mining -Mining generally refers to the process of performing certain functions for a network such as adding new records to a blockchain in exchange for mining rewards; it may also refer to other mechanisms whereby rewards (usually in the form of cryptocurrency) are provided for performing other tasks helpful to the network. - -#### mining power -A miner’s (or group of miners’) mining power is equal to the probability it will be selected to write a new block to the blockchain. Depending on the mechanism for mining, this is usually related to the overall share of computing power or cryptoassets the miner or miners possess relative to all miners for that blockchain. - -#### mining rewards -Mining rewards are newly issued tokens received by miners in exchange for adding new records to the blockchain or other activities beneficial to the network. - -#### name -An identifier or name. Names are a type of digital asset in the Stacks network. If you have signed into the Stacks Wallet, you might have created a name. If an application developer registered an application within Stacks, then they registered a name. Public Stacking pools can also have a name. - -#### network operation -A network operation is any change to the information about a digital asset (or smart contract) stored on a blockchain, including, for example, a change in the digital asset’s owner, or a change in the location at which it is stored on the network. How and when these network operations are performed for each digital asset is governed, on the Blockstack network, either by the Stacks Node software or a smart contract. - -#### NFT -Non fungible token. - -#### private key - -Private keys matches a corresponding public key. A public key also looks like a string of letters and numbers: - -![](/img/private.png) - -The exact format of the public and private key depend on the software you use to create them. - -#### proof-of-burn mining -The consensus algorithm used in the Stacks blockchain where miners destroy a proof-of-work-based cryptocurrency (currently Bitcoin) to get tokens; this enables the functionality where nodes can select between conflicting blockchain forks, as the blockchain fork with the most amount of cryptocurrency burned is considered to be the correct fork. - -#### proof-of-work -A proof-of-work system or proof-of-work mining is a mining mechanism where miners must expend computing power to solve complicated cryptographic puzzles, and prove that they have done so by writing the solution to the blockchain, in order to be allowed to add blocks to a blockchain. This is the mining system used, for example, by Bitcoin. - -#### public key -Public and private key pair comprise of two uniquely related cryptographic keys. It looks like a long random string of letters and numbers: `3048 0241 00C9 18FA CF8D EB2D EFD5 FD37 89B9 E069 EA97 FC20 …` The exact format of the public and private key depend on the software you use to create them. - -#### Public Key Infrastructure (PKI) -A system which returns a cryptographic public key associated with a name. - -#### replicated state machines (RSMs) -This is a model for reasoning about distributed computer programs -- any program (plus it's input) can be represented as a state machine, and when trying to get a distributed set of servers to agree on the output of an algorithm, you can model that process as N different state machines" - -#### Secret recovery Key, -Used to access an identity on the Stacks blockchain. A 24-word sequence of words for example: `applied binge crisp pictorial fiery` `dancing agreeable frogs light finish ping apple` - -#### seed phrase - -Used to access Stacks Wallet software. The seed phrase consists of 24 words in a sequence. Both the word *and its position the sequence* are important. Write down your seed phrase and store it in a secure location such as a safe deposit box. When you write the seed phrase down, include its position, for example,`1-frog, 2-horse, 3-building` and so on until you reach a final position `24-ocean`. -#### smart contract -A smart contract is a computer program written to a blockchain such as the Stacks blockchain by developers. This computer program defines the various network operations that can be performed on the digital assets on the blockchain, the computations that can be performed using the smart contract, along with defining various important properties of the respective digital assets like ownership rights and the cost in fuel required to register the digital assets. - -#### soft fork -A soft fork is a proposed update to the software governing the network that results in a post-update network that is compatible with the network as it existed prior to the update, because it restricts the network operations that can be performed after the update. - -#### Stacks (STX) address - - A STX address is a string of letters and numbers starting with an `SP` or `SM`, for example: `SM3KJBA4RZ7Z20KD2HBXNSXVPCR1D3CRAV6Q05MKT` If you created a software-only wallet with the Stacks Wallet software, the wallet has a single STX address which is also sometimes called the *wallet address*. You access a software wallet with a *seed phrase*. " - -#### Stacks blockchain -The Stacks blockchain is the custom blockchain being developed for use by the Stacks network that will use the Stacks token as its native currency and which will include the genesis block and subsequent blocks created by the mining activities described in the Stacks Network—Development of the Stacks network. - -#### Stacks Explorer -An application that allow you to view and search transactions in the blockchain. For example, https://explorer.stacks.co. - -#### Stacks node -A complete version of our open-source software available on Github at https://github.com/stacks-network/stacks-blockchain/ that governs the creation of the blockchain, the smart contracts that may be written to our blockchain, and other systems that make up the Stacks network, when run on the systems and devices of our users and developers. - -#### Stacks wallet -An application for accessing assets, identity and storage. More information and example [here](../services-using-stacks/wallets). Examples are the [Hiro Wallet](https://www.hiro.so/wallet), [xverse](https://www.xverse.app/) and [dcent](https://dcentwallet.com/). - -#### storage hub -A Gaia instance run by a hub provider or software. A Gaia hub stores data in a separate, addressed location. - -#### storage provider -A third-party company cloud or software provider that hosts one or more Gaia storage hubs. - -#### transaction -A transaction is a unit of work within a block. - -#### transaction fee -Fees paid by participants in a transaction to miners. - -#### two-sided market problem -Economic platforms having two distinct user groups that provide each other with network benefits. The Stacks platform is a classic two-sided market. - -#### username -A shorthand name for your id.blockstack. - -#### virtual blockchain -A layer that sits on top of a blockchain that introduces new functionality and operations without requiring changes to the underlying blockchain. - -#### wallet address -A wallet address is the form in which a public key can be presented and recorded on a blockchain. Wallet addresses are therefore used to assign the ownership of digital assets on the Blockstack network. - -#### watch-only wallet -A wallet without send and receive ability. You can view only balances and transaction history. - -#### web of trust mining -Web-of-trust mining provides incentive mechanisms for users where an initial trusted-set of unique users is curated in the genesis block and, in the future, the initial set of users can expand the web-of-trust after the network goes live. - -#### web3 -The exact definition is still under discussion, but it general refers to the 3rd generation of the web that is based on blockchain technology and incorporates decentralized and token-based economics. - -#### zone file -A Domain Name System (DNS) zone file is a text file that describes a DNS zone. A DNS zone is a subset, often a single domain, of the hierarchical domain name structure of the DNS. diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/references/nft.md b/i18n/hi/docusaurus-plugin-content-docs/current/references/nft.md deleted file mode 100644 index 033ee0a71a..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/references/nft.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: NFTs on Stacks -description: A list of sites that operate NFTs on Stacks ---- - -List of sites that operate NFTS on Stacks on alphabetical order. - -### [Byzantion](https://byzantion.xyz/) - -![website-screenshot](/img/sh_nft_byzantion.png) - -### [Gamma](https://gamma.io/) -![website-screenshot](/img/sh_nft_gamma.png) - -### [Megapont](https://www.megapont.com/) - -![website-screenshot](/img/sh_nft_megapont.png) - -### [StacksArt](https://www.stacksart.com/) - -![website-screenshot](/img/sh_nft_stacksart.png) - diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md b/i18n/hi/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md deleted file mode 100644 index dc6e507d5e..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Stacks info sites -description: A list of sites on alphabetical order that display status and stats of the Stacks network. ---- - -### [Haystack](https://haystack.tools/mempool) - -![website-screenshot](/img/sh_haystacks.png) - -### [Stacksdata](https://stacksdata.info/) - -![website-screenshot](/img/sh_stacksdata.png) - -### [Stacksonchain](https://stacksonchain.com) - -![website-screenshot](/img/sh_stacksonchain.png) - -### [Status Hiro](https://status.hiro.so/) - -![website-screenshot](/img/sh_statushiro.png) - -### [Stxstats](https://www.stxstats.co/) - -![website-screenshot](/img/sh_stxstats.png) - -### [Novuminsights](https://stacks.novuminsights.com/health) - -![website-screenshot](/img/sh_novuminsights.png) - -### [Onstacks](https://app.onstacks.com/) - -![website-screenshot](/img/sh_onstacks.png) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json b/i18n/hi/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json deleted file mode 100644 index ebd63f366c..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Services using Stacks", - "position": 8, - "link": { - "type": "generated-index", - "description": "An 'always incomplete' list of services that use Stacks." - } -} \ No newline at end of file diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md b/i18n/hi/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md deleted file mode 100644 index 51defacba7..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: DeFi -description: De-Fi sites on Stacks -sidebar_position: 2 ---- - -They are multiple De-Fi sites that operate on the Stacks blockchain. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Alex - -[Alex](https://app.alexlab.co) ![](/img/sh_alex.png) - -## Arkadiko - -[Arkadiko](https://arkadiko.finance/) ![](/img/sh_arkadiko.png) - -## Catamaran Swaps - -[Catamaran Swaps](https://www.catamaranswaps.org/) allows trustless exchange of digital assets. - -![](/img/sh_catamaran.png) - -## Lnswap - -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange - -![](/img/sh_lnswap.png) - -## Neoswap - -[Neoswap](https://neoswap.party) - -![](/img/sh_neoswap.png) - -## Stackswap - -[Stackswap](https://app.stackswap.org/v2) - -![](/img/sh_stackswap.png) - diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/services-using-stacks/more.md b/i18n/hi/docusaurus-plugin-content-docs/current/services-using-stacks/more.md deleted file mode 100644 index df0b3e2254..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/services-using-stacks/more.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: More -description: More services built on Stacks. -sidebar_position: 5 ---- - -List of sites on alphabetical order added by the community. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Citycoins - -[Citycoins](https://citycoins.co) - -![](/img/sh_citycoins.png) - -## Sigle - -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. - -![](/img/sh_sigle.png) \ No newline at end of file diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md b/i18n/hi/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md deleted file mode 100644 index bfa0505dc9..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: NFTs -description: NFTs on Stacks -sidebar_position: 3 ---- - -List of sites that operate NFTS on Stacks on alphabetical order. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -### [Byzantion](https://byzantion.xyz/) - -![website-screenshot](/img/sh_nft_byzantion.png) - -### [Gamma](https://gamma.io/) -![website-screenshot](/img/sh_nft_gamma.png) - -### [Megapont](https://www.megapont.com/) - -![website-screenshot](/img/sh_nft_megapont.png) - -### [StacksArt](https://www.stacksart.com/) - -![website-screenshot](/img/sh_nft_stacksart.png) - -### [Superfandom](https://superfandom.io/) - -![website-screenshot](/img/sh_superfandom.png) \ No newline at end of file diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/services-using-stacks/other.md b/i18n/hi/docusaurus-plugin-content-docs/current/services-using-stacks/other.md deleted file mode 100644 index 199fc41da5..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/services-using-stacks/other.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Other Stacks sites -description: A list of sites on alphabetical order built on Stacks. -sidebar_position: 4 ---- - -List of sites on alphabetical order added by the community. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Alex -[Alex](https://app.alexlab.co) - -## Sigle - -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. \ No newline at end of file diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md b/i18n/hi/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md deleted file mode 100644 index 35ced8dac6..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Stacks info sites -description: Status and stats of the Stacks network. -sidebar_position: 1 ---- - -A list of sites on alphabetical order that display status and stats of the Stacks network. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -### [Haystack](https://haystack.tools/mempool) - -![website-screenshot](/img/sh_haystacks.png) - -### [Stacksdata](https://stacksdata.info/) - -![website-screenshot](/img/sh_stacksdata.png) - -### [Stacksonchain](https://stacksonchain.com) - -![website-screenshot](/img/sh_stacksonchain.png) - -### [Status Hiro](https://status.hiro.so/) - -![website-screenshot](/img/sh_statushiro.png) - -### [Stxstats](https://www.stxstats.co/) - -![website-screenshot](/img/sh_stxstats.png) - -### [Novuminsights](https://stacks.novuminsights.com/health) - -![website-screenshot](/img/sh_novuminsights.png) - -### [Onstacks](https://app.onstacks.com/) - -![website-screenshot](/img/sh_onstacks.png) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md b/i18n/hi/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md deleted file mode 100644 index d4b4cbf18c..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Swaps -description: A list of sites that allow Swaps -sidebar_position: 2 ---- - -They are multiple sites that allow you to make swaps using the Stacks blockchain. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Catamaran Swaps - -[Catamaran Swaps](https://www.catamaranswaps.org/) allows trustless exchange of digital assets. - -![](/img/sh_catamaran.png) - -## Lnswap - -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange - -![](/img/sh_lnswap.png) - -## Neoswap - -[Neoswap](https://neoswap.party) - -![](/img/sh_neoswap.png) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md b/i18n/hi/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md deleted file mode 100644 index e5ea6c5b45..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Wallets -description: Wallets for Stacks -sidebar_position: 4 ---- - -A list of hardware and software wallets for Stacks - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Blockchain.com - -[Blockchain.com](https://www.blockchain.com/wallet) - -![](/img/sh_blockchain.png) -## Boom - -[Boom](https://boom.money) - -![](/img/sh_boom.png) - -## Dcent wallet - -[D'CENT](https://dcentwallet.com) - -![](/img/sh_dcent.png) -## Hiro Wallet - -[Hiro Wallet](https://www.hiro.so/wallet) - -![](/img/sh_hirowallet.png) - -## Neptune - -[Neptune](https://neptunewallet.io) - -![](/img/sh_neptunewallet.png) - -## Xverse - -[Xverse](https://www.xverse.app/) - -![](/img/sh_xverse.png) - -## Wise - -[Wise](https://wiseapp.id) - -![](/img/sh_wiseapp.png) \ No newline at end of file diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md b/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md deleted file mode 100644 index bd2c361985..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md +++ /dev/null @@ -1,214 +0,0 @@ ---- -title: Accounts -description: Guide to Stacks 2.0 accounts -sidebar_position: 5 ---- - -## Introduction - -Stacks 2.0 accounts are entities that own assets, like Stacks (STX) tokens. An account has an address, private key, nonce, and one or more asset balances. - -:::tip The encryption algorithm used in Stacks 2.0 is **[secp256k1](https://en.bitcoinwiki.org/wiki/Secp256k1)**. - -Additionally, [Ed25519](https://ed25519.cr.yp.to/) is also used just for the VRF (Verifiable Random Function). ::: - -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. - -:::tip -The transaction type doesn't need to be a token transfer - contract deploy and contract call transactions can change the balances of an account -::: - -## Creation - -An account is generated from a 24-word mnemonic phrase. This is often referred to as the **seed phrase**. The seed phrase provides access to Stacks 2.0 accounts. - -:::danger -If the seed phrase is lost, access to the associated account cannot be restored. No person or organization, including Blockstack, can recover a lost seed phrase. -::: - -The easiest way to generate a new Stacks 2.0 account is to use the [Stacks CLI](https://github.com/hirosystems/stacks.js/tree/master/packages/cli): - -```bash -# install CLI globally -npm install --global @stacks/cli - -# generate a new account and store details in a new file -# '-t' option makes this a testnet account -stx make_keychain -t > cli_keychain.json -``` - -`make_keychain` creates the following file: - -```js -{ - "mnemonic": "aaa bbb ccc ddd ...", - "keyInfo": { - "privateKey": "5a3f1f15245bb3fb...", - "address": "STJRM2AMVF90ER6G3RW1QTF85E3HZH37006D5ER1", - "btcAddress": "biwSd6KTEvJcyX2R8oyfgj5REuLzczMYC1", - "wif": "L4HXn7PLmzoNW...", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -| Field | Description | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `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.privateKey` | Private key for the account. Required for token transfers and often referred to as `senderKey` | -| `keyInfo.address` | Stacks address for the account | -| `keyInfo.btcAddress` | Corresponding BTC address for the account. | -| `keyInfo.wif` | Private key of the btcAddress in compressed format. | -| `keyInfo.index` | Nonce for the account, starting at 0 | - -Note that a new account automatically exists for each new private key. There is no need to manually instantiate an account on the Stacks 2.0 blockchain. - -:::tip Addresses are created by generating the [RIPEMD-160 hash](https://en.wikipedia.org/wiki/RIPEMD#RIPEMD-160_hashes) of the [SHA256](https://en.bitcoinwiki.org/wiki/SHA-256) of the public key. BTC addresses are encoded with [Base58Check](https://en.bitcoin.it/wiki/Base58Check_encoding). For Stacks addresses, [c32check](https://github.com/stacks-network/c32check) is used. Deriving an address from a public key can be done without internet access, for instance using the c32check `c32addressDecode` method. ::: - -Alternatively to the CLI creation, the [Stacks Transactions JS](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library can be used: - -```js -import { - makeRandomPrivKey, - privateKeyToString, - getAddressFromPrivateKey, - TransactionVersion, -} from '@stacks/transactions'; - -const privateKey = makeRandomPrivKey(); - -// Get public key from private -const publicKey = getPublicKey(privateKey); - -const stacksAddress = getAddressFromPrivateKey( - privateKeyToString(privateKey), - TransactionVersion.Testnet // remove for Mainnet addresses -); -``` - -A second alternative would be to use [stacks-gen](https://github.com/psq/stacks-gen). This tool will generate all the keys you need in one place, including the values needed for calling the stacking contract, and also a WIF key for use with `bitcoind`. - -#### stacks-gen prerequisite - -Install [npx](https://github.com/npm/npx) if not already installed. (npx will check whether `` exists in \$PATH, or in the local project binaries, and execute that. If `` is not found, it will be installed prior to execution). - -``` -npm install -g npx -``` - -#### stacks-gen usage - -``` -npx -q stacks-gen sk --testnet - -{ - "phrase": "guide air pet hat friend anchor harvest dog depart matter deny awkward sign almost speak short dragon rare private fame depart elevator snake chef", - "private": "0351764dc07ee1ad038ff49c0e020799f0a350dd0769017ea09460e150a6401901", - "public": "022d82baea2d041ac281bebafab11571f45db4f163a9e3f8640b1c804a4ac6f662", - "stacks": "ST16JQQNQXVNGR8RZ1D52TMH5MFHTXVPHRV6YE19C", - "stacking": "{ hashbytes: 0x4d2bdeb7eeeb0c231f0b4a2d5225a3e3aeeed1c6, version: 0x00 }", - "btc": "mnYzsxxW271GkmyMnRfiopEkaEpeqLtDy8", - "wif": "cMh9kwaCEttgTQYkyMUYQVbdm5ZarZdBHErcq7mXUChXXCo7CFEh" -} -``` - -:::tip The stacking object with hashbytes and a version represents the bitcoin address derived from the Stacks address. Read more about the [bitcoin address format](stacking#bitcoin-address). ::: - -Full documentation available at [stacks-gen](https://github.com/psq/stacks-gen). - -## Querying - -### Get Stacks (STX) balance and nonce - -STX balance and nonce can be obtained through the [`GET /v2/accounts/`](https://docs.hiro.so/api#operation/get_account_info) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/accounts/' -``` - -Sample response: - -```js -{ - "balance": "0x0000000000000000002386f26f3f40ec", - "nonce": 17 -} -``` - -:::tip -The balance string represents an unsigned 128-bit integer (big-endian) in hex encoding -::: - -### Get all token balances - -All token balances can be obtained through the [`GET /extended/v1/address//balances`](https://docs.hiro.so/api#operation/get_account_balance) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/address//balances' -``` - -Sample response: - -```js -{ - "stx": { - "balance": "0", - "total_sent": "0", - "total_received": "0" - }, - "fungible_tokens": {}, - "non_fungible_tokens": {} -} -``` - -:::tip Stacks accounts cannot hold bitcoins. The best way to obtain corresponding BTC balances is to derive the BTC address from the Stacks address (using [`c32check`](https://github.com/stacks-network/c32check#c32tob58-b58toc32)) and query the Bitcoin network. ::: - -### Get all asset events - -All asset events associated with the account can be obtained through the [`GET /extended/v1/address//assets`](https://docs.hiro.so/api#operation/get_account_balance) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/address//assets' -``` - -Sample response: - -```js -{ - "limit": 20, - "offset": 0, - "total": 0, - "results": [ - { - "event_index": 5, - "event_type": "non_fungible_token_asset", - "asset": { - "asset_event_type": "transfer", - "asset_id": "ST2W14YX9SFVDB1ZGHSH40CX1YQAP9XKRAYSSVYAG.hello_world::hello-nft", - "sender": "SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR", - "recipient": "SM2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQVX8X0G", - "value": { - "hex": "0x0100000000000000000000000000000001", - "repr": "u1" - } - } - }, - { - "event_index": 3, - "event_type": "fungible_token_asset", - "asset": { - "asset_event_type": "mint", - "asset_id": "ST2W14YX9SFVDB1ZGHSH40CX1YQAP9XKRAYSSVYAG.hello_world::novel-token-19", - "sender": "", - "recipient": "SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR", - "amount": "12" - } - } - ] -} -``` diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/index.md b/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/index.md deleted file mode 100644 index 1533219df9..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/index.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Understand Stacks -description: Learn more about the Stacks 2.0 blockchain -sidebar_position: 1 ---- - -![](/img/SBC-L-2x-10.png) -## Introduction - -Stacks 2.0 is a layer-1 blockchain that connects to Bitcoin and brings smart contracts and decentralized apps to it. Smart contracts and apps developed on the Stacks platform are natively integrated with the security, stability, and economic power of Bitcoin. - -## Capabilities - -Read more about the features provided by the Stacks 2.0 blockchain. - - - -:::tip Check out the [technical specifications](technical-specs) for a brief overview ::: - - - - -A detailed [comparison of the Stacks blockchain to other blockchain technologies][] is available at the Stacks Foundation blog. -### Consensus mechanism -![](/img/pages/stacking.svg) Stacks 2.0 implements a new mining mechanism called Proof of Transfer ("PoX"). PoX is a consensus algorithm between two blockchains. It uses an established blockchain (in this case Bitcoin) to secure a new blockchain (Stacks). - -PoX connects to Bitcoin with a 1:1 block ratio, meaning anything that happens on the Stacks blockchain can be verified on the Bitcoin Blockchain. - -Instead of burning electricity on proof of work, PoX reuses already minted bitcoins as "proof of computation" and miners represent their cost of mining in bitcoins directly. - - -[Read more about Proof of Transfer](proof-of-transfer) -### Mining - -![](/img/pages/testnet-sm.svg) Mining is required to make the network usable, trustworthy, and secure. Miners verify incoming transactions, participate in the consensus mechanism, and write new blocks to the blockchain. - -To incentivize mining, miners receive freshly minted Stacks (STX) tokens if they win the bid for becoming the leader of the next round. - -[Read more about Mining](mining) - -### Stacking - -Bitcoins used for miner bids are sent to a set of specific addresses corresponding to Stacks (STX) tokens holders that are actively participating in consensus ("Stackers"). Thus, rather than being destroyed, the bitcoins consumed in the mining process go to productive Stacks holders as a reward based on their holdings of Stacks and participation in the Stacking algorithm. - -Stackers have to lock up their Stacks (STX) tokens for a certain period of time. - -[Read more about Stacking](stacking) - -### Smart contracts - -![](/img/pages/write-smart-contracts-sm.svg) Clarity is a new language for smart contracts on the Stacks 2.0 blockchain. The Clarity smart contract language optimizes for predictability and security. - -Stacks 2.0 anchors clarity smart contracts to Bitcoin making it possible for smart contracts to operate based on actions seen on the bitcoin blockchain. - -:::note The [Clarity open-source project](https://clarity-lang.org/) is supported by Stacks and [Algorand](https://www.algorand.com/) ::: - - -Clarity is distinct from other languages designed for writing smart contracts in a few ways: - -- **Predictability**: The Clarity language uses precise and unambiguous syntax that allows developers to predict exactly how their contracts will be executed. -- **Security**: The Clarity language allows users to supply their own conditions for transactions that ensure that a contract may never unexpectedly transfer a token owned by a user. -- **No compiler**: Contracts written in Clarity are broadcasted on the Stacks blockchain exactly as they are written by developers. This ensures that the code developers wrote, analyzed, and tested, is exactly what gets executed. - -[Read more about Clarity](../write-smart-contracts/clarity-language/) - -## Guides - -Read one of our guides to understand the ins and outs of the Stacks 2.0 blockchain. - -* [Account](../understand-stacks/accounts) -* [Transactions](../understand-stacks/transactions) -* [Network](../understand-stacks/network) -* [Microblocks](../understand-stacks/microblocks) - -[comparison of the Stacks blockchain to other blockchain technologies]: https://stacks.org/stacks-blockchain diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md b/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md deleted file mode 100644 index de64c617f4..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: Microblocks -description: Guide to Stacks Microblocks -sidebar_position: 8 ---- - -## Introduction - -Microblocks are a protocol-level feature of the Stacks blockchain that solve the technical challenge of transaction latency. Because each Stacks block is anchored to a Bitcoin block through the [Proof-of-Transfer consensus mechanism](../understand-stacks/proof-of-transfer), Stacks is necessarily limited to the same block times as the Bitcoin network. Microblocks allow the Stacks blockchain to perform state transitions between anchor blocks. - -Microblocks are a powerful mechanism for developers to create performant, high quality applications on Stacks, while still inheriting the security of Bitcoin. - -## Transaction states - -The [Stacks block production model](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.) is described in SIP-001. The standard outlines the mechanism by which elected block leaders can produce blocks on the Stacks blockchain either by batching transactions or by streaming them. Microblocks are the product of the streaming model. - -If a block leader has elected to mine microblocks, the leader selects transactions from the mempool and package them into microblocks during the current epoch. Microblocks are blocks of transactions included by a miner after the previous anchor block has been mined, but before the next block is selected. Transactions included in microblocks are processed by the network: their results are known. - -Consider a transaction from the perspective of the number of block confirmations it has. A transaction included in a microblock might have the following example lifecycle: - -``` -Transaction 1 is broadcast to the mempool. It has 0 confirmations. -Transaction 1 is included in a microblock. It still has 0 confirmations, but the results of the transaction are known -Transaction 1 is included in the next anchor block. It has 1 confirmation. -The next Stacks block confirms the previous block. Transaction 1 has 2 confirmations. -The next Stacks block confirms the previous block. Transaction 1 has 3 confirmations. -... -``` - -Consider a similar transaction that is not included in a microblock: - -``` -Transaction 2 is broadcast to the mempool. It has 0 confirmations. -Transaction 2 is included in the next anchor block. It has 1 confirmation. -The next Stacks block confirms the previous block. Transaction 2 has 2 confirmations. -The next Stacks block confirms the previous block. Transaction 2 has 3 confirmations. -``` - -The lifecycles of the two transactions are similar, but the difference is pending state. Many Bitcoin wallets display 0-confirmation balances: your wallet balance with any mempool transactions already applied. This is useful because it tells you when you've sent a transaction or received one. With smart contracts, displaying pending state is not as straightforward, because smart contracts do not just transfer inputs to outputs, they may call other contracts, emit events, or perform other computations. A transaction processed in a microblock generates all that information. - -:::tip -If a transaction is dependent on a chain state that could by altered by previous transactions with serious -implications, you should carefully consider whether it should be performed using microblocks. -::: - -## Enabling microblocks - -Miners can choose to enable or disable microblocks in their mining configuration. As a best practice, miners should enable microblock mining. When an application or user submits a transaction, the transaction can include an argument that requires the transaction to be in a microblock, an anchor block, or in either. - -### Transactions - -Transactions include an option that controls if a miner should include them in microblocks or in anchor blocks. The anchor mode transaction option is an optional argument that controls whether a transaction must be included in an anchor block or a microblock, or is eligible for either. - -### Mining - -Stacks miners must enable microblocks in their miner configuration to implement the block streaming model. For more information, see [mining microblocks](../understand-stacks/mining#microblocks). - -## Developing with microblocks - -In most cases, information from transactions included in microblocks should be treated like information from any other block. Wallets and explorers should display the consequences of microblock transactions as the current state of the network. This state should be acknowledged as tentative. - -A microblock transaction can end up being reorganized in the next block rather than just being confirmed as-is. Because of this, your UI should communicate to users if the outputs of a transaction changed, or if the transaction's associated block changed. This is the same outcome as if a 1-block fork occurred. - -### Stacks.js libraries - -Stacks.js provides the [AnchorMode][] argument on transaction objects so that your application can set the microblocks preference for transactions. - -### API - -:::danger API support for microblocks is a work-in-progress. Review the [API documentation][microblocks_api] carefully to ensure that you are up-to-date on the latest implementation details for microblocks. ::: - -The Stacks Blockchain API exposes microblocks through several endpoints. Please review the [Stacks Blockchain API guide][] for more details. - -## Best practices - -Working with microblocks is a design decision that you must make for your own application. When working with microblocks, the following best practices are recommended. - -### Handling nonce - -Nonce handling with microblocks is challenging because the next account nonce must take into account any nonce values included in microblocks, which may not yet be included in an anchor block. The Stacks Blockchain API [provides an endpoint][] to retrieve the next nonce for a given principal. - -### Application design - -The state of microblock transactions should be carefully communicated to users. No transaction is final until it's included in an anchor block, and your application design should reflect this. - -The following guidelines are provided as an initial set of best practices for UI design when incorporating microblocks into your application. - -#### Explorers - -Display pending state, but warn that a transaction is still pending. Indicate visually that displayed balances depend on pending state. - -#### Wallets - -Display pending state, but warn that a transaction is still pending. Indicate visually that displayed balances depend on pending state. - -#### Exchanges - -Continue to count confirmations, microblocks should be considered pending. - -#### Applications - -Microblock communication is highly app-dependent. For some applications, displaying a pending or 0-confirmation transaction as confirmed may be fine. For example, storing data on the chain, or querying the BNS contract. For other applications, such as the transfer of real value, waiting for 3-confirmations would be prudent before displaying the state as confirmed. - -[AnchorMode]: https://stacks.js.org/enums/transactions.AnchorMode.html -[Stacks Blockchain API guide]: https://docs.hiro.so/get-started/stacks-blockchain-api#microblocks-support -[provides an endpoint]: https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling -[microblocks_api]: https://docs.hiro.so/api#tag/Microblocks diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/mining.md b/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/mining.md deleted file mode 100644 index fa1f56ed3f..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/mining.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Mining -description: A guide to mining on Stacks 2.0 -sidebar_position: 4 ---- - -## Introduction - -This guide highlights some technical details related to mining on the Stacks 2.0 network. - -For steps on how to setup your own miner please refer to [miner on tesnet](nodes-and-miners/miner-testnet.md) and [miner on mainnet](nodes-and-miners/miner-testnet.md). - -## Mining frequency - -A new Stacks block may be mined once per Bitcoin block. To be considered for mining a block, a miner must have a block commit included in a Bitcoin block. If a miner wishes to update their commitment after submission, they may use Bitcoin Replace-By-Fee. - -## Coinbase rewards - -Miners receive coinbase rewards for blocks they win. - -The reward amounts are: - -- 1000 STX per block are released in the first 4 years of mining -- 500 STX per block are released during the following 4 years -- 250 STX per block are released during the following 4 years -- 125 STX per block are released from then on indefinitely. - -These "halvings" are synchronized with Bitcoin halvings. - -![coinbase rewards](/img/pages/coinbase-rewards.png) - -## Transaction fees - -Miners receive Stacks fees for transactions mined in any block they produce. - -For transactions mined in microblocks, the miner that produces the microblock receives 40% of the fees, while the miner that confirms the microblock receives 60% of the fees. - -## Reward maturity - -Block rewards and transaction fees take 100 blocks on the Bitcoin blockchain to mature. After successfully mining a block your rewards appear in your Stacks account after ~24 hours. - -## Mining with proof-of-transfer - -Miners commit Bitcoin to **two** addresses in every leader block commit. The amount committed to each address must be the same. The addresses are chosen from the current reward set of stacking participants. Addresses are chosen using a verifiable-random-function, and determining the correct two addresses for a given block requires monitoring the Stacks chain. - -![mining with pox](/img/pages/mining-with-pox.png) - -## 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, 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. - -While there is no minimum BTC commitment enforced by the protocol, in practice, there's a floor constrained by [dust](https://unchained-capital.com/blog/dust-thermodynamics/)": basically, if the fees for a transaction exceed the value of the spent output, it's considered dust. How dust is [calculated](https://github.com/bitcoin/bitcoin/blob/master/src/policy/policy.cpp#L14) depends on a number of factors, we've found 5,500 satoshis to be good lower bound per [output](https://learnmeabitcoin.com/technical/output). Bitcoin transactions from Stacks miners contain two outputs (for Proof-of-Transfer), so a commitment of at least 11,000 satoshis / block is recommended. - -To calculate the amount of BTC to send miners should: - -- Guess the price BTC/STX for the next day (100 blocks later) -- Guess the total amount of BTCs committed by all miners - -## Microblocks - -The Stacks blockchain produces blocks at the same rate as the Bitcoin blockchain. In order to provide lower latency transactions, miners can opt to enable microblocks. Microblocks allow the current block leader to stream transactions and include their state transitions in the current epoch. - -If a block leader opts to produce microblocks, the next leader builds the chain tip off the last microblock that the current leader produces. - -The block streaming model is described in [SIP-001][]. - -[SIP-001]: https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md#operation-as-a-leader diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/network.md b/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/network.md deleted file mode 100644 index 6efcc385ec..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/network.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: Network -description: Guide to the Stacks 2.0 network -sidebar_position: 7 ---- - -## Tokens - -Stacks (STX) tokens are the native tokens on the Stacks 2.0 blockchain. The smallest fraction is one micro-STX. 1,000,000 micro-STX make one Stacks (STX). - -STX amounts should be stored as integers (8 bytes long), and represent the amount of micro-STX. For display purposes, micro-STX are divided by 1,000,000 (decimal precision of 6). - -## 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 in bytes. The fee rate is a market determined variable. For the [testnet](testnet), it is set to 1 micro-STX. - -Fee estimates can obtained through the [`GET /v2/fees/transfer`](https://docs.hiro.so/api#operation/get_fee_transfer) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/fees/transfer' -``` - -The API will respond with the fee rate (as integer): - -```json -1 -``` - -[The Stacks Transactions JS library](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) supports fee estimation for: - -- token transfers (`estimateTransfer`) -- contract deploys (`estimateContractDeploy`) -- non read-only contract calls (`estimateContractFunctionCall`) - -:::tip For an implementation using a different language than JavaScript, please review [this reference implementation](https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/src/builders.ts#L97). ::: - -## Nonces - -Every account carries a [nonce property](https://en.wikipedia.org/wiki/Cryptographic_nonce) that indicates the number of transactions processed for the given account. Nonces are one-time codes, starting at `0` for new accounts, and incremented by 1 on every transaction. - -Nonces are added to all transactions and help identify them in order to ensure transactions are processed in order and to avoid duplicated processing. - -:::tip -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 is constructed, the most recent nonce of the account needs to fetched and set. - -:::tip The API provides an endpoint to [simplify nonce handling](https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling). ::: - -## Confirmations - -The Stacks 2.0 network is anchored onto the bitcoin network. This allows transactions on Stacks to inherit the same finality and security of the Bitcoin blockchain. - -The time to mine a block, to confirm transactions, will eventually match the expected "block time" of the bitcoin network: 10 minutes. - -:::tip Transactions can also be mined in [microblocks](microblocks), reducing the latency significantly. ::: - -The block time is hardcoded and will change throughout the implementation phases of the [testnet](testnet). The current block time can be obtained through the [`GET /extended/v1/info/network_block_times`](https://docs.hiro.so/api#operation/get_network_block_times) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/info/network_block_times' -``` - -The API will respond with the block time (in seconds): - -```js -{ - "testnet": { - "target_block_time": 120 - }, - "mainnet": { - "target_block_time": 600 - } -} -``` - -## Read-only function calls - -Smart contracts can expose public function calls. For functions that make state modifications to the blockchain, transactions need to be generated and broadcasted. - -However, for read-only function calls, transactions are **not** required. Instead, these calls can be done using the [Stacks Blockchain API](https://docs.hiro.so/get-started/stacks-blockchain-api). - -:::tip -Read-only function calls do not require transaction fees -::: - -A read-only contract call can be done using the [`POST /v2/contracts/call-read///`](https://docs.hiro.so/api#operation/call_read_only_function) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl --location --request POST 'https://stacks-node-api.testnet.stacks.co/v2/contracts/call-read///' \ ---header 'Content-Type: application/json' \ ---data-raw '{ - "sender": ".", - "arguments": [, ...] -}' -``` - -Sample response for a successful call: - -```js -{ - "okay": true, - "result": "" -} -``` - -:::tip To set the function call arguments and read the result, [Clarity values](../write-smart-contracts/values) need to be serialized into a hexadecimal string. The [Stacks Transactions JS](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library supports these operations ::: - -## Querying - -Stacks 2.0 network details can be queried using the [Stacks Blockchain API](https://docs.hiro.so/get-started/stacks-blockchain-api). - -### Health check - -The [status checker](https://stacks-status.com/) is a service that provides a user interface to quickly review the health of the Stacks 2.0 blockchain. - -### Network info - -The network information can be obtained using the [`GET /v2/info`](https://docs.hiro.so/api#operation/get_core_api_info) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/info' -``` - -Sample response: - -```js -{ - "peer_version": 385875968, - "burn_consensus": "826401d65cf3671210a3fb135d827d549c0b4d37", - "burn_block_height": 1972, - "stable_burn_consensus": "e27ea23f199076bc41a729d76a813e125b725f64", - "stable_burn_block_height": 1971, - "server_version": "blockstack-core 0.0.1 => 23.0.0.0 (master:bdd042242+, release build, linux [x86_64]", - "network_id": 2147483648, - "parent_network_id": 3669344250, - "stacks_tip_height": 933, - "stacks_tip": "1f601823fbcc5b6b2215b2ff59d2818fba61ee4a3cea426d8bc3dbb268005d8f", - "stacks_tip_burn_block": "54c56a9685545c45accf42b5dcb2787c97eda8185a1c794daf9b5a59d4807abc", - "unanchored_tip": "71948ee211dac3b241eb65d881637f649d0d49ac08ee4a41c29217d3026d7aae", - "exit_at_block_height": 28160 -} -``` diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md b/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md deleted file mode 100644 index 4264616742..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Proof of Transfer -description: Understand the proof-of-transfer consensus mechanism -sidebar_position: 3 ---- - -## Overview - -Consensus algorithms for blockchains require compute or financial resources to secure the blockchain. The general practice of decentralized consensus is to make it practically infeasible for any single malicious actor to have enough computing power or ownership stake to attack the network. - -Popular consensus mechanisms in modern blockchains include proof-of-work, in which nodes dedicate computing resources, and proof-of-stake, in which nodes dedicate financial resources to secure the network. - -Proof-of-burn is a novel consensus mechanism where miners compete by ‘burning’ (destroying) a proof-of-work cryptocurrency as a proxy for computing resources. - -Proof-of-transfer (PoX) is an extension of the proof-of-burn mechanism. 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. - -![PoX mechanism](/img/pox-mechanism.png) - -This allows network participants to secure the PoX cryptocurrency network and earn a reward in the base cryptocurrency. Thus, proof-of-transfer blockchains are anchored on their chosen proof-of-work chain. Stacks uses [Bitcoin](#why-bitcoin) as its anchor chain. - -![PoX participants](/img/pox-participants.png) - -## Why Bitcoin? - -There are a number of reasons that Stacks chose Bitcoin as the blockchain to power consensus. It's the oldest blockchain protocol, having launched in 2009, and has become a recognized asset outside of the cryptocurrency community. BTC has held the highest market capitalization of any cryptocurrency for the past decade. - -Bitcoin champions simplicity and stability, and has stood the test of time. Influencing or attacking the network is infeasible or impractical for any potential hackers. It's one of the only cryptocurrencies to capture public attention. Bitcoin is a household name, and is recognized as an asset by governments, large corporations, and legacy banking institutions. Lastly, Bitcoin is largely considered a reliable store of value, and provides extensive infrastructure to support the proof-of-transfer consensus mechanism. - -SIP-001 provides a full [list of reasons why Bitcoin was chosen to secure Stacks](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md). - -![btc-stacks](/img/pox-why-bitcoin.png) - -## Blocks and microblocks - -The Stacks blockchain allows for increased transaction throughput using a mechanism called microblocks. Bitcoin and Stacks progress in lockstep, and their blocks are confirmed simultaneously. On Stacks, this is referred to as an ‘anchor block’. An entire block of Stacks transactions corresponds to a single Bitcoin transaction. This significantly improves cost/byte ratio for processing Stacks transactions. Because of simultaneous block production, Bitcoin acts as a rate-limiter for creating Stacks blocks, thereby preventing denial-of-service attacks on its peer network. - -However, in between Stacks anchor blocks settling on the Bitcoin blockchain, there are also a varying number of microblocks that allow rapid settlement of Stacks transactions with a high degree of confidence. This allows Stacks transaction throughput to scale independently of Bitcoin, while still periodically establishing finality with the Bitcoin chain. The Stacks blockchain adopts a block streaming model whereby each leader can adaptively select and package transactions into their block as they arrive in the mempool. Therefore when an anchor block is confirmed, all of the transactions in the parent microblock stream are packaged and processed. This is an unprecedented method for achieving scalability without creating a totally separate protocol from Bitcoin. - -![stx-microblock](/img/stx-microblocks.png) - -## Unlocking Bitcoin capital - -Stacks also unlocks the hundreds of billions in capital in Bitcoin, and gives Bitcoiners new opportunities to use and earn BTC. Stacks is a accompaniment to the Bitcoin ecosystem, and the two networks working in tandem enables totally novel ways of using BTC. The Stacks ecosystem makes interactive cryptocurrency applications available to Bitcoin holders. Additionally, by stacking STX tokens and participating in the PoX consensus mechanism, users have the opportunity to earn BTC while securing the Stacks chain. - -![Unlocking Bitcoin](/img/pox-unlocking-btc.png) - -## Clarity and the Bitcoin state - -Clarity smart contracts also have unique visibility into the state of the Bitcoin blockchain. This means that contract logic in a Clarity file has the ability to trigger when specific Bitcoin transactions are confirmed. Clarity smart contracts have a built in Simple Payment Verification (SPV) proofs for Bitcoin that make interacting with Bitcoin’s state much simpler for developers. Additionally, Clarity contracts can fork with the original Bitcoin chain. Therefore, in an edge case where Bitcoin forks, developers wouldn’t have to worry about adjusting the deployment of their smart contracts. - -## See also - -- [Read the full PoX whitepaper](https://community.stacks.org/pox) -- [Watch Executive Chair of Hiro Muneeb Ali and Evangelist Joe Bender give an overview of Stack's breakthrough PoX mining mechanism](https://www.youtube.com/watch?v=NY_eUrIcWOY) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md b/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md deleted file mode 100644 index 5f3863e8dd..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: Stacking -description: Introduction to the reward mechanism of Proof-of-Transfer -sidebar_position: 9 ---- - -## Introduction - -Stacking rewards Stacks (STX) token holders with bitcoin for providing a valuable service to the network by locking up their tokens for a certain time. - -![](/img/stacking.png) - -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. - -:::info The Stacking consensus algorithm is implemented as a smart contract, using [Clarity](../write-smart-contracts/). [Read more about the contract](../noteworthy-contracts/stacking-contract). ::: - -## Stacking flow - -The Stacking mechanism can be presented as a flow of actions: - -![Stacking flow](/img/stacking-illustration.png) - -1. Make API calls to get details about the upcoming reward cycle -2. For a specific Stacks account, confirm eligibility -3. Confirm the BTC reward address and the lockup duration -4. The transaction is broadcasted and the STX tokens are locked. This needs to happen before the prepare phase of the next reward cycle, the last 100 Bitcoin blocks of the ongoing reward phase -5. The Stacking mechanism executes reward cycles and sends out rewards to the set BTC reward address -6. During the lockup period, details about unlocking timing, rewards and more can be obtained -7. Once the lockup period is passed, the tokens are released and accessible again -8. Display reward history, including details like earnings for previous reward cycles - -:::info Keep in mind that the target duration for a reward cycles is ~2 weeks. This duration is based on the target block time of the network (10 minutes) and can be higher at times due to [confirmation time variances](https://www.blockchain.com/charts/median-confirmation-time) of the bitcoin network. ::: - -## Stacking delegation flow - -The Stacking flow is different for delegation use cases: - -![Delegated tacking flow](/img/stacking-delegation-illustration.png) - -- Before Stacking can be initiated for a token holder, the delegator needs to be granted permission to Stack on behalf of the account owner. The permission is restricted to the maximum amount the delegator is allowed to Stack. The maximum amount is not limited by the available funds and can be set much higher. An account can only be associated with one single delegator -- The account has to define the delegation relationship. They can optionally restrict the Bitcoin reward address that must be used for payouts, and the expiration burn block height for the permission, thus limiting the time a delegator has permission to Stack -- Delegators have to lock Stacks from different accounts ("pooling phase") until they reach the minimum amount of Stacks required to participate in Stacking -- Once a delegator locks enough STX tokens, they can finalize and commit their participation in the next reward cycle -- Certain delegation relationships may allow the STX holder to receive the payout directly from the miner (step 5/6) -- The termination of the delegation relationship can either happen automatically based on set expiration rules or by actively revoking delegation rights - -## PoX mining - -PoX mining is a modification of Proof-of-Burn (PoB) mining, where instead of sending the committed Bitcoin to a burn address, it's transferred to eligible STX holders that participate in the stacking protocol. - -:::note -A PoX miner can only receive newly minted STX tokens when they transfer Bitcoin to eligible owners of STX tokens -::: - -![Mining flow](/img/pox-mining-flow.png) - -Miners run Stacks nodes with mining enabled to participate in the PoX mechanism. The node implements the PoX mechanism, which ensures proper handling and incentives through four key phases: - -- Registration: miners register for a future election by sending consensus data to the network -- Commitment: registered miners transfer Bitcoin to participate in the election. Committed BTC are sent to a set participating STX token holders -- Election: a verifiable random function chooses one miner to write a new block on the Stacks blockchain -- Assembly: the elected miner writes the new block and collects rewards in form of new STX tokens - -## Token holder eligibility - -Stacks (STX) token holders don't automatically receive stacking rewards. Instead, they must: - -- Commit to participation before a reward cycle begins -- Commit the minimum amount of STX tokens to secure a reward slot, or pool with others to reach the minimum -- Lock up STX tokens for a specified period -- Provide a supported Bitcoin address to receive rewards (native segwit is not supported) - -The following diagram describes how the minimum STX tokens per slot is determined. More information on [dynamic minimums for stacking](https://stacking.club) is available at stacking.club. - -![Dynamic minimum for individual eligibility](/img/stacking-dynamic-minimum.png) - -Token holders have a variety of providers and tools to support their participation in Stacking. The Stacks website contains a [list of stacking providers and pools](https://stacks.org/stacking#earn). - -## Stacking in the PoX consensus algorithm - -Stacking is a built-in capability of PoX and occurs through a set of actions on the Stacks blockchain. The [full proof-of-transfer implementation details](https://github.com/stacks-network/stacks-blockchain/blob/develop/sip/sip-007-stacking-consensus.md) are in SIP-007. Below is a summary of the most relevant actions of the algorithm. - -![PoX cycles](/img/pox-cycles.png) - -- Stacking happens over reward cycles with a fixed length. In each reward cycle, a set of Bitcoin addresses associated with stacking participants receive BTC rewards -- A reward cycle consists of two phases: prepare and reward -- During the prepare phase, miners decide on an anchor block and a reward set. Mining any descendant forks of the anchor block requires transferring mining funds to the appropriate reward addresses. The reward set is the set of Bitcoin addresses which are eligible to receive funds in the reward cycle -- Miners register as leader candidates for a future election by sending a key transaction that burns cryptocurrency. The transaction also registers the leader's preferred chain tip (must be a descendant of the anchor block) and commitment of funds to 2 addresses from the reward set -- Token holders register for the next rewards cycle by broadcasting a signed message that locks up associated STX tokens for a protocol-specified lockup period, specifies a Bitcoin address to receive the funds, and votes on a Stacks chain tip -- Multiple leaders can commit to the same chain tip. The leader that wins the election and the peers who also burn for that leader collectively share the reward, proportional to how much each one burned -- Token holders' locked up tokens automatically unlock as soon as the lockup period finishes - -## Bitcoin address - -:::danger You must provide a BTC address in one of two formats: - -* [Legacy (P2PKH)](https://en.bitcoin.it/wiki/Transaction#Pay-to-PubkeyHash), which starts with `1`. - -* [Segregated Witness / Segwit (P2SH)](https://en.bitcoin.it/wiki/Pay_to_script_hash), which starts with `3`. The "Native Segwit" format (which starts with `bc1`), for example, is not supported. ::: - -The Stacking contract needs a special format for the Bitcoin address (the reward address). This is required to ensure that miners are able to correctly construct the Bitcoin transaction containing the reward address. - -The address must be specified in the following format using the Clarity language: - -```clar -;; a tuple of a version and hashbytes buffer -(pox-addr (tuple (version (buff 1)) (hashbytes (buff 20)))) -``` - -The `version` buffer must represent what kind of bitcoin address is being submitted. It can be one of the following: - -```js -SerializeP2PKH = 0x00, // hash160(public-key), same as bitcoin's p2pkh -SerializeP2SH = 0x01, // hash160(multisig-redeem-script), same as bitcoin's multisig p2sh -SerializeP2WPKH = 0x02, // hash160(segwit-program-00(p2pkh)), same as bitcoin's p2sh-p2wpkh -SerializeP2WSH = 0x03, // hash160(segwit-program-00(public-keys)), same as bitcoin's p2sh-p2wsh -``` - -The `hashbytes` are the 20 hash bytes of the bitcoin address. You can obtain that from a bitcoin library, for instance using [`bitcoinjs-lib`](https://github.com/bitcoinjs/bitcoinjs-lib): - -```js -const btc = require('bitcoinjs-lib'); -console.log( - '0x' + btc.address.fromBase58Check('1C56LYirKa3PFXFsvhSESgDy2acEHVAEt6').hash.toString('hex') -); -``` - -## Choosing the right Stacking strategy - -[Here](https://blog.stacks.co/stacking-strategy) is an interesting article that may help you choose the right Stacking stategy. - - -## Where to Stacks? - -You can Stack on your own, on a pool or on an exchange: -### Stacking on your own - -Stacking on your own is non-custodial. - -Stacking on your own requires a protocol minimum (amount changes but about 100,000 STX). - -[Hiro Wallet](https://www.hiro.so/wallet) allows stacking on your own. - -### Stacking on a pool - -Stacking on a pool allows Stacking without the requirement of the protocol minumum. - -Some available pools are: - -| Pool | Type | Pays rewards in | Fee | Minimum amount | -| --------------------------------------------------- | ------------- |:---------------:| --- |:--------------:| -| [Friedger's Pool](https://pool.friedger.de/) | Non custodial | STX or xBTC | No | 40 STX | -| [Planbetter](https://planbetter.org/) | Non custodial | BTC | 5% | 200 STX | -| [Stacked](https://staking.staked.us/stacks-staking) | Non custodial | BTC | | 100,000 STX | -| [Xverse](https://www.xverse.app/) | Non custodial | BTC | No | 100 STX | - -### Stacking on an exchange - -Stacking on an exchange is custodial, meaning you are trusting the exchange with your Stacks. - -Several exchanges allow Stacking directly on their sites. Examples are [Okcoin](https://www.okcoin.com) and [Binance](https://www.binance.com/en/staking) - -## Stacking statistics - -You can view all sorts of Stacking data and statistics on [Stacking Club](https://stacking.club) \ No newline at end of file diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md b/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md deleted file mode 100644 index d942d6af8f..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Stacks Blockchain API -description: Interacting with the Stacks 2.0 Blockchain via API ---- - -## Temporal page because of a Crowdin bug \ No newline at end of file diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md b/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md deleted file mode 100644 index e370129d1d..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Technical Specifications -description: Summary of technical specifications of Stacks 2.0 -sidebar_position: 10 ---- - -## Consensus - -- Proof of Transfer (PoX) as described in [SIP-007](https://github.com/stacksgov/sips/blob/main/sips/sip-007/sip-007-stacking-consensus.md) -- Network will transition to Proof of Burn (PoB) as described in [SIP-001](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md) after 10 years. [Learn more about Proof-of-Burn in SIP-001](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md). -- Threat model - - 51% of malicious Stacks mining power can perform a double-spend attack - - 51% of malicious Bitcoin mining power can reorg the Stacks chain -- Different actors and their roles - - Stacks Miners package transactions into blocks, mine them through a Bitcoin transaction, propagate them, and if they win the block race, append microblocks to their winning block until the next block is mined. The next block confirms the microblock stream. - - Stacks Holders may alter the calculation of block limits (subject to a miner veto) and may vote to disable Proof-of-Transfer rewards for a reward cycle. -- Transactions are considered final when the corresponding "block commit" transaction on Bitcoin is finalized. Typically this can by 3-6 confirmations. -- For more details, see [Proof of Transfer](proof-of-transfer). - -## Proof of Transfer Mining - -- Coinbase reward schedule: - - 1000 STX/block for first 4 years - - 500 STX/block for following 4 years - - 250 STX/block for subsequent 4 years - - 125 STX/block in perpetuity after that -- Coinbase rewards accumulate for "missed sortitions": If a Bitcoin block has no sortition (at height N), then any Stacks block mined in a subsequent sortition that builds off of any Stacks chain tip that existed at the penultimate sortition (at height N-1) may claim its coinbase. This encourages miners to keep mining even if Bitcoin fees are high. -- Initial mining bonus: This is a special case of the above to incentivize early miners. Coinbase for all burnchain blocks between the first burn block height (to be chosen by independent miners as part of the Stacks 2.0 launch) and the first sortition winner accumulate and are distributed to miners over a fixed window (to be determined). For instance, say burn block height is 10,000 and first sortition is at block 10500 and distribution window is 100 blocks, then coinbase for the first 500 blocks (10,500 - 10,000) will be distributed evenly to miners who win sortition over the subsequent 100 blocks. -- 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 at least 11,000 satoshis (5,500 sats / [UTXO output](https://learnmeabitcoin.com/technical/utxo)); 2 outputs / block) to avoid "dust." -- For more details, see [Mining](mining). - -## Stacking - -- Stacking works in 2 phases - 1. Prepare phase: In this phase an "anchor block" is chosen. The qualifying set of addresses ("reward set") is determined based on the snapshot of the chain at the anchor block. Length of prepare phase is 100 blocks. Stacking commitments need to be confirmed before this phase starts - 2. Reward phase: In this phase miner BTC commitments are distributed amongst the reward set. Reward cycle length is 2000 BTC blocks (~2 weeks). -- 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/stacksgov/sips/blob/main/sips/sip-007/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.stacks.co/references/stacking-contract#delegate-stx). -- Only two types of BTC reward addresses are supported: [Legacy (P2PKH)](https://en.bitcoin.it/wiki/Transaction#Pay-to-PubkeyHash) or [Segregated Witness / Segwit (P2SH)](https://en.bitcoin.it/wiki/Pay_to_script_hash). Native Segwit is not supported. -- Further reading: [Stacking](stacking) - -## Accounts and Addresses - -- Transactions in the Stacks blockchain originate from, are paid for by, and execute under the authority of accounts -- An account is fully specified by its address + nonce + assets -- 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 (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](accounts) - -## Transactions - -- Transaction 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 - 2. _paying account_ is the account that is billed by the leader for the cost of validating and executing the transaction - 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 -- Transactions can be batched or streamed into blocks. The behavior can be controlled by the anchor mode of a transaction. With streaming ([microblocks](microblocks)), a faster confirmation time is possible. -- 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. -- Mempool limit for concurrent pending transactions is 25 per account -- Pending mempool transactions will be garbage-collected [256 blocks after receipt](https://github.com/stacks-network/stacks-blockchain/blob/master/src/core/mempool.rs#L62). With 10 minutes target block time, this would equal ~42 hours -- [Learn more about transaction encoding in SIP-005](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md#transaction-encoding) -- [Transaction signing and verification are described in SIP-005](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md#transaction-signing-and-verifying) -- All transactions impacting account balance are atomic, a transfer operation can not increment one account’s balance without decrementing another’s. However, transactions that perform multiple account actions (for example, transferring from multiple accounts) may partially complete. -- Transactions can include a memo string (max 34 bytes) - -## See also - -- [Read the full Stacks 2.0: Apps and Smart Contracts for Bitcoin whitepaper](https://cloudflare-ipfs.com/ipfs/QmaGgiVHymeDjAc3aF1AwyhiFFwN97pme5m536cHT4FsAW). - -- [Watch Aaron Blankstein video on Stacks whitepater v2](https://www.youtube.com/watch?v=Wd-Bfe8Sn-Y). \ No newline at end of file diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md b/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md deleted file mode 100644 index 59934a5bde..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Testnet -description: Test your smart contracts and apps -sidebar_position: 2 ---- - -## About testnet - -The testnet is a separate blockchain from the Stacks mainnet analogous to a staging environment. It's a network used by developers to test their apps, smart contracts, or changes to the protocol in a production-like environment. It produces blocks at roughly the same rate as mainnet; about 1 block every 10 minutes on average. The Stacks testnet is rarely reset. - -### Faucet - -The testnet faucet provides you with free Stacks Token (STX) to test with. These are not the same as STX on mainnet and have no value. You can get STX from the faucet on the [Stacks Explorer Sandbox](https://explorer.stacks.co/sandbox/faucet?chain=testnet), or using the [API](https://docs.hiro.so/api#tag/Faucets). - -To get STX tokens from within the Explorer Sandbox, navigate to the "Faucet" tab on the left and click "Request STX" button. - -![](/img/stx_faucet.png) - -You can also try out [Stacking](stacking) by clicking on `I want to stack`. - -:::note -The Explorer Sandbox requires you to login with a Stacks wallet -::: - -### Testnet API - -The hosted Stacks Blockchain API for the testnet is available at this base URL: - -```shell -https://stacks-node-api.testnet.stacks.co/ -``` - -![](/img/api_testnet_status.png) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md b/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md deleted file mode 100644 index 2ff6072384..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Transactions -description: Guide to Stacks 2.0 transactions -sidebar_position: 6 ---- - -## Introduction - -Transactions are the fundamental unit of execution in the Stacks blockchain. Each transaction is originated from a [Stacks 2.0 account](accounts), and is retained in the Stacks blockchain history for eternity. This guide helps you understand Stacks 2.0 transactions. - -## Lifecycle - -Transactions go through phases before being finally confirmed, and available for all, on the Stacks 2.0 network. - -![Transaction lifecycle](/img/tx-lifecycle.png) - -- **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/en/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. - -:::note A transaction can have one of three states once it is registered: `pending`, `success`, or `failed`. ::: - -## Types - -The Stacks 2.0 supports a set of different transaction types: - -| **Type** | **Value** | **Description** | -| ----------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Coinbase | `coinbase` | The first transaction in a new block (an entity holding several transactions). Used to register for block rewards. These are not manually generated and broadcasted like other types of transactions. | -| Token transfer | `token_transfer` | Asset transfer from a sender to a recipient | -| Contract deploy | `smart_contract` | Contract instantiation | -| Contract call | `contract_call` | Contract call for a public, non read-only function | -| Poison Microblock | `poison_microblock` | Punish leaders who intentionally equivocate about the microblocks they package | - -A sample of each transaction type can be found in the [Stacks Blockchain API response definition for transactions](https://docs.hiro.so/api#operation/get_transaction_by_id). - -:::caution Read-only contract call calls do **not** require transactions. Read more about it in the [network guide](network#read-only-function-calls). ::: diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md b/i18n/hi/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md deleted file mode 100644 index fd45c80583..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Clarity Language -description: Overview of the Clarity language constructs -sidebar_label: Clarity Language -tags: - - clarity ---- - -## Clarity Type System - -The Clarity language uses a strong static type system. Function arguments and database schemas require specified types, and use of types is checked during contract launch. The type system does _not_ have a universal super type. - -## Public Functions - -Functions specified via `define-public` statements are _public_ functions and these are the only types of functions which may be called directly through signed blockchain transactions. In addition to being callable directly from a transaction (see the Stacks wire formats for more details on Stacks transactions), public functions may be called by other smart contracts. - -Public functions _must_ return a `(response ...)` type. This is used by Clarity to determine whether or not to materialize any changes from the execution of the function. If a function returns an `(err ...)` type, any mutations on the blockchain state from executing the function (and any function that it called during execution) will be aborted. - -In addition to functions defined via `define-public`, contracts may expose read-only functions. These functions, defined via `define-read-only`, are callable by other smart contracts, and may be queryable via public blockchain explorers. These functions _may not_ mutate any blockchain state. Unlike normal public functions, read-only functions may return any type. - -## Contract Calls - -A smart contract may call functions from other smart contracts using a `(contract-call?)` function. - -This function returns a response type result -- the return value of the called smart contract function. - -We distinguish 2 different types of `contract-call?`: - -### Static dispatch - -The callee is a known, invariant contract available on-chain when the caller contract is deployed. In this case, the callee's principal is provided as the first argument, followed by the name of the method and its arguments: - -```clarity -(contract-call? - .registrar - register-name - name-to-register) -``` - -### Dynamic dispatch - -The callee is passed as an argument, and typed as a trait reference (``). - -```clarity -(define-public (swap (token-a ) - (amount-a uint) - (owner-a principal) - (token-b ) - (amount-b uint) - (owner-b principal))) - (begin - (unwrap! (contract-call? token-a transfer-from? owner-a owner-b amount-a)) - (unwrap! (contract-call? token-b transfer-from? owner-b owner-a amount-b)))) -``` - -Traits can either be locally defined: - -```clarity -(define-trait can-transfer-tokens ( - (transfer-from? (principal principal uint) (response uint))) -``` - -Or imported from an existing contract: - -```clarity -(use-trait can-transfer-tokens - .contract-defining-trait.can-transfer-tokens) -``` - -Looking at trait conformance, callee contracts have two different paths. They can either be "compatible" with a trait by defining methods matching some of the methods defined in a trait, or explicitly declare conformance using the `impl-trait` statement: - -```clarity -(impl-trait .contract-defining-trait.can-transfer-tokens) -``` - -Explicit conformance should be prefered when adequate. It acts as a safeguard by helping the static analysis system to detect deviations in method signatures before contract deployment. - -The following limitations are imposed on contract calls: - -1. On static dispatches, callee smart contracts _must_ exist at the time of creation. -2. No cycles may exist in the call graph of a smart contract. This prevents recursion (and re-entrancy bugs). Such structures can be detected with static analysis of the call graph, and will be rejected by the network. -3. `contract-call?` are for inter-contract calls only. Attempts to execute when the caller is also the callee will abort the transaction. diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md b/i18n/hi/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md deleted file mode 100644 index 4605b2f4c9..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md +++ /dev/null @@ -1,1385 +0,0 @@ ---- -title: Functions -description: See a detailed list of all functions for the Clarity language. -tags: - - clarity ---- - -## Functions - -Detailed list of all functions for the Clarity language. - -### + (add) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(+ i1 i2...)` -#### description: -Adds a variable number of integer inputs and returns the result. In the event of an _overflow_, throws a runtime error. -#### example: -```clarity -(+ 1 2 3) ;; Returns 6 -(+ 2 3) ;; Returns 5 -(+ 1 2 3 4) ;; Returns 10 -(+ 9 -3) ;; Returns 6 -(+ -3 -2) ;; Returns -5 -``` - -### - (subtract) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(- i1 i2...)` -#### description: -Subtracts a variable number of integer inputs and returns the result. In the event of an _underflow_, throws a runtime error. -#### example: -```clarity -(- 2 1 1) ;; Returns 0 -(- 0 3) ;; Returns -3 -(- 5 -3) ;; Returns 8 -(- -4 -5) ;; Returns 1 -``` - -### * (multiply) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(* i1 i2...)` -#### description: -Multiplies a variable number of integer inputs and returns the result. In the event of an _overflow_, throws a runtime error. -#### example: -```clarity -(* 2 3) ;; Returns 6 -(* 5 2) ;; Returns 10 -(* 2 2 2) ;; Returns 8 -(* 3 -2) ;; Returns -6 -(* -1 -2) ;; Returns 2 -``` - -### / (divide) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(/ i1 i2...)` -#### description: -Divides a variable number of integer inputs and returns the _integer part_ of the result. In the event of _division by zero_, throws a runtime error. - -#### example: -```clarity -(/ 2 3) ;; Returns 0 -(/ 5 2) ;; Returns 2 -(/ 4 2 2) ;; Returns 1 -(/ -10 2) ;; Returns -5 -(/ -8 -2) ;; Returns 4 -(/ -9 4) ;; Returns -2 -``` - -### >= (greater than or equal) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(>= i1 i2)` -#### description: -Compares two integers, returning `true` if `i1` is greater than or equal to `i2` and `false` otherwise. -#### example: -```clarity -(>= 1 1) ;; Returns true -(>= 5 2) ;; Returns true -``` - -### <= (less than or equal) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(<= i1 i2)` -#### description: -Compares two integers, returning true if `i1` is less than or equal to `i2` and `false` otherwise. -#### example: -```clarity -(<= 1 1) ;; Returns true -(<= 5 2) ;; Returns false -``` - -### < (less than) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(< i1 i2)` -#### description: -Compares two integers, returning `true` if `i1` is less than `i2` and `false` otherwise. -#### example: -```clarity -(< 1 2) ;; Returns true -(< 5 2) ;; Returns false -``` - -### > (greater than) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(> i1 i2)` -#### description: -Compares two integers, returning `true` if `i1` is greater than `i2` and false otherwise. -#### example: -```clarity -(> 1 2) ;; Returns false -(> 5 2) ;; Returns true -``` - -### to-int -#### input: `uint` -#### output: `int` -#### signature: `(to-int u)` -#### description: -Tries to convert the `uint` argument to an `int`. Will cause a runtime error and abort if the supplied argument is >= `pow(2, 127)`` -#### example: -```clarity -(to-int u238) ;; Returns 238 -``` - -### to-uint -#### input: `int` -#### output: `uint` -#### signature: `(to-uint i)` -#### description: -Tries to convert the `int` argument to a `uint`. Will cause a runtime error and abort if the supplied argument is negative. -#### example: -```clarity -(to-uint 238) ;; Returns u238 -``` - -### mod -#### input: `int, int | uint, uint` -#### output: `int | uint` -#### signature: `(mod i1 i2)` -#### description: -Returns the integer remainder from integer dividing `i1` by `i2`. In the event of a division by zero, throws a runtime error. -#### example: -```clarity -(mod 2 3) ;; Returns 2 -(mod 5 2) ;; Returns 1 -(mod 7 1) ;; Returns 0 -``` - -### pow -#### input: `int, int | uint, uint` -#### output: `int | uint` -#### signature: `(pow i1 i2)` -#### description: -Returns the result of raising `i1` to the power of `i2`. In the event of an _overflow_, throws a runtime error. -#### example: -```clarity -(pow 2 3) ;; Returns 8 -(pow 2 2) ;; Returns 4 -(pow 7 1) ;; Returns 7 -``` - -### sqrti -#### input: `int | uint` -#### output: `int | uint` -#### signature: `(sqrti n)` -#### description: -Returns the largest integer that is less than or equal to the square root of `n`. Fails on a negative numbers. -#### example: -```clarity -(sqrti u11) ;; Returns u3 -(sqrti 1000000) ;; Returns 1000 -(sqrti u1) ;; Returns u1 -(sqrti 0) ;; Returns 0 -``` - -### log2 -#### input: `int | uint` -#### output: `int | uint` -#### signature: `(log2 n)` -#### description: -Returns the _integer part_ of the power to which the number 2 must be raised to obtain the value `n`. Fails on zero or a negative number. -#### example: -```clarity -(log2 u8) ;; Returns u3 -(log2 8) ;; Returns 3 -(log2 u1) ;; Returns u0 -(log2 1000) ;; Returns 9 -``` - -### xor -#### input: `int, int | uint, uint` -#### output: `int | uint` -#### signature: `(xor i1 i2)` -#### description: -Returns the result of bitwise exclusive or'ing `i1` with `i2`. -#### example: -```clarity -(xor 1 2) ;; Returns 3 -(xor 120 280) ;; Returns 352 -``` - -### and -#### input: `bool, ...` -#### output: `bool` -#### signature: `(and b1 b2 ...)` -#### description: -Returns `true` if all boolean inputs are `true`. Importantly, the supplied arguments are evaluated in-order and lazily. Lazy evaluation means that if one of the arguments returns `false`, the function short-circuits, and no subsequent arguments are evaluated. -#### example: -```clarity -(and true false) ;; Returns false -(and (is-eq (+ 1 2) 1) (is-eq 4 4)) ;; Returns false -(and (is-eq (+ 1 2) 3) (is-eq 4 4)) ;; Returns true -``` - -### or -#### input: `bool, ...` -#### output: `bool` -#### signature: `(or b1 b2 ...)` -#### description: -Returns `true` if any boolean inputs are `true`. Importantly, the supplied arguments are evaluated in-order and lazily. Lazy evaluation means that if one of the arguments returns `true`, the function short-circuits, and no subsequent arguments are evaluated. -#### example: -```clarity -(or true false) ;; Returns true -(or (is-eq (+ 1 2) 1) (is-eq 4 4)) ;; Returns true -(or (is-eq (+ 1 2) 1) (is-eq 3 4)) ;; Returns false -(or (is-eq (+ 1 2) 3) (is-eq 4 4)) ;; Returns true -``` - -### not -#### input: `bool` -#### output: `bool` -#### signature: `(not b1)` -#### description: -Returns the inverse of the boolean input. -#### example: -```clarity -(not true) ;; Returns false -(not (is-eq 1 2)) ;; Returns true -``` - -### is-eq -#### input: `A, A, ...` -#### output: `bool` -#### signature: `(is-eq v1 v2...)` -#### description: -Compares the inputted values, returning `true` if they are all equal. Note that _unlike_ the `(and ...)` function, `(is-eq ...)` will _not_ short-circuit. All values supplied to is-eq _must_ be the same type. -#### example: -```clarity -(is-eq 1 1) ;; Returns true -(is-eq true false) ;; Returns false -(is-eq \"abc\" 234 234) ;; Throws type error -``` - -### if -#### input: `bool, A, A` -#### output: `A` -#### signature: `(if bool1 expr1 expr2)` -#### description: -The `if` function admits a boolean argument and two expressions which must return the same type. In the case that the boolean input is `true`, the `if` function evaluates and returns `expr1`. If the boolean input is `false`, the `if` function evaluates and returns `expr2`. -#### example: -```clarity -(if true 1 2) ;; Returns 1 -(if (> 1 2) 1 2) ;; Returns 2 -``` - -### let -#### input: `((name1 AnyType) (name2 AnyType) ...), AnyType, ... A` -#### output: `A` -#### signature: `(let ((name1 expr1) (name2 expr2) ...) expr-body1 expr-body2 ... expr-body-last)` -#### description: -The `let` function accepts a list of `variable name` and `expression` pairs, evaluating each expression and _binding_ it to the corresponding variable name. `let` bindings are sequential: when a `let` binding is evaluated, it may refer to prior binding. The _context_ created by this set of bindings is used for evaluating its body expressions. The let expression returns the value of the last such body expression. Note: intermediary statements returning a response type must be checked` -#### example: -```clarity -(let ((a 2) (b (+ 5 6 7))) (print a) (print b) (+ a b)) ;; Returns 20 -(let ((a 5) (c (+ a 1)) (d (+ c 1)) (b (+ a c d))) (print a) (print b) (+ a b)) ;; Returns 23 -``` - -### map -#### input: `Function(A, B, ..., N) -> X, sequence_A, sequence_B, ..., sequence_N` -#### output: `(list X)` -#### signature: `(map func sequence_A sequence_B ... sequence_N)` -#### description: -The `map` function applies the function `func` to each corresponding element of the input sequences, and outputs a _list_ of the same type containing the outputs from those function applications. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. Also, note that, no matter what kind of sequences the inputs are, the output is always a list. -#### example: -```clarity -(map not (list true false true false)) ;; Returns (false true false true) -(map + (list 1 2 3) (list 1 2 3) (list 1 2 3)) ;; Returns (3 6 9) -(define-private (a-or-b (char (string-utf8 1))) (if (is-eq char u\"a\") u\"a\" u\"b\")) -(map a-or-b u\"aca\") ;; Returns (u\"a\" u\"b\" u\"a\") -(define-private (zero-or-one (char (buff 1))) (if (is-eq char 0x00) 0x00 0x01)) -(map zero-or-one 0x000102) ;; Returns (0x00 0x01 0x01) -``` - -### fold -#### input: `Function(A, B) -> B, sequence_A, B` -#### output: `B` -#### signature: `(fold func sequence_A initial_B)` -#### description: -The `fold` function condenses `sequence_A` into a value of type `B` by recursively applies the function `func` to each element of the input sequence _and_ the output of a previous application of `func`. - -`fold` uses `initial_B` in the initial application of `func`, along with the first element of `sequence_A`. The resulting value of type `B` is used for the next application of `func`, along with the next element of `sequence_A` and so on. `fold` returns the last value of type `B` returned by these successive applications `func`. - -Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. - -#### example: -```clarity -(fold * (list 2 2 2) 1) ;; Returns 8 -(fold * (list 2 2 2) 0) ;; Returns 0 -;; calculates (- 11 (- 7 (- 3 2))) -(fold - (list 3 7 11) 2) ;; Returns 5 -(define-private (concat-string (a (string-ascii 20)) (b (string-ascii 20))) (unwrap-panic (as-max-len? (concat a b) u20))) -(fold concat-string \"cdef\" \"ab\") ;; Returns \"fedcab\" -(fold concat-string (list \"cd\" \"ef\") \"ab\") ;; Returns \"efcdab\" -(define-private (concat-buff (a (buff 20)) (b (buff 20))) (unwrap-panic (as-max-len? (concat a b) u20))) -(fold concat-buff 0x03040506 0x0102) ;; Returns 0x060504030102 -``` - -### append -#### input: `list A, A` -#### output: `list` -#### signature: `(append (list 1 2 3 4) 5)` -#### description: -The `append` function takes a list and another value with the same entry type, and outputs a list of the same type with max_len += 1. -#### example: -```clarity -(append (list 1 2 3 4) 5) ;; Returns (1 2 3 4 5) -``` - -### concat -#### input: `sequence_A, sequence_A` -#### output: `sequence_A` -#### signature: `(concat sequence1 sequence2)` -#### description: -The `concat` function takes two sequences of the same type, and returns a concatenated sequence of the same type, with the resulting sequence_len = sequence1_len + sequence2_len. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`. - -#### example: -```clarity -(concat (list 1 2) (list 3 4)) ;; Returns (1 2 3 4) -(concat \"hello \" \"world\") ;; Returns \"hello world\" -(concat 0x0102 0x0304) ;; Returns 0x01020304 -``` - -### as-max-len? -#### input: `sequence_A, uint` -#### output: `sequence_A` -#### signature: `(as-max-len? sequence max_length)` -#### description: -The `as-max-len?` function takes a sequence argument and a uint-valued, literal length argument. The function returns an optional type. If the input sequence length is less than or equal to the supplied max_length, this returns `(some sequence)`, otherwise it returns `none`. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`. ` -#### example: -```clarity -(as-max-len? (list 2 2 2) u3) ;; Returns (some (2 2 2)) -(as-max-len? (list 1 2 3) u2) ;; Returns none -(as-max-len? \"hello\" u10) ;; Returns (some \"hello\") -(as-max-len? 0x010203 u10) ;; Returns (some 0x010203) -``` - -### len -#### input: `sequence_A` -#### output: `uint` -#### signature: `(len sequence)` -#### description: -The `len` function returns the length of a given sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`. ` -#### example: -```clarity -(len \"blockstack\") ;; Returns u10 -(len (list 1 2 3 4 5)) ;; Returns u5 -(len 0x010203) ;; Returns u3 -``` - -### element-at -#### input: `sequence_A, uint` -#### output: `(optional A)` -#### signature: `(element-at sequence index)` -#### description: -The `element-at` function returns the element at `index` in the provided sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. ` -#### example: -```clarity -(element-at \"blockstack\" u5) ;; Returns (some \"s\") -(element-at (list 1 2 3 4 5) u5) ;; Returns none -(element-at (list 1 2 3 4 5) (+ u1 u2)) ;; Returns (some 4) -(element-at \"abcd\" u1) ;; Returns (some \"b\") -(element-at 0xfb01 u1) ;; Returns (some 0x01) -``` - -### index-of -#### input: `sequence_A, A` -#### output: `(optional uint)` -#### signature: `(index-of sequence item)` -#### description: -The `index-of` function returns the first index at which `item` can be found, using `is-eq` checks, in the provided sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. If the target item is not found in the sequence (or if an empty string or buffer is supplied), this function returns `none`. -#### example: -```clarity -(index-of \"blockstack\" \"b\") ;; Returns (some u0) -(index-of \"blockstack\" \"k\") ;; Returns (some u4) -(index-of \"blockstack\" \"\") ;; Returns none -(index-of (list 1 2 3 4 5) 6) ;; Returns none -(index-of 0xfb01 0x01) ;; Returns (some u1) -``` - -### list -#### input: `A, ...` -#### output: `(list A)` -#### signature: `(list expr1 expr2 expr3 ...)` -#### description: -The `list` function constructs a list composed of the inputted values. Each supplied value must be of the same type. -#### example: -```clarity -(list (+ 1 2) 4 5) ;; Returns (3 4 5) -``` - -### var-get -#### input: `VarName` -#### output: `A` -#### signature: `(var-get var-name)` -#### description: -The `var-get` function looks up and returns an entry from a contract's data map. The value is looked up using `var-name`. -#### example: -```clarity -(define-data-var cursor int 6) -(var-get cursor) ;; Returns 6 -``` - -### var-set -#### input: `VarName, AnyType` -#### output: `bool` -#### signature: `(var-set var-name expr1)` -#### description: -The `var-set` function sets the value associated with the input variable to the inputted value. The function always returns `true`. -#### example: -```clarity -(define-data-var cursor int 6) -(var-get cursor) ;; Returns 6 -(var-set cursor (+ (var-get cursor) 1)) ;; Returns true -(var-get cursor) ;; Returns 7 -``` - -### map-get? -#### input: `MapName, tuple` -#### output: `(optional (tuple))` -#### signature: `(map-get? map-name key-tuple)` -#### description: -The `map-get?` function looks up and returns an entry from a contract's data map. The value is looked up using `key-tuple`. If there is no value associated with that key in the data map, the function returns a `none` option. Otherwise, it returns `(some value)`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(map-get? names-map (tuple (name \"blockstack\"))) ;; Returns (some (tuple (id 1337))) -(map-get? names-map { name: \"blockstack\" }) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-set -#### input: `MapName, tuple_A, tuple_B` -#### output: `bool` -#### signature: `(map-set map-name key-tuple value-tuple)` -#### description: -The `map-set` function sets the value associated with the input key to the inputted value. This function performs a _blind_ update; whether or not a value is already associated with the key, the function overwrites that existing association. - -Note: the `value-tuple` requires 1 additional byte for storage in the materialized blockchain state, and therefore the maximum size of a value that may be inserted into a map is MAX_CLARITY_VALUE - 1. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-set names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-insert -#### input: `MapName, tuple_A, tuple_B` -#### output: `bool` -#### signature: `(map-insert map-name key-tuple value-tuple)` -#### description: -The `map-insert` function sets the value associated with the input key to the inputted value if and only if there is not already a value associated with the key in the map. If an insert occurs, the function returns `true`. If a value already existed for this key in the data map, the function returns `false`. - -Note: the `value-tuple` requires 1 additional byte for storage in the materialized blockchain state, and therefore the maximum size of a value that may be inserted into a map is MAX_CLARITY_VALUE - 1. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns false -(map-insert names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-delete -#### input: `MapName, tuple` -#### output: `bool` -#### signature: `(map-delete map-name key-tuple)` -#### description: -The `map-delete` function removes the value associated with the input key for the given map. If an item exists and is removed, the function returns `true`. If a value did not exist for this key in the data map, the function returns `false`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-delete names-map { name: \"blockstack\" }) ;; Returns true -(map-delete names-map { name: \"blockstack\" }) ;; Returns false -(map-delete names-map (tuple (name \"blockstack\"))) ;; Same command, using a shorthand for constructing the tuple -``` - -### tuple -#### input: `(key-name A), (key-name-2 B), ...` -#### output: `(tuple (key-name A) (key-name-2 B) ...)` -#### signature: `(tuple (key0 expr0) (key1 expr1) ...)` -#### description: -The `tuple` special form constructs a typed tuple from the supplied key and expression pairs. A `get` function can use typed tuples as input to select specific values from a given tuple. Key names may not appear multiple times in the same tuple definition. Supplied expressions are evaluated and associated with the expressions' paired key name. - -There is a shorthand using curly brackets of the form {key0: expr0, key1: expr, ...}` -#### example: -```clarity -(tuple (name \"blockstack\") (id 1337)) ;; using tuple -{name: \"blockstack\", id: 1337} ;; using curly brackets -``` - -### get -#### input: `KeyName, (tuple) | (optional (tuple))` -#### output: `A` -#### signature: `(get key-name tuple)` -#### description: -The `get` function fetches the value associated with a given key from the supplied typed tuple. If an `Optional` value is supplied as the inputted tuple, `get` returns an `Optional` type of the specified key in the tuple. If the supplied option is a `(none)` option, get returns `(none)`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(get id (tuple (name \"blockstack\") (id 1337))) ;; Returns 1337 -(get id (map-get? names-map (tuple (name \"blockstack\")))) ;; Returns (some 1337) -(get id (map-get? names-map (tuple (name \"non-existent\")))) ;; Returns none -``` - -### merge -#### input: `tuple, tuple` -#### output: `tuple` -#### signature: `(merge tuple { key1: val1 })` -#### description: -The `merge` function returns a new tuple with the combined fields, without mutating the supplied tuples. -#### example: -```clarity -(define-map users { id: int } { name: (string-ascii 12), address: (optional principal) }) -(map-insert users { id: 1337 } { name: \"john\", address: none }) ;; Returns true -(let ((user (unwrap-panic (map-get? users { id: 1337 })))) -(merge user { address: (some 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) })) ;; Returns (tuple (address (some SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF)) (name \"john\")) -``` - -### begin -#### input: `AnyType, ... A` -#### output: `A` -#### signature: `(begin expr1 expr2 expr3 ... expr-last)` -#### description: -The `begin` function evaluates each of its input expressions, returning the return value of the last such expression. Note: intermediary statements returning a response type must be checked. -#### example: -```clarity -(begin (+ 1 2) 4 5) ;; Returns 5 -``` - -### hash160 -#### input: `buff|uint|int` -#### output: `(buff 20)` -#### signature: `(hash160 value)` -#### description: -The `hash160` function computes `RIPEMD160(SHA256(x))` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(hash160 0) ;; Returns 0xe4352f72356db555721651aa612e00379167b30f -``` - -### sha256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(sha256 value)` -#### description: -The `sha256` function computes `SHA256(x)` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(sha256 0) ;; Returns 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb -``` - -### sha512 -#### input: `buff|uint|int` -#### output: `(buff 64)` -#### signature: `(sha512 value)` -#### description: -The `sha512` function computes `SHA512(x)` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(sha512 1) ;; Returns 0x6fcee9a7b7a7b821d241c03c82377928bc6882e7a08c78a4221199bfa220cdc55212273018ee613317c8293bb8d1ce08d1e017508e94e06ab85a734c99c7cc34 -``` - -### sha512/256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(sha512/256 value)` -#### description: -The `sha512/256` function computes `SHA512/256(x)` (the SHA512 algorithm with the 512/256 initialization vector, truncated to 256 bits) of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(sha512/256 1) ;; Returns 0x515a7e92e7c60522db968d81ff70b80818fc17aeabbec36baf0dda2812e94a86 -``` - -### keccak256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(keccak256 value)` -#### description: -The `keccak256` function computes `KECCAK256(value)` of the inputted value. Note that this differs from the `NIST SHA-3` (that is, FIPS 202) standard. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(keccak256 0) ;; Returns 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4 -``` - -### secp256k1-recover? -#### input: `(buff 32), (buff 65)` -#### output: `(response (buff 33) uint)` -#### signature: `(secp256k1-recover? message-hash signature)` -#### description: -The `secp256k1-recover?` function recovers the public key used to sign the message which sha256 is `message-hash` with the provided `signature`. If the signature does not match, it will return the error code `(err u1).`. If the signature is invalid, it will return the error code `(err u2).`. The signature includes 64 bytes plus an additional recovery id (00..03) for a total of 65 bytes. -#### example: -```clarity -(secp256k1-recover? 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a1301) - ;; Returns (ok 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) - ``` - -### secp256k1-verify -#### input: `(buff 32), (buff 64) | (buff 65), (buff 33)` -#### output: `bool` -#### signature: `(secp256k1-verify message-hash signature public-key)` -#### description: -The `secp256k1-verify` function verifies that the provided signature of the message-hash was signed with the private key that generated the public key. The `message-hash` is the `sha256` of the message. The signature includes 64 bytes plus an optional additional recovery id (00..03) for a total of 64 or 65 bytes. -#### example: -```clarity -(secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a1301 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns true -(secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a13 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns true -(secp256k1-verify 0x0000000000000000000000000000000000000000000000000000000000000000 - 0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns false - ``` - -### print -#### input: `A` -#### output: `A` -#### signature: `(print expr)` -#### description: -The `print` function evaluates and returns its input expression. On Stacks Core nodes configured for development (as opposed to production mining nodes), this function prints the resulting value to `STDOUT` (standard output). -#### example: -```clarity -(print (+ 1 2 3)) ;; Returns 6 -``` - -### contract-call? -#### input: `ContractName, PublicFunctionName, Arg0, ...` -#### output: `(response A B)` -#### signature: `(contract-call? .contract-name function-name arg0 arg1 ...)` -#### description: -The `contract-call?` function executes the given public function of the given contract. You _may not_ use this function to call a public function defined in the current contract. If the public function returns _err_, any database changes resulting from calling `contract-call?` are aborted. If the function returns _ok_, database changes occurred. -#### example: -```clarity - -;; instantiate the sample-contracts/tokens.clar contract first! -(as-contract (contract-call? .tokens mint! u19)) ;; Returns (ok u19) -``` - -### as-contract -#### input: `A` -#### output: `A` -#### signature: `(as-contract expr)` -#### description: -The `as-contract` function switches the current context's `tx-sender` value to the _contract's_ principal and executes `expr` with that context. It returns the resulting value of `expr`. -#### example: -```clarity -(as-contract tx-sender) ;; Returns S1G2081040G2081040G2081040G208105NK8PE5.docs-test -``` - -### contract-of -#### input: `Trait` -#### output: `principal` -#### signature: `(contract-of .contract-name)` -#### description: -The `contract-of` function returns the principal of the contract implementing the trait. -#### example: -```clarity -(use-trait token-a-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) -(define-public (forward-get-balance (user principal) (contract )) - (begin - (ok (contract-of contract)))) ;; returns the principal of the contract implementing -``` - -### principal-of? -#### input: `(buff 33)` -#### output: `(response principal uint)` -#### signature: `(principal-of? public-key)` -#### description: -The `principal-of?` function returns the principal derived from the provided public key. If the `public-key` is invalid, it will return the error code `(err u1).`. ` -#### example: -```clarity -(principal-of? 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns (ok ST1AW6EKPGT61SQ9FNVDS17RKNWT8ZP582VF9HSCP) -``` - -### at-block -#### input: `(buff 32), A` -#### output: `A` -#### signature: `(at-block id-block-hash expr)` -#### description: -The `at-block` function evaluates the expression `expr` _as if_ it were evaluated at the end of the block indicated by the _block-hash_ argument. The `expr` closure must be read-only. - -Note: The block identifying hash must be a hash returned by the `id-header-hash` block information property. This hash uniquely identifies Stacks blocks and is unique across Stacks forks. While the hash returned by `header-hash` is unique within the context of a single fork, it is not unique across Stacks forks. - -The function returns the result of evaluating `expr`. - -#### example: -```clarity -(define-data-var data int 1) -(at-block 0x0000000000000000000000000000000000000000000000000000000000000000 block-height) ;; Returns u0 -(at-block (get-block-info? id-header-hash 0) (var-get data)) ;; Throws NoSuchDataVariable because `data` wasn't initialized at block height 0 -``` - -### get-block-info? -#### input: `BlockInfoPropertyName, BlockHeightInt` -#### output: `(optional buff) | (optional uint)` -#### signature: `(get-block-info? prop-name block-height-expr)` -#### description: -The `get-block-info?` function fetches data for a block of the given block height. The value and type returned are determined by the specified `BlockInfoPropertyName`. If the provided `BlockHeightInt` does not correspond to an existing block prior to the current block, the function returns `none`. The currently available property names are `time`, `header-hash`, `burnchain-header-hash`, `id-header-hash`, `miner-address`, and `vrf-seed`. - -The `time` property returns an integer value of the block header time field. This is a Unix epoch timestamp in seconds which roughly corresponds to when the block was mined. **Warning**: this does not increase monotonically with each block and block times are accurate only to within two hours. See [BIP113](https://github.com/bitcoin/bips/blob/master/bip-0113.mediawiki) for more information. - -The `header-hash`, `burnchain-header-hash`, `id-header-hash`, and `vrf-seed` properties return a 32-byte buffer. - -The `miner-address` property returns a `principal` corresponding to the miner of the given block. - -The `id-header-hash` is the block identifier value that must be used as input to the `at-block` function. - -#### example: -```clarity -(get-block-info? time u0) ;; Returns (some u1557860301) -(get-block-info? header-hash u0) ;; Returns (some 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb) -(get-block-info? vrf-seed u0) ;; Returns (some 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4) -``` - -### err -#### input: `A` -#### output: `(response A B)` -#### signature: `(err value)` -#### description: -The `err` function constructs a response type from the input value. Use `err` for creating return values in public functions. An _err_ value indicates that any database changes during the processing of the function should be rolled back. -#### example: -```clarity -(err true) ;; Returns (err true) -``` - -### ok -#### input: `A` -#### output: `(response A B)` -#### signature: `(ok value)` -#### description: -The `ok` function constructs a response type from the input value. Use `ok` for creating return values in public functions. An _ok_ value indicates that any database changes during the processing of the function should materialize. -#### example: -```clarity -(ok 1) ;; Returns (ok 1) -``` - -### some -#### input: `A` -#### output: `(optional A)` -#### signature: `(some value)` -#### description: -The `some` function constructs a `optional` type from the input value. -#### example: -```clarity -(some 1) ;; Returns (some 1) -(is-none (some 2)) ;; Returns false -``` - -### default-to -#### input: `A, (optional A)` -#### output: `A` -#### signature: `(default-to default-value option-value)` -#### description: -The `default-to` function attempts to 'unpack' the second argument: if the argument is a `(some ...)` option, it returns the inner value of the option. If the second argument is a `(none)` value, `default-to` it returns the value of `default-value`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(default-to 0 (get id (map-get? names-map (tuple (name \"blockstack\"))))) ;; Returns 1337 -(default-to 0 (get id (map-get? names-map (tuple (name \"non-existant\"))))) ;; Returns 0 -``` - -### asserts! -#### input: `bool, C` -#### output: `bool` -#### signature: `(asserts! bool-expr thrown-value)` -#### description: -The `asserts!` function admits a boolean argument and asserts its evaluation: if bool-expr is `true`, `asserts!` returns `true` and proceeds in the program execution. If the supplied argument is returning a false value, `asserts!` _returns_ `thrown-value` and exits the current control-flow. -#### example: -```clarity -(asserts! (is-eq 1 1) (err 1)) ;; Returns true -``` - -### unwrap! -#### input: `(optional A) | (response A B), C` -#### output: `A` -#### signature: `(unwrap! option-input thrown-value)` -#### description: -The `unwrap!` function attempts to 'unpack' the first argument: if the argument is an option type, and the argument is a `(some ...)` option, `unwrap!` returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, `unwrap!` returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `(none)` value, `unwrap!` _returns_ `thrown-value` from the current function and exits the current control-flow. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(define-private (get-name-or-err (name (string-ascii 12))) - (let ((raw-name (unwrap! (map-get? names-map { name: name }) (err 1)))) - (ok raw-name))) - -(get-name-or-err \"blockstack\") ;; Returns (ok (tuple (id 1337))) -(get-name-or-err \"non-existant\") ;; Returns (err 1) -``` - -### unwrap-err! -#### input: `(response A B), C` -#### output: `B` -#### signature: `(unwrap-err! response-input thrown-value)` -#### description: -The `unwrap-err!` function attempts to 'unpack' the first argument: if the argument is an `(err ...)` response, `unwrap-err!` returns the inner value of the `err`. If the supplied argument is an `(ok ...)` value, `unwrap-err!` _returns_ `thrown-value` from the current function and exits the current control-flow. -#### example: -```clarity -(unwrap-err! (err 1) false) ;; Returns 1 -``` - -### unwrap-panic -#### input: `(optional A) | (response A B)` -#### output: `A` -#### signature: `(unwrap-panic option-input)` -#### description: -The `unwrap` function attempts to 'unpack' its argument: if the argument is an option type, and the argument is a `(some ...)` option, this function returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, it returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `(none)` value, `unwrap` throws a runtime error, aborting any further processing of the current transaction. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(unwrap-panic (map-get? names-map { name: \"blockstack\" })) ;; Returns (tuple (id 1337)) -(unwrap-panic (map-get? names-map { name: \"non-existant\" })) ;; Throws a runtime exception -``` - -### unwrap-err-panic -#### input: `(response A B)` -#### output: `B` -#### signature: `(unwrap-err-panic response-input)` -#### description: -The `unwrap-err` function attempts to 'unpack' the first argument: if the argument is an `(err ...)` response, `unwrap` returns the inner value of the `err`. If the supplied argument is an `(ok ...)` value, `unwrap-err` throws a runtime error, aborting any further processing of the current transaction. -#### example: -```clarity -(unwrap-err-panic (err 1)) ;; Returns 1 -(unwrap-err-panic (ok 1)) ;; Throws a runtime exception -``` - -### match -#### input: `(optional A) name expression expression | (response A B) name expression name expression` -#### output: `C` -#### signature: `(match opt-input some-binding-name some-branch none-branch) | -(match-resp input ok-binding-name ok-branch err-binding-name err-branch)` -#### description: -The `match` function is used to test and destructure optional and response types. - -If the `input` is an optional, it tests whether the provided `input` is a `some` or `none` option, and evaluates `some-branch` or `none-branch` in each respective case. - -Within the `some-branch`, the _contained value_ of the `input` argument is bound to the provided `some-binding-name` name. - -Only _one_ of the branches will be evaluated (similar to `if` statements). - -If the `input` is a response, it tests whether the provided `input` is an `ok` or `err` response type, and evaluates `ok-branch` or `err-branch` in each respective case. - -Within the `ok-branch`, the _contained ok value_ of the `input` argument is bound to the provided `ok-binding-name` name. - -Within the `err-branch`, the _contained err value_ of the `input` argument is bound to the provided `err-binding-name` name. - -Only _one_ of the branches will be evaluated (similar to `if` statements). - -Note: Type checking requires that the type of both the ok and err parts of the response object be determinable. For situations in which one of the parts of a response is untyped, you should use `unwrap-panic` or `unwrap-err-panic` instead of `match`. -#### example: -```clarity - -(define-private (add-10 (x (optional int))) - (match x - value (+ 10 value) - 10)) -(add-10 (some 5)) ;; Returns 15 -(add-10 none) ;; Returns 10 - -(define-private (add-or-pass-err (x (response int (string-ascii 10))) (to-add int)) - (match x - value (ok (+ to-add value)) - err-value (err err-value))) -(add-or-pass-err (ok 5) 20) ;; Returns (ok 25) -(add-or-pass-err (err \"ERROR\") 20) ;; Returns (err \"ERROR\") -``` - -### try! -#### input: `(optional A) | (response A B)` -#### output: `A` -#### signature: `(try! option-input)` -#### description: -The `try!` function attempts to 'unpack' the first argument: if the argument is an option type, and the argument is a `(some ...)` option, `try!` returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, `try!` returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `none` value, `try!` _returns_ either `none` or the `(err ...)` value from the current function and exits the current control-flow. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(try! (map-get? names-map { name: \"blockstack\" })) ;; Returns (tuple (id 1337)) -(define-private (checked-even (x int)) - (if (is-eq (mod x 2) 0) - (ok x) - (err false))) -(define-private (double-if-even (x int)) - (ok (* 2 (try! (checked-even x))))) -(double-if-even 10) ;; Returns (ok 20) -(double-if-even 3) ;; Returns (err false) -``` - -### is-ok -#### input: `(response A B)` -#### output: `bool` -#### signature: `(is-ok value)` -#### description: -`is-ok` tests a supplied response value, returning `true` if the response was `ok`, and `false` if it was an `err`. -#### example: -```clarity -(is-ok (ok 1)) ;; Returns true -(is-ok (err 1)) ;; Returns false -``` - -### is-none -#### input: `(optional A)` -#### output: `bool` -#### signature: `(is-none value)` -#### description: -`is-none` tests a supplied option value, returning `true` if the option value is `(none)`, and `false` if it is a `(some ...)`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(is-none (get id (map-get? names-map { name: \"blockstack\" }))) ;; Returns false -(is-none (get id (map-get? names-map { name: \"non-existant\" }))) ;; Returns true -``` - -### is-err -#### input: `(response A B)` -#### output: `bool` -#### signature: `(is-err value)` -#### description: -`is-err` tests a supplied response value, returning `true` if the response was an `err`, and `false` if it was an `ok`. -#### example: -```clarity -(is-err (ok 1)) ;; Returns false -(is-err (err 1)) ;; Returns true -``` - -### is-some -#### input: `(optional A)` -#### output: `bool` -#### signature: `(is-some value)` -#### description: -`is-some` tests a supplied option value, returning `true` if the option value is `(some ...)`, and `false` if it is a `none`. -#### example: -```clarity - -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(is-some (get id (map-get? names-map { name: \"blockstack\" }))) ;; Returns true -(is-some (get id (map-get? names-map { name: \"non-existant\" }))) ;; Returns false -``` - -### filter -#### input: `Function(A) -> bool, sequence_A` -#### output: `sequence_A` -#### signature: `(filter func sequence)` -#### description: -The `filter` function applies the input function `func` to each element of the input sequence, and returns the same sequence with any elements removed for which `func` returned `false`. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. ` -#### example: -```clarity - -(filter not (list true false true false)) ;; Returns (false false) -(define-private (is-a (char (string-utf8 1))) (is-eq char u\"a\")) -(filter is-a u\"acabd\") ;; Returns u\"aa\" -(define-private (is-zero (char (buff 1))) (is-eq char 0x00)) -(filter is-zero 0x00010002) ;; Returns 0x0000 -``` - -### ft-get-balance -#### input: `TokenName, principal` -#### output: `uint` -#### signature: `(ft-get-balance token-name principal)` -#### description: -`ft-get-balance` returns `token-name` balance of the principal `principal`. The token type must have been defined using `define-fungible-token`. -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-get-balance stackaroo 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns u100 -``` - -### nft-get-owner? -#### input: `AssetName, A` -#### output: `(optional principal)` -#### signature: `(nft-get-owner? asset-class asset-identifier)` -#### description: -`nft-get-owner?` returns the owner of an asset, identified by `asset-identifier`, or `none` if the asset does not exist. The asset type must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) -(nft-get-owner? stackaroo \"Roo\") ;; Returns (some SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) -(nft-get-owner? stackaroo \"Too\") ;; Returns none -``` - -### ft-transfer? -#### input: `TokenName, uint, principal, principal` -#### output: `(response bool uint)` -#### signature: `(ft-transfer? token-name amount sender recipient)` -#### description: -`ft-transfer?` is used to increase the token balance for the `recipient` principal for a token type defined using `define-fungible-token` by debiting the `sender` principal. In contrast to `stx-transfer?`, any user can transfer the assets. When used, relevant guards need to be added. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- amount to send is non-positive ` -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-transfer? stackaroo u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(ft-transfer? stackaroo u60 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u1) -``` - -### nft-transfer? -#### input: `AssetName, A, principal, principal` -#### output: `(response bool uint)` -#### signature: `(nft-transfer? asset-class asset-identifier sender recipient)` -#### description: -`nft-transfer?` is used to change the owner of an asset identified by `asset-identifier` from `sender` to `recipient`. The `asset-class` must have been defined by `define-non-fungible-token` and `asset-identifier` must be of the type specified in that definition. In contrast to `stx-transfer?`, any user can transfer the asset. When used, relevant guards need to be added. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not own the asset `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- asset identified by asset-identifier does not exist ` -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(nft-transfer? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(nft-transfer? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u1) -(nft-transfer? stackaroo \"Stacka\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u3) -``` - -### nft-mint? -#### input: `AssetName, A, principal` -#### output: `(response bool uint)` -#### signature: `(nft-mint? asset-class asset-identifier recipient)` -#### description: -`nft-mint?` is used to instantiate an asset and set that asset's owner to the `recipient` principal. The asset must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. - -If an asset identified by `asset-identifier` _already exists_, this function will return an error with the following error code: - -`(err u1)` - -Otherwise, on successfuly mint, it returns `(ok true)`. ` -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### ft-mint? -#### input: `TokenName, uint, principal` -#### output: `(response bool uint)` -#### signature: `(ft-mint? token-name amount recipient)` -#### description: -`ft-mint?` is used to increase the token balance for the `recipient` principal for a token type defined using `define-fungible-token`. The increased token balance is _not_ transfered from another principal, but rather minted. - -If a non-positive amount is provided to mint, this function returns `(err 1)`. Otherwise, on successfuly mint, it returns `(ok true)`. ` -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### ft-get-supply -#### input: `TokenName` -#### output: `uint` -#### signature: `(ft-get-supply token-name)` -#### description: -`ft-get-balance` returns `token-name` circulating supply. The token type must have been defined using `define-fungible-token`. -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-get-supply stackaroo) ;; Returns u100 -``` - -### ft-burn? -#### input: `TokenName, uint, principal` -#### output: `(response bool uint)` -#### signature: `(ft-burn? token-name amount sender)` -#### description: -`ft-burn?` is used to decrease the token balance for the `sender` principal for a token type defined using `define-fungible-token`. The decreased token balance is _not_ transfered to another principal, but rather destroyed, reducing the circulating supply. - -If a non-positive amount is provided to burn, this function returns `(err 1)`. Otherwise, on successfuly burn, it returns `(ok true)`. - -#### example: -```clarity - -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(ft-burn? stackaroo u50 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### nft-burn? -#### input: `AssetName, A, principal` -#### output: `(response bool uint)` -#### signature: `(nft-burn? asset-class asset-identifier recipient)` -#### description: -`nft-burn?` is used to burn an asset and remove that asset's owner from the `recipient` principal. The asset must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. - -If an asset identified by `asset-identifier` _doesn't exist_, this function will return an error with the following error code: - -`(err u1)` - -Otherwise, on successfuly burn, it returns `(ok true)`. ` -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(nft-burn? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### stx-get-balance -#### input: `principal` -#### output: `uint` -#### signature: `(stx-get-balance owner)` -#### description: -`stx-get-balance` is used to query the STX balance of the `owner` principal. - -This function returns the STX balance of the `owner` principal. In the event that the `owner` principal isn't materialized, it returns 0. - -#### example: -```clarity -(stx-get-balance 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns u0 -(stx-get-balance (as-contract tx-sender)) ;; Returns u1000 -``` - -### stx-transfer? -#### input: `uint, principal, principal` -#### output: `(response bool uint)` -#### signature: `(stx-transfer? amount sender recipient)` -#### description: -`stx-transfer?` is used to increase the STX balance for the `recipient` principal by debiting the `sender` principal. The `sender` principal _must_ be equal to the current context's `tx-sender`. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- amount to send is non-positive `(err u4)` -- the `sender` principal is not the current `tx-sender` - -#### example: -```clarity - -(as-contract - (stx-transfer? u60 tx-sender 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (ok true) -(as-contract - (stx-transfer? u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR tx-sender)) ;; Returns (err u4) -``` - -### stx-burn? -#### input: `uint, principal` -#### output: `(response bool uint)` -#### signature: `(stx-burn? amount sender)` -#### description: -`stx-burn?` debits the `sender` principal's STX holdings by `amount`, destroying the STX. The `sender` principal _must_ be equal to the current context's `tx-sender`. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u3)` -- amount to send is non-positive `(err u4)` -- the `sender` principal is not the current `tx-sender` - -#### example: -```clarity -(as-contract - (stx-burn? u60 tx-sender)) ;; Returns (ok true) -(as-contract - (stx-burn? u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (err u4) -``` - -### define-constant -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-constant name expression)` -#### description: -`define-constant` is used to define a private constant value in a smart contract. The expression passed into the definition is evaluated at contract launch, in the order that it is supplied in the contract. This can lead to undefined function or undefined variable errors in the event that a function or variable used in the expression has not been defined before the constant. - -Like other kinds of definition statements, `define-constant` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -#### example: -```clarity - -(define-constant four (+ 2 2)) -(+ 4 four) ;; Returns 8 -``` - -### define-private -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-private (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### description: -`define-private` is used to define _private_ functions for a smart contract. Private functions may not be called from other smart contracts, nor may they be invoked directly by users. Instead, these functions may only be invoked by other functions defined in the same smart contract. - -Like other kinds of definition statements, `define-private` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Private functions may return any type. -#### example: -```clarity -(define-private (max-of (i1 int) (i2 int)) - (if (> i1 i2) - i1 - i2)) -(max-of 4 6) ;; Returns 6 -``` - -### define-public -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-public (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### description: -`define-public` is used to define a _public_ function and transaction for a smart contract. Public functions are callable from other smart contracts and may be invoked directly by users by submitting a transaction to the Stacks blockchain. - -Like other kinds of definition statements, `define-public` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Public functions _must_ return a ResponseType (using either `ok` or `err`). Any datamap modifications performed by a public function is aborted if the function returns an `err` type. Public functions may be invoked by other contracts via `contract-call?`. -#### example: -```clarity -(define-public (hello-world (input int)) - (begin (print (+ 2 input)) - (ok input))) -``` - -### define-read-only -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-read-only (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### description: -`define-read-only` is used to define a _public read-only_ function for a smart contract. Such functions are callable from other smart contracts. - -Like other kinds of definition statements, `define-read-only` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Read-only functions may return any type. However, read-only functions may not perform any datamap modifications, or call any functions which perform such modifications. This is enforced both during type checks and during the execution of the function. Public read-only functions may be invoked by other contracts via `contract-call?`. -#### example: -```clarity -(define-read-only (just-return-one-hundred) - (* 10 10)) - ``` - -### define-map -#### input: `MapName, TypeDefinition, TypeDefinition` -#### output: `Not Applicable` -#### signature: `(define-map map-name key-type value-type)` -#### description: -`define-map` is used to define a new datamap for use in a smart contract. Such maps are only modifiable by the current smart contract. - -Maps are defined with a key type and value type, often these types are tuple types. - -Like other kinds of definition statements, `define-map` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). -#### example: -```clarity -(define-map squares { x: int } { square: int }) -(define-private (add-entry (x int)) - (map-insert squares { x: 2 } { square: (* x x) })) -(add-entry 1) -(add-entry 2) -(add-entry 3) -(add-entry 4) -(add-entry 5) -``` - -### define-data-var -#### input: `VarName, TypeDefinition, Value` -#### output: `Not Applicable` -#### signature: `(define-data-var var-name type value)` -#### description: -`define-data-var` is used to define a new persisted variable for use in a smart contract. Such variable are only modifiable by the current smart contract. - -Persisted variable are defined with a type and a value. - -Like other kinds of definition statements, `define-data-var` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). -#### example: -```clarity -(define-data-var size int 0) -(define-private (set-size (value int)) - (var-set size value)) -(set-size 1) -(set-size 2) -``` - -### define-fungible-token -#### input: `TokenName, ` -#### output: `Not Applicable` -#### signature: `(define-fungible-token token-name )` -#### description: -`define-fungible-token` is used to define a new fungible token class for use in the current contract. - -The second argument, if supplied, defines the total supply of the fungible token. This ensures that all calls to the `ft-mint?` function will never be able to create more than `total-supply` tokens. If any such call were to increase the total supply of tokens passed that amount, that invocation of `ft-mint?` will result in a runtime error and abort. - -Like other kinds of definition statements, `define-fungible-token` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Tokens defined using `define-fungible-token` may be used in `ft-transfer?`, `ft-mint?`, and `ft-get-balance` functions` -#### example: -```clarity -(define-fungible-token stacks) -(define-fungible-token limited-supply-stacks u100) -``` - -### define-non-fungible-token -#### input: `AssetName, TypeSignature` -#### output: `Not Applicable` -#### signature: `(define-non-fungible-token asset-name asset-identifier-type)` -#### description: -`define-non-fungible-token` is used to define a new non-fungible token class for use in the current contract. Individual assets are identified by their asset identifier, which must be of the type `asset-identifier-type`. Asset identifiers are _unique_ identifiers. - -Like other kinds of definition statements, `define-non-fungible-token` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Assets defined using `define-non-fungible-token` may be used in `nft-transfer?`, `nft-mint?`, and `nft-get-owner?` functions` -#### example: -```clarity -(define-non-fungible-token names (buff 50)) -``` - -### define-trait -#### input: `VarName, [MethodSignature]` -#### output: `Not Applicable` -#### signature: `(define-trait trait-name ((func1-name (arg1-type arg2-type ...) (return-type))))` -#### description: -`define-trait` is used to define a new trait definition for use in a smart contract. Other contracts can implement a given trait and then have their contract identifier being passed as function arguments in order to be called dynamically with `contract-call?`. - -Traits are defined with a name, and a list functions defined with a name, a list of argument types, and return type. - -Like other kinds of definition statements, `define-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -#### example: -```clarity -(define-trait token-trait - ((transfer? (principal principal uint) (response uint uint)) - (get-balance (principal) (response uint uint)))) -``` - -### use-trait -#### input: `VarName, TraitIdentifier` -#### output: `Not Applicable` -#### signature: `(use-trait trait-alias trait-identifier)` -#### description: -`use-trait` is used to bring a trait, defined in another contract, to the current contract. Subsequent references to an imported trait are signaled with the syntax ``. - -Traits import are defined with a name, used as an alias, and a trait identifier. Trait identifiers can either be using the sugared syntax (.token-a.token-trait), or be fully qualified ('SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait). - -Like other kinds of definition statements, `use-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put such a statement in the middle of a function body). -#### example: -```clarity -(use-trait token-a-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) -(define-public (forward-get-balance (user principal) (contract )) - (begin - (ok 1))) -``` - -### impl-trait -#### input: `TraitIdentifier` -#### output: `Not Applicable` -#### signature: `(impl-trait trait-identifier)` -#### description: -`impl-trait` can be use for asserting that a contract is fully implementing a given trait. Additional checks are being performed when the contract is being published, rejecting the deployment if the contract is violating the trait specification. - -Trait identifiers can either be using the sugared syntax (.token-a.token-trait), or be fully qualified ('SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait). - -Like other kinds of definition statements, `impl-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put such a statement in the middle of a function body). - -#### example: -```clarity -(impl-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) -(define-public (get-balance (account principal)) - (ok u0)) -(define-public (transfer? (from principal) (to principal) (amount uint)) - (ok u0)) -``` \ No newline at end of file diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md b/i18n/hi/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md deleted file mode 100644 index fd62451198..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Keywords -description: See a detailed list of all keywords for the Clarity language. -tags: - - clarity ---- - -![](/img/keywords.jpg) -## Keyword reference - -Detailed list of all keywords for the Clarity language. - - -### contract-caller -#### output: `principal` -#### description: -Returns the caller of the current contract context. If this contract is the first one called by a signed transaction, the caller will be equal to the signing principal. If `contract-call?` was used to invoke a function from a new contract, `contract-caller` changes to the _calling_ contract's principal. If `as-contract` is used to change the `tx-sender` context, `contract-caller` _also_ changes to the same contract principal. -#### example: -```clarity -(print contract-caller) ;; Will print out a Stacks address of the transaction sender -``` - -### tx-sender -#### output: `principal` -#### description: -Returns the original sender of the current transaction, or if `as-contract` was called to modify the sending context, it returns that contract principal. -#### example: -```clarity -(print tx-sender) ;; Will print out a Stacks address of the transaction sender -``` - -### block-height -#### output: `uint` -#### description: -Returns the current block height of the Stacks blockchain as an uint -#### example: -```clarity -(> block-height 1000) ;; returns true if the current block-height has passed 1000 blocks. -``` - -### burn-block-height -#### output: `uint` -#### description: -Returns the current block height of the underlying burn blockchain as a uint -#### example: -```clarity -(> burn-block-height 1000) ;; returns true if the current height of the underlying burn blockchain has passed 1000 blocks. -``` - -### none -#### output: `(optional ?)` -#### description: -Represents the _none_ option indicating no value for a given optional (analogous to a null value). -#### example: -```clarity -(define-public (only-if-positive (a int)) - (if (> a 0) - (some a) - none)) -(only-if-positive 4) ;; Returns (some 4) -(only-if-positive (- 3)) ;; Returns none -``` - -### true -#### output: `bool` -#### description: -Boolean true constant. -#### example: -```clarity -(and true false) ;; Evaluates to false -(or false true) ;; Evaluates to true -``` - -### false -#### output: `bool` -#### description: -Boolean false constant. -#### example: -```clarity -(and true false) ;; Evaluates to false -(or false true) ;; Evaluates to true -``` - -### stx-liquid-supply -#### output: `uint` -#### description: -Returns the total number of micro-STX (uSTX) that are liquid in the system as of this block. -#### example: -```clarity -(print stx-liquid-supply) ;; Will print out the total number of liquid uSTX -``` - -### is-in-regtest -#### output: `bool` -#### description: -Returns whether or not the code is running in a regression test -#### example: -```clarity -(print is-in-regtest) ;; Will print 'true' if the code is running in a regression test -``` - diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md b/i18n/hi/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md deleted file mode 100644 index d22f991413..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Types -description: See a detailed list of all types for the Clarity language. -tags: - - clarity ---- - -## Clarity Type System - -The type system contains the following types: - -| Types | Notes | -| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `int` | signed 128-bit integer | -| `uint` | unsigned 128-bit integer | -| `bool` | boolean value (`true` or `false`) | -| `principal` | object representing a principal (whether a contract principal or standard principal) | -| `(buff max-len)` | byte buffer of 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` (u"A smiley face emoji \u{1F600} as a utf8 string") | -| `(list max-len entry-type)` | list of maximum length `max-len`, with entries of type `entry-type` | -| `{label-0: value-type-0, label-1: value-type-1, ...}` | tuple, group of data values with named fields | -| `(optional some-type)` | an option type for objects that can either be `(some value)` or `none` | -| `(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. | diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md b/i18n/hi/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md deleted file mode 100644 index c518c7bbae..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Clarity overview -description: Overview and guides for getting started with Clarity -sidebar_label: Write smart contracts -sidebar_position: 2 ---- - -## Introduction - -Clarity is a **decidable** smart contract language that optimizes for predictability and security, designed for the Stacks blockchain. Smart contracts allow developers to encode essential business logic on a blockchain. - -## Smart contracts - -Smart contracts encode and enforce rules for modifying a particular set of data that is shared among people and entities who don't necessarily trust each other. For example, a smart contract can hold funds in escrow until multiple parties agree to release them, create its own ledger and keep track of its own novel tokens (fungible or non-fungible), and even help make supply chains more transparent. - -Because smart contracts are programs that exist in a blockchain, anyone can query them, and anyone can submit transactions to execute them. A smart contract execution can result in new transactions being written to the blockchain. - -Apps can take advantage of smart contracts to manage a global state that is visible to the public. Anyone can audit the blockchain to independently verify that an app's global shared state has been managed correctly according to the smart contract's rules. - -There is a [Clarity Visual Studio Code plugin][] available for syntax assistance and debugging. - -## Use cases - -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 (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 - -## Language design - -Clarity differs from most other smart contract languages in two essential ways: - -- The language is interpreted and broadcast on the blockchain as is (not compiled) -- The language is decidable (not Turing complete) - -Using an interpreted language ensures that the executed code is human-readable and auditable. A decidable language like Clarity makes it possible to determine precisely which code is executed, for any function. - -A Clarity smart contract consists of two parts, a data space and a set of functions. Only the associated smart contract may modify its corresponding data space on the blockchain. Functions may be private and thus callable only from within the smart contract, or public and thus callable from other contracts. Users call smart contracts' public functions by broadcasting a transaction on the blockchain which invokes the public function. Contracts can also call public functions from other smart contracts. - -Note some of the key Clarity language rules and limitations. - -- The only primitive types are booleans, integers, buffers, and principals. -- Recursion is illegal and there are no anonymous functions. -- Looping is only performed via `map`, `filter`, or `fold`. -- There is support for lists, however, the only variable length lists in the language appear as function inputs; there is no support for list operations like append or join. -- Variables are immutable. - -## Explore more - -For language details and references, see the following: - -- [Clarity language overview](./clarity-language/) -- [Understating Principals](principals) -- [Clarity Values](values) - -[Clarity Visual Studio Code plugin]: https://marketplace.visualstudio.com/items?itemName=HiroSystems.clarity-lsp diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md b/i18n/hi/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md deleted file mode 100644 index 9cc4fe60aa..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md +++ /dev/null @@ -1,236 +0,0 @@ ---- -title: Principals -description: 'Clarity: Understanding Principals' -sidebar_position: 1 ---- - -## Introduction - -_Principals_ are a Clarity native type that represents an entity that can have a token balance. This section discusses principals and how they are used in the Clarity. - -## Principals and tx-sender - -Assets in the smart contracting language and blockchain are "owned" by objects of the principal type, meaning that any object of the principal type may own an asset. For the case of public-key hash and multi-signature Stacks addresses, a given principal can operate on their assets by issuing a signed transaction on the blockchain. _Smart contracts_ may also be principals (represented by the smart contract's identifier), however, there is no private key associated with the smart contract, and it cannot broadcast a signed transaction on the blockchain. - -A Clarity contract can use a globally defined `tx-sender` variable to obtain the current principal. The following example defines a transaction type that transfers `amount` microSTX from the sender to a recipient if amount is a multiple of 10, otherwise returning a 400 error code. - -```clarity -(define-public (transfer-to-recipient! (recipient principal) (amount uint)) - (if (is-eq (mod amount 10) 0) - (stx-transfer? amount tx-sender recipient) - (err u400))) -``` - -Clarity provides an additional variable to help smart contracts authenticate a transaction sender. The keyword `contract-caller` returns the principal that _called_ the current contract. If an inter-contract call occurred, `contract-caller` returns the last contract in the stack of callers. For example, suppose there are three contracts A, B, and C, each with an `invoke` function such that `A::invoke` calls `B::invoke` and `B::invoke` calls `C::invoke`. - -When a user Bob issues a transaction that calls `A::invoke`, the value of `contract-caller` in each successive invoke function's body would change: - -```clarity -in A::invoke, contract-caller = Bob -in B::invoke, contract-caller = A -in C::invoke, contract-caller = B -``` - -This allows contracts to make assertions and perform authorization checks using not only the `tx-sender` (which in this example, would always be "Bob"), but also using the `contract-caller`. This could be used to ensure that a particular function is only ever called directly and never called via an inter-contract call (by asserting that `tx-sender` and `contract-caller` are equal). We provide an example of a two different types of authorization checks in the rocket ship example below. - -## Smart contracts as principals - -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, for example: - -```clarity -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-name -``` - -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 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 qualified identifier for the contracts would be: - -```clarity -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-A -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-B -``` - -But, in the contract source code, if the developer wishes to call a function from `contract-A` in `contract-B`, they can write - -```clarity -(contract-call? .contract-A public-function-foo) -``` - -This allows the smart contract developer to modularize their applications across multiple smart contracts _without_ knowing the publishing key a priori. - -In order for a smart contract to operate on assets it owns, smart contracts may use the special `(as-contract ...)` function. This function executes the expression (passed as an argument) with the `tx-sender` set to the contract's principal, rather than the current sender. The `as-contract` function returns the value of the provided expression. - -For example, a smart contract that implements something like a "token faucet" could be implemented as so: - -```clarity -(define-map claimed-before - ((sender principal)) - ((claimed bool))) - -(define-constant err-already-claimed u1) -(define-constant err-faucet-empty u2) -(define-constant stx-amount u1) - -(define-public (claim-from-faucet) - (let ((requester tx-sender)) ;; set a local variable requester = tx-sender - (asserts! (is-none (map-get? claimed-before {sender: requester})) (err err-already-claimed)) - (unwrap! (as-contract (stx-transfer? stx-amount tx-sender requester)) (err err-faucet-empty)) - (map-set claimed-before {sender: requester} {claimed: true}) - (ok stx-amount))) -``` - -In this example, the public function `claim-from-faucet`: - -- Checks if the sender has claimed from the faucet before. -- Assigns the tx sender to a `requester` variable. -- Adds an entry to the tracking map. -- Uses `as-contract` to send 1 microstack - -Unlike other principals, there is no private key associated with a smart contract. As it lacks a private key, a Clarity smart contract cannot broadcast a signed transaction on the blockchain. - -## Example: Authorization checks - -The interactions between `tx-sender`, `contract-caller` and `as-contract` are subtle, but are important when performing authorization checks in a contract. In this example contract, we'll show two different kinds of authorization checks a contract may wish to perform, and then walk through how different ways in which contract functions may be called will pass or fail those checks. - -This contract defines a "rocket-ship" non-fungible-token that a principal may own and manage the authorized pilots. Pilots are principals that are allowed to "fly" the rocket ship. - -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. -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 be called _directly_ by the ship's owner, rather than through a inter-contract-call. - -The second type of check is more restrictive than the first check, and is helpful for guarding very sensitive routines --- it protects users from unknowingly calling a function on a malicious contract that subsequently tries to call sensitive functions on another contract. - -```clarity -;; -;; rockets-base.clar -;; - -(define-non-fungible-token rocket-ship uint) - -;; a map from rocket ships to their allowed -;; pilots -(define-map allowed-pilots - ((rocket-ship uint)) ((pilots (list 10 principal)))) - -;; implementing a contains function via fold -(define-private (contains-check - (y principal) - (to-check { p: principal, result: bool })) - (if (get result to-check) - to-check - { p: (get p to-check), - result: (is-eq (get p to-check) y) })) - -(define-private (contains (x principal) (find-in (list 10 principal))) - (get result (fold contains-check find-in - { p: x, result: false }))) - -(define-read-only (is-my-ship (ship uint)) - (is-eq (some tx-sender) (nft-get-owner? rocket-ship ship))) - -;; this function will print a message -;; (and emit an event) if the tx-sender was -;; an authorized flyer. -;; -;; here we use tx-sender, because we want -;; to allow the user to let other contracts -;; fly the ship on behalf of users - -(define-public (fly-ship (ship uint)) - (let ((pilots (default-to - (list) - (get pilots (map-get? allowed-pilots { rocket-ship: ship }))))) - (if (contains tx-sender pilots) - (begin (print "Flew the rocket-ship!") - (ok true)) - (begin (print "Tried to fly without permission!") - (ok false))))) -;; -;; Authorize a new pilot. -;; -;; here we want to ensure that this function -;; was called _directly_ by the user by -;; checking that tx-sender and contract-caller are equal. -;; if any other contract is in the call stack, contract-caller -;; would be updated to a different principal. -;; -(define-public (authorize-pilot (ship uint) (pilot principal)) - (begin - ;; sender must equal caller: an intermediate contract is - ;; not issuing this call. - (asserts! (is-eq tx-sender contract-caller) (err u1)) - ;; sender must own the rocket ship - (asserts! (is-eq (some tx-sender) - (nft-get-owner? rocket-ship ship)) (err u2)) - (let ((prev-pilots (default-to - (list) - (get pilots (map-get? allowed-pilots { rocket-ship: ship }))))) - ;; don't add a pilot already in the list - (asserts! (not (contains pilot prev-pilots)) (err u3)) - ;; append to the list, and check that it is less than - ;; the allowed maximum - (match (as-max-len? (append prev-pilots pilot) u10) - next-pilots - (ok (map-set allowed-pilots {rocket-ship: ship} {pilots: next-pilots})) - ;; too many pilots already - (err u4))))) -``` - -### Extending functionality: Multi-flyer contract - -The authorization scheme for `fly-ship` allows pilots to fly rocket-ships from other contracts. This allows other contracts to provide new functionality built around calling that function. - -For example, we can create a contract that calls `fly-ship` for multiple rocket-ships in a single transaction: - -```clarity -;; -;; rockets-multi.clar -;; - -(define-private (call-fly (ship uint)) - (unwrap! (contract-call? .rockets-base fly-ship ship) false)) -;; try to fly all the ships, returning a list of whether -;; or not we were able to fly the supplied ships -(define-public (fly-all (ships (list 10 uint))) - (ok (map call-fly ships))) -``` - -### Authorization for Contract-Owned Assets - -The check in `authorize-pilot` protects users from malicious contracts, but how would such a scheme support contract-owned assets? This is what the `as-contract` function is used for. The `as-contract` function executes the supplied closure as if the sender of the transaction was the current contract, rather than the user -- it does this by updating `tx-sender` to the current contract principal. We can use this to, for example, create a smart contract rocket-ship-line: - -```clarity -;; -;; rockets-ship-line.clar -;; - -(define-constant line-ceo 'SP19Y6GRV9X778VFS1V8WT2H502WFK33XZXADJWZ) - -(define-data-var employed-pilots (list 10 principal) (list)) - -;; This function will: -;; * check that it is called by the line-ceo -;; * check that the rocket is owned by the contract -;; * authorize each employed pilot to the ship -(define-public (add-managed-rocket (ship uint)) - (begin - ;; 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 - (asserts! (contract-call? .rockets-base is-my-ship ship) (err u2)) - ;; register all of our pilots on the ship - (add-pilots-to ship))))) - -;; add all the pilots to a ship using fold -- -;; the fold checks the return type of previous calls, -;; skipping subsequent contract-calls if one fails. -(define-private (add-pilot-via-fold (pilot principal) (prior-result (response uint uint))) - (let ((ship (try! prior-result))) - (try! (contract-call? .rockets-base authorize-pilot ship pilot)) - (ok ship))) -(define-private (add-pilots-to (ship uint)) - (fold add-pilot-via-fold (var-get employed-pilots) (ok ship))) -``` - -In order for the contract to add each pilot to a new ship, the contract must call `authorize-pilot`. However, the contract wants to perform this action on behalf of a ship the _contract_ owns, not the transaction sender. To do this, the contract uses `as-contract`. diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md b/i18n/hi/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md deleted file mode 100644 index a01e37bc04..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Resources -description: 'Resources' -sidebar_position: 8 ---- - -# External resources - - -[Clarity book](https://book.clarity-lang.org/) - -[Clarity Universe](https://stacks.org/clarity-universe) - -[Hiro Clarity tutorials](https://docs.hiro.so/tutorials) diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md b/i18n/hi/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md deleted file mode 100644 index ed65829518..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Clarity development software -description: The following tools are useful when developing Clarity smart contracts -sidebar_position: 4 ---- - -## Language Server Protocol for Clarity (including Visual Studio Code extension) - -The Language Server Protocol (LSP) defines the protocol used between an editor or IDE and a language server that provides language features like auto complete, go to definition, find all references etc. - -This makes programming in Clarity easier and much more intuitive. - -![Clarity LSP Screenshot](https://raw.githubusercontent.com/hirosystems/clarity-lsp/21b64298ca117dc41358eb9dce4605cc4a448a4c/images/screenshot.png?raw=true) - - -Clarity LSP repository is available [here](https://github.com/hirosystems/clarity-lsp). The extension for Visual Studio Code can be downloaded directly from [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=HiroSystems.clarity-lsp), but can be and older version. For a more up to date version you can also download it from [open-vsx](https://open-vsx.org/extension/hirosystems/clarity-lsp). - -## Clarity REPL - -A read—eval—print loop (REPL), also termed an interactive toplevel or language shell, is a simple, interactive computer programming environment that takes single user inputs (that is, single expressions), evaluates (executes) them, and returns the result to the user; a program written in a REPL environment is executed piecewise. - -![Clarity-repl](https://github.com/hirosystems/clarity-repl/blob/develop/docs/images/screenshot.png?raw=true) - -Instructions on how to install Clarity REPL can be found [here](https://github.com/hirosystems/clarity-repl). - -## Clarinet - -Clarinet is a Clarity runtime packaged as a command line tool, designed to facilitate smart contract understanding, development, testing and deployment. Clarinet consists of a Clarity REPL and a testing harness, which, when used together allow you to rapidly develop and test a Clarity smart contract, with the need to deploy the contract to a local devnet or testnet. - -![Clarinet](https://github.com/hirosystems/clarinet/blob/develop/docs/images/demo.gif?raw=true) - -Installation instructions, including build from source instructions can be found [here](https://github.com/hirosystems/clarinet). If you prefer you can directly download the latest compiled realease for Windows, Mac and Linux [here](https://github.com/hirosystems/clarinet/releases). - -[Clarinet 101](https://www.youtube.com/playlist?list=PL5Ujm489LoJaAz9kUJm8lYUWdGJ2AnQTb) contains multiple Clarinet video tutorials - -### Getting started with Clarinet - -You can verify you have Clarinet installed by checking its version: - -```bash -$ clarinet --version -clarinet 0.70 -``` - -More detailed information on using Clarinet is available [here](https://book.clarity-lang.org/ch07-00-using-clarinet.html). However to get you started, the following commands are important to know. - -Create a new project and enter its directory: - -```bash -clarinet new my-project && cd my-project -``` - -Create a new contract inside `my-project`: - -```bash -clarinet contract new mycoolcontract -``` - -Check the syntax of Clarity: - -```bash -clarity check -``` - -To test your contract: - -```bash -clarinet test -``` - -Enter Clarinet's console: - -```bash -clarinet console -``` diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md b/i18n/hi/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md deleted file mode 100644 index c3bc8944d7..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Tokens -description: Learn about token support within Clarity -sidebar_position: 3 ---- - -## Introduction - -A fundamental use of blockchain technology is the representation, store, and transfer of value between users of a blockchain. Cryptocurrency is a very common use of blockchain technology, and remains one of the primary drivers of adoption of blockchain technology. Cryptocurrencies are represented by blockchain tokens: individual units of value within a given blockchain ecosystem. Blockchain tokens can extend beyond just digital currency, however, and recent developments throughout the cryptocurrency community have demonstrated potential for the use of blockchain to tokenize and represent not just money but other tangible assets. - -A blockchain token is a digital asset that can be verifiably owned by a user of a blockchain. Blockchain tokens are governed by a set of rules that are defined by either the blockchain itself (in the case of native tokens) or by a smart contract on a blockchain. Rules can vary depending on the nature and the use of the token. - -Tokens on a blockchain fall into two general categories, depending on their properties: [fungible][] or [non-fungible][]. The following sections discuss the properties of both types of tokens, and provide information about implementation of the two types of tokens on Stacks. - -## Fungible tokens - -A core property of any token on a blockchain is fungibility. A fungible token is a token that's mutually interchangable or capable of mutual substitution. In other words, one quantity or part of a fungible token can be replaced by an equal quantity or part of the same fungible token. Fungible tokens are often used to represent real-world fungible assets like currency. The STX token is an example of a fungible token. Other examples include stablecoins, tokens that represent voting rights in a DAO, or tokens that algorithmically track the price of stocks. - -Fungible tokens form one of the most important value propositions for blockchain technology, the ability to store value and exchange that value through both internal and external transactions. Because fungible tokens can be divided into smaller parts and recombined into the same value representation, they serve a great utility for transferring value between blockchain users. - -The primary fungible token on the Stacks blockchain is the native token, STX. Because the Stacks blockchain allows for the creation of \[smart contracts\]\[\], other fungible tokens can be created on the Stacks blockchain as well. [SIP-010][] specifies the standard for fungible tokens on the Stacks blockchain. This specification defines the functions and traits that a fungible token on Stacks _must_ have. By complying with this standard, fungible tokens on Stacks can be easily represented by wallets that support Stacks. - -### Understanding the fungible token standard - -The [SIP-010][] standard is an interface definition that allows Stacks applications and wallets to interact with fungible tokens in a standard way. Supporting the standard reduces complexity for token creators to get their tokens into the ecosystem. Under the [SIP-010][] standard, fungible tokens must have the following characteristics: - -- Ability to transfer a specified amount of the token to a recipient (`transfer`). The recipient is required to be a Stacks principal. -- Ability to obtain the human-readable name of the token (`get-name`). -- Ability to obtain a short name (ticker symbol) for the token (`get-symbol`). -- Ability to get the number of decimals in the token representation (`get-decimals`). This is used to construct a representation of the token that humans would be familiar dealing with. For example, the US dollar has 2 decimals, if the base unit is cents. -- Ability to get the balance of the token for a particular Stacks principal (`get-balance-of`). -- Ability to get the total supply of the token (`get-total-supply`). -- A URI to metadata associated with the token (`get-token-uri`). This can resolve to off-chain metadata about the token or contract, such as an image icon for the token or a description. - -## Non-fungible tokens (NFTs) - -Non-fungible tokens (NFTs) are a type of token that are not interchangeable. NFTs have unique traits (usually in the form of attached metadata) that restrict the abillity to replace them with identical tokens. An NFT is a token that is unique, such as a piece of art, or ownership rights to a real-world asset such as a house. - -NFTs alone don't have an inherent value, like a currency. The value of an NFT is derived from the assets that the NFT represents. The use of NFTs are myriad, including digital art, collectibles, domain names, and representation of ownership of content rights. NFTs can be used as digital certificates that track the authenticty of real world items, or digitize the ownership rights to property. - -As with fungible tokens, NFTs on the Stacks blockchain are created with smart contracts. [SIP-009][] specifies the standard for NFTs on the Stacks blockchain. This specification defines the functions and traits that an NFT _must_ have, but most NFTs have more functions or traits attached than those solely described by the specification. By complying with this standard, non-fungible tokens on Stacks can be easily represented by wallets that support Stacks. - -### Understanding the non-fungible token standard - -The [SIP-009][] standard is an interface definition that the Stacks ecosystem aligned on. With support for this standard across wallets and tools, it becomes easy to interact with NFTs. Under the [SIP-009][] standard, NFT contract must have the following characteristics: - -- Ability to obtain the last token identifier (`get-last-token-id`). This id represents the upper limit of NFTs issued by the contract. -- A URI to metadata associated with a specific token identifier. (`get-token-uri`). This URI could resolve to a JSON file with information about the creator, associated media files, descriptions, signatures, and more. -- Ability to verify the owner for a given token identifier (`get-owner`). The owner resolves to a [Stacks principal](principals). -- Ability to transfer an NFT to a recipient (`transfer`). The recipient is required to be a Stacks principal. - -## Further reading - -- [The Difference Between Fungible and Non-Fungible Tokens](https://101blockchains.com/fungible-vs-non-fungible-tokens/) -- [Explain It Like I Am 5: NFTs](https://messari.io/article/explain-it-like-i-am-5-nfts) - -[fungible]: #fungible-tokens -[non-fungible]: #non-fungible-tokens-nfts -[SIP-010]: https://github.com/stacksgov/sips/blob/main/sips/sip-010/sip-010-fungible-token-standard.md -[SIP-009]: https://github.com/stacksgov/sips/blob/main/sips/sip-009/sip-009-nft-standard.md diff --git a/i18n/hi/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md b/i18n/hi/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md deleted file mode 100644 index fc4765aa0c..0000000000 --- a/i18n/hi/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md +++ /dev/null @@ -1,301 +0,0 @@ ---- -title: Clarity Values -description: Learn how to deal with Clarity Values in JavaScript -sidebar_position: 2 ---- - -## Introduction - -The Clarity language makes use of a strong static 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/hirosystems/stacks.js/tree/master/packages/transactions) library makes this easy, as we will demonstrate below. - -## Clarity Types - -Please see the following page for information on [Clarity Types](../write-smart-contracts/clarity-language/language-types). - -## Constructing Clarity Values and accessing their data - -Clarity values can be constructed with functions provided by the [@stacks/transactions](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library. These functions simply output javascript objects that contain a value and a numerical representation of the Clarity type information. The Clarity types are encoded as follows: - -```typescript -export enum ClarityType { - Int = 0, - UInt = 1, - Buffer = 2, - BoolTrue = 3, - BoolFalse = 4, - PrincipalStandard = 5, - PrincipalContract = 6, - ResponseOk = 7, - ResponseErr = 8, - OptionalNone = 9, - OptionalSome = 10, - List = 11, - Tuple = 12, - StringASCII = 13, - StringUTF8 = 14, -} -``` - -`ClarityValue` objects can be serialized and included in transactions that interact with published Clarity contracts. - -Here are examples of how to construct each type of Clarity value, and how to access its data if it has any: - -### Booleans - -```typescript -const t = trueCV(); -// { type: ClarityType.BoolTrue } - -const f = falseCV(); -// { type: ClarityType.BoolFalse } -``` - -Boolean Clarity Values don't contain any underlying data. They are simply objects with `type` information. - -### Optional Values - -```typescript -const nothing: NoneCV = noneCV(); -// { type: ClarityType.OptionalNone } - -const something: SomeCV = someCV(trueCV()); -// { type: ClarityType.OptionalSome, value: { type: 4 } } -``` - -Optional Clarity Values can either be nothing (an empty type that has no data), or something (a wrapped value). - -If you are dealing with a function or contract function that returns an `OptionalCV`, you should always check what type it is before trying to access its value. - -```typescript -const maybeVal: OptionalCV = await callReadOnlyFunction(...); - -if (maybeVal.type === ClarityType.OptionalSome) { - console.log(maybeVal.value); -} else if (maybeVal.type === ClarityType.OptionalNone) { - // deal with `none` value -} -``` - -### Buffers - -```typescript -const buffer = Buffer.from('foo'); -const bufCV: BufferCV = bufferCV(buffer); -// { type: ClarityType.Buffer, buffer: } -``` - -### Integers - -Clarity supports both integers and unsigned integers. - -```typescript -const i: IntCV = intCV(-10); -// { type: ClarityType.Int, value: BN { ... } } - -const u: UIntCV = uintCV(10); -// { type: ClarityType.UInt, value: BN { ... } } -``` - -Clarity value ints store their underlying data as `BigNum` values from the [bn.js](https://github.com/indutny/bn.js/) library. - -In order to display/print Clarity (u)int values, use the `cvToString(val)` method. - -If you wish to perform arithmetic operations using Clarity (u)int values, you must use methods from the `BigNum` api on their underlying `BigNum` values, and the construct a new Clarity value out of the result. For example: - -```typescript -const x = intCV(1); -const y = intCV(2); - -x.value.add(y.value); -// 3 -``` - -### Strings - -```typescript -const ascii: StringAsciiCV = stringAsciiCV('hello world'); -// { type: ClarityType.StringASCII, data: 'hello world' } - -const utf8: StringUtf8CV = stringUtf8CV('hello 🌾'); -// { type: ClarityType.StringUTF8, data: 'hello 🌾' } -``` - -Clarity supports both ascii and utf8 strings. - -### Principals - -```typescript -const address = 'SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B'; -const contractName = 'contract-name'; - -const spCV = standardPrincipalCV(address); -// { -// type: ClarityType.PrincipalStandard -// address: { -// type: StacksMessageType.Address, -// version: AddressVersion.MainnetSingleSig, -// hash160: "SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B" -// } -// } - -const cpCV = contractPrincipalCV(address, contractName); -// { -// type: ClarityType.PrincipalContract, -// contractName: { -// type: StacksMessageType.LengthPrefixedString, -// content: 'contract-name', -// lengthPrefixBytes: 1, -// maxLengthBytes: 128, -// }, -// address: { -// type: StacksMessageType.Address, -// version: AddressVersion.MainnetSingleSig, -// hash160: "SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B" -// } -// } -``` - -Both kinds of Clarity principal values contain `type` information and an `address` object. Contract principals also contain a `contractName`. - -### Response Values - -```typescript -const errCV = responseErrorCV(trueCV()); -// { type: ResponseErr, value: { type: ClarityType.BoolTrue } } - -const okCV = responseOkCV(falseCV()); -// { type: ResponseOk, value: { type: ClarityType.BoolFalse } } -``` - -Response Clarity Values will either have the type `ClarityType.ResponseOk` or `ClarityType.ResponseErr`. They both contain a Clarity Value. Often this value will be an integer error code if the response is an `Error`. - -### Tuples - -```typescript -const tupCV = tupleCV({ - a: intCV(1), - b: trueCV(), - c: falseCV(), -}); -// { -// type: ClarityType.Tuple, -// data: { -// a: { type: ClarityType.Int, value: BN { ... } }, -// b: { type: ClarityType.BoolTrue }, -// c: { type: ClarityType.BoolFalse }, -// } -// } - -console.log(tupCV.data['b']); -// { type: ClarityType.BoolTrue } -``` - -Tuples in Clarity are typed and contain named fields. The tuple above, for example, contains three fields with the names **a**, **b** and **c**, and the types of their values are `Int`, `Boolean` and `Boolean`, respectively. - -Clarity tuples are represented in JavaScript as objects and a tuple's data can be accessed by its `data` field, where the underlying JS object is stored. - -### Lists - -```typescript -const l = listCV([trueCV(), falseCV()]); -// { type: ClarityType.List, list: [{ type: ClarityType.BoolTrue }] } - -console.log(l.list[0]); -// { type: ClarityType.BoolTrue } -``` - -Lists, in Clarity, are homogeneous, meaning they can only contain elements of a singular (Clarity) type. Make sure to avoid constructing lists that have elements of multiple types. - -A Clarity lists underlying data can be accessed via its `list` field. - -## Using Clarity Values - -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](../understand-stacks/transactions#construction). - -## Utilizing Clarity Values from Transaction Responses - -`Read-only` Clarity functions can return Clarity values as a response. These `read-only` functions can be accessed easily in JavaScript via the [`callReadOnlyFunction()`](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions#calling-read-only-contract-function) function included in `@stacks/transactions`, which returns a `ClarityValue`. - -As mentioned above, `ClarityValues` are simply javascript objects containing a value and its associated Clarity type information. These object types are defined [here](https://github.com/hirosystems/stacks.js/tree/1f2b5fd8bdf1c2b5866e8171163594d7708a8c7a/packages/transactions/src/clarity/types). - -When you are calling a `read-only` contract function, you will always know what type the function will return, since functions in Clarity are strongly typed. - -It is common for Clarity functions to return values wrapped in a `Response`, in order to indicate if there was success or an error. - -Since every `ClarityValue` has a `type` field, the type of the result of a `read-only` function call can be checked and acted upon like so: - -```typescript -const contractAddress = 'ST3KC0MTNW34S1ZXD36JYKFD3JJMWA01M55DSJ4JE'; -const contractName = 'kv-store'; -const functionName = 'get-value'; -const buffer = bufferCVFromString('foo'); -const network = new StacksTestnet(); // for mainnet, use `StacksMainnet()` -const senderAddress = 'ST2F4BK4GZH6YFBNHYDDGN4T1RKBA7DA1BJZPJEJJ'; - -const options = { - contractAddress, - contractName, - functionName, - functionArgs: [buffer], - network, - senderAddress, -}; - -// make a read-only call to a contract function that -// returns a Response -const result: ResponseCV = await callReadOnlyFunction(options); - -if (result.type === ClarityType.ResponseOk) { - console.log(cvToString(result.value)); -} else if (result.type === ClarityType.ResponseErr) { - throw new Error(`kv-store contract error: ${result.value.data}`); -} -``` - -### ClarityValues to/from Hex - -If you receive a response from a transaction in the form of a `hex` string, you can deserialize it into a Clarity value like so: - -```javascript -import { hexToCV } from '@stacks/transactions'; - -let cv = hexToCV('hex_string'); -``` - -Similarly, you can convert a Clarity value to `hex` string like so: - -```javascript -import { cvToHex, trueCV } from '@stacks/transactions'; - -let trueHex = cvToHex(trueCV()); -``` - -## Debugging Clarity Values - -Sometimes you might receive a Clarity value that you were not expecting. Logging the value to your console won't always prove to be useful, unless you have memorized the Clarity value type enum values. - -In order to figure out what kind of value you are dealing with, you can use the `cvToString()` function to convert the Clarity value to a more easily readable string. - -For example, calling `cvToString()` on a large `tuple` might yield something like: - -``` -(tuple - (a -1) - (b u1) - (c 0x74657374) - (d true) - (e (some true)) - (f none) - (g SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B) - (h SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B.test) - (i (ok true)) - (j (err false)) - (k (list true false)) - (l (tuple (a true) (b false))) - (m "hello world") - (n u"hello \u{1234}"))` -``` diff --git a/i18n/id/docusaurus-plugin-content-docs/current/blockchain/index.md b/i18n/id/docusaurus-plugin-content-docs/current/blockchain/index.md deleted file mode 100644 index 13db24ec30..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/blockchain/index.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: Blockchain -description: Stacks Blockchain -sidebar_position: 6 ---- - -Below is a guide to start working locally with the Stacks Blockchain. - -Code repository is [here](https://github.com/stacks-network/stacks-blockchain). - -## Getting started with the Stacks Blockchain - -### Download and build stacks-blockchain - -The first step is to ensure that you have Rust and the support software installed. - -```bash -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -``` - -:::info -For building on Windows, follow the rustup installer instructions at https://rustup.rs/ -::: - -From there, you can clone the Stacks Blockchain repository: - -```bash -git clone --depth=1 https://github.com/stacks-network/stacks-blockchain.git - -cd stacks-blockchain -``` - -Then build the project: - -```bash -cargo build -``` - -Run the tests: - -```bash -cargo test testnet -- --test-threads=1 -``` - -### Encode and sign transactions - -Here, we have generated a keypair that will be used for signing the upcoming transactions: - -```bash -cargo run --bin blockstack-cli generate-sk --testnet - -# Output -# { -# secretKey: "b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001", -# publicKey: "02781d2d3a545afdb7f6013a8241b9e400475397516a0d0f76863c6742210539b5", -# stacksAddress: "ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH" -# } -``` - -This keypair is already registered in the `testnet-follower-conf.toml` file, so it can be used as presented here. - -We will interact with the following simple contract `kv-store`. In our examples, we will assume this contract is saved to `./kv-store.clar`: - -```scheme -(define-map store { key: (string-ascii 32) } { value: (string-ascii 32) }) - -(define-public (get-value (key (string-ascii 32))) - (match (map-get? store { key: key }) - entry (ok (get value entry)) - (err 0))) - -(define-public (set-value (key (string-ascii 32)) (value (string-ascii 32))) - (begin - (map-set store { key: key } { value: value }) - (ok true))) -``` - -We want to publish this contract on chain, then issue some transactions that interact with it by setting some keys and getting some values, so we can observe read and writes. - -Our first step is to generate and sign, using your private key, the transaction that will publish the contract `kv-store`. To do that, we will use the subcommand `blockstack-cli` that has the following usage: - -```bash -blockstack-cli (options) publish [publisher-secret-key-hex] [fee-rate] [nonce] [contract-name] [file-name.clar] -``` - -With the following arguments: - -```bash -cargo run --bin blockstack-cli publish b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 515 0 kv-store ./kv-store.clar --testnet -``` - -The `515` is the transaction fee, denominated in microSTX. Right now, the testnet requires one microSTX per byte minimum, and this transaction should be less than 515 bytes. The third argument `0` is a nonce, that must be increased monotonically with each new transaction. - -This command will output the **binary format** of the transaction. In our case, we want to pipe this output and dump it to a file that will be used later in this tutorial. - -```bash -cargo run --bin blockstack-cli publish b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 515 0 kv-store ./kv-store.clar --testnet | xxd -r -p > tx1.bin -``` - -### Run the testnet - -You can observe the state machine in action locally by running: - -```bash -cargo stacks-node start --config=./testnet/stacks-node/conf/testnet-follower-conf.toml -``` - -`testnet-follower-conf.toml` is a configuration file that you can use for setting genesis balances or configuring Event observers. You can grant an address an initial account balance by adding the following entries: - -``` -[[ustx_balance]] -address = "ST2VHM28V9E5QCRD6C73215KAPSBKQGPWTEE5CMQT" -amount = 100000000 -``` - -The `address` field is the Stacks testnet address, and the `amount` field is the number of microSTX to grant to it in the genesis block. The addresses of the private keys used in the tutorial below are already added. - -### Publish your contract - -Assuming that the testnet is running, we can publish our `kv-store` contract. - -In another terminal (or file explorer), you can move the `tx1.bin` generated earlier, to the mempool: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx1.bin http://localhost:20443/v2/transactions -``` - -In the terminal window running the testnet, you can observe the state machine's reactions. - -### Reading from / Writing to the contract - -Now that our contract has been published on chain, let's try to submit some read / write transactions. We will start by trying to read the value associated with the key `foo`. - -To do that, we will use the subcommand: - -```bash -cargo run --bin blockstack-cli contract-call --help -``` - -With the following arguments: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 1 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store get-value -e \"foo\" --testnet | xxd -r -p > tx2.bin -``` - -`contract-call` generates and signs a contract-call transaction. - -We can submit the transaction by moving it to the mempool path: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx2.bin http://localhost:20443/v2/transactions -``` - -Similarly, we can generate a transaction that would be setting the key `foo` to the value `bar`: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 2 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store set-value -e \"foo\" -e \"bar\" --testnet | xxd -r -p > tx3.bin -``` - -And submit it by moving it to the mempool path: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx3.bin http://localhost:20443/v2/transactions -``` - -Finally, we can issue a third transaction, reading the key `foo` again, for ensuring that the previous transaction has successfully updated the state machine: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 3 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store get-value -e \"foo\" --testnet | xxd -r -p > tx4.bin -``` - -And submit this last transaction by moving it to the mempool path: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx4.bin http://localhost:20443/v2/transactions -``` - -Congratulations, you can now [write your own smart contracts with Clarity](write-smart-contracts/). diff --git a/i18n/id/docusaurus-plugin-content-docs/current/blockchain/networks.md b/i18n/id/docusaurus-plugin-content-docs/current/blockchain/networks.md deleted file mode 100644 index fe9725352c..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/blockchain/networks.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Stacks Blockchain Networks -description: Stacks Blockchain Networks -sidebar_position: 3 ---- - -### Stacks Blockchain Networks - -- [x] **Krypton** is a Stacks 2 testnet with a fixed, two-minute block time, called `regtest`. Regtest is generally unstable for regular use, and is reset often. See the [regtest documentation](understand-stacks/testnet) for more information on using regtest. - -- [x] **Testnet** (old Xenon) is the Stacks 2 public testnet, which runs PoX against the Bitcoin testnet. It is the full implementation of the Stacks 2 blockchain, and should be considered a stable testnet for developing Clarity smart contracts. See the [testnet documentation](understand-stacks/testnet) for more information on the public testnet. - -- [x] **Mainnet** is the fully functional Stacks 2 blockchain, see the [Stacks overview](understand-stacks/) for information on running a Stacks node, mining, stacking, and writing Clarity smart contracts. diff --git a/i18n/id/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md b/i18n/id/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md deleted file mode 100644 index e7ec7fb2dd..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: API Blockchain Stacks -description: Berinteraksi dengan Blockchain Stacks 2.0 melalui API -sidebar_position: 4 ---- - -## Pengantar - -:::tip API Documentation Official API Documentation is available [here](https://stacks-network.github.io/stacks-blockchain/). ::: - - -API Blockchain Stacks 2.0 memungkinkan Anda untuk melakukan query blockchain Stacks 2.0 dan berinteraksi dengan kontrak pintar. Dibangun untuk menjaga tampilan halaman dari Stacks 2.0 Blockchain. - -:::caution The RESTful API is developed by Hiro. Hiro juga melakukan hosting noda API publik untuk kemudahan onboarding. Dalam menggunakannya, Anda harus mempercayai server yang dihosting, memberikan pengalaman onboarding yang lebih cepat. You can [run your own API server](https://docs.hiro.so/get-started/running-api-node) ::: - -API JSON RESTful dapat digunakan tanpa otorisasi apa pun. Jalur dasar untuk API adalah: - -```bash -# for mainnet, replace `testnet` with `mainnet` -https://stacks-node-api.testnet.stacks.co/ -``` - -:::note This documentation only covers endpoints that are exposed on a Stacks node, referred to as the RPC API. Untuk dokumentasi lengkap tentang API RESTful, lihat [referensi API Hiro](https://docs.hiro.so/api). ::: - -### API RPC Noda Stacks - -[Implementasi noda-stacks](https://github.com/stacks-network/stacks-blockchain/) mengekspos endpoint RPC JSON. - -Semua `/v2/` merutekan proxy ke Noda Stacks yang dihosting oleh Hiro. Untuk arsitektur tanpa kepercayaan, Anda harus membuat permintaan ini ke noda yang dihosting sendiri. - -## Endpoint API RPC Noda Stacks yang diproxy - -API Blockchain Stacks 2.0 dihosting secara terpusat. Namun, setiap noda Stacks yang berjalan memperlihatkan API RPC, yang memungkinkan Anda berinteraksi dengan blockchain yang mendasarinya. Alih-alih menggunakan API yang dihosting secara terpusat, Anda dapat langsung mengakses API RPC dari noda yang dihosting secara lokal. - -:::tip -The Stacks Blockchain API proxies to Node RPC endpoints -::: - -Meskipun Noda RPC API tidak memberikan fungsionalitas yang sama seperti API Blockchain Stacks 2.0 yang dihosting, Anda mendapatkan fungsionalitas serupa dengan cara yang dicakupkan ke noda tertentu. API RPC mencakup endpoint berikut: - -- [POST /v2/transactions](https://docs.hiro.so/api#operation/post_core_node_transactions) -- [GET /v2/contracts/interface/{contract_address}/{contract_name}](https://docs.hiro.so/api#operation/get_contract_interface) -- [POST /v2/map_entry/{contract_address}/{contract_name}/{map_name}](https://docs.hiro.so/api#operation/get_contract_data_map_entry) -- [GET /v2/contracts/source/{contract_address}/{contract_name}](https://docs.hiro.so/api#operation/get_contract_source) -- [GET /v2/accounts/{principal}](https://docs.hiro.so/api#operation/get_account_info) -- [POST /v2/contracts/call-read/{contract_address}/{contract_name}/{function_name}](https://docs.hiro.so/api#operation/call_read_only_function) -- [GET /v2/fees/transfer](https://docs.hiro.so/api#operation/get_fee_transfer) -- [GET /v2/info](https://docs.hiro.so/api#operation/get_core_api_info) - -:::caution If you run a local node, it exposes an HTTP server on port `20443`. Endpoint info adalah `localhost:20443/v2/info`. ::: diff --git a/i18n/id/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md b/i18n/id/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md deleted file mode 100644 index 71e3542302..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Stacks Releases -description: Stacks Blockchain Releases -sidebar_position: 2 ---- - -:::info -This page needs contributions. Help us improve it. -::: - -### Stacks Blockchain Releases - -All releases are published [here](https://github.com/stacks-network/stacks-blockchain/releases). Most important ones are described below. - -### Stacks 2.1 - -Scheduled for release at the end of 2022. - -More information on [what to expect with Stacks 2.1](https://stacks.org/stacks-21-what-to-expect). - -#### Stacks 2.05 -Activated on [Bitcoin block 713000](https://explorer.stacks.co/txid/0xece8e369310b5ff9b92ef11181ae0d2457ac0c821376d4a96c4998763e22ad04?chain=mainnet). - -This breaking change enables storage cost for list to be based on actual length and change in number of indexed I/O operations. More info on this [blog post](https://www.stacks.org/stacks-2-05?ref=docs-website). - -#### Stacks 2.0 -Activated on January 14th 2021 - -This hard fork enables Stacking, Clarity smart contracts, scalable transactions, and also building directly on Bitcoin. More info [here](https://forum.stacks.org/t/path-to-mainnet-for-stx-holders-things-to-know-ahead-of-stacks-2-0/11529). - -#### Stacks Genesis -Released on 2018, October 30th UTC+6 at Bitcoin block height 547921 - -This hard fork addresses registration of digital assets with Stacks token and also distribution of Stacks token to the existing purchasers. More info [here](https://blog.blockstack.org/the-launch-of-the-stacks-genesis-block/?ref=docs-website). - diff --git a/i18n/id/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md b/i18n/id/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md deleted file mode 100644 index a7d508d0e3..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Tips penerapan -description: Mempelajari beberapa metode umum untuk menerapkan aplikasi Anda. ---- - -## Pengantar - -Aplikasi Stacks adalah aplikasi web yang mengautentikasi pengguna dengan Stacks Auth dan menyimpan data dengan Gaia. Kedua teknologi ini dapat diakses dari sisi klien. Dengan demikian, desain dan pengoperasian aplikasi Stacks cenderung sederhana, karena dalam banyak kasus, aplikasi tersebut tidak perlu menghosting apa pun selain aset aplikasi. - -## Tempat untuk menerapkan aplikasi Anda - -Sebelum pengguna dapat berinteraksi dengan aplikasi Anda, Anda harus menerapkannya pada server yang dapat diakses melalui internet. Untuk memulai penerapan, Anda harus melakukan hal di bawah ini: - -- Mengkonfigurasikan atau menyesuaikan file pada direktori `public`. -- Membangun situs aplikasi Anda untuk penerapan. -- Menyalin file aplikasi yang Anda buat ke server produksi Anda. - -Jika Anda pertama kali mengisi aplikasi dengan generator aplikasi Stacks, aplikasi Anda berisi blok awal untuk mengkonfigurasi, membangun, dan menerapkan aplikasi Anda. Misalnya, template React membuat perancah dengan blok penyusun berikut. - -| File atau Direktori | Deskripsi | -| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| node_modules/react-scripts | Satu set skrip dapat membantu Anda memulai proyek React tanpa mengkonfigurasi, jadi Anda tidak perlu menyiapkan proyek Anda sendiri. | -| package.json | Berisi bagian skrip yang menyertakan referensi ke skrip-react, yang merupakan dependensi. Skrip ini membuat direktori build yang berisi file Anda untuk penerapan. | -| public/favicon.ico | Contoh ikon pintasan. | -| public/index.html | Halaman entri untuk aplikasi. | -| public/manifest.json | File JSON yang menjelaskan aplikasi web Anda ke browser. | -| cors | Berisi contoh file penerapan untuk konfigurasi permintaan lintas-asal. | - -Jika Anda menggunakan generator untuk membuat perancah JavasScript atau Vue, file konfigurasi proyek Anda akan berbeda. - -Terlepas dari perancah mana yang Anda gunakan, Anda harus menyesuaikan dan memperluas perancah dasar ini sesuai kebutuhan aplikasi Anda. Misalnya, Anda mungkin ingin menambahkan lebih banyak properti ke file `manifest.json`. Karena setiap aplikasi berbeda, Stacks Auth tidak dapat memberi Anda petunjuk khusus tentang cara melakukannya. Langkah-langkah yang Anda ambil khusus untuk aplikasi Anda sendiri. - -## Autentikasi Stacks dan penerapannya - -Saat aplikasi Anda mengautentikasi pengguna dengan Stacks, Wallet Stacks pada URL meminta sumber daya (manifes aplikasi) dari DApp Anda. Permintaan untuk sumber daya di luar asal (Wallet Stacks) disebut sebagai _permintaan lintas-asal_(COR). Mendapatkan data dengan cara ini bisa berisiko, jadi Anda harus mengkonfigurasi keamanan situs web Anda untuk memungkinkan interaksi lintas asal. - -Anda dapat menganggap interaksi CORS sebagai gedung apartemen dengan Keamanan. Misalnya, jika Anda perlu meminjam tangga, Anda dapat meminta tetangga di gedung Anda yang memilikinya. Keamanan kemungkinan besar tidak akan bermasalah dengan permintaan ini (yaitu, sama-asal, gedung Anda). Jika Anda memerlukan alat tertentu, dan Anda memesannya dikirim dari toko perangkat keras online (yaitu, lintas-asal, situs lain), Keamanan dapat meminta identifikasi sebelum mengizinkan petugas pengiriman masuk ke gedung apartemen. (Credit: Codecademy) - -Cara Anda mengkonfigurasi COR bergantung pada perusahaan yang Anda gunakan untuk menghost aplikasi web Anda. Generator aplikasi menambahkan direktori `cors` ke perancah aplikasi Anda. Direktori ini berisi file untuk Netlify (`_headers` dan `_redirects`) serta satu untuk Firebase (`firebase.json`). Konfigurasi pada direktori `cors` membuat file `manifest.json` aplikasi Anda dapat diakses oleh aplikasi lain (misalnya, ke Browser Stacks). Jika Anda menerapkan ke layanan selain Netlify atau Firebase, Anda harus mengkonfigurasi CORS pada layanan tersebut untuk menyertakan header berikut saat menayangkan `manifest.json`: - -```html -Access-Control-Allow-Origin: * Access-Control-Allow-Headers: "X-Requested-With, Content-Type, -Origin, Authorization, Accept, Client-Security-Token, Accept-Encoding" Access-Control-Allow-Methods: -"POST, GET, OPTIONS, DELETE, PUT" -``` - -Lihat dokumentasi untuk layanan hosting Anda untuk mempelajari cara mengkonfigurasi CORS pada layanan tersebut. - -## Penerapan dan Radiks - -Jika Anda menerapkan aplikasi Stacks yang menggunakan [Radiks](https://github.com/stacks-network/radiks), penerapan Anda mencakup server dan komponen database. Anda harus mempertimbangkan hal ini saat menerapkan aplikasi Anda. Anda mungkin ingin memilih layanan seperti [Heroku](https://www.heroku.com) atau [Digital Ocean](https://www.digitalocean.com) jika aplikasi Anda menggunakan Radiks. diff --git a/i18n/id/docusaurus-plugin-content-docs/current/build-apps/index.md b/i18n/id/docusaurus-plugin-content-docs/current/build-apps/index.md deleted file mode 100644 index e2f46e4f1e..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/build-apps/index.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Membangun aplikasi dengan Stacks -description: Mengautentikasi pengguna, Menandatangani transaksi, dan menyimpan data dengan blockchain Stacks -sidebar_position: 3 -sidebar_label: Build apps ---- - -## Pengantar - -Aplikasi yang dibuat dengan blockchain Stacks memberi pengguna kendali atas identitas digital, aset, dan data mereka. - -Tidak seperti kebanyakan aplikasi berbasis cloud, mereka "terdesentralisasi" karena tidak bergantung pada platform, server, atau database terpusat untuk bisa berfungsi. Sebaliknya, mereka menggunakan blockchain Stacks untuk mengautentikasi pengguna dan memfasilitasi permintaan baca dan tulis untuk mereka tanpa satu titik kegagalan atau kepercayaan. - -Stacks menyediakan tiga fungsi utama untuk membangun aplikasi: - - - -- **Autentikasi**: Mendaftarkan dan login pengguna dengan identitas di blockchain Stacks -- **Penandatanganan transaksi**: Meminta pengguna untuk menandatangani dan menyiarkan transaksi ke blockchain Stacks -- **Data storage**: Save and retrieve data for users with [Gaia](../gaia) - - -Ketiga integrasi ini dapat digunakan bersama untuk menciptakan pengalaman pengguna baru yang kuat yang menyaingi atau melampaui aplikasi tradisional—semuanya untuk melindungi hak digital pengguna Anda. - -Meskipun integrasi dimungkinkan untuk semua jenis aplikasi, sebagian besar sumber daya yang tersedia di sini adalah untuk pengembang web yang berpengalaman dengan JavaScript. Lihat [Dokumen developer Hiro](https://docs.hiro.so) untuk informasi selengkapnya tentang pustaka pengembangan aplikasi yang tersedia untuk Stacks. - -## [Referensi](references) - -[Autentikasi](references/authentication) - -[BNS](references/bns) - -[Gaia](../gaia/) - diff --git a/i18n/id/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md b/i18n/id/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md deleted file mode 100644 index f7dddad79c..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: NoCodeClarity -description: Launch apps for the Stacks blockchain through no code platforms like Bubble. ---- - -## Pengantar - -![](https://d1muf25xaso8hp.cloudfront.net/https%3A%2F%2Fs3.amazonaws.com%2Fappforest_uf%2Ff1653407713550x759333524803365600%2FLogo%2520of%2520NoCodeClarity.png?w=179&h=84&auto=compress&dpr=1&fit=max) - -[NoCodeClarity](https://nocodeclarity.com) allows people to create applications for the Stacks blockchain without coding. - -## Stacks Plug-In on bubble - -The [Stacks-No-Code-Plugin](https://bubble.io/plugin/the-stacks-plug-in-1645467277638x949839693014368300) released in May 2022 and it can easily be installed on Bubble with a few clicks allowing users to deploy applications with no coding knowledge. [Bubble](https://bubble.io/blog/explaining-bubble-to-investors/) is the first No Code platform that the Stacks plugin launched on. More platforms are in the roadmap of NoCodeClarity, founded by Christopher Perceptions and Sergio Gongora. The Stacks plugin was created through the support of the Stacks Foundation via a grant in January 2022 and NoCodeClarity was awarded a $100,000 grant in June 2022 to expand the roadmap. - -Additional [instructions](https://s3.amazonaws.com/appforest_uf/f1654202471526x991633667675927800/Instructions%20v2.docx.pdf) are also available. Tutorials and step by step guides will be released soon. - -The Stacks-No-Code-Plugin code is [publicly available on Github](https://github.com/nocodeclarity/Stacks-No-Code-Plugin). - -![](/img/bubble-stacks-plugin.png) - -## Demo page - -A demo page is available [here](https://test-stacks-plugin.bubbleapps.io/version-test). - -## NoCodeClarity videos - -NodeCodeClarity has their own [youtube channel](https://www.youtube.com/channel/UC9Ep0VQ-GQ-yDzt-wmIElRA). - -Videos: - -* [NoCodeClarity Setup](https://www.youtube.com/watch?v=WanXlpBGl0w) -* [NoCodeClarity - Part 1 of the plugin](https://www.youtube.com/watch?v=o6d3hrzNqVI&t=248s) -* [NoCodeClarity - Part 2 of the plugin](https://www.youtube.com/watch?v=0rzMdsrRg80) -* [Sneak Peek of the No Code Stacks Wallet Template](https://www.youtube.com/watch?v=Xe6Yv0rF6XM) \ No newline at end of file diff --git a/i18n/id/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md b/i18n/id/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md deleted file mode 100644 index 8333be2974..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Autentikasi -description: Daftar dan masuk pengguna menggunakan identitas pada blockchain Stacks ---- - -## Pengantar - -Panduan ini menjelaskan bagaimana autentikasi dilakukan pada blockchain Stacks. - -Autentikasi menyediakan cara bagi pengguna untuk mengidentifikasi diri mereka ke aplikasi sambil mempertahankan kontrol penuh atas kredensial dan detail pribadinya. Ini dapat diintegrasikan sendiri atau digunakan bersama dengan [penandatanganan transaksi](https://docs.hiro.so/get-started/transactions#signature-and-verification) dan [penyimpanan data](https://docs.stacks.co/gaia/overview), yang merupakan prasyarat. - -Users who register for your app can subsequently authenticate to any other app with support for the [Blockchain Naming System](bns) and vice versa. - -## Cara kerjanya - -Alur autentikasi dengan Stacks mirip dengan alur klien-server biasa yang digunakan oleh layanan masuk terpusat (misalnya, OAuth). Namun, dengan Stacks alur autentikasi terjadi sepenuhnya di sisi klien. - -Aplikasi dan autentikator, seperti [Wallet Stacks](https://www.hiro.so/wallet/install-web), berkomunikasi selama alur autentikasi dengan meneruskan dua token. Aplikasi yang melakukan permintaan mengirimkan token `authRequest` kepada autentikator. Setelah pengguna menyetujui autentikasi, autentikator merespons aplikasi dengan token `authResponse`. - -Token ini didasarkan pada [standar JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) dengan dukungan tambahan untuk kurva `secp256k1` yang digunakan oleh Bitcoin dan banyak mata uang kripto lainnya. Mereka diteruskan melalui string kueri URL. - -Saat pengguna memilih untuk mengautentikasi aplikasi, itu akan mengirimkan token `authRequest` ke autentikator melalui string kueri URL dengan parameter yang bernama sama yaitu: - -`https://wallet.hiro.so/...?authRequest=j902120cn829n1jnvoa...` - -Saat autentikator menerima permintaan, autentikator akan menghasilkan token `authResponse` untuk aplikasi dengan menggunakan _kunci transit sementara_ . Kunci transit sementara hanya digunakan untuk contoh aplikasi tertentu, dalam hal ini, untuk menandatangani `authRequest`. - -Aplikasi menyimpan kunci transit sementara selama pembuatan permintaan. Bagian publik dari kunci transit diteruskan dalam token `authRequest`. Autentikator menggunakan bagian publik dari kunci untuk mengenkripsi _kunci privat aplikasi_ yang dikembalikan melalui `authResponse`. - -Autentikator membuat kunci privat aplikasi dari _identitas alamat kunci privat_ pengguna dan domain aplikasi. Kunci privat aplikasi memiliki tiga fungsi: - -1. Digunakan untuk membuat kredensial yang memberikan akses aplikasi ke keranjang penyimpanan di hub Gaia pengguna -2. Digunakan dalam enkripsi ujung-ke-ujung dari file yang disimpan untuk aplikasi di penyimpanan pengguna Gaia. -3. Berfungsi sebagai rahasia kriptografi yang dapat digunakan aplikasi untuk melakukan fungsi kriptografi lainnya. - -Terakhir, kunci privat aplikasi bersifat deterministik, artinya kunci privat yang sama akan selalu dibuat untuk alamat dan domain Stacks tertentu. - -The first two of these functions are particularly relevant to [data storage with Stacks.js](https://docs.stacks.co/docs/gaia). - -## Pasangan kunci - -Autentikasi dengan Stacks akan membuat ekstensif jika menggunakan kriptografi kunci publik secara umum dan ECDSA dengan kurva `secp256k1` secara khusus. - -Bagian berikut menjelaskan tiga pasangan kunci publik-privat yang digunakan, termasuk bagaimana mereka dibuat, di mana mereka digunakan dan kepada siapa kunci privat diungkapkan. - -### Kunci privat transit - -Privat transit adalah kunci sementara yang digunakan untuk mengenkripsi rahasia yang perlu diteruskan dari autentikator ke aplikasi selama proses autentikasi. Ini dibuat secara acak oleh aplikasi di awal respons autentikasi. - -Kunci publik yang sesuai dengan kunci privat transit disimpan dalam susunan elemen tunggal dalam `public_keys` dari token permintaan autentikasi. Autentikator mengenkripsi data rahasia seperti kunci privat aplikasi menggunakan kunci publik ini dan mengirimkannya kembali ke aplikasi saat pengguna masuk ke aplikasi. Kunci privat transit menandatangani permintaan autentikasi aplikasi. - -### Identitas alamat kunci privat - -Identitas alamat kunci privat berasal dari frasa keychain pengguna dan merupakan kunci privat dari nama pengguna Stacks yang dipilih pengguna untuk masuk ke aplikasi. Ini merupakan rahasia yang dimiliki oleh pengguna dan jangan pernah meninggalkan rahasia pengguna dari autentikator. - -Kunci privat ini menandatangani token respons autentikasi untuk aplikasi yang menunjukkan bahwa pengguna telah menyetujui masuk ke aplikasi tersebut. - -### Kunci privat aplikasi - -Kunci privat aplikasi adalah kunci privat khusus aplikasi yang dihasilkan dari identitas alamat kunci privat pengguna menggunakan `domain_name` sebagai masukan. - -Kunci privat aplikasi dibagikan secara aman dengan aplikasi pada setiap autentikasi, dan dienkripsi oleh autentikator dengan kunci publik transit. Karena kunci transit hanya disimpan di sisi klien, ini akan mencegah serangan man-in-the-middle di mana server atau penyedia internet berpotensi mengintip kunci privat aplikasi. diff --git a/i18n/id/docusaurus-plugin-content-docs/current/build-apps/references/bns.md b/i18n/id/docusaurus-plugin-content-docs/current/build-apps/references/bns.md deleted file mode 100644 index 4e96898511..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/build-apps/references/bns.md +++ /dev/null @@ -1,240 +0,0 @@ ---- -title: Sistem Penamaan Blockchain -description: Mengikat nama pengguna Stacks ke status luar-rantai ---- - -Blockchain Naming System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of control. - -Blockchain Stacks V1 mengimplementasikan BNS melalui operasi nama urutan pertama. Di Stacks V2, BNS diimplementasikan melalui kontrak pintar yang dimuat selama blok genesis. - -Nama-nama di BNS memiliki tiga properti: - -- **Nama yang unik secara global.** Protokol tidak mengizinkan tubrukan nama, dan semua noda yang berperilaku baik menyelesaikan nama yang diberikan ke status yang sama. -- **Nama memiliki makna yang manusiawi.** Setiap nama dipilih oleh pembuatnya. -- **Nama dimiliki secara penuh.** Hanya pemilik nama yang dapat mengubah statusnya. Secara khusus, sebuah nama dimiliki oleh satu atau lebih kunci privat ECDSA. - -Blockchain Stacks memastikan bahwa tampilan BNS setiap noda disinkronkan ke semua noda lain di dunia, sehingga kueri pada satu noda akan sama pada noda lain. Noda blockchain Stacks memungkinkan pemilik nama untuk mengikat hingga 40Kb keadaan luar-rantai ke nama mereka, yang akan direplikasi ke semua noda blockchain Stacks lainnya melalui jaringan P2P. - -Konsekuensi terbesar bagi pengembang adalah bahwa di BNS, membaca status nama prosesnya akan cepat dan murah namun menulis status nama prosesnya akan lambat dan mahal. Ini karena mendaftarkan dan mengubah nama memerlukan satu atau lebih transaksi untuk dikirim ke blockchain yang mendasarinya, dan noda BNS tidak akan memprosesnya sampai mereka telah dikonfirmasi. Pengguna dan pengembang perlu memperoleh dan membelanjakan mata uang kripto (STX) yang diperlukan untuk mengirim transaksi BNS. - -## Motivasi di balik sistem penamaan - -Kami mengandalkan sistem penamaan dalam kehidupan sehari-hari, dan sistem penamaan memainkan peran penting dalam banyak aplikasi yang berbeda. Misalnya, ketika Anda mencari teman di media sosial, Anda menggunakan sistem penamaan platform untuk mencari nama agar menemukan profil mereka. Ketika Anda mencari situs web, Anda menggunakan Domain Name Service untuk mencari nama host ke alamat IP hostnya. Ketika Anda memeriksa cabang Git, Anda menggunakan klien Git Anda untuk mencari nama cabang ke commit hash. Ketika Anda mencari kunci PGP milik seseorang di keyserver, Anda mencari ID kunci mereka ke kunci publik mereka. - -Hal seperti apa yang kita inginkan untuk menjadi kenyataan mengenai penamaan? Di BNS, nama bersifat unik secara global, nama memiliki makna yang manusiawi, dan nama dimiliki secara penuh. Namun, jika Anda melihat contoh ini, Anda akan melihat bahwa masing-masing hanya menjamin _dua_ properti ini. Ini untuk membatasi seberapa bergunanya mereka. - -- Di DNS dan media sosial, namanya unik secara global dan dapat dibaca oleh manusia, namun tidak dimiliki secara penuh. Operator sistem memiliki keputusan akhir tentang apa yang diputuskan oleh masing-masing nama. - - - **Permasalahan**: Klien harus mempercayai sistem untuk membuat pilihan yang tepat dalam penyelesaian nama yang diberikan. Ini termasuk mempercayai bahwa tidak seorang pun kecuali administrator sistem yang dapat membuat perubahan ini. - -- Di Git, nama cabang memiliki makna yang manusiawi dan dimiliki secara penuh, namun tidak unik secara global. Dua noda Git yang berbeda dapat mencari nama cabang yang sama ke status repositori berbeda yang tidak terkait. - - - **Permasalahan**: Karena nama dapat merujuk ke dalam keadaan yang bertentangan, pengembang harus mencari tahu beberapa mekanisme lain untuk menyelesaikan ambiguitas. Dalam kasus Git, pengguna harus melakukan intervensi secara manual. - -- Di PGP, nama adalah ID kunci. Mereka unik secara global dan dimiliki secara kriptografis, tetapi tidak dapat dibaca oleh manusia. ID kunci PGP berasal dari kunci yang mereka referensikan. - - **Problem**: These names are difficult for most users to remember since they do not carry semantic information relating to their use in the system. - -Nama BNS memiliki ketiga properti ini, dan tidak memiliki satu permasalahan pun. Ini dapat menjadikannya alat yang ampuh untuk membangun semua jenis aplikasi jaringan. Dengan BNS, kita dapat melakukan hal berikut dan banyak lagi: - -- Membangun domain name services di mana nama host tidak dapat dibajak. -- Membangun platform media sosial di mana nama pengguna tidak dapat dicuri oleh phisher. -- Membangun sistem kontrol versi di mana cabang repositori tidak bertentangan. -- Build public-key infrastructure where it's easy for users to discover and remember each other's keys. - -## Organisasi BNS - -Nama BNS diatur ke dalam hierarki nama global. Ada tiga susunan berbeda dalam hierarki ini yang terkait dengan penamaan: - -- **Ruang nama**. Ruang nama adalah nama level teratas dalam hierarki. Sebuah analogi untuk ruang nama BNS adalah domain level atas DNS. Ruang nama BNS yang ada meliputi: `.id`, `.podcast`, dan `.helloworld`. Semua nama lain merupakan milik satu ruang nama. Siapa pun dapat membuat ruang nama, tetapi agar ruang nama tetap ada, ruang nama harus _diluncurkan_ sehingga siapa pun dapat mendaftarkan nama di dalamnya. Ruang nama tidak dimiliki oleh pembuatnya. - -- **Nama BNS**. Nama BNS adalah nama-nama yang catatannya disimpan langsung di blockchain. Kepemilikan dan status nama-nama ini dikontrol dengan mengirimkan transaksi blockchain. Contoh dari nama BNS yaitu `verified.podcast` dan `muneeb.id`. Siapa pun dapat membuat nama BNS, selama ruang nama yang memuatnya sudah ada. - -- **Subdomain BNS**. Subdomain BNS adalah nama-nama yang catatannya disimpan di luar-rantai, tetapi secara kolektif tertaut ke blockchain. Kepemilikan dan status untuk nama-nama ini berada dalam data jaringan P2P. Sementara subdomain BNS dimiliki oleh kunci privat yang terpisah, pemilik nama BNS harus menyiarkan status subdomain mereka. Contoh dari subdomain yaitu `jude.personal.id` dan `podsaveamerica.verified.podcast`. Tidak seperti ruang nama dan nama BNS, status subdomain BNS adalah _bukan_ bagian dari aturan konsensus blockchain. - -A feature comparison matrix summarizing the similarities and differences between these name objects is presented below: - -| Fitur | **Ruang nama** | **Nama BNS** | **Subdomain BNS** | -| ---------------------------------------- | -------------- | ------------ | ----------------- | -| Unik secara global | X | X | X | -| Bermakna manusiawi | X | X | X | -| Dimiliki oleh kunci privat | | X | X | -| Siapa pun dapat membuat | X | X | [1] | -| Pemilik bisa memperbarui | | X | [1] | -| Status dihosting secara dalam-rantai | X | X | | -| Status dihosting secara luar-rantai | | X | X | -| Perilaku dikontrol oleh aturan konsensus | X | X | | -| Mungkin memiliki tanggal kedaluwarsa | | X | | - -[1] Memerlukan kerjasama pemilik nama BNS untuk menyiarkan transaksinya - -## Ruang nama - -Ruang nama adalah objek penamaan level atas pada BNS. - -Ruang nama mengontrol beberapa properti tentang nama-nama di dalamnya: - -- Seberapa mahal untuk mendaftar -- Seberapa lama dapat bertahan sebelum harus diperbarui -- Siapa (jika ada) yang menerima biaya pendaftaran nama -- Siapa yang diizinkan untuk menyemai ruang nama dengan nama awalnya. - -Pada saat penulisan ini, ruang nama BNS terbesar adalah ruang nama `.id`. Nama dalam ruang nama `.id` dimaksudkan untuk menyelesaikan identitas pengguna. Nama pendek di `.id` lebih mahal daripada nama panjang, dan harus diperbarui oleh pemiliknya setiap dua tahun. Biaya pendaftaran nama tidak dibayarkan kepada siapa pun secara khusus --- mereka dikirim ke "lubang hitam" di mana mereka dianggap tidak dapat dihabiskan (tujuannya adalah untuk mencegah squatter ID). - -Tidak seperti DNS, _siapa saja_ dapat membuat ruang nama dan menyetel propertinya. Ruang nama dibuat berdasarkan yang pertama datang yang pertama dilayani, dan setelah dibuat, mereka bertahan selamanya. - -Namun, membuat ruang nama tidak gratis. Pembuat ruang nama harus _membakar_ mata uang kripto untuk melakukannya. Semakin pendek ruang nama, semakin banyak mata uang kripto yang harus dibakar (ruang nama pendek lebih berharga daripada ruang nama panjang). Misalnya, Blockstack PBC 40 BTC membutuhkan biaya untuk membuat ruang nama `.id` pada tahun 2015 (dalam transaksi `5f00b8e609821edd6f3369ee4ee86e03ea34b890e242236cdb66ef6c9c6a1b281`). - -Namespaces can be between 1 and 19 characters long, and are composed of the characters `a-z`, `0-9`, `-`, and `_`. - -## Subdomain - -Nama BNS dimiliki secara penuh karena pemilik dari kunci privatnya dapat menghasilkan transaksi valid yang memperbarui hash dan pemilik file zonanya. Namun, ada biaya yang mengharuskan pemilik nama untuk membayar transaksi yang mendasarinya di blockchain. Selain itu, pendekatan ini membatasi tingkat pendaftaran nama BNS dan operasi ke bandwidth transaksi blockchain yang mendasarinya. - -BNS mengatasi ini melalui subdomain. **Subdomain BNS** adalah jenis nama BNS yang status dan pemiliknya disimpan di luar blockchain, tetapi keberadaan dan riwayat operasinya ditautkan ke blockchain. Seperti rekan-rekan dalam-rantai mereka, subdomain secara global itu unik, dimiliki secara kuat, dan dapat dibaca oleh manusia. BNS memberi mereka nama status dan kunci publik mereka sendiri. Tidak seperti nama dalam-rantai, subdomain dapat dibuat dan dikelola dengan murah, karena mereka disiarkan ke jaringan BNS secara berkelompok. Satu transaksi blockchain dapat mengirim hingga 120 operasi subdomain. - -Ini dicapai dengan menyimpan catatan subdomain dalam file zona nama BNS. Pemilik nama dalam-rantai menyiarkan operasi subdomain dengan mengkodekan sebagai catatan `TXT` dalam file zona DNS. Untuk menyiarkan file zona, pemilik nama menyetel hash file zona baru dengan transaksi `NAME_UPDATE` dan mereplikasi file zona. Pada gilirannya, mereplikasi semua operasi subdomain yang dikandungnya, dan menautkan kumpulan operasi subdomain ke transaksi dalam-rantai. Aturan konsensus noda BNS memastikan bahwa hanya operasi subdomain yang valid dari transaksi _valid_ `NAME_UPDATE` yang akan disimpan. - -For example, the name `verified.podcast` once wrote the zone file hash `247121450ca0e9af45e85a82e61cd525cd7ba023`, which is the hash of the following zone file: - -```bash -$TTL 3600 -1yeardaily TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxeWVhcmRhaWx5CiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMXllYXJkYWlseS9oZWFkLmpzb24iCg==" -2dopequeens TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAyZG9wZXF1ZWVucwokVFRMIDM2MDAKX2h0dHAuX3RjcCBVUkkgMTAgMSAiaHR0cHM6Ly9waC5kb3Rwb2RjYXN0LmNvLzJkb3BlcXVlZW5zL2hlYWQuanNvbiIK" -10happier TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxMGhhcHBpZXIKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8xMGhhcHBpZXIvaGVhZC5qc29uIgo=" -31thoughts TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzMXRob3VnaHRzCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzF0aG91Z2h0cy9oZWFkLmpzb24iCg==" -359 TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzNTkKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8zNTkvaGVhZC5qc29uIgo=" -30for30 TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzMGZvcjMwCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzBmb3IzMC9oZWFkLmpzb24iCg==" -onea TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiBvbmVhCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vb25lYS9oZWFkLmpzb24iCg==" -10minuteteacher TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxMG1pbnV0ZXRlYWNoZXIKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8xMG1pbnV0ZXRlYWNoZXIvaGVhZC5qc29uIgo=" -36questionsthepodcastmusical TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzNnF1ZXN0aW9uc3RoZXBvZGNhc3RtdXNpY2FsCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzZxdWVzdGlvbnN0aGVwb2RjYXN0bXVzaWNhbC9oZWFkLmpzb24iCg==" -_http._tcp URI 10 1 "https://dotpodcast.co/" -``` - -Setiap catatan `TXT` dalam file zona ini mengkodekan pembuatan subdomain. Misalnya, `1yeardaily.verified.podcast` memutuskan untuk: - -```json -{ - "address": "1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH", - "blockchain": "bitcoin", - "last_txid": "d87a22ebab3455b7399bfef8a41791935f94bc97aee55967edd5a87f22cce339", - "status": "registered_subdomain", - "zonefile_hash": "e7acc97fd42c48ed94fd4d41f674eddbee5557e3", - "zonefile_txt": "$ORIGIN 1yeardaily\n$TTL 3600\n_http._tcp URI 10 1 \"https://ph.dotpodcast.co/1yeardaily/head.json\"\n" -} -``` - -This information was extracted from the `1yeardaily` `TXT` resource record in the zone file for `verified.podcast`. - -### Siklus Subdomain - -Perhatikan bahwa `1yeardaily.verified.podcast` memiliki hash (alamat) kunci publik yang berbeda dari `verified.podcast`. Noda BNS hanya akan memproses operasi subdomain berikutnya pada `1yeardaily.verified.podcast` jika noda tersebut menyertakan tanda tangan dari kunci privat alamat ini. `verified.podcast` tidak dapat menghasilkan pembaruan; hanya pemilik `1yeardaily.verified.podcast yang dapat melakukannya`. - -Siklus subdomain dan operasinya ditunjukkan pada Gambar 2. - -``` - pembuatan pembaruan transfer - subdomain subdomain subdomain -+----------------+ +----------------+ +----------------+ -| cicero | | cicero | | cicero | -| owner="1Et..." | di-ttd | owner="1Et..." | di-ttd | owner="1cJ..." | -| zf0="7e4..." |<--------| zf0="111..." |<--------| zf0="111..." |<---- ... -| seqn=0 | | seqn=1 | | seqn=2 | -| | | sig="xxxx" | | sig="xxxx" | -+----------------+ +----------------+ +----------------+ - | | | - | luar-rantai | | -~ ~ ~ ~ | ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~|~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ | ~ ~ ~ ~ ~ ~ ~ ... - | dalam-rantai | | - V V (hash file zona ) V -+----------------+ +----------------+ +----------------+ -| res_publica.id | | jude.id | | res_publica.id | -| NAME_UPDATE |<--------| NAME_UPDATE |<--------| NAME_UPDATE |<---- ... -+----------------+ +----------------+ +----------------+ - blok blok blok - blockchain blockchain blockchain - - -Gambar 2: Masa pakai subdomain sehubungan dengan operasi nama dalam-rantai. Operasi -subdomain baru hanya akan diterima jika memiliki nomor "seqn=" yang lebih baru, -dan tanda tangan yang valid di "sig=" di atas badan transaksi. Bidang "sig=" -mencakup kunci publik dan tanda tangan, serta kunci publik harus hash ke bidang "addr=" -operasi subdomain sebelumnya. - -Transaksi pembuatan subdomain dan transfer subdomain untuk -"cicero.res_publica.id" disiarkan oleh pemilik "res_publica.id." -Namun, nama dalam-rantai mana pun ("jude.id" dalam kasus ini) dapat menyiarkan pembaruan subdomain untuk "cicero.res_publica.id." -``` - -Operasi subdomain diurutkan berdasarkan nomor urut, dimulai dari 0. Setiap operasi subdomain baru harus menyertakan: - -- Nomor urut berikutnya -- Kunci publik yang di-hash ke alamat transaksi subdomain sebelumnya -- A signature from the corresponding private key over the entire subdomain operation. - -Jika dua operasi subdomain yang ditandatangani dengan benar tetapi bertentangan ditemukan (jika mereka memiliki nomor urut yang sama), salah satu yang terjadi lebih awal dalam riwayat blockchain yang akan diterima. Operasi subdomain yang tidak valid akan diabaikan. - -Combined, this ensures that a BNS node with all of the zone files with a given subdomain's operations will be able to determine the valid sequence of state-transitions it has undergone, and determine the current zone file and public key hash for the subdomain. - -### Pembuatan dan Pengelolaan Subdomain - -Tidak seperti nama dalam-rantai, pemilik subdomain memerlukan bantuan pemilik nama dalam-rantai untuk menyiarkan operasi subdomain mereka. Khususnya: - -- Transaksi pembuatan subdomain hanya dapat diproses oleh pemilik dari nama dalam-rantai yang berbagi sufiksnya. Misalnya, hanya pemilik `res_publica.id` yang dapat menyiarkan transaksi pembuatan subdomain untuk nama subdomain yang diakhiri dengan `.res_publica.id`. -- Transaksi transfer subdomain hanya dapat disiarkan oleh pemilik nama dalam-rantai yang membuatnya. Misalnya, pemilik `cicero.res_publica.id` membutuhkan pemilik `res_publica.id` untuk menyiarkan transaksi transfer subdomain untuk mengubah kunci publik dari `cicero.res_publica.id`. -- Untuk mengirim pembuatan subdomain atau transfer subdomain, semua file zona pemilik nama dalam-rantai harus ada di jaringan Atlas. Ini memungkinkan noda BNS membuktikan _tidak adanya_ operasi pembuatan subdomain dan transfer subdomain yang bertentangan saat memproses file zona baru. -- Transaksi pembaruan subdomain dapat disiarkan oleh _setiap_ pemilik nama dalam-rantai, tetapi pemilik subdomain perlu menemukan orang yang mau bekerja sama. Misalnya, pemilik `verified.podcast` dapat menyiarkan transaksi pembaruan subdomain yang dibuat oleh pemilik `cicero.res_publica.id`. - -That said, to create a subdomain, the subdomain owner generates a subdomain-creation operation for their desired name and gives it to the on-chain name owner. - -Setelah dibuat, pemilik subdomain dapat menggunakan pemilik nama dalam-rantai mana pun untuk menyiarkan operasi pembaruan subdomain. Untuk melakukannya, mereka membuat dan menandatangani operasi subdomain yang diperlukan dan memberikannya kepada pemilik nama dalam-rantai, yang kemudian mengemasnya dengan operasi subdomain lain ke dalam file zona DNS dan menyiarkannya ke jaringan. - -Jika pemilik subdomain ingin mengubah alamat subdomainnya, mereka harus menandatangani operasi transfer subdomain dan memberikannya kepada pemilik nama dalam-rantai yang membuat subdomain. Mereka kemudian mengemasnya ke dalam file zona dan menyiarkannya. - -### Pendaftar Subdomain - -Karena nama subdomain murah, pengembang mungkin cenderung menjalankan pendaftar subdomain atas nama aplikasi mereka. Misalnya, nama `personal.id` digunakan untuk mendaftarkan nama pengguna tanpa mengharuskan mereka membelanjakan Bitcoin apa pun. - -Kami menyediakan implementasi referensi [Pendaftar Subdomain BNS](https://github.com/stacks-network/subdomain-registrar) untuk membantu pengembang menyiarkan operasi subdomain. Pengguna akan tetap memiliki nama subdomain mereka; pendaftar hanya memberi pengembang cara yang nyaman bagi mereka untuk mendaftar dan mengelolanya dalam konteks aplikasi tertentu. - -# Standar BNS dan DID - -BNS names are compliant with the emerging [Decentralized Identity Foundation](http://identity.foundation) protocol specification for decentralized identifiers (DIDs). - -Setiap nama di BNS memiliki DID yang terkait. Format DID untuk BNS adalah: - -```bash - did:stack:v0:{address}-{index} -``` - -Di mana: - -- `{address}` adalah hash kunci publik dalam-rantai (misalnya alamat Bitcoin). -- `{index}` mengacu pada nama `nth` yang dibuat oleh alamat tersebut. - -For example, the DID for `personal.id` is `did:stack:v0:1dARRtzHPAFRNE7Yup2Md9w18XEQAtLiV-0`, because the name `personal.id` was the first-ever name created by `1dARRtzHPAFRNE7Yup2Md9w18XEQAtLiV`. - -Contoh lainnya, DID untuk `jude.id` adalah `did:stack:v0:16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg-1`. Di sini, alamat `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` telah membuat satu nama sebelumnya dalam riwayat sebelum nama ini (yang kebetulan adalah `abcdefgh123456.id`). - -Tujuan DID adalah untuk memberikan pengidentifikasi tak terbatas untuk kunci publik. Kunci publik dapat berubah, namun DID tidak. - -Blockchain Stacks mengimplementasikan metode DID agar kompatibel dengan sistem lain yang menggunakan DID untuk resolusi kunci publik. Agar DID dapat diselesaikan, semua hal berikut harus benar dalam penamaan: - -- Nama harus ada -- Hash file zona nama harus hash dari file zona DNS yang terbentuk dengan baik -- File zona DNS harus ada pada data noda Stacks. -- File zona DNS harus berisi catatan sumber daya `URI` yang mengarah ke JSON Web Token yang ditandatangani -- Kunci publik yang menandatangani Token Web JSON (dan disertakan dengannya) harus di-hash ke alamat yang memiliki nama tersebut - -Tidak semua nama akan memiliki DID yang menjadi kunci publik. Namun, nama yang dibuat oleh alat standar akan memiliki DID yang melakukannya. - -API RESTful sedang dalam pengembangan. - -## Pengkodean DID untuk Subdomain - -Setiap nama dan subdomain di BNS memiliki DID. Pengkodean sedikit berbeda untuk subdomain, sehingga perangkat lunak dapat menentukan jalur kode mana yang harus diambil. - -- Untuk nama BNS dalam-rantai, `{address}` sama dengan alamat Bitcoin yang memiliki nama tersebut. Saat ini, alamat versi byte 0 dan versi byte 5 didukung (yaitu, alamat yang dimulai dengan `1` atau `3`, yang artinya `p2pkh` dan alamat `p2sh`). - -- Untuk subdomain BNS luar-rantai, `{address}` memiliki versi byte 63 untuk subdomain yang dimiliki oleh satu kunci privat, dan versi byte 50 untuk subdomain yang dimiliki oleh sekumpulan m-of-n dari kunci privat. Artinya, alamat DID subdomain masing-masing dimulai dengan `S` atau `M`. - -Bidang `{index}` untuk DID subdomain berbeda dari bidang `{index}` untuk DID nama BNS, meskipun nama dan subdomain dibuat sama. Misalnya, nama `abcdefgh123456.id` memiliki DID `did:stack:v0:16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg-0`, karena itu adalah nama depan yang dibuat oleh `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg`. Namun, `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` _juga_ membuat `jude.statism.id` sebagai nama subdomain pertamanya. DID untuk `jude.statism.id` adalah `did:stack:v0:SSXMcDiCZ7yFSQSUj7mWzmDcdwYhq97p2i-0`. Perhatikan bahwa alamat `SSXMcDiCZ7yFSQSUj7mWzmDcdwYhq97p2i` mengkodekan hash kunci publik yang sama dengan alamat `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` (satu-satunya perbedaan antara dua string ini adalah yang pertama dikodekan base58check dengan versi byte 0, dan yang kedua dikodekan dengan versi byte 63). diff --git a/i18n/id/docusaurus-plugin-content-docs/current/build-apps/references/references.md b/i18n/id/docusaurus-plugin-content-docs/current/build-apps/references/references.md deleted file mode 100644 index f3293b5df1..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/build-apps/references/references.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Referensi -sidebar_label: Referensi ---- - -[Autentikasi](./authentication) - -[Sistem Penamaan Blockchain](./bns) - -[Hiro example apps](https://docs.hiro.so/example-apps) \ No newline at end of file diff --git a/i18n/id/docusaurus-plugin-content-docs/current/contribute/docs.md b/i18n/id/docusaurus-plugin-content-docs/current/contribute/docs.md deleted file mode 100644 index d177a03b4a..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/contribute/docs.md +++ /dev/null @@ -1,207 +0,0 @@ ---- -title: Contribute to docs -description: Learn how this site is built, and how you can contribute to it. ---- - -## Pengantar - -Terima kasih atas minat Anda yang ingin berkontribusi dan membantu membuat dokumen ini menjadi lebih baik. - -This docs site is built on the open source platform [Discosaurus 2](https://docusaurus.io/) and most of its content is written in Markdown files. All of the code for this site is free and open source, located at the [GitHub repository here](https://github.com/stacks-network/docs). - -:::tip Don't know what Markdown is? Want to learn? Here is a [helpful guide](https://guides.github.com/features/mastering-markdown/). - -Don't want to learn it? No need to. Write [in plain text an issue on Github](https://github.com/stacks-network/docs/issues/new?assignees=&labels=documentation&template=add-documentation.md&title=%5BAdd+docs%5D) ::: - -:::info You need a free [Github](https://www.github.com) account to add or edit any content. ::: - -To edit any page, just click on the *Edit this page* button at the bottom of each page and submit your changes online. - -To add new content, they are two different ways to do it, the [easy way](#easy-way) and the [advanced way](#advanced-way). - -## Easy way - -[**Simply click here and enter the text of the article you wish to add.**](https://github.com/stacks-network/docs/issues/new?assignees=&labels=documentation&template=add-documentation.md&title=%5BAdd+docs%5D) - -This will open up an issue on github using our template. -## Advanced way - -For more advanced changes you can follow the next steps. - -You can also test the site locally using this method. -### Steps - -1. Fork the [docs reposiroty](https://github.com/stacks-network/docs) by clicking on the *Fork* button in the upper right of the screen. -2. Clone your fork to your local machine with this command `git clone git@github.com:/docs.git stacks_docs` -3. Enter your project folder `cd stacks_docs` -4. Create a branch `git checkout -b feat/my-feature-branch`. -5. You can optionally preview your changes in real time with: - - `npm install` (to install dependencies). - - `npx docusaurus start` to start a local copy of the site. A web browser will open at http://localhost:3000, so you can see a preview of yourhanges in real time. -6. Make the changes you wish and then commit them with this kind of message: `git commit -am "feat: some new feature or content"`. -7. Push to to GitHub with `git push --set-upstream origin feature/my-feature-branch`. -8. Visit GitHub and make your pull request. - -## Aditional information -### Running and building the site locally (optional) - -You can start the page locally with the following command. This is enough to preview your changes. -```bash -npx docusaurus start -``` - -Before running this command for the first time you will need to run `npm install` to install dependencies. - -The docs site will be accessible at this url: [`http://localhost:3000`](http://localhost:3000). - - -After you finished your changes, you can also build the entire site with the following command (not usually needed): -```bash -npm run build -``` - -:::tip `npx docusaurus start` will only load the default language (english). To test all languages you can build with `npm run build` and then preview your build with `npm run serve`. ::: - -### An alternative: Working in browser - -As an alterative to working locally, you can also use the web IDE gitpod that provides an environment to contribute directly from within your browser. - -You only need to have a github account and open [this link](https://gitpod.io/#https://github.com/stacks-network/docs). - -### Folder structure of the site - -If you are interested in only adding new documentation content to the site, the files that will be important to you are located within `./docs/*`: - -```bash -docs/ - build-apps - contribute/ - faq/ - gaia/ - nodes-and-miners/ - noteworthy-contracts/ - references/ - understand-stack/ - write-smart-contracts/ -``` - -The routing for this site is file based, meaning if you created a folder within `/docs/gaia/` named `testing` and in it a file named `test1.md`, you would be able to navigate to `http://localhost:3000/gaia/testing/test1` and you would see whatever content is in that markdown file. - -All the docs in English are stored in the folder `/docs/`. - -To add new English content simply add a markdown file (.md) into any subfolder in docs, and it will be automatically displayed in the category of that folder. - -All the docs in other languages are stored under the folder `i18n`, but these files should never be edited using GitHub as they are overwritten by Crowdin every time new translations are added. **To make changes in other languages**, you must do so using Crowdin. Please refer to [translations](translations) instead. - -### Frontmatter - -Frontmatter is the top part of any markdown document that is written in a language called [YAML](https://yaml.org/). It looks like this: - -```yaml ---- -title: This is my page title -description: A short, concise sentence describing what is on this page ---- -``` - -Frontmatter gives us the ability to define some things within a page that the site can use, such as a page title or page description. When adding any new page, please include a `title` and `description`. - - - -### Use Conventional Commits - -We use the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) as and commits naming convention. Use it while contributing, please. - -### Code blocks - -To write a code block, you need to wrap your code in ` ```language `, and end your code block with ` ``` `. Here is an example of ` ```clarity `. - -```clarity -(define-data-var counter int 0) - -(define-public (get-counter) - (ok (var-get counter))) -``` -### Admonitions - -You can use the following admonitions to highlight content. - -```md -:::note -Some **content** with _markdown_ `syntax`. -::: - -:::tip -Some **content** with _markdown_ `syntax`. -::: - -:::info -Some **content** with _markdown_ `syntax`. -::: - -:::caution -Some **content** with _markdown_ `syntax`. -::: - -:::danger -Some **content** with _markdown_ `syntax`. -::: - -:::tip My personalized title -Some **content** with _markdown_ `syntax`. -::: -``` - -Which renders: - -:::note - -Some **content** with _markdown_ `syntax`. - -::: - -:::tip - -Some **content** with _markdown_ `syntax`. - -::: - -:::info - -Some **content** with _markdown_ `syntax`. - -::: - -:::caution - -Some **content** with _markdown_ `syntax`. - -::: - -:::danger - -Some **content** with _markdown_ `syntax`. - -::: - -:::tip My personalized title - -Some **content** with _markdown_ `syntax`. - -::: \ No newline at end of file diff --git a/i18n/id/docusaurus-plugin-content-docs/current/contribute/index.md b/i18n/id/docusaurus-plugin-content-docs/current/contribute/index.md deleted file mode 100644 index de4e1d2e68..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/contribute/index.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Contribute -description: Berkontribusi pada ekosistem Stacks. -sidebar_position: 10 -sidebar_label: "Contribute" ---- - -Anda dapat berkontribusi pada ekosistem Stacks dengan berbagai cara: - - - -### Dokumentasi - -Berkontribusi pada Stacks Docs di situs web ini. Info lebih lanjut [di sini](docs). - -### Terjemahan - -Help us reach more people with translations. Detail lebih lanjut [di sini](translations). - - - -### Artikel - -Menulis artikel atau memposting blog tentang Stacks. Tempat yang baik untuk memulai adalah [Forum Stacks](https://forum.stacks.org). - -### Github - -Jika Anda familier dengan Github, Github adalah beberapa repositori dari Ekosistem Stacks yang dapat Anda kontribusikan. - -- https://github.com/stacks-network/ diff --git a/i18n/id/docusaurus-plugin-content-docs/current/contribute/translations.md b/i18n/id/docusaurus-plugin-content-docs/current/contribute/translations.md deleted file mode 100644 index 04cc3c5f7c..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/contribute/translations.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Contribute with translations -description: Want to help tranlating these docs to your local language? ---- - -## Bantuan untuk terjemahan - -Translations are managed with Crowdin. -Anybody can colaborate and no technichal skills are required, as it's all done on the browser. - -Untuk membantu penerjemahan, buka [halaman ini](https://crowdin.com/project/docsstacksco), klik bahasa apa saja dan mulailah menerjemahkan. - -Semua bantuan akan dihargai. - -:::caution -Please don't add any translations to the Github repository, as the translated pages get rewritten from Crowdin. Translations need to be added on Crodin intead. -::: - -### Common issues on translations - -When translating in Crowdin, please only translate the texts and not the html code. - -If you acccidently modify the html tags you will get errors like shown below (`Seems like some formating tags are missing` or `Translation contains tag that source text doesn't have`). These errors will prevent your translation getting published until the tags are left as they were in the original text. - -![](/img/crowdin-qa-issue-formatting_tags_missing.png) ![](/img/crowdin-qa-issue-tag_source.png) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/faq/faq.md b/i18n/id/docusaurus-plugin-content-docs/current/faq/faq.md deleted file mode 100644 index 7416c1b07f..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/faq/faq.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: General FAQs -description: Pertanyaan Umum -sidebar_label: "Pertanyaan Umum (FAQ)" -sidebar_position: 10 ---- - -![](/img/glasses.png) - -## Mengapa transfer saya tertunda? - -Biasanya karena biaya Anda terlalu rendah atau [nonce](#what-is-nonce) Anda salah. - -Informasi lebih lanjut dapat ditemukan [di sini](https://www.hiro.so/wallet-faq/why-is-my-stacks-transaction-pending). Ada juga [praktik terbaik dan masalah yang diketahui](https://forum.stacks.org/t/transactions-in-mempool-best-practices-and-known-issues/11659) serta [mendiagnosis transaksi yang tertunda](https://forum.stacks.org/t/diagnosing-pending-transactions/11908). - -Ada juga [skrip](https://github.com/citycoins/scripts/blob/main/getnetworkstatus.js) ini untuk melihat 200 transaksi pertama atau semua transaksi di mempool, untuk kemudian mengembalikan nilai biaya maksimum dan rata-rata. Kami telah memperhatikan bahwa menggunakan 1,5-2x biaya rata-rata di mempool umumnya akan memproses barang dalam 6-10 blok bahkan selama kemacetan tinggi. - -Ada juga [skrip](https://github.com/citycoins/scripts/blob/main/gettxstatus.js) ini untuk melacak transaksi yang tertunda hingga mencapai status akhir. - -## Apa itu Nonce? - -Sebuah nonce digunakan untuk memastikan bahwa setiap transaksi berjalan dalam urutan yang benar. Nonce dimulai dari 0, jadi transaksi pertama dari sebuah alamat harus disetel ke nonce=0. Anda dapat menemukan alamat dompet Anda dengan mencari alamat di [penjelajah blockchain Stacks](https://explorer.stacks.co/) mana pun. Anda juga dapat menggunakan saldo `$ stx
`. - -Jika Anda memiliki nonce transaksi yang kurang dari nonce akun Anda, transaksi tersebut tidak dapat ditambang dan akan (harus) hilang setelah 256 blok. Ini tidak mempengaruhi transaksi masa depan dan oleh karena itu dapat diabaikan begitu saja, mereka berada di masa lalu. - -Jika Anda memiliki transaksi nonce yang sama dengan nonce akun Anda, maka transaksi tersebut sah dan harus menjadi baris berikutnya yang akan diproses selanjutnya. - -Jika Anda memiliki nonce transaksi yang lebih tinggi dari nonce akun Anda, maka perlu ada rantai transaksi yang dimulai dengan nonce akun Anda agar dapat diproses. Misalnya. Nonce akun Anda adalah 10 tetapi transaksi yang tertunda memiliki nonce 12. Ini tidak dapat ditambang sampai transaksi dengan nonce 10 dan 11 diproses. - -## Apa itu Replace-by-fee (RBF)? - -Transaksi replace-by-fee (RBF) memberi tahu blockchain bahwa Anda ingin mengganti satu transaksi dengan yang lain, sambil menentukan biaya yang lebih tinggi dari biaya transaksi asli. Suatu transaksi dapat diganti dengan **transaksi lain**, dan tidak terbatas pada operasi yang sama. - -Ini dapat digunakan untuk **membatalkan transaksi** secara efektif dengan menggantinya dengan sesuatu yang lain, seperti transfer STX kecil ke alamat lain yang dimiliki. - -Ini dapat digunakan untuk **menaikkan biaya untuk transaksi** yang tertunda sehingga dianggap oleh penambang selama periode kemacetan yang tinggi. Ini juga dapat digunakan untuk _mengirim ulang_ transaksi, dalam arti bahwa transaksi RBF mendapat txid baru dan dipertimbangkan lagi (atau lebih cepat) oleh penambang. Misalnya. Saya mengajukan transaksi saya dengan biaya 1 STX di blok 54.123. Dengan blok 54.133 saya melihat tx saya belum diambil, jadi saya RBF dengan 1.1 STX. Kemudian tunggu 10 blok lagi, dan RBF lagi jika tidak diterima. Ada keseimbangan antara melakukan ini terlalu sering dan menjaga kecepatan yang konsisten, tetapi telah terlihat membantu menyelesaikan transaksi, terutama ketika yang baru terus-menerus membanjiri. - -Transaksi penggantian harus menggunakan nonce yang sama dengan transaksi awal dengan kenaikan biaya minimal 0,000001 STX. Misalnya. Transaksi awal Anda dikenakan biaya 0,03 STX, transaksi RBF baru harus dikenakan biaya 0,030001 STX atau lebih. - -Proses transaksi RBF dengan salah satu dari dua cara berikut: - -- Jika penambang mengambil transaksi asli sebelum transaksi RBF diterima, maka transaksi asli diproses dan transaksi pengganti masuk ke status tidak dapat ditambang. Ini pada akhirnya akan hilang dan tidak mempengaruhi transaksi di masa depan. -- Jika penambang mengambil transaksi yang diganti, maka transaksi baru akan diproses alih-alih yang asli, dan status transaksi awal diatur ke “droppped_replaced_by_fee”. Status ini tidak ditampilkan pada explorer tetapi dapat dilihat saat menanyakan file txid. - -Mengirimkan beberapa transaksi untuk tindakan yang sama dapat memperlambat segalanya dalam beberapa cara. - -- Jika total yang dibelanjakan dalam 2 atau 3 transaksi lebih dari yang dapat dihabiskan dalam satu transaksi, transaksi tersebut tampaknya tidak dapat ditambang. -- Jika biaya untuk beberapa transaksi melebihi saldo STX, transaksi tidak dapat ditambang. - -## What are .btc domains? - -[This forum post](https://forum.stacks.org/t/btc-domains-are-live/12065) explains all the benefits of .btc domains. They can currently be purchased in [btc.us](https://btc.us/) - -## What is the blockchain trilemma? - -## Stacks vs. Solana vs. Polygon: How Do They Compare From a Developer Perspective? - -[This blog post answers the question](https://www.hiro.so/blog/stacks-vs-solana-vs-polygon-how-do-they-compare-from-a-developer-perspective). - -## What Does Lightning’s Taro Proposal Mean for Stacks? - -[This blog post answers the question](https://www.hiro.so/blog/what-does-lightnings-taro-proposal-mean-for-stacks). - - -## Is Stacks a [PoS chain](https://en.wikipedia.org/wiki/Proof_of_stake)?[¹][] - -No. - -The act of block production requires an extrinsic expenditure — it is not tied to owning the native token, as would be required in PoS. The only way to produce blocks in the Stacks chain is to transfer Bitcoin to a predetermined randomized list of Bitcoin addresses. Moreover, the Stacks blockchain can fork, and there exists a protocol to rank forks by quality independent of the set of miners and the tokens they hold. These two properties further distinguish it from PoS chains, which cannot fork due to the inability to identify a canonical fork without trusting a 3rd party to decree a particular fork as valid. The ability to fork allows the Stacks blockchain to survive failure modes that would crash a PoS chain. - -## Is Stacks a [sidechain](https://en.bitcoin.it/wiki/Sidechain)?[¹][] - -No. - -For two key reasons. - -First, the history of all Stacks blocks produced is recorded to Bitcoin. This means that the act of producing a private Stacks fork is at least as hard as reorging the Bitcoin chain. This in turn makes it so attacks on the chain that rely on creating private forks (such as selfish mining and double-spending) are much harder to carry out profitably, since all honest participants can see the attack coming before it happens and have a chance to apply countermeasures. Sidechains offer no such security benefit. - -Second, the Stacks blockchain has its own token; it does not represent pegged Bitcoin. This means that the safety of the canonical fork of the Stacks blockchain is underpinned by its entire token economy’s value, whereas the safety of a sidechain’s canonical fork is underpinned only by whatever system-specific measures incentivize its validators to produce blocks honestly, or the Bitcoin miners’ willingness to process peg-in requests (whichever is the weaker guarantee). - - -## Is Stacks a [layer-2 system](https://academy.binance.com/en/glossary/layer-2) for Bitcoin?[¹][] - -No. - -Stacks blockchain is a layer-1 blockchain, which uses a novel and unique mining protocol called proof-of-transfer (PoX). A PoX blockchain runs in parallel to another blockchain (Bitcoin in Stacks’ case), which it uses as a reliable broadcast medium for its block headers. It's a sovereign system in its own right. The Stacks blockchain state is distinct from Bitcoin, and is wholly maintained by and for Stacks nodes. Stacks transactions are separate from Bitcoin transactions. Layer-2 systems like Lightning are designed to help scale Bitcoin payment transactions, whereas Stacks is designed to bring new use-cases to Bitcoin through smart contracts. Stacks is not designed as a Bitcoin layer-2 scalability solution. - - -## Is Stacks a [merged-mined chain](https://en.bitcoin.it/wiki/Merged_mining_specification)?[¹][] - -No. - -The only block producers on the Stacks chain are Stacks miners. Bitcoin miners do not participate in Stacks block validation, and do not claim Stacks block rewards. Moreover, Stacks is not a [blind merged-mined chain](https://github.com/bitcoin/bips/blob/master/bip-0301.mediawiki), because STX block winners are public and randomly chosen (instead of highest-bid-wins), and its tokens are minted according to a schedule that is independent of the degree of miner commitment or Bitcoin transferred (instead of minted only by one-way pegs from Bitcoin). This ensures that Stacks is able to make forward progress without opt-in from Bitcoin miners, and it ensures that Stacks miners are adequately compensated for keeping the system alive regardless of transaction volume. - -## Whats the difference between Stacks and Ethereum?[²][] -**Computation and Storage** Stacks does all computation and storage outside of the blockchain, and uses the blockchain only as a “shared source of truth” between clients. By contrast, Ethereum does all computation and most application storage in the blockchain itself. Like Ethereum, if two Stacks nodes see the same underlying blockchain, they will independently run the same computations and produce the same state. Unlike Ethereum, there is no Stacks-specific blockchain. - -**Programming Language and Tooling** Stacks’s programming model is based on running off-chain programs. These programs can be written and debugged in any language you want. By contrast, Ethereum’s programming model is based on running on-chain “smart contracts.” These are written and debugged with a whole new set of tools, like Solidity and Serpent. - -**Scalability of On-chain Computation** Stacks is designed around a “virtual chain” concept, where nodes only need to reach consensus on the shared “virtual chain” they’re interested in. Virtual chains do not interact with one another, and a single blockchain can host many virtual chains. Although Stacks’s specific virtual chain is not Turing-complete (i.e. it’s a list of instructions to build the name database), it is possible to create Turing-complete virtual chains like Ethereum. These virtual chains can live in any blockchain for which there exists a driver, and virtual chain clients only need to execute their virtual chain transactions (i.e. Stacks only processes Stacks virtual chain transactions). - -By contrast, because smart contracts run on-chain and can call one another, all Ethereum nodes need to process all smart contracts’ computations in order to reach consensus. This can get expensive as the number of running smart contracts grow, which takes the form of gas fee increases. - -**Scalability of Off-chain Computation** Stacks applications are very similar to Web applications today and almost never need to interact with the blockchain. For most Stacks applications, the blockchain is only used to authenticate the application’s code and data before the user runs it. By contrast, Ethereum applications usually require an application-specific smart contract, and must interact with the blockchain to carry out its operations. - - -[¹]: https://stacks.org/stacks-blockchain -[²]: https://forum.stacks.org/t/what-is-the-difference-between-blockstack-and-ethereum/781 diff --git a/i18n/id/docusaurus-plugin-content-docs/current/gaia/configuration.md b/i18n/id/docusaurus-plugin-content-docs/current/gaia/configuration.md deleted file mode 100644 index 9fa365d7bf..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/gaia/configuration.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Configuration -description: Configuring Gaia Hub ---- - -## Configuration files - -The following configuration files exist in the folder `deploy/configs/gaia/`: - -``` -admin-config.json -hub-config.json -reader-config.json -``` - -## GAIA Admin Service - -You can also use the GAIA Admin Service to remotely administer it with an API Key. It will require you to install `npm` with a `apt install npm`. Once `npm` is installed you can continue with the steps in the [GAIA Admin Service](https://github.com/stacks-network/gaia/blob/master/admin/README.md). - -## Driver Selection - -The Gaia hub currently supports the following drivers: - -``` -'aws' == Amazon S3 -'azure' == Azure Blob Storage -'disk' == Local disk -'google-cloud' === Google Cloud Storage -``` - -Set the driver you wish to use in your [config.json](https://github.com/stacks-network/gaia/blob/master/hub/config.sample.json) file with the `driver` parameter. Many drivers additionally accept the `bucket` parameter, which controls the bucket name that files should be written to. - -These driver may require you to provide additional credentials for performing writes to the backends. See `config.sample.json` for fields for those credentials. In some cases, the driver can use a system configured credential for the backend (e.g., if you are logged into your AWS CLI account, and run the hub from that environment, it won't need to read credentials from your `config.json`). - -:::caution -The disk driver requires a \*nix like filesystem interface, and will not work correctly when trying to run in a Windows environment. -::: - -## Note on SSL - -We _strongly_ recommend that you deploy your Gaia hub with SSL enabled. Otherwise, the tokens used to authenticate with the Gaia hub may be stolen by attackers, which could allow them to execute writes on your behalf. -Configuration options are available to run the hub with an `https` Node.js server. -Otherwise, a reverse proxy web server such as nginx or Apache can be used. - -## Require Correct Hub URL - -If you turn on the `requireCorrectHubUrl` option in your `config.json` file, your Gaia hub will require that authentication requests correctly include the `hubURL` they are trying to connect with. This is used to prevent a malicious gaia hub from using an authentication token for itself on other Gaia hubs. - -By default, the Gaia hub will validate that the supplied URL matches `https://${config.serverName}`, but if there are multiple valid URLs for clients to reach the hub at, you can include a list in your `config.json`: - -```javascript -{ - .... - serverName: "normalserver.com" - validHubUrls: [ "https://specialserver.com/", - "https://legacyurl.info" ] - .... -} -``` - -## The readURL parameter - -By default, the gaia hub drivers will return read URLs which point directly at the written content. For example, an S3 driver would return the URL directly to the S3 file. However, if you configure a CDN or domain to point at that same bucket, you can use the `readURL` parameter to tell the gaia hub that files can be read from the given URL. For example, the `hub.blockstack.org` Gaia Hub is configured to return a read URL that looks like `https://gaia.blockstack.org/hub/`. - -Unset this configuration parameter if you do not intend to deploy any caching. - -## Minimum Proofs Requirement - -The gaia hub can also be configured to require a minimum number of social proofs in a user's profile to accept writes from that user. This can be used as a kind of spam-control mechanism. However, we recommend for the smoothest operation of your gaia hub, to set the `proofsConfig.proofsRequired` configuration key to `0`. - -## CDN & Replicated Hubs - -- https://docs.microsoft.com/en-us/azure/storage/blobs/storage-https-custom-domain-cdn - -- The hub implementation is designed to be ran from a single Node.js instance. If the hub instance is sharded (e.g. replicated hubs via load balancing), then any given `bucket` (identified by URI segment) must be served by the same instance, At least a couple elements of the Gaia Hub depend on this: token invalidation in-memory caching, and resource endpoint 409 contention behavior. diff --git a/i18n/id/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md b/i18n/id/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md deleted file mode 100644 index 558cbb14f5..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Deploy Gaia Hub -description: Steps and tutorials ---- - -## Deploy your GAIA hub - -Tutorials to deploy your own GAIA hub are currently available for [Linux](./setup-linux), [MacOS](./setup-mac) and [Amazon EC2 / CloudFormation](./gaia-on-ec2). - -Regardless of what server the Gaia Hub runs on, the storage it uses can currently be deployed on multiple platforms: - -- Local disk (the server itself) -- Amazon S3 -- Azure Blob Storage -- Google Cloud - -:::tip -Support for IPFS is under development. -::: \ No newline at end of file diff --git a/i18n/id/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md b/i18n/id/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md deleted file mode 100644 index 1653a061ac..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Amazon EC2 -description: Use a template to deploy a Gaia hub on Amazon EC2 -tags: - - tutorial - - gaia ---- - -## Pengantar - -The template provided on this page provides an easy way to deploy a Gaia hub directly to Amazon EC2. You can use this template to deploy your own Gaia hub to your Amazon Web Services (AWS) account. Amazon EC2 is an affordable and convenient cloud computing provider. The template provides a one-click deploy for Amazon EC2 with either S3 or EBS as a storage provider. - -## Prasyarat - -This procedure uses Amazon CloudFormation to configure an EC2 cloud compute provider to run the Gaia hub service with an S3 or EBS provider for file storage. You should have access to an AWS account either through your personal account or through a corporate account. This account should have permissions to create resources. - -Additionally, you must also own a domain name and be able to update the DNS records associated with that domain name. - -## Setup steps - -### Step 1 - Create Stack - -Use a link in the table to launch the [CloudFormation](https://console.aws.amazon.com/cloudformation/) template in the AWS region that you wish to deploy a Gaia hub. - -![Create stack](/img/cloudformation-create-stack.png) - -### Step 2 - Setup stack using template - -You need to configure the template with the appropiate values for your hub and domain it runs on. - -Select `Template is ready` and `Amazon S3 URL` and enter the following Amazon S3 URL: -``` -https://s3-external-1.amazonaws.com/cf-templates-vzldibfi2mw8-us-east-1/2022160J6G-cloudformation.yaml -``` - -If you prefer you can instead select `Template is ready` and `Upload a template file` to upload the template file `cloudformation.yaml`. - -The latest `cloudformation.yaml` file can be downloaded [here](https://raw.githubusercontent.com/stacks-network/gaia/master/deploy/cloudformation.yaml). On most browsers you can right-click on that page and click on `Save page as` to download the file. Alternatively, you can copy/paste the text into a text file called `cloudformation.yaml`. - -Then click `Next`. - -![Specify template](/img/cloudformation-specify-template.png) - -### Step 3 - Specify stack details - -Specify the stack details and then click `Next`: ![Specify template](/img/cloudformation-specify-stack-details.png) - -| Bidang | Nilai | Notes | -| --------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Stack name | _a unique name in your AWS account_ | e.g.: my_gaia_hub | -| DomainName | _your-domain_ | | -| EmailAddress | _your email address_ | | -| GaiaBucketName | _S3 bucket name_ | The template combines this name with the stack name to create a unique S3 bucket. The template ignores this field if GaiaStorageType is set to `disk`. | -| GaiaStorageType | `s3` or `disk` | Select the GaiaStorageType of which to use as a backend for the Gaia Hub. Selecting `s3` causes the template to create an S3 bucket based on the name given in the previous field. Selecting `disk` causes the template to attach a separate EBS volume to the EC2 instance for Hub storage. | -| InstaceType | t2.micro | Select the instance type you want. Default value is `t2.micro`. | -| KeyName | | In the KeyName drop-down, select an [EC2 KeyPair](https://console.aws.amazon.com/ec2/v2/home?region=us-east-1#KeyPairs:) to enable SSH access to the EC2 instance. You should download the `.pem` keyfile for this pair from the EC2 console. For more information see the [EC2 key pair documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html#prepare-key-pair) | -| SSHLocation | 0.0.0.0/0 | Leave the SSHLocation field with the default value of `0.0.0.0/0` to enable SSH access from any IP address. If you wish to restrict SSH access to the EC2 instance to a certain IP, you can update this field. | -| SubnetId | _subnetid_ | Select a public subnet | -| VpcId | _vpcid_ | | - -### Step 4 - Configure stack options - -Configure any stack options that fit your desired setup and click `Next`. All these fields are optional. - -![Specify template](/img/cloudformation-stack-options.png) - -### Step 5 - Review - -Review the configuration of your Gaia hub, select the checkbox to acknowledge that AWS may create IAM resources with custom names and click on `Create stack`. - -![Specify template](/img/cloudformation-iam-resources.png) - -### Step 6 - Retrieve the public IP of your Gaia hub - -Your stack can take several minutes to launch. You can monitor the Events tab of your hub to review the current progress of the launch. When the launch is complete, the Outputs tab displays information about the hub. Select the PublicIP and copy it to configure your domain name. - -Create an `A` DNS record pointing to the given IP in your domain. - -Wait a few minutes for the DNS record to propagate, and your should be able to access your Gaia hub with SSH. - -## Accessing your Gaia hub with SSH - -To SSH into your Gaia hub EC2 host directly, you must have the keyfile used in container creation. Access the host with the following command in your terminal: - -```bash -ssh -i admin@ -``` - -:::tip If you can only access SSH with the IP but not with the DNS name and you wish to do so, you can optionally activate it by following these steps: - - Open your [AWS Console](https://console.aws.amazon.com) - Click on `Service` -> VPC - Open Your VPCs - Select your VPC connected to your Gaia Hub - Click `Actions` -> `Edit DNS Hostnames` -> Change `DNS hostnames` to `Enable` -::: -## Graphical representation of the cloudformation template - -![](/img/cloudformation-gaia-template1-designer.png) \ No newline at end of file diff --git a/i18n/id/docusaurus-plugin-content-docs/current/gaia/gaia.md b/i18n/id/docusaurus-plugin-content-docs/current/gaia/gaia.md deleted file mode 100644 index af9898274b..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/gaia/gaia.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Gaia -description: Arsitektur penyimpanan terdesentralisasi untuk data luar-rantai -sidebar_position: 5 -tags: - - gaia ---- - -## Pengantar - -Aplikasi yang dibuat dengan blockchain Stacks menyimpan data luar-rantai menggunakan sistem penyimpanan yang disebut Gaia. - -Sementara metadata transaksional publik paling baik disimpan di blockchain Stacks, data aplikasi pengguna seringkali dapat disimpan lebih efisien dan pribadi di penyimpanan Gaia. - -Menyimpan data dari blockchain memastikan bahwa aplikasi Stacks dapat memberi pengguna kinerja tinggi dan ketersediaan tinggi untuk baca dan tulis data tanpa memperkenalkan pihak kepercayaan pusat. - -:::tip Latest whitepaper of GAIA (May 2022) is available [here](https://dev1-gaia-hub.s3.amazonaws.com/GAIA_Whitepaper.pdf) ::: - -## Memahami Gaia dalam arsitektur Stacks - -Diagram berikut menggambarkan arsitektur Stacks dan tempat Gaia di dalamnya: - -![Arsitektur Stacks](/img/architecture.png) - -Blockchain membutuhkan konsensus di antara sejumlah besar orang, sehingga mereka bisa melambat. Selain itu, blockchain tidak dirancang untuk menampung banyak data. Ini artinya menggunakan blockchain untuk setiap bit data yang mungkin ditulis dan disimpan pengguna itu mahal. Misalnya, bayangkan jika sebuah aplikasi menyimpan setiap tweet dalam rantai. - -Blockchain Stacks mengatasi masalah kinerja menggunakan pendekatan berlapis. Lapisan dasar terdiri dari blockchain Stacks dan Sistem Penamaan Blockchain (BNS). Blockchain mengatur kepemilikan identitas di jaringan Stacks. Identitas dapat berupa nama seperti nama domain, nama pengguna, atau nama aplikasi. - -Ketika identitas dibuat, pembuatannya dicatat di blockchain Stacks. Identitas membentuk data utama yang disimpan ke dalam blockchain Stacks. Identitas ini sesuai dengan perutean data di Stacks OSI. Data perutean disimpan di Jaringan Atlas Peer, lapisan kedua. Setiap noda inti yang bergabung dengan Jaringan Stacks dapat memperoleh seluruh salinan data perutean ini. Stacks menggunakan data perutean untuk mengaitkan identitas (nama domain, nama pengguna, dan nama aplikasi) dengan lokasi penyimpanan tertentu di lapisan akhir, yaitu Sistem Penyimpanan Gaia. - -Sistem Penyimpanan Gaia terdiri dari _layanan hub_ dan sumber daya penyimpanan pada penyedia perangkat lunak cloud. Penyedia penyimpanan dapat berupa penyedia komersial apa pun seperti Azure, DigitalOcean, Amazon EC2, dan sebagainya. Biasanya sumber daya komputasi dan sumber daya penyimpanan berada di vendor cloud yang sama, meskipun ini bukan suatu keharusan. Gaia saat ini memiliki dukungan driver untuk S3, Azure Blob Storage, Google Cloud Platform, dan disk lokal, tetapi model driver juga memungkinkan dukungan backend lainnya. - -Gaia menyimpan data sebagai penyimpanan nilai kunci sederhana. Saat identitas dibuat, penyimpanan data yang sesuai dikaitkan dengan identitas tersebut di Gaia. Saat pengguna masuk ke dApp, proses autentikasi memberikan aplikasi URL hub Gaia, yang kemudian ditulis ke penyimpanan atas nama pengguna tersebut. - -Blockchain Stacks hanya menyimpan data identitas. Data yang dibuat oleh tindakan dari identitas yang disimpan dalam Sistem Penyimpanan Gaia. Setiap pengguna memiliki data profil. Saat pengguna berinteraksi dengan dApp yang terdesentralisasi, aplikasi tersebut menyimpan data aplikasi atas nama pengguna. Karena Gaia menyimpan data pengguna dan aplikasi dari blockchain, Stacks DApp biasanya lebih berkinerja daripada DApps yang dibuat di blockchain lain. - -## Kontrol pengguna atau cara Gaia didesentralisasi? - -Hub Gaia berjalan sebagai layanan yang menulis ke penyimpanan data. Penyimpanan itu sendiri adalah penyimpanan nilai kunci sederhana. Layanan hub menulis ke penyimpanan data dengan meminta token autentikasi yang valid dari pemohon. Biasanya, layanan hub berjalan pada sumber daya komputasi dan penyimpanan itu sendiri pada sumber daya penyimpanan khusus yang terpisah. Biasanya, kedua sumber daya milik penyedia komputasi cloud yang sama. - -![Penyimpanan Gaia](/img/gaia-storage.png) - -Pendekatan Gaia terhadap desentralisasi berfokus pada kontrol pengguna atas data dan penyimpanannya. Pengguna dapat memilih penyedia hub Gaia. Jika pengguna dapat memilih penyedia hub Gaia mana yang akan digunakan, maka pilihan itu adalah semua desentralisasi yang diperlukan untuk mengaktifkan aplikasi yang dikontrol oleh pengguna. Selain itu, Gaia mendefinisikan API seragam untuk aplikasi untuk mengakses data tersebut. - -Kontrol data pengguna terletak pada cara data pengguna diakses. Saat aplikasi mengambil file `data.txt` untuk pengguna tertentu `alice.id`, pencarian akan mengikuti langkah-langkah berikut: - -1. Ambil `zonefile` untuk `alice.id`. -2. Baca URL profilnya dari `zonefile`. -3. Ambil profil Alice. -4. _Verifikasi_ bahwa profil ditandatangani oleh kunci `alice.id` -5. Temukan url read-only dari bagian profil `appsMeta` (mis. `https://example-app.gaia.alice.org`). -6. Ambil file dari `https://example-app.gaia.alice.org/data.txt`. - -Karena `alice.id` memiliki akses ke [zonefile](https://docs.stacks.co/references/bns-contract#name-update), dia dapat mengubah di mana profilnya disimpan. Misalnya, dia dapat melakukan ini jika penyedia layanan atau penyimpanan profil saat ini disepakati. Untuk mengubah tempat penyimpanan profilnya, dia mengubah URL hub Gaia nya ke URL hub Gaia lainnya. Jika pengguna memiliki sumber daya komputasi dan penyimpanan yang cukup, pengguna dapat menjalankan Sistem Penyimpanan Gaia mereka sendiri dan mengabaikan penyedia hub Gaia komersial secara bersamaan. - -:::caution -Users with existing identities cannot yet migrate their data from one hub to another. -::: - -Aplikasi yang menulis langsung atas nama `alice.id` tidak perlu melakukan pencarian. Alih-alih, [Alur autentikasi Stacks](https://stacks.js.org) menyediakan URL hub gaia pilihan Alice ke aplikasi. Alur autentikasi ini _juga_ dalam kontrol Alice karena wallet Alice _harus_ menghasilkan respons autentikasi. - -## Memahami penyimpanan data - -Hub Gaia menyimpan data tertulis _persis_ seperti yang diberikan. Ini menawarkan jaminan minimal tentang data. Hub Gaia tidak memastikan bahwa data diformat secara valid, berisi tanda tangan yang valid, atau dienkripsi. Sebaliknya, filosofi desain menyatakan bahwa masalah ini adalah masalah dari sisi klien. - -Pustaka klien (seperti [`Stacks.js`](https://stacks.js.org/)) mampu memberikan jaminan ini. Definisi liberal dari [prinsip ujung-ke-ujung](https://en.wikipedia.org/wiki/End-to-end_principle) memandu keputusan desain ini. - -Saat aplikasi ditulis ke hub Gaia, token autentikasi, kunci, dan data diteruskan ke hub Gaia. - -![Tulisan Gaia](/img/gaia-writes.png) - -Token memastikan aplikasi memiliki otorisasi untuk menulis ke hub atas nama pengguna. - -## Gaia versus sistem penyimpanan lainnya - -Berikut ini adalah cara Gaia menghadapi sistem penyimpanan terdesentralisasi lainnya. Fitur yang umum untuk semua sistem penyimpanan dihilangkan. - -| Fitur | [Gaia](https://github.com/stacks-network/gaia) | [Sia](https://sia.tech/) | [Storj](https://storj.io/) | [IPFS](https://ipfs.io/) | [DAT](https://datproject.org/) | [SSB](https://www.scuttlebutt.nz/) | -| ----------------------------------------------------- | ---------------------------------------------- | ------------------------ | -------------------------- | ------------------------ | ------------------------------ | ---------------------------------- | -| Pengguna mengontrol tempat data dihosting | X | | | | | | -| Data dapat dilihat di browser Web biasa | X | | | X | | | -| Data dapat dibaca/ditulis | X | | | | X | X | -| Data dapat dihapus | X | | | | X | X | -| Data dapat dicantumkan | X | X | X | | X | X | -| Ruang data yang dihapus dapat diambil kembali | X | X | X | X | | | -| Pencarian data memiliki kinerja yang dapat diprediksi | X | | X | | | | -| Izin menulis dapat didelegasikan | X | | | | | | -| Izin pencantuman dapat didelegasikan | X | | | | | | -| Mendukung banyak backend secara asli | X | | X | | | | -| Data dapat dialamatkan secara global | X | X | X | X | X | | -| Membutuhkan mata uang kripto untuk bekerja | | X | X | | | | -| Data ditujukan untuk konten | | X | X | X | X | X | diff --git a/i18n/id/docusaurus-plugin-content-docs/current/gaia/setup-linux.md b/i18n/id/docusaurus-plugin-content-docs/current/gaia/setup-linux.md deleted file mode 100644 index db427f890a..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/gaia/setup-linux.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: Linux -description: Steps to setup a GAIA hub on a Linux server (fresh install). This example is using Debian, but should work on any Linux distribution. It uses docker compose in the backgroud. -tags: - - tutorial - - gaia ---- - -This configuration will setup the following 4 docker containers: - -- Nginx with certbot on TCP ports 80 and 443. -- Gaia hub on TCP port 3000. -- Gaia admin on TCP port 8009. -- Gaia reader on TCP port 8008 - -**1. Update the system and install the dependencies and software we will use to test:** - -```bash -apt update && apt upgrade -y && apt install -y git vim gnupg jq -``` - -**2. Install [docker](https://docs.docker.com/engine/install/debian/) and [docker-compose](https://docs.docker.com/compose/cli-command/#install-on-linux)** in your OS. -For our example we install _docker_ with: - -```bash -curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg - -echo \ - "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian \ - $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null - -apt update && apt install -y docker-ce docker-ce-cli containerd.io -``` - -Install _docker-compose_ by downloading the [latest-release](https://github.com/docker/compose/releases): - -```bash -VERSION_DC=$(curl --silent https://api.github.com/repos/docker/compose/releases/latest | jq .name -r) -DESTINATION_DC=~/.docker/cli-plugins -mkdir -p ${DESTINATION_DC} -curl -SL https://github.com/docker/compose/releases/download/${VERSION_DC}/docker-compose-linux-x86_64 -o ${DESTINATION_DC}/docker-compose -chmod +x ${DESTINATION_DC}/docker-compose -``` - -**3. Clone the GAIA repository** and enter it's docker directory. - -```bash -git clone https://github.com/stacks-network/gaia.git && cd gaia/deploy/docker -``` - -**4. Copy and edit appropiate .env file**. -In the folder `./deploy/docker/` they are different sample files for different configurations like using aws, azure or disk among others. In this example we will store the data localy so we will copy the _disk_ file and update the domain and email fields. Please change `gaia.site.com` and `gaiarocks@mydomain.com` accordingly. Note you need both for the SSL certificate to be created correctly. - -```bash -export MYGAIADOMAIN=gaia.site.com -export MYGAIAEMAIL=gaiarocks@mydomain.com -cp sample-disk.env disk.env -sed -i 's/my-domain.com/'"$MYGAIADOMAIN"'/g' disk.env -sed -i 's/my-email@example.com/'"$MYGAIAEMAIL"'/g' disk.env - -``` - -**5. Start GAIA HUB service** - -To start GAIA HUB - -```bash -./gaiahub.sh start -``` - -To stop GAIA HUB - -```bash -./gaiahub.sh stop -``` - -To view GAIA HUB status - -```bash -./gaiahub.sh status -``` - -**6. Verify server works locally** with the following command: - -```bash -curl -sk http://localhost/hub_info | jq -``` - -A correct result should look similar to this: - -```bash - { - "challenge_text": "[\"gaiahub\",\"0\",\"gaia-0\",\"blockstack_storage_please_sign\"]", - "latest_auth_version": "v1", - "max_file_upload_size_megabytes": 20, - "read_url_prefix": "https://gaia.site.com/reader/" - } -``` - -**7. Test your GAIA HUB** Running `gaia_test.js` will test your GAIA Hub, by trying to connect to it, uploading a file and downloading it again. - -First install all required dependencies with: - -```bash -npm install -``` - -Then, from the root folder of the project type: - -```bash -node ./deploy/gaia_test.js https://yourgaiaurl -``` - -A correct result will be something like this: - -``` -Will run a test for the GAIA HUB: https://gaia.mydomain.com -Generating some test keys... -Private key: 5aacc60fc2a429e1f02be139f3cac82061c6a980******************** -Public key: 025691f17f2ab80dc4af363bb9c7aac59e9e1db6ae8ff668202582a3f4ec9678ff -Address: 15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS -[DEBUG] connectToGaiaHub: https://gaia.mydomain.com/hub_info -[DEBUG] uploadToGaiaHub: uploading testing.txt to https://gaia.mydomain.com -File uploaded successfully. -Upload to gaia hub thinks it can read it from: https://gaia.mydomain.com/reader/15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS/testing.txt -Hub info thinks it can read it from : https://gaia.mydomain.com/reader/15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS/testing.txt -Let's now try to fetch the uploaded file... -File fetched successfully. Contents of file: GAIA ROCKS! -``` diff --git a/i18n/id/docusaurus-plugin-content-docs/current/gaia/setup-mac.md b/i18n/id/docusaurus-plugin-content-docs/current/gaia/setup-mac.md deleted file mode 100644 index 808833b212..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/gaia/setup-mac.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: MacOS -description: MacOS for local testing/development -tags: - - tutorial ---- - -The following assumes you have [Docker Installed](https://docs.docker.com/docker-for-mac/install/) - -- Recommended to also have [MacOS Homebrew](https://docs.brew.sh/Installation) installed -- Use Homebrew to install jq with `brew install jq` - -In your working directory: - -**1. Clone a copy of the [gaia repo](https://github.com/stacks-network/gaia):** - -```bash -$ git clone -b master --single-branch https://github.com/stacks-network/gaia -``` - -**2. Change your cwd:** - -```bash -$ cd gaia/deploy/docker -``` - -**3. Create a copy of sample-disk.env and fill out the values:** - -``` -$ cp sample-disk.env disk.env -# Update the DOMAIN_NAME variable to `localhost` -``` - -**4. Start the server:** - -``` -$ docker-compose -f docker-compose-base.yaml -f docker-compose-disk.yaml --env-file disk.env up -``` - -**5. Verify the server is responding locally:** - -``` -$ curl -sk https://localhost/hub_info | jq - { - "challenge_text": "[\"gaiahub\",\"0\",\"gaia-0\",\"blockstack_storage_please_sign\"]", - "latest_auth_version": "v1", - "max_file_upload_size_megabytes": 20, - "read_url_prefix": "https://localhost/reader/" - } -``` - -### Modifying the configuration for your gaia-hub - -Two methods exist: - -1. Edit the `gaia/deploy/configs/gaia/hub-config.json` using `vim` or other - -- requires a restart of the containers: `docker-compose -f docker-compose-base.yaml -f docker-compose-disk.yaml --env-file disk.env restart` - -2. Use the running `admin` container to modify any config values, and also reload the hub when complete: - -- [GitHub - Gaia Admin README.md](https://github.com/stacks-network/gaia/blob/master/admin/README.md) - -``` -$ export API_KEY="hello" -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - -H 'Content-Type: application/json' \ - -X POST \ - --data-raw '{"serverName": "myserver"}' \ - http://localhost:8009/v1/admin/config - -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - -X POST \ - http://localhost:8009/v1/admin/reload - -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - http://localhost:8009/v1/admin/config | jq -``` diff --git a/i18n/id/docusaurus-plugin-content-docs/current/governance/_index.md b/i18n/id/docusaurus-plugin-content-docs/current/governance/_index.md deleted file mode 100644 index 1ecdf67871..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/governance/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Governance -description: Governance -sidebar_position: 9 ---- - -This page needs contributions. Help us write it! \ No newline at end of file diff --git a/i18n/id/docusaurus-plugin-content-docs/current/governance/index.md b/i18n/id/docusaurus-plugin-content-docs/current/governance/index.md deleted file mode 100644 index 91b0215b5f..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/governance/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Governance -description: Governance -sidebar_position: 9 ---- - -![](/img/stacks-governance.png) - -This page needs contributions. Help us write it! - -Governance in web3 is driven by the community. - -How can I get involved ? - -[Governance Resources website](https://resources.stacksgov.com) - -[Github - Stack Community Governance](https://github.com/stacksgov) - -:::tip Community Calls Monthly community calls are recorded and available [here](https://www.youtube.com/playlist?list=PLg717Ri_rTnwwYjQYlc7rIP6x2FaTNn7f) ::: diff --git a/i18n/id/docusaurus-plugin-content-docs/current/governance/sips.md b/i18n/id/docusaurus-plugin-content-docs/current/governance/sips.md deleted file mode 100644 index 29ac1ae1ed..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/governance/sips.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: SIPs -description: SIPs -sidebar_position: 9 ---- - -## Stacks Improvement Proposals (SIPs) - -Stacks improvement proposals (SIPs) are aimed at describing the implementation of the Stacks blockchain, as well as proposing improvements. - -The SIP process [(SIP-000)](https://github.com/stacksgov/sips/blob/main/sips/sip-000/sip-000-stacks-improvement-proposal-process.md) describes how to make a SIP and get it ratified. - -They should contain concise technical specifications of features or standards and the rationale behind it. SIPs are intended to be the primary medium for proposing new features, for collecting community input on a system-wide issue, and for documenting design decisions. - -The SIPs are located in the [stacksgov/sips](https://github.com/stacksgov/sips) repository as part of the [Stacks Community Governance organization](https://github.com/stacksgov). - -Anyone in the Stacks community can submit a SIP. - -:::tip Stacks Improvement Proposals Community Calls SIP Meeting calls are recorded and available [here](https://www.youtube.com/playlist?list=PLg717Ri_rTnx5kuaWqp3cUAtwQk_yzslT) - -More details of the meetings are available [here](https://github.com/stacksgov/sips/issues/79) ::: - -## Ratified SIPSs - -- [x] [SIP 001: Burn Election](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md) -- [x] [SIP 002: Clarity, a language for predictable smart contracts](https://github.com/stacksgov/sips/blob/main/sips/sip-002/sip-002-smart-contract-language.md) -- [x] [SIP 003: Peer Network](https://github.com/stacksgov/sips/blob/main/sips/sip-003/sip-003-peer-network.md) -- [x] [SIP 004: Cryptographic Committment to Materialized Views](https://github.com/stacksgov/sips/blob/main/sips/sip-004/sip-004-materialized-view.md) -- [x] [SIP 005: Blocks, Transactions, and Accounts](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md) -- [x] [SIP 006: Clarity Execution Cost Assessment](https://github.com/stacksgov/sips/blob/main/sips/sip-006/sip-006-runtime-cost-assessment.md) -- [x] [SIP 007: Stacking Consensus](https://github.com/stacksgov/sips/blob/main/sips/sip-007/sip-007-stacking-consensus.md) -- [x] [SIP 008: Clarity Parsing and Analysis Cost Assessment](https://github.com/stacksgov/sips/blob/main/sips/sip-008/sip-008-analysis-cost-assessment.md) -- [x] [SIP 009: Standard Trait Definition for Non-Fungible Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-009/sip-009-nft-standard.md) -- [x] [SIP 010: Standard Trait Definition for Fungible Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-010/sip-010-fungible-token-standard.md) -- [x] [SIP 012: Burn Height Selection for a Network Upgrade to Introduce New Cost-Limits](https://github.com/stacksgov/sips/blob/main/sips/sip-012/sip-012-cost-limits-network-upgrade.md) -- [x] [SIP-016: Metadata for Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-016/sip-016-token-metadata.md) - -## How to Get Involved - -There are several ways you can get involved with the SIP process: - -* **Join the weekly SIP Meeting call** listed [here](https://community.stacks.org/events). - -* **SIP Editor**. SIP editors help SIP authors make sure their SIPs are well-formed and follow the right process. They help get SIPs ready for deep review by advancing it them from Draft to Accepted status. If you want to become a SIP editor, open an issue with your name and email to ask to be added to the list of SIP editors. - -* **Join a CAB** (Consideration Advisory Board). SIPs fall under the purview of one or more considerations. A full list is in [this github](https://github.com/stacksgov/sips/tree/main/considerations) directory. Currently they are: Diversity, Economics, Ethics, Governance and Technical. Members of SIP consideration advisory boards use their domain expertise to give Accepted SIPs a deep read, and give the authors any/all feedback to help make the SIP workable. If you want to join a board, reach out to the board's chairperson via the listed contact information. - -* **Steering Committee**. The Steering Committee organizes the consideration advisory boards and votes to advance Recommended SIPs to Activation-in-Progress status, and then to either Ratified or Rejected status. Once they are in the process of being activated, they use a SIP's Activation section to determine whether or not the Stacks ecosystem has ratified or rejected the SIP. Joining this committee requires the consent of the Stacks Foundation board. diff --git a/i18n/id/docusaurus-plugin-content-docs/current/intro.md b/i18n/id/docusaurus-plugin-content-docs/current/intro.md deleted file mode 100644 index 404fb77266..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/intro.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_label: "Beranda" -sidebar_position: 1 ---- - -# Stacks Pendahuluan - -Selamat datang di Dokumentasi Stacks resmi yang digerakkan oleh komunitas. - -Belajar tentang penambangan Stacks, token STX, dan bahasa pemrograman kontrak pintar Clarity. - -![](/img/Bitcoinet-L_2.svg) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md b/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md deleted file mode 100644 index 07e71136e4..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Stacks di DigitalOcean -description: A guide to setup Stacks on DigitalOcean -sidebar_position: 4 -tags: - - tutorial ---- - -## Pengantar - -This is a step by step guide to deploy the [Stacks Blockchain on DigitalOcean](https://marketplace.digitalocean.com/apps/stacks-blockchain). Code is hosted on this [Github repository](https://github.com/stacks-network/stacks-blockchain-docker). - -## Steps - -#### Step 1 - -Go to the [Stacks Blockchain page](https://marketplace.digitalocean.com/apps/stacks-blockchain) in DigitalOcean's marketplace. Click on `Create Stacks Blockchain Droplet`. - -#### Step 2 - -Choose a plan (it will only allow you to select a plan that meets the minimum requirements) and your prefered datacenter region. ![](/img/sh_digitalocean-choose-plan.png) - -#### Step 3 - -Enter a root password or enable SSH keys if your prefer. - -![](/img/sh_digitalocean-choose-authentication.png) - -#### Step 4 - -You can leave the rest of the options as they are and click on `Create Droplet` - -#### Step 5 - -You will need to wait a few seconds for the droplet to get created. Once created click on it to see more information. - -![](/img/sh_digitalocean-creating-droplet.png) - -![](/img/sh_digitalocean-created-droplet.png) - -### Step 6 - -Congratulations! You are now running the Stacks Blockchain. You can click on `Console` for a terminal window to open or login using SSH to the public IP you've been assigned to with user `root`. - -![](/img/sh_digitalocean-console-button.png) ![](/img/sh_digitalocean-console.png) - -## Getting started after deploying Stacks Blockchain - -Once droplet is launched, initial startup can take several minutes while BNS data is imported (this is a one time operation). - -To keep track of the progress, you can `ssh root@your_droplet_public_ipv4` to the host and run: `/opt/stacks-blockchain-docker/manage.sh -n mainnet -a logs`. - -Once the stacks blockchain starts to sync with peers, application ports will open and nginx port 80 will now start proxying requests. - -Use `http://your_droplet_public_ipv4` to access the data directly, with output being similar to: - -```json -{ - "server_version": "stacks-blockchain-api v3.0.3 (master:cd0c8aef)", - "status": "ready", - "chain_tip": { - "block_height": 16220, - "block_hash": "0x3123fba9c0de6b569573494cf83c1d5d198a66bfd5f48ef97949b6bf11ba13be", - "index_block_hash": "0xeec960fbbd6186b4ccac85ce12adba72be497d881f81e077305c90955b51a6ae" - } -} -``` - -All services are managed by a [systemd unit file](https://github.com/stacksfoundation/stacks-machine-images/blob/master/files/etc/systemd/system/stacks.service) that is set to start on boot. - -Manual control is also possible via the [manage.sh script](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/manage.sh) at `/opt/stacks-blockchain-docker/manage.sh` on the host. - -Full details on how to use the manage.sh script is [available here](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/README.md#quickstart). - -## API Creation - -In addition to creating a Droplet from the Stacks Blockchain 1-Click App via the control panel, you can also use the [DigitalOcean API](https://digitalocean.com/docs/api). - -As an example, to create a 4GB Stacks Blockchain Droplet in the SFO2 region, you can use the following curl command. You’ll need to either save your [API access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/) to an environment variable or substitute it into the command below. - -```bash -curl -X POST -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer '$TOKEN'' -d \ - '{"name":"choose_a_name","region":"sfo2","size":"s-2vcpu-4gb","image":"stacksfoundation-stacksblockchain"}' \ - "https://api.digitalocean.com/v2/droplets" -``` diff --git a/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md b/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md deleted file mode 100644 index 979265d7b2..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Noda dan Penambang -description: Noda dan Penambang -sidebar_position: 7 ---- - -Berikut adalah semua langkah untuk menjalankan noda dan penambang, baik di mainnet maupun testnet. - -## Apa itu noda Stacks? - -## Apa itu penambang Stacks? diff --git a/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md b/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md deleted file mode 100644 index 40397a51e0..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Miner costs and fees -description: Miner Cost and Fee Estimation -sidebar_position: 8 ---- - -## Configuring Cost and Fee Estimation - -Fee and cost estimators can be configured via the config section `[fee_estimation]`: - -``` -[fee_estimation] -cost_estimator = naive_pessimistic -fee_estimator = fuzzed_weighted_median_fee_rate -fee_rate_fuzzer_fraction = 0.1 -fee_rate_window_size = 5 -cost_metric = proportion_dot_product -log_error = true -enabled = true -``` - -Fee and cost estimators observe transactions on the network and use the observed costs of those transactions to build estimates for viable fee rates and expected execution costs for transactions. Estimators and metrics can be selected using the configuration fields above, though the default values are the only options currently. `log_error` controls whether or not the INFO logger will display information about the cost estimator accuracy as new costs are observed. Setting `enabled = false` turns off the cost estimators. Cost estimators are **not** consensus-critical components, but rather can be used by miners to rank transactions in the mempool or client to determine appropriate fee rates for transactions before broadcasting them. - -The `fuzzed_weighted_median_fee_rate` uses a median estimate from a window of the fees paid in the last `fee_rate_window_size` blocks. Estimates are then randomly "fuzzed" using uniform random fuzz of size up to `fee_rate_fuzzer_fraction` of the base estimate. diff --git a/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md b/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md deleted file mode 100644 index 499abebafe..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md +++ /dev/null @@ -1,343 +0,0 @@ ---- -title: Menambang token Stacks mainnet -description: Menyiapkan dan menjalankan penambang di mainnet Stacks 2.0 -sidebar_position: 5 -tags: - - tutorial ---- - -## Pengantar - -Make sure you've followed the [run a node](run-a-node) procedure. Setelah selesai, tinggal beberapa langkah lagi untuk menjalankan penambang proof-of-burn di mainnet. - -If you're interested in mining on the testnet, you can find instructions on how to do that [here](miner-testnet): - -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining): - -## Menjalankan bitcoind secara lokal - -Untuk berpartisipasi sebagai penambang di mainnet, Anda harus memiliki akses ke noda bitcoin mainnet. Salah satu cara untuk mencapai ini adalah dengan menjalankan bitcoind secara lokal. [Pastikan komputer Anda memenuhi persyaratan perangkat keras minimum sebelum melanjutkan.](https://bitcoin.org/en/bitcoin-core/features/requirements) - -Pertama, unduh perangkat lunak bitcoind untuk platform Anda dari https://bitcoin.org/en/download. - -Selanjutnya, mulai bitcoind dengan konfigurasi berikut: - -```toml -server=1 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=1 -banscore=1 -bind=0.0.0.0:8333 -rpcbind=0.0.0.0:8332 -rpcport=8332 -``` - -Terakhir, mulai bitcoind sebagai berikut: - -```bash -bitcoind -conf=path/to/bitcoin.conf -``` - -Mungkin perlu waktu beberapa hari hingga noda tersebut disinkronkan dengan mainnet Bitcoin. - -## Menjalankan penambang - -Pertama, sebuah keychain perlu dibuat. Dengan keychain ini, kita akan membeli beberapa BTC dari pertukaran mata uang kripto, dan kemudian menggunakan BTC tersebut untuk mulai menambang. - -Untuk mendapatkan keychain, cara paling sederhana adalah dengan menggunakan `stacks-cli`. Kita akan menggunakan perintah `make_keychain`. - -```bash -npx @stacks/cli make_keychain 2>/dev/null | json_pp > keychain.txt -``` - -Setelah ini berjalan, Anda akan melihat beberapa JSON di file `keychain.txt` baru yang terlihat seperti ini: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -**Jangan sampai kehilangan informasi ini** - kita harus menggunakan bidang `privateKey`. - -Alamat BTC di atas kemudian perlu diimpor ke jaringan BTC. - -```bash -bitcoin-cli -rpcport=8332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - - - -Setelah diimpor, kita perlu mendapatkan beberapa BTC ke alamat tersebut. Anda seharusnya dapat mentransfer BTC ke alamat ini menggunakan pertukaran mata uang kripto seperti [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), atau [Kraken](https://www.kraken.com). - - - -Sekarang, kita perlu mengkonfigurasi noda kita untuk menggunakan keychain Bitcoin ini. Kloning [repositori blockchain-stacks](https://github.com/stacks-network/stacks-blockchain) ke mesin lokal Anda jika Anda belum melakukannya. Di folder `blockchain-stacks`, ubah file di [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf /mainnet-miner-conf.toml). - -Perbarui properti berikut: - -```toml -[node] -... -# Masukkan kunci privat Anda di sini -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Sekarang, ambil `privateKey` Anda dari sebelumnya, ketika Anda menjalankan perintah `make_keychain`. Ganti bidang `seed` dengan kunci privat Anda. Simpan dan tutup file konfigurasi ini. - -Untuk menjalankan penambang Anda, jalankan ini di baris perintah: - -```bash -stacks-node start --config=./testnet/stacks-node/conf/mainnet-miner-conf.toml -``` - -Noda Anda akan dimulai. Ini akan memakan waktu untuk menyinkronkan, dan kemudian penambang Anda akan berjalan. - -### Membuat biner yang dioptimalkan - -Langkah-langkah di atas sangat bagus untuk mencoba menjalankan noda sementara. Jika Anda ingin menghost noda di server di suatu tempat, Anda mungkin ingin menghasilkan biner yang dioptimalkan. Untuk melakukannya, gunakan konfigurasi yang sama seperti di atas, jalankan: - -```bash -cd testnet/stacks-node -cargo build --release --bin stacks-node -``` - -Kode di atas akan mengkompilasi biner yang dioptimalkan. Untuk menggunakannya, jalankan: - -```bash -cd ../.. -./target/release/stacks-node start --config=./mainnet-miner-conf.toml -``` - -To read more about the technical details of mining on the Stacks 2.0 network, have a look at [the mining guide](../understand-stacks/mining). - -### Aktifkan pencatatan debug - -Jika Anda mengalami masalah atau ingin melihat pencatatan verbose, Anda dapat menjalankan noda dengan pencatatan debug yang diaktifkan. Di baris perintah, jalankan: - -```bash -STACKS_LOG_DEBUG=1 stacks-node mainnet -``` - -## Menjalankan penambang di Windows - -### Prasyarat - -Make sure are [running a node](run-a-node) and [running bitcoind locally](#running-bitcoind-locally) before starting this tutorial. - -### Membuat keychain dan mendapatkan token mainnet di Windows - -Untuk mengatur penambang, pertama-tama kita perlu membuat keychain. Dengan keychain ini, kita akan membeli beberapa BTC dari pertukaran mata uang kripto, dan kemudian menggunakan BTC tersebut untuk mulai menambang. - -Untuk mendapatkan keychain, cara paling sederhana adalah dengan menggunakan `stacks-cli`. Kita akan menggunakan perintah `stx make-keychain`. - -Membuat keychain: - -```bash -npm install --global @stacks/cli -stx make_keychain > cli_keychain.json -type cli_keychain.json -``` - -Setelah ini berjalan, Anda mungkin akan melihat beberapa log instalasi, dan pada akhirnya Anda akan melihat beberapa JSON yang terlihat seperti ini: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -Alamat BTC di atas kemudian perlu diimpor ke jaringan BTC. - -```bash -bitcoin-cli -rpcport=8332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - -Setelah diimpor, kita perlu mendapatkan beberapa BTC ke alamat tersebut. Anda seharusnya dapat mentransfer BTC ke alamat ini menggunakan pertukaran mata uang kripto seperti [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), atau [Kraken](https://www.kraken.com). - -### Perbarui file konfigurasi - -Sekarang, kita perlu mengkonfigurasi noda kita untuk menggunakan keychain Bitcoin ini. Kloning [repositori blockchain-stacks](https://github.com/stacks-network/stacks-blockchain) ke mesin lokal Anda jika Anda belum melakukannya. Di folder `blockchain-stacks`, ubah file di [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf /mainnet-miner-conf.toml). - -Perbarui properti berikut: - -```toml -[node] -... -# Masukkan kunci privat Anda di sini -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Sekarang, ambil `privateKey` Anda dari sebelumnya, ketika Anda menjalankan perintah `stx make_keychain`. Ganti bidang seed dengan kunci privat Anda. Simpan dan tutup file konfigurasi ini. - -### Jalankan penambang - -Untuk memulai penambang Anda, jalankan ini di baris perintah: - -```bash -stacks-node start --config=testnet/stacks-node/conf/mainnet-miner-conf.toml -``` - -:::note -While starting the node for the first time, windows defender might pop up with a message to allow access. Jika demikian, izinkan akses untuk menjalankan noda. -::: ![Windows Defender](/img/windows-defender.png) - -Noda Anda akan dimulai. Ini akan memakan waktu untuk menyinkronkan, dan kemudian penambang Anda akan berjalan. - -### Aktifkan pencatatan debug pada Windows - -Jika Anda mengalami masalah atau ingin melihat pencatatan verbose, Anda dapat menjalankan noda dengan pencatatan debug yang diaktifkan. Di baris perintah, jalankan: - -```bash -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=mainnet-miner-conf.toml -``` - -## Opsional: Berjalan dengan Docker - -Atau, Anda dapat menjalankan noda mainnet dengan Docker. - -:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: - -### Membuat keychain dan mendapatkan token - -Membuat keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null -``` - -Kita perlu mendapatkan beberapa BTC ke alamat tersebut. Anda seharusnya dapat mentransfer BTC ke alamat ini menggunakan pertukaran mata uang kripto seperti [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), atau [Kraken](https://www.kraken.com). - -### Perbarui file konfigurasi - -Sekarang, kita perlu mengkonfigurasi noda kita untuk menggunakan keychain Bitcoin ini. Kloning [repositori blockchain-stacks](https://github.com/stacks-network/stacks-blockchain) ke mesin lokal Anda jika Anda belum melakukannya. Di folder `blockchain-stacks`, ubah file di [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf /mainnet-miner-conf.toml). - -Perbarui properti berikut: - -```toml -[node] -... -# Masukkan kunci privat Anda di sini -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Sekarang, ambil `privateKey` Anda dari sebelumnya, ketika Anda menjalankan perintah `stx make_keychain`. Ganti bidang seed dengan kunci privat Anda. Simpan dan tutup file konfigurasi ini. - -### Memulai penambang - -:::info The ENV VARS `RUST_BACKTRACE` and `STACKS_LOG_DEBUG` are optional. If removed, debug logs will be disabled ::: - -```bash -docker run -d \ - --name stacks_miner \ - --rm \ - --network host \ - -e RUST_BACKTRACE="full" \ - -e STACKS_LOG_DEBUG="1" \ - -v "$(pwd)/testnet/stacks-node/conf/mainnet-miner-conf.toml:/src/stacks-node/mainnet-miner-conf.toml" \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain:latest \ -/bin/stacks-node start --config /src/stacks-node/mainnet-miner-conf.toml -``` - -Anda dapat meninjau log noda dengan perintah ini: - -```bash -docker logs -f stacks_miner -``` - -## Opsional: Berjalan di Kubernetes dengan Helm - -Selain itu, Anda juga dapat menjalankan noda mainnet di klaster Kubernetes menggunakan [bagan Helm blockchain-stacks](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). - -Pastikan Anda telah menginstal prasyarat berikut di mesin Anda: - -- [Docker](https://docs.docker.com/get-docker/) -- [minikube](https://minikube.sigs.k8s.io/docs/start/) (Hanya diperlukan jika membuat klaster Kubernetes lokal) -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [helm](https://helm.sh/docs/intro/install/) - -### Membuat keychain dan mendapatkan beberapa token - -Membuat keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null -``` - -Kita perlu mendapatkan beberapa BTC ke alamat tersebut. Anda seharusnya dapat mentransfer BTC ke alamat ini menggunakan pertukaran mata uang kripto seperti [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), atau [Kraken](https://www.kraken.com). - -### Instal grafik dan jalankan penambang - -Untuk menginstal grafik dengan nama rilis `my-release` dan menjalankan noda sebagai penambang: - -```bash -minikube start # Jalankan ini hanya jika berdiri di cluster Kubernetes lokal -helm repo add blockstack https://charts.blockstack.xyz -helm install my-release blockstack/stacks-blockchain \ - --set config.node.miner=true \ - --set config.node.seed="replace-with-your-privateKey-from-generate-keychain-step" \ - --set config.burnchain.mode="mainnet" -``` - -Anda dapat meninjau log noda dengan perintah ini: - -```bash -kubectl logs -l app.kubernetes.io/name=stacks-blockchain -``` - -Untuk informasi selengkapnya tentang bagan Helm dan opsi konfigurasi, lihat [bagan beranda](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). diff --git a/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md b/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md deleted file mode 100644 index e892bf9c82..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md +++ /dev/null @@ -1,336 +0,0 @@ ---- -title: Menambang token Stacks testnet -description: Menyiapkan dan menjalankan penambang di testnet Stacks 2.0 -sidebar_position: 4 -tags: - - tutorial ---- - -## Pengantar - -Make sure you've followed the [Run a node](run-a-node) procedure. Setelah selesai, tinggal beberapa langkah lagi untuk menjalankan penambang proof-of-burn di testnet. - -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining). - -## Menjalankan bitcoind secara lokal - -To participate as a miner on Testnet, you must have access to a testnet bitcoin node. Salah satu cara untuk mencapai ini adalah dengan menjalankan bitcoind secara lokal. [Pastikan komputer Anda memenuhi persyaratan perangkat keras minimum sebelum melanjutkan.](https://bitcoin.org/en/bitcoin-core/features/requirements) - -Pertama, unduh perangkat lunak bitcoind untuk platform Anda dari https://bitcoin.org/en/download. - -Selanjutnya, mulai bitcoind dengan konfigurasi berikut: - -```toml -server=1 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password -testnet=1 -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=1 -banscore=1 - -[test] -bind=0.0.0.0:18333 -rpcbind=0.0.0.0:18332 -rpcport=18332 -``` - -Terakhir, mulai bitcoind sebagai berikut: - -```bash -bitcoind -conf=path/to/bitcoin.conf -``` - -Mungkin perlu waktu beberapa jam hingga noda tersebut disinkronkan dengan testnet Bitcoin. - -## Menjalankan penambang - -Pertama, sebuah keychain perlu dibuat. Dengan keychain ini, kita akan mendapatkan beberapa BTC testnet dari faucet, dan kemudian menggunakan BTC tersebut untuk mulai menambang. - -Untuk mendapatkan keychain, cara paling sederhana adalah dengan menggunakan `stacks-cli`. Kita akan menggunakan perintah `make_keychain`, dan meneruskan `-t` untuk menunjukkan bahwa kita menginginkan keychain testnet. - -```bash -npx @stacks/cli make_keychain -t 2>/dev/null | json_pp > keychain.txt -``` - -Setelah ini berjalan, Anda akan melihat beberapa JSON di file `keychain.txt` baru yang terlihat seperti ini: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -**Jangan sampai kehilangan informasi ini** - kita harus menggunakan bidang `privateKey`. - -Alamat BTC di atas kemudian perlu diimpor ke jaringan testnet BTC. - -```bash -bitcoin-cli -rpcport=18332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - -Setelah diimpor, kita perlu mendapatkan beberapa BTC ke alamat tersebut. Ambil bidang `btcAddress`, dan tempel ke [faucet testnet Bitcoin ini](https://tbtc.bitaps.com/). Anda akan dikirim `0.01` BTC testnet ke alamat tersebut. - -Sekarang, kita perlu mengkonfigurasi noda kita untuk menggunakan keychain Bitcoin ini. Kloning [repositori blockchain-stacks](https://github.com/stacks-network/stacks-blockchain) ke mesin lokal Anda jika Anda belum melakukannya. Di folder `blockchain-stacks`, ubah file di [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf /testnet-miner-conf.toml). - -Perbarui properti berikut: - -```toml -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Sekarang, ambil `privateKey` Anda dari sebelumnya, ketika Anda menjalankan perintah `make_keychain`. Ganti bidang `seed` dengan kunci privat Anda. Simpan dan tutup file konfigurasi ini. - -Untuk menjalankan penambang Anda, jalankan ini di baris perintah: - -```bash -stacks-node start --config=./testnet/stacks-node/conf/testnet-miner-conf.toml -``` - -Noda Anda akan dimulai. Ini akan memakan waktu untuk menyinkronkan, dan kemudian penambang Anda akan berjalan. - -### Membuat biner yang dioptimalkan - -Langkah-langkah di atas sangat bagus untuk mencoba menjalankan noda sementara. Jika Anda ingin menghost noda di server di suatu tempat, Anda mungkin ingin menghasilkan biner yang dioptimalkan. Untuk melakukannya, gunakan konfigurasi yang sama seperti di atas, jalankan: - -```bash -cd testnet/stacks-node -cargo build --release --bin stacks-node -``` - -Kode di atas akan mengkompilasi biner yang dioptimalkan. Untuk menggunakannya, jalankan: - -```bash -cd ../.. -./target/release/stacks-node start --config=./testnet/conf/testnet-follower-conf.toml -``` - -To read more about the technical details of mining on the Stacks 2.0 network, have a look at [the minig guide](../understand-stacks/mining): - -### Aktifkan pencatatan debug - -Jika Anda mengalami masalah atau ingin melihat pencatatan verbose, Anda dapat menjalankan noda dengan pencatatan debug yang diaktifkan. Di baris perintah, jalankan: - -```bash -STACKS_LOG_DEBUG=1 stacks-node testnet -``` - -## Menjalankan penambang di Windows - -### Prasyarat - -Make sure are [running a testnet node](run-a-node) before starting this tutorial. - -### Membuat keychain dan mendapatkan token testnet di Windows - -Untuk mengatur penambang, pertama-tama kita perlu membuat keychain. Dengan keychain ini, kita akan mendapatkan beberapa BTC testnet dari faucet, dan kemudian menggunakan BTC tersebut untuk mulai menambang. - -Untuk mendapatkan keychain, cara paling sederhana adalah dengan menggunakan `stacks-cli`. Kita akan menggunakan perintah `stx make-keychain`, dan meneruskan `-t` untuk menunjukkan bahwa kita menginginkan keychain testnet. - -Membuat keychain: - -```bash -npm install --global @stacks/cli -stx make_keychain -t > cli_keychain.json -type cli_keychain.json -``` - -Setelah ini berjalan, Anda mungkin akan melihat beberapa log instalasi, dan pada akhirnya Anda akan melihat beberapa JSON yang terlihat seperti ini: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -Meminta BTC dari faucet: - -Kita perlu mendapatkan beberapa BTC ke alamat tersebut. Ambil bidang `btcAddress`, dan tempel ke [faucet testnet Bitcoin ini](https://tbtc.bitaps.com/). Anda akan dikirim 0.01 BTC testnet ke alamat tersebut. - -### Perbarui file konfigurasi - -Sekarang, kita perlu mengkonfigurasi noda kita untuk menggunakan keychain Bitcoin ini. Kloning [repositori blockchain-stacks](https://github.com/stacks-network/stacks-blockchain) ke mesin lokal Anda jika Anda belum melakukannya. Di folder `blockchain-stacks`, ubah file di [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf /testnet-miner-conf.toml). - -Perbarui properti berikut: - -```toml -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Sekarang, ambil `privateKey` Anda dari sebelumnya, ketika Anda menjalankan perintah `stx make_keychain`. Ganti bidang seed dengan kunci privat Anda. Simpan dan tutup file konfigurasi ini. - -### Jalankan penambang - -Untuk memulai penambang Anda, jalankan ini di baris perintah: - -```bash -stacks-node start --config=testnet/stacks-node/conf/testnet-miner-conf.toml -``` - - - -:::note -While starting the node for the first time, windows defender might pop up with a message to allow access. Jika demikian, izinkan akses untuk menjalankan noda. -::: ![Windows Defender](/img/windows-defender.png) - - - -Noda Anda akan dimulai. Ini akan memakan waktu untuk menyinkronkan, dan kemudian penambang Anda akan berjalan. - -### Aktifkan pencatatan debug pada Windows - -Jika Anda mengalami masalah atau ingin melihat pencatatan verbose, Anda dapat menjalankan noda dengan pencatatan debug yang diaktifkan. Di baris perintah, jalankan: - -```bash -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=testnet-miner-conf.toml -``` - -## Opsional: Berjalan dengan Docker - -Atau, Anda dapat menjalankan noda testnet dengan Docker. - -:::warning Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: - -### Membuat keychain dan mendapatkan token testnet - -Membuat keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` - -Kita perlu mendapatkan beberapa BTC ke alamat tersebut. Ambil bidang `btcAddress`, dan tempel ke [faucet testnet Bitcoin ini](https://tbtc.bitaps.com/). Anda akan dikirim 0.01 BTC testnet ke alamat tersebut. - -### Perbarui file konfigurasi - -Sekarang, kita perlu mengkonfigurasi noda kita untuk menggunakan keychain Bitcoin ini. Kloning [repositori blockchain-stacks](https://github.com/stacks-network/stacks-blockchain) ke mesin lokal Anda jika Anda belum melakukannya. Di folder `blockchain-stacks`, ubah file di [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf /testnet-miner-conf.toml). - -Perbarui properti berikut: - -```toml -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Sekarang, ambil `privateKey` Anda dari sebelumnya, ketika Anda menjalankan perintah `stx make_keychain`. Ganti bidang seed dengan kunci privat Anda. Simpan dan tutup file konfigurasi ini. - -### Memulai penambang - -:::info The ENV VARS `RUST_BACKTRACE` and `STACKS_LOG_DEBUG` are optional. If removed, debug logs will be disabled ::: - -```bash -docker run -d \ - --name stacks_miner \ - --rm \ - --network host \ - -e RUST_BACKTRACE="full" \ - -e STACKS_LOG_DEBUG="1" \ - -v "$(pwd))/testnet/stacks-node/conf/testnet-miner-conf.toml:/src/stacks-node/testnet-miner-conf.toml" \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain:latest \ -/bin/stacks-node start --config /src/stacks-node/testnet-miner-conf.toml -``` - -Anda dapat meninjau log noda dengan perintah ini: - -```bash -docker logs -f stacks_miner -``` - -## Opsional: Berjalan di Kubernetes dengan Helm - -Selain itu, Anda juga dapat menjalankan noda testnet di klaster Kubernetes menggunakan [bagan Helm blockchain-stacks](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). - -Pastikan Anda telah menginstal prasyarat berikut di mesin Anda: - -- [Docker](https://docs.docker.com/get-docker/) -- [minikube](https://minikube.sigs.k8s.io/docs/start/) (Hanya diperlukan jika membuat klaster Kubernetes lokal) -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [helm](https://helm.sh/docs/intro/install/) - -### Membuat keychain dan mendapatkan beberapa token - -Membuat keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` - -Kita perlu mendapatkan beberapa BTC ke alamat tersebut. Ambil bidang `btcAddress`, dan tempel ke [faucet testnet Bitcoin ini](https://tbtc.bitaps.com/). Anda akan dikirim 0.01 BTC testnet ke alamat tersebut. - -### Instal grafik dan jalankan penambang - -Untuk menginstal grafik dengan nama rilis `my-release` dan menjalankan noda sebagai penambang: - -```bash -minikube start # Jalankan ini hanya jika berdiri di klaster Kubernetes lokal -helm repo add blockstack https://charts.blockstack.xyz -helm install my-release blockstack/stacks-blockchain \ - --set config.node.miner=true \ - --set config.node.seed="replace-with-your-privateKey-from-generate-keychain-step" -``` - -Anda dapat meninjau log noda dengan perintah ini: - -```bash -kubectl logs -l app.kubernetes.io/name=stacks-blockchain -``` - -Untuk informasi selengkapnya tentang bagan Helm dan opsi konfigurasi, lihat [bagan beranda](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). diff --git a/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md b/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md deleted file mode 100644 index 94d938c5ca..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md +++ /dev/null @@ -1,351 +0,0 @@ ---- -title: Run a node -description: Set up and run a Stacks node -sidebar_position: 1 -tags: - - tutorial ---- - -## Stacks Blockchain with Docker - -Run your own Stacks Blockchain node easily with just few commands. - -This tutorial describes a simple and effective [quickstart](#quickstart) to run a Stacks node using public scripts hosted in [Stacks Blockchain repository](https://github.com/stacks-network/stacks-blockchain-docker). Valid for mainnet, testnet and mocknet. - -## **Quickstart** - -1. **Clone the stacks-blockchain-docker repository locally** - -```bash -git clone https://github.com/stacks-network/stacks-blockchain-docker && cd stacks-blockchain-docker -``` - -2. **Optionally, create/copy `.env` file**. If file `.env` doesn't exist when launched it will be created from `sample.env` automatically. - -```bash -cp sample.env .env -``` - -_You may also use a symlink as an alternative to copying: `ln -s sample.env .env`_ - -3. **Optionally, ensure all images are up to date** - -```bash -./manage.sh -n -a pull -``` - -4. **Start the Services** - -```bash -./manage.sh -n -a start -``` - -- With optional proxy: - -```bash -./manage.sh -n -a start -f proxy -``` - -- With optional bitcoin node: - -```bash -./manage.sh -n -a start -f bitcoin -``` - -5. **Stop the Services** - -```bash -./manage.sh -n -a stop -``` - -6. **Retrieve Service Logs** - -```bash -./manage.sh -n -a logs -``` - -- Export docker log files to `./exported-logs`: - -This will create one log file for every running service, for example: postgres.log, stacks-blockain.log, stacks-blockchain-api.log and bitcoin-core.log. -Notice that each time you run this command the log files will be overwritten. - -```bash -./manage.sh -n -a logs export -``` - -7. **Restart all services** - -```bash -./manage.sh -n -a restart -``` - -- With optional proxy: - -```bash -./manage.sh -n -a restart -f proxy -``` - -8. **Delete** all data in `./persistent-data/` and/or data of the Bitcoin blockchain. - - This data is owned by root, so you will need to run it with sudo privileges so it can delete the data. - -```bash -$ sudo ./manage.sh -n -a reset - -Please confirm what persistent data you wish to delete: - -0. Cancel -1. Delete Persistent data for Stacks testnet only and leave Bitcoin blockchain data unaffected. -2. Delete Persistent data for Stacks testnet and Bitcoin blockchain data in ./persistent-data/blockchain-bitcoin -3. Delete Persistent data for Bitcoin blockchain data in ./persistent-data/blockchain-bitcoin only. -Please note that BNS data will never get deleted. - -Type 0, 1, 2 or 3: 2 - -Ok. Delete Stacks and Bitcoin data. -[ Success ] Persistent data deleted for Bitcoin blockchain. -[ Success ] Persistent data deleted for Stacks testnet. - -``` - -9. **Download BNS data to** `./persistent-data/bns-data` - -```bash -./manage.sh bns -``` - -10. **Export stacks-blockchain-api events** (_Not applicable for mocknet_) - -```bash -./manage.sh -n -a export -# check logs for completion -./manage.sh -n -a restart -``` - -11. **Replay stacks-blockchain-api events** (_Not applicable for mocknet_) - -```bash -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart -``` - -## **Running also a bitcoin node (Optional)** - -Stacks needs to use a Bitcoin node, and by default when you run a Stacks node you will be using a public Bitcoin node, which is configured in the `.env` file. Default values is `BITCOIN_NODE=bitcoin.mainnet.stacks.org`. - -However, you can optionaly run both nodes together and configured in a way that you Stacks node will use your own Bitcoin node instead of a public one. - -If you run the script with a bitcoin node it will download and build it directly from source for increased security. This process which only needs to happen once can take up to 20-30 minutes depending on the speed of your system. Also, once the bitcoin node is up and running it will need an additional time for sync for the first time (can be hours for testnet and days for mainnet). - -### Why run Stacks node with your own Bitcoin node? - -Because running your own Bitcoin node will give you higher security and improved perfomance. - -* **Improved perfomance**: The Bitcoin node will serve you blocks faster, as well as UTXOs for your miner (if you run one). -* **Higher security**: The Bitcoin node will also have validated all bitcoin transactions the Stacks node consumes. If you don't run your own Bitcoin node, you're relying on the SPV headers to vouch for the validity of Bitcoin blocks. - -The disadvantage of running your own Bitcoin node is that you need the extra space to store the Bitcoin blockchain (about 500GB) and the initial time it will take to download this data the first time. - -### Example - -You can run easily run your Stacks node with your own Bitcoin node by adding the flag `bitcoin`. This is available only for testnet and mainnet. - -Example: `./manage.sh -n mainnet -a start -f bitcoin` or `./manage.sh -n testnet -a start -f bitcoin` - -### Bitcoin node configuration - -In the `.env` file there is the variable `BITCOIN_BLOCKCHAIN_FOLDER`. As the bitcoin blockchain can be large (over 500GB) you optionally change this variable to any location of your choosing. If you have previously used the [bitcoin core application](https://bitcoin.org/en/bitcoin-core/) and already have the bitcoin blockchain synced, you can use the same data folder and avoid redownloading the entire bitcoin blockchain. - -## **Accessing the services** - -:::tip For networks other than `mocknet`, downloading the initial headers can take several minutes. Until the headers are downloaded, the `/v2/info` endpoints won't return any data. - -Use the command `./manage.sh -n -a logs` to check the sync progress. ::: - -**stacks-blockchain**: - -- Ports `20443-20444` are exposed to `localhost` - -```bash -curl -sL localhost:20443/v2/info | jq -``` - -**stacks-blockchain-api**: - -- Port `3999` are exposed to `localhost` - -```bash -curl -sL localhost:3999/v2/info | jq -``` - -**proxy**: - -- Port `80` is exposed to `localhost` - -```bash -curl -sL localhost/v2/info | jq -curl -sL localhost/ | jq -``` - ---- - -## Upgrades - -⚠️ For upgrades to running instances of this repo, you'll need to [run the event-replay](https://github.com/hirosystems/stacks-blockchain-api#event-replay): - -```bash -./manage.sh -n -a stop -./manage.sh -n -a export -./manage.sh -n -a import -./manage.sh -n -a restart -``` - ---- - -## **Workarounds to potential issues** - -_**Port(s) already in use**_: - -- 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. `3999` and edit your `.env` file to use the new port. - -```bash -netstat -anl | grep 3999 -``` - -``` -tcp46 0 0 *.3999 *.* LISTEN -``` - -_**Containers not starting (hanging on start)**_: - -- Occasionally, docker can get **stuck** and not allow new containers to start. If this happens, simply restart your docker daemon and try again. - -_**Database Issues**_: - -- For any of the various Postgres/sync issues, it may be easier to simply remove the persistent data dir. Note that doing so will result in a longer startup time as the data is repopulated. - -```bash -./manage.sh -n -a stop -./manage.sh -n -a reset -./manage.sh -n -a start -``` - -_**API Missing Parent Block Error**_: - -- If the Stacks blockchain is no longer syncing blocks, and the API reports an error similar to this:\ - `Error processing core node block message DB does not contain a parent block at height 1970 with index_hash 0x3367f1abe0ee35b10e77fbcaa00d3ca452355478068a0662ec492bb30ee0f13e"`,\ - The API (and by extension the DB) is out of sync with the blockchain. \ - The only known method to recover is to resync from genesis (**event-replay _may_ work, but in all likelihood will restore data to the same broken state**). - -- To attempt the event-replay - -```bash -./manage.sh -n -a stop -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart -``` - -- To wipe data and re-sync from genesis - -```bash -./manage.sh -n -a stop -./manage.sh -n -a reset -./manage.sh -n -a restart -``` - - -## **Requirements:** - -- [Docker](https://docs.docker.com/get-docker/) >= `17.09` -- [docker-compose](https://github.com/docker/compose/releases/) >= `1.27.4` -- [git](https://git-scm.com/downloads) -- [jq binary](https://stedolan.github.io/jq/download/) -- [sed](https://www.gnu.org/software/sed/) -- Machine with (at a minimum): - - 4GB memory - - 1 Vcpu - - 50GB storage (600GB if you optionally also run the bitcoin mainnet node) - -:::caution MacOS with an M1 processor is NOT recommended - -The way Docker for Mac on an Arm chip is designed makes the I/O incredibly slow, and blockchains are **_very_** heavy on I/O. This only seems to affect MacOS, other Arm based systems like Raspberry Pi's seem to work fine. - -::: - - -### Install/Update docker-compose - -:::note `docker-compose` executable is required, even though recent versions of Docker contain `compose` natively ::: - -- [Install Docker-compose](https://docs.docker.com/compose/install/) -- [Docker Desktop for Mac](https://docs.docker.com/docker-for-mac/install/) -- [Docker Desktop for Windows](https://docs.docker.com/docker-for-windows/install/) -- [Docker Engine for Linux](https://docs.docker.com/engine/install/#server) - -First, check if you have `docker-compose` installed locally. - -To do that, run this command in your terminal : - -```bash -docker-compose --version -``` - -Output should look something very similar to this : - -``` -docker-compose version 1.27.4, build 40524192 -``` - -If the command is not found, or the version is < `1.27.4`, run the following to install the latest to `/usr/local/bin/docker-compose`: - -```bash -#You will need to have jq installed, or this snippet won't run. -VERSION=$(curl --silent https://api.github.com/repos/docker/compose/releases/latest | jq .name -r) -DESTINATION=/usr/local/bin/docker-compose -sudo curl -L https://github.com/docker/compose/releases/download/${VERSION}/docker-compose-$(uname -s)-$(uname -m) -o $DESTINATION -sudo chmod 755 $DESTINATION -``` - -### Security note on docker - -The Docker daemon always runs as the root user so by default you will need root privileges to interact with it. - -The script `manage.sh` uses docker, so to avoid the requirement of needing to run the script with root privileges it is prefered to be able to *manage Docker as a non-root user*, following [these simple tests](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user). - -This will avoid the need of running the script with root privileges for all operations except the removal of data. - -### Configuration files you can edit - -The following files can be modified to personalize your node configuration, but generally most of them should be left as-is. All these files will be created from the sample copy if they don't exist at runtime (for example `.env` is created from `sample.env`). However these files will never be modified by the application once created and will never be pushed back to github, so your changes will be safe. - -* `.env` -* `./conf/mainnet/Config.toml` -* `./conf/mainnet/bitcoin.conf` -* `./conf/testnet/Config.toml` -* `./conf/testnet/bitcoin.conf` - -By default: - -- BNS data is **not** enabled/imported - - To enable, uncomment `# BNS_IMPORT_DIR=/bns-data` in `./env` - - Download BNS data: `./manage.sh bns` -- Fungible token metadata is **not** enabled - - To enable, uncomment `# STACKS_API_ENABLE_FT_METADATA=1` in `./env` -- Non-Fungible token metadata is **not** enabled - - To enable, uncomment `# STACKS_API_ENABLE_NFT_METADATA=1` in `./env` -- Verbose logging is **not** enabled - - To enable, uncomment `# VERBOSE=true` in `./env` -- Bitcoin blockchain folder is configured in `BITCOIN_BLOCKCHAIN_FOLDER` in `./env` - -### Local Data Dirs - -Directories will be created on first start that will store persistent data under `./persistent-data/` - -`` can be 1 of: - -- mainnet -- testnet -- mocknet diff --git a/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md b/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md deleted file mode 100644 index 2d801e9cc6..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md +++ /dev/null @@ -1,188 +0,0 @@ ---- -title: Menjalankan noda mainnet -description: Menyiapkan dan menjalankan node mainnet dengan Docker -sidebar_position: 3 -tags: - - tutorial ---- - -## Pengantar - -Prosedur ini menunjukkan cara menjalankan noda mainnet lokal menggunakan gambar Docker. - -:::caution -This procedure focuses on Unix-like operating systems (Linux and MacOS). Prosedur ini belum diuji pada Windows. -::: - -## Prasyarat - -Menjalankan noda tidak memiliki persyaratan perangkat keras khusus. Pengguna telah berhasil menjalankan noda pada papan Raspberry Pi dan arsitektur system-on-chip lainnya. Untuk menyelesaikan prosedur ini, Anda harus menginstal perangkat lunak berikut di mesin host noda: - -- [Docker](https://docs.docker.com/get-docker/) -- [curl](https://curl.se/download.html) -- [jq](https://stedolan.github.io/jq/download/) - -### Konfigurasi firewall - -Agar layanan noda API berfungsi dengan benar, Anda harus mengkonfigurasi aturan firewall jaringan apa pun untuk mengizinkan lalu lintas pada port yang dibahas di bagian ini. Detail konfigurasi jaringan dan firewall sangat spesifik untuk mesin dan jaringan Anda, jadi contoh detail tidak diberikan. - -Port berikut harus terbuka di mesin host: - -Jalan masuk: - -- stacks-blockchain (open to `0.0.0.0/0`): - - `20443 TCP` - - `20444 TCP` - -Jalan keluar: - -- `8332` -- `8333` -- `20443-20444` - -These egress ports are for syncing stacks-blockchain and Bitcoin headers. Jika tidak terbuka, sinkronisasi akan gagal. - -## Langkah 1: pengaturan awal - -Untuk menjalankan noda mainnet, Anda harus mengunduh gambar Docker dan membuat struktur direktori untuk menyimpan data persisten dari layanan. Unduh dan konfigurasikan gambar Docker dengan perintah berikut: - -```sh -docker pull blockstack/stacks-blockchain -``` - -Buat struktur direktori untuk data layanan dengan perintah berikut: - -```sh -mkdir -p ./stacks-node/{persistent-data/stacks-blockchain/mainnet,config/mainnet} && cd stacks-node -``` - -## Langkah 2: menjalankan blockchain Stacks - -Pertama, buat file `./config/mainnet/Config.toml` dan tambahkan konten berikut ke file menggunakan editor teks: - -```toml -[node] -working_dir = "/root/stacks-node/data" -rpc_bind = "0.0.0.0:20443" -p2p_bind = "0.0.0.0:20444" -bootstrap_node = "02da7a464ac770ae8337a343670778b93410f2f3fef6bea98dd1c3e9224459d36b@seed-0.mainnet.stacks.co:20444,02afeae522aab5f8c99a00ddf75fbcb4a641e052dd48836408d9cf437344b63516@seed-1.mainnet.stacks.co:20444,03652212ea76be0ed4cd83a25c06e57819993029a7b9999f7d63c36340b34a4e62@seed-2.mainnet.stacks.co:20444" -wait_time_for_microblocks = 10000 - -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "bitcoin.blockstack.com" -username = "blockstack" -password = "blockstacksystem" -rpc_port = 8332 -peer_port = 8333 - -[connection_options] -read_only_call_limit_write_length = 0 -read_only_call_limit_read_length = 100000 -read_only_call_limit_write_count = 0 -read_only_call_limit_read_count = 30 -read_only_call_limit_runtime = 1000000000 -``` - -Start the `stacks-blockchain` container with the following command: - -```sh -docker run -d --rm \ - --name stacks-blockchain \ - -v $(pwd)/persistent-data/stacks-blockchain/mainnet:/root/stacks-node/data \ - -v $(pwd)/config/mainnet:/src/stacks-node \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain \ -/bin/stacks-node start --config /src/stacks-node/Config.toml -``` - -You can verify the running `stacks-blockchain` container with the command: - -```sh -docker ps --filter name=stacks-blockchain -``` - -## Langkah 3: memverifikasi layanan - -:::note -The initial burnchain header sync can take several minutes, until this is done the following commands will not work -::: - -To verify the `stacks-blockchain` burnchain header sync progress: - -```sh -docker logs stacks-blockchain -``` - -Keluarannya harus mirip dengan berikut ini: - -``` -INFO [1626290705.886954] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.2% (8000 out of 691034) -INFO [1626290748.103291] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.4% (10000 out of 691034) -INFO [1626290776.956535] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.7% (12000 out of 691034) -``` - -To verify the `stacks-blockchain` tip height is progressing use the following command: - -```sh -curl -sL localhost:20443/v2/info | jq -``` - -Jika kejadian sedang berjalan, Anda akan menerima keluaran terminal yang mirip dengan berikut ini: - -```json -{ - "peer_version": 402653184, - "pox_consensus": "89d752034e73ed10d3b97e6bcf3cff53367b4166", - "burn_block_height": 666143, - "stable_pox_consensus": "707f26d9d0d1b4c62881a093c99f9232bc74e744", - "stable_burn_block_height": 666136, - "server_version": "stacks-node 2.0.11.1.0-rc1 (master:67dccdf, release build, linux [x86_64])", - "network_id": 1, - "parent_network_id": 3652501241, - "stacks_tip_height": 61, - "stacks_tip": "e08b2fe3dce36fd6d015c2a839c8eb0885cbe29119c1e2a581f75bc5814bce6f", - "stacks_tip_consensus_hash": "ad9f4cb6155a5b4f5dcb719d0f6bee043038bc63", - "genesis_chainstate_hash": "74237aa39aa50a83de11a4f53e9d3bb7d43461d1de9873f402e5453ae60bc59b", - "unanchored_tip": "74d172df8f8934b468c5b0af2efdefe938e9848772d69bcaeffcfe1d6c6ef041", - "unanchored_seq": 0, - "exit_at_block_height": null -} -``` - -## Menghentikan noda mainnet - -Gunakan perintah berikut untuk menghentikan noda mainnet lokal: - -```sh -docker stop stacks-blockchain -``` - -## Opsional. Menjalankan noda Stacks dengan noda bitcoin sendiri - -Disarankan untuk menggunakan noda bitcoin Anda sendiri jika memungkinkan. - -Untuk melakukannya cukup perbarui file `stacks-node/config/mainnet/Config.toml` dengan detail noda bitcoin Anda. Misalnya: - -``` -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "localhost" -username = "rpc username" -password = "rpc password" -rpc_port = 8332 -peer_port = 8333 -``` - -Konfigurasi rpc noda bitcoin Anda berada di luar cakupan dokumen ini, namun Anda dapat menemukan informasi lebih lanjut tentang cara menyiapkannya [ di sini](https://developer.bitcoin.org/examples/intro.html). - -## Bacaan tambahan - - - -- [Menjalankan noda API Stacks](https://docs.hiro.so/get-started/running-api-node) -- [Menjalankan noda testnet Stacks](running-testnet-node) - diff --git a/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md b/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md deleted file mode 100644 index 4253167645..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: Menjalankan noda testnet -description: Menyiapkan dan menjalankan noda testnet dengan Docker -sidebar_position: 2 -tags: - - tutorial ---- - -## Pengantar - -Prosedur ini menunjukkan cara menjalankan noda testnet lokal menggunakan gambar Docker. - -:::caution -This procedure focuses on Unix-like operating systems (Linux and MacOS). Prosedur ini belum diuji pada Windows. -::: - -## Prasyarat - -Menjalankan noda tidak memiliki persyaratan perangkat keras khusus. Pengguna telah berhasil menjalankan noda pada papan Raspberry Pi dan arsitektur system-on-chip lainnya. Untuk menyelesaikan prosedur ini, Anda harus menginstal perangkat lunak berikut di mesin host noda: - -- [Docker](https://docs.docker.com/get-docker/) -- [curl](https://curl.se/download.html) -- [jq](https://stedolan.github.io/jq/download/) - -### Konfigurasi firewall - -Agar layanan noda API berfungsi dengan benar, Anda harus mengkonfigurasi aturan firewall jaringan apa pun untuk mengizinkan lalu lintas pada port yang dibahas di bagian ini. Detail konfigurasi jaringan dan firewall sangat spesifik untuk mesin dan jaringan Anda, jadi contoh detail tidak diberikan. - -Port berikut harus terbuka di mesin host: - -Jalan masuk: - -- stacks-blockchain (open to `0.0.0.0/0`): - - `20443 TCP` - - `20444 TCP` - -Jalan keluar: - -- `18332` -- `18333` -- `20443-20444` - -These egress ports are for syncing stacks-blockchain and Bitcoin headers. Jika tidak terbuka, sinkronisasi akan gagal. - -## Langkah 1: pengaturan awal - -Untuk menjalankan noda testnet, Anda harus mengunduh gambar Docker dan membuat struktur direktori untuk menyimpan data persisten dari layanan. Unduh dan konfigurasikan gambar Docker dengan perintah berikut: - -```sh -docker pull blockstack/stacks-blockchain -``` - -Buat struktur direktori untuk data layanan dengan perintah berikut: - -```sh -mkdir -p ./stacks-node/persistent-data/stacks-blockchain/testnet && cd stacks-node -``` - -## Langkah 2: menjalankan blockchain Stacks - -Start the stacks-blockchain container with the following command: - -```sh -docker run -d --rm \ - --name stacks-blockchain \ - -v $(pwd)/persistent-data/stacks-blockchain/testnet:/root/stacks-node/data \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain \ -/bin/stacks-node testnet -``` - -You can verify the running stacks-blockchain container with the command: - -```sh -docker ps --filter name=stacks-blockchain -``` - -## Langkah 3: memverifikasi layanan - -:::info -The initial burnchain header sync can take several minutes, until this is done the following commands will not work -::: - -To verify the stacks-blockchain burnchain header sync progress: - -```sh -docker logs stacks-blockchain -``` - -Keluarannya harus mirip dengan berikut ini: - -``` -INFO [1626290705.886954] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.2% (8000 out of 2034380) -INFO [1626290748.103291] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.4% (10000 out of 2034380) -INFO [1626290776.956535] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.7% (12000 out of 2034380) -``` - -To verify the stacks-blockchain tip height is progressing use the following command: - -```sh -curl -sL localhost:20443/v2/info | jq -``` - -Jika kejadian sedang berjalan, Anda akan menerima keluaran terminal yang mirip dengan berikut ini: - -```json -{ - "peer_version": 4207599105, - "pox_consensus": "12f7fa85e5099755a00b7eaecded1aa27af61748", - "burn_block_height": 2034380, - "stable_pox_consensus": "5cc4e0403ff6a1a4bd17dae9600c7c13d0b10bdf", - "stable_burn_block_height": 2034373, - "server_version": "stacks-node 2.0.11.2.0-rc1 (develop:7b6d3ee+, release build, linux [x86_64])", - "network_id": 2147483648, - "parent_network_id": 118034699, - "stacks_tip_height": 509, - "stacks_tip": "e0ee952e9891709d196080ca638ad07e6146d4c362e6afe4bb46f42d5fe584e8", - "stacks_tip_consensus_hash": "12f7fa85e5099755a00b7eaecded1aa27af61748", - "genesis_chainstate_hash": "74237aa39aa50a83de11a4f53e9d3bb7d43461d1de9873f402e5453ae60bc59b", - "unanchored_tip": "32bc86590f11504f17904ee7f5cb05bcf71a68a35f0bb3bc2d31aca726090842", - "unanchored_seq": 0, - "exit_at_block_height": null -} -``` - -## Menghentikan noda testnet - -Gunakan perintah berikut untuk menghentikan noda testnet lokal: - -```sh -docker stop stacks-blockchain -``` - -## Bacaan tambahan - - - -- [Menjalankan noda API Stacks](https://docs.hiro.so/get-started/running-api-node) -- [Menjalankan node mainnet Stacks](running-mainnet-node) - diff --git a/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md b/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md deleted file mode 100644 index 9da4700db8..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md +++ /dev/null @@ -1,506 +0,0 @@ ---- -title: Konfigurasi Noda Stacks -description: Parameter konfigurasi dan opsi untuk biner noda-stacks -sidebar_position: 6 ---- - -## Pemakaian - -```bash -stacks-node sub-command [--subcommand-option ] -``` - -## Subperintah - -:::caution The `stacks-node` binary may have deprecated commands that are not documented on this page. Perintah yang tidak digunakan lagi mungkin dapat diakses hingga sepenuhnya dihapus dari sumbernya. ::: - -### mocknet - -Memulai noda berdasarkan penyiapan lokal cepat yang meniru burnchain. Ideal untuk pengembangan kontrak pintar. - -Contoh: - -```bash -stacks-node mocknet -``` - -### krypton - -Start a node that will join and stream blocks from the public krypton regtest, powered by Blockstack via [Proof of Transfer](../understand-stacks#consensus-mechanism). - -Contoh: - -```bash -stacks-node krypton -``` - -### testnet - -Start a node that will join and stream blocks from the public testnet. - -Contoh: - -```bash -stacks-node testnet -``` - -### mainnet - -Memulai noda yang bergabung dan mengalirkan blok dari mainnet publik. - -Contoh: - -```bash -stacks-node mainnet -``` - -### mulai - -Memulai noda dengan konfigurasi Anda sendiri. Can be used for joining a network, starting a new chain, or replacing default values used by the `mocknet` or `testnet` subcommands. - -#### Argumen - -**--config**: jalur relatif atau absolut ke file konfigurasi TOML. Diperlukan. - -Contoh: - -```bash -stacks-node start --config=/path/to/config.toml -``` - -Lihat [Opsi File Konfigurasi](#configuration-file-options) untuk informasi lebih lanjut. - -#### versi - -Menampilkan informasi tentang versi saat ini dan siklus rilis. - -Contoh: - -```bash -stacks-node version -``` - -#### bantuan - -Menampilkan pesan bantuan. - -Contoh: - -```bash -stacks-node help -``` - -## Opsi File Konfigurasi - -File konfigurasi TOML memiliki beberapa bagian di mana opsi dapat ditempatkan. - -Untuk melihat daftar contoh konfigurasi, [lihat halaman ini](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf) . - -### Bagian: noda - -Berisi berbagai opsi konfigurasi yang berkaitan dengan noda-stacks. - -Contoh: - -```toml -[node] -rpc_bind = "0.0.0.0:20443" -p2p_bind = "0.0.0.0:20444" -# Enter your private key here -seed = "replace-with-your-private-key" -miner = true -``` - -#### working_dir (opsional) - -Jalur absolut ke direktori yang akan digunakan noda-stacks untuk menyimpan berbagai data. - -Contoh: - -```toml -working_dir = "/root/stacks-node" -``` - -#### rpc_bind - -Alamat dan port noda-stacks harus diikat untuk koneksi RPC. - -Contoh: - -```toml -rpc_bind = "0.0.0.0:20443" -``` - -#### p2p_bind - -Alamat dan port noda-stacks harus diikat untuk koneksi RPC. - -Contoh: - -```toml -p2p_bind = "0.0.0.0:20444" -``` - -#### data_url (opsional) - -Alamat dan port dari mana noda-stacks akan menerima koneksi rpc yang masuk. - -Contoh: - -```toml -data_url = "1.2.3.4:20443" -``` - -#### p2p_address (opsional) - -Alamat dan port dari mana noda-stacks akan menerima koneksi p2p yang masuk. - -Contoh: - -```toml -p2p_address = "1.2.3.4:20444" -``` - -#### bootstrap_node (opsional) - -Kunci publik, alamat, dan noda-stacks port harus digunakan untuk menarik data transaksi dari saat memulai. - -Contoh: - -```toml -bootstrap_node = "047435c194e9b01b3d7f7a2802d6684a3af68d05bbf4ec8f17021980d777691f1d51651f7f1d566532c804da506c117bbf79ad62eea81213ba58f8808b4d9504ad@testnet.blockstack.org:20444" -``` - -#### wait_time_for_microblocks (opsional) - -Jumlah waktu (dalam milidetik) yang akan ditunggu oleh sebuah noda sebelum mencoba menambang sebuah blok, setelah mengejar ujung rantai yang ditautkan. Ini dapat memberi waktu untuk menyiarkan mikroblok yang akan disertakan dalam blok yang ditambang tersebut. - -Contoh: - -```toml -wait_time_for_microblocks = 15000 -``` - -#### seed (opsional) - -Kunci privat yang digunakan untuk menambang. Hanya diperlukan jika `miner` disetel ke `true`. - -Contoh: - -```toml -seed = "replace-with-your-private-key" -``` - -#### local_peer_seed (opsional) - -Kunci privat yang digunakan untuk menandatangani pesan P2P di jaringan Stacks. Ini membedakan peer jaringan dan digunakan bahkan oleh noda non-penambangan. - -Contoh: - -```toml -local_peer_seed = "replace-with-your-private-key" -``` - -#### miner (opsional) - -Menentukan apakah noda-stacks menjalankan pengikut (`false`) atau penambang (`true`). Default ke `false` jika dihilangkan. - -Contoh: - -```toml -miner = true -``` - -#### mine_microblocks (opsional) - -Menentukan apakah noda-stacks akan menambang mikroblok. Hanya akan berlaku jika `miner` disetel ke `true`. - -Contoh: - -```toml -mine_microblocks = true -``` - -#### prometheus_bind (opsional) - -Alamat dan port noda-stacks harus terbuka untuk pengumpulan metrik Prometheus. - -Contoh: - -```toml -prometheus_bind = "0.0.0.0:9153" -``` - -### Bagian: events_observer (opsional) - -Berisi opsi untuk menonton event yang dipancarkan oleh layanan [stacks-blockchain-api](https://github.com/hirosystems/stacks-blockchain-api) lokal. - -:::info -This section can be repeated multiple times. -::: - -Contoh: - -```toml -[[events_observer]] -endpoint = "address-to-my-local.stacks-node-api.com:3700" -retry_count = 255 -events_keys = ["*"] -``` - -#### endpoint - -Alamat dan port ke api-noda-stacks untuk menonton event. - -Contoh: - -```toml -endpoint = "address-to-my-local.stacks-node-api.com:3700" -``` - -#### retry_count - -Frekuensi pengiriman ulang event ke endpoint sebelum gagal. - -Contoh: - -```toml -retry_count = 255 -``` - -#### events_keys - -Kunci event yang harus ditonton. Event noda yang dipancarkan dapat dibatasi oleh akun, nama fungsi, dan jenis peristiwa. Asterix ("\*") dapat digunakan untuk memancarkan semua event. - -Contoh: - -```toml -events_keys = ["*"] -``` - -```toml -events_keys = [ - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.store::print", - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.contract.ft-token", - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.contract.nft-token", - "stx" -] -``` - -### Bagian: connection_options (opsional) - -Menentukan opsi konfigurasi untuk orang lain yang terhubung ke noda stacks. - -Contoh: - -```toml -[connection_options] -public_ip_address = "1.2.3.4:20444" -download_interval = 60 -walk_interval = 30 -``` - -#### public_ip_address - -IP publik yang diiklankan dari noda-stacks ini. - -Contoh: - -```toml -public_ip_address = "1.2.3.4:20444" -``` - -#### download_interval - -Waktu (dalam detik) antara upaya mengunduh blok. - -Contoh: - -```toml -download_interval = 60 -``` - -#### walk_interval - -Waktu (dalam detik) antara upaya untuk berjalan di sekitar lingkungan. - -Contoh: - -```toml -walk_interval = 30 -``` - -#### read_only_call_limit_read_length - -Jumlah total byte yang diizinkan untuk dibaca oleh panggilan fungsi read-only individual. - -Contoh: - -```toml -read_only_call_limit_read_length = 100000 -``` - -#### read_only_call_limit_read_count - -Jumlah total operasi baca independen yang diizinkan untuk panggilan fungsi read-only individual. - -Contoh: - -```toml -read_only_call_limit_read_count = 30 -``` - -#### read_only_call_limit_runtime - -Batas [Biaya runtime](https://github.com/stacksgov/sips/blob/2d3fd9bf8da7a04f588d90ff6252173d7609d7bf/sips/sip-006/sip-006-runtime-cost-assessment.md#introduction) untuk panggilan fungsi read-only individual. - -Contoh: - -```toml -read_only_call_limit_runtime = 1000000000 -``` - -### Bagian: burnchain - -Bagian ini berisi opsi konfigurasi yang berkaitan dengan blockchain yang diikat oleh noda-stacks di backend untuk proof-of-transfer (BTC). - -Contoh: - -```toml -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "your.bitcoind.node.org" -rpc_port = 8332 -peer_port = 8333 -``` - -#### chain - -Noda-stacks blockchain mengikat pada backend untuk proof-of-transfer. Hanya nilai yang didukung: `"bitcoin"`. - -Contoh: - -```toml -chain = "bitcoin" -``` - -#### mode - -Profil atau fase pengujian untuk menjalankan noda-stacks. Nilai yang valid adalah `"mocknet"`, `"helium"`, `"neon"`, `"argon"`, ` "krypton"`, `"xenon"`. - -Contoh: - -```toml -mode = "xenon" -``` - -#### peer_host - -Nama domain host yang menjalankan blockchain Bitcoin backend. Diperlukan untuk menjalankan noda Bitcoin pribadi secara lokal, atau menggunakan noda Bitcoin yang dihosting secara publik. - -Contoh: - -```toml -peer_host = "your.bitcoind.node.org" -``` - -#### rpc_port - -port peer_host noda-stacks akan terhubung untuk koneksi RPC. - -Contoh: - -```toml -rpc_port = 8332 -``` - -#### peer_port - -port peer_host noda-stacks akan terhubung untuk koneksi P2P. - -Contoh: - -```toml -peer_port = 8333 -``` - -#### burn_fee_cap (opsional) - -Jumlah maksimum (dalam Satoshi) dari "komitmen bakar" untuk disiarkan untuk pemilihan blok berikutnya. - -Contoh: - -```toml -burn_fee_cap = 30000 -``` - -#### satoshis_per_byte (opsional) - -Jumlah (dalam Satoshi) per [byte virtual](https://en.bitcoin.it/wiki/Weight_units). Ini digunakan untuk menghitung biaya transaksi. - -Contoh: - -```toml -satoshis_per_byte = 50 -``` - -Jadi total biaya transaksi adalah `(estimated_tx_size * satoshis_per_byte) + burn_fee_cap`. - -#### commit_anchor_block_within (opsional) - -Menetapkan periode waktu (dalam milidetik) untuk komitmen. Hanya digunakan bila `mode` disetel ke `"helium"`. - -Contoh: - -```toml -commit_anchor_block_within = 10000 -``` - -### Bagian: ustx_balance (hanya testnet/regtest) - -Bagian ini berisi opsi konfigurasi yang berkaitan dengan alokasi blok genesis untuk alamat di mikro-STX. Jika pengguna mengubah nilai-nilai ini, noda mereka mungkin bertentangan dengan noda lain di jaringan dan tidak dapat menyinkronkan dengan noda lain. - -:::info -This section can repeat multiple times, and thus is in double-brackets. Setiap bagian hanya dapat mendefinisikan satu alamat. Bagian ini diabaikan jika menjalankan noda di mainnet. -::: - -Contoh: - -```toml -[[ustx_balance]] -address = "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6" -amount = 10000000000000000 - -[[ustx_balance]] -address = "ST11NJTTKGVT6D1HY4NJRVQWMQM7TVAR091EJ8P2Y" -amount = 10000000000000000 - -[[ustx_balance]] -address = "ST1HB1T8WRNBYB0Y3T7WXZS38NKKPTBR3EG9EPJKR" -amount = 10000000000000000 - -[[ustx_balance]] -address = "STRYYQQ9M8KAF4NS7WNZQYY59X93XEKR31JP64CP" -amount = 10000000000000000 -``` - -#### address - -Alamat yang menjaga saldo mikro-STX. - -Contoh: - -```toml -address = "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6" -``` - -#### amount - -Saldo micro-STX diberikan ke alamat di awal noda. - -Contoh: - -```toml -amount = 10000000000000000 -``` diff --git a/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md b/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md deleted file mode 100644 index 094e3f03a1..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Verify Miner -description: Verify node is operating as miner -sidebar_position: 7 ---- - -You can verify that your node is operating as a miner by checking its log output to verify that it was able to find its Bitcoin UTXOs: - -```bash -$ head -n 100 /path/to/your/node/logs | grep -i utxo -INFO [1630127492.031042] [testnet/stacks-node/src/run_loop/neon.rs:146] [main] Miner node: checking UTXOs at address: -INFO [1630127492.062652] [testnet/stacks-node/src/run_loop/neon.rs:164] [main] UTXOs found - will run as a Miner node -``` \ No newline at end of file diff --git a/i18n/id/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json b/i18n/id/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json deleted file mode 100644 index f5de305558..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Noteworthy Contracts", - "position": 4, - "link": { - "type": "generated-index", - "description": "Specific deployed Clarity Contracts worth mentioning." - } -} \ No newline at end of file diff --git a/i18n/id/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md b/i18n/id/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md deleted file mode 100644 index 29c84bbc50..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md +++ /dev/null @@ -1,362 +0,0 @@ ---- -title: Kontrak BNS -description: The Blockchain Naming System. ---- - -![](/img/satoshi-btc.png) - -## Pengantar - -The Blockchain Naming System (BNS) is implemented as a smart contract using Clarity. - -Below is a list of public and read-only functions as well as error codes that can be returned by those methods: -* [Fungsi publik](#public-functions) -* [Fungsi read-only](#read-only-functions) -* [Kode kesalahan](#error-codes) - -## Fungsi publik - - -### name-import - -#### Input: `(buff 20), (buff 48), principal, (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-import namespace name beneficiary zonefile-hash)` -#### Description: -Imports name to a revealed namespace. Each imported name is given both an owner and some off-chain state. - -### name-preorder - -#### Input: `(buff 20), uint` -#### Output: `(response uint int)` -#### Signature: `(name-preorder hashed-salted-fqn stx-to-burn)` -#### Description: -Preorders a name by telling all BNS nodes the salted hash of the BNS name. It pays the registration fee to the namespace owner's designated address. - -### name-register - -#### Input: `(buff 20), (buff 48), (buff 20), (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-register namespace name salt zonefile-hash)` -#### Description: -Reveals the salt and the name to all BNS nodes, and assigns the name an initial public key hash and zone file hash. - -### name-renewal - -#### Input: `(buff 20), (buff 48), uint, (optional principal), (optional (buff 20))` -#### Output: `(response bool int)` -#### Signature: `(name-renewal namespace name stx-to-burn new-owner zonefile-hash)` -#### Description: -Depending in the namespace rules, a name can expire. For example, names in the .id namespace expire after 2 years. You need to send a name renewal every so often to keep your name. - -You will pay the registration cost of your name to the namespace's designated burn address when you renew it. When a name expires, it enters a \"grace period\". The period is set to 5000 blocks (a month) but can be configured for each namespace. - -It will stop resolving in the grace period, and all of the above operations will cease to be honored by the BNS consensus rules. You may, however, send a NAME_RENEWAL during this grace period to preserve your name. After the grace period, everybody can register that name again. If your name is in a namespace where names do not expire, then you never need to use this transaction. -### name-revoke - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(name-revoke namespace name)` -#### Description: -Makes a name unresolvable. The BNS consensus rules stipulate that once a name is revoked, no one can change its public key hash or its zone file hash. The name's zone file hash is set to null to prevent it from resolving. You should only do this if your private key is compromised, or if you want to render your name unusable for whatever reason. - -### name-transfer - -#### Input: `(buff 20), (buff 48), principal, (optional (buff 20))` -#### Output: `(response bool int)` -#### Signature: `(name-transfer namespace name new-owner zonefile-hash)` -#### Description: -Changes the name's public key hash. You would send a name transfer transaction if you wanted to: -* Change your private key -* Send the name to someone else or -* Update your zone file - -When transferring a name, you have the option to also clear the name's zone file hash (i.e. set it to null). This is useful for when you send the name to someone else, so the recipient's name does not resolve to your zone file. - -### name-update - -#### Input: `(buff 20), (buff 48), (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-update namespace name zonefile-hash)` -#### Description: -Changes the name's zone file hash. You would send a name update transaction if you wanted to change the name's zone file contents. For example, you would do this if you want to deploy your own Gaia hub and want other people to read from it. - -### namespace-preorder - -#### Input: `(buff 20), uint` -#### Output: `(response uint int)` -#### Signature: `(namespace-preorder hashed-salted-namespace stx-to-burn)` -#### Description: -Registers the salted hash of the namespace with BNS nodes, and burns the requisite amount of cryptocurrency. Additionally, this step proves to the BNS nodes that user has honored the BNS consensus rules by including a recent consensus hash in the transaction. Returns pre-order's expiration date (in blocks). - -### namespace-ready - -#### Input: `(buff 20)` -#### Output: `(response bool int)` -#### Signature: `(namespace-ready namespace)` -#### Description: -Launches the namespace and makes it available to the public. Once a namespace is launched, anyone can register a name in it if they pay the appropriate amount of cryptocurrency. - -### namespace-reveal - -#### Input: `(buff 20), (buff 20), uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, principal` -#### Output: `(response bool int)` -#### Signature: `(namespace-reveal namespace namespace-salt p-func-base p-func-coeff p-func-b1 p-func-b2 p-func-b3 p-func-b4 p-func-b5 p-func-b6 p-func-b7 p-func-b8 p-func-b9 p-func-b10 p-func-b11 p-func-b12 p-func-b13 p-func-b14 p-func-b15 p-func-b16 p-func-non-alpha-discount p-func-no-vowel-discount lifetime namespace-import)` -#### Description: -Reveals the salt and the namespace ID (after a namespace preorder). It reveals how long names last in this namespace before they expire or must be renewed, and it sets a price function for the namespace that determines how cheap or expensive names its will be.All of the parameters prefixed by `p` make up the `price function`. These parameters govern the pricing and lifetime of names in the namespace. - -The rules for a namespace are as follows: - -* a name can fall into one of 16 buckets, measured by length. Bucket 16 incorporates all names at least 16 characters long. - -* the pricing structure applies a multiplicative penalty for having numeric characters, or punctuation characters. - -* the price of a name in a bucket is `((coeff) * (base) ^ (bucket exponent)) / ((numeric discount multiplier) * (punctuation discount multiplier))` - -Contoh: - -* base = 10 -* coeff = 2 -* nonalpha discount: 10 -* no-vowel discount: 10 -* buckets 1, 2: 9 -* buckets 3, 4, 5, 6: 8 -* buckets 7, 8, 9, 10, 11, 12, 13, 14: 7 -* buckets 15, 16+: - - -## Fungsi read-only - -### can-name-be-registered - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(can-name-be-registered namespace name)` -#### Description: -Returns true if the provided name can be registered. - -### can-namespace-be-registered - -#### Input: `(buff 20)` -#### Output: `(response bool UnknownType)` -#### Signature: `(can-namespace-be-registered namespace)` -#### Description: -Returns true if the provided namespace is available. - -### can-receive-name - -#### Input: `principal` -#### Output: `(response bool int)` -#### Signature: `(can-receive-name owner)` -#### Description: -Returns true if the provided name can be received. That is, if it is not curretly owned, a previous lease is expired, and the name wasn't revoked. - -### get-name-price - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response uint int)` -#### Signature: `(get-name-price namespace name)` -#### Description: -Gets the price for a name. - -### get-namespace-price - -#### Input: `(buff 20)` -#### Output: `(response uint int)` -#### Signature: `(get-namespace-price namespace)` -#### Description: -Gets the price for a namespace. - -### get-namespace-properties - -#### Input: `(buff 20)` -#### Output: `(response (tuple (namespace (buff 20)) (properties (tuple (can-update-price-function bool) (launched-at (optional uint)) (lifetime uint) (namespace-import principal) (price-function (tuple (base uint) (buckets (list 16 uint)) (coeff uint) (no-vowel-discount uint) (nonalpha-discount uint))) (revealed-at uint)))) int)` -#### Signature: `(get-namespace-properties namespace)` -#### Description: -Get namespace properties. - -### is-name-lease-expired - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(is-name-lease-expired namespace name)` -#### Description: -Return true if the provided name lease is expired. - -### name-resolve - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response (tuple (lease-ending-at (optional uint)) (lease-started-at uint) (owner principal) (zonefile-hash (buff 20))) int)` -#### Signature: `(name-resolve namespace name)` -#### Description: -Get name registration details. - -### resolve-principal - -#### Input: `principal` -#### Output: `(response (tuple (name (buff 48)) (namespace (buff 20))) (tuple (code int) (name (optional (tuple (name (buff 48)) (namespace (buff 20)))))))` -#### Signature: `(resolve-principal owner)` -#### Description: -Returns the registered name that a principal owns if there is one. A principal can only own one name at a time. - -## Kode kesalahan - -### ERR_INSUFFICIENT_FUNDS -#### type: `int` -#### value: `4001` - -### ERR_NAMESPACE_ALREADY_EXISTS -#### type: `int` -#### value: `1006` - -### ERR_NAMESPACE_ALREADY_LAUNCHED -#### type: `int` -#### value: `1014` - -### ERR_NAMESPACE_BLANK -#### type: `int` -#### value: `1013` - -### ERR_NAMESPACE_CHARSET_INVALID -#### type: `int` -#### value: `1016` - -### ERR_NAMESPACE_HASH_MALFORMED -#### type: `int` -#### value: `1015` - -### ERR_NAMESPACE_NOT_FOUND -#### type: `int` -#### value: `1005` - -### ERR_NAMESPACE_NOT_LAUNCHED -#### type: `int` -#### value: `1007` - -### ERR_NAMESPACE_OPERATION_UNAUTHORIZED -#### type: `int` -#### value: `1011` - -### ERR_NAMESPACE_PREORDER_ALREADY_EXISTS -#### type: `int` -#### value: `1003` - -### ERR_NAMESPACE_PREORDER_CLAIMABILITY_EXPIRED -#### type: `int` -#### value: `1009` - -### ERR_NAMESPACE_PREORDER_EXPIRED -#### type: `int` -#### value: `1002` - -### ERR_NAMESPACE_PREORDER_LAUNCHABILITY_EXPIRED -#### type: `int` -#### value: `1010` - -### ERR_NAMESPACE_PREORDER_NOT_FOUND -#### type: `int` -#### value: `1001` - -### ERR_NAMESPACE_PRICE_FUNCTION_INVALID -#### type: `int` -#### value: `1008` - -### ERR_NAMESPACE_STX_BURNT_INSUFFICIENT -#### type: `int` -#### value: `1012` - -### ERR_NAMESPACE_UNAVAILABLE -#### type: `int` -#### value: `1004` - -### ERR_NAME_ALREADY_CLAIMED -#### type: `int` -#### value: `2011` - -### ERR_NAME_BLANK -#### type: `int` -#### value: `2010` - -### ERR_NAME_CHARSET_INVALID -#### type: `int` -#### value: `2022` - -### ERR_NAME_CLAIMABILITY_EXPIRED -#### type: `int` -#### value: `2012` - -### ERR_NAME_COULD_NOT_BE_MINTED -#### type: `int` -#### value: `2020` - -### ERR_NAME_COULD_NOT_BE_TRANSFERED -#### type: `int` -#### value: `2021` - -### ERR_NAME_EXPIRED -#### type: `int` -#### value: `2008` - -### ERR_NAME_GRACE_PERIOD -#### type: `int` -#### value: `2009` - -### ERR_NAME_HASH_MALFORMED -#### type: `int` -#### value: `2017` - -### ERR_NAME_NOT_FOUND -#### type: `int` -#### value: `2013` - -### ERR_NAME_NOT_RESOLVABLE -#### type: `int` -#### value: `2019` - -### ERR_NAME_OPERATION_UNAUTHORIZED -#### type: `int` -#### value: `2006` - -### ERR_NAME_PREORDERED_BEFORE_NAMESPACE_LAUNCH -#### type: `int` -#### value: `2018` - -### ERR_NAME_PREORDER_ALREADY_EXISTS -#### type: `int` -#### value: `2016` - -### ERR_NAME_PREORDER_EXPIRED -#### type: `int` -#### value: `2002` - -### ERR_NAME_PREORDER_FUNDS_INSUFFICIENT -#### type: `int` -#### value: `2003` - -### ERR_NAME_PREORDER_NOT_FOUND -#### type: `int` -#### value: `2001` - -### ERR_NAME_REVOKED -#### type: `int` -#### value: `2014` - -### ERR_NAME_STX_BURNT_INSUFFICIENT -#### type: `int` -#### value: `2007` - -### ERR_NAME_TRANSFER_FAILED -#### type: `int` -#### value: `2015` - -### ERR_NAME_UNAVAILABLE -#### type: `int` -#### value: `2004` - -### ERR_PANIC -#### type: `int` -#### value: `0` - -### ERR_PRINCIPAL_ALREADY_ASSOCIATED -#### type: `int` -#### value: `3001` diff --git a/i18n/id/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md b/i18n/id/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md deleted file mode 100644 index a976bf1908..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -title: Kontrak Stacking -description: Lihat daftar rinci semua fungsi dan kode kesalahan kontrak Stacking. ---- - -## Pengantar - -Stacking diimplementasikan sebagai kontrak pintar menggunakan Clarity. Anda selalu dapat menemukan pengidentifikasi kontrak Stacking menggunakan [`v2/pox` endpoint](https://docs.hiro.so/api#operation/get_pox_info) Blockchain Stacks API. - -Below is a list of public and read-only functions as well as error codes that can be returned by those methods: - -* [Fungsi publik](#public-functions) -* [Fungsi read-only](#read-only-functions) -* [Kode kesalahan](#error-codes) - -## Fungsi publik - -### allow-contract-caller -#### input: `principal, (optional uint)` -#### output: `(response bool int)` -#### signature: `(allow-contract-caller caller until-burn-ht)` -#### description: -Give a contract-caller authorization to call stacking methods. Normally, stacking methods may only be invoked by _direct_ transactions (i.e., the `tx-sender` issues a direct `contract-call` to the stacking methods). - -By issuing an allowance, the tx-sender may call through the allowed contract. - -### delegate-stack-stx -#### input: `principal, uint, (tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint` -#### output: `(response (tuple (lock-amount uint) (stacker principal) (unlock-burn-height uint)) int)` -#### signature: `(delegate-stack-stx stacker amount-ustx pox-addr start-burn-ht lock-period)` -#### description: -As a delegate, stack the given principal's STX using `partial-stacked-by-cycle`. - -Once the delegate has stacked > minimum, the delegate should call `stack-aggregation-commit`. - -### delegate-stx -#### input: `uint, principal, (optional uint), (optional (tuple (hashbytes (buff 20)) (version (buff 1))))` -#### output: `(response bool int)` -#### signature: `(delegate-stx amount-ustx delegate-to until-burn-ht pox-addr)` -#### description: -Delegate to `delegate-to` the ability to stack from a given address. - -This method _does not_ lock the funds, rather, it allows the delegate to issue the stacking lock. - -The caller specifies: - -* amount-ustx: the total amount of ustx the delegate may be allowed to lock -* until-burn-ht: an optional burn height at which this delegation expiration -* pox-addr: an optional p2pkh or p2sh address to which any rewards *must* be sent - -### disallow-contract-caller -#### input: `principal` -#### output: `(response bool int)` -#### signature: `(disallow-contract-caller caller)` -#### description: -Revokes authorization from a contract to invoke stacking methods through contract-calls - -### reject-pox -#### input: -#### output: `(response bool int)` -#### signature: `(reject-pox)` -#### description: -Reject Stacking for this reward cycle. - -`tx-sender` votes all its uSTX for rejection. - -Note that unlike Stacking, rejecting PoX does not lock the tx-sender's tokens: PoX rejection acts like a coin vote. - -### revoke-delegate-stx -#### input: -#### output: `(response bool int)` -#### signature: `(revoke-delegate-stx)` -#### description: -Revoke a Stacking delegate relationship. A particular Stacker may only have one delegate, so this method does not take any parameters, and just revokes the Stacker's current delegate (if one exists). - -### stack-aggregation-commit -#### input: `(tuple (hashbytes (buff 20)) (version (buff 1))), uint` -#### output: `(response bool int)` -#### signature: `(stack-aggregation-commit pox-addr reward-cycle)` -#### description: -Commit partially stacked STX. - -This allows a stacker/delegate to lock fewer STX than the minimal threshold in multiple transactions, - -so long as: - -1. The pox-addr is the same. -2. This \"commit\" transaction is called _before_ the PoX anchor block. - -This ensures that each entry in the reward set returned to the stacks-node is greater than the threshold, - - but does not require it be all locked up within a single transaction - -### stack-stx -#### input: `uint, (tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint` -#### output: `(response (tuple (lock-amount uint) (stacker principal) (unlock-burn-height uint)) int)` -#### signature: `(stack-stx amount-ustx pox-addr start-burn-ht lock-period)` -#### description: -Lock up some uSTX for stacking! Note that the given amount here is in micro-STX (uSTX). - -The STX will be locked for the given number of reward cycles (lock-period). - -This is the self-service interface. tx-sender will be the Stacker. - -* The given stacker cannot currently be stacking. -* You will need the minimum uSTX threshold. This isn't determined until the reward cycle begins, but this method still requires stacking over the _absolute minimum_ amount, which can be obtained by calling `get-stacking-minimum`. -* The pox-addr argument must represent a valid reward address. Right now, this must be a Bitcoin p2pkh or p2sh address. It cannot be a native Segwit address, but it may be a p2wpkh-p2sh or p2wsh-p2sh address. - -The tokens will unlock and be returned to the Stacker (tx-sender) automatically. - -## Fungsi read-only - -### can-stack-stx -#### input: `(tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint, uint` -#### output: `(response bool int)` -#### signature: `(can-stack-stx pox-addr amount-ustx first-reward-cycle num-cycles)` -#### description: -Evaluate if a participant can stack an amount of STX for a given period. - -### get-pox-info -#### input: -#### output: `(response (tuple (current-rejection-votes uint) (first-burnchain-block-height uint) (min-amount-ustx uint) (prepare-cycle-length uint) (rejection-fraction uint) (reward-cycle-id uint) (reward-cycle-length uint) (total-liquid-supply-ustx uint)) UnknownType)` -#### signature: `(get-pox-info)` -#### description: -Returns information about PoX status. - -### get-pox-rejection -#### input: `principal, uint` -#### output: `(optional (tuple (amount uint)))` -#### signature: `(get-pox-rejection stacker reward-cycle)` -#### description: -Returns the amount of uSTX that a given principal used to reject a PoX cycle. - -### get-stacker-info -#### input: `principal` -#### output: `(optional (tuple (amount-ustx uint) (first-reward-cycle uint) (lock-period uint) (pox-addr (tuple (hashbytes (buff 20)) (version (buff 1))))))` -#### signature: `(get-stacker-info stacker)` -#### description: -Returns the _current_ stacking information for `stacker. If the information is expired, or if there's never been such a stacker, then returns none. - -### get-stacking-minimum -#### input: -#### output: `uint` -#### signature: `(get-stacking-minimum)` -#### description: -Returns the absolute minimum amount that could be validly Stacked (the threshold to Stack in a given reward cycle may be higher than this - -### get-total-ustx-stacked -#### input: `uint` -#### output: `uint` -#### signature: `(get-total-ustx-stacked reward-cycle)` -#### description: -Returns the amount of currently participating uSTX in the given cycle. - -### is-pox-active -#### input: `uint` -#### output: `bool` -#### signature: `(is-pox-active reward-cycle)` -#### description: -Returns whether or not PoX has been rejected at a given PoX cycle. -## Kode kesalahan - -### ERR_DELEGATION_EXPIRES_DURING_LOCK -#### type: `int` -#### value: `21` - -### ERR_DELEGATION_POX_ADDR_REQUIRED -#### type: `int` -#### value: `23` - -### ERR_DELEGATION_TOO_MUCH_LOCKED -#### type: `int` -#### value: `22` - -### ERR_INVALID_START_BURN_HEIGHT -#### type: `int` -#### value: `24` - -### ERR_NOT_ALLOWED -#### type: `int` -#### value: `19` - -### ERR_STACKING_ALREADY_DELEGATED -#### type: `int` -#### value: `20` - -### ERR_STACKING_ALREADY_REJECTED -#### type: `int` -#### value: `17` - -### ERR_STACKING_ALREADY_STACKED -#### type: `int` -#### value: `3` - -### ERR_STACKING_EXPIRED -#### type: `int` -#### value: `5` - -### ERR_STACKING_INSUFFICIENT_FUNDS -#### type: `int` -#### value: `1` - -### ERR_STACKING_INVALID_AMOUNT -#### type: `int` -#### value: `18` - -### ERR_STACKING_INVALID_LOCK_PERIOD -#### type: `int` -#### value: `2` - -### ERR_STACKING_INVALID_POX_ADDRESS -#### type: `int` -#### value: `13` - -### ERR_STACKING_NO_SUCH_PRINCIPAL -#### type: `int` -#### value: `4` - -### ERR_STACKING_PERMISSION_DENIED -#### type: `int` -#### value: `9` - -### ERR_STACKING_POX_ADDRESS_IN_USE -#### type: `int` -#### value: `12` - -### ERR_STACKING_STX_LOCKED -#### type: `int` -#### value: `6` - -### ERR_STACKING_THRESHOLD_NOT_MET -#### type: `int` -#### value: `11` - -### ERR_STACKING_UNREACHABLE -#### type: `int` -#### value: `255` \ No newline at end of file diff --git a/i18n/id/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md b/i18n/id/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md deleted file mode 100644 index 411e6d242e..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: xBTC -description: Wrapped BTC on Stacks ---- - -![](/img/xbtc-icon.webp) - -## Pengantar - -[Wrapped.com](https://www.wrapped.com) has brought Bitcoin (xBTC) to the Stacks ecosystem. - -xBTC is backed 1:1 by Bitcoin and empowers developers to expand the Bitcoin DeFi ecosystem. - -The reserves are publicly visible [here](https://open.wrapped.com/reserves/). - -## Contract - -[SP3DX3H4FEYZJZ586MFBS25ZW3HZDMEW92260R2PR.Wrapped-Bitcoin](https://explorer.stacks.co/txid/SP3DX3H4FEYZJZ586MFBS25ZW3HZDMEW92260R2PR.Wrapped-Bitcoin?chain=mainnet) - -## Examples of uses - -[Friedger Mining Pool](https://pool.friedger.de/) currrently supports Stacking rewards payments in xBTC (optional). - - -## More information - -* [Blog post announcement](https://www.stacks.co/blog/tokensoft-wrapped-fundamental-bitcoin-defi-building-blocks-xbtc) by Muneeb Ali - -* Video: [Why xBTC is Important For Bitcoin to Grow](https://www.youtube.com/watch?v=xIoadrfSdi4) \ No newline at end of file diff --git a/i18n/id/docusaurus-plugin-content-docs/current/references/_category_.json b/i18n/id/docusaurus-plugin-content-docs/current/references/_category_.json deleted file mode 100644 index aa2deec477..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/references/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Referensi", - "position": 9, - "link": { - "type": "generated-index", - "description": "Stacks references." - } -} \ No newline at end of file diff --git a/i18n/id/docusaurus-plugin-content-docs/current/references/glossary.md b/i18n/id/docusaurus-plugin-content-docs/current/references/glossary.md deleted file mode 100644 index 53174e2764..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/references/glossary.md +++ /dev/null @@ -1,215 +0,0 @@ ---- -title: Glosarium -description: Daftar lengkap istilah yang digunakan dalam ekosistem. ---- - -Daftar lengkap istilah yang digunakan dalam ekosistem. - -#### App Review -An incentive mechanism for application developers in the early stage (first four years) of the ecosystem and helps with bootstrapping the two-sided market. - -#### Atlas -A peer network provide a global index for discovery. - -#### Bitcoin (BTC) address -A string of letters and numbers. `3E53XjqK4Cxt71BGeP2VhpcotM8LZ853C8` Sharing this address allows anyone to send Bitcoin to the address. - -#### block -A discrete group of records written to a blockchain that can effectively be identified and referenced by the use of headers that contain a digital fingerprint of the records each block contains. - -#### blockchain -A database created and shared by the members of a peer-to-peer computer network which each member of that network can independently trust due to the rules governing the database’s creation. A blockchain can therefore be used to replace centralized databases. - -#### Blockchain Name System (BNS) -Replacement for DNS. More info [here](../noteworthy-contracts/bns-contract). - -#### Blockstack Browser -A deprecated application for accessing identity and storage. - -#### Blockstack Owner Address - -Looks like a bitcoin address but starts with `ID` for example: `ID-1J3PUxY5uDShUnHRrMyU6yKtoHEUPhKULs` - -#### Burning -Burning a token means that the token is transferred to an address that is a black hole—one that is not owned by any entity and for which guessing the applicable private key is effectively impossible based on known mathematical principles. This effectively destroys the token by making it unavailable for future use and decreases the total number of tokens available from that point forward. - -#### consensus hash -A consensus hash is a cryptographic hash that each node calculates at each block. It is derived from the accepted state transitions in the last-processed block and a geometric series of prior-calculated consensus hashes. - -#### Consensus rules -"The rules governing the creation of new valid records in a blockchain database and the mining algorithms used for this purpose. - -#### control plane -The part of a network that carries signaling traffic and is responsible for routing. Control packets originate from or are destined for a router. Functions of the control plane include system configuration and management. - -#### core node -A server that runs Stacks Blockchain services. - -#### crypto-asset -A digital asset which utilises cryptography, peer-to-peer networking and a public ledger to regulate the creation of new units, verify transactions and secure the transactions without the intervention of any middleman. - -#### cryptography -The practise and study of encryption and decryption - encoding data so that it can only be decoded by specific individuals. A system for encrypting and decrypting data is a cryptosystem. - -#### DAO -See Decentralized Autonomous Organization. - -#### decentralized application (DApp) -A DApp is a service that enables direct interaction between end users and providers (e.g. connecting buyers and sellers in some marketplace, owners and stores in file storage). A term coined by Ethereum. See their glossary: http://ethdocs.org/en/latest/glossary.html#dapp" - -#### Decentralized Autonomous Organization -A type of contract or suite of contracts on the blockchain that is intented to codify, enforce or automate the processes of an organization. - -#### digital asset -Also referred to as a crypto-asset. Any set of unique digital information—including, for example, programs, decentralized programs, isolated chunks of programming code, collections of data, e-mail or web addresses or cryptocurrency tokens—that is capable of being stored and uniquely tracked on a computer network such as the Stacks network and over which a user can maintain control through that network. - -#### digital fingerprint -A digital fingerprint is a unique number of a fixed length that can be produced by running any set of digital information through something called a cryptographic hash function. Each set of digital information (including a digital asset, and the digital record of any network operation on that digital asset) should (as a practical matter) have a unique digital fingerprint, which allows that set of digital information to be identified. However, it is almost impossible to recreate a digital asset from its digital fingerprint. The Blockstack network uses industry-standard algorithms such as SHA-256 to create digital fingerprints. - -#### digital signature -A digital signature is a sequence of digital information combining a user’s private key and any digital information that the user wishes to sign. Any other party can use the user’s paired public key to verify that the digital signature is authentic, i.e. that the public key was generated from a particular piece of digital information and the user’s private key. - -#### distributed hash tables (DHT) -A form of network used to store some content in the form of key/value pairs. ... This experimental project try to avoid keeping all the blockchain, but instead prefers to store it in a DHT. - -#### ephemeral key -A cryptographic key is called ephemeral if it is generated for each execution of a key establishment process. - -#### fork -The term fork is used to refer both to any situation where there are two or more competing versions of a blockchain on a network (a situation that may arise and resolve itself in the ordinary course of network operations due to lags in communication between core nodes) and any software update that is proposed for adoption by the core nodes of a blockchain network that may result in a persistent fork on the network, with core nodes that adopt the update recognizing one version of the blockchain and those which do not recognizing another. - -#### Gaia -Decentralized storage architecture for off-chain data. More info [here](../gaia). - -#### genesis block -The genesis block is the first block of the Stacks blockchain, which will create the initial 1.32 billion Stacks Tokens. - -#### id.blockstack -An identifier in the Blockstack, for example meepers.id.blockstack. This is your name & identity that is registered in the .id namespace on Blockstack. Your personal data and storage are built around this ID. Apps that want to access your data use your permission and identity to find it. An id is usually a shorthand for a longer, hash ID string, for example ID-1Fj9kkw15P51Fj9kkw15P5xJmyefWhLKrQMKNPREfaqsJ" - -#### identity - -A way to identify a person or an organization on the Stacks network. An identity is unique, both `meepers.id.blockstack` or `chad.id` are examples of IDs. - -#### identity management (IDM) -Identity management, also known as identity and access management is, in computer security, the security and business discipline that enables the right individuals to access the right resources at the right times and for the right reason". - -#### know your customer (KYC) -Or KYC, is a popular term used in the banking or financial field. KYC is a process where financial institutions, insurers and other companies obtain information about the identity and address of the customers as part of risk management. - -#### light clients -Clients that can independently validate the existence of transactions by downloading only block headers and not the entire blockchain. - -#### magic recovery code - -A long encrypted string, for example: `36mWivFdy0YPH2z31EflpQz/Y0UMrOrJ++lH=0EI7c3mop2JuRBm5WXxSTazJsUjOA...` Do not share the QR code that accompanied your recovery code either. This is a QR code: - -![](/img/qr-code.png) - -#### mesh network -A local network topology in which the infrastructure nodes (i.e. bridges, switches, and other infrastructure devices) connect directly, dynamically and non-hierarchically to as many other nodes as possible and cooperate with one another to efficiently route data from/to clients. - -#### mining -Mining generally refers to the process of performing certain functions for a network such as adding new records to a blockchain in exchange for mining rewards; it may also refer to other mechanisms whereby rewards (usually in the form of cryptocurrency) are provided for performing other tasks helpful to the network. - -#### mining power -A miner’s (or group of miners’) mining power is equal to the probability it will be selected to write a new block to the blockchain. Depending on the mechanism for mining, this is usually related to the overall share of computing power or cryptoassets the miner or miners possess relative to all miners for that blockchain. - -#### mining rewards -Mining rewards are newly issued tokens received by miners in exchange for adding new records to the blockchain or other activities beneficial to the network. - -#### name -An identifier or name. Names are a type of digital asset in the Stacks network. If you have signed into the Stacks Wallet, you might have created a name. If an application developer registered an application within Stacks, then they registered a name. Public Stacking pools can also have a name. - -#### network operation -A network operation is any change to the information about a digital asset (or smart contract) stored on a blockchain, including, for example, a change in the digital asset’s owner, or a change in the location at which it is stored on the network. How and when these network operations are performed for each digital asset is governed, on the Blockstack network, either by the Stacks Node software or a smart contract. - -#### NFT -Non fungible token. - -#### private key - -Private keys matches a corresponding public key. A public key also looks like a string of letters and numbers: - -![](/img/private.png) - -The exact format of the public and private key depend on the software you use to create them. - -#### proof-of-burn mining -The consensus algorithm used in the Stacks blockchain where miners destroy a proof-of-work-based cryptocurrency (currently Bitcoin) to get tokens; this enables the functionality where nodes can select between conflicting blockchain forks, as the blockchain fork with the most amount of cryptocurrency burned is considered to be the correct fork. - -#### proof-of-work -A proof-of-work system or proof-of-work mining is a mining mechanism where miners must expend computing power to solve complicated cryptographic puzzles, and prove that they have done so by writing the solution to the blockchain, in order to be allowed to add blocks to a blockchain. This is the mining system used, for example, by Bitcoin. - -#### public key -Public and private key pair comprise of two uniquely related cryptographic keys. It looks like a long random string of letters and numbers: `3048 0241 00C9 18FA CF8D EB2D EFD5 FD37 89B9 E069 EA97 FC20 …` The exact format of the public and private key depend on the software you use to create them. - -#### Public Key Infrastructure (PKI) -A system which returns a cryptographic public key associated with a name. - -#### replicated state machines (RSMs) -This is a model for reasoning about distributed computer programs -- any program (plus it's input) can be represented as a state machine, and when trying to get a distributed set of servers to agree on the output of an algorithm, you can model that process as N different state machines" - -#### Secret recovery Key, -Used to access an identity on the Stacks blockchain. A 24-word sequence of words for example: `applied binge crisp pictorial fiery` `dancing agreeable frogs light finish ping apple` - -#### seed phrase - -Used to access Stacks Wallet software. The seed phrase consists of 24 words in a sequence. Both the word *and its position the sequence* are important. Write down your seed phrase and store it in a secure location such as a safe deposit box. When you write the seed phrase down, include its position, for example,`1-frog, 2-horse, 3-building` and so on until you reach a final position `24-ocean`. -#### smart contract -A smart contract is a computer program written to a blockchain such as the Stacks blockchain by developers. This computer program defines the various network operations that can be performed on the digital assets on the blockchain, the computations that can be performed using the smart contract, along with defining various important properties of the respective digital assets like ownership rights and the cost in fuel required to register the digital assets. - -#### soft fork -A soft fork is a proposed update to the software governing the network that results in a post-update network that is compatible with the network as it existed prior to the update, because it restricts the network operations that can be performed after the update. - -#### Stacks (STX) address - - A STX address is a string of letters and numbers starting with an `SP` or `SM`, for example: `SM3KJBA4RZ7Z20KD2HBXNSXVPCR1D3CRAV6Q05MKT` If you created a software-only wallet with the Stacks Wallet software, the wallet has a single STX address which is also sometimes called the *wallet address*. You access a software wallet with a *seed phrase*. " - -#### Stacks blockchain -The Stacks blockchain is the custom blockchain being developed for use by the Stacks network that will use the Stacks token as its native currency and which will include the genesis block and subsequent blocks created by the mining activities described in the Stacks Network—Development of the Stacks network. - -#### Stacks Explorer -An application that allow you to view and search transactions in the blockchain. For example, https://explorer.stacks.co. - -#### Stacks node -A complete version of our open-source software available on Github at https://github.com/stacks-network/stacks-blockchain/ that governs the creation of the blockchain, the smart contracts that may be written to our blockchain, and other systems that make up the Stacks network, when run on the systems and devices of our users and developers. - -#### Stacks wallet -An application for accessing assets, identity and storage. More information and example [here](../services-using-stacks/wallets). Examples are the [Hiro Wallet](https://www.hiro.so/wallet), [xverse](https://www.xverse.app/) and [dcent](https://dcentwallet.com/). - -#### storage hub -A Gaia instance run by a hub provider or software. A Gaia hub stores data in a separate, addressed location. - -#### storage provider -A third-party company cloud or software provider that hosts one or more Gaia storage hubs. - -#### transaction -A transaction is a unit of work within a block. - -#### transaction fee -Fees paid by participants in a transaction to miners. - -#### two-sided market problem -Economic platforms having two distinct user groups that provide each other with network benefits. The Stacks platform is a classic two-sided market. - -#### username -A shorthand name for your id.blockstack. - -#### virtual blockchain -A layer that sits on top of a blockchain that introduces new functionality and operations without requiring changes to the underlying blockchain. - -#### wallet address -A wallet address is the form in which a public key can be presented and recorded on a blockchain. Wallet addresses are therefore used to assign the ownership of digital assets on the Blockstack network. - -#### watch-only wallet -A wallet without send and receive ability. You can view only balances and transaction history. - -#### web of trust mining -Web-of-trust mining provides incentive mechanisms for users where an initial trusted-set of unique users is curated in the genesis block and, in the future, the initial set of users can expand the web-of-trust after the network goes live. - -#### web3 -The exact definition is still under discussion, but it general refers to the 3rd generation of the web that is based on blockchain technology and incorporates decentralized and token-based economics. - -#### zone file -A Domain Name System (DNS) zone file is a text file that describes a DNS zone. A DNS zone is a subset, often a single domain, of the hierarchical domain name structure of the DNS. diff --git a/i18n/id/docusaurus-plugin-content-docs/current/references/nft.md b/i18n/id/docusaurus-plugin-content-docs/current/references/nft.md deleted file mode 100644 index 033ee0a71a..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/references/nft.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: NFTs on Stacks -description: A list of sites that operate NFTs on Stacks ---- - -List of sites that operate NFTS on Stacks on alphabetical order. - -### [Byzantion](https://byzantion.xyz/) - -![website-screenshot](/img/sh_nft_byzantion.png) - -### [Gamma](https://gamma.io/) -![website-screenshot](/img/sh_nft_gamma.png) - -### [Megapont](https://www.megapont.com/) - -![website-screenshot](/img/sh_nft_megapont.png) - -### [StacksArt](https://www.stacksart.com/) - -![website-screenshot](/img/sh_nft_stacksart.png) - diff --git a/i18n/id/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md b/i18n/id/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md deleted file mode 100644 index 3486936892..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Situs info Stacks -description: Daftar situs berdasarkan abjad yang menampilkan status dan statistik jaringan Stacks. ---- - -### [Haystack](https://haystack.tools/mempool) - -![website-screenshot](/img/sh_haystacks.png) - -### [Stacksdata](https://stacksdata.info/) - -![website-screenshot](/img/sh_stacksdata.png) - -### [Stacksonchain](https://stacksonchain.com) - -![website-screenshot](/img/sh_stacksonchain.png) - -### [Status Hiro](https://status.hiro.so/) - -![website-screenshot](/img/sh_statushiro.png) - -### [Stxstats](https://www.stxstats.co/) - -![website-screenshot](/img/sh_stxstats.png) - -### [Novuminsights](https://stacks.novuminsights.com/health) - -![website-screenshot](/img/sh_novuminsights.png) - -### [Onstacks](https://app.onstacks.com/) - -![website-screenshot](/img/sh_onstacks.png) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json b/i18n/id/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json deleted file mode 100644 index ebd63f366c..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Services using Stacks", - "position": 8, - "link": { - "type": "generated-index", - "description": "An 'always incomplete' list of services that use Stacks." - } -} \ No newline at end of file diff --git a/i18n/id/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md b/i18n/id/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md deleted file mode 100644 index 51defacba7..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: DeFi -description: De-Fi sites on Stacks -sidebar_position: 2 ---- - -They are multiple De-Fi sites that operate on the Stacks blockchain. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Alex - -[Alex](https://app.alexlab.co) ![](/img/sh_alex.png) - -## Arkadiko - -[Arkadiko](https://arkadiko.finance/) ![](/img/sh_arkadiko.png) - -## Catamaran Swaps - -[Catamaran Swaps](https://www.catamaranswaps.org/) allows trustless exchange of digital assets. - -![](/img/sh_catamaran.png) - -## Lnswap - -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange - -![](/img/sh_lnswap.png) - -## Neoswap - -[Neoswap](https://neoswap.party) - -![](/img/sh_neoswap.png) - -## Stackswap - -[Stackswap](https://app.stackswap.org/v2) - -![](/img/sh_stackswap.png) - diff --git a/i18n/id/docusaurus-plugin-content-docs/current/services-using-stacks/more.md b/i18n/id/docusaurus-plugin-content-docs/current/services-using-stacks/more.md deleted file mode 100644 index df0b3e2254..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/services-using-stacks/more.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: More -description: More services built on Stacks. -sidebar_position: 5 ---- - -List of sites on alphabetical order added by the community. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Citycoins - -[Citycoins](https://citycoins.co) - -![](/img/sh_citycoins.png) - -## Sigle - -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. - -![](/img/sh_sigle.png) \ No newline at end of file diff --git a/i18n/id/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md b/i18n/id/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md deleted file mode 100644 index bfa0505dc9..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: NFTs -description: NFTs on Stacks -sidebar_position: 3 ---- - -List of sites that operate NFTS on Stacks on alphabetical order. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -### [Byzantion](https://byzantion.xyz/) - -![website-screenshot](/img/sh_nft_byzantion.png) - -### [Gamma](https://gamma.io/) -![website-screenshot](/img/sh_nft_gamma.png) - -### [Megapont](https://www.megapont.com/) - -![website-screenshot](/img/sh_nft_megapont.png) - -### [StacksArt](https://www.stacksart.com/) - -![website-screenshot](/img/sh_nft_stacksart.png) - -### [Superfandom](https://superfandom.io/) - -![website-screenshot](/img/sh_superfandom.png) \ No newline at end of file diff --git a/i18n/id/docusaurus-plugin-content-docs/current/services-using-stacks/other.md b/i18n/id/docusaurus-plugin-content-docs/current/services-using-stacks/other.md deleted file mode 100644 index 199fc41da5..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/services-using-stacks/other.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Other Stacks sites -description: A list of sites on alphabetical order built on Stacks. -sidebar_position: 4 ---- - -List of sites on alphabetical order added by the community. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Alex -[Alex](https://app.alexlab.co) - -## Sigle - -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. \ No newline at end of file diff --git a/i18n/id/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md b/i18n/id/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md deleted file mode 100644 index 5ad27b2901..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Situs info Stacks -description: Status and stats of the Stacks network. -sidebar_position: 1 ---- - -Daftar situs berdasarkan abjad yang menampilkan status dan statistik jaringan Stacks. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -### [Haystack](https://haystack.tools/mempool) - -![website-screenshot](/img/sh_haystacks.png) - -### [Stacksdata](https://stacksdata.info/) - -![website-screenshot](/img/sh_stacksdata.png) - -### [Stacksonchain](https://stacksonchain.com) - -![website-screenshot](/img/sh_stacksonchain.png) - -### [Status Hiro](https://status.hiro.so/) - -![website-screenshot](/img/sh_statushiro.png) - -### [Stxstats](https://www.stxstats.co/) - -![website-screenshot](/img/sh_stxstats.png) - -### [Novuminsights](https://stacks.novuminsights.com/health) - -![website-screenshot](/img/sh_novuminsights.png) - -### [Onstacks](https://app.onstacks.com/) - -![website-screenshot](/img/sh_onstacks.png) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md b/i18n/id/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md deleted file mode 100644 index d4b4cbf18c..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Swaps -description: A list of sites that allow Swaps -sidebar_position: 2 ---- - -They are multiple sites that allow you to make swaps using the Stacks blockchain. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Catamaran Swaps - -[Catamaran Swaps](https://www.catamaranswaps.org/) allows trustless exchange of digital assets. - -![](/img/sh_catamaran.png) - -## Lnswap - -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange - -![](/img/sh_lnswap.png) - -## Neoswap - -[Neoswap](https://neoswap.party) - -![](/img/sh_neoswap.png) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md b/i18n/id/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md deleted file mode 100644 index e33ca3010d..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Wallet -description: Wallets for Stacks -sidebar_position: 4 ---- - -A list of hardware and software wallets for Stacks - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Blockchain.com - -[Blockchain.com](https://www.blockchain.com/wallet) - -![](/img/sh_blockchain.png) -## Boom - -[Boom](https://boom.money) - -![](/img/sh_boom.png) - -## Dcent wallet - -[D'CENT](https://dcentwallet.com) - -![](/img/sh_dcent.png) -## Hiro Wallet - -[Hiro Wallet](https://www.hiro.so/wallet) - -![](/img/sh_hirowallet.png) - -## Neptune - -[Neptune](https://neptunewallet.io) - -![](/img/sh_neptunewallet.png) - -## Xverse - -[Xverse](https://www.xverse.app/) - -![](/img/sh_xverse.png) - -## Wise - -[Wise](https://wiseapp.id) - -![](/img/sh_wiseapp.png) \ No newline at end of file diff --git a/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md b/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md deleted file mode 100644 index cc9fced09f..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md +++ /dev/null @@ -1,214 +0,0 @@ ---- -title: Akun -description: Panduan untuk akun Stacks 2.0 -sidebar_position: 5 ---- - -## Pengantar - -Akun dalam Stacks 2.0 adalah suatu entitas yang memiliki aset, seperti token Stacks (STX). Suatu akun memiliki alamat, kunci rahasia, nonce, dan satu atau lebih saldo aset. - -:::tip The encryption algorithm used in Stacks 2.0 is **[secp256k1](https://en.bitcoinwiki.org/wiki/Secp256k1)**. - -Additionally, [Ed25519](https://ed25519.cr.yp.to/) is also used just for the VRF (Verifiable Random Function). ::: - -Aset tidak bisa meninggalkan suatu akun tanpa tindakan dari pemilik akun. Semua perubahan terhadap aset (dan saldo dari akun) membutuhkan transaksi terkait. - -:::tip -The transaction type doesn't need to be a token transfer - contract deploy and contract call transactions can change the balances of an account -::: - -## Pembuatan - -Suatu akun dibuat dari frasa 24-kata mnemonic. Hal ini sering disebut juga sebagai **frasa seed**. Frasa seed memberikan akses ke akun Stacks 2.0. - -:::danger -If the seed phrase is lost, access to the associated account cannot be restored. Tidak ada seseorang atau organisasi, termasuk Blockstacks, yang dapat memulihkan frasa seed yang hilang. -::: - -Cara paling mudah untuk membuat sebuah akun Stacks 2.0 baru adalah dengan [Stacks CLI](https://github.com/hirosystems/stacks.js/tree/master/packages/cli): - -```bash -# install CLI globally -npm install --global @stacks/cli - -# generate a new account and store details in a new file -# '-t' option makes this a testnet account -stx make_keychain -t > cli_keychain.json -``` - -`make_keychain` membuat file berikut: - -```js -{ - "mnemonic": "aaa bbb ccc ddd ...", - "keyInfo": { - "privateKey": "5a3f1f15245bb3fb...", - "address": "STJRM2AMVF90ER6G3RW1QTF85E3HZH37006D5ER1", - "btcAddress": "biwSd6KTEvJcyX2R8oyfgj5REuLzczMYC1", - "wif": "L4HXn7PLmzoNW...", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -| Bidang | Deskripsi | -| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `mnemonic` | Sebuah frasa seed 240kata digunakan untuk mengakses akun, dibuat menggunakan [BIP39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) dengan 256 bit entropi | -| `keyInfo.privateKey` | Kunci privat untuk akun. Dibutuhkan untuk transfer token dan sering dirujuk sebagai `senderKey` | -| `keyInfo.address` | Alamat Stacks untuk akun | -| `keyInfo.btcAddress` | Alamat BTC yang sesuai untuk akun. | -| `keyInfo.wif` | Kunci privat btcAddress dalam format terkompresi. | -| `keyInfo.index` | Nonce untuk akun, dimulai dari 0 | - -Perlu dicatat bahwa akun baru secara otomatis tersedia untuk setiap kunci privat. Tidak perlu memulai proses pembuatan akun di blockchain Stacks 2.0. - -:::tip Addresses are created by generating the [RIPEMD-160 hash](https://en.wikipedia.org/wiki/RIPEMD#RIPEMD-160_hashes) of the [SHA256](https://en.bitcoinwiki.org/wiki/SHA-256) of the public key. Alamat BTC dikodekan dengan [Base58Check](https://en.bitcoin.it/wiki/Base58Check_encoding). Untuk alamat Stacks, [c32check](https://github.com/stacks-network/c32check) digunakan. Menurunkan suatu alamat dari kunci publik dapat dilakukan tanpa adanya akses internet, contohnya menggunakan metode c32check `c32addressDecode`. ::: - -Sebagai alternatif untuk pembuatan CLI, pustaka [Transaksi Stacks JS](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) dapat digunakan: - -```js -import { - makeRandomPrivKey, - privateKeyToString, - getAddressFromPrivateKey, - TransactionVersion, -} from '@stacks/transactions'; - -const privateKey = makeRandomPrivKey(); - -// Get public key from private -const publicKey = getPublicKey(privateKey); - -const stacksAddress = getAddressFromPrivateKey( - privateKeyToString(privateKey), - TransactionVersion.Testnet // remove for Mainnet addresses -); -``` - -Alternatif lain dapat menggunakan [stacks-gen](https://github.com/psq/stacks-gen). Alat ini dapat membuat semua kunci yang dibutuhkan dalam satu tempat, termasuk nilai yang dibutuhkan untuk memanggil kontrak stacking, dan juga kunci WIF untuk digunakan dengan `bitcoind`. - -#### prasyarat stacks-gen - -Install [npx](https://github.com/npm/npx) jika belum terpasang. (npx akan mengecek apakah `` sudah ada di \$PATH, atau di daftar file biner proyek lokal dan menjalankannya. Jika `` tidak ditemukan, program akan terpasang sebelum dijalankan). - -``` -npm install -g npx -``` - -#### penggunaan stacks-gen - -``` -npx -q stacks-gen sk --testnet - -{ - "phrase": "guide air pet hat friend anchor harvest dog depart matter deny awkward sign almost speak short dragon rare private fame depart elevator snake chef", - "private": "0351764dc07ee1ad038ff49c0e020799f0a350dd0769017ea09460e150a6401901", - "public": "022d82baea2d041ac281bebafab11571f45db4f163a9e3f8640b1c804a4ac6f662", - "stacks": "ST16JQQNQXVNGR8RZ1D52TMH5MFHTXVPHRV6YE19C", - "stacking": "{ hashbytes: 0x4d2bdeb7eeeb0c231f0b4a2d5225a3e3aeeed1c6, version: 0x00 }", - "btc": "mnYzsxxW271GkmyMnRfiopEkaEpeqLtDy8", - "wif": "cMh9kwaCEttgTQYkyMUYQVbdm5ZarZdBHErcq7mXUChXXCo7CFEh" -} -``` - -:::tip The stacking object with hashbytes and a version represents the bitcoin address derived from the Stacks address. Read more about the [bitcoin address format](stacking#bitcoin-address). ::: - -Dokumentasi lengkap terdapat di [stacks-gen](https://github.com/psq/stacks-gen). - -## Melakukan query - -### Mendapatkan saldo dan nonce Stacks (STX) - -Saldo dan nonce STX dapat diperoleh melalui [`GET /v2/accounts/`](https://docs.hiro.so/api#operation/get_account_info) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/accounts/' -``` - -Contoh respon: - -```js -{ - "balance": "0x0000000000000000002386f26f3f40ec", - "nonce": 17 -} -``` - -:::tip -The balance string represents an unsigned 128-bit integer (big-endian) in hex encoding -::: - -### Dapatkan semua saldo token - -Semua saldo token dapat diperoleh melalui [`GET /extended/v1/address//balances`](https://docs.hiro.so/api#operation/get_account_balance) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/address//balances' -``` - -Contoh respon: - -```js -{ - "stx": { - "balance": "0", - "total_sent": "0", - "total_received": "0" - }, - "fungible_tokens": {}, - "non_fungible_tokens": {} -} -``` - -:::tip Stacks accounts cannot hold bitcoins. Cara terbaik untuk mendapatkan saldo BTC yang sesuai adalah dengan mendapatkan alamat BTC dari alamat Stacks (menggunakan [`c32check`](https://github.com/stacks-network/c32check#c32tob58-b58toc32)) dan kueri jaringan Bitcoin. ::: - -### Dapatkan semua event aset - -Semua event aset yang terkait dengan akun dapat diperoleh melalui [`GET /extended/v1/address// aset`](https://docs.hiro.so/api#operation/get_account_balance) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/address//assets' -``` - -Contoh respon: - -```js -{ - "limit": 20, - "offset": 0, - "total": 0, - "results": [ - { - "event_index": 5, - "event_type": "non_fungible_token_asset", - "asset": { - "asset_event_type": "transfer", - "asset_id": "ST2W14YX9SFVDB1ZGHSH40CX1YQAP9XKRAYSSVYAG.hello_world::hello-nft", - "sender": "SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR", - "recipient": "SM2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQVX8X0G", - "value": { - "hex": "0x0100000000000000000000000000000001", - "repr": "u1" - } - } - }, - { - "event_index": 3, - "event_type": "fungible_token_asset", - "asset": { - "asset_event_type": "mint", - "asset_id": "ST2W14YX9SFVDB1ZGHSH40CX1YQAP9XKRAYSSVYAG.hello_world::novel-token-19", - "sender": "", - "recipient": "SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR", - "amount": "12" - } - } - ] -} -``` diff --git a/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/index.md b/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/index.md deleted file mode 100644 index aa7392a00f..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/index.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Memahami Stacks -description: Pelajari lebih lanjut tentang blockchain Stacks 2.0 -sidebar_position: 1 ---- - -![](/img/SBC-L-2x-10.png) -## Pengantar - -Stacks 2.0 adalah blockchain lapisan-1 yang terhubung ke Bitcoin dan membawa kontrak pintar dan aplikasi terdesentralisasi ke dalamnya. Kontrak pintar dan aplikasi yang dikembangkan di platform Stacks secara native terintegrasi dengan keamanan, stabilitas, dan kekuatan ekonomi Bitcoin. - -## Kemampuan - -Baca lebih lanjut tentang fitur-fitur yang disediakan blockchain Stacks 2.0. - - - -:::tip Check out the [technical specifications](technical-specs) for a brief overview ::: - - - - -A detailed [comparison of the Stacks blockchain to other blockchain technologies][] is available at the Stacks Foundation blog. -### Mekanisme konsensus -![](/img/pages/stacking.svg) Stacks 2.0 mengimplementasikan mekanisme penambangan baru yang disebut Proof of Transfer ("PoX"). PoX adalah algoritma konsensus antara dua blockchain. Menggunakan blockchain yang sudah mapan (dalam hal ini Bitcoin) untuk mengamankan blockchain baru (Stacks). - -PoX terhubung ke Bitcoin dengan rasio blok 1:1, artinya apa pun yang terjadi di blockchain Stacks dapat diverifikasi di Blockchain Bitcoin. - -Instead of burning electricity on proof of work, PoX reuses already minted bitcoins as "proof of computation" and miners represent their cost of mining in bitcoins directly. - - -[Read more about Proof of Transfer](proof-of-transfer) -### Penambangan - -![](/img/pages/testnet-sm.svg) Menambang diperlukan untuk membuat jaringan dapat digunakan, dapat dipercaya, dan aman. Penambang memverifikasi transaksi masuk, berpartisipasi dalam mekanisme konsensus, dan menulis blok baru ke blockchain. - -Untuk memberi insentif pada penambangan, penambang menerima token Stacks (STX) yang baru dicetak jika mereka memenangkan tawaran untuk menjadi pemimpin putaran berikutnya. - -[Read more about Mining](mining) - -### Stacking - -Bitcoin yang digunakan untuk tawaran penambang dikirim ke sekumpulan alamat spesifik yang sesuai dengan pemegang token Stacks (STX) yang secara aktif berpartisipasi dalam konsensus ("Stackers"). Jadi, alih-alih dihancurkan, bitcoin yang digunakan dalam proses penambangan diberikan kepada pemegang Stacks yang produktif sebagai hadiah berdasarkan kepemilikan Stacks dan partisipasi mereka dalam algoritma Stacking. - -Stacker harus mengunci token Stacks (STX) mereka untuk jangka waktu tertentu. - -[Read more about Stacking](stacking) - -### Kontrak pintar - -![](/img/pages/write-smart-contracts-sm.svg) Clarity adalah bahasa baru untuk kontrak pintar di blockchain Stacks 2.0. Bahasa kontrak cerdas Clarity mengoptimalkan prediktabilitas dan keamanan. - -Stacks 2.0 menambatkan kontrak pintar Clarity ke Bitcoin sehingga memungkinkan kontrak pintar untuk beroperasi berdasarkan tindakan yang terlihat pada blockchain bitcoin. - -:::note The [Clarity open-source project](https://clarity-lang.org/) is supported by Stacks and [Algorand](https://www.algorand.com/) ::: - - -Clarity berbeda dari bahasa lain yang dirancang untuk menulis kontrak pintar dalam beberapa cara: - -- **Prediktabilitas**: Bahasa Clarity menggunakan sintaks yang tepat dan tidak ambigu yang memungkinkan pengembang memprediksi dengan tepat bagaimana kontrak mereka akan dijalankan. -- **Keamanan**: Bahasa Clarity memungkinkan pengguna untuk menyediakan kondisi mereka sendiri untuk transaksi yang memastikan bahwa kontrak tidak akan pernah tiba-tiba mentransfer token yang dimiliki oleh pengguna. -- **Tidak ada kompiler**: Kontrak yang ditulis dalam Clarity disebarkan di blockchain Stacks persis seperti yang ditulis oleh pengembang. Ini memastikan bahwa pengembang kode yang menulis, menganalisis, dan menguji, persis seperti yang dijalankan. - -[Read more about Clarity](../write-smart-contracts/clarity-language/) - -## Panduan - -Baca salah satu panduan kami untuk memahami seluk beluk blockchain Stacks 2.0. - -* [Account](../understand-stacks/accounts) -* [Transaksi](../understand-stacks/transactions) -* [Jaringan](../understand-stacks/network) -* [Mikroblok](../understand-stacks/microblocks) - -[comparison of the Stacks blockchain to other blockchain technologies]: https://stacks.org/stacks-blockchain diff --git a/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md b/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md deleted file mode 100644 index 45bbe6e420..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: Mikroblok -description: Panduan untuk Mikroblok Stacks -sidebar_position: 8 ---- - -## Pengantar - -Mikroblok adalah fitur level-protokol dari blockchain Stacks yang dapat menyelesaikan tantangan teknis dari latensi transaksi. Because each Stacks block is anchored to a Bitcoin block through the [Proof-of-Transfer consensus mechanism](../understand-stacks/proof-of-transfer), Stacks is necessarily limited to the same block times as the Bitcoin network. Mikroblok memungkinkan blockchain Stacks untuk melakukan transisi status antara blok tertaut. - -Microblocks are a powerful mechanism for developers to create performant, high quality applications on Stacks, while still inheriting the security of Bitcoin. - -## Status transaksi - -The [Stacks block production model](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.) is described in SIP-001. Standar tersebut menguraikan mekanisme di mana pemimpin blok terpilih dapat menghasilkan blok di blockchain Stacks baik dengan mengelompokkan transaksi atau dengan mengalirkannya. Mikroblok adalah produk dari model streaming. - -Jika pemimpin blok telah memilih untuk menambang mikroblok, pemimpin memilih transaksi dari mempool dan mengemasnya menjadi mikroblok pada epoch saat ini. Mikroblok adalah blok transaksi yang dimasukkan oleh penambang setelah blok tertaut sebelumnya ditambang, namun sebelum blok berikutnya dipilih. Transaksi yang termasuk dalam mikroblok diproses oleh jaringan: hasilnya akan diketahui. - -Pertimbangkan suatu transaksi dari perspektif jumlah konfirmasi blok yang dimilikinya. Transaksi yang termasuk dalam mikroblok dapat memiliki siklus hidup sebagai berikut: - -``` -Transaksi 1 disiarkan ke mempool. Awalnya memiliki 0 konfirmasi. -Transaksi 1 telah dimasukkan ke dalam mikroblok. Sekarang masih memiliki 0 konfirmasi, namun hasil dari transaksi sudah diketahui. Transaksi 1 telah dimasukan ke dalam blok tertaut berikutnya. Sekarang memiliki 1 konfirmasi. -Blok Stacks berikutnya mengkonfimasi blok sebelumnya. Transaksi 1 sekarang memiliki 2 konfirmasi. -Blok Stacks berikutnya mengkonfimasi blok sebelumnya. Transaksi 1 sekarang memiliki 3 konfirmasi. -... -``` - -Pertimbangkan suatu transaksi serupa yang belum dimasukkan ke dalam suatu mikroblok: - -``` -Transaksi 2 disiarkan ke mempool. Awalnya memiliki 0 konfirmasi. -Transaksi 2 telah dimasukkan ke dalam blok tertaut berikutnya. Sekarang memiliki 1 konfirmasi. -Blok Stacks berikutnya mengkonfimasi blok sebelumnya. Transaksi 2 sekarang memiliki 2 konfirmasi. -Blok Stacks berikutnya mengkonfimasi blok sebelumnya. Transaksi 2 sekarang memiliki 3 konfirmasi. -``` - -Siklus hidup dari dua transaksi tersebut mirip, namun perbedaannya terdapat pada status tertunda. Banyak wallet Bitcoin menampilkan saldo 0-konfirmasi: saldo wallet Anda dengan transaksi mempool apapun yang telah terjadi. Hal ini berguna karena dapat menunjukkan pada Anda ketika Anda sudah mengirim atau menerima transaksi. Dengan kontrak pintar, menampilkan status tertunda bukan suatu proses yang sederhana, karena pada kontrak pintar bukan hanya terdapat transfer tapi juga perpindahan dari input ke output, kontrak pintar juga dapat memanggil kontrak pintar lainnya, memancarkan event, atau melakukan komputasi lainnya. Transaksi yang diproses dalam mikroblok menghasilkan semua informasi itu. - -:::tip -If a transaction is dependent on a chain state that could by altered by previous transactions with serious -implications, you should carefully consider whether it should be performed using microblocks. -::: - -## Mengaktifkan mikroblok - -Penambang dapat memilih untuk mengaktifkan atau menonaktifkan mikroblok pada konfigurasi penambangan. Sebagai praktik terbaik, penambang harus mengaktifkan penambangan mikroblok. Ketika aplikasi atau pengguna mengirimkan transaksi, transaksi tersebut dapat menyertakan argumen yang mengharuskan transaksi berada dalam mikroblok, blok tertaut, atau salah satunya. - -### Transaksi - -Transaksi mencakup opsi yang mengontrol apakah penambang harus memasukkannya ke dalam mikroblok atau blok tertaut. Opsi transaksi mode tertaut adalah argumen opsional yang mengontrol apakah suatu transaksi harus disertakan dalam blok tertaut atau mikroblok, atau memenuhi syarat untuk salah satunya. - -### Penambangan - -Penambang Stacks harus mengaktifkan mikroblok dalam konfigurasi penambangnya untuk menerapkan model streaming blok. For more information, see [mining microblocks](../understand-stacks/mining#microblocks). - -## Mengembangkan dengan mikroblok - -Pada kebanyakan kasus, informasi dari transaksi yang ada pada mikroblok harus diperlakukan seperti informasi yang datang dari blok lain. Wallet dan penjelajah menampilkan konsekuensi transaksi mikroblok sebagai keadaan jaringan saat ini. Keadaannya tentatif. - -Suatu transaksi mikroblok dapat direorganisasi pada blok berikutnya alih-alih dikonfirmasi apa adanya. Karena itu, UI Anda harus bisa mengkomunikasikan kepada pengguna jika keluaran transaksi berubah, atau jika blok terkait transaksi berubah. Ini adalah hasil yang sama seperti jika terjadi percabangan 1 blok. - -### Pustaka Stacks.js - -Stacks.js provides the [AnchorMode][] argument on transaction objects so that your application can set the microblocks preference for transactions. - -### API - -:::danger API support for microblocks is a work-in-progress. Review the [API documentation][microblocks_api] carefully to ensure that you are up-to-date on the latest implementation details for microblocks. ::: - -API Blockchain Stacks mengeluarkan mikroblok melalui berbagai endpoint. Please review the [Stacks Blockchain API guide][] for more details. - -## Praktik Terbaik - -Bekerja dengan mikroblok adalah keputusan desain yang harus Anda lakukan untuk aplikasi yang Anda buat. Ketika bekerja dengan mikroblok, praktik terbaik berikut ini disarankan. - -### Menangani nonce - -Penanganan nonce dengan mikroblok merupakan hal yang menantang karena akun nonce berikutnya harus memperhitungkan nilai nonce yang termasuk dalam mikroblok, yang mungkin belum termasuk dalam blok tertaut. The Stacks Blockchain API [provides an endpoint][] to retrieve the next nonce for a given principal. - -### Desain Aplikasi - -Keadaan dari transaksi mikroblok harus secara cermat dikomunikasikan ke pengguna. Tidak ada transaksi yang menjadi final sebelum dimasukkan ke dalam blok tertaut, dan desain aplikasi Anda harus menunjukkan ini. - -The following guidelines are provided as an initial set of best practices for UI design when incorporating microblocks into your application. - -#### Penjelajah - -Menampilkan status tertunda, namun memperingatkan bahwa transaksi masih tertunda. Diindikasikan secara visual bahwa saldo yang ditampilkan bergantung pada status tertunda. - -#### Wallet - -Menampilkan status tertunda, namun memperingatkan bahwa transaksi masih tertunda. Diindikasikan secara visual bahwa saldo yang ditampilkan bergantung pada status tertunda. - -#### Bursa - -Melanjutkan untuk menghitung konfirmasi, status mikroblok masih dianggap sebagai tertunda. - -#### Aplikasi - -Komunikasi mikroblok sangat bergantung terhadap aplikasi. Untuk beberapa aplikasi, menampilkan transaksi yang masih tertunda atau 0-konfirmasi sebagai terkonfirmasi mungkin tidak apa-apa. Misalnya, menyimpan data di rantai, atau mengqueri kontrak BNS. Untuk aplikasi lain, seperti mengirim nilai nyata, menunggu 3-konfirmasi akan lebih bijaksana sebelum menampilkan status sebagai terkonfirmasi. - -[AnchorMode]: https://stacks.js.org/enums/transactions.AnchorMode.html -[Stacks Blockchain API guide]: https://docs.hiro.so/get-started/stacks-blockchain-api#microblocks-support -[provides an endpoint]: https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling -[microblocks_api]: https://docs.hiro.so/api#tag/Microblocks diff --git a/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/mining.md b/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/mining.md deleted file mode 100644 index bc94011f7d..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/mining.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Penambangan -description: Panduan untuk menambang di Stacks 2.0 -sidebar_position: 4 ---- - -## Pengantar - -Panduan ini menggaris bawahi beberapa detail teknis terkait menambang pada jaringan Stacks 2.0. - -For steps on how to setup your own miner please refer to [miner on tesnet](nodes-and-miners/miner-testnet.md) and [miner on mainnet](nodes-and-miners/miner-testnet.md). - -## Frekuensi menambang - -Blok Stacks baru dapat ditambang satu kali per blok Bitcoin. Untuk dapat dipertimbangkan menambang sebuah blok, seorang penambang harus memiliki komit blok yang disertakan dalam blok Bitcoin. Jika penambang ingin memperbarui komitmen mereka setelah pengumpulan, mereka dapat menggunakan Bitcoin Replace-By-Fee. - -## Hadiah coinbase - -Penambang menerima hadiah coinbase untuk blok yang mereka menangkan. - -Jumlah hadiahnya adalah: - -- 1000 STX per blok dikeluarkan pada 4 tahun pertama penambangan -- 500 STX per blok dikeluarkan selama 4 tahun berikutnya -- 250 STX per blok dikeluarkan selama 4 tahun berikutnya -- 125 STX per blok dikeluarkan mulai dari saat itu dan seterusnya. - -"Halving" ini disinkronkan dengan halving Bitcoin. - -![hadiah coinbase](/img/pages/coinbase-rewards.png) - -## Biaya transaksi - -Penambang menerima biaya Stacks untuk transaksi yang ditambang untuk setiap blok yang mereka produksi. - -Untuk transaksi yang ditambang di mikroblok, penambang yang memproduksi mikroblok menerima 40% dari biaya, sedangkan penambang yang mengkonfirmasi mikroblok menerima 60% dari biaya. - -## Maturitas hadiah - -Hadiah blok dan biaya transaksi membutuhkan 100 blok pada jaringan Bitcoin untuk menjadi matur. Setelah berhasil menambang blok, hadiah akan muncul di akun Stacks selama kurang lebih ~24 jam. - -## Menambang menggunakan proof-of-transfer - -Penambang berkomitmen mengeluarkan Bitcoin ke **dua** alamat pada setiap pemilihan ketua blok. Jumlah yang dikomit untuk setiap alamat harus sama. Alamat dipilih dari peserta penerima hadiah stacking saat ini. Alamat dipilih menggunakan fungsi-acak-terverifikasi, dan menentukan dua alamat yang tepat untuk blok tertentu memerlukan pemantauan rantai Stacks. - -![menambang dengan pox](/img/pages/mining-with-pox.png) - -## Kemungkinan untuk menambang blok berikutnya - -Penambang yang dipilih untuk menambang blok berikutnya dipilih tergantung pada jumlah BTC yang dikirim oleh penambang, yaitu ditransfer atau dibakar. - -Kemungkinan penambang untuk menambang blok berikutnya sama dengan BTC yang dikirim penambang dibagi dengan total BTC yang dikirim oleh semua penambang. - -Meskipun tidak ada komitmen BTC minimum yang diwajibkan oleh protokol, dalam praktiknya, ada batasan yang dibatasi oleh [dust](https://unchained-capital.com/blog/dust-thermodynamics/)": yang pada dasarnya, jika biaya untuk suatu transaksi melebihi nilai pengeluaran yang dikeluarkan, itu dianggap sebagai dust. Bagaimana dust [dihitung](https://github.com/bitcoin/bitcoin/blob/master/src/policy/policy.cpp#L14) tergantung dari beberapa faktor, kita menemukan bahwa 5.500 satoshi adalah batas bawah untuk setiap [keluaran](https://learnmeabitcoin.com/technical/output). Transaksi Bitcoin dari penambang Stacks memiliki dua keluaran (untuk Proof-of-Transfer), jadi suatu komitmen paling tidak 11,000 satoshi / blok yang direkomendasikan. - -Untuk menghitung jumlah BTC yang dikirim penambang harus: - -- Menebak harga BTC/STX untuk hari berikutnya (100 blok kemudian) -- Menebak jumlah BTC yang digunakan oleh semua penambang - -## Mikroblok - -Jaringan blokchain Stacks membuat blok pada kecepatan yang sama seperti blockchain Bitcoin. Untuk menghasilkan latensi transaksi yang lebih rendah, penambang dapat mengaktifkan mikroblok. Mikroblok memungkinkan pemimpin blok saat ini untuk mengalirkan transaksi dan memasukkan status transisinya ke dalam epoch saat ini. - -Jika suatu pemimpin blok memilih untuk memproduksi mikroblok, pemimpin berikutnya harus membuat rantai dari ujung transaksi mikroblok yang pemimpin saat ini hasilkan. - -Model streaming blok dijelaskan di [SIP-001][]. - -[SIP-001]: https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md#operation-as-a-leader diff --git a/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/network.md b/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/network.md deleted file mode 100644 index 1dac3fd91c..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/network.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: Jaringan -description: Panduan jaringan Stacks 2.0 -sidebar_position: 7 ---- - -## Token - -Token Stacks (STX) merupakan token native di jaringan blokchain Stacks 2.0. Bagian terkecilnya adalah satu mikro-STX. 1.000.000 mikro-STX sama dengan satu Stacks (STX). - -Jumlah STX harus disimpan sebagai bilangan bulat (panjang 8 bytes), dan mewakili jumlah mikro-STX. Sebagai gambaran, mikro-STX dibagi dengan 1.000.000 (6 digit desimal). - -## Biaya - -Biaya digunakan untuk memberi insentif kepada penambang untuk mengkonfirmasi transaksi di jaringan blockhchain Stacks 2.0. Biaya tersebut dihitung berdasarkan perkiraan tarif biaya dan ukuran transaksi dalam byte. Tingkat biaya adalah variabel yang ditentukan oleh pasar. For the [testnet](testnet), it is set to 1 micro-STX. - -Perkiraan biaya dapat diperoleh melalui endpoint [`GET /v2/fees/transfer`](https://docs.hiro.so/api#operation/get_fee_transfer): - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/fees/transfer' -``` - -API akan merespons dengan tarif biaya (sebagai bilangan bulat): - -```json -1 -``` - -[Pustaka Transaksi Stacks JS](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) mendukung estimasi biaya untuk: - -- transfer token (`estimateTransfer`) -- penyebaran kontrak (`estimateContractDeploy`) -- panggilan kontrak non read-only (`estimateContractFunctionCall`) - -:::tip For an implementation using a different language than JavaScript, please review [this reference implementation](https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/src/builders.ts#L97). ::: - -## Nonce - -Setiap akun membawa [properti nonce](https://en.wikipedia.org/wiki/Cryptographic_nonce) yang menunjukkan jumlah transaksi yang diproses untuk akun yang diberikan. Nonce adalah kode satu kali, dimulai dari `0` untuk akun baru, dan bertambah 1 pada setiap transaksi. - -Nonce ditambahkan ke semua transaksi dan membantu mengidentifikasinya untuk memastikan transaksi diproses secara berurutan untuk menghindari pemrosesan ganda. - -:::tip -The consensus mechanism also ensures that transactions aren't "replayed" in two ways. Pertama, noda mengqueri output transaksi yang tidak terpakai (UTXOs) untuk memenuhi kondisi pengeluaran mereka dalam transaksi baru. Kedua, pesan yang dikirim antar noda meninjau nomor urut. -::: - -Ketika transaksi transfer token baru dibuat, nonce akun terbaru perlu diambil dan diatur. - -:::tip The API provides an endpoint to [simplify nonce handling](https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling). ::: - -## Konfirmasi - -Jaringan Stacks 2.0 ditautkan ke jaringan bitcoin. Ini memungkinkan transaksi di Stacks untuk mendapat finalitas dan keamanan yang sama dari jaringan blockchain Bitcoin. - -Waktu untuk menambang satu blok, untuk mengkonfirmasi transaksi, pada akhirnya akan sesuai dengan "waktu blok" yang diharapkan dari jaringan bitcoin: 10 menit. - -:::tip Transactions can also be mined in [microblocks](microblocks), reducing the latency significantly. ::: - -The block time is hardcoded and will change throughout the implementation phases of the [testnet](testnet). Waktu blok terkini dapat diperoleh melalui endpoint [`GET /extended/v1/info/network_block_times`](https://docs.hiro.so/api#operation/get_network_block_times): - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/info/network_block_times' -``` - -API akan merespons dengan waktu blok (dalam detik): - -```js -{ - "testnet": { - "target_block_time": 120 - }, - "mainnet": { - "target_block_time": 600 - } -} -``` - -## Panggilan fungsi read-only - -Kontrak pintar dapat memperlihatkan panggilan fungsi publik. Untuk fungsi yang membuat modifikasi status pada blockchain, transaksi perlu dibuat dan disebarkan. - -Namun, untuk panggilan fungsi read-only, transaksi **tidak** diperlukan. Sebagai gantinya, panggilan ini dapat dilakukan menggunakan [Stacks Blockchain API](https://docs.hiro.so/get-started/stacks-blockchain-api). - -:::tip -Read-only function calls do not require transaction fees -::: - -Panggilan kontrak read-only dapat dilakukan menggunakan endpoint [`POST /v2/contracts/call-read///`](https://docs.hiro.so/api#operation/call_read_only_function): - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl --location --request POST 'https://stacks-node-api.testnet.stacks.co/v2/contracts/call-read///' \ ---header 'Content-Type: application/json' \ ---data-raw '{ - "sender": ".", - "arguments": [, ...] -}' -``` - -Contoh respons untuk panggilan yang berhasil: - -```js -{ - "okay": true, - "result": "" -} -``` - -:::tip To set the function call arguments and read the result, [Clarity values](../write-smart-contracts/values) need to be serialized into a hexadecimal string. The [Stacks Transactions JS](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library supports these operations ::: - -## Melakukan query - -Detail jaringan Stacks 2.0 dapat di-query menggunakan [API Blockchain Stacks](https://docs.hiro.so/get-started/stacks-blockchain-api). - -### Cek kesehatan - -[Pemeriksa status](https://stacks-status.com/) adalah layanan yang menyediakan antarmuka pengguna untuk meninjau kesehatan blockchain Stacks 2.0 dengan cepat. - -### Informasi jaringan - -Informasi jaringan dapat diperoleh menggunakan endpoint [`GET /v2/info`](https://docs.hiro.so/api#operation/get_core_api_info): - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/info' -``` - -Contoh respon: - -```js -{ - "peer_version": 385875968, - "burn_consensus": "826401d65cf3671210a3fb135d827d549c0b4d37", - "burn_block_height": 1972, - "stable_burn_consensus": "e27ea23f199076bc41a729d76a813e125b725f64", - "stable_burn_block_height": 1971, - "server_version": "blockstack-core 0.0.1 => 23.0.0.0 (master:bdd042242+, release build, linux [x86_64]", - "network_id": 2147483648, - "parent_network_id": 3669344250, - "stacks_tip_height": 933, - "stacks_tip": "1f601823fbcc5b6b2215b2ff59d2818fba61ee4a3cea426d8bc3dbb268005d8f", - "stacks_tip_burn_block": "54c56a9685545c45accf42b5dcb2787c97eda8185a1c794daf9b5a59d4807abc", - "unanchored_tip": "71948ee211dac3b241eb65d881637f649d0d49ac08ee4a41c29217d3026d7aae", - "exit_at_block_height": 28160 -} -``` diff --git a/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md b/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md deleted file mode 100644 index 33df6521ad..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Proof of Transfer -description: Memahami mekanisme konsensus proof-of-transfer -sidebar_position: 3 ---- - -## Ringkasan - -Algoritma konsensus untuk blockchain membutuhkan sumber daya komputasi atau finansial untuk mengamankan blockchain. Praktik umum dari konsensus terdesentralisasi adalah dengan membuatnya secara praktis tidak memungkinkan bagi setiap aktor jahat untuk memiliki kekuatan komputasi yang cukup atau kepemilikan saham untuk menyerang jaringan. - -Mekanisme konsensus populer di blockchain modern termasuk proof-of-work, di mana noda mendedikasikan sumber daya komputasi, dan proof-of-stake, di mana noda mendedikasikan sumber daya keuangan untuk mengamankan jaringan. - -Proof-of-burn adalah mekanisme konsensus baru di mana para penambang bersaing dengan 'membakar' (menghancurkan) mata uang kripto proof-of-work sebagai proxy untuk sumber daya komputasi. - -Proof-of-transfer (PoX) adalah perpanjangan dari mekanisme proof-of-burn. PoX menggunakan mata uang kripto proof-of-work dari blockchain yang sudah ada untuk mengamankan blockchain baru. Namun, tidak seperti proof-of-burn, alih-alih membakar mata uang kripto, penambang mentransfer mata uang kripto yang berkomitmen ke beberapa peserta lain dalam jaringan. - -![Mekanisme PoX](/img/pox-mechanism.png) - -Ini memungkinkan peserta jaringan untuk mengamankan jaringan mata uang kripto PoX dan mendapatkan hadiah dalam mata uang kripto dasar. Maka dari itu, blockchain proof-of-transfer terkait pada rantai proof-of-work pilihan mereka. Stacks menggunakan [Bitcoin](#why-bitcoin) sebagai rantai tertautnya. - -![Peserta PoX](/img/pox-participants.png) - -## Mengapa Bitcoin? - -Ada beberapa alasan mengapa Stacks memilih Bitcoin sebagai blockchain untuk mendukung konsensus. Ini adalah protokol blockchain tertua, yang diluncurkan pada tahun 2009, dan telah menjadi aset yang diakui di luar komunitas mata uang kripto. BTC telah memegang kapitalisasi pasar tertinggi dari semua mata uang kripto selama dekade terakhir ini. - -Bitcoin unggul pada kesederhanaan dan stabilitas, dan telah teruji oleh waktu. Mempengaruhi atau menyerang jaringan akan menjadi sulit atau tidak praktis bagi peretas yang berpotensial. Ini adalah satu-satunya mata uang kripto yang menarik perhatian publik. Bitcoin adalah nama rumah tangga, dan diakui sebagai aset oleh pemerintah, perusahaan besar, dan lembaga perbankan warisan. Terakhir, Bitcoin sebagian besar dianggap sebagai penyimpan nilai yang andal, dan menyediakan infrastruktur yang luas untuk mendukung mekanisme konsensus proof-of-transfer. - -SIP-001 memberikan [daftar lengkap alasan mengapa Bitcoin dipilih untuk mengamankan Stacks](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md). - -![btc-stacks](/img/pox-why-bitcoin.png) - -## Blok dan mikroblok - -Blockchain Stacks memungkinkan peningkatan transaksi melalui mekanisme yang disebut mikroblok. Bitcoin dan Stacks berkembang secara bertahap, dan blok mereka dikonfirmasi secara bersamaan. Di Stacks, ini disebut sebagai 'blok tertaut'. Seluruh blok transaksi Stacks sesuai dengan satu transaksi Bitcoin. Ini secara signifikan meningkatkan rasio biaya/byte untuk memproses transaksi Stacks. Karena produksi blok yang secara simultan, Bitcoin bertindak sebagai pembatas kecepatan untuk membuat blok Stacks, sehingga mencegah serangan penolakan layanan pada jaringan rekanannya. - -Namun, di antara blok terkait Stacks yang menetap di blockchain Bitcoin, ada juga sejumlah mikroblok yang memungkinkan penyelesaian transaksi Stacks secara cepat dengan tingkat kepercayaan yang tinggi. Hal ini memungkinkan transaksi Stacks untuk menskalakan secara independen dari Bitcoin, sambil tetap secara berkala menetapkan finalitas dengan rantai Bitcoin. Blockchain Stacks mengadopsi model streaming blok di mana setiap pemimpin dapat secara adaptif memilih dan mengemas transaksi ke dalam blok mereka saat mereka tiba di mempool. Oleh karena itu ketika blok terkait dikonfirmasi, semua transaksi dalam aliran mikroblok induk dikemas dan diproses. Ini merupakan metode yang belum pernah terjadi sebelumnya untuk mencapai skalabilitas tanpa membuat protokol yang benar-benar terpisah dari Bitcoin. - -![stx-mikroblok](/img/stx-microblocks.png) - -## Membuka kunci modal Bitcoin - -Stacks juga membuka ratusan miliar modal dalam Bitcoin, dan memberi para Bitcoiner peluang baru untuk menggunakan dan mendapatkan BTC. Stacks merupakan pendamping ekosistem Bitcoin, dan dua jaringan yang bekerja bersama-sama memungkinkan cara yang benar-benar baru dalam menggunakan BTC. Ekosistem Stacks membuat aplikasi mata uang kripto yang interaktif tersedia untuk pemegang Bitcoin. Selain itu, dengan stacking token STX dan berpartisipasi dalam mekanisme konsensus PoX, pengguna memiliki kesempatan untuk mendapatkan BTC sambil mengamankan rantai Stacks. - -![Membuka kunci Bitcoin](/img/pox-unlocking-btc.png) - -## Clarity dan status Bitcoin - -Kontrak pintar Clarity juga memiliki visibilitas unik ke dalam status blockchain Bitcoin. Ini berarti bahwa logika kontrak dalam file Clarity memiliki kemampuan untuk memicu ketika transaksi Bitcoin tertentu dikonfirmasi. Kontrak cerdas Clarity memiliki bukti Verifikasi Pembayaran Sederhana (SPV) bawaan untuk Bitcoin yang membuat interaksi dengan status Bitcoin menjadi lebih mudah bagi pengembang. Selain itu, kontrak Clarity dapat bercabang dengan rantai Bitcoin yang asli. Oleh karena itu, dalam kasus di mana Bitcoin bercabang, pengembang tidak perlu khawatir untuk menyesuaikan penerapan kontrak pintar mereka. - -## Lihat juga - -- [Baca whitepaper PoX lengkap](https://community.stacks.org/pox) -- [Watch Executive Chair of Hiro Muneeb Ali and Evangelist Joe Bender give an overview of Stack's breakthrough PoX mining mechanism](https://www.youtube.com/watch?v=NY_eUrIcWOY) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md b/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md deleted file mode 100644 index a9861aafd3..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: Stacking -description: Pengantar mekanisme hadiah Proof-of-Transfer -sidebar_position: 9 ---- - -## Pengantar - -Stacking memberi hadiah kepada pemegang token Stacks (STX) dengan bitcoin karena menyediakan layanan berharga ke jaringan dengan mengunci token mereka untuk waktu tertentu. - -![](/img/stacking.png) - -Stacking merupakan tindakan bawaan, yang diperlukan oleh mekanisme "Proof-of-Transfer" (PoX). Mekanisme PoX dijalankan oleh setiap penambang di jaringan Stacks 2.0. - -:::info The Stacking consensus algorithm is implemented as a smart contract, using [Clarity](../write-smart-contracts/). [Read more about the contract](../noteworthy-contracts/stacking-contract). ::: - -## Alur Stacking - -Mekanisme Stacking dapat disajikan sebagai berikut: - -![Alur Stacking](/img/stacking-illustration.png) - -1. Melakukan panggilan API untuk mendapatkan detail tentang siklus hadiah yang akan datang -2. Untuk akun Stacks tertentu, mengkonfirmasikan kelayakannya -3. Mengkonfirmasikan alamat hadiah BTC dan durasi penguncian -4. Transaksi disebarkan dan token STX dikunci. Ini perlu terjadi sebelum fase persiapan dari siklus hadiah berikutnya, 100 blok Bitcoin terakhir dari fase hadiah yang sedang berlangsung -5. Mekanisme Stacks dalam menjalankan siklus hadiah dan mengirimkan hadiah ke alamat hadiah BTC yang ditetapkan -6. Selama periode penguncian, detail tentang waktu pembukaan kunci, hadiah, dan lainnya dapat diperoleh -7. Setelah periode penguncian berlalu, token dilepaskan dan dapat diakses kembali -8. Menampilkan riwayat hadiah, termasuk detail seperti penghasilan untuk siklus hadiah sebelumnya - -:::info Keep in mind that the target duration for a reward cycles is ~2 weeks. Durasi ini didasarkan pada waktu blok target jaringan (10 menit) dan bisa lebih tinggi karena [varians waktu konfirmasi](https://www.blockchain.com/charts/median-confirmation-time) dari jaringan bitcoin. ::: - -## Alur pendelegasian Stacking - -Alur Stacking berbeda untuk kasus penggunaan delegasi: - -![Alur pendelegasian Stacking](/img/stacking-delegation-illustration.png) - -- Sebelum Stacking dapat dimulai untuk pemegang token, delegator harus diberikan izin ke Stacks atas nama pemilik akun. Izin dibatasi hingga jumlah maksimum yang diizinkan untuk di-Stack oleh delegator. Jumlah maksimum tidak dibatasi oleh dana yang tersedia dan dapat diatur sehingga jauh lebih tinggi. Sebuah akun hanya dapat diasosiasikan dengan satu delegator -- Akun harus mendefinisikan hubungan delegasi. Mereka secara opsional dapat membatasi alamat hadiah Bitcoin yang harus digunakan untuk pembayaran, dan ketinggian blok bakar kedaluwarsa untuk izin, sehingga membatasi waktu delegator memiliki izin untuk Stack -- Delegator harus mengunci Stacks dari akun yang berbeda ("fase gabungan") hingga mencapai jumlah minimum Stacks yang diperlukan untuk berpartisipasi dalam Stacking -- Setelah delegator mengunci token STX yang cukup, mereka dapat menyelesaikan dan melakukan partisipasi mereka dalam siklus hadiah berikutnya -- Hubungan delegasi tertentu memungkinkan pemegang STX untuk menerima pembayaran langsung dari penambang (langkah 5/6) -- Pemutusan hubungan delegasi dapat terjadi secara otomatis berdasarkan aturan kedaluwarsa yang ditetapkan atau secara aktif mencabut hak delegasi - -## Penambangan PoX - -Penambangan PoX adalah modifikasi dari penambangan Proof-of-Burn (PoB), alih-alih mengirim Bitcoin yang berkomitmen ke alamat pembakaran, Bitcoin akan ditransfer ke pemegang STX yang memenuhi syarat yang berpartisipasi dalam protokol stacking. - -:::note -A PoX miner can only receive newly minted STX tokens when they transfer Bitcoin to eligible owners of STX tokens -::: - -![Alur menambang](/img/pox-mining-flow.png) - -Penambang menjalankan noda Stacks dengan penambangan aktif untuk berpartisipasi dalam mekanisme PoX. Noda mengimplementasikan mekanisme PoX, yang memastikan penanganan dan insentif yang tepat melalui empat fase utama: - -- Pendaftaran: penambang mendaftar untuk pemilihan mendatang dengan mengirimkan data konsensus ke jaringan -- Komitmen: penambang terdaftar mentransfer Bitcoin untuk berpartisipasi dalam pemilihan. BTC yang berkomitmen dikirim ke satu kumpulan pemegang token STX yang berpartisipasi -- Pemilihan: fungsi acak terverifikasi memilih satu penambang untuk menulis blok baru di blockchain Stacks -- Perakitan: penambang terpilih menulis blok baru dan mengumpulkan hadiah dalam bentuk token STX baru - -## Persyaratan pemegang token - -Pemegang token Stacks (STX) tidak secara otomatis menerima hadiah stacking. Sebaliknya, mereka harus: - -- Komit untuk berpartisipasi sebelum siklus hadiah dimulai -- Komit mengenai jumlah minimum token STX untuk mengamankan slot hadiah, atau menggabungkan dengan orang lain untuk mencapai jumlah minimum -- Mengunci token STX untuk periode tertentu -- Memberikan alamat Bitcoin yang didukung untuk menerima hadiah (native segwit tidak didukung) - -Diagram berikut menjelaskan cara token STX minimal per slot ditentukan. Informasi lebih lanjut tentang [minimal dinamis untuk stacking](https://stacking.club) tersedia di stacking.club. - -![Minimal dinamis untuk kelayakan individu](/img/stacking-dynamic-minimum.png) - -Pemegang token memiliki berbagai penyedia dan alat untuk mendukung partisipasi mereka dalam Stacking. Situs web Stacks berisi [daftar penyedia dan gabungan stacking](https://stacks.org/stacking#earn). - -## Stacking dalam algoritma konsensus PoX - -Stacking adalah kemampuan bawaan PoX dan terjadi melalui serangkaian tindakan pada blockchain Stacks. [Detail implementasi proof-of-transfer lengkap](https://github.com/stacks-network/stacks-blockchain/blob/develop/sip/sip-007-stacking-consensus.md) ada di SIP-007. Di bawah ini adalah ringkasan tindakan yang paling relevan dari algoritma. - -![Siklus PoX](/img/pox-cycles.png) - -- Stacking terjadi selama siklus hadiah dengan waktu yang tetap. Dalam setiap siklus hadiah, satu kumpulan alamat Bitcoin yang terkait dengan peserta stacking akan menerima hadiah BTC -- Siklus penghargaan terdiri dari dua fase: persiapan dan penghargaan -- Selama fase persiapan, penambang memutuskan blok terkait dan mengumpulkan hadiah. Menambang cabang turunan dari blok terkait memerlukan transfer dana penambangan ke alamat hadiah yang sesuai. Kumpulan hadiah adalah kumpulan alamat Bitcoin yang memenuhi syarat untuk menerima dana dalam siklus hadiah -- Penambang mendaftar sebagai kandidat pemimpin untuk pemilihan di masa depan dengan mengirimkan transaksi kunci yang dapat membakar mata uang kripto. Transaksi juga mendaftarkan ujung rantai pilihan pemimpin (harus merupakan turunan dari blok terkait) dan komitmen dana ke 2 alamat dari kumpulan hadiah -- Pemegang Token mendaftar untuk siklus hadiah berikutnya dengan menyiarkan pesan yang ditandatangani yang mengunci token STX terkait untuk periode penguncian yang ditentukan protokol, menentukan alamat Bitcoin untuk menerima dana, dan memberikan suara pada ujung rantai Stacks -- Beberapa pemimpin dapat berkomitmen pada ujung rantai yang sama. Pemimpin yang memenangkan pemilihan dan rekan-rekan yang juga mendukung pemimpin itu secara kolektif berbagi hadiah, sebanding dengan berapa banyak yang dibakar oleh masing-masing -- Token yang dikunci pemegang Token secara otomatis akan terbuka setelah periode penguncian selesai - -## Alamat bitcoin - -:::danger You must provide a BTC address in one of two formats: - -* [Legacy (P2PKH)](https://en.bitcoin.it/wiki/Transaction#Pay-to-PubkeyHash), which starts with `1`. - -* [Segregated Witness / Segwit (P2SH)](https://en.bitcoin.it/wiki/Pay_to_script_hash), which starts with `3`. The "Native Segwit" format (which starts with `bc1`), for example, is not supported. ::: - -Kontrak Stacking memerlukan format khusus untuk alamat Bitcoin (alamat hadiah). Ini diperlukan untuk memastikan bahwa penambang dapat dengan benar membuat transaksi Bitcoin yang berisi alamat hadiah. - -Alamat harus ditentukan dalam format berikut menggunakan bahasa Clarity: - -```clar -;; a tuple of a version and hashbytes buffer -(pox-addr (tuple (version (buff 1)) (hashbytes (buff 20)))) -``` - -`versi` buffer harus mewakili jenis alamat bitcoin yang sedang dikirimkan. Ini dapat berupa: - -```js -SerializeP2PKH = 0x00, // hash160(public-key), same as bitcoin's p2pkh -SerializeP2SH = 0x01, // hash160(multisig-redeem-script), same as bitcoin's multisig p2sh -SerializeP2WPKH = 0x02, // hash160(segwit-program-00(p2pkh)), same as bitcoin's p2sh-p2wpkh -SerializeP2WSH = 0x03, // hash160(segwit-program-00(public-keys)), same as bitcoin's p2sh-p2wsh -``` - -`Hashbytes` adalah 20 byte hash dari alamat bitcoin. Anda bisa mendapatkannya dari pustaka bitcoin, misalnya menggunakan [`bitcoinjs-lib`](https://github.com/bitcoinjs/bitcoinjs-lib): - -```js -const btc = require('bitcoinjs-lib'); -console.log( - '0x' + btc.address.fromBase58Check('1C56LYirKa3PFXFsvhSESgDy2acEHVAEt6').hash.toString('hex') -); -``` - -## Choosing the right Stacking strategy - -[Here](https://blog.stacks.co/stacking-strategy) is an interesting article that may help you choose the right Stacking stategy. - - -## Where to Stacks? - -You can Stack on your own, on a pool or on an exchange: -### Stacking on your own - -Stacking on your own is non-custodial. - -Stacking on your own requires a protocol minimum (amount changes but about 100,000 STX). - -[Hiro Wallet](https://www.hiro.so/wallet) allows stacking on your own. - -### Stacking on a pool - -Stacking on a pool allows Stacking without the requirement of the protocol minumum. - -Some available pools are: - -| Pool | Jenis | Pays rewards in | Fee | Minimum amount | -| --------------------------------------------------- | ------------- |:---------------:| --- |:--------------:| -| [Friedger's Pool](https://pool.friedger.de/) | Non custodial | STX or xBTC | No | 40 STX | -| [Planbetter](https://planbetter.org/) | Non custodial | BTC | 5% | 200 STX | -| [Stacked](https://staking.staked.us/stacks-staking) | Non custodial | BTC | | 100,000 STX | -| [Xverse](https://www.xverse.app/) | Non custodial | BTC | No | 100 STX | - -### Stacking on an exchange - -Stacking on an exchange is custodial, meaning you are trusting the exchange with your Stacks. - -Several exchanges allow Stacking directly on their sites. Examples are [Okcoin](https://www.okcoin.com) and [Binance](https://www.binance.com/en/staking) - -## Stacking statistics - -You can view all sorts of Stacking data and statistics on [Stacking Club](https://stacking.club) \ No newline at end of file diff --git a/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md b/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md deleted file mode 100644 index 8902e42735..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: API Blockchain Stacks -description: Berinteraksi dengan Blockchain Stacks 2.0 melalui API ---- - -## Temporal page because of a Crowdin bug \ No newline at end of file diff --git a/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md b/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md deleted file mode 100644 index dc6df07730..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Spesifikasi Teknis -description: Ringkasan spesifikasi teknis Stacks 2.0 -sidebar_position: 10 ---- - -## Konsensus - -- Proof of Transfer (PoX) seperti yang dijelaskan dalam [SIP-007](https://github.com/stacksgov/sips/blob/main/sips/sip-007/sip-007-stacking-consensus.md) -- Jaringan akan bertransisi ke Proof of Burn (PoB) seperti yang dijelaskan dalam [SIP-001](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md) setelah 10 tahun. [Pelajari lebih lanjut tentang Proof-of-Burn di SIP-001](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md). -- Model ancaman - - 51% dari kekuatan penambangan Stacks yang berbahaya dapat melakukan serangan pengeluaran ganda - - 51% dari kekuatan penambangan Bitcoin yang berbahaya dapat mengatur ulang rantai Stacks -- Aktor yang berbeda dan peran mereka - - Penambang Stacks mengemas transaksi ke dalam blok, menambangnya melalui transaksi Bitcoin, menyebarkannya, dan jika mereka memenangkan perlombaan blok, mereka akan menambahkan mikroblok ke blok pemenang mereka hingga blok berikutnya ditambang. Blok berikutnya mengkonfirmasi aliran mikroblok. - - Pemegang Stacks dapat mengubah perhitungan batas blok (yang tunduk pada veto penambang) dan dapat memilih untuk menonaktifkan hadiah Proof-of-Transfer untuk siklus hadiah. -- Transaksi dianggap final ketika transaksi "blok komit" yang sesuai pada Bitcoin diselesaikan. Biasanya sampai dengan 3-6 konfirmasi. -- For more details, see [Proof of Transfer](proof-of-transfer). - -## Menambang Proof of Transfer - -- Jadwal hadiah Coinbase: - - 1000 STX/blok untuk 4 tahun pertama - - 500 STX/blok untuk 4 tahun berikutnya - - 250 STX/blok untuk 4 tahun berikutnya - - 125 STX/blok setelahnya -- Hadiah Coinbase terakumulasi untuk "penyortiran yang tidak terjawab": Jika blok Bitcoin tidak memiliki penyortiran (pada ketinggian N), maka blok Stacks apa pun yang ditambang dalam penyortiran berikutnya yang dibangun dari ujung rantai Stacks yang ada pada penyortiran kedua dari belakang (pada ketinggian N- 1) dapat mengklaim codebasenya. Ini mendorong penambang untuk tetap menambang meskipun biaya Bitcoin tinggi. -- Bonus penambangan awal: Ini adalah kasus khusus di atas untuk memberi insentif kepada penambang awal. Coinbase untuk semua blok burnchain antara ketinggian blok pembakaran pertama (akan dipilih oleh penambang independen sebagai bagian dari peluncuran Stacks 2.0) dan pemenang penyortiran pertama terakumulasi dan didistribusikan ke penambang melalui jendela (akan ditentukan). Misalnya, katakanlah tinggi blok bakar adalah 10.000 dan penyortiran pertama berada di blok 10500 dan jendela distribusi adalah 100 blok, maka coinbase untuk 500 blok pertama (10.500 - 10.000) akan didistribusikan secara merata kepada penambang yang memenangkan penyortiran pada 100 blok berikutnya. -- Hadiah maturitas jendela: 100 blok, yang berarti para pemimpin akan mendapatkan hadiah coinbase 100 blok setelah mereka berhasil menambang. -- Interval blok: Blockchain Stacks menghasilkan blok dengan kecepatan yang sama dengan burnchain yang mendasarinya. Untuk Bitcoin, kira-kira setiap 10 menit. -- Komitmen BTC: Penambang harus melakukan setidaknya 11.000 satoshi (5.500 sats / [keluaran UTXO](https://learnmeabitcoin.com/technical/utxo)); 2 keluaran / blok) untuk menghindari "dust." -- For more details, see [Mining](mining). - -## Stacking - -- Stacking terdiri dari 2 fase - 1. Fase persiapan: Dalam fase ini, "blok terkait" dipilih. Kumpulan alamat yang memenuhi syarat ("kumpulan hadiah") ditentukan berdasarkan snapshot dari rantai di blok terkait. Panjang fase persiapan adalah 100 blok. Komitmen stacking perlu dikonfirmasi sebelum fase ini dimulai - 2. Fase hadiah: Dalam fase ini, komitmen BTC penambang didistribusikan di antara kumpulan hadiah. Panjang siklus hadiah adalah 2000 blok BTC (~2 minggu). -- Dua alamat / blok hadiah, dengan total 4000 alamat setiap siklus hadiah. Alamat dipilih menggunakan VRF (fungsi acak terverifikasi), sehingga setiap noda dapat secara deterministik tiba di alamat hadiah yang sama untuk blok yang diberikan. -- Ambang stacking: 0,025% dari jumlah partisipasi STX ketika partisipasi antara 25% dan 100% dan ketika partisipasi di bawah 25%, tingkat ambang selalu 0,00625 dari pasokan likuiditas STX. -- Delegasi: Alamat STX dapat menunjuk alamat lain untuk berpartisipasi dalam Stacking atas namanya. [Bagian yang relevan dalam SIP-007](https://github.com/stacksgov/sips/blob/main/sips/sip-007/sip-007-stacking-consensus.md#stacker-delegation). -- Gabungan: Pemegang STX yang secara individu tidak memenuhi ambang Stacking dapat menggabungkan kepemilikan mereka untuk berpartisipasi dalam Stacking. Untuk melakukan ini, pemegang STX harus mengatur alamat hadiah (opsional) ke "alamat delegasi." Untuk lebih jelasnya, lihat [referensi ini](https://docs.stacks.co/references/stacking-contract#delegate-stx). -- Hanya dua jenis alamat hadiah BTC yang didukung: [Legacy (P2PKH)](https://en.bitcoin.it/wiki/Transaction#Pay-to-PubkeyHash) atau [Segregated Witness / Segwit (P2SH)](https://en.bitcoin.it/wiki/Pay_to_script_hash). Native Segwit tidak didukung. -- Further reading: [Stacking](stacking) - -## Akun dan Alamat - -- Transaksi di blockchain Stacks berasal dari, dibayar oleh, dan dijalankan di bawah otoritas akun -- Sebuah akun sepenuhnya ditentukan oleh alamat + nonce + asetnya -- Alamat berisi 2 atau 3 bidang: versi 1 byte, hash kunci publik 20 byte (RIPEMD160(SHA256(input))), nama opsional (panjang variabel, maks 128 byte) -- Dua jenis akun: akun standar dimiliki oleh satu atau lebih kunci privat; akun kontrak terwujud ketika kontrak pintar dipakai (ditentukan oleh bidang nama opsional di atas) -- Nonce berfungsi menghitung berapa kali akun telah mengotorisasi transaksi. Dimulai dari 0, otorisasi yang valid harus menyertakan nilai nonce _berikutnya_. -- Aset adalah peta semua jenis aset -- STX, semua aset dalam-rantai yang ditentukan oleh kontrak Clarity (misalnya NFT) -- ke dalam jumlah yang dimiliki oleh akun tersebut. -- Akun tidak perlu "dibuat" atau didaftarkan secara eksplisit; semua akun secara implisit ada dan dipakai pada penggunaan pertama. -- Further reading: [Accounts](accounts) - -## Transaksi - -- Jenis transaksi: coinbase, transfer-token, penyebaran kontrak, panggilan kontrak, mikroblok poison. -- Hanya akun standar (bukan kontrak) yang dapat membayar biaya transaksi. -- Eksekusi transaksi diatur oleh 3 akun (mungkin berbeda atau tidak) - 1. _akun asal_ adalah akun yang membuat, _mengotorisasi_ dan mengirimkan transaksi - 2. _akun pembayaran_ adalah akun yang ditagih oleh pimpinan atas biaya validasi dan pelaksanaan transaksi - 3. _akun pengirim_ adalah akun yang mengidentifikasi siapa yang sedang menjalankan transaksi: ini dapat berubah saat transaksi dijalankan melalui fungsi Clarity `sebagai kontrak` -- Transaksi dapat di-batch atau dialirkan ke dalam blok. Perilaku dapat dikendalikan oleh mode terkait transaksi. With streaming ([microblocks](microblocks)), a faster confirmation time is possible. -- Dua jenis otorisasi: otorisasi standar adalah di mana akun asal sama dengan akun pembayaran. Otorisasi _Bersponsor_ adalah perbedaan antara akun asal dan akun pembayaran. Misalnya, pengembang atau penyedia layanan dapat membayar pengguna untuk memanggil kontrak pintar mereka. -- Untuk otorisasi bersponsor, pertama-tama pengguna menandatangani dengan akun asal dan kemudian sponsor menandatangani dengan akun pembayaran. -- Batas Mempool untuk transaksi tertunda bersamaan adalah 25 per akun -- Transaksi mempool yang tertunda akan dikumpulkan setelah [256 blok diterima](https://github.com/stacks-network/stacks-blockchain/blob/master/src/core/mempool.rs#L62). Dengan waktu blok target 10 menit, ini sama dengan ~42 jam -- [Pelajari lebih lanjut tentang pengkodean transaksi di SIP-005](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md#transaction-encoding) -- [Penandatanganan dan verifikasi transaksi dijelaskan dalam SIP-005](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md#transaction-signing-and-verifying) -- Semua transaksi yang mempengaruhi saldo akun bersifat atomik, operasi transfer tidak dapat menambah saldo satu akun tanpa mengurangi yang lain. Namun, transaksi yang melakukan beberapa tindakan akun (misalnya, mentransfer dari beberapa akun) mungkin sebagian akan selesai. -- Transaksi dapat menyertakan string memo (maks 34 byte) - -## Lihat juga - -- [Baca Stacks 2.0 lengkap: Aplikasi dan Kontrak Pintar untuk whitepaper Bitcoin](https://cloudflare-ipfs.com/ipfs/QmaGgiVHymeDjAc3aF1AwyhiFFwN97pme5m536cHT4FsAW). - -- [Tonton video Aaron Blankstein di Stacks whitepaper v2](https://www.youtube.com/watch?v=Wd-Bfe8Sn-Y). \ No newline at end of file diff --git a/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md b/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md deleted file mode 100644 index f130802d8b..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Testnet -description: Uji kontrak dan aplikasi pintar Anda -sidebar_position: 2 ---- - -## Tentang testnet - -The testnet is a separate blockchain from the Stacks mainnet analogous to a staging environment. Testnet adalah jaringan yang digunakan oleh pengembang untuk menguji aplikasi, kontrak pintar, atau perubahan protokol mereka dalam lingkungan seperti produksi. Testnet menghasilkan blok dengan kecepatan yang kira-kira sama dengan mainnet; sekitar 1 blok setiap 10 menit rata-rata. Testnet Stacks jarang diatur ulang. - -### Faucet - -Faucet testnet memberi Anda Token Stacks (STX) gratis untuk diuji. Token tersebut tidak sama dengan STX di mainnet dan tidak memiliki nilai. Anda bisa mendapatkan STX dari faucet di [Stacks Explorer Sandbox](https://explorer.stacks.co/sandbox/faucet?chain=testnet), atau menggunakan [API](https://docs.hiro.so/api#tag/Faucets). - -To get STX tokens from within the Explorer Sandbox, navigate to the "Faucet" tab on the left and click "Request STX" button. - -![](/img/stx_faucet.png) - -You can also try out [Stacking](stacking) by clicking on `I want to stack`. - -:::note -The Explorer Sandbox requires you to login with a Stacks wallet -::: - -### API testnet - -The hosted Stacks Blockchain API for the testnet is available at this base URL: - -```shell -https://stacks-node-api.testnet.stacks.co/ -``` - -![](/img/api_testnet_status.png) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md b/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md deleted file mode 100644 index 8e256f1182..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Transaksi -description: Panduan untuk transaksi Stacks 2.0 -sidebar_position: 6 ---- - -## Pengantar - -Transaksi adalah unit dasar eksekusi di blockchain Stacks. Each transaction is originated from a [Stacks 2.0 account](accounts), and is retained in the Stacks blockchain history for eternity. Panduan ini akan membantu Anda memahami transaksi Stacks 2.0. - -## Siklus hidup - -Transaksi melewati fase sebelum akhirnya dikonfirmasi, dan tersedia untuk semua, di jaringan Stacks 2.0. - -![Siklus hidup transaksi](/img/tx-lifecycle.png) - -- **Membuat**: Transaksi dibuat sesuai dengan spesifikasi pengkodean. -- **Validasi dan tanda tangan**: Transaksi divalidasi untuk memastikan transaksi dilakukan dengan baik. Tanda tangan diperlukan untuk diisi. -- **Broadcast**: Transaksi dikirim ke noda. -- **Daftar**: Seorang penambang menerima transaksi, memverifikasi, dan menambahkannya ke ["mempool"](https://academy.binance.com/en/glossary/mempool), area penyimpanan untuk semua transaksi yang tertunda. -- **Proses**: Penambang meninjau mempool dan memilih transaksi untuk blok berikutnya yang akan ditambang. Tergantung pada jenis transaksi, tindakan yang berbeda dapat terjadi dalam langkah ini. Misalnya, pasca kondisi dapat diverifikasi untuk transfer token, token yang ditentukan kontrak cerdas dapat dicetak, atau upaya untuk memanggil metode kontrak cerdas yang ada dapat dilakukan. -- **Konfirmasi**: Penambang berhasil menambang blok dengan serangkaian transaksi. Transaksi di dalam berhasil disebarkan ke jaringan. - -:::note A transaction can have one of three states once it is registered: `pending`, `success`, or `failed`. ::: - -## Tipe - -Stacks 2.0 mendukung serangkaian jenis transaksi yang berbeda: - -| **Jenis** | **Nilai** | **Deskripsi** | -| ------------------ | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Coinbase | `coinbase` | Transaksi pertama di blok baru (entitas yang memegang beberapa transaksi). Digunakan untuk mendaftar hadiah blok. Ini tidak dibuat dan disiarkan secara manual seperti jenis transaksi lainnya. | -| Transfer token | `token_transfer` | Transfer aset dari pengirim ke penerima | -| Penyebaran kontrak | `smart_contract` | Instansiasi kontrak | -| Panggilan kontrak | `contract_call` | Panggilan kontrak untuk fungsi publik, non read-only | -| Mikroblok Poison | `poison_microblock` | Menghukum para pemimpin yang dengan sengaja mengelak tentang mikroblok yang telah mereka kemas | - -Contoh setiap jenis transaksi dapat ditemukan di [Definisi respon Stacks Blockchain API untuk transaksi](https://docs.hiro.so/api#operation/get_transaction_by_id). - -:::caution Read-only contract call calls do **not** require transactions. Read more about it in the [network guide](network#read-only-function-calls). ::: diff --git a/i18n/id/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md b/i18n/id/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md deleted file mode 100644 index d173b16f5b..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Clarity Language -description: Ringkasan dari konstruksi bahasa Clarity -sidebar_label: Clarity Language -tags: - - clarity ---- - -## Sistem Tipe Clarity - -Bahasa Clarity menggunakan sistem tipe statis yang kuat. Argumen fungsi dan skema database memerlukan tipe tertentu, dan penggunaan tipe diperiksa selama peluncuran kontrak. Sistem tipe _tidak_ memiliki tipe universal super. - -## Fungsi publik - -Fungsi yang ditentukan melalui pernyataan `define-public` adalah fungsi _publik_ dan ini adalah satu-satunya jenis fungsi yang dapat dipanggil secara langsung melalui transaksi blockchain yang ditandatangani. Selain dapat dipanggil langsung dari suatu transaksi (lihat format wire Stacks untuk detail lebih lanjut tentang transaksi Stacks), fungsi publik dapat dipanggil oleh kontrak pintar lainnya. - -Fungsi publik _harus_ mengembalikan tipe `(respons ...)`. Ini digunakan oleh Clarity untuk menentukan apakah perubahan dari menjalankan fungsi akan terwujud atau tidak. Jika suatu fungsi mengembalikan tipe `(err ...)`, setiap mutasi pada status blockchain dari menjalankan fungsi (dan fungsi apa pun yang dipanggil selama eksekusi) akan dibatalkan. - -Selain fungsi yang ditentukan melalui `define-public`, kontrak dapat mengekspos fungsi read-only. Fungsi-fungsi ini, yang ditentukan melalui `define-read-only`, dapat dipanggil oleh kontrak pintar lainnya, dan dapat diquerikan melalui penjelajah blockchain publik. Fungsi-fungsi ini _tidak boleh_ mengubah status blockchain apa pun. Tidak seperti fungsi publik normal, fungsi read-only dapat mengembalikan jenis apa pun. - -## Panggilan kontrak - -Kontrak pintar dapat memanggil fungsi dari kontrak pintar lainnya menggunakan fungsi `(contract-call?)`. - -Fungsi ini mengembalikan hasil tipe respons -- nilai pengembalian dari fungsi kontrak pintar yang disebut. - -Kami membedakan 2 jenis `contract-call?` yang berbeda, yaitu: - -### Pengiriman statis - -Yang dipanggil adalah kontrak invarian yang diketahui tersedia dalam-rantai saat kontrak pemanggil diterapkan. Dalam hal ini, prinsipal yang dipanggil disediakan sebagai argumen pertama, diikuti dengan nama metode dan argumennya: - -```clarity -(contract-call? - .registrar - register-name - name-to-register) -``` - -### Pengiriman dinamis - -Yang dipanggil diteruskan sebagai argumen, dan diketik sebagai referensi sifat (``). - -```clarity -(define-public (swap (token-a ) - (amount-a uint) - (owner-a principal) - (token-b ) - (amount-b uint) - (owner-b principal))) - (begin - (unwrap! (contract-call? token-a transfer-from? owner-a owner-b amount-a)) - (unwrap! (contract-call? token-b transfer-from? owner-b owner-a amount-b)))) -``` - -Sifat dapat didefinisikan secara lokal: - -```clarity -(define-trait can-transfer-tokens ( - (transfer-from? (principal principal uint) (response uint))) -``` - -Atau diimpor dari kontrak yang ada: - -```clarity -(use-trait can-transfer-tokens - .contract-defining-trait.can-transfer-tokens) -``` - -Melihat kesesuaian sifat, kontrak yang dipanggil memiliki dua jalur yang berbeda. Mereka "kompatibel" oleh suatu sifat dengan mendefinisikan metode yang cocok melalui beberapa metode yang didefinisikan dalam suatu sifat, atau secara eksplisit menyatakan kesesuaian menggunakan pernyataan `impl-trait`: - -```clarity -(impl-trait .contract-defining-trait.can-transfer-tokens) -``` - -Kesesuaian eksplisit harus lebih dipilih apabila memadai. Bertindak sebagai perlindungan dengan membantu sistem analisis statis untuk mendeteksi penyimpangan dalam tanda tangan metode sebelum penerapan kontrak. - -Batasan berikut dikenakan pada panggilan kontrak: - -1. Pada pengiriman statis, kontrak pintar yang dipanggil harus ada pada saat pembuatan. -2. Tidak ada siklus yang mungkin ada dalam grafik panggilan kontrak pintar. Mencegah rekursi (dan bug masuk kembali). Struktur tersebut dapat dideteksi dengan analisis statis dari grafik panggilan, dan akan ditolak oleh jaringan. -3. `contract-call?` hanya untuk panggilan antar kontrak. Upaya untuk menjalankan ketika pemanggil juga yang dipanggil akan membatalkan transaksi. diff --git a/i18n/id/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md b/i18n/id/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md deleted file mode 100644 index 6528bfaac9..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md +++ /dev/null @@ -1,1385 +0,0 @@ ---- -title: Fungsi -description: Lihat daftar rinci semua fungsi untuk bahasa Clarity. -tags: - - clarity ---- - -## Fungsi - -Detailed list of all functions for the Clarity language. - -### + (add) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(+ i1 i2...)` -#### description: -Adds a variable number of integer inputs and returns the result. In the event of an _overflow_, throws a runtime error. -#### example: -```clarity -(+ 1 2 3) ;; Returns 6 -(+ 2 3) ;; Returns 5 -(+ 1 2 3 4) ;; Returns 10 -(+ 9 -3) ;; Returns 6 -(+ -3 -2) ;; Returns -5 -``` - -### - (subtract) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(- i1 i2...)` -#### description: -Subtracts a variable number of integer inputs and returns the result. In the event of an _underflow_, throws a runtime error. -#### example: -```clarity -(- 2 1 1) ;; Returns 0 -(- 0 3) ;; Returns -3 -(- 5 -3) ;; Returns 8 -(- -4 -5) ;; Returns 1 -``` - -### * (multiply) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(* i1 i2...)` -#### description: -Multiplies a variable number of integer inputs and returns the result. In the event of an _overflow_, throws a runtime error. -#### example: -```clarity -(* 2 3) ;; Returns 6 -(* 5 2) ;; Returns 10 -(* 2 2 2) ;; Returns 8 -(* 3 -2) ;; Returns -6 -(* -1 -2) ;; Returns 2 -``` - -### / (divide) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(/ i1 i2...)` -#### description: -Divides a variable number of integer inputs and returns the _integer part_ of the result. In the event of _division by zero_, throws a runtime error. - -#### example: -```clarity -(/ 2 3) ;; Returns 0 -(/ 5 2) ;; Returns 2 -(/ 4 2 2) ;; Returns 1 -(/ -10 2) ;; Returns -5 -(/ -8 -2) ;; Returns 4 -(/ -9 4) ;; Returns -2 -``` - -### >= (greater than or equal) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(>= i1 i2)` -#### deskripsi: -Compares two integers, returning `true` if `i1` is greater than or equal to `i2` and `false` otherwise. -#### contoh: -```clarity -(>= 1 1) ;; Returns true -(>= 5 2) ;; Returns true -``` - -### <= (less than or equal) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(<= i1 i2)` -#### deskripsi: -Compares two integers, returning true if `i1` is less than or equal to `i2` and `false` otherwise. -#### contoh: -```clarity -(<= 1 1) ;; Returns true -(<= 5 2) ;; Returns false -``` - -### < (less than) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(< i1 i2)` -#### deskripsi: -Compares two integers, returning `true` if `i1` is less than `i2` and `false` otherwise. -#### contoh: -```clarity -(< 1 2) ;; Returns true -(< 5 2) ;; Returns false -``` - -### > (greater than) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(> i1 i2)` -#### deskripsi: -Compares two integers, returning `true` if `i1` is greater than `i2` and false otherwise. -#### contoh: -```clarity -(> 1 2) ;; Returns false -(> 5 2) ;; Returns true -``` - -### to-int -#### input: `uint` -#### output: `int` -#### signature: `(to-int u)` -#### deskripsi: -Tries to convert the `uint` argument to an `int`. Will cause a runtime error and abort if the supplied argument is >= `pow(2, 127)`` -#### contoh: -```clarity -(to-int u238) ;; Returns 238 -``` - -### to-uint -#### input: `int` -#### output: `uint` -#### signature: `(to-uint i)` -#### deskripsi: -Tries to convert the `int` argument to a `uint`. Will cause a runtime error and abort if the supplied argument is negative. -#### contoh: -```clarity -(to-uint 238) ;; Returns u238 -``` - -### mod -#### input: `int, int | uint, uint` -#### output: `int | uint` -#### signature: `(mod i1 i2)` -#### description: -Returns the integer remainder from integer dividing `i1` by `i2`. In the event of a division by zero, throws a runtime error. -#### example: -```clarity -(mod 2 3) ;; Returns 2 -(mod 5 2) ;; Returns 1 -(mod 7 1) ;; Returns 0 -``` - -### pow -#### input: `int, int | uint, uint` -#### output: `int | uint` -#### signature: `(pow i1 i2)` -#### description: -Returns the result of raising `i1` to the power of `i2`. In the event of an _overflow_, throws a runtime error. -#### example: -```clarity -(pow 2 3) ;; Returns 8 -(pow 2 2) ;; Returns 4 -(pow 7 1) ;; Returns 7 -``` - -### sqrti -#### input: `int | uint` -#### output: `int | uint` -#### signature: `(sqrti n)` -#### description: -Returns the largest integer that is less than or equal to the square root of `n`. Fails on a negative numbers. -#### example: -```clarity -(sqrti u11) ;; Returns u3 -(sqrti 1000000) ;; Returns 1000 -(sqrti u1) ;; Returns u1 -(sqrti 0) ;; Returns 0 -``` - -### log2 -#### input: `int | uint` -#### output: `int | uint` -#### signature: `(log2 n)` -#### description: -Returns the _integer part_ of the power to which the number 2 must be raised to obtain the value `n`. Fails on zero or a negative number. -#### example: -```clarity -(log2 u8) ;; Returns u3 -(log2 8) ;; Returns 3 -(log2 u1) ;; Returns u0 -(log2 1000) ;; Returns 9 -``` - -### xor -#### input: `int, int | uint, uint` -#### output: `int | uint` -#### signature: `(xor i1 i2)` -#### description: -Returns the result of bitwise exclusive or'ing `i1` with `i2`. -#### example: -```clarity -(xor 1 2) ;; Returns 3 -(xor 120 280) ;; Returns 352 -``` - -### and -#### input: `bool, ...` -#### output: `bool` -#### signature: `(and b1 b2 ...)` -#### description: -Returns `true` if all boolean inputs are `true`. Importantly, the supplied arguments are evaluated in-order and lazily. Lazy evaluation means that if one of the arguments returns `false`, the function short-circuits, and no subsequent arguments are evaluated. -#### example: -```clarity -(and true false) ;; Returns false -(and (is-eq (+ 1 2) 1) (is-eq 4 4)) ;; Returns false -(and (is-eq (+ 1 2) 3) (is-eq 4 4)) ;; Returns true -``` - -### or -#### input: `bool, ...` -#### output: `bool` -#### signature: `(or b1 b2 ...)` -#### description: -Returns `true` if any boolean inputs are `true`. Importantly, the supplied arguments are evaluated in-order and lazily. Lazy evaluation means that if one of the arguments returns `true`, the function short-circuits, and no subsequent arguments are evaluated. -#### example: -```clarity -(or true false) ;; Returns true -(or (is-eq (+ 1 2) 1) (is-eq 4 4)) ;; Returns true -(or (is-eq (+ 1 2) 1) (is-eq 3 4)) ;; Returns false -(or (is-eq (+ 1 2) 3) (is-eq 4 4)) ;; Returns true -``` - -### not -#### input: `bool` -#### output: `bool` -#### signature: `(not b1)` -#### description: -Returns the inverse of the boolean input. -#### example: -```clarity -(not true) ;; Returns false -(not (is-eq 1 2)) ;; Returns true -``` - -### is-eq -#### input: `A, A, ...` -#### output: `bool` -#### signature: `(is-eq v1 v2...)` -#### description: -Compares the inputted values, returning `true` if they are all equal. Note that _unlike_ the `(and ...)` function, `(is-eq ...)` will _not_ short-circuit. All values supplied to is-eq _must_ be the same type. -#### example: -```clarity -(is-eq 1 1) ;; Returns true -(is-eq true false) ;; Returns false -(is-eq \"abc\" 234 234) ;; Throws type error -``` - -### if -#### input: `bool, A, A` -#### output: `A` -#### signature: `(if bool1 expr1 expr2)` -#### description: -The `if` function admits a boolean argument and two expressions which must return the same type. In the case that the boolean input is `true`, the `if` function evaluates and returns `expr1`. If the boolean input is `false`, the `if` function evaluates and returns `expr2`. -#### example: -```clarity -(if true 1 2) ;; Returns 1 -(if (> 1 2) 1 2) ;; Returns 2 -``` - -### let -#### input: `((name1 AnyType) (name2 AnyType) ...), AnyType, ... A` -#### output: `A` -#### signature: `(let ((name1 expr1) (name2 expr2) ...) expr-body1 expr-body2 ... expr-body-last)` -#### description: -The `let` function accepts a list of `variable name` and `expression` pairs, evaluating each expression and _binding_ it to the corresponding variable name. `let` bindings are sequential: when a `let` binding is evaluated, it may refer to prior binding. The _context_ created by this set of bindings is used for evaluating its body expressions. The let expression returns the value of the last such body expression. Note: intermediary statements returning a response type must be checked` -#### example: -```clarity -(let ((a 2) (b (+ 5 6 7))) (print a) (print b) (+ a b)) ;; Returns 20 -(let ((a 5) (c (+ a 1)) (d (+ c 1)) (b (+ a c d))) (print a) (print b) (+ a b)) ;; Returns 23 -``` - -### map -#### input: `Function(A, B, ..., N) -> X, sequence_A, sequence_B, ..., sequence_N` -#### output: `(list X)` -#### signature: `(map func sequence_A sequence_B ... sequence_N)` -#### description: -The `map` function applies the function `func` to each corresponding element of the input sequences, and outputs a _list_ of the same type containing the outputs from those function applications. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. Also, note that, no matter what kind of sequences the inputs are, the output is always a list. -#### example: -```clarity -(map not (list true false true false)) ;; Returns (false true false true) -(map + (list 1 2 3) (list 1 2 3) (list 1 2 3)) ;; Returns (3 6 9) -(define-private (a-or-b (char (string-utf8 1))) (if (is-eq char u\"a\") u\"a\" u\"b\")) -(map a-or-b u\"aca\") ;; Returns (u\"a\" u\"b\" u\"a\") -(define-private (zero-or-one (char (buff 1))) (if (is-eq char 0x00) 0x00 0x01)) -(map zero-or-one 0x000102) ;; Returns (0x00 0x01 0x01) -``` - -### fold -#### input: `Function(A, B) -> B, sequence_A, B` -#### output: `B` -#### signature: `(fold func sequence_A initial_B)` -#### description: -The `fold` function condenses `sequence_A` into a value of type `B` by recursively applies the function `func` to each element of the input sequence _and_ the output of a previous application of `func`. - -`fold` uses `initial_B` in the initial application of `func`, along with the first element of `sequence_A`. The resulting value of type `B` is used for the next application of `func`, along with the next element of `sequence_A` and so on. `fold` returns the last value of type `B` returned by these successive applications `func`. - -Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. - -#### example: -```clarity -(fold * (list 2 2 2) 1) ;; Returns 8 -(fold * (list 2 2 2) 0) ;; Returns 0 -;; calculates (- 11 (- 7 (- 3 2))) -(fold - (list 3 7 11) 2) ;; Returns 5 -(define-private (concat-string (a (string-ascii 20)) (b (string-ascii 20))) (unwrap-panic (as-max-len? (concat a b) u20))) -(fold concat-string \"cdef\" \"ab\") ;; Returns \"fedcab\" -(fold concat-string (list \"cd\" \"ef\") \"ab\") ;; Returns \"efcdab\" -(define-private (concat-buff (a (buff 20)) (b (buff 20))) (unwrap-panic (as-max-len? (concat a b) u20))) -(fold concat-buff 0x03040506 0x0102) ;; Returns 0x060504030102 -``` - -### append -#### input: `list A, A` -#### output: `list` -#### signature: `(append (list 1 2 3 4) 5)` -#### description: -The `append` function takes a list and another value with the same entry type, and outputs a list of the same type with max_len += 1. -#### example: -```clarity -(append (list 1 2 3 4) 5) ;; Returns (1 2 3 4 5) -``` - -### concat -#### input: `sequence_A, sequence_A` -#### output: `sequence_A` -#### signature: `(concat sequence1 sequence2)` -#### description: -The `concat` function takes two sequences of the same type, and returns a concatenated sequence of the same type, with the resulting sequence_len = sequence1_len + sequence2_len. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`. - -#### example: -```clarity -(concat (list 1 2) (list 3 4)) ;; Returns (1 2 3 4) -(concat \"hello \" \"world\") ;; Returns \"hello world\" -(concat 0x0102 0x0304) ;; Returns 0x01020304 -``` - -### as-max-len? -#### input: `sequence_A, uint` -#### output: `sequence_A` -#### signature: `(as-max-len? sequence max_length)` -#### description: -The `as-max-len?` function takes a sequence argument and a uint-valued, literal length argument. The function returns an optional type. If the input sequence length is less than or equal to the supplied max_length, this returns `(some sequence)`, otherwise it returns `none`. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`. ` -#### example: -```clarity -(as-max-len? (list 2 2 2) u3) ;; Returns (some (2 2 2)) -(as-max-len? (list 1 2 3) u2) ;; Returns none -(as-max-len? \"hello\" u10) ;; Returns (some \"hello\") -(as-max-len? 0x010203 u10) ;; Returns (some 0x010203) -``` - -### len -#### input: `sequence_A` -#### output: `uint` -#### signature: `(len sequence)` -#### description: -The `len` function returns the length of a given sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`. ` -#### example: -```clarity -(len \"blockstack\") ;; Returns u10 -(len (list 1 2 3 4 5)) ;; Returns u5 -(len 0x010203) ;; Returns u3 -``` - -### element-at -#### input: `sequence_A, uint` -#### output: `(optional A)` -#### signature: `(element-at sequence index)` -#### description: -The `element-at` function returns the element at `index` in the provided sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. ` -#### example: -```clarity -(element-at \"blockstack\" u5) ;; Returns (some \"s\") -(element-at (list 1 2 3 4 5) u5) ;; Returns none -(element-at (list 1 2 3 4 5) (+ u1 u2)) ;; Returns (some 4) -(element-at \"abcd\" u1) ;; Returns (some \"b\") -(element-at 0xfb01 u1) ;; Returns (some 0x01) -``` - -### index-of -#### input: `sequence_A, A` -#### output: `(optional uint)` -#### signature: `(index-of sequence item)` -#### description: -The `index-of` function returns the first index at which `item` can be found, using `is-eq` checks, in the provided sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. If the target item is not found in the sequence (or if an empty string or buffer is supplied), this function returns `none`. -#### example: -```clarity -(index-of \"blockstack\" \"b\") ;; Returns (some u0) -(index-of \"blockstack\" \"k\") ;; Returns (some u4) -(index-of \"blockstack\" \"\") ;; Returns none -(index-of (list 1 2 3 4 5) 6) ;; Returns none -(index-of 0xfb01 0x01) ;; Returns (some u1) -``` - -### list -#### input: `A, ...` -#### output: `(list A)` -#### signature: `(list expr1 expr2 expr3 ...)` -#### description: -The `list` function constructs a list composed of the inputted values. Each supplied value must be of the same type. -#### example: -```clarity -(list (+ 1 2) 4 5) ;; Returns (3 4 5) -``` - -### var-get -#### input: `VarName` -#### output: `A` -#### signature: `(var-get var-name)` -#### description: -The `var-get` function looks up and returns an entry from a contract's data map. The value is looked up using `var-name`. -#### example: -```clarity -(define-data-var cursor int 6) -(var-get cursor) ;; Returns 6 -``` - -### var-set -#### input: `VarName, AnyType` -#### output: `bool` -#### signature: `(var-set var-name expr1)` -#### description: -The `var-set` function sets the value associated with the input variable to the inputted value. The function always returns `true`. -#### example: -```clarity -(define-data-var cursor int 6) -(var-get cursor) ;; Returns 6 -(var-set cursor (+ (var-get cursor) 1)) ;; Returns true -(var-get cursor) ;; Returns 7 -``` - -### map-get? -#### input: `MapName, tuple` -#### output: `(optional (tuple))` -#### signature: `(map-get? map-name key-tuple)` -#### description: -The `map-get?` function looks up and returns an entry from a contract's data map. The value is looked up using `key-tuple`. If there is no value associated with that key in the data map, the function returns a `none` option. Otherwise, it returns `(some value)`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(map-get? names-map (tuple (name \"blockstack\"))) ;; Returns (some (tuple (id 1337))) -(map-get? names-map { name: \"blockstack\" }) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-set -#### input: `MapName, tuple_A, tuple_B` -#### output: `bool` -#### signature: `(map-set map-name key-tuple value-tuple)` -#### description: -The `map-set` function sets the value associated with the input key to the inputted value. This function performs a _blind_ update; whether or not a value is already associated with the key, the function overwrites that existing association. - -Note: the `value-tuple` requires 1 additional byte for storage in the materialized blockchain state, and therefore the maximum size of a value that may be inserted into a map is MAX_CLARITY_VALUE - 1. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-set names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-insert -#### input: `MapName, tuple_A, tuple_B` -#### output: `bool` -#### signature: `(map-insert map-name key-tuple value-tuple)` -#### description: -The `map-insert` function sets the value associated with the input key to the inputted value if and only if there is not already a value associated with the key in the map. If an insert occurs, the function returns `true`. If a value already existed for this key in the data map, the function returns `false`. - -Note: the `value-tuple` requires 1 additional byte for storage in the materialized blockchain state, and therefore the maximum size of a value that may be inserted into a map is MAX_CLARITY_VALUE - 1. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns false -(map-insert names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-delete -#### input: `MapName, tuple` -#### output: `bool` -#### signature: `(map-delete map-name key-tuple)` -#### description: -The `map-delete` function removes the value associated with the input key for the given map. If an item exists and is removed, the function returns `true`. If a value did not exist for this key in the data map, the function returns `false`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-delete names-map { name: \"blockstack\" }) ;; Returns true -(map-delete names-map { name: \"blockstack\" }) ;; Returns false -(map-delete names-map (tuple (name \"blockstack\"))) ;; Same command, using a shorthand for constructing the tuple -``` - -### tuple -#### input: `(key-name A), (key-name-2 B), ...` -#### output: `(tuple (key-name A) (key-name-2 B) ...)` -#### signature: `(tuple (key0 expr0) (key1 expr1) ...)` -#### description: -The `tuple` special form constructs a typed tuple from the supplied key and expression pairs. A `get` function can use typed tuples as input to select specific values from a given tuple. Key names may not appear multiple times in the same tuple definition. Supplied expressions are evaluated and associated with the expressions' paired key name. - -There is a shorthand using curly brackets of the form {key0: expr0, key1: expr, ...}` -#### example: -```clarity -(tuple (name \"blockstack\") (id 1337)) ;; using tuple -{name: \"blockstack\", id: 1337} ;; using curly brackets -``` - -### get -#### input: `KeyName, (tuple) | (optional (tuple))` -#### output: `A` -#### signature: `(get key-name tuple)` -#### description: -The `get` function fetches the value associated with a given key from the supplied typed tuple. If an `Optional` value is supplied as the inputted tuple, `get` returns an `Optional` type of the specified key in the tuple. If the supplied option is a `(none)` option, get returns `(none)`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(get id (tuple (name \"blockstack\") (id 1337))) ;; Returns 1337 -(get id (map-get? names-map (tuple (name \"blockstack\")))) ;; Returns (some 1337) -(get id (map-get? names-map (tuple (name \"non-existent\")))) ;; Returns none -``` - -### merge -#### input: `tuple, tuple` -#### output: `tuple` -#### signature: `(merge tuple { key1: val1 })` -#### description: -The `merge` function returns a new tuple with the combined fields, without mutating the supplied tuples. -#### example: -```clarity -(define-map users { id: int } { name: (string-ascii 12), address: (optional principal) }) -(map-insert users { id: 1337 } { name: \"john\", address: none }) ;; Returns true -(let ((user (unwrap-panic (map-get? users { id: 1337 })))) -(merge user { address: (some 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) })) ;; Returns (tuple (address (some SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF)) (name \"john\")) -``` - -### begin -#### input: `AnyType, ... A` -#### output: `A` -#### signature: `(begin expr1 expr2 expr3 ... expr-last)` -#### description: -The `begin` function evaluates each of its input expressions, returning the return value of the last such expression. Note: intermediary statements returning a response type must be checked. -#### example: -```clarity -(begin (+ 1 2) 4 5) ;; Returns 5 -``` - -### hash160 -#### input: `buff|uint|int` -#### output: `(buff 20)` -#### signature: `(hash160 value)` -#### description: -The `hash160` function computes `RIPEMD160(SHA256(x))` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(hash160 0) ;; Returns 0xe4352f72356db555721651aa612e00379167b30f -``` - -### sha256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(sha256 value)` -#### description: -The `sha256` function computes `SHA256(x)` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(sha256 0) ;; Returns 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb -``` - -### sha512 -#### input: `buff|uint|int` -#### output: `(buff 64)` -#### signature: `(sha512 value)` -#### description: -The `sha512` function computes `SHA512(x)` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(sha512 1) ;; Returns 0x6fcee9a7b7a7b821d241c03c82377928bc6882e7a08c78a4221199bfa220cdc55212273018ee613317c8293bb8d1ce08d1e017508e94e06ab85a734c99c7cc34 -``` - -### sha512/256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(sha512/256 value)` -#### description: -The `sha512/256` function computes `SHA512/256(x)` (the SHA512 algorithm with the 512/256 initialization vector, truncated to 256 bits) of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(sha512/256 1) ;; Returns 0x515a7e92e7c60522db968d81ff70b80818fc17aeabbec36baf0dda2812e94a86 -``` - -### keccak256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(keccak256 value)` -#### description: -The `keccak256` function computes `KECCAK256(value)` of the inputted value. Note that this differs from the `NIST SHA-3` (that is, FIPS 202) standard. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(keccak256 0) ;; Returns 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4 -``` - -### secp256k1-recover? -#### input: `(buff 32), (buff 65)` -#### output: `(response (buff 33) uint)` -#### signature: `(secp256k1-recover? message-hash signature)` -#### description: -The `secp256k1-recover?` function recovers the public key used to sign the message which sha256 is `message-hash` with the provided `signature`. If the signature does not match, it will return the error code `(err u1).`. If the signature is invalid, it will return the error code `(err u2).`. The signature includes 64 bytes plus an additional recovery id (00..03) for a total of 65 bytes. -#### example: -```clarity -(secp256k1-recover? 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a1301) - ;; Returns (ok 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) - ``` - -### secp256k1-verify -#### input: `(buff 32), (buff 64) | (buff 65), (buff 33)` -#### output: `bool` -#### signature: `(secp256k1-verify message-hash signature public-key)` -#### description: -The `secp256k1-verify` function verifies that the provided signature of the message-hash was signed with the private key that generated the public key. The `message-hash` is the `sha256` of the message. The signature includes 64 bytes plus an optional additional recovery id (00..03) for a total of 64 or 65 bytes. -#### example: -```clarity -(secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a1301 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns true -(secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a13 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns true -(secp256k1-verify 0x0000000000000000000000000000000000000000000000000000000000000000 - 0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns false - ``` - -### print -#### input: `A` -#### output: `A` -#### signature: `(print expr)` -#### description: -The `print` function evaluates and returns its input expression. On Stacks Core nodes configured for development (as opposed to production mining nodes), this function prints the resulting value to `STDOUT` (standard output). -#### example: -```clarity -(print (+ 1 2 3)) ;; Returns 6 -``` - -### contract-call? -#### input: `ContractName, PublicFunctionName, Arg0, ...` -#### output: `(response A B)` -#### signature: `(contract-call? .contract-name function-name arg0 arg1 ...)` -#### description: -The `contract-call?` function executes the given public function of the given contract. You _may not_ use this function to call a public function defined in the current contract. If the public function returns _err_, any database changes resulting from calling `contract-call?` are aborted. If the function returns _ok_, database changes occurred. -#### example: -```clarity - -;; instantiate the sample-contracts/tokens.clar contract first! -(as-contract (contract-call? .tokens mint! u19)) ;; Returns (ok u19) -``` - -### as-contract -#### input: `A` -#### output: `A` -#### signature: `(as-contract expr)` -#### description: -The `as-contract` function switches the current context's `tx-sender` value to the _contract's_ principal and executes `expr` with that context. It returns the resulting value of `expr`. -#### example: -```clarity -(as-contract tx-sender) ;; Returns S1G2081040G2081040G2081040G208105NK8PE5.docs-test -``` - -### contract-of -#### input: `Trait` -#### output: `principal` -#### signature: `(contract-of .contract-name)` -#### description: -The `contract-of` function returns the principal of the contract implementing the trait. -#### example: -```clarity -(use-trait token-a-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) -(define-public (forward-get-balance (user principal) (contract )) - (begin - (ok (contract-of contract)))) ;; returns the principal of the contract implementing -``` - -### principal-of? -#### input: `(buff 33)` -#### output: `(response principal uint)` -#### signature: `(principal-of? public-key)` -#### description: -The `principal-of?` function returns the principal derived from the provided public key. If the `public-key` is invalid, it will return the error code `(err u1).`. ` -#### example: -```clarity -(principal-of? 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns (ok ST1AW6EKPGT61SQ9FNVDS17RKNWT8ZP582VF9HSCP) -``` - -### at-block -#### input: `(buff 32), A` -#### output: `A` -#### signature: `(at-block id-block-hash expr)` -#### description: -The `at-block` function evaluates the expression `expr` _as if_ it were evaluated at the end of the block indicated by the _block-hash_ argument. The `expr` closure must be read-only. - -Note: The block identifying hash must be a hash returned by the `id-header-hash` block information property. This hash uniquely identifies Stacks blocks and is unique across Stacks forks. While the hash returned by `header-hash` is unique within the context of a single fork, it is not unique across Stacks forks. - -The function returns the result of evaluating `expr`. - -#### example: -```clarity -(define-data-var data int 1) -(at-block 0x0000000000000000000000000000000000000000000000000000000000000000 block-height) ;; Returns u0 -(at-block (get-block-info? id-header-hash 0) (var-get data)) ;; Throws NoSuchDataVariable because `data` wasn't initialized at block height 0 -``` - -### get-block-info? -#### input: `BlockInfoPropertyName, BlockHeightInt` -#### output: `(optional buff) | (optional uint)` -#### signature: `(get-block-info? prop-name block-height-expr)` -#### description: -The `get-block-info?` function fetches data for a block of the given block height. The value and type returned are determined by the specified `BlockInfoPropertyName`. If the provided `BlockHeightInt` does not correspond to an existing block prior to the current block, the function returns `none`. The currently available property names are `time`, `header-hash`, `burnchain-header-hash`, `id-header-hash`, `miner-address`, and `vrf-seed`. - -The `time` property returns an integer value of the block header time field. This is a Unix epoch timestamp in seconds which roughly corresponds to when the block was mined. **Warning**: this does not increase monotonically with each block and block times are accurate only to within two hours. See [BIP113](https://github.com/bitcoin/bips/blob/master/bip-0113.mediawiki) for more information. - -The `header-hash`, `burnchain-header-hash`, `id-header-hash`, and `vrf-seed` properties return a 32-byte buffer. - -The `miner-address` property returns a `principal` corresponding to the miner of the given block. - -The `id-header-hash` is the block identifier value that must be used as input to the `at-block` function. - -#### example: -```clarity -(get-block-info? time u0) ;; Returns (some u1557860301) -(get-block-info? header-hash u0) ;; Returns (some 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb) -(get-block-info? vrf-seed u0) ;; Returns (some 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4) -``` - -### err -#### input: `A` -#### output: `(response A B)` -#### signature: `(err value)` -#### description: -The `err` function constructs a response type from the input value. Use `err` for creating return values in public functions. An _err_ value indicates that any database changes during the processing of the function should be rolled back. -#### example: -```clarity -(err true) ;; Returns (err true) -``` - -### ok -#### input: `A` -#### output: `(response A B)` -#### signature: `(ok value)` -#### description: -The `ok` function constructs a response type from the input value. Use `ok` for creating return values in public functions. An _ok_ value indicates that any database changes during the processing of the function should materialize. -#### example: -```clarity -(ok 1) ;; Returns (ok 1) -``` - -### some -#### input: `A` -#### output: `(optional A)` -#### signature: `(some value)` -#### description: -The `some` function constructs a `optional` type from the input value. -#### example: -```clarity -(some 1) ;; Returns (some 1) -(is-none (some 2)) ;; Returns false -``` - -### default-to -#### input: `A, (optional A)` -#### output: `A` -#### signature: `(default-to default-value option-value)` -#### description: -The `default-to` function attempts to 'unpack' the second argument: if the argument is a `(some ...)` option, it returns the inner value of the option. If the second argument is a `(none)` value, `default-to` it returns the value of `default-value`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(default-to 0 (get id (map-get? names-map (tuple (name \"blockstack\"))))) ;; Returns 1337 -(default-to 0 (get id (map-get? names-map (tuple (name \"non-existant\"))))) ;; Returns 0 -``` - -### asserts! -#### input: `bool, C` -#### output: `bool` -#### signature: `(asserts! bool-expr thrown-value)` -#### description: -The `asserts!` function admits a boolean argument and asserts its evaluation: if bool-expr is `true`, `asserts!` returns `true` and proceeds in the program execution. If the supplied argument is returning a false value, `asserts!` _returns_ `thrown-value` and exits the current control-flow. -#### example: -```clarity -(asserts! (is-eq 1 1) (err 1)) ;; Returns true -``` - -### unwrap! -#### input: `(optional A) | (response A B), C` -#### output: `A` -#### signature: `(unwrap! option-input thrown-value)` -#### description: -The `unwrap!` function attempts to 'unpack' the first argument: if the argument is an option type, and the argument is a `(some ...)` option, `unwrap!` returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, `unwrap!` returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `(none)` value, `unwrap!` _returns_ `thrown-value` from the current function and exits the current control-flow. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(define-private (get-name-or-err (name (string-ascii 12))) - (let ((raw-name (unwrap! (map-get? names-map { name: name }) (err 1)))) - (ok raw-name))) - -(get-name-or-err \"blockstack\") ;; Returns (ok (tuple (id 1337))) -(get-name-or-err \"non-existant\") ;; Returns (err 1) -``` - -### unwrap-err! -#### input: `(response A B), C` -#### output: `B` -#### signature: `(unwrap-err! response-input thrown-value)` -#### description: -The `unwrap-err!` function attempts to 'unpack' the first argument: if the argument is an `(err ...)` response, `unwrap-err!` returns the inner value of the `err`. If the supplied argument is an `(ok ...)` value, `unwrap-err!` _returns_ `thrown-value` from the current function and exits the current control-flow. -#### example: -```clarity -(unwrap-err! (err 1) false) ;; Returns 1 -``` - -### unwrap-panic -#### input: `(optional A) | (response A B)` -#### output: `A` -#### signature: `(unwrap-panic option-input)` -#### description: -The `unwrap` function attempts to 'unpack' its argument: if the argument is an option type, and the argument is a `(some ...)` option, this function returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, it returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `(none)` value, `unwrap` throws a runtime error, aborting any further processing of the current transaction. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(unwrap-panic (map-get? names-map { name: \"blockstack\" })) ;; Returns (tuple (id 1337)) -(unwrap-panic (map-get? names-map { name: \"non-existant\" })) ;; Throws a runtime exception -``` - -### unwrap-err-panic -#### input: `(response A B)` -#### output: `B` -#### signature: `(unwrap-err-panic response-input)` -#### description: -The `unwrap-err` function attempts to 'unpack' the first argument: if the argument is an `(err ...)` response, `unwrap` returns the inner value of the `err`. If the supplied argument is an `(ok ...)` value, `unwrap-err` throws a runtime error, aborting any further processing of the current transaction. -#### example: -```clarity -(unwrap-err-panic (err 1)) ;; Returns 1 -(unwrap-err-panic (ok 1)) ;; Throws a runtime exception -``` - -### match -#### input: `(optional A) name expression expression | (response A B) name expression name expression` -#### output: `C` -#### signature: `(match opt-input some-binding-name some-branch none-branch) | -(match-resp input ok-binding-name ok-branch err-binding-name err-branch)` -#### description: -The `match` function is used to test and destructure optional and response types. - -If the `input` is an optional, it tests whether the provided `input` is a `some` or `none` option, and evaluates `some-branch` or `none-branch` in each respective case. - -Within the `some-branch`, the _contained value_ of the `input` argument is bound to the provided `some-binding-name` name. - -Only _one_ of the branches will be evaluated (similar to `if` statements). - -If the `input` is a response, it tests whether the provided `input` is an `ok` or `err` response type, and evaluates `ok-branch` or `err-branch` in each respective case. - -Within the `ok-branch`, the _contained ok value_ of the `input` argument is bound to the provided `ok-binding-name` name. - -Within the `err-branch`, the _contained err value_ of the `input` argument is bound to the provided `err-binding-name` name. - -Only _one_ of the branches will be evaluated (similar to `if` statements). - -Note: Type checking requires that the type of both the ok and err parts of the response object be determinable. For situations in which one of the parts of a response is untyped, you should use `unwrap-panic` or `unwrap-err-panic` instead of `match`. -#### example: -```clarity - -(define-private (add-10 (x (optional int))) - (match x - value (+ 10 value) - 10)) -(add-10 (some 5)) ;; Returns 15 -(add-10 none) ;; Returns 10 - -(define-private (add-or-pass-err (x (response int (string-ascii 10))) (to-add int)) - (match x - value (ok (+ to-add value)) - err-value (err err-value))) -(add-or-pass-err (ok 5) 20) ;; Returns (ok 25) -(add-or-pass-err (err \"ERROR\") 20) ;; Returns (err \"ERROR\") -``` - -### try! -#### input: `(optional A) | (response A B)` -#### output: `A` -#### signature: `(try! option-input)` -#### description: -The `try!` function attempts to 'unpack' the first argument: if the argument is an option type, and the argument is a `(some ...)` option, `try!` returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, `try!` returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `none` value, `try!` _returns_ either `none` or the `(err ...)` value from the current function and exits the current control-flow. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(try! (map-get? names-map { name: \"blockstack\" })) ;; Returns (tuple (id 1337)) -(define-private (checked-even (x int)) - (if (is-eq (mod x 2) 0) - (ok x) - (err false))) -(define-private (double-if-even (x int)) - (ok (* 2 (try! (checked-even x))))) -(double-if-even 10) ;; Returns (ok 20) -(double-if-even 3) ;; Returns (err false) -``` - -### is-ok -#### input: `(response A B)` -#### output: `bool` -#### signature: `(is-ok value)` -#### description: -`is-ok` tests a supplied response value, returning `true` if the response was `ok`, and `false` if it was an `err`. -#### example: -```clarity -(is-ok (ok 1)) ;; Returns true -(is-ok (err 1)) ;; Returns false -``` - -### is-none -#### input: `(optional A)` -#### output: `bool` -#### signature: `(is-none value)` -#### description: -`is-none` tests a supplied option value, returning `true` if the option value is `(none)`, and `false` if it is a `(some ...)`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(is-none (get id (map-get? names-map { name: \"blockstack\" }))) ;; Returns false -(is-none (get id (map-get? names-map { name: \"non-existant\" }))) ;; Returns true -``` - -### is-err -#### input: `(response A B)` -#### output: `bool` -#### signature: `(is-err value)` -#### description: -`is-err` tests a supplied response value, returning `true` if the response was an `err`, and `false` if it was an `ok`. -#### example: -```clarity -(is-err (ok 1)) ;; Returns false -(is-err (err 1)) ;; Returns true -``` - -### is-some -#### input: `(optional A)` -#### output: `bool` -#### signature: `(is-some value)` -#### description: -`is-some` tests a supplied option value, returning `true` if the option value is `(some ...)`, and `false` if it is a `none`. -#### example: -```clarity - -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(is-some (get id (map-get? names-map { name: \"blockstack\" }))) ;; Returns true -(is-some (get id (map-get? names-map { name: \"non-existant\" }))) ;; Returns false -``` - -### filter -#### input: `Function(A) -> bool, sequence_A` -#### output: `sequence_A` -#### signature: `(filter func sequence)` -#### description: -The `filter` function applies the input function `func` to each element of the input sequence, and returns the same sequence with any elements removed for which `func` returned `false`. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. ` -#### example: -```clarity - -(filter not (list true false true false)) ;; Returns (false false) -(define-private (is-a (char (string-utf8 1))) (is-eq char u\"a\")) -(filter is-a u\"acabd\") ;; Returns u\"aa\" -(define-private (is-zero (char (buff 1))) (is-eq char 0x00)) -(filter is-zero 0x00010002) ;; Returns 0x0000 -``` - -### ft-get-balance -#### input: `TokenName, principal` -#### output: `uint` -#### signature: `(ft-get-balance token-name principal)` -#### description: -`ft-get-balance` returns `token-name` balance of the principal `principal`. The token type must have been defined using `define-fungible-token`. -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-get-balance stackaroo 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns u100 -``` - -### nft-get-owner? -#### input: `AssetName, A` -#### output: `(optional principal)` -#### signature: `(nft-get-owner? asset-class asset-identifier)` -#### description: -`nft-get-owner?` returns the owner of an asset, identified by `asset-identifier`, or `none` if the asset does not exist. The asset type must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) -(nft-get-owner? stackaroo \"Roo\") ;; Returns (some SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) -(nft-get-owner? stackaroo \"Too\") ;; Returns none -``` - -### ft-transfer? -#### input: `TokenName, uint, principal, principal` -#### output: `(response bool uint)` -#### signature: `(ft-transfer? token-name amount sender recipient)` -#### description: -`ft-transfer?` is used to increase the token balance for the `recipient` principal for a token type defined using `define-fungible-token` by debiting the `sender` principal. In contrast to `stx-transfer?`, any user can transfer the assets. When used, relevant guards need to be added. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- amount to send is non-positive -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-transfer? stackaroo u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(ft-transfer? stackaroo u60 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u1) -``` - -### nft-transfer? -#### input: `AssetName, A, principal, principal` -#### output: `(response bool uint)` -#### signature: `(nft-transfer? asset-class asset-identifier sender recipient)` -#### description: -`nft-transfer?` is used to change the owner of an asset identified by `asset-identifier` from `sender` to `recipient`. The `asset-class` must have been defined by `define-non-fungible-token` and `asset-identifier` must be of the type specified in that definition. In contrast to `stx-transfer?`, any user can transfer the asset. When used, relevant guards need to be added. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not own the asset `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- asset identified by asset-identifier does not exist -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(nft-transfer? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(nft-transfer? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u1) -(nft-transfer? stackaroo \"Stacka\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u3) -``` - -### nft-mint? -#### input: `AssetName, A, principal` -#### output: `(response bool uint)` -#### signature: `(nft-mint? asset-class asset-identifier recipient)` -#### description: -`nft-mint?` is used to instantiate an asset and set that asset's owner to the `recipient` principal. The asset must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. - -If an asset identified by `asset-identifier` _already exists_, this function will return an error with the following error code: - -`(err u1)` - -Otherwise, on successfuly mint, it returns `(ok true)`. ` -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### ft-mint? -#### input: `TokenName, uint, principal` -#### output: `(response bool uint)` -#### signature: `(ft-mint? token-name amount recipient)` -#### description: -`ft-mint?` is used to increase the token balance for the `recipient` principal for a token type defined using `define-fungible-token`. The increased token balance is _not_ transfered from another principal, but rather minted. - -If a non-positive amount is provided to mint, this function returns `(err 1)`. Otherwise, on successfuly mint, it returns `(ok true)`. ` -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### ft-get-supply -#### input: `TokenName` -#### output: `uint` -#### signature: `(ft-get-supply token-name)` -#### description: -`ft-get-balance` returns `token-name` circulating supply. The token type must have been defined using `define-fungible-token`. -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-get-supply stackaroo) ;; Returns u100 -``` - -### ft-burn? -#### input: `TokenName, uint, principal` -#### output: `(response bool uint)` -#### signature: `(ft-burn? token-name amount sender)` -#### description: -`ft-burn?` is used to decrease the token balance for the `sender` principal for a token type defined using `define-fungible-token`. The decreased token balance is _not_ transfered to another principal, but rather destroyed, reducing the circulating supply. - -If a non-positive amount is provided to burn, this function returns `(err 1)`. Otherwise, on successfuly burn, it returns `(ok true)`. - -#### example: -```clarity - -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(ft-burn? stackaroo u50 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### nft-burn? -#### input: `AssetName, A, principal` -#### output: `(response bool uint)` -#### signature: `(nft-burn? asset-class asset-identifier recipient)` -#### description: -`nft-burn?` is used to burn an asset and remove that asset's owner from the `recipient` principal. The asset must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. - -If an asset identified by `asset-identifier` _doesn't exist_, this function will return an error with the following error code: - -`(err u1)` - -Otherwise, on successfuly burn, it returns `(ok true)`. ` -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(nft-burn? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### stx-get-balance -#### input: `principal` -#### output: `uint` -#### signature: `(stx-get-balance owner)` -#### description: -`stx-get-balance` is used to query the STX balance of the `owner` principal. - -This function returns the STX balance of the `owner` principal. In the event that the `owner` principal isn't materialized, it returns 0. - -#### example: -```clarity -(stx-get-balance 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns u0 -(stx-get-balance (as-contract tx-sender)) ;; Returns u1000 -``` - -### stx-transfer? -#### input: `uint, principal, principal` -#### output: `(response bool uint)` -#### signature: `(stx-transfer? amount sender recipient)` -#### description: -`stx-transfer?` is used to increase the STX balance for the `recipient` principal by debiting the `sender` principal. The `sender` principal _must_ be equal to the current context's `tx-sender`. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- amount to send is non-positive `(err u4)` -- the `sender` principal is not the current `tx-sender` - -#### example: -```clarity - -(as-contract - (stx-transfer? u60 tx-sender 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (ok true) -(as-contract - (stx-transfer? u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR tx-sender)) ;; Returns (err u4) -``` - -### stx-burn? -#### input: `uint, principal` -#### output: `(response bool uint)` -#### signature: `(stx-burn? amount sender)` -#### description: -`stx-burn?` debits the `sender` principal's STX holdings by `amount`, destroying the STX. The `sender` principal _must_ be equal to the current context's `tx-sender`. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u3)` -- amount to send is non-positive `(err u4)` -- the `sender` principal is not the current `tx-sender` - -#### example: -```clarity -(as-contract - (stx-burn? u60 tx-sender)) ;; Returns (ok true) -(as-contract - (stx-burn? u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (err u4) -``` - -### define-constant -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-constant name expression)` -#### description: -`define-constant` is used to define a private constant value in a smart contract. The expression passed into the definition is evaluated at contract launch, in the order that it is supplied in the contract. This can lead to undefined function or undefined variable errors in the event that a function or variable used in the expression has not been defined before the constant. - -Like other kinds of definition statements, `define-constant` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -#### example: -```clarity - -(define-constant four (+ 2 2)) -(+ 4 four) ;; Returns 8 -``` - -### define-private -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-private (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### description: -`define-private` is used to define _private_ functions for a smart contract. Private functions may not be called from other smart contracts, nor may they be invoked directly by users. Instead, these functions may only be invoked by other functions defined in the same smart contract. - -Like other kinds of definition statements, `define-private` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Private functions may return any type. -#### example: -```clarity -(define-private (max-of (i1 int) (i2 int)) - (if (> i1 i2) - i1 - i2)) -(max-of 4 6) ;; Returns 6 -``` - -### define-public -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-public (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### description: -`define-public` is used to define a _public_ function and transaction for a smart contract. Public functions are callable from other smart contracts and may be invoked directly by users by submitting a transaction to the Stacks blockchain. - -Like other kinds of definition statements, `define-public` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Public functions _must_ return a ResponseType (using either `ok` or `err`). Any datamap modifications performed by a public function is aborted if the function returns an `err` type. Public functions may be invoked by other contracts via `contract-call?`. -#### example: -```clarity -(define-public (hello-world (input int)) - (begin (print (+ 2 input)) - (ok input))) -``` - -### define-read-only -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-read-only (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### description: -`define-read-only` is used to define a _public read-only_ function for a smart contract. Such functions are callable from other smart contracts. - -Like other kinds of definition statements, `define-read-only` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Read-only functions may return any type. However, read-only functions may not perform any datamap modifications, or call any functions which perform such modifications. This is enforced both during type checks and during the execution of the function. Public read-only functions may be invoked by other contracts via `contract-call?`. -#### example: -```clarity -(define-read-only (just-return-one-hundred) - (* 10 10)) - ``` - -### define-map -#### input: `MapName, TypeDefinition, TypeDefinition` -#### output: `Not Applicable` -#### signature: `(define-map map-name key-type value-type)` -#### description: -`define-map` is used to define a new datamap for use in a smart contract. Such maps are only modifiable by the current smart contract. - -Maps are defined with a key type and value type, often these types are tuple types. - -Like other kinds of definition statements, `define-map` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). -#### example: -```clarity -(define-map squares { x: int } { square: int }) -(define-private (add-entry (x int)) - (map-insert squares { x: 2 } { square: (* x x) })) -(add-entry 1) -(add-entry 2) -(add-entry 3) -(add-entry 4) -(add-entry 5) -``` - -### define-data-var -#### input: `VarName, TypeDefinition, Value` -#### output: `Not Applicable` -#### signature: `(define-data-var var-name type value)` -#### description: -`define-data-var` is used to define a new persisted variable for use in a smart contract. Such variable are only modifiable by the current smart contract. - -Persisted variable are defined with a type and a value. - -Like other kinds of definition statements, `define-data-var` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). -#### example: -```clarity -(define-data-var size int 0) -(define-private (set-size (value int)) - (var-set size value)) -(set-size 1) -(set-size 2) -``` - -### define-fungible-token -#### input: `TokenName, ` -#### output: `Not Applicable` -#### signature: `(define-fungible-token token-name )` -#### description: -`define-fungible-token` is used to define a new fungible token class for use in the current contract. - -The second argument, if supplied, defines the total supply of the fungible token. This ensures that all calls to the `ft-mint?` function will never be able to create more than `total-supply` tokens. If any such call were to increase the total supply of tokens passed that amount, that invocation of `ft-mint?` will result in a runtime error and abort. - -Like other kinds of definition statements, `define-fungible-token` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Tokens defined using `define-fungible-token` may be used in `ft-transfer?`, `ft-mint?`, and `ft-get-balance` functions` -#### example: -```clarity -(define-fungible-token stacks) -(define-fungible-token limited-supply-stacks u100) -``` - -### define-non-fungible-token -#### input: `AssetName, TypeSignature` -#### output: `Not Applicable` -#### signature: `(define-non-fungible-token asset-name asset-identifier-type)` -#### description: -`define-non-fungible-token` is used to define a new non-fungible token class for use in the current contract. Individual assets are identified by their asset identifier, which must be of the type `asset-identifier-type`. Asset identifiers are _unique_ identifiers. - -Like other kinds of definition statements, `define-non-fungible-token` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Assets defined using `define-non-fungible-token` may be used in `nft-transfer?`, `nft-mint?`, and `nft-get-owner?` functions` -#### example: -```clarity -(define-non-fungible-token names (buff 50)) -``` - -### define-trait -#### input: `VarName, [MethodSignature]` -#### output: `Not Applicable` -#### signature: `(define-trait trait-name ((func1-name (arg1-type arg2-type ...) (return-type))))` -#### description: -`define-trait` is used to define a new trait definition for use in a smart contract. Other contracts can implement a given trait and then have their contract identifier being passed as function arguments in order to be called dynamically with `contract-call?`. - -Traits are defined with a name, and a list functions defined with a name, a list of argument types, and return type. - -Like other kinds of definition statements, `define-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -#### example: -```clarity -(define-trait token-trait - ((transfer? (principal principal uint) (response uint uint)) - (get-balance (principal) (response uint uint)))) -``` - -### use-trait -#### input: `VarName, TraitIdentifier` -#### output: `Not Applicable` -#### signature: `(use-trait trait-alias trait-identifier)` -#### description: -`use-trait` is used to bring a trait, defined in another contract, to the current contract. Subsequent references to an imported trait are signaled with the syntax ``. - -Traits import are defined with a name, used as an alias, and a trait identifier. Trait identifiers can either be using the sugared syntax (.token-a.token-trait), or be fully qualified ('SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait). - -Like other kinds of definition statements, `use-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put such a statement in the middle of a function body). -#### example: -```clarity -(use-trait token-a-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) -(define-public (forward-get-balance (user principal) (contract )) - (begin - (ok 1))) -``` - -### impl-trait -#### input: `TraitIdentifier` -#### output: `Not Applicable` -#### signature: `(impl-trait trait-identifier)` -#### description: -`impl-trait` can be use for asserting that a contract is fully implementing a given trait. Additional checks are being performed when the contract is being published, rejecting the deployment if the contract is violating the trait specification. - -Trait identifiers can either be using the sugared syntax (.token-a.token-trait), or be fully qualified ('SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait). - -Like other kinds of definition statements, `impl-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put such a statement in the middle of a function body). - -#### example: -```clarity -(impl-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) -(define-public (get-balance (account principal)) - (ok u0)) -(define-public (transfer? (from principal) (to principal) (amount uint)) - (ok u0)) -``` \ No newline at end of file diff --git a/i18n/id/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md b/i18n/id/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md deleted file mode 100644 index 9daa5f6fc1..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: Kata kunci -description: Lihat daftar rinci semua kata kunci untuk bahasa Clarity. -tags: - - clarity ---- - -![](/img/keywords.jpg) -## Referensi kata kunci - -Detailed list of all keywords for the Clarity language. - - -### contract-caller -#### output: `principal` -#### description: -Returns the caller of the current contract context. If this contract is the first one called by a signed transaction, the caller will be equal to the signing principal. If `contract-call?` was used to invoke a function from a new contract, `contract-caller` changes to the _calling_ contract's principal. If `as-contract` is used to change the `tx-sender` context, `contract-caller` _also_ changes to the same contract principal. -#### example: -```clarity -(print contract-caller) ;; Will print out a Stacks address of the transaction sender -``` - -### tx-sender -#### output: `principal` -#### description: -Returns the original sender of the current transaction, or if `as-contract` was called to modify the sending context, it returns that contract principal. -#### example: -```clarity -(print tx-sender) ;; Will print out a Stacks address of the transaction sender -``` - -### block-height -#### output: `uint` -#### description: -Returns the current block height of the Stacks blockchain as an uint -#### example: -```clarity -(> block-height 1000) ;; returns true if the current block-height has passed 1000 blocks. -``` - -### burn-block-height -#### output: `uint` -#### description: -Returns the current block height of the underlying burn blockchain as a uint -#### example: -```clarity -(> burn-block-height 1000) ;; returns true if the current height of the underlying burn blockchain has passed 1000 blocks. -``` - -### none -#### output: `(optional ?)` -#### description: -Represents the _none_ option indicating no value for a given optional (analogous to a null value). -#### example: -```clarity -(define-public (only-if-positive (a int)) - (if (> a 0) - (some a) - none)) -(only-if-positive 4) ;; Returns (some 4) -(only-if-positive (- 3)) ;; Returns none -``` - -### true -#### output: `bool` -#### description: -Boolean true constant. -#### example: -```clarity -(and true false) ;; Evaluates to false -(or false true) ;; Evaluates to true -``` - -### false -#### output: `bool` -#### description: -Boolean false constant. -#### example: -```clarity -(and true false) ;; Evaluates to false -(or false true) ;; Evaluates to true -``` - -### stx-liquid-supply -#### output: `uint` -#### description: -Returns the total number of micro-STX (uSTX) that are liquid in the system as of this block. -#### example: -```clarity -(print stx-liquid-supply) ;; Will print out the total number of liquid uSTX -``` - -### is-in-regtest -#### output: `bool` -#### description: -Returns whether or not the code is running in a regression test -#### example: -```clarity -(print is-in-regtest) ;; Will print 'true' if the code is running in a regression test - -``` - diff --git a/i18n/id/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md b/i18n/id/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md deleted file mode 100644 index 4cd25aae73..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Tipe -description: Lihat daftar rinci semua tipe untuk bahasa Clarity. -tags: - - clarity ---- - -## Sistem Tipe Clarity - -Sistem tipe ini berisi: - -| Tipe | Notes | -| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `int` | signed 128-bit integer | -| `uint` | unsigned 128-bit integer | -| `bool` | boolean value (`true` or `false`) | -| `principal` | object representing a principal (whether a contract principal or standard principal) | -| `(buff max-len)` | byte buffer of 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` (u"A smiley face emoji \u{1F600} as a utf8 string") | -| `(list max-len entry-type)` | list of maximum length `max-len`, with entries of type `entry-type` | -| `{label-0: value-type-0, label-1: value-type-1, ...}` | tuple, group of data values with named fields | -| `(optional some-type)` | an option type for objects that can either be `(some value)` or `none` | -| `(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. | diff --git a/i18n/id/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md b/i18n/id/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md deleted file mode 100644 index b53be32110..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Ringkasan Clarity -description: Ringkasan dan panduan untuk memulai Clarity -sidebar_label: Menulis kontrak pintar -sidebar_position: 2 ---- - -## Pengantar - -Clarity adalah bahasa kontrak pintar yang **dapat ditentukan** yang mengoptimalkan prediktabilitas dan keamanan, dirancang untuk blockchain Stacks. Kontrak pintar memungkinkan pengembang untuk mengkodekan logika bisnis penting di blockchain. - -## Kontrak pintar - -Kontrak pintar mengkodekan dan menegakkan aturan untuk memodifikasi kumpulan data tertentu yang dibagikan di antara orang-orang dan entitas yang belum tentu saling percaya satu sama lain. Misalnya, kontrak pintar dapat menyimpan dana dalam escrow sampai beberapa pihak setuju untuk melepaskan dana tersebut, membuat buku besar sendiri dan melacak token barunya sendiri (sepadan atau tidak sepadan), dan bahkan membantu membuat rantai pasokan lebih transparan. - -Karena kontrak pintar adalah program yang ada di blockchain, siapa pun dapat mengquerikan, dan siapa pun dapat mengirimkan transaksi untuk menjalankannya. Menjalankan kontrak pintar dapat menghasilkan transaksi baru yang ditulis ke blockchain. - -Aplikasi dapat memanfaatkan kontrak pintar untuk mengelola status global yang dapat dilihat oleh publik. Siapa pun dapat mengaudit blockchain untuk memverifikasi secara independen bahwa status bersama global aplikasi telah dikelola dengan benar sesuai dengan aturan kontrak pintar. - -Ada [plugin Clarity Visual Studio Code][] yang tersedia untuk bantuan sintaks dan debugging. - -## Kasus penggunaan - -Tidak semua aplikasi terdesentralisasi memerlukan kontrak pintar, tetapi Clarity membuka kemampuan menarik untuk aplikasi yang terdesentralisasi. Contoh dari kasus penggunaan termasuk, namun tidak terbatas pada: - -- Kontrol akses (misalnya membayar untuk bisa mengakses) -- Non-fungible (misalnya barang koleksi) dan token fungible (misalnya stablecoin) -- Template model bisnis (misalnya langganan) -- Blockchain khusus aplikasi -- Decentralized Autonomous Organizations - -## Desain bahasa - -Clarity berbeda dari kebanyakan bahasa kontrak pintar lainnya dalam dua hal penting yaitu: - -- Bahasa diinterpretasikan dan disiarkan di blockchain sebagaimana adanya (tidak dikompilasi) -- Bahasa dapat ditentukan (tidak Turing lengkap) - -Menggunakan bahasa yang diinterpretasikan memastikan bahwa kode yang dieksekusi dapat dibaca oleh manusia dan dapat diaudit. Bahasa yang dapat ditentukan seperti Clarity memungkinkan untuk menentukan dengan tepat kode mana yang bisa dijalankan, untuk fungsi apa pun. - -Kontrak pintar Clarity terdiri dari dua bagian, ruang data dan serangkaian fungsi. Hanya kontrak pintar terkait yang dapat mengubah ruang data terkait di blockchain. Fungsi mungkin bersifat privat dan dengan demikian hanya dapat dipanggil dari dalam kontrak pintar, atau publik dan dengan demikian dapat dipanggil dari kontrak lain. Pengguna memanggil fungsi publik kontrak pintar dengan menyiarkan transaksi di blockchain yang dapat memanggil fungsi publik. Kontrak juga dapat memanggil fungsi publik dari kontrak pintar lainnya. - -Perhatikan beberapa aturan dan batasan bahasa Clarity utama. - -- Satu-satunya tipe primitif adalah boolean, integer, buffer, dan prinsipal. -- Rekursi adalah ilegal dan tidak memiliki fungsi anonim. -- Looping hanya dilakukan melalui `map`, `filter`, atau `fold`. -- Ada dukungan untuk daftar, namun, satu-satunya daftar panjang variabel dalam bahasa yang muncul sebagai input fungsi; tidak ada dukungan untuk operasi daftar seperti menambahkan atau bergabung. -- Variabel tidak dapat diubah. - -## Jelajahi lebih banyak - -Untuk detail dan referensi bahasa, lihat berikut ini: - -- [Clarity language overview](./clarity-language/) -- [Understating Principals](principals) -- [Nilai Clarity](values) - -[plugin Clarity Visual Studio Code]: https://marketplace.visualstudio.com/items?itemName=HiroSystems.clarity-lsp diff --git a/i18n/id/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md b/i18n/id/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md deleted file mode 100644 index 78f4effbb3..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md +++ /dev/null @@ -1,236 +0,0 @@ ---- -title: Prinsipal -description: 'Clarity: Memahami Prinsipal' -sidebar_position: 1 ---- - -## Pengantar - -_Prinsipal_ adalah tipe native Clarity yang mewakili entitas yang dapat memiliki saldo token. Bagian ini membahas prinsip-prinsip dan bagaimana mereka digunakan dalam Clarity. - -## Prinsipal dan tx-sender - -Aset dalam bahasa kontrak pintar dan blockchain "dimiliki" oleh objek dari tipe utama, yang berarti bahwa objek apa pun dari tipe utama dapat memiliki aset. Untuk kasus alamat Stacks dari hash kunci-publik dan multi-tanda tangan, prinsipal tertentu dapat beroperasi pada aset mereka dengan mengeluarkan transaksi yang ditandatangani di blockchain. _Kontrak pintar_ mungkin juga prinsipal (direpresentasikan oleh pengidentifikasi kontrak pintar), namun, tidak ada kunci privat yang terkait dengan kontrak pintar, dan tidak dapat menyiarkan transaksi yang ditandatangani pada blockchain. - -Kontrak Clarity dapat menggunakan variabel `tx sender` yang ditentukan secara global untuk mendapatkan prinsipal saat ini. Contoh berikut mendefinisikan jenis transaksi yang mentransfer `amount` microSTX dari pengirim ke penerima jika jumlahnya kelipatan 10, jika tidak maka akan mengembalikan kode kesalahan 400. - -```clarity -(define-public (transfer-to-recipient! (recipient principal) (amount uint)) - (if (is-eq (mod amount 10) 0) - (stx-transfer? amount tx-sender recipient) - (err u400))) -``` - -Clarity menyediakan variabel tambahan untuk membantu kontrak pintar mengautentikasi pengirim transaksi. Kata kunci `contract-caller` mengembalikan prinsipal yang _memanggil_ kontrak saat ini. Jika panggilan antar-kontrak terjadi, `contract-caller` mengembalikan kontrak terakhir di Stacks pemanggil. Misalnya, ada tiga kontrak A, B, dan C, masing-masing dengan fungsi `invoke` sedemikian rupa sehingga `A::invoke` memanggil `B::invoke` dan `B::invoke` memanggil `C::invoke`. - -When a user Bob issues a transaction that calls `A::invoke`, the value of `contract-caller` in each successive invoke function's body would change: - -```clarity -in A::invoke, contract-caller = Bob -in B::invoke, contract-caller = A -in C::invoke, contract-caller = B -``` - -Hal ini memungkinkan kontrak untuk membuat pernyataan dan melakukan pemeriksaan otorisasi tidak hanya menggunakan `tx-sender` (yang dalam contoh ini, akan selalu menjadi "Bob"), tetapi juga menggunakan `contract-caller`. Ini dapat digunakan untuk memastikan bahwa fungsi tertentu hanya dipanggil secara langsung dan tidak pernah dipanggil melalui panggilan antar-kontrak (dengan menyatakan bahwa `tx-sender` dan `contract-caller` adalah sama). Kami memberikan contoh dua jenis pemeriksaan otorisasi yang berbeda dalam contoh kapal roket di bawah ini. - -## Kontrak pintar sebagai prinsipal - -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, for example: - -```clarity -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-name -``` - -Untuk kenyamanan, kontrak pintar dapat menulis pengidentifikasi kontrak dalam bentuk `.contract-name`. Ini akan diperluas oleh juru bahasa Clarity menjadi pengidentifikasi kontrak yang sepenuhnya memenuhi syarat yang sesuai dengan alamat penerbitan yang sama dengan kontrak tempat kontrak tersebut muncul. Misalnya, jika alamat penerbit yang sama, `SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR`, menerbitkan dua kontrak, `contract-A` dan `contract-B`, pengidentifikasi yang sepenuhnya memenuhi syarat untuk kontrak akan menjadi: - -```clarity -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-A -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-B -``` - -But, in the contract source code, if the developer wishes to call a function from `contract-A` in `contract-B`, they can write - -```clarity -(contract-call? .contract-A public-function-foo) -``` - -This allows the smart contract developer to modularize their applications across multiple smart contracts _without_ knowing the publishing key a priori. - -Agar kontrak cerdas dapat beroperasi pada aset yang dimilikinya, kontrak cerdas dapat menggunakan fungsi khusus `(as-contract ...)`. Fungsi ini menjalankan ekspresi (diteruskan sebagai argumen) dengan `tx-sender` disetel ke prinsipal kontrak, bukan pengirim saat ini. Fungsi `as-contract` yaitu mengembalikan nilai ekspresi yang diberikan. - -For example, a smart contract that implements something like a "token faucet" could be implemented as so: - -```clarity -(define-map claimed-before - ((sender principal)) - ((claimed bool))) - -(define-constant err-already-claimed u1) -(define-constant err-faucet-empty u2) -(define-constant stx-amount u1) - -(define-public (claim-from-faucet) - (let ((requester tx-sender)) ;; set a local variable requester = tx-sender - (asserts! (is-none (map-get? claimed-before {sender: requester})) (err err-already-claimed)) - (unwrap! (as-contract (stx-transfer? stx-amount tx-sender requester)) (err err-faucet-empty)) - (map-set claimed-before {sender: requester} {claimed: true}) - (ok stx-amount))) -``` - -Dalam contoh ini, fungsi publik `claim-from-faucet`: - -- Memeriksa apakah pengirim telah mengklaim dari faucet sebelumnya. -- Menetapkan tx sender ke variabel `requester`. -- Menambahkan entri ke peta pelacakan. -- Menggunakan `as-contract` untuk mengirim 1 mikrostack - -Tidak seperti prinsipal lainnya, tidak ada kunci privat yang terkait dengan kontrak pintar. Karena tidak memiliki kunci privat, kontrak pintar Clarity tidak dapat menyiarkan transaksi yang ditandatangani di blockchain. - -## Contoh: Pemeriksaan otorisasi - -Interaksi antara `tx-sender`, `contract-caller` dan `as-contract` tidak begitu terlihat, tetapi penting saat melakukan pemeriksaan otorisasi dalam sebuah kontrak. Dalam contoh kontrak ini, kami akan menunjukkan dua jenis pemeriksaan otorisasi yang berbeda yang mungkin akan dilakukan oleh suatu kontrak, dan kemudian membahas bagaimana cara yang berbeda dalam memanggil fungsi kontrak akan berhasil atau gagal dalam pemeriksaan tersebut. - -Kontrak ini mendefinisikan sebuah "kapal roket" token-yang tidak-sepadan di mana prinsipal dapat memiliki dan mengelola pilot resmi. Pilot adalah prinsipal yang diizinkan untuk "menerbangkan" kapal roket. - -Kontrak ini melakukan dua pemeriksaan otorisasi yang berbeda: - -1. Sebelum kapal diizinkan untuk terbang, kontrak akan memeriksa apakah transaksi dibuat dan ditandatangani oleh pilot yang berwenang atau tidak. Seorang pilot dapat, misalnya, memanggil kontrak lain, yang kemudian memanggil fungsi publik `fly-ship` atas nama pilot. -2. Sebelum memodifikasi pilot yang diizinkan untuk kapal roket tertentu, kontrak tersebut memeriksa bahwa transaksi tersebut ditandatangani oleh pemilik kapal roket. Selanjutnya, kontrak mensyaratkan bahwa fungsi ini dipanggil _langsung_ oleh pemilik kapal, bukan melalui panggilan antar-kontrak. - -The second type of check is more restrictive than the first check, and is helpful for guarding very sensitive routines --- it protects users from unknowingly calling a function on a malicious contract that subsequently tries to call sensitive functions on another contract. - -```clarity -;; -;; rockets-base.clar -;; - -(define-non-fungible-token rocket-ship uint) - -;; a map from rocket ships to their allowed -;; pilots -(define-map allowed-pilots - ((rocket-ship uint)) ((pilots (list 10 principal)))) - -;; implementing a contains function via fold -(define-private (contains-check - (y principal) - (to-check { p: principal, result: bool })) - (if (get result to-check) - to-check - { p: (get p to-check), - result: (is-eq (get p to-check) y) })) - -(define-private (contains (x principal) (find-in (list 10 principal))) - (get result (fold contains-check find-in - { p: x, result: false }))) - -(define-read-only (is-my-ship (ship uint)) - (is-eq (some tx-sender) (nft-get-owner? rocket-ship ship))) - -;; this function will print a message -;; (and emit an event) if the tx-sender was -;; an authorized flyer. -;; -;; here we use tx-sender, because we want -;; to allow the user to let other contracts -;; fly the ship on behalf of users - -(define-public (fly-ship (ship uint)) - (let ((pilots (default-to - (list) - (get pilots (map-get? allowed-pilots { rocket-ship: ship }))))) - (if (contains tx-sender pilots) - (begin (print "Flew the rocket-ship!") - (ok true)) - (begin (print "Tried to fly without permission!") - (ok false))))) -;; -;; Authorize a new pilot. -;; -;; here we want to ensure that this function -;; was called _directly_ by the user by -;; checking that tx-sender and contract-caller are equal. -;; if any other contract is in the call stack, contract-caller -;; would be updated to a different principal. -;; -(define-public (authorize-pilot (ship uint) (pilot principal)) - (begin - ;; sender must equal caller: an intermediate contract is - ;; not issuing this call. - (asserts! (is-eq tx-sender contract-caller) (err u1)) - ;; sender must own the rocket ship - (asserts! (is-eq (some tx-sender) - (nft-get-owner? rocket-ship ship)) (err u2)) - (let ((prev-pilots (default-to - (list) - (get pilots (map-get? allowed-pilots { rocket-ship: ship }))))) - ;; don't add a pilot already in the list - (asserts! (not (contains pilot prev-pilots)) (err u3)) - ;; append to the list, and check that it is less than - ;; the allowed maximum - (match (as-max-len? (append prev-pilots pilot) u10) - next-pilots - (ok (map-set allowed-pilots {rocket-ship: ship} {pilots: next-pilots})) - ;; too many pilots already - (err u4))))) -``` - -### Memperluas fungsionalitas: Kontrak multi-flyer - -Skema otorisasi untuk `fly-ship` memungkinkan pilot untuk menerbangkan roket dari kontrak lain. Ini memungkinkan kontrak lain untuk menyediakan fungsionalitas baru yang dibangun di sekitar pemanggilan fungsi tersebut. - -For example, we can create a contract that calls `fly-ship` for multiple rocket-ships in a single transaction: - -```clarity -;; -;; rockets-multi.clar -;; - -(define-private (call-fly (ship uint)) - (unwrap! (contract-call? .rockets-base fly-ship ship) false)) -;; try to fly all the ships, returning a list of whether -;; or not we were able to fly the supplied ships -(define-public (fly-all (ships (list 10 uint))) - (ok (map call-fly ships))) -``` - -### Otorisasi untuk Aset Milik Kontrak - -Pemeriksaan `authorize-pilot` melindungi pengguna dari kontrak berbahaya, tetapi bagaimana skema tersebut mendukung aset yang dimiliki kontrak? Inilah gunanya fungsi dari `as-contract`. Fungsi `as-contract` menjalankan penutupan yang diberikan seolah-olah pengirim transaksi adalah kontrak saat ini, bukan pengguna -- fungsi ini dilakukan dengan memperbarui `tx sender` ke prinsip kontrak saat ini. Kita dapat menggunakan ini untuk, misalnya, membuat kontrak kapal roket pintar: - -```clarity -;; -;; rockets-ship-line.clar -;; - -(define-constant line-ceo 'SP19Y6GRV9X778VFS1V8WT2H502WFK33XZXADJWZ) - -(define-data-var employed-pilots (list 10 principal) (list)) - -;; This function will: -;; * check that it is called by the line-ceo -;; * check that the rocket is owned by the contract -;; * authorize each employed pilot to the ship -(define-public (add-managed-rocket (ship uint)) - (begin - ;; 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 - (asserts! (contract-call? .rockets-base is-my-ship ship) (err u2)) - ;; register all of our pilots on the ship - (add-pilots-to ship))))) - -;; add all the pilots to a ship using fold -- -;; the fold checks the return type of previous calls, -;; skipping subsequent contract-calls if one fails. -(define-private (add-pilot-via-fold (pilot principal) (prior-result (response uint uint))) - (let ((ship (try! prior-result))) - (try! (contract-call? .rockets-base authorize-pilot ship pilot)) - (ok ship))) -(define-private (add-pilots-to (ship uint)) - (fold add-pilot-via-fold (var-get employed-pilots) (ok ship))) -``` - -Agar kontrak dapat menambahkan setiap pilot ke kapal baru, kontrak harus memanggil `otorisasi-pilot`. Namun, kontrak ingin melakukan tindakan ini atas nama kapal yang _kontrak_ miliki, bukan pengirim transaksi. Untuk melakukan ini, kontrak menggunakan `as-contract`. diff --git a/i18n/id/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md b/i18n/id/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md deleted file mode 100644 index a01e37bc04..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Resources -description: 'Resources' -sidebar_position: 8 ---- - -# External resources - - -[Clarity book](https://book.clarity-lang.org/) - -[Clarity Universe](https://stacks.org/clarity-universe) - -[Hiro Clarity tutorials](https://docs.hiro.so/tutorials) diff --git a/i18n/id/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md b/i18n/id/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md deleted file mode 100644 index cfdcf8f22a..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Perangkat lunak pengembangan Clarity -description: Alat berikut berguna saat mengembangkan kontrak pintar Clarity -sidebar_position: 4 ---- - -## Language Server Protocol untuk Clarity (termasuk ekstensi Kode Visual Studio) - -Language Server Protocol (LSP) mendefinisikan protokol yang digunakan antara editor atau IDE dan server bahasa yang menyediakan fitur bahasa seperti pelengkapan otomatis, masuk ke definisi, menemukan semua referensi, dll. - -Ini membuat pemrograman di Clarity lebih mudah dan lebih intuitif. - -![Tangkapan Layar Clarity LSP](https://raw.githubusercontent.com/hirosystems/clarity-lsp/21b64298ca117dc41358eb9dce4605cc4a448a4c/images/screenshot.png?raw=true) - - -Repositori Clarity LSP tersedia [di sini](https://github.com/hirosystems/clarity-lsp). Ekstensi untuk Visual Studio Code dapat diunduh langsung dari [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=HiroSystems.clarity-lsp), tetapi mungkin untuk versi lebih lama. Untuk versi yang lebih terbaru, Anda juga dapat mengunduhnya dari [open-vsx](https://open-vsx.org/extension/hirosystems/clarity-lsp). - -## Clarity REPL - -Read—eval—print loop (REPL), juga disebut sebagai tingkat atas interaktif atau bahasa shell, adalah sederhana, lingkungan pemrograman komputer interaktif yang mengambil input pengguna tunggal (yaitu, ekspresi tunggal), mengevaluasi (mengeksekusi) mereka, dan mengembalikan hasil untuk pengguna; sebuah program yang ditulis dalam lingkungan REPL dijalankan secara sepotong demi sepotong. - -![Clarity-repl](https://github.com/hirosystems/clarity-repl/blob/develop/docs/images/screenshot.png?raw=true) - -Petunjuk tentang cara menginstal Clarity REPL dapat ditemukan [di sini](https://github.com/hirosystems/clarity-repl). - -## Clarinet - -Clarinet adalah runtime Clarity yang dikemas sebagai alat baris perintah, yang dirancang untuk memfasilitasi pemahaman, pengembangan, pengujian, dan penerapan kontrak cerdas. Clarinet terdiri dari Clarity REPL dan rangkaian pengujian, yang bila digunakan bersama-sama memungkinkan Anda bisa mengembangkan dan menguji kontrak pintar Clarity dengan cepat, dengan kebutuhan untuk menyebarkan kontrak ke devnet atau testnet lokal. - -![Clarinet](https://github.com/hirosystems/clarinet/blob/develop/docs/images/demo.gif?raw=true) - -Petunjuk penginstalan, termasuk petunjuk build dari sumber dapat ditemukan [di sini](https://github.com/hirosystems/clarinet). Jika mau, Anda dapat langsung mengunduh realease terkompilasi terbaru untuk Windows, Mac, dan Linux [di sini](https://github.com/hirosystems/clarinet/releases). - -[Clarinet 101](https://www.youtube.com/playlist?list=PL5Ujm489LoJaAz9kUJm8lYUWdGJ2AnQTb) berisi beberapa video tutorial Clarinet - -### Memulai dengan Clarinet - -Anda dapat memverifikasi bahwa Anda telah menginstal Clarinet dengan memeriksa versinya: - -```bash -$ clarinet --version -clarinet 0.70 -``` - -Informasi lebih lanjut tentang penggunaan Clarinet tersedia [di sini](https://book.clarity-lang.org/ch07-00-using-clarinet.html). Namun untuk memulai, perintah berikut penting untuk diketahui. - -Buat proyek baru dan masukkan direktorinya: - -```bash -clarinet new my-project && cd my-project -``` - -Buat kontrak baru di dalam `my-project`: - -```bash -clarinet contract new mycoolcontract -``` - -Check the syntax of Clarity: - -```bash -clarity check -``` - -Untuk menguji kontrak Anda: - -```bash -clarinet test -``` - -Masuk ke konsol Clarinet: - -```bash -clarinet console -``` diff --git a/i18n/id/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md b/i18n/id/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md deleted file mode 100644 index d319f409af..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Token -description: Pelajari tentang dukungan token dalam Clarity -sidebar_position: 3 ---- - -## Pengantar - -Penggunaan mendasar dari teknologi blockchain adalah representasi, penyimpanan, dan transfer nilai antara pengguna blockchain. Mata uang kripto adalah penggunaan teknologi blockchain yang sangat umum, dan tetap menjadi salah satu pendorong utama adopsi teknologi blockchain. Mata uang kripto direpresentasikan oleh token blockchain: unit nilai individual dalam ekosistem blockchain tertentu. Token Blockchain dapat melampaui mata uang digital, bagaimanapun, dan perkembangan terakhir di seluruh komunitas mata uang kripto telah menunjukkan potensi penggunaan blockchain untuk tokenize dan merepresentasikan tidak hanya uang tetapi aset berwujud lainnya. - -Token blockchain adalah aset digital yang dapat diverifikasi dan dimiliki oleh pengguna blockchain. Token Blockchain diatur oleh seperangkat aturan yang ditentukan oleh blockchain itu sendiri (dalam kasus token asli) atau oleh kontrak pintar pada blockchain. Aturan dapat bervariasi tergantung pada sifat dan penggunaan token. - -Token pada blockchain terbagi dalam dua kategori umum, tergantung pada propertinya: [sepadan][] atau [tidak-sepadan][]. Bagian berikut membahas properti dari kedua jenis token, dan memberikan informasi tentang penerapan kedua jenis token di Stacks. - -## Fungible tokens - -Properti inti dari token apa pun di blockchain adalah fungibilitas. Token yang sepadan adalah token yang dapat saling dipertukarkan atau mampu saling menggantikan. Dengan kata lain, satu kuantitas atau bagian dari token yang sepadan dapat diganti dengan jumlah yang sama atau bagian dari token yang sepadan yang sama. Token yang sepadan sering digunakan untuk merepresentasikan dunia nyata yang sepadan seperti mata uang. Token STX adalah contoh dari token yang sepadan. Contoh lain termasuk stablecoin, token yang mewakili hak suara dalam DAO, atau token yang secara algoritma melacak harga saham. - -Token yang sepadan membentuk salah satu proposisi nilai terpenting untuk teknologi blockchain, kemampuan untuk menyimpan nilai dan menukar nilai tersebut melalui transaksi internal dan eksternal. Karena token yang sepadan dapat dibagi menjadi bagian-bagian yang lebih kecil dan digabungkan kembali menjadi representasi nilai yang sama, mereka melayani utilitas yang hebat untuk mentransfer nilai antara pengguna blockchain. - -Token utama yang sepadan pada blockchain Stacks adalah token asli, STX. Because the Stacks blockchain allows for the creation of \[smart contracts\]\[\], other fungible tokens can be created on the Stacks blockchain as well. [SIP-010][] specifies the standard for fungible tokens on the Stacks blockchain. Spesifikasi ini mendefinisikan fungsi dan sifat yang _harus_ dimiliki oleh token yang sepadan pada Stacks. Dengan mematuhi standar ini, token yang sepadan pada Stacks dapat dengan mudah direpresentasikan oleh wallet yang mendukung Stacks. - -### Memahami standar token yang sepadan - -The [SIP-010][] standard is an interface definition that allows Stacks applications and wallets to interact with fungible tokens in a standard way. Mendukung standar mengurangi kompleksitas pembuat token untuk memasukkan token mereka ke dalam ekosistem. Under the [SIP-010][] standard, fungible tokens must have the following characteristics: - -- Kemampuan untuk mentransfer sejumlah token tertentu ke penerima (`transfer`). Penerima harus menjadi prinsipal Stacks. -- Kemampuan untuk mendapatkan nama token yang dapat dibaca oleh manusia (`get-name`). -- Kemampuan untuk mendapatkan nama pendek (simbol ticker) untuk token (`get-symbol`). -- Kemampuan untuk mendapatkan jumlah desimal dalam representasi token (`get-decimals`). Ini digunakan untuk membangun representasi token yang biasa dihadapi oleh seseorang. Misalnya, dolar AS memiliki 2 desimal, jika satuan dasarnya adalah sen. -- Kemampuan untuk mendapatkan saldo token untuk prinsipal Stacks tertentu (`get-balance-of`). -- Kemampuan untuk mendapatkan total pasokan token (`get-total-supply`). -- URI ke metadata yang terkait dengan token (`get-token-uri`). Ini dapat menyelesaikan metadata luar-rantai tentang token atau kontrak, seperti ikon gambar untuk token atau deskripsi. - -## Non-fungible tokens (NFT) - -Non-fungible tokens (NFT) adalah jenis token yang tidak dapat dipertukarkan. NFT memiliki sifat unik (biasanya dalam bentuk metadata lampiran) yang membatasi kemampuan untuk menggantinya dengan token yang identik. NFT adalah token yang unik, seperti karya seni, atau hak kepemilikan atas aset nyata seperti rumah. - -NFT sendiri tidak memiliki nilai bawaan, seperti mata uang. Nilai NFT berasal dari aset yang direpresentasikan oleh NFT. Penggunaan NFT sangat banyak, termasuk seni digital, koleksi, nama domain, dan representasi kepemilikan hak konten. NFT dapat digunakan sebagai sertifikat digital yang melacak keaslian barang nyata, atau mendigitalkan hak kepemilikan atas properti. - -As with fungible tokens, NFTs on the Stacks blockchain are created with smart contracts. [SIP-009][] specifies the standard for NFTs on the Stacks blockchain. Spesifikasi ini mendefinisikan fungsi dan sifat yang _harus_ dimiliki, tetapi sebagian besar NFT memiliki lebih banyak fungsi atau sifat yang dilampirkan daripada yang hanya dijelaskan oleh spesifikasi. Dengan mematuhi standar ini, token yang tidak sepadan pada Stacks dapat dengan mudah direpresentasikan oleh wallet yang mendukung Stacks. - -### Memahami standar token yang tidak sepadan - -The [SIP-009][] standard is an interface definition that the Stacks ecosystem aligned on. Dengan dukungan untuk standar ini di seluruh dompet dan alat, akan menjadi makin mudah untuk berinteraksi dengan NFT. Under the [SIP-009][] standard, NFT contract must have the following characteristics: - -- Kemampuan untuk mendapatkan pengidentifikasi token terakhir (`get-last-token-id`). Id ini merepresentasikan batas atas NFT yang dikeluarkan oleh kontrak. -- URI ke metadata yang terkait dengan pengidentifikasi token tertentu. (`get-token-uri`). URI ini dapat diselesaikan menjadi file JSON dengan informasi tentang pembuatnya, file media terkait, deskripsi, tanda tangan, dan banyak lagi. -- Kemampuan untuk memverifikasi pemilik untuk pengidentifikasi token yang diberikan (`get-owner`). The owner resolves to a [Stacks principal](principals). -- Kemampuan untuk mentransfer NFT ke penerima (`transfer`). Penerima harus menjadi prinsipal Stacks. - -## Bacaan lebih lanjut - -- [Perbedaan Antara Token Fungible dan Non-Fungible](https://101blockchains.com/fungible-vs-non-fungible-tokens/) -- [Jelaskan Seperti Saya 5: NFT](https://messari.io/article/explain-it-like-i-am-5-nfts) - -[sepadan]: #fungible-tokens -[tidak-sepadan]: #non-fungible-tokens-nfts -[SIP-010]: https://github.com/stacksgov/sips/blob/main/sips/sip-010/sip-010-fungible-token-standard.md -[SIP-009]: https://github.com/stacksgov/sips/blob/main/sips/sip-009/sip-009-nft-standard.md diff --git a/i18n/id/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md b/i18n/id/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md deleted file mode 100644 index 6414717ed5..0000000000 --- a/i18n/id/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md +++ /dev/null @@ -1,301 +0,0 @@ ---- -title: Nilai Clarity -description: Pelajari cara menangani Nilai Clarity dalam JavaScript -sidebar_position: 2 ---- - -## Pengantar - -The Clarity language makes use of a strong static type system. Ini berarti bahwa setiap fungsi yang didefinisikan dalam Clarity mengharapkan argumen dari tipe tertentu, dan bahwa kegagalan untuk memberikan argumen yang diketik dengan benar akan mengakibatkan kode Anda gagal dikompilasi, atau transaksi panggilan kontrak Anda gagal sebelum dijalankan. - -Untuk membangun aplikasi web yang berinteraksi dengan kontrak Clarity, Anda perlu mempelajari cara membuat dan menggunakan objek `ClarityValue`. Pustaka [@stacks/transactions](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) mempermudah semua, seperti yang akan kami tunjukkan di bawah ini. - -## Tipe Clarity - -Please see the following page for information on [Clarity Types](../write-smart-contracts/clarity-language/language-types). - -## Membangun Nilai Clarity dan mengakses datanya - -Nilai Clarity dapat dibuat dengan fungsi yang disediakan oleh pustaka [@stacks/transactions](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions). Fungsi-fungsi ini hanya menampilkan objek javascript yang berisi nilai dan representasi numerik dari informasi jenis Clarity. Jenis Clarity dikodekan sebagai berikut: - -```typescript -export enum ClarityType { - Int = 0, - UInt = 1, - Buffer = 2, - BoolTrue = 3, - BoolFalse = 4, - PrincipalStandard = 5, - PrincipalContract = 6, - ResponseOk = 7, - ResponseErr = 8, - OptionalNone = 9, - OptionalSome = 10, - List = 11, - Tuple = 12, - StringASCII = 13, - StringUTF8 = 14, -} -``` - -Objek `ClarityValue` dapat diserialkan dan disertakan dalam transaksi yang berinteraksi dengan kontrak Clarity yang dipublikasikan. - -Berikut adalah contoh cara membangun setiap jenis nilai Clarity, dan cara mengakses datanya jika ada: - -### Boolean - -```typescript -const t = trueCV(); -// { type: ClarityType.BoolTrue } - -const f = falseCV(); -// { type: ClarityType.BoolFalse } -``` - -Nilai Clarity Boolean tidak berisi data yang mendasarinya. Mereka hanyalah objek dengan informasi `type`. - -### Nilai Opsi - -```typescript -const nothing: NoneCV = noneCV(); -// { type: ClarityType.OptionalNone } - -const something: SomeCV = someCV(trueCV()); -// { type: ClarityType.OptionalSome, value: { type: 4 } } -``` - -Nilai Clarity Opsional dapat berupa (tipe kosong yang tidak memiliki data), atau sesuatu (nilai yang dikemas). - -Jika Anda berurusan dengan fungsi atau fungsi kontrak yang mengembalikan `OptionalCV`, Anda harus selalu memeriksa jenisnya sebelum mencoba mengakses nilainya. - -```typescript -const maybeVal: OptionalCV = await callReadOnlyFunction(...); - -if (maybeVal.type === ClarityType.OptionalSome) { - console.log(maybeVal.value); -} else if (maybeVal.type === ClarityType.OptionalNone) { - // deal with `none` value -} -``` - -### Buffer - -```typescript -const buffer = Buffer.from('foo'); -const bufCV: BufferCV = bufferCV(buffer); -// { type: ClarityType.Buffer, buffer: } -``` - -### Bilangan bulat - -Clarity mendukung bilangan bulat dan bilangan bulat yang tidak ditandatangani. - -```typescript -const i: IntCV = intCV(-10); -// { type: ClarityType.Int, value: BN { ... } } - -const u: UIntCV = uintCV(10); -// { type: ClarityType.UInt, value: BN { ... } } -``` - -Int nilai Clarity menyimpan data dasarnya sebagai nilai `BigNum` dari pustaka [bn.js](https://github.com/indutny/bn.js/). - -Untuk menampilkan/mencetak nilai Clarity (u)int, gunakan metode `cvToString(val)`. - -Jika Anda ingin melakukan operasi aritmatika menggunakan nilai Clarity (u)int, Anda harus menggunakan metode dari api `BigNum` pada nilai `BigNum` yang mendasarinya, dan membangun nilai Clarity baru keluar dari hasil. Misalnya: - -```typescript -const x = intCV(1); -const y = intCV(2); - -x.value.add(y.value); -// 3 -``` - -### String - -```typescript -const ascii: StringAsciiCV = stringAsciiCV('hello world'); -// { type: ClarityType.StringASCII, data: 'hello world' } - -const utf8: StringUtf8CV = stringUtf8CV('hello 🌾'); -// { type: ClarityType.StringUTF8, data: 'hello 🌾' } -``` - -Clarity mendukung string ascii dan utf8. - -### Prinsipal - -```typescript -const address = 'SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B'; -const contractName = 'contract-name'; - -const spCV = standardPrincipalCV(address); -// { -// type: ClarityType.PrincipalStandard -// address: { -// type: StacksMessageType.Address, -// version: AddressVersion.MainnetSingleSig, -// hash160: "SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B" -// } -// } - -const cpCV = contractPrincipalCV(address, contractName); -// { -// type: ClarityType.PrincipalContract, -// contractName: { -// type: StacksMessageType.LengthPrefixedString, -// content: 'contract-name', -// lengthPrefixBytes: 1, -// maxLengthBytes: 128, -// }, -// address: { -// type: StacksMessageType.Address, -// version: AddressVersion.MainnetSingleSig, -// hash160: "SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B" -// } -// } -``` - -Kedua jenis nilai prinsipal Clarity berisi informasi `type` dan objek `address`. Prinsipal kontrak juga berisi `contractName`. - -### Nilai Respons - -```typescript -const errCV = responseErrorCV(trueCV()); -// { type: ResponseErr, value: { type: ClarityType.BoolTrue } } - -const okCV = responseOkCV(falseCV()); -// { type: ResponseOk, value: { type: ClarityType.BoolFalse } } -``` - -Nilai Clarity Respons akan memiliki jenis `ClarityType.ResponseOk` atau `ClarityType.ResponseErr`. Keduanya mengandung Nilai Clarity. Seringkali nilai ini akan menjadi kode kesalahan bilangan bulat jika responsnya adalah `Error`. - -### Tuple - -```typescript -const tupCV = tupleCV({ - a: intCV(1), - b: trueCV(), - c: falseCV(), -}); -// { -// type: ClarityType.Tuple, -// data: { -// a: { type: ClarityType.Int, value: BN { ... } }, -// b: { type: ClarityType.BoolTrue }, -// c: { type: ClarityType.BoolFalse }, -// } -// } - -console.log(tupCV.data['b']); -// { type: ClarityType.BoolTrue } -``` - -Tuple di Clarity diketik dan berisi bidang yang memiliki nama. Tuple di atas, misalnya, berisi tiga bidang dengan nama **a**, **b** dan **c**, dan jenis nilainya masing-masing adalah `Int`, `Boolean` dan `Boolean`. - -Tuple Clarity direpresentasikan dalam JavaScript sebagai objek dan data tuple dapat diakses oleh bidang `data`, tempat objek JS yang mendasarinya disimpan. - -### Daftar - -```typescript -const l = listCV([trueCV(), falseCV()]); -// { type: ClarityType.List, list: [{ type: ClarityType.BoolTrue }] } - -console.log(l.list[0]); -// { type: ClarityType.BoolTrue } -``` - -Daftar, dalam Clarity, bersifat homogen, artinya daftar tersebut hanya dapat berisi elemen bertipe tunggal (Clarity). Pastikan untuk menghindari membuat daftar yang memiliki elemen dari beberapa jenis. - -Data yang mendasari daftar Clarity dapat diakses melalui bidang `list`. - -## Menggunakan Nilai Clarity - -Sekarang setelah Anda mengetahui cara membuat _dan_ mendekonstruksi nilai Clarity, Anda dapat menggunakannya untuk membuat transaksi `contract-call` yang memanggil fungsi kontrak pintar, dan Anda dapat memanfaatkan respons dari mereka. - -This is covered in depth [here](../understand-stacks/transactions#construction). - -## Memanfaatkan Nilai Clarity dari Respons Transaksi - -`Read-only` Fungsi Clarity dapat mengembalikan nilai Clarity sebagai respons. Fungsi `read-only` ini dapat diakses dengan mudah di JavaScript melalui [`callReadOnlyFunction()`](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions#calling-read -only-contract-function) fungsi yang disertakan dalam `@stacks/transactions`, yang mengembalikan `ClarityValue`. - -Seperti disebutkan di atas, `ClarityValues` hanyalah objek javascript yang berisi nilai dan informasi jenis Clarity yang terkait. Jenis objek ini ditentukan [di sini](https://github.com/hirosystems/stacks.js/tree/1f2b5fd8bdf1c2b5866e8171163594d7708a8c7a/packages/transactions/src/clarity/types). - -Ketika Anda memanggil fungsi kontrak `read-only`, Anda akan selalu tahu jenis fungsi yang akan dikembalikan, karena fungsi di Clarity diketik dengan kuat. - -Fungsi Clarity biasanya mengembalikan nilai yang dikemas dengan `Response`, untuk menunjukkan apakah berhasil atau ada kesalahan. - -Karena setiap `ClarityValue` memiliki bidang `type`, jenis hasil dari panggilan fungsi `read-only` dapat diperiksa dan ditindaklanjuti seperti di bawah ini: - -```typescript -const contractAddress = 'ST3KC0MTNW34S1ZXD36JYKFD3JJMWA01M55DSJ4JE'; -const contractName = 'kv-store'; -const functionName = 'get-value'; -const buffer = bufferCVFromString('foo'); -const network = new StacksTestnet(); // for mainnet, use `StacksMainnet()` -const senderAddress = 'ST2F4BK4GZH6YFBNHYDDGN4T1RKBA7DA1BJZPJEJJ'; - -const options = { - contractAddress, - contractName, - functionName, - functionArgs: [buffer], - network, - senderAddress, -}; - -// make a read-only call to a contract function that -// returns a Response -const result: ResponseCV = await callReadOnlyFunction(options); - -if (result.type === ClarityType.ResponseOk) { - console.log(cvToString(result.value)); -} else if (result.type === ClarityType.ResponseErr) { - throw new Error(`kv-store contract error: ${result.value.data}`); -} -``` - -### Nilai Clarity ke/dari Hex - -Jika Anda menerima respons dari transaksi dalam bentuk string `hex`, Anda dapat melakukan deserialize menjadi nilai Clarity seperti berikut: - -```javascript -import { hexToCV } from '@stacks/transactions'; - -let cv = hexToCV('hex_string'); -``` - -Demikian pula, Anda dapat mengkonversi nilai Clarity menjadi string `hex` seperti: - -```javascript -import { cvToHex, trueCV } from '@stacks/transactions'; - -let trueHex = cvToHex(trueCV()); -``` - -## Mendebug Nilai Clarity - -Terkadang Anda mungkin menerima nilai Clarity yang tidak Anda harapkan. Mencatat nilai ke konsol Anda tidak akan selalu terbukti bermanfaat, kecuali Anda telah mengingat nilai enum tipe nilai Clarity. - -Untuk mengetahui jenis nilai yang Anda hadapi, Anda dapat menggunakan fungsi `cvToString()` untuk mengonversi nilai Clarity menjadi string yang lebih mudah dibaca. - -Misalnya, memanggil `cvToString()` pada `tuple` besar kemungkinan akan menghasilkan sesuatu seperti: - -``` -(tuple - (a -1) - (b u1) - (c 0x74657374) - (d true) - (e (some true)) - (f none) - (g SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B) - (h SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B.test) - (i (ok true)) - (j (err false)) - (k (list true false)) - (l (tuple (a true) (b false))) - (m "hello world") - (n u"hello \u{1234}"))` -``` diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/blockchain/index.md b/i18n/ja/docusaurus-plugin-content-docs/current/blockchain/index.md deleted file mode 100644 index 13db24ec30..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/blockchain/index.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: Blockchain -description: Stacks Blockchain -sidebar_position: 6 ---- - -Below is a guide to start working locally with the Stacks Blockchain. - -Code repository is [here](https://github.com/stacks-network/stacks-blockchain). - -## Getting started with the Stacks Blockchain - -### Download and build stacks-blockchain - -The first step is to ensure that you have Rust and the support software installed. - -```bash -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -``` - -:::info -For building on Windows, follow the rustup installer instructions at https://rustup.rs/ -::: - -From there, you can clone the Stacks Blockchain repository: - -```bash -git clone --depth=1 https://github.com/stacks-network/stacks-blockchain.git - -cd stacks-blockchain -``` - -Then build the project: - -```bash -cargo build -``` - -Run the tests: - -```bash -cargo test testnet -- --test-threads=1 -``` - -### Encode and sign transactions - -Here, we have generated a keypair that will be used for signing the upcoming transactions: - -```bash -cargo run --bin blockstack-cli generate-sk --testnet - -# Output -# { -# secretKey: "b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001", -# publicKey: "02781d2d3a545afdb7f6013a8241b9e400475397516a0d0f76863c6742210539b5", -# stacksAddress: "ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH" -# } -``` - -This keypair is already registered in the `testnet-follower-conf.toml` file, so it can be used as presented here. - -We will interact with the following simple contract `kv-store`. In our examples, we will assume this contract is saved to `./kv-store.clar`: - -```scheme -(define-map store { key: (string-ascii 32) } { value: (string-ascii 32) }) - -(define-public (get-value (key (string-ascii 32))) - (match (map-get? store { key: key }) - entry (ok (get value entry)) - (err 0))) - -(define-public (set-value (key (string-ascii 32)) (value (string-ascii 32))) - (begin - (map-set store { key: key } { value: value }) - (ok true))) -``` - -We want to publish this contract on chain, then issue some transactions that interact with it by setting some keys and getting some values, so we can observe read and writes. - -Our first step is to generate and sign, using your private key, the transaction that will publish the contract `kv-store`. To do that, we will use the subcommand `blockstack-cli` that has the following usage: - -```bash -blockstack-cli (options) publish [publisher-secret-key-hex] [fee-rate] [nonce] [contract-name] [file-name.clar] -``` - -With the following arguments: - -```bash -cargo run --bin blockstack-cli publish b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 515 0 kv-store ./kv-store.clar --testnet -``` - -The `515` is the transaction fee, denominated in microSTX. Right now, the testnet requires one microSTX per byte minimum, and this transaction should be less than 515 bytes. The third argument `0` is a nonce, that must be increased monotonically with each new transaction. - -This command will output the **binary format** of the transaction. In our case, we want to pipe this output and dump it to a file that will be used later in this tutorial. - -```bash -cargo run --bin blockstack-cli publish b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 515 0 kv-store ./kv-store.clar --testnet | xxd -r -p > tx1.bin -``` - -### Run the testnet - -You can observe the state machine in action locally by running: - -```bash -cargo stacks-node start --config=./testnet/stacks-node/conf/testnet-follower-conf.toml -``` - -`testnet-follower-conf.toml` is a configuration file that you can use for setting genesis balances or configuring Event observers. You can grant an address an initial account balance by adding the following entries: - -``` -[[ustx_balance]] -address = "ST2VHM28V9E5QCRD6C73215KAPSBKQGPWTEE5CMQT" -amount = 100000000 -``` - -The `address` field is the Stacks testnet address, and the `amount` field is the number of microSTX to grant to it in the genesis block. The addresses of the private keys used in the tutorial below are already added. - -### Publish your contract - -Assuming that the testnet is running, we can publish our `kv-store` contract. - -In another terminal (or file explorer), you can move the `tx1.bin` generated earlier, to the mempool: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx1.bin http://localhost:20443/v2/transactions -``` - -In the terminal window running the testnet, you can observe the state machine's reactions. - -### Reading from / Writing to the contract - -Now that our contract has been published on chain, let's try to submit some read / write transactions. We will start by trying to read the value associated with the key `foo`. - -To do that, we will use the subcommand: - -```bash -cargo run --bin blockstack-cli contract-call --help -``` - -With the following arguments: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 1 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store get-value -e \"foo\" --testnet | xxd -r -p > tx2.bin -``` - -`contract-call` generates and signs a contract-call transaction. - -We can submit the transaction by moving it to the mempool path: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx2.bin http://localhost:20443/v2/transactions -``` - -Similarly, we can generate a transaction that would be setting the key `foo` to the value `bar`: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 2 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store set-value -e \"foo\" -e \"bar\" --testnet | xxd -r -p > tx3.bin -``` - -And submit it by moving it to the mempool path: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx3.bin http://localhost:20443/v2/transactions -``` - -Finally, we can issue a third transaction, reading the key `foo` again, for ensuring that the previous transaction has successfully updated the state machine: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 3 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store get-value -e \"foo\" --testnet | xxd -r -p > tx4.bin -``` - -And submit this last transaction by moving it to the mempool path: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx4.bin http://localhost:20443/v2/transactions -``` - -Congratulations, you can now [write your own smart contracts with Clarity](write-smart-contracts/). diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/blockchain/networks.md b/i18n/ja/docusaurus-plugin-content-docs/current/blockchain/networks.md deleted file mode 100644 index fe9725352c..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/blockchain/networks.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Stacks Blockchain Networks -description: Stacks Blockchain Networks -sidebar_position: 3 ---- - -### Stacks Blockchain Networks - -- [x] **Krypton** is a Stacks 2 testnet with a fixed, two-minute block time, called `regtest`. Regtest is generally unstable for regular use, and is reset often. See the [regtest documentation](understand-stacks/testnet) for more information on using regtest. - -- [x] **Testnet** (old Xenon) is the Stacks 2 public testnet, which runs PoX against the Bitcoin testnet. It is the full implementation of the Stacks 2 blockchain, and should be considered a stable testnet for developing Clarity smart contracts. See the [testnet documentation](understand-stacks/testnet) for more information on the public testnet. - -- [x] **Mainnet** is the fully functional Stacks 2 blockchain, see the [Stacks overview](understand-stacks/) for information on running a Stacks node, mining, stacking, and writing Clarity smart contracts. diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md b/i18n/ja/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md deleted file mode 100644 index cf4f84a2da..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Stacks Blockchain API -description: Interacting with the Stacks 2.0 Blockchain via API -sidebar_position: 4 ---- - -## Introduction - -:::tip API Documentation Official API Documentation is available [here](https://stacks-network.github.io/stacks-blockchain/). ::: - - -The Stacks 2.0 Blockchain API allows you to query the Stacks 2.0 blockchain and interact with smart contracts. It was built to maintain pageable materialized views of the Stacks 2.0 Blockchain. - -:::caution The RESTful API is developed by Hiro. Hiro also hosts a public API node for easy onboarding. Using it requires you to trust the hosted server, but provides a faster onboarding experience. You can [run your own API server](https://docs.hiro.so/get-started/running-api-node) ::: - -The RESTful JSON API can be used without any authorization. The basepath for the API is: - -```bash -# for mainnet, replace `testnet` with `mainnet` -https://stacks-node-api.testnet.stacks.co/ -``` - -:::note This documentation only covers endpoints that are exposed on a Stacks node, referred to as the RPC API. For full documentation on the RESTful API, check out the [Hiro's API reference](https://docs.hiro.so/api). ::: - -### Stacks Node RPC API - -The [stacks-node implementation](https://github.com/stacks-network/stacks-blockchain/) exposes JSON RPC endpoints. - -All `/v2/` routes a proxied to a Hiro-hosted Stacks Node. For a trustless architecture, you should make these requests to a self-hosted node. - -## Proxied Stacks Node RPC API endpoints - -The Stacks 2.0 Blockchain API is centrally hosted. However, every running Stacks node exposes an RPC API, which allows you to interact with the underlying blockchain. Instead of using a centrally hosted API, you can directly access the RPC API of a locally hosted Node. - -:::tip -The Stacks Blockchain API proxies to Node RPC endpoints -::: - -While the Node RPC API doesn't give the same functionality as the hosted Stacks 2.0 Blockchain API, you get similar functionality in a way that is scoped to that specific node. The RPC API includes the following endpoints: - -- [POST /v2/transactions](https://docs.hiro.so/api#operation/post_core_node_transactions) -- [GET /v2/contracts/interface/{contract_address}/{contract_name}](https://docs.hiro.so/api#operation/get_contract_interface) -- [POST /v2/map_entry/{contract_address}/{contract_name}/{map_name}](https://docs.hiro.so/api#operation/get_contract_data_map_entry) -- [GET /v2/contracts/source/{contract_address}/{contract_name}](https://docs.hiro.so/api#operation/get_contract_source) -- [GET /v2/accounts/{principal}](https://docs.hiro.so/api#operation/get_account_info) -- [POST /v2/contracts/call-read/{contract_address}/{contract_name}/{function_name}](https://docs.hiro.so/api#operation/call_read_only_function) -- [GET /v2/fees/transfer](https://docs.hiro.so/api#operation/get_fee_transfer) -- [GET /v2/info](https://docs.hiro.so/api#operation/get_core_api_info) - -:::caution If you run a local node, it exposes an HTTP server on port `20443`. The info endpoint would be `localhost:20443/v2/info`. ::: diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md b/i18n/ja/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md deleted file mode 100644 index 71e3542302..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Stacks Releases -description: Stacks Blockchain Releases -sidebar_position: 2 ---- - -:::info -This page needs contributions. Help us improve it. -::: - -### Stacks Blockchain Releases - -All releases are published [here](https://github.com/stacks-network/stacks-blockchain/releases). Most important ones are described below. - -### Stacks 2.1 - -Scheduled for release at the end of 2022. - -More information on [what to expect with Stacks 2.1](https://stacks.org/stacks-21-what-to-expect). - -#### Stacks 2.05 -Activated on [Bitcoin block 713000](https://explorer.stacks.co/txid/0xece8e369310b5ff9b92ef11181ae0d2457ac0c821376d4a96c4998763e22ad04?chain=mainnet). - -This breaking change enables storage cost for list to be based on actual length and change in number of indexed I/O operations. More info on this [blog post](https://www.stacks.org/stacks-2-05?ref=docs-website). - -#### Stacks 2.0 -Activated on January 14th 2021 - -This hard fork enables Stacking, Clarity smart contracts, scalable transactions, and also building directly on Bitcoin. More info [here](https://forum.stacks.org/t/path-to-mainnet-for-stx-holders-things-to-know-ahead-of-stacks-2-0/11529). - -#### Stacks Genesis -Released on 2018, October 30th UTC+6 at Bitcoin block height 547921 - -This hard fork addresses registration of digital assets with Stacks token and also distribution of Stacks token to the existing purchasers. More info [here](https://blog.blockstack.org/the-launch-of-the-stacks-genesis-block/?ref=docs-website). - diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md b/i18n/ja/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md deleted file mode 100644 index 25ec969824..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Deploy tips -description: Learn some common methods for deploying your application. ---- - -## Introduction - -Stacks applications are web applications that authenticate users with Stacks Auth and store data with Gaia. Both of these technologies can be accessed on the client side. As such, Stacks apps tend to be simple in design and operation, since in many cases, they don’t have to host anything besides the application’s assets. - -## Where to deploy your application - -Before users can interact with your application, you must deploy it on a server that is accessible over the internet. Deploying requires that you: - -- Configure or customize the files in the `public` directory. -- Build your application site for deployment. -- Copy your generated application files to your production server. - -If you first populated your application with the Stacks application generator, your application contains the starting blocks for configuring, building, and deploying your app. For example, the React template builds out a scaffolding with the following building blocks. - -| File or Directory | Description | -| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| node_modules/react-scripts | A set of scripts for that helps you kick off React projects without configuring, so you do not have to set up your project by yourself. | -| package.json | Contains a scripts section that includes a reference to the react-scripts, which are a dependency. This script creates a build directory containing your files for deployment. | -| public/favicon.ico | An example shortcut icon. | -| public/index.html | An entry page for an application. | -| public/manifest.json | A JSON file that describes your web application to the browser. | -| cors | Contains example deployment files for cross-origin request configuration. | - -If you use the generator to build JavasScript or Vue scaffolding, your project configuration files will be different. - -Regardless of which scaffolding you use, you must customize and extend this basic scaffolding as needed by your application. For example, you may want to add more properties to the `manifest.json` file. Since every application is different, Stacks Auth cannot give you specific instructions on how to do this. The steps you take are specific to your application. - -## Stacks Authentication and deployment - -When your application authenticates users with Stacks, the Stacks Wallet at on URL requests a resource (the app manifest) from your DApp. A request for a resource outside of the origin (the Stacks Wallet) 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 (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) - -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 Stacks 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`: - -```html -Access-Control-Allow-Origin: * Access-Control-Allow-Headers: "X-Requested-With, Content-Type, -Origin, Authorization, Accept, Client-Security-Token, Accept-Encoding" Access-Control-Allow-Methods: -"POST, GET, OPTIONS, DELETE, PUT" -``` - -Consult the documentation for your hosting service to learn how to configure CORS on that service. - -## Deployment and Radiks - -If you are deploying a Stacks application that uses [Radiks](https://github.com/stacks-network/radiks), your deployment includes a server and a database component. You must take this into account when deploying your application. You may want to choose a service such as [Heroku](https://www.heroku.com) or [Digital Ocean](https://www.digitalocean.com) if your app uses Radiks. diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/build-apps/index.md b/i18n/ja/docusaurus-plugin-content-docs/current/build-apps/index.md deleted file mode 100644 index 23714cba5d..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/build-apps/index.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Build apps with Stacks -description: Authenticate users, sign transactions and store data with the Stacks blockchain -sidebar_position: 3 -sidebar_label: Build apps ---- - -## Introduction - -Apps built with the Stacks blockchain give users control over their digital identities, assets, and data. - -Unlike most cloud-based apps, they are "decentralized" since they don't depend on any centralized platform, server, or database to function. Rather, they use the Stacks blockchain to authenticate users and facilitate read and write requests for them without any single point of failure or trust. - -Stacks provides three main functions for building apps: - - - -- **Authentication**: Register and sign users in with identities on the Stacks blockchain -- **Transaction signing**: Prompt users to sign and broadcast transactions to the Stacks blockchain -- **Data storage**: Save and retrieve data for users with [Gaia](../gaia) - - -All three of these integrations can be used together to create powerful new user experiences that rival or exceed those of traditional apps—all while protecting your users' digital rights. - -While integration is possible for any type of app, most of the resources available here are for web developers experienced with JavaScript. See [Hiro developer docs](https://docs.hiro.so) for more information on the available app development libraries for Stacks. - -## [References](references) - -[Authentication](references/authentication) - -[BNS](references/bns) - -[Gaia](../gaia/) - diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md b/i18n/ja/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md deleted file mode 100644 index 727b4e2163..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: NoCodeClarity -description: Launch apps for the Stacks blockchain through no code platforms like Bubble. ---- - -## Introduction - -![](https://d1muf25xaso8hp.cloudfront.net/https%3A%2F%2Fs3.amazonaws.com%2Fappforest_uf%2Ff1653407713550x759333524803365600%2FLogo%2520of%2520NoCodeClarity.png?w=179&h=84&auto=compress&dpr=1&fit=max) - -[NoCodeClarity](https://nocodeclarity.com) allows people to create applications for the Stacks blockchain without coding. - -## Stacks Plug-In on bubble - -The [Stacks-No-Code-Plugin](https://bubble.io/plugin/the-stacks-plug-in-1645467277638x949839693014368300) released in May 2022 and it can easily be installed on Bubble with a few clicks allowing users to deploy applications with no coding knowledge. [Bubble](https://bubble.io/blog/explaining-bubble-to-investors/) is the first No Code platform that the Stacks plugin launched on. More platforms are in the roadmap of NoCodeClarity, founded by Christopher Perceptions and Sergio Gongora. The Stacks plugin was created through the support of the Stacks Foundation via a grant in January 2022 and NoCodeClarity was awarded a $100,000 grant in June 2022 to expand the roadmap. - -Additional [instructions](https://s3.amazonaws.com/appforest_uf/f1654202471526x991633667675927800/Instructions%20v2.docx.pdf) are also available. Tutorials and step by step guides will be released soon. - -The Stacks-No-Code-Plugin code is [publicly available on Github](https://github.com/nocodeclarity/Stacks-No-Code-Plugin). - -![](/img/bubble-stacks-plugin.png) - -## Demo page - -A demo page is available [here](https://test-stacks-plugin.bubbleapps.io/version-test). - -## NoCodeClarity videos - -NodeCodeClarity has their own [youtube channel](https://www.youtube.com/channel/UC9Ep0VQ-GQ-yDzt-wmIElRA). - -Videos: - -* [NoCodeClarity Setup](https://www.youtube.com/watch?v=WanXlpBGl0w) -* [NoCodeClarity - Part 1 of the plugin](https://www.youtube.com/watch?v=o6d3hrzNqVI&t=248s) -* [NoCodeClarity - Part 2 of the plugin](https://www.youtube.com/watch?v=0rzMdsrRg80) -* [Sneak Peek of the No Code Stacks Wallet Template](https://www.youtube.com/watch?v=Xe6Yv0rF6XM) \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md b/i18n/ja/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md deleted file mode 100644 index 86a8568663..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Authentication -description: Register and sign in users with identities on the Stacks blockchain ---- - -## Introduction - -This guide explains how authentication is performed on the Stacks blockchain. - -Authentication provides a way for users to identify themselves to an app while retaining complete control over their credentials and personal details. It can be integrated alone or used in conjunction with [transaction signing](https://docs.hiro.so/get-started/transactions#signature-and-verification) and [data storage](https://docs.stacks.co/build-apps/references/gaia), for which it is a prerequisite. - -Users who register for your app can subsequently authenticate to any other app with support for the [Blockchain Naming System](bns) and vice versa. - -## How it works - -The authentication flow with Stacks is similar to the typical client-server flow used by centralized sign in services (for example, OAuth). However, with Stacks the authentication flow happens entirely client-side. - -An app and authenticator, such as [the Stacks Wallet](https://www.hiro.so/wallet/install-web), communicate during the authentication flow by passing back and forth two tokens. The requesting app sends the authenticator an `authRequest` token. Once a user approves authentication, the authenticator responds to the app with an `authResponse` token. - -These tokens are are based on [a JSON Web Token (JWT) standard](https://tools.ietf.org/html/rfc7519) with additional support for the `secp256k1` curve used by Bitcoin and many other cryptocurrencies. They are passed via URL query strings. - -When a user chooses to authenticate an app, it sends the `authRequest` token to the authenticator via a URL query string with an equally named parameter: - -`https://wallet.hiro.so/...?authRequest=j902120cn829n1jnvoa...` - -When the authenticator receives the request, it generates an `authResponse` token for the app using an _ephemeral transit key_ . The ephemeral transit key is just used for the particular instance of the app, in this case, to sign the `authRequest`. - -The app stores the ephemeral transit key during request generation. The public portion of the transit key is passed in the `authRequest` token. The authenticator uses the public portion of the key to encrypt an _app private key_ which is returned via the `authResponse`. - -The authenticator generates the app private key from the user's _identity address private key_ and the app's domain. The app private key serves three functions: - -1. It is used to create credentials that give the app access to a storage bucket in the user's Gaia hub -2. It is used in the end-to-end encryption of files stored for the app in the user's Gaia storage. -3. It serves as a cryptographic secret that apps can use to perform other cryptographic functions. - -Finally, the app private key is deterministic, meaning that the same private key will always be generated for a given Stacks address and domain. - -The first two of these functions are particularly relevant to [data storage with Stacks.js](https://docs.stacks.co/docs/gaia). - -## Key pairs - -Authentication with Stacks makes extensive use of public key cryptography generally and ECDSA with the `secp256k1` curve in particular. - -The following sections describe the three public-private key pairs used, including how they're generated, where they're used and to whom private keys are disclosed. - -### Transit private key - -The transit private is an ephemeral key that is used to encrypt secrets that need to be passed from the authenticator to the app during the authentication process. It is randomly generated by the app at the beginning of the authentication response. - -The public key that corresponds to the transit private key is stored in a single element array in the `public_keys` key of the authentication request token. The authenticator encrypts secret data such as the app private key using this public key and sends it back to the app when the user signs in to the app. The transit private key signs the app authentication request. - -### Identity address private key - -The identity address private key is derived from the user's keychain phrase and is the private key of the Stacks username that the user chooses to use to sign in to the app. It is a secret owned by the user and never leaves the user's instance of the authenticator. - -This private key signs the authentication response token for an app to indicate that the user approves sign in to that app. - -### App private key - -The app private key is an app-specific private key that is generated from the user's identity address private key using the `domain_name` as input. - -The app private key is securely shared with the app on each authentication, encrypted by the authenticator with the transit public key. Because the transit key is only stored on the client side, this prevents a man-in-the-middle attack where a server or internet provider could potentially snoop on the app private key. diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/build-apps/references/bns.md b/i18n/ja/docusaurus-plugin-content-docs/current/build-apps/references/bns.md deleted file mode 100644 index 32b045dc83..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/build-apps/references/bns.md +++ /dev/null @@ -1,241 +0,0 @@ ---- -title: Blockchain Naming System -description: Binds Stacks usernames to off-chain state ---- - -Blockchain Naming System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of control. - -The Stacks V1 blockchain implemented BNS through first-order name operations. In Stacks V2, BNS is instead implemented through a smart-contract loaded during the genesis block. - -Names in BNS have three properties: - -- **Names are globally unique.** The protocol does not allow name collisions, and all well-behaved nodes resolve a given name to the same state. -- **Names are human-meaningful.** Each name is chosen by its creator. -- **Names are strongly owned.** Only the name's owner can change the state it resolves to. Specifically, a name is owned by one or more ECDSA private keys. - -The Stacks blockchain insures that each node's BNS view is synchronized to all of the other nodes in the world, so queries on one node will be the same on other nodes. Stacks blockchain nodes allow a name's owner to bind up to 40Kb of off-chain state to their name, which will be replicated to all other Stacks blockchain nodes via a P2P network. - -The biggest consequence for developers is that in BNS, reading name state is fast and cheap but writing name state is slow and expensive. This is because registering and modifying names requires one or more transactions to be sent to the underlying blockchain, and BNS nodes will not process them until they are sufficiently confirmed. Users and developers need to acquire and spend the requisite cryptocurrency (STX) to send BNS transactions. - -## Motivation behind naming systems - -We rely on naming systems in everyday life, and they play a critical role in many different applications. For example, when you look up a friend on social media, you are using the platform's naming system to resolve their name to their profile. When you look up a website, you are using the Domain Name Service to resolve the hostname to its host's IP address. When you check out a Git branch, you are using your Git client to resolve the branch name to a commit hash. When you look up someone's PGP key on a keyserver, you are resolving their key ID to their public key. - -What kinds of things do we want to be true about names? In BNS, names are globally unique, names are human-meaningful, and names are strongly owned. However, if you look at these examples, you'll see that each of them only guarantees _two_ of these properties. This limits how useful they can be. - -- In DNS and social media, names are globally unique and human-readable, but not strongly owned. The system operator has the final say as to what each names resolves to. - - - **Problem**: Clients must trust the system to make the right choice in what a given name resolves to. This includes trusting that no one but the system administrators can make these changes. - -- In Git, branch names are human-meaningful and strongly owned, but not globally unique. Two different Git nodes may resolve the same branch name to different unrelated repository states. - - - **Problem**: Since names can refer to conflicting state, developers have to figure out some other mechanism to resolve ambiguities. In Git's case, the user has to manually intervene. - -- In PGP, names are key IDs. They are are globally unique and cryptographically owned, but not human-readable. PGP key IDs are derived from the keys they reference. - - **Problem**: These names are difficult for most users to remember since they do not carry semantic information relating to their use in the system. - -BNS names have all three properties, and none of these problems. This makes it a powerful tool for building all kinds of network applications. With BNS, we can do the following and more: - -- Build domain name services where hostnames can't be hijacked. -- Build social media platforms where user names can't be stolen by phishers. -- Build version control systems where repository branches do not conflict. -- Build public-key infrastructure where it's easy for users to discover and remember each other's keys. - -## Organization of BNS - -BNS names are organized into a global name hierarchy. There are three different layers in this hierarchy related to naming: - -- **Namespaces**. These are the top-level names in the hierarchy. An analogy to BNS namespaces are DNS top-level domains. Existing BNS namespaces include `.id`, `.podcast`, and `.helloworld`. All other names belong to exactly one namespace. Anyone can create a namespace, but in order for the namespace to be persisted, it must be _launched_ so that anyone can register names in it. Namespaces are not owned by their creators. - -- **BNS names**. These are names whose records are stored directly on the blockchain. The ownership and state of these names are controlled by sending blockchain transactions. Example names include `verified.podcast` and `muneeb.id`. Anyone can create a BNS name, as long as the namespace that contains it exists already. - -- **BNS subdomains**. These are names whose records are stored off-chain, but are collectively anchored to the blockchain. The ownership and state for these names lives within the P2P network data. While BNS subdomains are owned by separate private keys, a BNS name owner must broadcast their subdomain state. Example subdomains include `jude.personal.id` and `podsaveamerica.verified.podcast`. Unlike BNS namespaces and names, the state of BNS subdomains is _not_ part of the blockchain consensus rules. - -A feature comparison matrix summarizing the similarities and differences between these name objects is presented below: - -| Feature | **Namespaces** | **BNS names** | **BNS Subdomains** | -| -------------------------------------- | -------------- | ------------- | ------------------ | -| Globally unique | X | X | X | -| Human-meaningful | X | X | X | -| Owned by a private key | | X | X | -| Anyone can create | X | X | [1] | -| Owner can update | | X | [1] | -| State hosted on-chain | X | X | | -| State hosted off-chain | | X | X | -| Behavior controlled by consensus rules | X | X | | -| May have an expiration date | | X | | - -[1] Requires the cooperation of a BNS name owner to broadcast its transactions - -## Namespaces - -Namespaces are the top-level naming objects in BNS. - -They control a few properties about the names within them: - -- How expensive they are to register -- How long they last before they have to be renewed -- Who (if anyone) receives the name registration fees -- Who is allowed to seed the namespace with its initial names. - -At the time of this writing, by far the largest BNS namespace is the `.id` namespace. Names in the `.id` namespace are meant for resolving user identities. Short names in `.id` are more expensive than long names, and have to be renewed by their owners every two years. Name registration fees are not paid to anyone in particular---they are instead sent to a "black hole" where they are rendered unspendable (the intention is to discourage ID squatters). - -Unlike DNS, _anyone_ can create a namespace and set its properties. Namespaces are created on a first-come first-serve basis, and once created, they last 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 (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`). - -Namespaces can be between 1 and 19 characters long, and are composed of the characters `a-z`, `0-9`, `-`, and `_`. - -## Subdomains - -BNS names are strongly owned because the owner of its private key can generate valid transactions that update its zone file hash and owner. However, this comes at the cost of requiring a name owner to pay for the underlying transaction in the blockchain. Moreover, this approach limits the rate of BNS name registrations and operations to the underlying blockchain's transaction bandwidth. - -BNS overcomes this with subdomains. A **BNS subdomain** is a type of BNS name whose state and owner are stored outside of the blockchain, but whose existence and operation history are anchored to the blockchain. Like their on-chain counterparts, subdomains are globally unique, strongly owned, and human-readable. BNS gives them their own name state and public keys. Unlike on-chain names, subdomains can be created and managed cheaply, because they are broadcast to the BNS network in batches. A single blockchain transaction can send up to 120 subdomain operations. - -This is achieved by storing subdomain records in the BNS name zone files. An on-chain name owner broadcasts subdomain operations by encoding them as `TXT` records within a DNS zone file. To broadcast the zone file, the name owner sets the new zone file hash with a `NAME_UPDATE` transaction and replicates the zone file. This, in turn, replicates all subdomain operations it contains, and anchors the set of subdomain operations to an on-chain transaction. The BNS node's consensus rules ensure that only valid subdomain operations from _valid_ `NAME_UPDATE` transactions will ever be stored. - -For example, the name `verified.podcast` once wrote the zone file hash `247121450ca0e9af45e85a82e61cd525cd7ba023`, which is the hash of the following zone file: - -```bash -$TTL 3600 -1yeardaily TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxeWVhcmRhaWx5CiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMXllYXJkYWlseS9oZWFkLmpzb24iCg==" -2dopequeens TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAyZG9wZXF1ZWVucwokVFRMIDM2MDAKX2h0dHAuX3RjcCBVUkkgMTAgMSAiaHR0cHM6Ly9waC5kb3Rwb2RjYXN0LmNvLzJkb3BlcXVlZW5zL2hlYWQuanNvbiIK" -10happier TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxMGhhcHBpZXIKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8xMGhhcHBpZXIvaGVhZC5qc29uIgo=" -31thoughts TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzMXRob3VnaHRzCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzF0aG91Z2h0cy9oZWFkLmpzb24iCg==" -359 TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzNTkKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8zNTkvaGVhZC5qc29uIgo=" -30for30 TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzMGZvcjMwCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzBmb3IzMC9oZWFkLmpzb24iCg==" -onea TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiBvbmVhCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vb25lYS9oZWFkLmpzb24iCg==" -10minuteteacher TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxMG1pbnV0ZXRlYWNoZXIKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8xMG1pbnV0ZXRlYWNoZXIvaGVhZC5qc29uIgo=" -36questionsthepodcastmusical TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzNnF1ZXN0aW9uc3RoZXBvZGNhc3RtdXNpY2FsCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzZxdWVzdGlvbnN0aGVwb2RjYXN0bXVzaWNhbC9oZWFkLmpzb24iCg==" -_http._tcp URI 10 1 "https://dotpodcast.co/" -``` - -Each `TXT` record in this zone file encodes a subdomain-creation. For example, `1yeardaily.verified.podcast` resolves to: - -```json -{ - "address": "1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH", - "blockchain": "bitcoin", - "last_txid": "d87a22ebab3455b7399bfef8a41791935f94bc97aee55967edd5a87f22cce339", - "status": "registered_subdomain", - "zonefile_hash": "e7acc97fd42c48ed94fd4d41f674eddbee5557e3", - "zonefile_txt": "$ORIGIN 1yeardaily\n$TTL 3600\n_http._tcp URI 10 1 \"https://ph.dotpodcast.co/1yeardaily/head.json\"\n" -} -``` - -This information was extracted from the `1yeardaily` `TXT` resource record in the zone file for `verified.podcast`. - -### Subdomain Lifecycle - -Note that `1yeardaily.verified.podcast` has a different public key hash (address) than `verified.podcast`. A BNS node will only process a subsequent subdomain operation on `1yeardaily.verified.podcast` if it includes a signature from this address's private key. `verified.podcast` cannot generate updates; only the owner of `1yeardaily.verified.podcast can do so`. - -The lifecycle of a subdomain and its operations is shown in Figure 2. - -``` - subdomain subdomain subdomain - creation update transfer -+----------------+ +----------------+ +----------------+ -| cicero | | cicero | | cicero | -| owner="1Et..." | signed | owner="1Et..." | signed | owner="1cJ..." | -| zf0="7e4..." |<--------| zf0="111..." |<--------| zf0="111..." |<---- ... -| seqn=0 | | seqn=1 | | seqn=2 | -| | | sig="xxxx" | | sig="xxxx" | -+----------------+ +----------------+ +----------------+ - | | | - | off-chain | | -~ ~ ~ ~ | ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~|~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ | ~ ~ ~ ~ ~ ~ ~ ... - | on-chain | | - V V (zone file hash ) V -+----------------+ +----------------+ +----------------+ -| res_publica.id | | jude.id | | res_publica.id | -| NAME_UPDATE |<--------| NAME_UPDATE |<--------| NAME_UPDATE |<---- ... -+----------------+ +----------------+ +----------------+ - blockchain blockchain blockchain - block block block - - -Figure 2: Subdomain lifetime with respect to on-chain name operations .A new -subdomain operation will only be accepted if it has a later "sequence=" number, -and a valid signature in "sig=" over the transaction body .The "sig=" field -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." -However, any on-chain name ("jude.id" in this case) can broadcast a subdomain -update for "cicero.res_publica.id." -``` - -Subdomain operations are ordered by sequence number, starting at 0. Each new subdomain operation must include: - -- The next sequence number -- The public key that hashes to the previous subdomain transaction's address -- A signature from the corresponding private key over the entire subdomain operation. - -If two correctly signed but conflicting subdomain operations are discovered (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 subdomain's operations will be able to determine the valid sequence of state-transitions it has undergone, and determine the current zone file and public key hash for the subdomain. - -### Subdomain Creation and Management - -Unlike an on-chain name, a subdomain owner needs an on-chain name owner's help to broadcast their subdomain operations. In particular: - -- A subdomain-creation transaction can only be processed by the owner of the on-chain name that shares its suffix. For example, only the owner of `res_publica.id` can broadcast subdomain-creation transactions for subdomain names ending in `.res_publica.id`. -- A subdomain-transfer transaction can only be broadcast by the owner of the on-chain name that created it. For example, the owner of `cicero.res_publica.id` needs the owner of `res_publica.id` to broadcast a subdomain-transfer transaction to change `cicero.res_publica.id`'s public key. -- In order to send a subdomain-creation or subdomain-transfer, all of an on-chain name owner's zone files must be present in the Atlas network. This lets the BNS node prove the _absence_ of any conflicting subdomain-creation and subdomain-transfer operations when processing new zone files. -- A subdomain update transaction can be broadcast by _any_ on-chain name owner, but the subdomain owner needs to find one who will cooperate. For example, the owner of `verified.podcast` can broadcast a subdomain-update transaction created by the owner of `cicero.res_publica.id`. - -That said, to create a subdomain, the subdomain owner generates a subdomain-creation operation for their desired name and gives it to the on-chain name owner. - -Once created, a subdomain owner can use any on-chain name owner to broadcast a subdomain-update operation. To do so, they generate and sign the requisite subdomain operation and give it to an on-chain name owner, who then packages it with other subdomain operations into a DNS zone file and broadcasts it to the network. - -If the subdomain owner wants to change the address of their subdomain, they need to sign a subdomain-transfer operation and give it to the on-chain name owner who created the subdomain. They then package it into a zone file and broadcast it. - -### Subdomain Registrars - -Because subdomain names are cheap, developers may be inclined to run subdomain registrars on behalf of their applications. For example, the name `personal.id` is used to register usernames without requiring them to spend any Bitcoin. - -We supply a reference implementation of a [BNS Subdomain Registrar](https://github.com/stacks-network/subdomain-registrar) to help developers broadcast subdomain operations. Users would still own their subdomain names; the registrar simply gives developers a convenient way for them to register and manage them in the context of a particular application. - -# BNS and DID Standards - -BNS names are compliant with the emerging [Decentralized Identity Foundation](http://identity.foundation) protocol specification for decentralized identifiers (DIDs). - -Each name in BNS has an associated DID. The DID format for BNS is: - -```bash - did:stack:v0:{address}-{index} -``` - -Where: - -- `{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 `did:stack:v0:1dARRtzHPAFRNE7Yup2Md9w18XEQAtLiV-0`, because the name `personal.id` was the first-ever name created by `1dARRtzHPAFRNE7Yup2Md9w18XEQAtLiV`. - -As another example, the DID for `jude.id` is `did:stack:v0:16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg-1`. Here, the address `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` had created one earlier name in history prior to this one (which happens to be `abcdefgh123456.id`). - -The purpose of a DID is to provide an eternal identifier for a public key. The public key may change, but the DID will not. - -Stacks Blockchain implements a DID method of its own in order to be compatible with other systems that use DIDs for public key resolution. In order for a DID to be resolvable, all of the following must be true for a name: - -- The name must exist -- The name's zone file hash must be the hash of a well-formed DNS zone file -- The DNS zone file must be present in the Stacks node's data. -- The DNS zone file must contain a `URI` resource record that points to a signed JSON Web Token -- The public key that signed the JSON Web Token (and is included with it) must hash to the address that owns the name - -Not all names will have DIDs that resolve to public keys. However, names created by standard tooling will have DIDs that do. - -A RESTful API is under development. - -## DID Encoding for Subdomains - -Every name and subdomain in BNS has a DID. The encoding is slightly different 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 (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 subdomains owned by a single private key, and version byte 50 for subdomains owned by a m-of-n set of private keys. That is, subdomain DID addresses start with `S` or `M`, respectively. - -The `{index}` field for a subdomain's DID is distinct from the `{index}` field for a BNS name's DID, even if the same created both names and subdomains. For example, the name `abcdefgh123456.id` has the DID `did:stack:v0:16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg-0`, because it was the first name created by `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg`. However, `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` _also_ created `jude.statism.id` as its first subdomain name. The DID for `jude.statism.id` is `did:stack:v0:SSXMcDiCZ7yFSQSUj7mWzmDcdwYhq97p2i-0`. Note that the address `SSXMcDiCZ7yFSQSUj7mWzmDcdwYhq97p2i` encodes the same public key hash as the address `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` (the only difference between these two strings is that the first is base58check-encoded with version byte 0, and the second is encoded with version byte 63). diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/build-apps/references/references.md b/i18n/ja/docusaurus-plugin-content-docs/current/build-apps/references/references.md deleted file mode 100644 index babe5e119a..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/build-apps/references/references.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: References -sidebar_label: References ---- - -[Authentication](./authentication) - -[Blockchain Naming System](./bns) - -[Hiro example apps](https://docs.hiro.so/example-apps) \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/contribute/docs.md b/i18n/ja/docusaurus-plugin-content-docs/current/contribute/docs.md deleted file mode 100644 index 77705451b8..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/contribute/docs.md +++ /dev/null @@ -1,207 +0,0 @@ ---- -title: Contribute to docs -description: Learn how this site is built, and how you can contribute to it. ---- - -## Introduction - -Thank you for your interest in contributing and helping make these docs as good as they can be. - -This docs site is built on the open source platform [Discosaurus 2](https://docusaurus.io/) and most of its content is written in Markdown files. All of the code for this site is free and open source, located at the [GitHub repository here](https://github.com/stacks-network/docs). - -:::tip Don't know what Markdown is? Want to learn? Here is a [helpful guide](https://guides.github.com/features/mastering-markdown/). - -Don't want to learn it? No need to. Write [in plain text an issue on Github](https://github.com/stacks-network/docs/issues/new?assignees=&labels=documentation&template=add-documentation.md&title=%5BAdd+docs%5D) ::: - -:::info You need a free [Github](https://www.github.com) account to add or edit any content. ::: - -To edit any page, just click on the *Edit this page* button at the bottom of each page and submit your changes online. - -To add new content, they are two different ways to do it, the [easy way](#easy-way) and the [advanced way](#advanced-way). - -## Easy way - -[**Simply click here and enter the text of the article you wish to add.**](https://github.com/stacks-network/docs/issues/new?assignees=&labels=documentation&template=add-documentation.md&title=%5BAdd+docs%5D) - -This will open up an issue on github using our template. -## Advanced way - -For more advanced changes you can follow the next steps. - -You can also test the site locally using this method. -### Steps - -1. Fork the [docs reposiroty](https://github.com/stacks-network/docs) by clicking on the *Fork* button in the upper right of the screen. -2. Clone your fork to your local machine with this command `git clone git@github.com:/docs.git stacks_docs` -3. Enter your project folder `cd stacks_docs` -4. Create a branch `git checkout -b feat/my-feature-branch`. -5. You can optionally preview your changes in real time with: - - `npm install` (to install dependencies). - - `npx docusaurus start` to start a local copy of the site. A web browser will open at http://localhost:3000, so you can see a preview of yourhanges in real time. -6. Make the changes you wish and then commit them with this kind of message: `git commit -am "feat: some new feature or content"`. -7. Push to to GitHub with `git push --set-upstream origin feature/my-feature-branch`. -8. Visit GitHub and make your pull request. - -## Aditional information -### Running and building the site locally (optional) - -You can start the page locally with the following command. This is enough to preview your changes. -```bash -npx docusaurus start -``` - -Before running this command for the first time you will need to run `npm install` to install dependencies. - -The docs site will be accessible at this url: [`http://localhost:3000`](http://localhost:3000). - - -After you finished your changes, you can also build the entire site with the following command (not usually needed): -```bash -npm run build -``` - -:::tip `npx docusaurus start` will only load the default language (english). To test all languages you can build with `npm run build` and then preview your build with `npm run serve`. ::: - -### An alternative: Working in browser - -As an alterative to working locally, you can also use the web IDE gitpod that provides an environment to contribute directly from within your browser. - -You only need to have a github account and open [this link](https://gitpod.io/#https://github.com/stacks-network/docs). - -### Folder structure of the site - -If you are interested in only adding new documentation content to the site, the files that will be important to you are located within `./docs/*`: - -```bash -docs/ - build-apps - contribute/ - faq/ - gaia/ - nodes-and-miners/ - noteworthy-contracts/ - references/ - understand-stack/ - write-smart-contracts/ -``` - -The routing for this site is file based, meaning if you created a folder within `/docs/gaia/` named `testing` and in it a file named `test1.md`, you would be able to navigate to `http://localhost:3000/gaia/testing/test1` and you would see whatever content is in that markdown file. - -All the docs in English are stored in the folder `/docs/`. - -To add new English content simply add a markdown file (.md) into any subfolder in docs, and it will be automatically displayed in the category of that folder. - -All the docs in other languages are stored under the folder `i18n`, but these files should never be edited using GitHub as they are overwritten by Crowdin every time new translations are added. **To make changes in other languages**, you must do so using Crowdin. Please refer to [translations](translations) instead. - -### Frontmatter - -Frontmatter is the top part of any markdown document that is written in a language called [YAML](https://yaml.org/). It looks like this: - -```yaml ---- -title: This is my page title -description: A short, concise sentence describing what is on this page ---- -``` - -Frontmatter gives us the ability to define some things within a page that the site can use, such as a page title or page description. When adding any new page, please include a `title` and `description`. - - - -### Use Conventional Commits - -We use the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) as and commits naming convention. Use it while contributing, please. - -### Code blocks - -To write a code block, you need to wrap your code in ` ```language `, and end your code block with ` ``` `. Here is an example of ` ```clarity `. - -```clarity -(define-data-var counter int 0) - -(define-public (get-counter) - (ok (var-get counter))) -``` -### Admonitions - -You can use the following admonitions to highlight content. - -```md -:::note -Some **content** with _markdown_ `syntax`. -::: - -:::tip -Some **content** with _markdown_ `syntax`. -::: - -:::info -Some **content** with _markdown_ `syntax`. -::: - -:::caution -Some **content** with _markdown_ `syntax`. -::: - -:::danger -Some **content** with _markdown_ `syntax`. -::: - -:::tip My personalized title -Some **content** with _markdown_ `syntax`. -::: -``` - -Which renders: - -:::note - -Some **content** with _markdown_ `syntax`. - -::: - -:::tip - -Some **content** with _markdown_ `syntax`. - -::: - -:::info - -Some **content** with _markdown_ `syntax`. - -::: - -:::caution - -Some **content** with _markdown_ `syntax`. - -::: - -:::danger - -Some **content** with _markdown_ `syntax`. - -::: - -:::tip My personalized title - -Some **content** with _markdown_ `syntax`. - -::: \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/contribute/index.md b/i18n/ja/docusaurus-plugin-content-docs/current/contribute/index.md deleted file mode 100644 index ac81d899bd..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/contribute/index.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Contribute -description: Contribute to the Stacks ecosystem. -sidebar_position: 10 -sidebar_label: "Contribute" ---- - -You can contribute to the Stacks ecosystem in multiple ways: - - - -### Documentation - -Contribute to the Stacks Docs on this website. More info [here](docs). - -### Translations - -Help us reach more people with translations. More details [here](translations). - - - -### Articles - -Write an article or a blog post about Stacks. A good place to start is [Stacks Forum](https://forum.stacks.org). - -### Github - -If you are familiar with Github they are multiple repositories of the Stack Ecosystem that you can contribute to. - -- https://github.com/stacks-network/ diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/contribute/translations.md b/i18n/ja/docusaurus-plugin-content-docs/current/contribute/translations.md deleted file mode 100644 index bd9a452333..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/contribute/translations.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Contribute with translations -description: Want to help tranlating these docs to your local language? ---- - -## Help with translations - -Translations are managed with Crowdin. -Anybody can colaborate and no technichal skills are required, as it's all done on the browser. - -To help with translation please go to [this page](https://crowdin.com/project/docsstacksco), click any language and start translating. - -All help is appreciated. - -:::caution -Please don't add any translations to the Github repository, as the translated pages get rewritten from Crowdin. Translations need to be added on Crodin intead. -::: - -### Common issues on translations - -When translating in Crowdin, please only translate the texts and not the html code. - -If you acccidently modify the html tags you will get errors like shown below (`Seems like some formating tags are missing` or `Translation contains tag that source text doesn't have`). These errors will prevent your translation getting published until the tags are left as they were in the original text. - -![](/img/crowdin-qa-issue-formatting_tags_missing.png) ![](/img/crowdin-qa-issue-tag_source.png) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/faq/faq.md b/i18n/ja/docusaurus-plugin-content-docs/current/faq/faq.md deleted file mode 100644 index dde584e583..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/faq/faq.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: General FAQs -description: Frequently Asked Questions -sidebar_label: "FAQ" -sidebar_position: 10 ---- - -![](/img/glasses.png) - -## Why is my transfer still pending? - -Commonly it's because your fee is too low or your [nonce](#what-is-nonce) is incorrect. - -More information can be found [here](https://www.hiro.so/wallet-faq/why-is-my-stacks-transaction-pending). There are also [best practices and known issues](https://forum.stacks.org/t/transactions-in-mempool-best-practices-and-known-issues/11659) and [diagnosing pending transactions](https://forum.stacks.org/t/diagnosing-pending-transactions/11908). - -There is also this [script](https://github.com/citycoins/scripts/blob/main/getnetworkstatus.js) to look at either the first 200 transactions or all the transactions in the mempool, to then return the maximum adn average fee values. We've noticed that using 1.5-2x the average fee in the mempool will generally get things processed within 6-10 blocks even during high congestion. - -There is also this [script](https://github.com/citycoins/scripts/blob/main/gettxstatus.js) to track a pending transaction until it reaches a final status. - -## What is Nonce? - -A nonce is used to make sure that every transaction goes in right order. Nonce starts at 0, so the very first transaction from an address should set to nonce=0. You can find the nonce of your wallet address by searching the address in any [Stacks blockchain explorer](https://explorer.stacks.co/). You can also user `$ stx balance
`. - -If you have a transaction nonce that is less than your account nonce, the transaction is unmineable and will (should) disappear after 256 blocks. This does not affect future transactions and therefore can be just ignored, they are in the past. - -If you have a transaction nonce that is equal to your account nonce, then that transaction is valid and should be the next in line to be processed next. - -If you have a transaction nonce that is higher than your account nonce, then there needs to be a chain of transactions starting with your account nonce in order for it to be processed. E.g. Your account nonce is 10 but the pending transaction has a nonce of 12. It will not be mineable until a transaction with nonces 10 and 11 are processed. - -## Whats a Replace-by-fee (RBF)? - -A replace-by-fee (RBF) transaction tells the blockchain that you would like to replace one transaction with another, while specifying a fee that is higher than the original transaction fee. A transaction can be replaced with **any other transaction**, and is not limited to the same operation. - -This can be used to effectively **cancel a transaction** by replacing it with something else, like a small STX transfer to another owned address. - -This can be used to **raise the fee for a pending transaction** so it is considered by miners during periods of high congestion. This can also be used to _resubmit_ a transaction, in the sense that the RBF transaction gets a new txid and gets considered again (or faster) by miners. E.g. I submit my transaction with 1 STX fee at block 54,123. By block 54,133 I see my tx hasn’t been picked up, so I RBF with 1.1 STX. Then wait 10 blocks again, and RBF again if not received. There’s a balance between doing this too often and keeping a consistent pace, but it has been seen to help get transactions through, especially when new ones are constantly flooding in. - -The replacement transaction needs to use the same nonce as the original transaction with a fee increase of at least 0.000001 STX. E.g. Your original transaction has a fee of 0.03 STX, the new RBF transaction must have a fee of 0.030001 STX or above. - -RBF transactions process in one of two ways: - -- If miners pick up the original transaction before the RBF transaction is received, then the original transaction is processed and the replacement transaction goes into an unmineable state. It will eventually disappear and doesn’t affect future transactions. -- If miners pick up the replaced transaction then the new transaction is processed instead of the original, and the status of the original transaction is set to “droppped_replaced_by_fee”. This status is not shown on the explorer but can be seen when querying the txid. - -Submitting multiple transactions for the same action can slow things down in a few ways. - -- If the total spent in 2 or 3 transactions is more than can be spent in a single transaction, the transactions appear unmineable. -- If the fees for multiple transactions exceed the STX balance, the transactions will be unmineable. - -## What are .btc domains? - -[This forum post](https://forum.stacks.org/t/btc-domains-are-live/12065) explains all the benefits of .btc domains. They can currently be purchased in [btc.us](https://btc.us/) - -## What is the blockchain trilemma? - -## Stacks vs. Solana vs. Polygon: How Do They Compare From a Developer Perspective? - -[This blog post answers the question](https://www.hiro.so/blog/stacks-vs-solana-vs-polygon-how-do-they-compare-from-a-developer-perspective). - -## What Does Lightning’s Taro Proposal Mean for Stacks? - -[This blog post answers the question](https://www.hiro.so/blog/what-does-lightnings-taro-proposal-mean-for-stacks). - - -## Is Stacks a [PoS chain](https://en.wikipedia.org/wiki/Proof_of_stake)?[¹][] - -No. - -The act of block production requires an extrinsic expenditure — it is not tied to owning the native token, as would be required in PoS. The only way to produce blocks in the Stacks chain is to transfer Bitcoin to a predetermined randomized list of Bitcoin addresses. Moreover, the Stacks blockchain can fork, and there exists a protocol to rank forks by quality independent of the set of miners and the tokens they hold. These two properties further distinguish it from PoS chains, which cannot fork due to the inability to identify a canonical fork without trusting a 3rd party to decree a particular fork as valid. The ability to fork allows the Stacks blockchain to survive failure modes that would crash a PoS chain. - -## Is Stacks a [sidechain](https://en.bitcoin.it/wiki/Sidechain)?[¹][] - -No. - -For two key reasons. - -First, the history of all Stacks blocks produced is recorded to Bitcoin. This means that the act of producing a private Stacks fork is at least as hard as reorging the Bitcoin chain. This in turn makes it so attacks on the chain that rely on creating private forks (such as selfish mining and double-spending) are much harder to carry out profitably, since all honest participants can see the attack coming before it happens and have a chance to apply countermeasures. Sidechains offer no such security benefit. - -Second, the Stacks blockchain has its own token; it does not represent pegged Bitcoin. This means that the safety of the canonical fork of the Stacks blockchain is underpinned by its entire token economy’s value, whereas the safety of a sidechain’s canonical fork is underpinned only by whatever system-specific measures incentivize its validators to produce blocks honestly, or the Bitcoin miners’ willingness to process peg-in requests (whichever is the weaker guarantee). - - -## Is Stacks a [layer-2 system](https://academy.binance.com/en/glossary/layer-2) for Bitcoin?[¹][] - -No. - -Stacks blockchain is a layer-1 blockchain, which uses a novel and unique mining protocol called proof-of-transfer (PoX). A PoX blockchain runs in parallel to another blockchain (Bitcoin in Stacks’ case), which it uses as a reliable broadcast medium for its block headers. It's a sovereign system in its own right. The Stacks blockchain state is distinct from Bitcoin, and is wholly maintained by and for Stacks nodes. Stacks transactions are separate from Bitcoin transactions. Layer-2 systems like Lightning are designed to help scale Bitcoin payment transactions, whereas Stacks is designed to bring new use-cases to Bitcoin through smart contracts. Stacks is not designed as a Bitcoin layer-2 scalability solution. - - -## Is Stacks a [merged-mined chain](https://en.bitcoin.it/wiki/Merged_mining_specification)?[¹][] - -No. - -The only block producers on the Stacks chain are Stacks miners. Bitcoin miners do not participate in Stacks block validation, and do not claim Stacks block rewards. Moreover, Stacks is not a [blind merged-mined chain](https://github.com/bitcoin/bips/blob/master/bip-0301.mediawiki), because STX block winners are public and randomly chosen (instead of highest-bid-wins), and its tokens are minted according to a schedule that is independent of the degree of miner commitment or Bitcoin transferred (instead of minted only by one-way pegs from Bitcoin). This ensures that Stacks is able to make forward progress without opt-in from Bitcoin miners, and it ensures that Stacks miners are adequately compensated for keeping the system alive regardless of transaction volume. - -## Whats the difference between Stacks and Ethereum?[²][] -**Computation and Storage** Stacks does all computation and storage outside of the blockchain, and uses the blockchain only as a “shared source of truth” between clients. By contrast, Ethereum does all computation and most application storage in the blockchain itself. Like Ethereum, if two Stacks nodes see the same underlying blockchain, they will independently run the same computations and produce the same state. Unlike Ethereum, there is no Stacks-specific blockchain. - -**Programming Language and Tooling** Stacks’s programming model is based on running off-chain programs. These programs can be written and debugged in any language you want. By contrast, Ethereum’s programming model is based on running on-chain “smart contracts.” These are written and debugged with a whole new set of tools, like Solidity and Serpent. - -**Scalability of On-chain Computation** Stacks is designed around a “virtual chain” concept, where nodes only need to reach consensus on the shared “virtual chain” they’re interested in. Virtual chains do not interact with one another, and a single blockchain can host many virtual chains. Although Stacks’s specific virtual chain is not Turing-complete (i.e. it’s a list of instructions to build the name database), it is possible to create Turing-complete virtual chains like Ethereum. These virtual chains can live in any blockchain for which there exists a driver, and virtual chain clients only need to execute their virtual chain transactions (i.e. Stacks only processes Stacks virtual chain transactions). - -By contrast, because smart contracts run on-chain and can call one another, all Ethereum nodes need to process all smart contracts’ computations in order to reach consensus. This can get expensive as the number of running smart contracts grow, which takes the form of gas fee increases. - -**Scalability of Off-chain Computation** Stacks applications are very similar to Web applications today and almost never need to interact with the blockchain. For most Stacks applications, the blockchain is only used to authenticate the application’s code and data before the user runs it. By contrast, Ethereum applications usually require an application-specific smart contract, and must interact with the blockchain to carry out its operations. - - -[¹]: https://stacks.org/stacks-blockchain -[²]: https://forum.stacks.org/t/what-is-the-difference-between-blockstack-and-ethereum/781 diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/gaia/configuration.md b/i18n/ja/docusaurus-plugin-content-docs/current/gaia/configuration.md deleted file mode 100644 index a6a530cd70..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/gaia/configuration.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Configuration -description: Configuring Gaia Hub ---- - -## Configuration files - -The following configuration files exist in the folder `deploy/configs/gaia/`: - -``` -admin-config.json -hub-config.json -reader-config.json -``` - -## GAIA Admin Service - -You can also use the GAIA Admin Service to remotely administer it with an API Key. It will require you to install `npm` with a `apt install npm`. Once `npm` is installed you can continue with the steps in the [GAIA Admin Service](https://github.com/stacks-network/gaia/blob/master/admin/README.md). - -## Driver Selection - -The Gaia hub currently supports the following drivers: - -``` -'aws' == Amazon S3 -'azure' == Azure Blob Storage -'disk' == Local disk -'google-cloud' === Google Cloud Storage -``` - -Set the driver you wish to use in your [config.json](https://github.com/stacks-network/gaia/blob/master/hub/config.sample.json) file with the `driver` parameter. Many drivers additionally accept the `bucket` parameter, which controls the bucket name that files should be written to. - -These driver may require you to provide additional credentials for performing writes to the backends. See `config.sample.json` for fields for those credentials. In some cases, the driver can use a system configured credential for the backend (e.g., if you are logged into your AWS CLI account, and run the hub from that environment, it won't need to read credentials from your `config.json`). - -_Note:_ The disk driver requires a \*nix like filesystem interface, and will not work correctly when trying to run in a Windows environment. ::: - -## Note on SSL - -We _strongly_ recommend that you deploy your Gaia hub with SSL enabled. Otherwise, the tokens used to authenticate with the Gaia hub may be stolen by attackers, which could allow them to execute writes on your behalf. -Configuration options are available to run the hub with an `https` Node.js server. -Otherwise, a reverse proxy web server such as nginx or Apache can be used. - -## Require Correct Hub URL - -If you turn on the `requireCorrectHubUrl` option in your `config.json` file, your Gaia hub will require that authentication requests correctly include the `hubURL` they are trying to connect with. This is used to prevent a malicious gaia hub from using an authentication token for itself on other Gaia hubs. - -By default, the Gaia hub will validate that the supplied URL matches `https://${config.serverName}`, but if there are multiple valid URLs for clients to reach the hub at, you can include a list in your `config.json`: - -```javascript -{ - .... - serverName: "normalserver.com" - validHubUrls: [ "https://specialserver.com/", - "https://legacyurl.info" ] - .... -} -``` - -## The readURL parameter - -By default, the gaia hub drivers will return read URLs which point directly at the written content. For example, an S3 driver would return the URL directly to the S3 file. However, if you configure a CDN or domain to point at that same bucket, you can use the `readURL` parameter to tell the gaia hub that files can be read from the given URL. For example, the `hub.blockstack.org` Gaia Hub is configured to return a read URL that looks like `https://gaia.blockstack.org/hub/`. - -Unset this configuration parameter if you do not intend to deploy any caching. - -## Minimum Proofs Requirement - -The gaia hub can also be configured to require a minimum number of social proofs in a user's profile to accept writes from that user. This can be used as a kind of spam-control mechanism. However, we recommend for the smoothest operation of your gaia hub, to set the `proofsConfig.proofsRequired` configuration key to `0`. - -## CDN & Replicated Hubs - -- https://docs.microsoft.com/en-us/azure/storage/blobs/storage-https-custom-domain-cdn - -- The hub implementation is designed to be ran from a single Node.js instance. If the hub instance is sharded (e.g. replicated hubs via load balancing), then any given `bucket` (identified by URI segment) must be served by the same instance, At least a couple elements of the Gaia Hub depend on this: token invalidation in-memory caching, and resource endpoint 409 contention behavior. diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md b/i18n/ja/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md deleted file mode 100644 index 558cbb14f5..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Deploy Gaia Hub -description: Steps and tutorials ---- - -## Deploy your GAIA hub - -Tutorials to deploy your own GAIA hub are currently available for [Linux](./setup-linux), [MacOS](./setup-mac) and [Amazon EC2 / CloudFormation](./gaia-on-ec2). - -Regardless of what server the Gaia Hub runs on, the storage it uses can currently be deployed on multiple platforms: - -- Local disk (the server itself) -- Amazon S3 -- Azure Blob Storage -- Google Cloud - -:::tip -Support for IPFS is under development. -::: \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md b/i18n/ja/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md deleted file mode 100644 index 2067e7d57c..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Amazon EC2 -description: Use a template to deploy a Gaia hub on Amazon EC2 -tags: - - tutorial - - gaia ---- - -## Introduction - -The template provided on this page provides an easy way to deploy a Gaia hub directly to Amazon EC2. You can use this template to deploy your own Gaia hub to your Amazon Web Services (AWS) account. Amazon EC2 is an affordable and convenient cloud computing provider. The template provides a one-click deploy for Amazon EC2 with either S3 or EBS as a storage provider. - -## Prerequisites - -This procedure uses Amazon CloudFormation to configure an EC2 cloud compute provider to run the Gaia hub service with an S3 or EBS provider for file storage. You should have access to an AWS account either through your personal account or through a corporate account. This account should have permissions to create resources. - -Additionally, you must also own a domain name and be able to update the DNS records associated with that domain name. - -## Setup steps - -### Step 1 - Create Stack - -Use a link in the table to launch the [CloudFormation](https://console.aws.amazon.com/cloudformation/) template in the AWS region that you wish to deploy a Gaia hub. - -![Create stack](/img/cloudformation-create-stack.png) - -### Step 2 - Setup stack using template - -You need to configure the template with the appropiate values for your hub and domain it runs on. - -Select `Template is ready` and `Amazon S3 URL` and enter the following Amazon S3 URL: -``` -https://s3-external-1.amazonaws.com/cf-templates-vzldibfi2mw8-us-east-1/2022160J6G-cloudformation.yaml -``` - -If you prefer you can instead select `Template is ready` and `Upload a template file` to upload the template file `cloudformation.yaml`. - -The latest `cloudformation.yaml` file can be downloaded [here](https://raw.githubusercontent.com/stacks-network/gaia/master/deploy/cloudformation.yaml). On most browsers you can right-click on that page and click on `Save page as` to download the file. Alternatively, you can copy/paste the text into a text file called `cloudformation.yaml`. - -Then click `Next`. - -![Specify template](/img/cloudformation-specify-template.png) - -### Step 3 - Specify stack details - -Specify the stack details and then click `Next`: ![Specify template](/img/cloudformation-specify-stack-details.png) - -| Field | Value | Notes | -| --------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Stack name | _a unique name in your AWS account_ | e.g.: my_gaia_hub | -| DomainName | _your-domain_ | | -| EmailAddress | _your email address_ | | -| GaiaBucketName | _S3 bucket name_ | The template combines this name with the stack name to create a unique S3 bucket. The template ignores this field if GaiaStorageType is set to `disk`. | -| GaiaStorageType | `s3` or `disk` | Select the GaiaStorageType of which to use as a backend for the Gaia Hub. Selecting `s3` causes the template to create an S3 bucket based on the name given in the previous field. Selecting `disk` causes the template to attach a separate EBS volume to the EC2 instance for Hub storage. | -| InstaceType | t2.micro | Select the instance type you want. Default value is `t2.micro`. | -| KeyName | | In the KeyName drop-down, select an [EC2 KeyPair](https://console.aws.amazon.com/ec2/v2/home?region=us-east-1#KeyPairs:) to enable SSH access to the EC2 instance. You should download the `.pem` keyfile for this pair from the EC2 console. For more information see the [EC2 key pair documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html#prepare-key-pair) | -| SSHLocation | 0.0.0.0/0 | Leave the SSHLocation field with the default value of `0.0.0.0/0` to enable SSH access from any IP address. If you wish to restrict SSH access to the EC2 instance to a certain IP, you can update this field. | -| SubnetId | _subnetid_ | Select a public subnet | -| VpcId | _vpcid_ | | - -### Step 4 - Configure stack options - -Configure any stack options that fit your desired setup and click `Next`. All these fields are optional. - -![Specify template](/img/cloudformation-stack-options.png) - -### Step 5 - Review - -Review the configuration of your Gaia hub, select the checkbox to acknowledge that AWS may create IAM resources with custom names and click on `Create stack`. - -![Specify template](/img/cloudformation-iam-resources.png) - -### Step 6 - Retrieve the public IP of your Gaia hub - -Your stack can take several minutes to launch. You can monitor the Events tab of your hub to review the current progress of the launch. When the launch is complete, the Outputs tab displays information about the hub. Select the PublicIP and copy it to configure your domain name. - -Create an `A` DNS record pointing to the given IP in your domain. - -Wait a few minutes for the DNS record to propagate, and your should be able to access your Gaia hub with SSH. - -## Accessing your Gaia hub with SSH - -To SSH into your Gaia hub EC2 host directly, you must have the keyfile used in container creation. Access the host with the following command in your terminal: - -```bash -ssh -i admin@ -``` - -:::tip If you can only access SSH with the IP but not with the DNS name and you wish to do so, you can optionally activate it by following these steps: - - Open your [AWS Console](https://console.aws.amazon.com) - Click on `Service` -> VPC - Open Your VPCs - Select your VPC connected to your Gaia Hub - Click `Actions` -> `Edit DNS Hostnames` -> Change `DNS hostnames` to `Enable` -::: -## Graphical representation of the cloudformation template - -![](/img/cloudformation-gaia-template1-designer.png) \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/gaia/gaia.md b/i18n/ja/docusaurus-plugin-content-docs/current/gaia/gaia.md deleted file mode 100644 index 1070857350..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/gaia/gaia.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Gaia -description: Decentralized storage architecture for off-chain data -sidebar_position: 5 -tags: - - gaia ---- - -## Introduction - -Apps built with the Stacks blockchain store off-chain data using a storage system called Gaia. - -Whereas public transactional metadata is best stored on the Stacks blockchain, user application data can often be stored more efficiently and privately in Gaia storage. - -Storing data off of the blockchain ensures that Stacks applications can provide users with high performance and high availability for data reads and writes without introducing central trust parties. - -:::tip Latest whitepaper of GAIA (May 2022) is available [here](https://dev1-gaia-hub.s3.amazonaws.com/GAIA_Whitepaper.pdf) ::: - -## Understand Gaia in the Stacks architecture - -The following diagram depicts the Stacks architecture and Gaia's place in it: - -![Stacks Architecture](/img/architecture.png) - -Blockchains require consensus among large numbers of people, so they can be slow. Additionally, a blockchain is not designed to hold a lot of data. This means using a blockchain for every bit of data a user might write and store is expensive. For example, imagine if an application were storing every tweet in the chain. - -The Stacks blockchain addresses performance problems using a layered approach. The base layer consists of the Stacks blockchain and the Blockchain Naming System (BNS). The blockchain governs ownership of identities in the Stacks network. Identities can be names such as domain names, usernames, or application names. - -When an identity is created, its creation is recorded in the Stacks blockchain. Identities make up the primary data stored into the Stacks blockchain. These identities correspond to routing data in the OSI stack. The routing data is stored in the Atlas Peer Network, the second layer. Every core node that joins the Stacks Network is able to obtain an entire copy of this routing data. Stacks uses the routing data to associate identities (domain names, user names, and application names) with a particular storage location in the final layer, the Gaia Storage System. - -A Gaia Storage System consists of a _hub service_ and storage resource on a cloud software provider. The storage provider can be any commercial provider such as Azure, DigitalOcean, Amazon EC2, and so forth. Typically the compute resource and the storage resource reside same cloud vendor, though this is not a requirement. Gaia currently has driver support for S3, Azure Blob Storage, Google Cloud Platform and local disk, but the driver model allows for other backend support as well. - -Gaia stores data as a simple key-value store. When an identity is created, a corresponding data store is associated with that identity on Gaia. When a user logs into a dApp, the authentication process gives the application the URL of a Gaia hub, which then writes to storage on behalf of that user. - -The Stacks blockchain stores only identity data. Data created by the actions of an identity is stored in a Gaia Storage System. Each user has profile data. When a user interacts with a decentralized dApp that application stores application data on behalf of the user. Because Gaia stores user and application data off the blockchain, a Stacks DApp is typically more performant than DApps created on other blockchains. - -## User control or how is Gaia decentralized? - -A Gaia hub runs as a service which writes to data storage. The storage itself is a simple key-value store. The hub service writes to data storage by requiring a valid authentication token from a requestor. Typically, the hub service runs on a compute resource and the storage itself on separate, dedicated storage resource. Typically, both resources belong to the same cloud computing provider. - -![Gaiastorage](/img/gaia-storage.png) - -Gaia's approach to decentralization focuses on user control of data and its storage. Users can choose a Gaia hub provider. If a user can choose which Gaia hub provider to use, then that choice is all the decentralization required to enable user-controlled applications. Moreover, Gaia defines a uniform API for applications to access that data. - -The control of user data lies in the way that user data is accessed. When an application fetches a file `data.txt` for a given user `alice.id`, the lookup will follow these steps: - -1. Fetch the `zonefile` for `alice.id`. -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. Find the read-only url out of the profile's `appsMeta` section (e.g. `https://example-app.gaia.alice.org`). -6. Fetch the file from `https://example-app.gaia.alice.org/data.txt`. - -Because `alice.id` has access to her [zonefile](https://docs.stacks.co/references/bns-contract#name-update), 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. - -:::caution -Users with existing identities cannot yet migrate their data from one hub to another. -::: - -Applications writing directly on behalf of `alice.id` do not need to perform a lookup. Instead, the [Stacks authentication flow](https://stacks.js.org) provides Alice's chosen gaia hub URL to the application. This authentication flow _is also_ within Alice's control because Alice's wallet _must_ generate the authentication response. - -## Understand data storage - -A Gaia hub stores the written data _exactly_ as given. It offers minimal guarantees about the data. It does not ensure that data is validly formatted, contains valid signatures, or is encrypted. Rather, the design philosophy is that these concerns are client-side concerns. - -Client libraries (such as [`Stacks.js`](https://stacks.js.org/)) are capable of providing these guarantees. A liberal definition of the [end-to-end principle](https://en.wikipedia.org/wiki/End-to-end_principle) guides this design decision. - -When an application writes to a Gaia hub, an authentication token, key, and the data are passed to the Gaia hub. - -![Gaia writes](/img/gaia-writes.png) - -The token ensures the app has the authorization to write to the hub on the user's behalf. - -## Gaia versus other storage systems - -Here's how Gaia stacks up against other decentralized storage systems. Features that are common to all storage systems are omitted for brevity. - -| Features | [Gaia](https://github.com/stacks-network/gaia) | [Sia](https://sia.tech/) | [Storj](https://storj.io/) | [IPFS](https://ipfs.io/) | [DAT](https://datproject.org/) | [SSB](https://www.scuttlebutt.nz/) | -| ------------------------------------------ | ---------------------------------------------- | ------------------------ | -------------------------- | ------------------------ | ------------------------------ | ---------------------------------- | -| User controls where data is hosted | X | | | | | | -| Data can be viewed in a normal Web browser | X | | | X | | | -| Data is read/write | X | | | | X | X | -| Data can be deleted | X | | | | X | X | -| Data can be listed | X | X | X | | X | X | -| Deleted data space is reclaimed | X | X | X | X | | | -| Data lookups have predictable performance | X | | X | | | | -| Writes permission can be delegated | X | | | | | | -| Listing permission can be delegated | X | | | | | | -| Supports multiple backends natively | X | | X | | | | -| Data is globally addressable | X | X | X | X | X | | -| Needs a cryptocurrency to work | | X | X | | | | -| Data is content-addressed | | X | X | X | X | X | diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/gaia/setup-linux.md b/i18n/ja/docusaurus-plugin-content-docs/current/gaia/setup-linux.md deleted file mode 100644 index db427f890a..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/gaia/setup-linux.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: Linux -description: Steps to setup a GAIA hub on a Linux server (fresh install). This example is using Debian, but should work on any Linux distribution. It uses docker compose in the backgroud. -tags: - - tutorial - - gaia ---- - -This configuration will setup the following 4 docker containers: - -- Nginx with certbot on TCP ports 80 and 443. -- Gaia hub on TCP port 3000. -- Gaia admin on TCP port 8009. -- Gaia reader on TCP port 8008 - -**1. Update the system and install the dependencies and software we will use to test:** - -```bash -apt update && apt upgrade -y && apt install -y git vim gnupg jq -``` - -**2. Install [docker](https://docs.docker.com/engine/install/debian/) and [docker-compose](https://docs.docker.com/compose/cli-command/#install-on-linux)** in your OS. -For our example we install _docker_ with: - -```bash -curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg - -echo \ - "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian \ - $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null - -apt update && apt install -y docker-ce docker-ce-cli containerd.io -``` - -Install _docker-compose_ by downloading the [latest-release](https://github.com/docker/compose/releases): - -```bash -VERSION_DC=$(curl --silent https://api.github.com/repos/docker/compose/releases/latest | jq .name -r) -DESTINATION_DC=~/.docker/cli-plugins -mkdir -p ${DESTINATION_DC} -curl -SL https://github.com/docker/compose/releases/download/${VERSION_DC}/docker-compose-linux-x86_64 -o ${DESTINATION_DC}/docker-compose -chmod +x ${DESTINATION_DC}/docker-compose -``` - -**3. Clone the GAIA repository** and enter it's docker directory. - -```bash -git clone https://github.com/stacks-network/gaia.git && cd gaia/deploy/docker -``` - -**4. Copy and edit appropiate .env file**. -In the folder `./deploy/docker/` they are different sample files for different configurations like using aws, azure or disk among others. In this example we will store the data localy so we will copy the _disk_ file and update the domain and email fields. Please change `gaia.site.com` and `gaiarocks@mydomain.com` accordingly. Note you need both for the SSL certificate to be created correctly. - -```bash -export MYGAIADOMAIN=gaia.site.com -export MYGAIAEMAIL=gaiarocks@mydomain.com -cp sample-disk.env disk.env -sed -i 's/my-domain.com/'"$MYGAIADOMAIN"'/g' disk.env -sed -i 's/my-email@example.com/'"$MYGAIAEMAIL"'/g' disk.env - -``` - -**5. Start GAIA HUB service** - -To start GAIA HUB - -```bash -./gaiahub.sh start -``` - -To stop GAIA HUB - -```bash -./gaiahub.sh stop -``` - -To view GAIA HUB status - -```bash -./gaiahub.sh status -``` - -**6. Verify server works locally** with the following command: - -```bash -curl -sk http://localhost/hub_info | jq -``` - -A correct result should look similar to this: - -```bash - { - "challenge_text": "[\"gaiahub\",\"0\",\"gaia-0\",\"blockstack_storage_please_sign\"]", - "latest_auth_version": "v1", - "max_file_upload_size_megabytes": 20, - "read_url_prefix": "https://gaia.site.com/reader/" - } -``` - -**7. Test your GAIA HUB** Running `gaia_test.js` will test your GAIA Hub, by trying to connect to it, uploading a file and downloading it again. - -First install all required dependencies with: - -```bash -npm install -``` - -Then, from the root folder of the project type: - -```bash -node ./deploy/gaia_test.js https://yourgaiaurl -``` - -A correct result will be something like this: - -``` -Will run a test for the GAIA HUB: https://gaia.mydomain.com -Generating some test keys... -Private key: 5aacc60fc2a429e1f02be139f3cac82061c6a980******************** -Public key: 025691f17f2ab80dc4af363bb9c7aac59e9e1db6ae8ff668202582a3f4ec9678ff -Address: 15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS -[DEBUG] connectToGaiaHub: https://gaia.mydomain.com/hub_info -[DEBUG] uploadToGaiaHub: uploading testing.txt to https://gaia.mydomain.com -File uploaded successfully. -Upload to gaia hub thinks it can read it from: https://gaia.mydomain.com/reader/15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS/testing.txt -Hub info thinks it can read it from : https://gaia.mydomain.com/reader/15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS/testing.txt -Let's now try to fetch the uploaded file... -File fetched successfully. Contents of file: GAIA ROCKS! -``` diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/gaia/setup-mac.md b/i18n/ja/docusaurus-plugin-content-docs/current/gaia/setup-mac.md deleted file mode 100644 index 808833b212..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/gaia/setup-mac.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: MacOS -description: MacOS for local testing/development -tags: - - tutorial ---- - -The following assumes you have [Docker Installed](https://docs.docker.com/docker-for-mac/install/) - -- Recommended to also have [MacOS Homebrew](https://docs.brew.sh/Installation) installed -- Use Homebrew to install jq with `brew install jq` - -In your working directory: - -**1. Clone a copy of the [gaia repo](https://github.com/stacks-network/gaia):** - -```bash -$ git clone -b master --single-branch https://github.com/stacks-network/gaia -``` - -**2. Change your cwd:** - -```bash -$ cd gaia/deploy/docker -``` - -**3. Create a copy of sample-disk.env and fill out the values:** - -``` -$ cp sample-disk.env disk.env -# Update the DOMAIN_NAME variable to `localhost` -``` - -**4. Start the server:** - -``` -$ docker-compose -f docker-compose-base.yaml -f docker-compose-disk.yaml --env-file disk.env up -``` - -**5. Verify the server is responding locally:** - -``` -$ curl -sk https://localhost/hub_info | jq - { - "challenge_text": "[\"gaiahub\",\"0\",\"gaia-0\",\"blockstack_storage_please_sign\"]", - "latest_auth_version": "v1", - "max_file_upload_size_megabytes": 20, - "read_url_prefix": "https://localhost/reader/" - } -``` - -### Modifying the configuration for your gaia-hub - -Two methods exist: - -1. Edit the `gaia/deploy/configs/gaia/hub-config.json` using `vim` or other - -- requires a restart of the containers: `docker-compose -f docker-compose-base.yaml -f docker-compose-disk.yaml --env-file disk.env restart` - -2. Use the running `admin` container to modify any config values, and also reload the hub when complete: - -- [GitHub - Gaia Admin README.md](https://github.com/stacks-network/gaia/blob/master/admin/README.md) - -``` -$ export API_KEY="hello" -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - -H 'Content-Type: application/json' \ - -X POST \ - --data-raw '{"serverName": "myserver"}' \ - http://localhost:8009/v1/admin/config - -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - -X POST \ - http://localhost:8009/v1/admin/reload - -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - http://localhost:8009/v1/admin/config | jq -``` diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/governance/_index.md b/i18n/ja/docusaurus-plugin-content-docs/current/governance/_index.md deleted file mode 100644 index 1ecdf67871..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/governance/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Governance -description: Governance -sidebar_position: 9 ---- - -This page needs contributions. Help us write it! \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/governance/index.md b/i18n/ja/docusaurus-plugin-content-docs/current/governance/index.md deleted file mode 100644 index 91b0215b5f..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/governance/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Governance -description: Governance -sidebar_position: 9 ---- - -![](/img/stacks-governance.png) - -This page needs contributions. Help us write it! - -Governance in web3 is driven by the community. - -How can I get involved ? - -[Governance Resources website](https://resources.stacksgov.com) - -[Github - Stack Community Governance](https://github.com/stacksgov) - -:::tip Community Calls Monthly community calls are recorded and available [here](https://www.youtube.com/playlist?list=PLg717Ri_rTnwwYjQYlc7rIP6x2FaTNn7f) ::: diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/governance/sips.md b/i18n/ja/docusaurus-plugin-content-docs/current/governance/sips.md deleted file mode 100644 index 29ac1ae1ed..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/governance/sips.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: SIPs -description: SIPs -sidebar_position: 9 ---- - -## Stacks Improvement Proposals (SIPs) - -Stacks improvement proposals (SIPs) are aimed at describing the implementation of the Stacks blockchain, as well as proposing improvements. - -The SIP process [(SIP-000)](https://github.com/stacksgov/sips/blob/main/sips/sip-000/sip-000-stacks-improvement-proposal-process.md) describes how to make a SIP and get it ratified. - -They should contain concise technical specifications of features or standards and the rationale behind it. SIPs are intended to be the primary medium for proposing new features, for collecting community input on a system-wide issue, and for documenting design decisions. - -The SIPs are located in the [stacksgov/sips](https://github.com/stacksgov/sips) repository as part of the [Stacks Community Governance organization](https://github.com/stacksgov). - -Anyone in the Stacks community can submit a SIP. - -:::tip Stacks Improvement Proposals Community Calls SIP Meeting calls are recorded and available [here](https://www.youtube.com/playlist?list=PLg717Ri_rTnx5kuaWqp3cUAtwQk_yzslT) - -More details of the meetings are available [here](https://github.com/stacksgov/sips/issues/79) ::: - -## Ratified SIPSs - -- [x] [SIP 001: Burn Election](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md) -- [x] [SIP 002: Clarity, a language for predictable smart contracts](https://github.com/stacksgov/sips/blob/main/sips/sip-002/sip-002-smart-contract-language.md) -- [x] [SIP 003: Peer Network](https://github.com/stacksgov/sips/blob/main/sips/sip-003/sip-003-peer-network.md) -- [x] [SIP 004: Cryptographic Committment to Materialized Views](https://github.com/stacksgov/sips/blob/main/sips/sip-004/sip-004-materialized-view.md) -- [x] [SIP 005: Blocks, Transactions, and Accounts](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md) -- [x] [SIP 006: Clarity Execution Cost Assessment](https://github.com/stacksgov/sips/blob/main/sips/sip-006/sip-006-runtime-cost-assessment.md) -- [x] [SIP 007: Stacking Consensus](https://github.com/stacksgov/sips/blob/main/sips/sip-007/sip-007-stacking-consensus.md) -- [x] [SIP 008: Clarity Parsing and Analysis Cost Assessment](https://github.com/stacksgov/sips/blob/main/sips/sip-008/sip-008-analysis-cost-assessment.md) -- [x] [SIP 009: Standard Trait Definition for Non-Fungible Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-009/sip-009-nft-standard.md) -- [x] [SIP 010: Standard Trait Definition for Fungible Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-010/sip-010-fungible-token-standard.md) -- [x] [SIP 012: Burn Height Selection for a Network Upgrade to Introduce New Cost-Limits](https://github.com/stacksgov/sips/blob/main/sips/sip-012/sip-012-cost-limits-network-upgrade.md) -- [x] [SIP-016: Metadata for Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-016/sip-016-token-metadata.md) - -## How to Get Involved - -There are several ways you can get involved with the SIP process: - -* **Join the weekly SIP Meeting call** listed [here](https://community.stacks.org/events). - -* **SIP Editor**. SIP editors help SIP authors make sure their SIPs are well-formed and follow the right process. They help get SIPs ready for deep review by advancing it them from Draft to Accepted status. If you want to become a SIP editor, open an issue with your name and email to ask to be added to the list of SIP editors. - -* **Join a CAB** (Consideration Advisory Board). SIPs fall under the purview of one or more considerations. A full list is in [this github](https://github.com/stacksgov/sips/tree/main/considerations) directory. Currently they are: Diversity, Economics, Ethics, Governance and Technical. Members of SIP consideration advisory boards use their domain expertise to give Accepted SIPs a deep read, and give the authors any/all feedback to help make the SIP workable. If you want to join a board, reach out to the board's chairperson via the listed contact information. - -* **Steering Committee**. The Steering Committee organizes the consideration advisory boards and votes to advance Recommended SIPs to Activation-in-Progress status, and then to either Ratified or Rejected status. Once they are in the process of being activated, they use a SIP's Activation section to determine whether or not the Stacks ecosystem has ratified or rejected the SIP. Joining this committee requires the consent of the Stacks Foundation board. diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/intro.md b/i18n/ja/docusaurus-plugin-content-docs/current/intro.md deleted file mode 100644 index 84f1eaa649..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/intro.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_label: "Home" -sidebar_position: 1 ---- - -# Stacks Docs Introduction - -Welcome to the community driven official Stacks Documentation. - -Learn about Stacks mining, the STX token, and the Clarity smart contract language. - -![](/img/Bitcoinet-L_2.svg) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md b/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md deleted file mode 100644 index dd7194f504..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Stacks on DigitalOcean -description: A guide to setup Stacks on DigitalOcean -sidebar_position: 4 -tags: - - tutorial ---- - -## Introduction - -This is a step by step guide to deploy the [Stacks Blockchain on DigitalOcean](https://marketplace.digitalocean.com/apps/stacks-blockchain). Code is hosted on this [Github repository](https://github.com/stacks-network/stacks-blockchain-docker). - -## Steps - -#### Step 1 - -Go to the [Stacks Blockchain page](https://marketplace.digitalocean.com/apps/stacks-blockchain) in DigitalOcean's marketplace. Click on `Create Stacks Blockchain Droplet`. - -#### Step 2 - -Choose a plan (it will only allow you to select a plan that meets the minimum requirements) and your prefered datacenter region. ![](/img/sh_digitalocean-choose-plan.png) - -#### Step 3 - -Enter a root password or enable SSH keys if your prefer. - -![](/img/sh_digitalocean-choose-authentication.png) - -#### Step 4 - -You can leave the rest of the options as they are and click on `Create Droplet` - -#### Step 5 - -You will need to wait a few seconds for the droplet to get created. Once created click on it to see more information. - -![](/img/sh_digitalocean-creating-droplet.png) - -![](/img/sh_digitalocean-created-droplet.png) - -### Step 6 - -Congratulations! You are now running the Stacks Blockchain. You can click on `Console` for a terminal window to open or login using SSH to the public IP you've been assigned to with user `root`. - -![](/img/sh_digitalocean-console-button.png) ![](/img/sh_digitalocean-console.png) - -## Getting started after deploying Stacks Blockchain - -Once droplet is launched, initial startup can take several minutes while BNS data is imported (this is a one time operation). - -To keep track of the progress, you can `ssh root@your_droplet_public_ipv4` to the host and run: `/opt/stacks-blockchain-docker/manage.sh -n mainnet -a logs`. - -Once the stacks blockchain starts to sync with peers, application ports will open and nginx port 80 will now start proxying requests. - -Use `http://your_droplet_public_ipv4` to access the data directly, with output being similar to: - -```json -{ - "server_version": "stacks-blockchain-api v3.0.3 (master:cd0c8aef)", - "status": "ready", - "chain_tip": { - "block_height": 16220, - "block_hash": "0x3123fba9c0de6b569573494cf83c1d5d198a66bfd5f48ef97949b6bf11ba13be", - "index_block_hash": "0xeec960fbbd6186b4ccac85ce12adba72be497d881f81e077305c90955b51a6ae" - } -} -``` - -All services are managed by a [systemd unit file](https://github.com/stacksfoundation/stacks-machine-images/blob/master/files/etc/systemd/system/stacks.service) that is set to start on boot. - -Manual control is also possible via the [manage.sh script](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/manage.sh) at `/opt/stacks-blockchain-docker/manage.sh` on the host. - -Full details on how to use the manage.sh script is [available here](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/README.md#quickstart). - -## API Creation - -In addition to creating a Droplet from the Stacks Blockchain 1-Click App via the control panel, you can also use the [DigitalOcean API](https://digitalocean.com/docs/api). - -As an example, to create a 4GB Stacks Blockchain Droplet in the SFO2 region, you can use the following curl command. You’ll need to either save your [API access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/) to an environment variable or substitute it into the command below. - -```bash -curl -X POST -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer '$TOKEN'' -d \ - '{"name":"choose_a_name","region":"sfo2","size":"s-2vcpu-4gb","image":"stacksfoundation-stacksblockchain"}' \ - "https://api.digitalocean.com/v2/droplets" -``` diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md b/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md deleted file mode 100644 index b6cbb9754a..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Nodes and Miners -description: Nodes and Miners -sidebar_position: 7 ---- - -Here are all the steps to run nodes and miners, both on mainnet and testnet. - -## What's a Stacks node? - -## What's a Stacks miner? diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md b/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md deleted file mode 100644 index 40397a51e0..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Miner costs and fees -description: Miner Cost and Fee Estimation -sidebar_position: 8 ---- - -## Configuring Cost and Fee Estimation - -Fee and cost estimators can be configured via the config section `[fee_estimation]`: - -``` -[fee_estimation] -cost_estimator = naive_pessimistic -fee_estimator = fuzzed_weighted_median_fee_rate -fee_rate_fuzzer_fraction = 0.1 -fee_rate_window_size = 5 -cost_metric = proportion_dot_product -log_error = true -enabled = true -``` - -Fee and cost estimators observe transactions on the network and use the observed costs of those transactions to build estimates for viable fee rates and expected execution costs for transactions. Estimators and metrics can be selected using the configuration fields above, though the default values are the only options currently. `log_error` controls whether or not the INFO logger will display information about the cost estimator accuracy as new costs are observed. Setting `enabled = false` turns off the cost estimators. Cost estimators are **not** consensus-critical components, but rather can be used by miners to rank transactions in the mempool or client to determine appropriate fee rates for transactions before broadcasting them. - -The `fuzzed_weighted_median_fee_rate` uses a median estimate from a window of the fees paid in the last `fee_rate_window_size` blocks. Estimates are then randomly "fuzzed" using uniform random fuzz of size up to `fee_rate_fuzzer_fraction` of the base estimate. diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md b/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md deleted file mode 100644 index 061f4a2511..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md +++ /dev/null @@ -1,343 +0,0 @@ ---- -title: Mine mainnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 mainnet -sidebar_position: 5 -tags: - - tutorial ---- - -## Introduction - -Make sure you've followed the [run a node](run-a-node) procedure. Once completed it's only a few more steps to run a proof-of-burn miner on the mainnet. - -If you're interested in mining on the testnet, you can find instructions on how to do that [here](miner-testnet): - -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining): - -## Running bitcoind locally - -To participate as a miner on mainnet, you must have access to a mainnet bitcoin node. One way to accomplish this is to run bitcoind locally. [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements) - -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. - -Next, start bitcoind with the following configuration: - -```toml -server=1 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=1 -banscore=1 -bind=0.0.0.0:8333 -rpcbind=0.0.0.0:8332 -rpcport=8332 -``` - -Finally, start bitcoind as follows: - -```bash -bitcoind -conf=path/to/bitcoin.conf -``` - -It may take a few days for the node to synchronize with the Bitcoin mainnet. - -## Running a miner - -First, a keychain needs to be generated. With this keychain, we'll purchase some BTC from a crytpocurrency exchange, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. We'll use the `make_keychain` command. - -```bash -npx @stacks/cli make_keychain 2>/dev/null | json_pp > keychain.txt -``` - -After this runs, you should see some JSON in the new `keychain.txt` file that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -**Don't lose this information** - we'll need to use the `privateKey` field later on. - -The above BTC address will then need to be imported into the BTC network. - -```bash -bitcoin-cli -rpcport=8332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - - - -Once imported, we need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - - - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/mainnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `make_keychain` command. Replace the `seed` field with your private key. Save and close this configuration file. - -To run your miner, run this in the command line: - -```bash -stacks-node start --config=./testnet/stacks-node/conf/mainnet-miner-conf.toml -``` - -Your node should start. It will take some time to sync, and then your miner will be running. - -### Creating an optimized binary - -The steps above are great for trying to run a node temporarily. If you want to host a node on a server somewhere, you might want to generate an optimized binary. To do so, use the same configuration as above, but run: - -```bash -cd testnet/stacks-node -cargo build --release --bin stacks-node -``` - -The above code will compile an optimized binary. To use it, run: - -```bash -cd ../.. -./target/release/stacks-node start --config=./mainnet-miner-conf.toml -``` - -To read more about the technical details of mining on the Stacks 2.0 network, have a look at [the mining guide](../understand-stacks/mining). - -### Enable debug logging - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -STACKS_LOG_DEBUG=1 stacks-node mainnet -``` - -## Running a miner in Windows - -### Prerequisites - -Make sure are [running a node](run-a-node) and [running bitcoind locally](#running-bitcoind-locally) before starting this tutorial. - -### Generate keychain and get mainnet tokens in Windows - -To setup the miner, first we need to generate a keychain. With this keychain, we'll purchase some BTC from a crytpocurrency exchange, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. To get a keychain, the simplest way is to use the `stacks-cli`. - -Generate a keychain: - -```bash -npm install --global @stacks/cli -stx make_keychain > cli_keychain.json -type cli_keychain.json -``` - -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -The above BTC address will then need to be imported into the BTC network. - -```bash -bitcoin-cli -rpcport=8332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - -Once imported, we need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Update configuration file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/mainnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Run the miner - -To start your miner, run this in the command line: - -```bash -stacks-node start --config=testnet/stacks-node/conf/mainnet-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](/img/windows-defender.png) - -Your node should start. It will take some time to sync, and then your miner will be running. - -### Enable debug logging in Windows - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=mainnet-miner-conf.toml -``` - -## Optional: Running with Docker - -Alternatively, you can run the mainnet node with Docker. - -:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: - -### Generate keychain and get tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null -``` - -We need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Update configuration file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/mainnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Start the miner - -:::info The ENV VARS `RUST_BACKTRACE` and `STACKS_LOG_DEBUG` are optional. If removed, debug logs will be disabled ::: - -```bash -docker run -d \ - --name stacks_miner \ - --rm \ - --network host \ - -e RUST_BACKTRACE="full" \ - -e STACKS_LOG_DEBUG="1" \ - -v "$(pwd)/testnet/stacks-node/conf/mainnet-miner-conf.toml:/src/stacks-node/mainnet-miner-conf.toml" \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain:latest \ -/bin/stacks-node start --config /src/stacks-node/mainnet-miner-conf.toml -``` - -You can review the node logs with this command: - -```bash -docker logs -f stacks_miner -``` - -## Optional: Running in Kubernetes with Helm - -In addition, you're also able to run a mainnet node in a Kubernetes cluster using the [stacks-blockchain Helm chart](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). - -Ensure you have the following prerequisites installed on your machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [minikube](https://minikube.sigs.k8s.io/docs/start/) (Only needed if standing up a local Kubernetes cluster) -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [helm](https://helm.sh/docs/intro/install/) - -### Generate keychain and get some tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null -``` - -We need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Install the chart and run the miner - -To install the chart with the release name `my-release` and run the node as a miner: - -```bash -minikube start # Only run this if standing up a local Kubernetes cluster -helm repo add blockstack https://charts.blockstack.xyz -helm install my-release blockstack/stacks-blockchain \ - --set config.node.miner=true \ - --set config.node.seed="replace-with-your-privateKey-from-generate-keychain-step" \ - --set config.burnchain.mode="mainnet" -``` - -You can review the node logs with this command: - -```bash -kubectl logs -l app.kubernetes.io/name=stacks-blockchain -``` - -For more information on the Helm chart and configuration options, please refer to the [chart's homepage](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md b/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md deleted file mode 100644 index 56374190c1..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md +++ /dev/null @@ -1,336 +0,0 @@ ---- -title: Mine testnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 testnet -sidebar_position: 4 -tags: - - tutorial ---- - -## Introduction - -Make sure you've followed the [Run a node](run-a-node) procedure. Once completed it's only a few more steps to run a proof-of-burn miner on the testnet. - -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining). - -## Running bitcoind locally - -To participate as a miner on Testnet, you must have access to a testnet bitcoin node. One way to accomplish this is to run bitcoind locally. [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements) - -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. - -Next, start bitcoind with the following configuration: - -```toml -server=1 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password -testnet=1 -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=1 -banscore=1 - -[test] -bind=0.0.0.0:18333 -rpcbind=0.0.0.0:18332 -rpcport=18332 -``` - -Finally, start bitcoind as follows: - -```bash -bitcoind -conf=path/to/bitcoin.conf -``` - -It may take a few hours for the node to synchronize with the Bitcoin testnet. - -## Running a miner - -First, a keychain needs to be generated. With this keychain, we'll get some testnet BTC from a faucet, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. To get a keychain, the simplest way is to use the `stacks-cli`. - -```bash -npx @stacks/cli make_keychain -t 2>/dev/null | json_pp > keychain.txt -``` - -After this runs, you should see some JSON in the new `keychain.txt` file that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -**Don't lose this information** - we'll need to use the `privateKey` field later on. - -The above BTC address will then need to be imported into the BTC testnet network. - -```bash -bitcoin-cli -rpcport=18332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - -Once imported, we need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). You'll be sent `0.01` testnet BTC to that address. - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/testnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/testnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `make_keychain` command. Replace the `seed` field with your private key. Save and close this configuration file. - -To run your miner, run this in the command line: - -```bash -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. - -### Creating an optimized binary - -The steps above are great for trying to run a node temporarily. If you want to host a node on a server somewhere, you might want to generate an optimized binary. To do so, use the same configuration as above, but run: - -```bash -cd testnet/stacks-node -cargo build --release --bin stacks-node -``` - -The above code will compile an optimized binary. To use it, run: - -```bash -cd ../.. -./target/release/stacks-node start --config=./testnet/conf/testnet-follower-conf.toml -``` - -To read more about the technical details of mining on the Stacks 2.0 network, have a look at [the minig guide](../understand-stacks/mining): - -### Enable debug logging - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -STACKS_LOG_DEBUG=1 stacks-node testnet -``` - -## Running a miner in Windows - -### Prerequisites - -Make sure are [running a testnet node](run-a-node) before starting this tutorial. - -### Generate keychain and get testnet tokens in Windows - -To setup the miner, first, we need to generate a keychain. With this keychain, we'll get some testnet BTC from a faucet, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. We'll use the `stx make-keychain` command, and pass `-t` to indicate that we want a testnet keychain. - -Generate a keychain: - -```bash -npm install --global @stacks/cli -stx make_keychain -t > cli_keychain.json -type cli_keychain.json -``` - -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -Request BTC from faucet: - -We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). - -### Update configuration file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/testnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/testnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Run the miner - -To start your miner, run this in the command line: - -```bash -stacks-node start --config=testnet/stacks-node/conf/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](/img/windows-defender.png) - - - -Your node should start. It will take some time to sync, and then your miner will be running. - -### Enable debug logging in Windows - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=testnet-miner-conf.toml -``` - -## Optional: Running with Docker - -Alternatively, you can run the testnet node with Docker. - -:::warning Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: - -### Generate keychain and get testnet tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` - -We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). - -### Update config file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/testnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/testnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Start the miner - -:::info The ENV VARS `RUST_BACKTRACE` and `STACKS_LOG_DEBUG` are optional. If removed, debug logs will be disabled ::: - -```bash -docker run -d \ - --name stacks_miner \ - --rm \ - --network host \ - -e RUST_BACKTRACE="full" \ - -e STACKS_LOG_DEBUG="1" \ - -v "$(pwd))/testnet/stacks-node/conf/testnet-miner-conf.toml:/src/stacks-node/testnet-miner-conf.toml" \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain:latest \ -/bin/stacks-node start --config /src/stacks-node/testnet-miner-conf.toml -``` - -You can review the node logs with this command: - -```bash -docker logs -f stacks_miner -``` - -## Optional: Running in Kubernetes with Helm - -In addition, you're also able to run a testnet node in a Kubernetes cluster using the [stacks-blockchain Helm chart](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). - -Ensure you have the following prerequisites installed on your machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [minikube](https://minikube.sigs.k8s.io/docs/start/) (Only needed if standing up a local Kubernetes cluster) -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [helm](https://helm.sh/docs/intro/install/) - -### Generate keychain and get some testnet tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` - -We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). - -### Install the chart and run the miner - -To install the chart with the release name `my-release` and run the node as a miner: - -```bash -minikube start # Only run this if standing up a local Kubernetes cluster -helm repo add blockstack https://charts.blockstack.xyz -helm install my-release blockstack/stacks-blockchain \ - --set config.node.miner=true \ - --set config.node.seed="replace-with-your-privateKey-from-generate-keychain-step" -``` - -You can review the node logs with this command: - -```bash -kubectl logs -l app.kubernetes.io/name=stacks-blockchain -``` - -For more information on the Helm chart and configuration options, please refer to the [chart's homepage](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md b/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md deleted file mode 100644 index 94d938c5ca..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md +++ /dev/null @@ -1,351 +0,0 @@ ---- -title: Run a node -description: Set up and run a Stacks node -sidebar_position: 1 -tags: - - tutorial ---- - -## Stacks Blockchain with Docker - -Run your own Stacks Blockchain node easily with just few commands. - -This tutorial describes a simple and effective [quickstart](#quickstart) to run a Stacks node using public scripts hosted in [Stacks Blockchain repository](https://github.com/stacks-network/stacks-blockchain-docker). Valid for mainnet, testnet and mocknet. - -## **Quickstart** - -1. **Clone the stacks-blockchain-docker repository locally** - -```bash -git clone https://github.com/stacks-network/stacks-blockchain-docker && cd stacks-blockchain-docker -``` - -2. **Optionally, create/copy `.env` file**. If file `.env` doesn't exist when launched it will be created from `sample.env` automatically. - -```bash -cp sample.env .env -``` - -_You may also use a symlink as an alternative to copying: `ln -s sample.env .env`_ - -3. **Optionally, ensure all images are up to date** - -```bash -./manage.sh -n -a pull -``` - -4. **Start the Services** - -```bash -./manage.sh -n -a start -``` - -- With optional proxy: - -```bash -./manage.sh -n -a start -f proxy -``` - -- With optional bitcoin node: - -```bash -./manage.sh -n -a start -f bitcoin -``` - -5. **Stop the Services** - -```bash -./manage.sh -n -a stop -``` - -6. **Retrieve Service Logs** - -```bash -./manage.sh -n -a logs -``` - -- Export docker log files to `./exported-logs`: - -This will create one log file for every running service, for example: postgres.log, stacks-blockain.log, stacks-blockchain-api.log and bitcoin-core.log. -Notice that each time you run this command the log files will be overwritten. - -```bash -./manage.sh -n -a logs export -``` - -7. **Restart all services** - -```bash -./manage.sh -n -a restart -``` - -- With optional proxy: - -```bash -./manage.sh -n -a restart -f proxy -``` - -8. **Delete** all data in `./persistent-data/` and/or data of the Bitcoin blockchain. - - This data is owned by root, so you will need to run it with sudo privileges so it can delete the data. - -```bash -$ sudo ./manage.sh -n -a reset - -Please confirm what persistent data you wish to delete: - -0. Cancel -1. Delete Persistent data for Stacks testnet only and leave Bitcoin blockchain data unaffected. -2. Delete Persistent data for Stacks testnet and Bitcoin blockchain data in ./persistent-data/blockchain-bitcoin -3. Delete Persistent data for Bitcoin blockchain data in ./persistent-data/blockchain-bitcoin only. -Please note that BNS data will never get deleted. - -Type 0, 1, 2 or 3: 2 - -Ok. Delete Stacks and Bitcoin data. -[ Success ] Persistent data deleted for Bitcoin blockchain. -[ Success ] Persistent data deleted for Stacks testnet. - -``` - -9. **Download BNS data to** `./persistent-data/bns-data` - -```bash -./manage.sh bns -``` - -10. **Export stacks-blockchain-api events** (_Not applicable for mocknet_) - -```bash -./manage.sh -n -a export -# check logs for completion -./manage.sh -n -a restart -``` - -11. **Replay stacks-blockchain-api events** (_Not applicable for mocknet_) - -```bash -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart -``` - -## **Running also a bitcoin node (Optional)** - -Stacks needs to use a Bitcoin node, and by default when you run a Stacks node you will be using a public Bitcoin node, which is configured in the `.env` file. Default values is `BITCOIN_NODE=bitcoin.mainnet.stacks.org`. - -However, you can optionaly run both nodes together and configured in a way that you Stacks node will use your own Bitcoin node instead of a public one. - -If you run the script with a bitcoin node it will download and build it directly from source for increased security. This process which only needs to happen once can take up to 20-30 minutes depending on the speed of your system. Also, once the bitcoin node is up and running it will need an additional time for sync for the first time (can be hours for testnet and days for mainnet). - -### Why run Stacks node with your own Bitcoin node? - -Because running your own Bitcoin node will give you higher security and improved perfomance. - -* **Improved perfomance**: The Bitcoin node will serve you blocks faster, as well as UTXOs for your miner (if you run one). -* **Higher security**: The Bitcoin node will also have validated all bitcoin transactions the Stacks node consumes. If you don't run your own Bitcoin node, you're relying on the SPV headers to vouch for the validity of Bitcoin blocks. - -The disadvantage of running your own Bitcoin node is that you need the extra space to store the Bitcoin blockchain (about 500GB) and the initial time it will take to download this data the first time. - -### Example - -You can run easily run your Stacks node with your own Bitcoin node by adding the flag `bitcoin`. This is available only for testnet and mainnet. - -Example: `./manage.sh -n mainnet -a start -f bitcoin` or `./manage.sh -n testnet -a start -f bitcoin` - -### Bitcoin node configuration - -In the `.env` file there is the variable `BITCOIN_BLOCKCHAIN_FOLDER`. As the bitcoin blockchain can be large (over 500GB) you optionally change this variable to any location of your choosing. If you have previously used the [bitcoin core application](https://bitcoin.org/en/bitcoin-core/) and already have the bitcoin blockchain synced, you can use the same data folder and avoid redownloading the entire bitcoin blockchain. - -## **Accessing the services** - -:::tip For networks other than `mocknet`, downloading the initial headers can take several minutes. Until the headers are downloaded, the `/v2/info` endpoints won't return any data. - -Use the command `./manage.sh -n -a logs` to check the sync progress. ::: - -**stacks-blockchain**: - -- Ports `20443-20444` are exposed to `localhost` - -```bash -curl -sL localhost:20443/v2/info | jq -``` - -**stacks-blockchain-api**: - -- Port `3999` are exposed to `localhost` - -```bash -curl -sL localhost:3999/v2/info | jq -``` - -**proxy**: - -- Port `80` is exposed to `localhost` - -```bash -curl -sL localhost/v2/info | jq -curl -sL localhost/ | jq -``` - ---- - -## Upgrades - -⚠️ For upgrades to running instances of this repo, you'll need to [run the event-replay](https://github.com/hirosystems/stacks-blockchain-api#event-replay): - -```bash -./manage.sh -n -a stop -./manage.sh -n -a export -./manage.sh -n -a import -./manage.sh -n -a restart -``` - ---- - -## **Workarounds to potential issues** - -_**Port(s) already in use**_: - -- 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. `3999` and edit your `.env` file to use the new port. - -```bash -netstat -anl | grep 3999 -``` - -``` -tcp46 0 0 *.3999 *.* LISTEN -``` - -_**Containers not starting (hanging on start)**_: - -- Occasionally, docker can get **stuck** and not allow new containers to start. If this happens, simply restart your docker daemon and try again. - -_**Database Issues**_: - -- For any of the various Postgres/sync issues, it may be easier to simply remove the persistent data dir. Note that doing so will result in a longer startup time as the data is repopulated. - -```bash -./manage.sh -n -a stop -./manage.sh -n -a reset -./manage.sh -n -a start -``` - -_**API Missing Parent Block Error**_: - -- If the Stacks blockchain is no longer syncing blocks, and the API reports an error similar to this:\ - `Error processing core node block message DB does not contain a parent block at height 1970 with index_hash 0x3367f1abe0ee35b10e77fbcaa00d3ca452355478068a0662ec492bb30ee0f13e"`,\ - The API (and by extension the DB) is out of sync with the blockchain. \ - The only known method to recover is to resync from genesis (**event-replay _may_ work, but in all likelihood will restore data to the same broken state**). - -- To attempt the event-replay - -```bash -./manage.sh -n -a stop -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart -``` - -- To wipe data and re-sync from genesis - -```bash -./manage.sh -n -a stop -./manage.sh -n -a reset -./manage.sh -n -a restart -``` - - -## **Requirements:** - -- [Docker](https://docs.docker.com/get-docker/) >= `17.09` -- [docker-compose](https://github.com/docker/compose/releases/) >= `1.27.4` -- [git](https://git-scm.com/downloads) -- [jq binary](https://stedolan.github.io/jq/download/) -- [sed](https://www.gnu.org/software/sed/) -- Machine with (at a minimum): - - 4GB memory - - 1 Vcpu - - 50GB storage (600GB if you optionally also run the bitcoin mainnet node) - -:::caution MacOS with an M1 processor is NOT recommended - -The way Docker for Mac on an Arm chip is designed makes the I/O incredibly slow, and blockchains are **_very_** heavy on I/O. This only seems to affect MacOS, other Arm based systems like Raspberry Pi's seem to work fine. - -::: - - -### Install/Update docker-compose - -:::note `docker-compose` executable is required, even though recent versions of Docker contain `compose` natively ::: - -- [Install Docker-compose](https://docs.docker.com/compose/install/) -- [Docker Desktop for Mac](https://docs.docker.com/docker-for-mac/install/) -- [Docker Desktop for Windows](https://docs.docker.com/docker-for-windows/install/) -- [Docker Engine for Linux](https://docs.docker.com/engine/install/#server) - -First, check if you have `docker-compose` installed locally. - -To do that, run this command in your terminal : - -```bash -docker-compose --version -``` - -Output should look something very similar to this : - -``` -docker-compose version 1.27.4, build 40524192 -``` - -If the command is not found, or the version is < `1.27.4`, run the following to install the latest to `/usr/local/bin/docker-compose`: - -```bash -#You will need to have jq installed, or this snippet won't run. -VERSION=$(curl --silent https://api.github.com/repos/docker/compose/releases/latest | jq .name -r) -DESTINATION=/usr/local/bin/docker-compose -sudo curl -L https://github.com/docker/compose/releases/download/${VERSION}/docker-compose-$(uname -s)-$(uname -m) -o $DESTINATION -sudo chmod 755 $DESTINATION -``` - -### Security note on docker - -The Docker daemon always runs as the root user so by default you will need root privileges to interact with it. - -The script `manage.sh` uses docker, so to avoid the requirement of needing to run the script with root privileges it is prefered to be able to *manage Docker as a non-root user*, following [these simple tests](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user). - -This will avoid the need of running the script with root privileges for all operations except the removal of data. - -### Configuration files you can edit - -The following files can be modified to personalize your node configuration, but generally most of them should be left as-is. All these files will be created from the sample copy if they don't exist at runtime (for example `.env` is created from `sample.env`). However these files will never be modified by the application once created and will never be pushed back to github, so your changes will be safe. - -* `.env` -* `./conf/mainnet/Config.toml` -* `./conf/mainnet/bitcoin.conf` -* `./conf/testnet/Config.toml` -* `./conf/testnet/bitcoin.conf` - -By default: - -- BNS data is **not** enabled/imported - - To enable, uncomment `# BNS_IMPORT_DIR=/bns-data` in `./env` - - Download BNS data: `./manage.sh bns` -- Fungible token metadata is **not** enabled - - To enable, uncomment `# STACKS_API_ENABLE_FT_METADATA=1` in `./env` -- Non-Fungible token metadata is **not** enabled - - To enable, uncomment `# STACKS_API_ENABLE_NFT_METADATA=1` in `./env` -- Verbose logging is **not** enabled - - To enable, uncomment `# VERBOSE=true` in `./env` -- Bitcoin blockchain folder is configured in `BITCOIN_BLOCKCHAIN_FOLDER` in `./env` - -### Local Data Dirs - -Directories will be created on first start that will store persistent data under `./persistent-data/` - -`` can be 1 of: - -- mainnet -- testnet -- mocknet diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md b/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md deleted file mode 100644 index 09db354d0d..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md +++ /dev/null @@ -1,188 +0,0 @@ ---- -title: Running a mainnet node -description: Set up and run a mainnet node with Docker -sidebar_position: 3 -tags: - - tutorial ---- - -## Introduction - -This procedure demonstrates how to run a local mainnet node using Docker images. - -:::caution -This procedure focuses on Unix-like operating systems (Linux and MacOS). This procedure has not been tested on Windows. -::: - -## Prerequisites - -Running a node has no specialized hardware requirements. Users have been successful in running nodes on Raspberry Pi boards and other system-on-chip architectures. In order to complete this procedure, you must have the following software installed on the node host machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [curl](https://curl.se/download.html) -- [jq](https://stedolan.github.io/jq/download/) - -### Firewall configuration - -In order for the API node services to work correctly, you must configure any network firewall rules to allow traffic on the ports discussed in this section. The details of network and firewall configuration are highly specific to your machine and network, so a detailed example isn't provided. - -The following ports must open on the host machine: - -Ingress: - -- stacks-blockchain (open to `0.0.0.0/0`): - - `20443 TCP` - - `20444 TCP` - -Egress: - -- `8332` -- `8333` -- `20443-20444` - -These egress ports are for syncing stacks-blockchain and Bitcoin headers. If they're not open, the sync will fail. - -## Step 1: initial setup - -In order to run the mainnet node, you must download the Docker images and create a directory structure to hold the persistent data from the services. Download and configure the Docker images with the following commands: - -```sh -docker pull blockstack/stacks-blockchain -``` - -Create a directory structure for the service data with the following command: - -```sh -mkdir -p ./stacks-node/{persistent-data/stacks-blockchain/mainnet,config/mainnet} && cd stacks-node -``` - -## Step 2: running Stacks blockchain - -First, create the `./config/mainnet/Config.toml` file and add the following content to the file using a text editor: - -```toml -[node] -working_dir = "/root/stacks-node/data" -rpc_bind = "0.0.0.0:20443" -p2p_bind = "0.0.0.0:20444" -bootstrap_node = "02da7a464ac770ae8337a343670778b93410f2f3fef6bea98dd1c3e9224459d36b@seed-0.mainnet.stacks.co:20444,02afeae522aab5f8c99a00ddf75fbcb4a641e052dd48836408d9cf437344b63516@seed-1.mainnet.stacks.co:20444,03652212ea76be0ed4cd83a25c06e57819993029a7b9999f7d63c36340b34a4e62@seed-2.mainnet.stacks.co:20444" -wait_time_for_microblocks = 10000 - -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "bitcoin.blockstack.com" -username = "blockstack" -password = "blockstacksystem" -rpc_port = 8332 -peer_port = 8333 - -[connection_options] -read_only_call_limit_write_length = 0 -read_only_call_limit_read_length = 100000 -read_only_call_limit_write_count = 0 -read_only_call_limit_read_count = 30 -read_only_call_limit_runtime = 1000000000 -``` - -Start the `stacks-blockchain` container with the following command: - -```sh -docker run -d --rm \ - --name stacks-blockchain \ - -v $(pwd)/persistent-data/stacks-blockchain/mainnet:/root/stacks-node/data \ - -v $(pwd)/config/mainnet:/src/stacks-node \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain \ -/bin/stacks-node start --config /src/stacks-node/Config.toml -``` - -You can verify the running `stacks-blockchain` container with the command: - -```sh -docker ps --filter name=stacks-blockchain -``` - -## Step 3: verifying the services - -:::note -The initial burnchain header sync can take several minutes, until this is done the following commands will not work -::: - -To verify the `stacks-blockchain` burnchain header sync progress: - -```sh -docker logs stacks-blockchain -``` - -The output should be similar to the following: - -``` -INFO [1626290705.886954] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.2% (8000 out of 691034) -INFO [1626290748.103291] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.4% (10000 out of 691034) -INFO [1626290776.956535] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.7% (12000 out of 691034) -``` - -To verify the `stacks-blockchain` tip height is progressing use the following command: - -```sh -curl -sL localhost:20443/v2/info | jq -``` - -If the instance is running you should recieve terminal output similar to the following: - -```json -{ - "peer_version": 402653184, - "pox_consensus": "89d752034e73ed10d3b97e6bcf3cff53367b4166", - "burn_block_height": 666143, - "stable_pox_consensus": "707f26d9d0d1b4c62881a093c99f9232bc74e744", - "stable_burn_block_height": 666136, - "server_version": "stacks-node 2.0.11.1.0-rc1 (master:67dccdf, release build, linux [x86_64])", - "network_id": 1, - "parent_network_id": 3652501241, - "stacks_tip_height": 61, - "stacks_tip": "e08b2fe3dce36fd6d015c2a839c8eb0885cbe29119c1e2a581f75bc5814bce6f", - "stacks_tip_consensus_hash": "ad9f4cb6155a5b4f5dcb719d0f6bee043038bc63", - "genesis_chainstate_hash": "74237aa39aa50a83de11a4f53e9d3bb7d43461d1de9873f402e5453ae60bc59b", - "unanchored_tip": "74d172df8f8934b468c5b0af2efdefe938e9848772d69bcaeffcfe1d6c6ef041", - "unanchored_seq": 0, - "exit_at_block_height": null -} -``` - -## Stopping the mainnet node - -Use the following commands to stop the local mainnet node: - -```sh -docker stop stacks-blockchain -``` - -## Optional. Run stacks node with own bitcoin node - -It's encouraged to use your own bitcoin node when possible. - -To do this simply update the `stacks-node/config/mainnet/Config.toml` file with the details of your bitcoin node. For example: - -``` -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "localhost" -username = "rpc username" -password = "rpc password" -rpc_port = 8332 -peer_port = 8333 -``` - -The rpc configuration of your bitcoin node is out of the scope of this document, but you can find more information on how to set it up [here](https://developer.bitcoin.org/examples/intro.html). - -## Additional reading - - - -- [Running a Stacks API node](https://docs.hiro.so/get-started/running-api-node) -- [Running a Stacks testnet node](running-testnet-node) - diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md b/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md deleted file mode 100644 index da01ce2ea1..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: Running a testnet node -description: Set up and run a testnet node with Docker -sidebar_position: 2 -tags: - - tutorial ---- - -## Introduction - -This procedure demonstrates how to run a local testnet node using Docker images. - -:::caution -This procedure focuses on Unix-like operating systems (Linux and MacOS). This procedure has not been tested on Windows. -::: - -## Prerequisites - -Running a node has no specialized hardware requirements. Users have been successful in running nodes on Raspberry Pi boards and other system-on-chip architectures. In order to complete this procedure, you must have the following software installed on the node host machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [curl](https://curl.se/download.html) -- [jq](https://stedolan.github.io/jq/download/) - -### Firewall configuration - -In order for the API node services to work correctly, you must configure any network firewall rules to allow traffic on the ports discussed in this section. The details of network and firewall configuration are highly specific to your machine and network, so a detailed example isn't provided. - -The following ports must open on the host machine: - -Ingress: - -- stacks-blockchain (open to `0.0.0.0/0`): - - `20443 TCP` - - `20444 TCP` - -Egress: - -- `18332` -- `18333` -- `20443-20444` - -These egress ports are for syncing stacks-blockchain and Bitcoin headers. If they're not open, the sync will fail. - -## Step 1: initial setup - -In order to run the testnet node, you must download the Docker images and create a directory structure to hold the persistent data from the services. Download and configure the Docker images with the following commands: - -```sh -docker pull blockstack/stacks-blockchain -``` - -Create a directory structure for the service data with the following command: - -```sh -mkdir -p ./stacks-node/persistent-data/stacks-blockchain/testnet && cd stacks-node -``` - -## Step 2: running Stacks blockchain - -Start the stacks-blockchain container with the following command: - -```sh -docker run -d --rm \ - --name stacks-blockchain \ - -v $(pwd)/persistent-data/stacks-blockchain/testnet:/root/stacks-node/data \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain \ -/bin/stacks-node testnet -``` - -You can verify the running stacks-blockchain container with the command: - -```sh -docker ps --filter name=stacks-blockchain -``` - -## Step 3: verifying the services - -:::info -The initial burnchain header sync can take several minutes, until this is done the following commands will not work -::: - -To verify the stacks-blockchain burnchain header sync progress: - -```sh -docker logs stacks-blockchain -``` - -The output should be similar to the following: - -``` -INFO [1626290705.886954] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.2% (8000 out of 2034380) -INFO [1626290748.103291] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.4% (10000 out of 2034380) -INFO [1626290776.956535] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.7% (12000 out of 2034380) -``` - -To verify the stacks-blockchain tip height is progressing use the following command: - -```sh -curl -sL localhost:20443/v2/info | jq -``` - -If the instance is running you should recieve terminal output similar to the following: - -```json -{ - "peer_version": 4207599105, - "pox_consensus": "12f7fa85e5099755a00b7eaecded1aa27af61748", - "burn_block_height": 2034380, - "stable_pox_consensus": "5cc4e0403ff6a1a4bd17dae9600c7c13d0b10bdf", - "stable_burn_block_height": 2034373, - "server_version": "stacks-node 2.0.11.2.0-rc1 (develop:7b6d3ee+, release build, linux [x86_64])", - "network_id": 2147483648, - "parent_network_id": 118034699, - "stacks_tip_height": 509, - "stacks_tip": "e0ee952e9891709d196080ca638ad07e6146d4c362e6afe4bb46f42d5fe584e8", - "stacks_tip_consensus_hash": "12f7fa85e5099755a00b7eaecded1aa27af61748", - "genesis_chainstate_hash": "74237aa39aa50a83de11a4f53e9d3bb7d43461d1de9873f402e5453ae60bc59b", - "unanchored_tip": "32bc86590f11504f17904ee7f5cb05bcf71a68a35f0bb3bc2d31aca726090842", - "unanchored_seq": 0, - "exit_at_block_height": null -} -``` - -## Stopping the testnet node - -Use the following commands to stop the local testnet node: - -```sh -docker stop stacks-blockchain -``` - -## Additional reading - - - -- [Running a Stacks API node](https://docs.hiro.so/get-started/running-api-node) -- [Running a Stacks mainnet node](running-mainnet-node) - diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md b/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md deleted file mode 100644 index 89af343dc6..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md +++ /dev/null @@ -1,506 +0,0 @@ ---- -title: Stacks Node Configuration -description: Configuration parameters and options for the stacks-node binary -sidebar_position: 6 ---- - -## Usage - -```bash -stacks-node sub-command [--subcommand-option ] -``` - -## Subcommands - -:::caution The `stacks-node` binary may have deprecated commands that are not documented on this page. Deprecated commands may be accessible until they are fully removed from the sources. ::: - -### mocknet - -Start a node based on a fast local setup emulating a burnchain. Ideal for smart contract development. - -Example: - -```bash -stacks-node mocknet -``` - -### krypton - -Start a node that will join and stream blocks from the public krypton regtest, powered by Blockstack via [Proof of Transfer](../understand-stacks#consensus-mechanism). - -Example: - -```bash -stacks-node krypton -``` - -### testnet - -Start a node that will join and stream blocks from the public testnet. - -Example: - -```bash -stacks-node testnet -``` - -### mainnet - -Start a node that joins and streams blocks from the public mainnet. - -Example: - -```bash -stacks-node mainnet -``` - -### start - -Start a node with a config of your own. Can be used for joining a network, starting a new chain, or replacing default values used by the `mocknet` or `testnet` subcommands. - -#### Arguments - -**--config**: relative or absolute path to the TOML config file. Required. - -Example: - -```bash -stacks-node start --config=/path/to/config.toml -``` - -See [Configuration File Options](#configuration-file-options) for more information. - -#### version - -Displays information about the current version and the release cycle. - -Example: - -```bash -stacks-node version -``` - -#### help - -Displays a help message. - -Example: - -```bash -stacks-node help -``` - -## Configuration File Options - -The TOML configuration file has multiple sections under which an option may be placed. - -To see a list of example configurations, [please see this page](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf). - -### Section: node - -Contains various configuration options pertaining to the stacks-node. - -Example: - -```toml -[node] -rpc_bind = "0.0.0.0:20443" -p2p_bind = "0.0.0.0:20444" -# Enter your private key here -seed = "replace-with-your-private-key" -miner = true -``` - -#### working_dir (optional) - -Absolute path to the directory which the stacks-node will use for storing various data. - -Example: - -```toml -working_dir = "/root/stacks-node" -``` - -#### rpc_bind - -Address and port stacks-node should bind to for RPC connections. - -Example: - -```toml -rpc_bind = "0.0.0.0:20443" -``` - -#### p2p_bind - -Address and port stacks-node should bind to for P2P connections. - -Example: - -```toml -p2p_bind = "0.0.0.0:20444" -``` - -#### data_url (optional) - -Address and port from which the stacks-node will be receiving incoming rpc connections. - -Example: - -```toml -data_url = "1.2.3.4:20443" -``` - -#### p2p_address (optional) - -Address and port from which the stacks-node will be receiving incoming p2p connections. - -Example: - -```toml -p2p_address = "1.2.3.4:20444" -``` - -#### bootstrap_node (optional) - -Public key, address, and port stacks-node should use to pull transaction data from when starting. - -Example: - -```toml -bootstrap_node = "047435c194e9b01b3d7f7a2802d6684a3af68d05bbf4ec8f17021980d777691f1d51651f7f1d566532c804da506c117bbf79ad62eea81213ba58f8808b4d9504ad@testnet.blockstack.org:20444" -``` - -#### wait_time_for_microblocks (optional) - -The amount of time (in milliseconds) that a node will wait before trying to mine a block, after catching up to the anchored chain tip. This gives the current leader time to broadcast microblocks that will get included in that mined block. - -Example: - -```toml -wait_time_for_microblocks = 15000 -``` - -#### seed (optional) - -The private key to use for mining. Only needed if `miner` is set to `true`. - -Example: - -```toml -seed = "replace-with-your-private-key" -``` - -#### local_peer_seed (optional) - -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. - -Example: - -```toml -local_peer_seed = "replace-with-your-private-key" -``` - -#### miner (optional) - -Determines whether the stacks-node is running a follower (`false`) or a miner (`true`). Defaults to `false` if omitted. - -Example: - -```toml -miner = true -``` - -#### mine_microblocks (optional) - -Determines whether the stacks-node will mine microblocks. Will only take effect if `miner` is set to `true`. - -Example: - -```toml -mine_microblocks = true -``` - -#### prometheus_bind (optional) - -Address and port stacks-node should open for Prometheus metrics collection. - -Example: - -```toml -prometheus_bind = "0.0.0.0:9153" -``` - -### Section: events_observer (optional) - -Contains options for watching events emitted by a local [stacks-blockchain-api](https://github.com/hirosystems/stacks-blockchain-api) service. - -:::info -This section can be repeated multiple times. -::: - -Example: - -```toml -[[events_observer]] -endpoint = "address-to-my-local.stacks-node-api.com:3700" -retry_count = 255 -events_keys = ["*"] -``` - -#### endpoint - -Address and port to a stacks-node-api to watch for events. - -Example: - -```toml -endpoint = "address-to-my-local.stacks-node-api.com:3700" -``` - -#### retry_count - -Number of times to retry sending events to the endpoint before failing. - -Example: - -```toml -retry_count = 255 -``` - -#### events_keys - -Event keys for which to watch. The emitted node events can be restricted by account, function name and event type. Asterix ("\*") can be used to emit all events. - -Examples: - -```toml -events_keys = ["*"] -``` - -```toml -events_keys = [ - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.store::print", - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.contract.ft-token", - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.contract.nft-token", - "stx" -] -``` - -### Section: connection_options (optional) - -Specifies configuration options for others connecting to the stacks node. - -Example: - -```toml -[connection_options] -public_ip_address = "1.2.3.4:20444" -download_interval = 60 -walk_interval = 30 -``` - -#### public_ip_address - -The advertised public IP of this stacks-node. - -Example: - -```toml -public_ip_address = "1.2.3.4:20444" -``` - -#### download_interval - -Time (in seconds) between attempts to download blocks. - -Example: - -```toml -download_interval = 60 -``` - -#### walk_interval - -Time (in seconds) between attempts to walk the neighborhood. - -Example: - -```toml -walk_interval = 30 -``` - -#### read_only_call_limit_read_length - -Total number of bytes allowed to be read by an individual read-only function call. - -Example: - -```toml -read_only_call_limit_read_length = 100000 -``` - -#### read_only_call_limit_read_count - -Total number of independent read operations permitted for an individual read-only function call. - -Example: - -```toml -read_only_call_limit_read_count = 30 -``` - -#### read_only_call_limit_runtime - -[Runtime cost](https://github.com/stacksgov/sips/blob/2d3fd9bf8da7a04f588d90ff6252173d7609d7bf/sips/sip-006/sip-006-runtime-cost-assessment.md#introduction) limit for an individual read-only function call. - -Example: - -```toml -read_only_call_limit_runtime = 1000000000 -``` - -### Section: burnchain - -This section contains configuration options pertaining to the blockchain the stacks-node binds to on the backend for proof-of-transfer (BTC). - -Example: - -```toml -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "your.bitcoind.node.org" -rpc_port = 8332 -peer_port = 8333 -``` - -#### chain - -The blockchain stacks-node binds to on the backend for proof-of-transfer. Only value supported: `"bitcoin"`. - -Example: - -```toml -chain = "bitcoin" -``` - -#### mode - -The profile or test phase of which to run stacks-node. Valid values are `"mocknet"`, `"helium"`, `"neon"`, `"argon"`, `"krypton"`, `"xenon"`. - -Example: - -```toml -mode = "xenon" -``` - -#### peer_host - -Domain name of the host running the backend Bitcoin blockchain. It's required to either run a personal Bitcoin node locally, or to use a publicly hosted Bitcoin node. - -Example: - -```toml -peer_host = "your.bitcoind.node.org" -``` - -#### rpc_port - -peer_host's port stacks-node will connect to for RPC connections. - -Example: - -```toml -rpc_port = 8332 -``` - -#### peer_port - -peer_host's port stacks-node will connect to for P2P connections. - -Example: - -```toml -peer_port = 8333 -``` - -#### burn_fee_cap (optional) - -Maximum amount (in Satoshis) of "burn commitment" to broadcast for the next block's leader election. - -Example: - -```toml -burn_fee_cap = 30000 -``` - -#### satoshis_per_byte (optional) - -Amount (in Satoshis) per [virtual byte](https://en.bitcoin.it/wiki/Weight_units). This is used to compute the transaction fees. - -Example: - -```toml -satoshis_per_byte = 50 -``` - -So total transaction cost would be `(estimated_tx_size * satoshis_per_byte) + burn_fee_cap`. - -#### commit_anchor_block_within (optional) - -Sets the time period (in milliseconds) for commitments. Only used when `mode` is set to `"helium"`. - -Example: - -```toml -commit_anchor_block_within = 10000 -``` - -### Section: ustx_balance (testnet/regtest only) - -This section contains configuration options pertaining to the genesis block allocation for an address in micro-STX. If a user changes these values, their node may be in conflict with other nodes on the network and find themselves unable to sync with other nodes. - -:::info -This section can repeat multiple times, and thus is in double-brackets. Each section can define only one address. This section is ignored if running a node on mainnet. -::: - -Example: - -```toml -[[ustx_balance]] -address = "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6" -amount = 10000000000000000 - -[[ustx_balance]] -address = "ST11NJTTKGVT6D1HY4NJRVQWMQM7TVAR091EJ8P2Y" -amount = 10000000000000000 - -[[ustx_balance]] -address = "ST1HB1T8WRNBYB0Y3T7WXZS38NKKPTBR3EG9EPJKR" -amount = 10000000000000000 - -[[ustx_balance]] -address = "STRYYQQ9M8KAF4NS7WNZQYY59X93XEKR31JP64CP" -amount = 10000000000000000 -``` - -#### address - -Address which maintains a micro-STX balance. - -Example: - -```toml -address = "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6" -``` - -#### amount - -The balance of micro-STX given to the address at the start of the node. - -Example: - -```toml -amount = 10000000000000000 -``` diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md b/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md deleted file mode 100644 index 094e3f03a1..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Verify Miner -description: Verify node is operating as miner -sidebar_position: 7 ---- - -You can verify that your node is operating as a miner by checking its log output to verify that it was able to find its Bitcoin UTXOs: - -```bash -$ head -n 100 /path/to/your/node/logs | grep -i utxo -INFO [1630127492.031042] [testnet/stacks-node/src/run_loop/neon.rs:146] [main] Miner node: checking UTXOs at address: -INFO [1630127492.062652] [testnet/stacks-node/src/run_loop/neon.rs:164] [main] UTXOs found - will run as a Miner node -``` \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json b/i18n/ja/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json deleted file mode 100644 index f5de305558..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Noteworthy Contracts", - "position": 4, - "link": { - "type": "generated-index", - "description": "Specific deployed Clarity Contracts worth mentioning." - } -} \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md b/i18n/ja/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md deleted file mode 100644 index 99723a9ff2..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md +++ /dev/null @@ -1,362 +0,0 @@ ---- -title: BNS Contract -description: The Blockchain Naming System. ---- - -![](/img/satoshi-btc.png) - -## Introduction - -The Blockchain Naming System (BNS) is implemented as a smart contract using Clarity. - -Below is a list of public and read-only functions as well as error codes that can be returned by those methods: -* [Public functions](#public-functions) -* [Read-only functions](#read-only-functions) -* [Error codes](#error-codes) - -## Public functions - - -### name-import - -#### Input: `(buff 20), (buff 48), principal, (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-import namespace name beneficiary zonefile-hash)` -#### Description: -Imports name to a revealed namespace. Each imported name is given both an owner and some off-chain state. - -### name-preorder - -#### Input: `(buff 20), uint` -#### Output: `(response uint int)` -#### Signature: `(name-preorder hashed-salted-fqn stx-to-burn)` -#### Description: -Preorders a name by telling all BNS nodes the salted hash of the BNS name. It pays the registration fee to the namespace owner's designated address. - -### name-register - -#### Input: `(buff 20), (buff 48), (buff 20), (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-register namespace name salt zonefile-hash)` -#### Description: -Reveals the salt and the name to all BNS nodes, and assigns the name an initial public key hash and zone file hash. - -### name-renewal - -#### Input: `(buff 20), (buff 48), uint, (optional principal), (optional (buff 20))` -#### Output: `(response bool int)` -#### Signature: `(name-renewal namespace name stx-to-burn new-owner zonefile-hash)` -#### Description: -Depending in the namespace rules, a name can expire. For example, names in the .id namespace expire after 2 years. You need to send a name renewal every so often to keep your name. - -You will pay the registration cost of your name to the namespace's designated burn address when you renew it. When a name expires, it enters a \"grace period\". The period is set to 5000 blocks (a month) but can be configured for each namespace. - -It will stop resolving in the grace period, and all of the above operations will cease to be honored by the BNS consensus rules. You may, however, send a NAME_RENEWAL during this grace period to preserve your name. After the grace period, everybody can register that name again. If your name is in a namespace where names do not expire, then you never need to use this transaction. -### name-revoke - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(name-revoke namespace name)` -#### Description: -Makes a name unresolvable. The BNS consensus rules stipulate that once a name is revoked, no one can change its public key hash or its zone file hash. The name's zone file hash is set to null to prevent it from resolving. You should only do this if your private key is compromised, or if you want to render your name unusable for whatever reason. - -### name-transfer - -#### Input: `(buff 20), (buff 48), principal, (optional (buff 20))` -#### Output: `(response bool int)` -#### Signature: `(name-transfer namespace name new-owner zonefile-hash)` -#### Description: -Changes the name's public key hash. You would send a name transfer transaction if you wanted to: -* Change your private key -* Send the name to someone else or -* Update your zone file - -When transferring a name, you have the option to also clear the name's zone file hash (i.e. set it to null). This is useful for when you send the name to someone else, so the recipient's name does not resolve to your zone file. - -### name-update - -#### Input: `(buff 20), (buff 48), (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-update namespace name zonefile-hash)` -#### Description: -Changes the name's zone file hash. You would send a name update transaction if you wanted to change the name's zone file contents. For example, you would do this if you want to deploy your own Gaia hub and want other people to read from it. - -### namespace-preorder - -#### Input: `(buff 20), uint` -#### Output: `(response uint int)` -#### Signature: `(namespace-preorder hashed-salted-namespace stx-to-burn)` -#### Description: -Registers the salted hash of the namespace with BNS nodes, and burns the requisite amount of cryptocurrency. Additionally, this step proves to the BNS nodes that user has honored the BNS consensus rules by including a recent consensus hash in the transaction. Returns pre-order's expiration date (in blocks). - -### namespace-ready - -#### Input: `(buff 20)` -#### Output: `(response bool int)` -#### Signature: `(namespace-ready namespace)` -#### Description: -Launches the namespace and makes it available to the public. Once a namespace is launched, anyone can register a name in it if they pay the appropriate amount of cryptocurrency. - -### namespace-reveal - -#### Input: `(buff 20), (buff 20), uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, principal` -#### Output: `(response bool int)` -#### Signature: `(namespace-reveal namespace namespace-salt p-func-base p-func-coeff p-func-b1 p-func-b2 p-func-b3 p-func-b4 p-func-b5 p-func-b6 p-func-b7 p-func-b8 p-func-b9 p-func-b10 p-func-b11 p-func-b12 p-func-b13 p-func-b14 p-func-b15 p-func-b16 p-func-non-alpha-discount p-func-no-vowel-discount lifetime namespace-import)` -#### Description: -Reveals the salt and the namespace ID (after a namespace preorder). It reveals how long names last in this namespace before they expire or must be renewed, and it sets a price function for the namespace that determines how cheap or expensive names its will be.All of the parameters prefixed by `p` make up the `price function`. These parameters govern the pricing and lifetime of names in the namespace. - -The rules for a namespace are as follows: - -* a name can fall into one of 16 buckets, measured by length. Bucket 16 incorporates all names at least 16 characters long. - -* the pricing structure applies a multiplicative penalty for having numeric characters, or punctuation characters. - -* the price of a name in a bucket is `((coeff) * (base) ^ (bucket exponent)) / ((numeric discount multiplier) * (punctuation discount multiplier))` - -Example: - -* base = 10 -* coeff = 2 -* nonalpha discount: 10 -* no-vowel discount: 10 -* buckets 1, 2: 9 -* buckets 3, 4, 5, 6: 8 -* buckets 7, 8, 9, 10, 11, 12, 13, 14: 7 -* buckets 15, 16+: - - -## Read-only functions - -### can-name-be-registered - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(can-name-be-registered namespace name)` -#### Description: -Returns true if the provided name can be registered. - -### can-namespace-be-registered - -#### Input: `(buff 20)` -#### Output: `(response bool UnknownType)` -#### Signature: `(can-namespace-be-registered namespace)` -#### Description: -Returns true if the provided namespace is available. - -### can-receive-name - -#### Input: `principal` -#### Output: `(response bool int)` -#### Signature: `(can-receive-name owner)` -#### Description: -Returns true if the provided name can be received. That is, if it is not curretly owned, a previous lease is expired, and the name wasn't revoked. - -### get-name-price - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response uint int)` -#### Signature: `(get-name-price namespace name)` -#### Description: -Gets the price for a name. - -### get-namespace-price - -#### Input: `(buff 20)` -#### Output: `(response uint int)` -#### Signature: `(get-namespace-price namespace)` -#### Description: -Gets the price for a namespace. - -### get-namespace-properties - -#### Input: `(buff 20)` -#### Output: `(response (tuple (namespace (buff 20)) (properties (tuple (can-update-price-function bool) (launched-at (optional uint)) (lifetime uint) (namespace-import principal) (price-function (tuple (base uint) (buckets (list 16 uint)) (coeff uint) (no-vowel-discount uint) (nonalpha-discount uint))) (revealed-at uint)))) int)` -#### Signature: `(get-namespace-properties namespace)` -#### Description: -Get namespace properties. - -### is-name-lease-expired - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(is-name-lease-expired namespace name)` -#### Description: -Return true if the provided name lease is expired. - -### name-resolve - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response (tuple (lease-ending-at (optional uint)) (lease-started-at uint) (owner principal) (zonefile-hash (buff 20))) int)` -#### Signature: `(name-resolve namespace name)` -#### Description: -Get name registration details. - -### resolve-principal - -#### Input: `principal` -#### Output: `(response (tuple (name (buff 48)) (namespace (buff 20))) (tuple (code int) (name (optional (tuple (name (buff 48)) (namespace (buff 20)))))))` -#### Signature: `(resolve-principal owner)` -#### Description: -Returns the registered name that a principal owns if there is one. A principal can only own one name at a time. - -## Error codes - -### ERR_INSUFFICIENT_FUNDS -#### type: `int` -#### value: `4001` - -### ERR_NAMESPACE_ALREADY_EXISTS -#### type: `int` -#### value: `1006` - -### ERR_NAMESPACE_ALREADY_LAUNCHED -#### type: `int` -#### value: `1014` - -### ERR_NAMESPACE_BLANK -#### type: `int` -#### value: `1013` - -### ERR_NAMESPACE_CHARSET_INVALID -#### type: `int` -#### value: `1016` - -### ERR_NAMESPACE_HASH_MALFORMED -#### type: `int` -#### value: `1015` - -### ERR_NAMESPACE_NOT_FOUND -#### type: `int` -#### value: `1005` - -### ERR_NAMESPACE_NOT_LAUNCHED -#### type: `int` -#### value: `1007` - -### ERR_NAMESPACE_OPERATION_UNAUTHORIZED -#### type: `int` -#### value: `1011` - -### ERR_NAMESPACE_PREORDER_ALREADY_EXISTS -#### type: `int` -#### value: `1003` - -### ERR_NAMESPACE_PREORDER_CLAIMABILITY_EXPIRED -#### type: `int` -#### value: `1009` - -### ERR_NAMESPACE_PREORDER_EXPIRED -#### type: `int` -#### value: `1002` - -### ERR_NAMESPACE_PREORDER_LAUNCHABILITY_EXPIRED -#### type: `int` -#### value: `1010` - -### ERR_NAMESPACE_PREORDER_NOT_FOUND -#### type: `int` -#### value: `1001` - -### ERR_NAMESPACE_PRICE_FUNCTION_INVALID -#### type: `int` -#### value: `1008` - -### ERR_NAMESPACE_STX_BURNT_INSUFFICIENT -#### type: `int` -#### value: `1012` - -### ERR_NAMESPACE_UNAVAILABLE -#### type: `int` -#### value: `1004` - -### ERR_NAME_ALREADY_CLAIMED -#### type: `int` -#### value: `2011` - -### ERR_NAME_BLANK -#### type: `int` -#### value: `2010` - -### ERR_NAME_CHARSET_INVALID -#### type: `int` -#### value: `2022` - -### ERR_NAME_CLAIMABILITY_EXPIRED -#### type: `int` -#### value: `2012` - -### ERR_NAME_COULD_NOT_BE_MINTED -#### type: `int` -#### value: `2020` - -### ERR_NAME_COULD_NOT_BE_TRANSFERED -#### type: `int` -#### value: `2021` - -### ERR_NAME_EXPIRED -#### type: `int` -#### value: `2008` - -### ERR_NAME_GRACE_PERIOD -#### type: `int` -#### value: `2009` - -### ERR_NAME_HASH_MALFORMED -#### type: `int` -#### value: `2017` - -### ERR_NAME_NOT_FOUND -#### type: `int` -#### value: `2013` - -### ERR_NAME_NOT_RESOLVABLE -#### type: `int` -#### value: `2019` - -### ERR_NAME_OPERATION_UNAUTHORIZED -#### type: `int` -#### value: `2006` - -### ERR_NAME_PREORDERED_BEFORE_NAMESPACE_LAUNCH -#### type: `int` -#### value: `2018` - -### ERR_NAME_PREORDER_ALREADY_EXISTS -#### type: `int` -#### value: `2016` - -### ERR_NAME_PREORDER_EXPIRED -#### type: `int` -#### value: `2002` - -### ERR_NAME_PREORDER_FUNDS_INSUFFICIENT -#### type: `int` -#### value: `2003` - -### ERR_NAME_PREORDER_NOT_FOUND -#### type: `int` -#### value: `2001` - -### ERR_NAME_REVOKED -#### type: `int` -#### value: `2014` - -### ERR_NAME_STX_BURNT_INSUFFICIENT -#### type: `int` -#### value: `2007` - -### ERR_NAME_TRANSFER_FAILED -#### type: `int` -#### value: `2015` - -### ERR_NAME_UNAVAILABLE -#### type: `int` -#### value: `2004` - -### ERR_PANIC -#### type: `int` -#### value: `0` - -### ERR_PRINCIPAL_ALREADY_ASSOCIATED -#### type: `int` -#### value: `3001` diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md b/i18n/ja/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md deleted file mode 100644 index ce1b1ba859..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -title: Stacking Contract -description: See a detailed list of all functions and error codes of the Stacking contract. ---- - -## Introduction - -Stacking is implemented as a smart contract using Clarity. You can always find the Stacking contract identifier using the Stacks Blockchain API [`v2/pox` endpoint](https://docs.hiro.so/api#operation/get_pox_info). - -Below is a list of public and read-only functions as well as error codes that can be returned by those methods: - -* [Public functions](#public-functions) -* [Read-only functions](#read-only-functions) -* [Error codes](#error-codes) - -## Public functions - -### allow-contract-caller -#### input: `principal, (optional uint)` -#### output: `(response bool int)` -#### signature: `(allow-contract-caller caller until-burn-ht)` -#### description: -Give a contract-caller authorization to call stacking methods. Normally, stacking methods may only be invoked by _direct_ transactions (i.e., the `tx-sender` issues a direct `contract-call` to the stacking methods). - -By issuing an allowance, the tx-sender may call through the allowed contract. - -### delegate-stack-stx -#### input: `principal, uint, (tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint` -#### output: `(response (tuple (lock-amount uint) (stacker principal) (unlock-burn-height uint)) int)` -#### signature: `(delegate-stack-stx stacker amount-ustx pox-addr start-burn-ht lock-period)` -#### description: -As a delegate, stack the given principal's STX using `partial-stacked-by-cycle`. - -Once the delegate has stacked > minimum, the delegate should call `stack-aggregation-commit`. - -### delegate-stx -#### input: `uint, principal, (optional uint), (optional (tuple (hashbytes (buff 20)) (version (buff 1))))` -#### output: `(response bool int)` -#### signature: `(delegate-stx amount-ustx delegate-to until-burn-ht pox-addr)` -#### description: -Delegate to `delegate-to` the ability to stack from a given address. - -This method _does not_ lock the funds, rather, it allows the delegate to issue the stacking lock. - -The caller specifies: - -* amount-ustx: the total amount of ustx the delegate may be allowed to lock -* until-burn-ht: an optional burn height at which this delegation expiration -* pox-addr: an optional p2pkh or p2sh address to which any rewards *must* be sent - -### disallow-contract-caller -#### input: `principal` -#### output: `(response bool int)` -#### signature: `(disallow-contract-caller caller)` -#### description: -Revokes authorization from a contract to invoke stacking methods through contract-calls - -### reject-pox -#### input: -#### output: `(response bool int)` -#### signature: `(reject-pox)` -#### description: -Reject Stacking for this reward cycle. - -`tx-sender` votes all its uSTX for rejection. - -Note that unlike Stacking, rejecting PoX does not lock the tx-sender's tokens: PoX rejection acts like a coin vote. - -### revoke-delegate-stx -#### input: -#### output: `(response bool int)` -#### signature: `(revoke-delegate-stx)` -#### description: -Revoke a Stacking delegate relationship. A particular Stacker may only have one delegate, so this method does not take any parameters, and just revokes the Stacker's current delegate (if one exists). - -### stack-aggregation-commit -#### input: `(tuple (hashbytes (buff 20)) (version (buff 1))), uint` -#### output: `(response bool int)` -#### signature: `(stack-aggregation-commit pox-addr reward-cycle)` -#### description: -Commit partially stacked STX. - -This allows a stacker/delegate to lock fewer STX than the minimal threshold in multiple transactions, - -so long as: - -1. The pox-addr is the same. -2. This \"commit\" transaction is called _before_ the PoX anchor block. - -This ensures that each entry in the reward set returned to the stacks-node is greater than the threshold, - - but does not require it be all locked up within a single transaction - -### stack-stx -#### input: `uint, (tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint` -#### output: `(response (tuple (lock-amount uint) (stacker principal) (unlock-burn-height uint)) int)` -#### signature: `(stack-stx amount-ustx pox-addr start-burn-ht lock-period)` -#### description: -Lock up some uSTX for stacking! Note that the given amount here is in micro-STX (uSTX). - -The STX will be locked for the given number of reward cycles (lock-period). - -This is the self-service interface. tx-sender will be the Stacker. - -* The given stacker cannot currently be stacking. -* You will need the minimum uSTX threshold. This isn't determined until the reward cycle begins, but this method still requires stacking over the _absolute minimum_ amount, which can be obtained by calling `get-stacking-minimum`. -* The pox-addr argument must represent a valid reward address. Right now, this must be a Bitcoin p2pkh or p2sh address. It cannot be a native Segwit address, but it may be a p2wpkh-p2sh or p2wsh-p2sh address. - -The tokens will unlock and be returned to the Stacker (tx-sender) automatically. - -## Read-only functions - -### can-stack-stx -#### input: `(tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint, uint` -#### output: `(response bool int)` -#### signature: `(can-stack-stx pox-addr amount-ustx first-reward-cycle num-cycles)` -#### description: -Evaluate if a participant can stack an amount of STX for a given period. - -### get-pox-info -#### input: -#### output: `(response (tuple (current-rejection-votes uint) (first-burnchain-block-height uint) (min-amount-ustx uint) (prepare-cycle-length uint) (rejection-fraction uint) (reward-cycle-id uint) (reward-cycle-length uint) (total-liquid-supply-ustx uint)) UnknownType)` -#### signature: `(get-pox-info)` -#### description: -Returns information about PoX status. - -### get-pox-rejection -#### input: `principal, uint` -#### output: `(optional (tuple (amount uint)))` -#### signature: `(get-pox-rejection stacker reward-cycle)` -#### description: -Returns the amount of uSTX that a given principal used to reject a PoX cycle. - -### get-stacker-info -#### input: `principal` -#### output: `(optional (tuple (amount-ustx uint) (first-reward-cycle uint) (lock-period uint) (pox-addr (tuple (hashbytes (buff 20)) (version (buff 1))))))` -#### signature: `(get-stacker-info stacker)` -#### description: -Returns the _current_ stacking information for `stacker. If the information is expired, or if there's never been such a stacker, then returns none. - -### get-stacking-minimum -#### input: -#### output: `uint` -#### signature: `(get-stacking-minimum)` -#### description: -Returns the absolute minimum amount that could be validly Stacked (the threshold to Stack in a given reward cycle may be higher than this - -### get-total-ustx-stacked -#### input: `uint` -#### output: `uint` -#### signature: `(get-total-ustx-stacked reward-cycle)` -#### description: -Returns the amount of currently participating uSTX in the given cycle. - -### is-pox-active -#### input: `uint` -#### output: `bool` -#### signature: `(is-pox-active reward-cycle)` -#### description: -Returns whether or not PoX has been rejected at a given PoX cycle. -## Error codes - -### ERR_DELEGATION_EXPIRES_DURING_LOCK -#### type: `int` -#### value: `21` - -### ERR_DELEGATION_POX_ADDR_REQUIRED -#### type: `int` -#### value: `23` - -### ERR_DELEGATION_TOO_MUCH_LOCKED -#### type: `int` -#### value: `22` - -### ERR_INVALID_START_BURN_HEIGHT -#### type: `int` -#### value: `24` - -### ERR_NOT_ALLOWED -#### type: `int` -#### value: `19` - -### ERR_STACKING_ALREADY_DELEGATED -#### type: `int` -#### value: `20` - -### ERR_STACKING_ALREADY_REJECTED -#### type: `int` -#### value: `17` - -### ERR_STACKING_ALREADY_STACKED -#### type: `int` -#### value: `3` - -### ERR_STACKING_EXPIRED -#### type: `int` -#### value: `5` - -### ERR_STACKING_INSUFFICIENT_FUNDS -#### type: `int` -#### value: `1` - -### ERR_STACKING_INVALID_AMOUNT -#### type: `int` -#### value: `18` - -### ERR_STACKING_INVALID_LOCK_PERIOD -#### type: `int` -#### value: `2` - -### ERR_STACKING_INVALID_POX_ADDRESS -#### type: `int` -#### value: `13` - -### ERR_STACKING_NO_SUCH_PRINCIPAL -#### type: `int` -#### value: `4` - -### ERR_STACKING_PERMISSION_DENIED -#### type: `int` -#### value: `9` - -### ERR_STACKING_POX_ADDRESS_IN_USE -#### type: `int` -#### value: `12` - -### ERR_STACKING_STX_LOCKED -#### type: `int` -#### value: `6` - -### ERR_STACKING_THRESHOLD_NOT_MET -#### type: `int` -#### value: `11` - -### ERR_STACKING_UNREACHABLE -#### type: `int` -#### value: `255` \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md b/i18n/ja/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md deleted file mode 100644 index 5f38edfb57..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: xBTC -description: Wrapped BTC on Stacks ---- - -![](/img/xbtc-icon.webp) - -## Introduction - -[Wrapped.com](https://www.wrapped.com) has brought Bitcoin (xBTC) to the Stacks ecosystem. - -xBTC is backed 1:1 by Bitcoin and empowers developers to expand the Bitcoin DeFi ecosystem. - -The reserves are publicly visible [here](https://open.wrapped.com/reserves/). - -## Contract - -[SP3DX3H4FEYZJZ586MFBS25ZW3HZDMEW92260R2PR.Wrapped-Bitcoin](https://explorer.stacks.co/txid/SP3DX3H4FEYZJZ586MFBS25ZW3HZDMEW92260R2PR.Wrapped-Bitcoin?chain=mainnet) - -## Examples of uses - -[Friedger Mining Pool](https://pool.friedger.de/) currrently supports Stacking rewards payments in xBTC (optional). - - -## More information - -* [Blog post announcement](https://www.stacks.co/blog/tokensoft-wrapped-fundamental-bitcoin-defi-building-blocks-xbtc) by Muneeb Ali - -* Video: [Why xBTC is Important For Bitcoin to Grow](https://www.youtube.com/watch?v=xIoadrfSdi4) \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/references/_category_.json b/i18n/ja/docusaurus-plugin-content-docs/current/references/_category_.json deleted file mode 100644 index 3805ab0783..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/references/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "References", - "position": 9, - "link": { - "type": "generated-index", - "description": "Stacks references." - } -} \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/references/glossary.md b/i18n/ja/docusaurus-plugin-content-docs/current/references/glossary.md deleted file mode 100644 index 23badef6ac..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/references/glossary.md +++ /dev/null @@ -1,215 +0,0 @@ ---- -title: Glossary -description: A comprehensive list of terms used within the ecosystem. ---- - -A comprehensive list of terms used within the ecosystem. - -#### App Review -An incentive mechanism for application developers in the early stage (first four years) of the ecosystem and helps with bootstrapping the two-sided market. - -#### Atlas -A peer network provide a global index for discovery. - -#### Bitcoin (BTC) address -A string of letters and numbers. `3E53XjqK4Cxt71BGeP2VhpcotM8LZ853C8` Sharing this address allows anyone to send Bitcoin to the address. - -#### block -A discrete group of records written to a blockchain that can effectively be identified and referenced by the use of headers that contain a digital fingerprint of the records each block contains. - -#### blockchain -A database created and shared by the members of a peer-to-peer computer network which each member of that network can independently trust due to the rules governing the database’s creation. A blockchain can therefore be used to replace centralized databases. - -#### Blockchain Name System (BNS) -Replacement for DNS. More info [here](../noteworthy-contracts/bns-contract). - -#### Blockstack Browser -A deprecated application for accessing identity and storage. - -#### Blockstack Owner Address - -Looks like a bitcoin address but starts with `ID` for example: `ID-1J3PUxY5uDShUnHRrMyU6yKtoHEUPhKULs` - -#### Burning -Burning a token means that the token is transferred to an address that is a black hole—one that is not owned by any entity and for which guessing the applicable private key is effectively impossible based on known mathematical principles. This effectively destroys the token by making it unavailable for future use and decreases the total number of tokens available from that point forward. - -#### consensus hash -A consensus hash is a cryptographic hash that each node calculates at each block. It is derived from the accepted state transitions in the last-processed block and a geometric series of prior-calculated consensus hashes. - -#### Consensus rules -"The rules governing the creation of new valid records in a blockchain database and the mining algorithms used for this purpose. - -#### control plane -The part of a network that carries signaling traffic and is responsible for routing. Control packets originate from or are destined for a router. Functions of the control plane include system configuration and management. - -#### core node -A server that runs Stacks Blockchain services. - -#### crypto-asset -A digital asset which utilises cryptography, peer-to-peer networking and a public ledger to regulate the creation of new units, verify transactions and secure the transactions without the intervention of any middleman. - -#### cryptography -The practise and study of encryption and decryption - encoding data so that it can only be decoded by specific individuals. A system for encrypting and decrypting data is a cryptosystem. - -#### DAO -See Decentralized Autonomous Organization. - -#### decentralized application (DApp) -A DApp is a service that enables direct interaction between end users and providers (e.g. connecting buyers and sellers in some marketplace, owners and stores in file storage). A term coined by Ethereum. See their glossary: http://ethdocs.org/en/latest/glossary.html#dapp" - -#### Decentralized Autonomous Organization -A type of contract or suite of contracts on the blockchain that is intented to codify, enforce or automate the processes of an organization. - -#### digital asset -Also referred to as a crypto-asset. Any set of unique digital information—including, for example, programs, decentralized programs, isolated chunks of programming code, collections of data, e-mail or web addresses or cryptocurrency tokens—that is capable of being stored and uniquely tracked on a computer network such as the Stacks network and over which a user can maintain control through that network. - -#### digital fingerprint -A digital fingerprint is a unique number of a fixed length that can be produced by running any set of digital information through something called a cryptographic hash function. Each set of digital information (including a digital asset, and the digital record of any network operation on that digital asset) should (as a practical matter) have a unique digital fingerprint, which allows that set of digital information to be identified. However, it is almost impossible to recreate a digital asset from its digital fingerprint. The Blockstack network uses industry-standard algorithms such as SHA-256 to create digital fingerprints. - -#### digital signature -A digital signature is a sequence of digital information combining a user’s private key and any digital information that the user wishes to sign. Any other party can use the user’s paired public key to verify that the digital signature is authentic, i.e. that the public key was generated from a particular piece of digital information and the user’s private key. - -#### distributed hash tables (DHT) -A form of network used to store some content in the form of key/value pairs. ... This experimental project try to avoid keeping all the blockchain, but instead prefers to store it in a DHT. - -#### ephemeral key -A cryptographic key is called ephemeral if it is generated for each execution of a key establishment process. - -#### fork -The term fork is used to refer both to any situation where there are two or more competing versions of a blockchain on a network (a situation that may arise and resolve itself in the ordinary course of network operations due to lags in communication between core nodes) and any software update that is proposed for adoption by the core nodes of a blockchain network that may result in a persistent fork on the network, with core nodes that adopt the update recognizing one version of the blockchain and those which do not recognizing another. - -#### Gaia -Decentralized storage architecture for off-chain data. More info [here](../gaia). - -#### genesis block -The genesis block is the first block of the Stacks blockchain, which will create the initial 1.32 billion Stacks Tokens. - -#### id.blockstack -An identifier in the Blockstack, for example meepers.id.blockstack. This is your name & identity that is registered in the .id namespace on Blockstack. Your personal data and storage are built around this ID. Apps that want to access your data use your permission and identity to find it. An id is usually a shorthand for a longer, hash ID string, for example ID-1Fj9kkw15P51Fj9kkw15P5xJmyefWhLKrQMKNPREfaqsJ" - -#### identity - -A way to identify a person or an organization on the Stacks network. An identity is unique, both `meepers.id.blockstack` or `chad.id` are examples of IDs. - -#### identity management (IDM) -Identity management, also known as identity and access management is, in computer security, the security and business discipline that enables the right individuals to access the right resources at the right times and for the right reason". - -#### know your customer (KYC) -Or KYC, is a popular term used in the banking or financial field. KYC is a process where financial institutions, insurers and other companies obtain information about the identity and address of the customers as part of risk management. - -#### light clients -Clients that can independently validate the existence of transactions by downloading only block headers and not the entire blockchain. - -#### magic recovery code - -A long encrypted string, for example: `36mWivFdy0YPH2z31EflpQz/Y0UMrOrJ++lH=0EI7c3mop2JuRBm5WXxSTazJsUjOA...` Do not share the QR code that accompanied your recovery code either. This is a QR code: - -![](/img/qr-code.png) - -#### mesh network -A local network topology in which the infrastructure nodes (i.e. bridges, switches, and other infrastructure devices) connect directly, dynamically and non-hierarchically to as many other nodes as possible and cooperate with one another to efficiently route data from/to clients. - -#### mining -Mining generally refers to the process of performing certain functions for a network such as adding new records to a blockchain in exchange for mining rewards; it may also refer to other mechanisms whereby rewards (usually in the form of cryptocurrency) are provided for performing other tasks helpful to the network. - -#### mining power -A miner’s (or group of miners’) mining power is equal to the probability it will be selected to write a new block to the blockchain. Depending on the mechanism for mining, this is usually related to the overall share of computing power or cryptoassets the miner or miners possess relative to all miners for that blockchain. - -#### mining rewards -Mining rewards are newly issued tokens received by miners in exchange for adding new records to the blockchain or other activities beneficial to the network. - -#### name -An identifier or name. Names are a type of digital asset in the Stacks network. If you have signed into the Stacks Wallet, you might have created a name. If an application developer registered an application within Stacks, then they registered a name. Public Stacking pools can also have a name. - -#### network operation -A network operation is any change to the information about a digital asset (or smart contract) stored on a blockchain, including, for example, a change in the digital asset’s owner, or a change in the location at which it is stored on the network. How and when these network operations are performed for each digital asset is governed, on the Blockstack network, either by the Stacks Node software or a smart contract. - -#### NFT -Non fungible token. - -#### private key - -Private keys matches a corresponding public key. A public key also looks like a string of letters and numbers: - -![](/img/private.png) - -The exact format of the public and private key depend on the software you use to create them. - -#### proof-of-burn mining -The consensus algorithm used in the Stacks blockchain where miners destroy a proof-of-work-based cryptocurrency (currently Bitcoin) to get tokens; this enables the functionality where nodes can select between conflicting blockchain forks, as the blockchain fork with the most amount of cryptocurrency burned is considered to be the correct fork. - -#### proof-of-work -A proof-of-work system or proof-of-work mining is a mining mechanism where miners must expend computing power to solve complicated cryptographic puzzles, and prove that they have done so by writing the solution to the blockchain, in order to be allowed to add blocks to a blockchain. This is the mining system used, for example, by Bitcoin. - -#### public key -Public and private key pair comprise of two uniquely related cryptographic keys. It looks like a long random string of letters and numbers: `3048 0241 00C9 18FA CF8D EB2D EFD5 FD37 89B9 E069 EA97 FC20 … ` The exact format of the public and private key depend on the software you use to create them. - -#### Public Key Infrastructure (PKI) -A system which returns a cryptographic public key associated with a name. - -#### replicated state machines (RSMs) -This is a model for reasoning about distributed computer programs -- any program (plus it's input) can be represented as a state machine, and when trying to get a distributed set of servers to agree on the output of an algorithm, you can model that process as N different state machines" - -#### Secret recovery Key, -Used to access an identity on the Stacks blockchain. A 24-word sequence of words for example: `applied binge crisp pictorial fiery` `dancing agreeable frogs light finish ping apple` - -#### seed phrase - -Used to access Stacks Wallet software. The seed phrase consists of 24 words in a sequence. Both the word *and its position the sequence* are important. Write down your seed phrase and store it in a secure location such as a safe deposit box. When you write the seed phrase down, include its position, for example,`1-frog, 2-horse, 3-building` and so on until you reach a final position `24-ocean`. -#### smart contract -A smart contract is a computer program written to a blockchain such as the Stacks blockchain by developers. This computer program defines the various network operations that can be performed on the digital assets on the blockchain, the computations that can be performed using the smart contract, along with defining various important properties of the respective digital assets like ownership rights and the cost in fuel required to register the digital assets. - -#### soft fork -A soft fork is a proposed update to the software governing the network that results in a post-update network that is compatible with the network as it existed prior to the update, because it restricts the network operations that can be performed after the update. - -#### Stacks (STX) address - - A STX address is a string of letters and numbers starting with an `SP` or `SM`, for example: `SM3KJBA4RZ7Z20KD2HBXNSXVPCR1D3CRAV6Q05MKT` If you created a software-only wallet with the Stacks Wallet software, the wallet has a single STX address which is also sometimes called the *wallet address*. You access a software wallet with a *seed phrase*. " - -#### Stacks blockchain -The Stacks blockchain is the custom blockchain being developed for use by the Stacks network that will use the Stacks token as its native currency and which will include the genesis block and subsequent blocks created by the mining activities described in the Stacks Network—Development of the Stacks network. - -#### Stacks Explorer -An application that allow you to view and search transactions in the blockchain. For example, https://explorer.stacks.co. - -#### Stacks node -A complete version of our open-source software available on Github at https://github.com/stacks-network/stacks-blockchain/ that governs the creation of the blockchain, the smart contracts that may be written to our blockchain, and other systems that make up the Stacks network, when run on the systems and devices of our users and developers. - -#### Stacks wallet -An application for accessing assets, identity and storage. Examples are the [Hiro Wallet](https://www.hiro.so/wallet), [xverse](https://www.xverse.app/) and [dcent](https://dcentwallet.com/). More information and example [here](../services-using-stacks/wallets). - -#### storage hub -A Gaia instance run by a hub provider or software. A Gaia hub stores data in a separate, addressed location. - -#### storage provider -A third-party company cloud or software provider that hosts one or more Gaia storage hubs. - -#### transaction -A transaction is a unit of work within a block. - -#### transaction fee -Fees paid by participants in a transaction to miners. - -#### two-sided market problem -Economic platforms having two distinct user groups that provide each other with network benefits. The Stacks platform is a classic two-sided market. - -#### username -A shorthand name for your id.blockstack. - -#### virtual blockchain -A layer that sits on top of a blockchain that introduces new functionality and operations without requiring changes to the underlying blockchain. - -#### wallet address -A wallet address is the form in which a public key can be presented and recorded on a blockchain. Wallet addresses are therefore used to assign the ownership of digital assets on the Blockstack network. - -#### watch-only wallet -A wallet without send and receive ability. You can view only balances and transaction history. - -#### web of trust mining -Web-of-trust mining provides incentive mechanisms for users where an initial trusted-set of unique users is curated in the genesis block and, in the future, the initial set of users can expand the web-of-trust after the network goes live. - -#### web3 -The exact definition is still under discussion, but it general refers to the 3rd generation of the web that is based on blockchain technology and incorporates decentralized and token-based economics. - -#### zone file -A Domain Name System (DNS) zone file is a text file that describes a DNS zone. A DNS zone is a subset, often a single domain, of the hierarchical domain name structure of the DNS. diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/references/nft.md b/i18n/ja/docusaurus-plugin-content-docs/current/references/nft.md deleted file mode 100644 index 033ee0a71a..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/references/nft.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: NFTs on Stacks -description: A list of sites that operate NFTs on Stacks ---- - -List of sites that operate NFTS on Stacks on alphabetical order. - -### [Byzantion](https://byzantion.xyz/) - -![website-screenshot](/img/sh_nft_byzantion.png) - -### [Gamma](https://gamma.io/) -![website-screenshot](/img/sh_nft_gamma.png) - -### [Megapont](https://www.megapont.com/) - -![website-screenshot](/img/sh_nft_megapont.png) - -### [StacksArt](https://www.stacksart.com/) - -![website-screenshot](/img/sh_nft_stacksart.png) - diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md b/i18n/ja/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md deleted file mode 100644 index dc6e507d5e..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Stacks info sites -description: A list of sites on alphabetical order that display status and stats of the Stacks network. ---- - -### [Haystack](https://haystack.tools/mempool) - -![website-screenshot](/img/sh_haystacks.png) - -### [Stacksdata](https://stacksdata.info/) - -![website-screenshot](/img/sh_stacksdata.png) - -### [Stacksonchain](https://stacksonchain.com) - -![website-screenshot](/img/sh_stacksonchain.png) - -### [Status Hiro](https://status.hiro.so/) - -![website-screenshot](/img/sh_statushiro.png) - -### [Stxstats](https://www.stxstats.co/) - -![website-screenshot](/img/sh_stxstats.png) - -### [Novuminsights](https://stacks.novuminsights.com/health) - -![website-screenshot](/img/sh_novuminsights.png) - -### [Onstacks](https://app.onstacks.com/) - -![website-screenshot](/img/sh_onstacks.png) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json b/i18n/ja/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json deleted file mode 100644 index ebd63f366c..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Services using Stacks", - "position": 8, - "link": { - "type": "generated-index", - "description": "An 'always incomplete' list of services that use Stacks." - } -} \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md b/i18n/ja/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md deleted file mode 100644 index 51defacba7..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: DeFi -description: De-Fi sites on Stacks -sidebar_position: 2 ---- - -They are multiple De-Fi sites that operate on the Stacks blockchain. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Alex - -[Alex](https://app.alexlab.co) ![](/img/sh_alex.png) - -## Arkadiko - -[Arkadiko](https://arkadiko.finance/) ![](/img/sh_arkadiko.png) - -## Catamaran Swaps - -[Catamaran Swaps](https://www.catamaranswaps.org/) allows trustless exchange of digital assets. - -![](/img/sh_catamaran.png) - -## Lnswap - -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange - -![](/img/sh_lnswap.png) - -## Neoswap - -[Neoswap](https://neoswap.party) - -![](/img/sh_neoswap.png) - -## Stackswap - -[Stackswap](https://app.stackswap.org/v2) - -![](/img/sh_stackswap.png) - diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/services-using-stacks/more.md b/i18n/ja/docusaurus-plugin-content-docs/current/services-using-stacks/more.md deleted file mode 100644 index df0b3e2254..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/services-using-stacks/more.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: More -description: More services built on Stacks. -sidebar_position: 5 ---- - -List of sites on alphabetical order added by the community. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Citycoins - -[Citycoins](https://citycoins.co) - -![](/img/sh_citycoins.png) - -## Sigle - -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. - -![](/img/sh_sigle.png) \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md b/i18n/ja/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md deleted file mode 100644 index bfa0505dc9..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: NFTs -description: NFTs on Stacks -sidebar_position: 3 ---- - -List of sites that operate NFTS on Stacks on alphabetical order. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -### [Byzantion](https://byzantion.xyz/) - -![website-screenshot](/img/sh_nft_byzantion.png) - -### [Gamma](https://gamma.io/) -![website-screenshot](/img/sh_nft_gamma.png) - -### [Megapont](https://www.megapont.com/) - -![website-screenshot](/img/sh_nft_megapont.png) - -### [StacksArt](https://www.stacksart.com/) - -![website-screenshot](/img/sh_nft_stacksart.png) - -### [Superfandom](https://superfandom.io/) - -![website-screenshot](/img/sh_superfandom.png) \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/services-using-stacks/other.md b/i18n/ja/docusaurus-plugin-content-docs/current/services-using-stacks/other.md deleted file mode 100644 index 199fc41da5..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/services-using-stacks/other.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Other Stacks sites -description: A list of sites on alphabetical order built on Stacks. -sidebar_position: 4 ---- - -List of sites on alphabetical order added by the community. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Alex -[Alex](https://app.alexlab.co) - -## Sigle - -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md b/i18n/ja/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md deleted file mode 100644 index 35ced8dac6..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Stacks info sites -description: Status and stats of the Stacks network. -sidebar_position: 1 ---- - -A list of sites on alphabetical order that display status and stats of the Stacks network. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -### [Haystack](https://haystack.tools/mempool) - -![website-screenshot](/img/sh_haystacks.png) - -### [Stacksdata](https://stacksdata.info/) - -![website-screenshot](/img/sh_stacksdata.png) - -### [Stacksonchain](https://stacksonchain.com) - -![website-screenshot](/img/sh_stacksonchain.png) - -### [Status Hiro](https://status.hiro.so/) - -![website-screenshot](/img/sh_statushiro.png) - -### [Stxstats](https://www.stxstats.co/) - -![website-screenshot](/img/sh_stxstats.png) - -### [Novuminsights](https://stacks.novuminsights.com/health) - -![website-screenshot](/img/sh_novuminsights.png) - -### [Onstacks](https://app.onstacks.com/) - -![website-screenshot](/img/sh_onstacks.png) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md b/i18n/ja/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md deleted file mode 100644 index d4b4cbf18c..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Swaps -description: A list of sites that allow Swaps -sidebar_position: 2 ---- - -They are multiple sites that allow you to make swaps using the Stacks blockchain. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Catamaran Swaps - -[Catamaran Swaps](https://www.catamaranswaps.org/) allows trustless exchange of digital assets. - -![](/img/sh_catamaran.png) - -## Lnswap - -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange - -![](/img/sh_lnswap.png) - -## Neoswap - -[Neoswap](https://neoswap.party) - -![](/img/sh_neoswap.png) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md b/i18n/ja/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md deleted file mode 100644 index e5ea6c5b45..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Wallets -description: Wallets for Stacks -sidebar_position: 4 ---- - -A list of hardware and software wallets for Stacks - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Blockchain.com - -[Blockchain.com](https://www.blockchain.com/wallet) - -![](/img/sh_blockchain.png) -## Boom - -[Boom](https://boom.money) - -![](/img/sh_boom.png) - -## Dcent wallet - -[D'CENT](https://dcentwallet.com) - -![](/img/sh_dcent.png) -## Hiro Wallet - -[Hiro Wallet](https://www.hiro.so/wallet) - -![](/img/sh_hirowallet.png) - -## Neptune - -[Neptune](https://neptunewallet.io) - -![](/img/sh_neptunewallet.png) - -## Xverse - -[Xverse](https://www.xverse.app/) - -![](/img/sh_xverse.png) - -## Wise - -[Wise](https://wiseapp.id) - -![](/img/sh_wiseapp.png) \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md b/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md deleted file mode 100644 index bd2c361985..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md +++ /dev/null @@ -1,214 +0,0 @@ ---- -title: Accounts -description: Guide to Stacks 2.0 accounts -sidebar_position: 5 ---- - -## Introduction - -Stacks 2.0 accounts are entities that own assets, like Stacks (STX) tokens. An account has an address, private key, nonce, and one or more asset balances. - -:::tip The encryption algorithm used in Stacks 2.0 is **[secp256k1](https://en.bitcoinwiki.org/wiki/Secp256k1)**. - -Additionally, [Ed25519](https://ed25519.cr.yp.to/) is also used just for the VRF (Verifiable Random Function). ::: - -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. - -:::tip -The transaction type doesn't need to be a token transfer - contract deploy and contract call transactions can change the balances of an account -::: - -## Creation - -An account is generated from a 24-word mnemonic phrase. This is often referred to as the **seed phrase**. The seed phrase provides access to Stacks 2.0 accounts. - -:::danger -If the seed phrase is lost, access to the associated account cannot be restored. No person or organization, including Blockstack, can recover a lost seed phrase. -::: - -The easiest way to generate a new Stacks 2.0 account is to use the [Stacks CLI](https://github.com/hirosystems/stacks.js/tree/master/packages/cli): - -```bash -# install CLI globally -npm install --global @stacks/cli - -# generate a new account and store details in a new file -# '-t' option makes this a testnet account -stx make_keychain -t > cli_keychain.json -``` - -`make_keychain` creates the following file: - -```js -{ - "mnemonic": "aaa bbb ccc ddd ...", - "keyInfo": { - "privateKey": "5a3f1f15245bb3fb...", - "address": "STJRM2AMVF90ER6G3RW1QTF85E3HZH37006D5ER1", - "btcAddress": "biwSd6KTEvJcyX2R8oyfgj5REuLzczMYC1", - "wif": "L4HXn7PLmzoNW...", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -| Field | Description | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `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.privateKey` | Private key for the account. Required for token transfers and often referred to as `senderKey` | -| `keyInfo.address` | Stacks address for the account | -| `keyInfo.btcAddress` | Corresponding BTC address for the account. | -| `keyInfo.wif` | Private key of the btcAddress in compressed format. | -| `keyInfo.index` | Nonce for the account, starting at 0 | - -Note that a new account automatically exists for each new private key. There is no need to manually instantiate an account on the Stacks 2.0 blockchain. - -:::tip Addresses are created by generating the [RIPEMD-160 hash](https://en.wikipedia.org/wiki/RIPEMD#RIPEMD-160_hashes) of the [SHA256](https://en.bitcoinwiki.org/wiki/SHA-256) of the public key. BTC addresses are encoded with [Base58Check](https://en.bitcoin.it/wiki/Base58Check_encoding). For Stacks addresses, [c32check](https://github.com/stacks-network/c32check) is used. Deriving an address from a public key can be done without internet access, for instance using the c32check `c32addressDecode` method. ::: - -Alternatively to the CLI creation, the [Stacks Transactions JS](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library can be used: - -```js -import { - makeRandomPrivKey, - privateKeyToString, - getAddressFromPrivateKey, - TransactionVersion, -} from '@stacks/transactions'; - -const privateKey = makeRandomPrivKey(); - -// Get public key from private -const publicKey = getPublicKey(privateKey); - -const stacksAddress = getAddressFromPrivateKey( - privateKeyToString(privateKey), - TransactionVersion.Testnet // remove for Mainnet addresses -); -``` - -A second alternative would be to use [stacks-gen](https://github.com/psq/stacks-gen). This tool will generate all the keys you need in one place, including the values needed for calling the stacking contract, and also a WIF key for use with `bitcoind`. - -#### stacks-gen prerequisite - -Install [npx](https://github.com/npm/npx) if not already installed. (npx will check whether `` exists in \$PATH, or in the local project binaries, and execute that. If `` is not found, it will be installed prior to execution). - -``` -npm install -g npx -``` - -#### stacks-gen usage - -``` -npx -q stacks-gen sk --testnet - -{ - "phrase": "guide air pet hat friend anchor harvest dog depart matter deny awkward sign almost speak short dragon rare private fame depart elevator snake chef", - "private": "0351764dc07ee1ad038ff49c0e020799f0a350dd0769017ea09460e150a6401901", - "public": "022d82baea2d041ac281bebafab11571f45db4f163a9e3f8640b1c804a4ac6f662", - "stacks": "ST16JQQNQXVNGR8RZ1D52TMH5MFHTXVPHRV6YE19C", - "stacking": "{ hashbytes: 0x4d2bdeb7eeeb0c231f0b4a2d5225a3e3aeeed1c6, version: 0x00 }", - "btc": "mnYzsxxW271GkmyMnRfiopEkaEpeqLtDy8", - "wif": "cMh9kwaCEttgTQYkyMUYQVbdm5ZarZdBHErcq7mXUChXXCo7CFEh" -} -``` - -:::tip The stacking object with hashbytes and a version represents the bitcoin address derived from the Stacks address. Read more about the [bitcoin address format](stacking#bitcoin-address). ::: - -Full documentation available at [stacks-gen](https://github.com/psq/stacks-gen). - -## Querying - -### Get Stacks (STX) balance and nonce - -STX balance and nonce can be obtained through the [`GET /v2/accounts/`](https://docs.hiro.so/api#operation/get_account_info) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/accounts/' -``` - -Sample response: - -```js -{ - "balance": "0x0000000000000000002386f26f3f40ec", - "nonce": 17 -} -``` - -:::tip -The balance string represents an unsigned 128-bit integer (big-endian) in hex encoding -::: - -### Get all token balances - -All token balances can be obtained through the [`GET /extended/v1/address//balances`](https://docs.hiro.so/api#operation/get_account_balance) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/address//balances' -``` - -Sample response: - -```js -{ - "stx": { - "balance": "0", - "total_sent": "0", - "total_received": "0" - }, - "fungible_tokens": {}, - "non_fungible_tokens": {} -} -``` - -:::tip Stacks accounts cannot hold bitcoins. The best way to obtain corresponding BTC balances is to derive the BTC address from the Stacks address (using [`c32check`](https://github.com/stacks-network/c32check#c32tob58-b58toc32)) and query the Bitcoin network. ::: - -### Get all asset events - -All asset events associated with the account can be obtained through the [`GET /extended/v1/address//assets`](https://docs.hiro.so/api#operation/get_account_balance) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/address//assets' -``` - -Sample response: - -```js -{ - "limit": 20, - "offset": 0, - "total": 0, - "results": [ - { - "event_index": 5, - "event_type": "non_fungible_token_asset", - "asset": { - "asset_event_type": "transfer", - "asset_id": "ST2W14YX9SFVDB1ZGHSH40CX1YQAP9XKRAYSSVYAG.hello_world::hello-nft", - "sender": "SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR", - "recipient": "SM2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQVX8X0G", - "value": { - "hex": "0x0100000000000000000000000000000001", - "repr": "u1" - } - } - }, - { - "event_index": 3, - "event_type": "fungible_token_asset", - "asset": { - "asset_event_type": "mint", - "asset_id": "ST2W14YX9SFVDB1ZGHSH40CX1YQAP9XKRAYSSVYAG.hello_world::novel-token-19", - "sender": "", - "recipient": "SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR", - "amount": "12" - } - } - ] -} -``` diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/index.md b/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/index.md deleted file mode 100644 index 1533219df9..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/index.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Understand Stacks -description: Learn more about the Stacks 2.0 blockchain -sidebar_position: 1 ---- - -![](/img/SBC-L-2x-10.png) -## Introduction - -Stacks 2.0 is a layer-1 blockchain that connects to Bitcoin and brings smart contracts and decentralized apps to it. Smart contracts and apps developed on the Stacks platform are natively integrated with the security, stability, and economic power of Bitcoin. - -## Capabilities - -Read more about the features provided by the Stacks 2.0 blockchain. - - - -:::tip Check out the [technical specifications](technical-specs) for a brief overview ::: - - - - -A detailed [comparison of the Stacks blockchain to other blockchain technologies][] is available at the Stacks Foundation blog. -### Consensus mechanism -![](/img/pages/stacking.svg) Stacks 2.0 implements a new mining mechanism called Proof of Transfer ("PoX"). PoX is a consensus algorithm between two blockchains. It uses an established blockchain (in this case Bitcoin) to secure a new blockchain (Stacks). - -PoX connects to Bitcoin with a 1:1 block ratio, meaning anything that happens on the Stacks blockchain can be verified on the Bitcoin Blockchain. - -Instead of burning electricity on proof of work, PoX reuses already minted bitcoins as "proof of computation" and miners represent their cost of mining in bitcoins directly. - - -[Read more about Proof of Transfer](proof-of-transfer) -### Mining - -![](/img/pages/testnet-sm.svg) Mining is required to make the network usable, trustworthy, and secure. Miners verify incoming transactions, participate in the consensus mechanism, and write new blocks to the blockchain. - -To incentivize mining, miners receive freshly minted Stacks (STX) tokens if they win the bid for becoming the leader of the next round. - -[Read more about Mining](mining) - -### Stacking - -Bitcoins used for miner bids are sent to a set of specific addresses corresponding to Stacks (STX) tokens holders that are actively participating in consensus ("Stackers"). Thus, rather than being destroyed, the bitcoins consumed in the mining process go to productive Stacks holders as a reward based on their holdings of Stacks and participation in the Stacking algorithm. - -Stackers have to lock up their Stacks (STX) tokens for a certain period of time. - -[Read more about Stacking](stacking) - -### Smart contracts - -![](/img/pages/write-smart-contracts-sm.svg) Clarity is a new language for smart contracts on the Stacks 2.0 blockchain. The Clarity smart contract language optimizes for predictability and security. - -Stacks 2.0 anchors clarity smart contracts to Bitcoin making it possible for smart contracts to operate based on actions seen on the bitcoin blockchain. - -:::note The [Clarity open-source project](https://clarity-lang.org/) is supported by Stacks and [Algorand](https://www.algorand.com/) ::: - - -Clarity is distinct from other languages designed for writing smart contracts in a few ways: - -- **Predictability**: The Clarity language uses precise and unambiguous syntax that allows developers to predict exactly how their contracts will be executed. -- **Security**: The Clarity language allows users to supply their own conditions for transactions that ensure that a contract may never unexpectedly transfer a token owned by a user. -- **No compiler**: Contracts written in Clarity are broadcasted on the Stacks blockchain exactly as they are written by developers. This ensures that the code developers wrote, analyzed, and tested, is exactly what gets executed. - -[Read more about Clarity](../write-smart-contracts/clarity-language/) - -## Guides - -Read one of our guides to understand the ins and outs of the Stacks 2.0 blockchain. - -* [Account](../understand-stacks/accounts) -* [Transactions](../understand-stacks/transactions) -* [Network](../understand-stacks/network) -* [Microblocks](../understand-stacks/microblocks) - -[comparison of the Stacks blockchain to other blockchain technologies]: https://stacks.org/stacks-blockchain diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md b/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md deleted file mode 100644 index de64c617f4..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: Microblocks -description: Guide to Stacks Microblocks -sidebar_position: 8 ---- - -## Introduction - -Microblocks are a protocol-level feature of the Stacks blockchain that solve the technical challenge of transaction latency. Because each Stacks block is anchored to a Bitcoin block through the [Proof-of-Transfer consensus mechanism](../understand-stacks/proof-of-transfer), Stacks is necessarily limited to the same block times as the Bitcoin network. Microblocks allow the Stacks blockchain to perform state transitions between anchor blocks. - -Microblocks are a powerful mechanism for developers to create performant, high quality applications on Stacks, while still inheriting the security of Bitcoin. - -## Transaction states - -The [Stacks block production model](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.) is described in SIP-001. The standard outlines the mechanism by which elected block leaders can produce blocks on the Stacks blockchain either by batching transactions or by streaming them. Microblocks are the product of the streaming model. - -If a block leader has elected to mine microblocks, the leader selects transactions from the mempool and package them into microblocks during the current epoch. Microblocks are blocks of transactions included by a miner after the previous anchor block has been mined, but before the next block is selected. Transactions included in microblocks are processed by the network: their results are known. - -Consider a transaction from the perspective of the number of block confirmations it has. A transaction included in a microblock might have the following example lifecycle: - -``` -Transaction 1 is broadcast to the mempool. It has 0 confirmations. -Transaction 1 is included in a microblock. It still has 0 confirmations, but the results of the transaction are known -Transaction 1 is included in the next anchor block. It has 1 confirmation. -The next Stacks block confirms the previous block. Transaction 1 has 2 confirmations. -The next Stacks block confirms the previous block. Transaction 1 has 3 confirmations. -... -``` - -Consider a similar transaction that is not included in a microblock: - -``` -Transaction 2 is broadcast to the mempool. It has 0 confirmations. -Transaction 2 is included in the next anchor block. It has 1 confirmation. -The next Stacks block confirms the previous block. Transaction 2 has 2 confirmations. -The next Stacks block confirms the previous block. Transaction 2 has 3 confirmations. -``` - -The lifecycles of the two transactions are similar, but the difference is pending state. Many Bitcoin wallets display 0-confirmation balances: your wallet balance with any mempool transactions already applied. This is useful because it tells you when you've sent a transaction or received one. With smart contracts, displaying pending state is not as straightforward, because smart contracts do not just transfer inputs to outputs, they may call other contracts, emit events, or perform other computations. A transaction processed in a microblock generates all that information. - -:::tip -If a transaction is dependent on a chain state that could by altered by previous transactions with serious -implications, you should carefully consider whether it should be performed using microblocks. -::: - -## Enabling microblocks - -Miners can choose to enable or disable microblocks in their mining configuration. As a best practice, miners should enable microblock mining. When an application or user submits a transaction, the transaction can include an argument that requires the transaction to be in a microblock, an anchor block, or in either. - -### Transactions - -Transactions include an option that controls if a miner should include them in microblocks or in anchor blocks. The anchor mode transaction option is an optional argument that controls whether a transaction must be included in an anchor block or a microblock, or is eligible for either. - -### Mining - -Stacks miners must enable microblocks in their miner configuration to implement the block streaming model. For more information, see [mining microblocks](../understand-stacks/mining#microblocks). - -## Developing with microblocks - -In most cases, information from transactions included in microblocks should be treated like information from any other block. Wallets and explorers should display the consequences of microblock transactions as the current state of the network. This state should be acknowledged as tentative. - -A microblock transaction can end up being reorganized in the next block rather than just being confirmed as-is. Because of this, your UI should communicate to users if the outputs of a transaction changed, or if the transaction's associated block changed. This is the same outcome as if a 1-block fork occurred. - -### Stacks.js libraries - -Stacks.js provides the [AnchorMode][] argument on transaction objects so that your application can set the microblocks preference for transactions. - -### API - -:::danger API support for microblocks is a work-in-progress. Review the [API documentation][microblocks_api] carefully to ensure that you are up-to-date on the latest implementation details for microblocks. ::: - -The Stacks Blockchain API exposes microblocks through several endpoints. Please review the [Stacks Blockchain API guide][] for more details. - -## Best practices - -Working with microblocks is a design decision that you must make for your own application. When working with microblocks, the following best practices are recommended. - -### Handling nonce - -Nonce handling with microblocks is challenging because the next account nonce must take into account any nonce values included in microblocks, which may not yet be included in an anchor block. The Stacks Blockchain API [provides an endpoint][] to retrieve the next nonce for a given principal. - -### Application design - -The state of microblock transactions should be carefully communicated to users. No transaction is final until it's included in an anchor block, and your application design should reflect this. - -The following guidelines are provided as an initial set of best practices for UI design when incorporating microblocks into your application. - -#### Explorers - -Display pending state, but warn that a transaction is still pending. Indicate visually that displayed balances depend on pending state. - -#### Wallets - -Display pending state, but warn that a transaction is still pending. Indicate visually that displayed balances depend on pending state. - -#### Exchanges - -Continue to count confirmations, microblocks should be considered pending. - -#### Applications - -Microblock communication is highly app-dependent. For some applications, displaying a pending or 0-confirmation transaction as confirmed may be fine. For example, storing data on the chain, or querying the BNS contract. For other applications, such as the transfer of real value, waiting for 3-confirmations would be prudent before displaying the state as confirmed. - -[AnchorMode]: https://stacks.js.org/enums/transactions.AnchorMode.html -[Stacks Blockchain API guide]: https://docs.hiro.so/get-started/stacks-blockchain-api#microblocks-support -[provides an endpoint]: https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling -[microblocks_api]: https://docs.hiro.so/api#tag/Microblocks diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/mining.md b/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/mining.md deleted file mode 100644 index fa1f56ed3f..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/mining.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Mining -description: A guide to mining on Stacks 2.0 -sidebar_position: 4 ---- - -## Introduction - -This guide highlights some technical details related to mining on the Stacks 2.0 network. - -For steps on how to setup your own miner please refer to [miner on tesnet](nodes-and-miners/miner-testnet.md) and [miner on mainnet](nodes-and-miners/miner-testnet.md). - -## Mining frequency - -A new Stacks block may be mined once per Bitcoin block. To be considered for mining a block, a miner must have a block commit included in a Bitcoin block. If a miner wishes to update their commitment after submission, they may use Bitcoin Replace-By-Fee. - -## Coinbase rewards - -Miners receive coinbase rewards for blocks they win. - -The reward amounts are: - -- 1000 STX per block are released in the first 4 years of mining -- 500 STX per block are released during the following 4 years -- 250 STX per block are released during the following 4 years -- 125 STX per block are released from then on indefinitely. - -These "halvings" are synchronized with Bitcoin halvings. - -![coinbase rewards](/img/pages/coinbase-rewards.png) - -## Transaction fees - -Miners receive Stacks fees for transactions mined in any block they produce. - -For transactions mined in microblocks, the miner that produces the microblock receives 40% of the fees, while the miner that confirms the microblock receives 60% of the fees. - -## Reward maturity - -Block rewards and transaction fees take 100 blocks on the Bitcoin blockchain to mature. After successfully mining a block your rewards appear in your Stacks account after ~24 hours. - -## Mining with proof-of-transfer - -Miners commit Bitcoin to **two** addresses in every leader block commit. The amount committed to each address must be the same. The addresses are chosen from the current reward set of stacking participants. Addresses are chosen using a verifiable-random-function, and determining the correct two addresses for a given block requires monitoring the Stacks chain. - -![mining with pox](/img/pages/mining-with-pox.png) - -## 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, 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. - -While there is no minimum BTC commitment enforced by the protocol, in practice, there's a floor constrained by [dust](https://unchained-capital.com/blog/dust-thermodynamics/)": basically, if the fees for a transaction exceed the value of the spent output, it's considered dust. How dust is [calculated](https://github.com/bitcoin/bitcoin/blob/master/src/policy/policy.cpp#L14) depends on a number of factors, we've found 5,500 satoshis to be good lower bound per [output](https://learnmeabitcoin.com/technical/output). Bitcoin transactions from Stacks miners contain two outputs (for Proof-of-Transfer), so a commitment of at least 11,000 satoshis / block is recommended. - -To calculate the amount of BTC to send miners should: - -- Guess the price BTC/STX for the next day (100 blocks later) -- Guess the total amount of BTCs committed by all miners - -## Microblocks - -The Stacks blockchain produces blocks at the same rate as the Bitcoin blockchain. In order to provide lower latency transactions, miners can opt to enable microblocks. Microblocks allow the current block leader to stream transactions and include their state transitions in the current epoch. - -If a block leader opts to produce microblocks, the next leader builds the chain tip off the last microblock that the current leader produces. - -The block streaming model is described in [SIP-001][]. - -[SIP-001]: https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md#operation-as-a-leader diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/network.md b/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/network.md deleted file mode 100644 index 6efcc385ec..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/network.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: Network -description: Guide to the Stacks 2.0 network -sidebar_position: 7 ---- - -## Tokens - -Stacks (STX) tokens are the native tokens on the Stacks 2.0 blockchain. The smallest fraction is one micro-STX. 1,000,000 micro-STX make one Stacks (STX). - -STX amounts should be stored as integers (8 bytes long), and represent the amount of micro-STX. For display purposes, micro-STX are divided by 1,000,000 (decimal precision of 6). - -## 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 in bytes. The fee rate is a market determined variable. For the [testnet](testnet), it is set to 1 micro-STX. - -Fee estimates can obtained through the [`GET /v2/fees/transfer`](https://docs.hiro.so/api#operation/get_fee_transfer) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/fees/transfer' -``` - -The API will respond with the fee rate (as integer): - -```json -1 -``` - -[The Stacks Transactions JS library](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) supports fee estimation for: - -- token transfers (`estimateTransfer`) -- contract deploys (`estimateContractDeploy`) -- non read-only contract calls (`estimateContractFunctionCall`) - -:::tip For an implementation using a different language than JavaScript, please review [this reference implementation](https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/src/builders.ts#L97). ::: - -## Nonces - -Every account carries a [nonce property](https://en.wikipedia.org/wiki/Cryptographic_nonce) that indicates the number of transactions processed for the given account. Nonces are one-time codes, starting at `0` for new accounts, and incremented by 1 on every transaction. - -Nonces are added to all transactions and help identify them in order to ensure transactions are processed in order and to avoid duplicated processing. - -:::tip -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 is constructed, the most recent nonce of the account needs to fetched and set. - -:::tip The API provides an endpoint to [simplify nonce handling](https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling). ::: - -## Confirmations - -The Stacks 2.0 network is anchored onto the bitcoin network. This allows transactions on Stacks to inherit the same finality and security of the Bitcoin blockchain. - -The time to mine a block, to confirm transactions, will eventually match the expected "block time" of the bitcoin network: 10 minutes. - -:::tip Transactions can also be mined in [microblocks](microblocks), reducing the latency significantly. ::: - -The block time is hardcoded and will change throughout the implementation phases of the [testnet](testnet). The current block time can be obtained through the [`GET /extended/v1/info/network_block_times`](https://docs.hiro.so/api#operation/get_network_block_times) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/info/network_block_times' -``` - -The API will respond with the block time (in seconds): - -```js -{ - "testnet": { - "target_block_time": 120 - }, - "mainnet": { - "target_block_time": 600 - } -} -``` - -## Read-only function calls - -Smart contracts can expose public function calls. For functions that make state modifications to the blockchain, transactions need to be generated and broadcasted. - -However, for read-only function calls, transactions are **not** required. Instead, these calls can be done using the [Stacks Blockchain API](https://docs.hiro.so/get-started/stacks-blockchain-api). - -:::tip -Read-only function calls do not require transaction fees -::: - -A read-only contract call can be done using the [`POST /v2/contracts/call-read///`](https://docs.hiro.so/api#operation/call_read_only_function) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl --location --request POST 'https://stacks-node-api.testnet.stacks.co/v2/contracts/call-read///' \ ---header 'Content-Type: application/json' \ ---data-raw '{ - "sender": ".", - "arguments": [, ...] -}' -``` - -Sample response for a successful call: - -```js -{ - "okay": true, - "result": "" -} -``` - -:::tip To set the function call arguments and read the result, [Clarity values](../write-smart-contracts/values) need to be serialized into a hexadecimal string. The [Stacks Transactions JS](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library supports these operations ::: - -## Querying - -Stacks 2.0 network details can be queried using the [Stacks Blockchain API](https://docs.hiro.so/get-started/stacks-blockchain-api). - -### Health check - -The [status checker](https://stacks-status.com/) is a service that provides a user interface to quickly review the health of the Stacks 2.0 blockchain. - -### Network info - -The network information can be obtained using the [`GET /v2/info`](https://docs.hiro.so/api#operation/get_core_api_info) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/info' -``` - -Sample response: - -```js -{ - "peer_version": 385875968, - "burn_consensus": "826401d65cf3671210a3fb135d827d549c0b4d37", - "burn_block_height": 1972, - "stable_burn_consensus": "e27ea23f199076bc41a729d76a813e125b725f64", - "stable_burn_block_height": 1971, - "server_version": "blockstack-core 0.0.1 => 23.0.0.0 (master:bdd042242+, release build, linux [x86_64]", - "network_id": 2147483648, - "parent_network_id": 3669344250, - "stacks_tip_height": 933, - "stacks_tip": "1f601823fbcc5b6b2215b2ff59d2818fba61ee4a3cea426d8bc3dbb268005d8f", - "stacks_tip_burn_block": "54c56a9685545c45accf42b5dcb2787c97eda8185a1c794daf9b5a59d4807abc", - "unanchored_tip": "71948ee211dac3b241eb65d881637f649d0d49ac08ee4a41c29217d3026d7aae", - "exit_at_block_height": 28160 -} -``` diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md b/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md deleted file mode 100644 index c933f7af68..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Proof of Transfer -description: Understand the proof-of-transfer consensus mechanism -sidebar_position: 3 ---- - -## Overview - -Consensus algorithms for blockchains require compute or financial resources to secure the blockchain. The general practice of decentralized consensus is to make it practically infeasible for any single malicious actor to have enough computing power or ownership stake to attack the network. - -Popular consensus mechanisms in modern blockchains include proof-of-work, in which nodes dedicate computing resources, and proof-of-stake, in which nodes dedicate financial resources to secure the network. - -Proof-of-burn is a novel consensus mechanism where miners compete by ‘burning’ (destroying) a proof-of-work cryptocurrency as a proxy for computing resources. - -Proof-of-transfer (PoX) is an extension of the proof-of-burn mechanism. 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. - -![PoX mechanism](/img/pox-mechanism.png) - -This allows network participants to secure the PoX cryptocurrency network and earn a reward in the base cryptocurrency. Thus, proof-of-transfer blockchains are anchored on their chosen proof-of-work chain. Stacks uses [Bitcoin](#why-bitcoin) as its anchor chain. - -![PoX participants](/img/pox-participants.png) - -## Why Bitcoin? - -There are a number of reasons that Stacks chose Bitcoin as the blockchain to power consensus. It's the oldest blockchain protocol, having launched in 2009, and has become a recognized asset outside of the cryptocurrency community. BTC has held the highest market capitalization of any cryptocurrency for the past decade. - -Bitcoin champions simplicity and stability, and has stood the test of time. Influencing or attacking the network is infeasible or impractical for any potential hackers. It's one of the only cryptocurrencies to capture public attention. Bitcoin is a household name, and is recognized as an asset by governments, large corporations, and legacy banking institutions. Lastly, Bitcoin is largely considered a reliable store of value, and provides extensive infrastructure to support the proof-of-transfer consensus mechanism. - -SIP-001 provides a full [list of reasons why Bitcoin was chosen to secure Stacks](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md). - -![btc-stacks](/img/pox-why-bitcoin.png) - -## Blocks and microblocks - -The Stacks blockchain allows for increased transaction throughput using a mechanism called microblocks. Bitcoin and Stacks progress in lockstep, and their blocks are confirmed simultaneously. On Stacks, this is referred to as an ‘anchor block’. An entire block of Stacks transactions corresponds to a single Bitcoin transaction. This significantly improves cost/byte ratio for processing Stacks transactions. Because of simultaneous block production, Bitcoin acts as a rate-limiter for creating Stacks blocks, thereby preventing denial-of-service attacks on its peer network. - -However, in between Stacks anchor blocks settling on the Bitcoin blockchain, there are also a varying number of microblocks that allow rapid settlement of Stacks transactions with a high degree of confidence. This allows Stacks transaction throughput to scale independently of Bitcoin, while still periodically establishing finality with the Bitcoin chain. The Stacks blockchain adopts a block streaming model whereby each leader can adaptively select and package transactions into their block as they arrive in the mempool. Therefore when an anchor block is confirmed, all of the transactions in the parent microblock stream are packaged and processed. This is an unprecedented method for achieving scalability without creating a totally separate protocol from Bitcoin. - -![stx-microblock](/img/stx-microblocks.png) - -## Unlocking Bitcoin capital - -Stacks also unlocks the hundreds of billions in capital in Bitcoin, and gives Bitcoiners new opportunities to use and earn BTC. Stacks is a accompaniment to the Bitcoin ecosystem, and the two networks working in tandem enables totally novel ways of using BTC. The Stacks ecosystem makes interactive cryptocurrency applications available to Bitcoin holders. Additionally, By stacking STX tokens and participating in the PoX consensus mechanism, users have the opportunity to earn BTC while securing the Stacks chain. - -![Unlocking Bitcoin](/img/pox-unlocking-btc.png) - -## Clarity and the Bitcoin state - -Clarity smart contracts also have unique visibility into the state of the Bitcoin blockchain. This means that contract logic in a Clarity file has the ability to trigger when specific Bitcoin transactions are confirmed. Clarity smart contracts have a built in Simple Payment Verification (SPV) proofs for Bitcoin that make interacting with Bitcoin’s state much simpler for developers. Additionally, Clarity contracts can fork with the original Bitcoin chain. Therefore, in an edge case where Bitcoin forks, developers wouldn’t have to worry about adjusting the deployment of their smart contracts. - -## See also - -- [Read the full PoX whitepaper](https://community.stacks.org/pox) -- [Watch Executive Chair of Hiro Muneeb Ali and Evangelist Joe Bender give an overview of Stack's breakthrough PoX mining mechanism](https://www.youtube.com/watch?v=NY_eUrIcWOY) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md b/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md deleted file mode 100644 index 5f3863e8dd..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: Stacking -description: Introduction to the reward mechanism of Proof-of-Transfer -sidebar_position: 9 ---- - -## Introduction - -Stacking rewards Stacks (STX) token holders with bitcoin for providing a valuable service to the network by locking up their tokens for a certain time. - -![](/img/stacking.png) - -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. - -:::info The Stacking consensus algorithm is implemented as a smart contract, using [Clarity](../write-smart-contracts/). [Read more about the contract](../noteworthy-contracts/stacking-contract). ::: - -## Stacking flow - -The Stacking mechanism can be presented as a flow of actions: - -![Stacking flow](/img/stacking-illustration.png) - -1. Make API calls to get details about the upcoming reward cycle -2. For a specific Stacks account, confirm eligibility -3. Confirm the BTC reward address and the lockup duration -4. The transaction is broadcasted and the STX tokens are locked. This needs to happen before the prepare phase of the next reward cycle, the last 100 Bitcoin blocks of the ongoing reward phase -5. The Stacking mechanism executes reward cycles and sends out rewards to the set BTC reward address -6. During the lockup period, details about unlocking timing, rewards and more can be obtained -7. Once the lockup period is passed, the tokens are released and accessible again -8. Display reward history, including details like earnings for previous reward cycles - -:::info Keep in mind that the target duration for a reward cycles is ~2 weeks. This duration is based on the target block time of the network (10 minutes) and can be higher at times due to [confirmation time variances](https://www.blockchain.com/charts/median-confirmation-time) of the bitcoin network. ::: - -## Stacking delegation flow - -The Stacking flow is different for delegation use cases: - -![Delegated tacking flow](/img/stacking-delegation-illustration.png) - -- Before Stacking can be initiated for a token holder, the delegator needs to be granted permission to Stack on behalf of the account owner. The permission is restricted to the maximum amount the delegator is allowed to Stack. The maximum amount is not limited by the available funds and can be set much higher. An account can only be associated with one single delegator -- The account has to define the delegation relationship. They can optionally restrict the Bitcoin reward address that must be used for payouts, and the expiration burn block height for the permission, thus limiting the time a delegator has permission to Stack -- Delegators have to lock Stacks from different accounts ("pooling phase") until they reach the minimum amount of Stacks required to participate in Stacking -- Once a delegator locks enough STX tokens, they can finalize and commit their participation in the next reward cycle -- Certain delegation relationships may allow the STX holder to receive the payout directly from the miner (step 5/6) -- The termination of the delegation relationship can either happen automatically based on set expiration rules or by actively revoking delegation rights - -## PoX mining - -PoX mining is a modification of Proof-of-Burn (PoB) mining, where instead of sending the committed Bitcoin to a burn address, it's transferred to eligible STX holders that participate in the stacking protocol. - -:::note -A PoX miner can only receive newly minted STX tokens when they transfer Bitcoin to eligible owners of STX tokens -::: - -![Mining flow](/img/pox-mining-flow.png) - -Miners run Stacks nodes with mining enabled to participate in the PoX mechanism. The node implements the PoX mechanism, which ensures proper handling and incentives through four key phases: - -- Registration: miners register for a future election by sending consensus data to the network -- Commitment: registered miners transfer Bitcoin to participate in the election. Committed BTC are sent to a set participating STX token holders -- Election: a verifiable random function chooses one miner to write a new block on the Stacks blockchain -- Assembly: the elected miner writes the new block and collects rewards in form of new STX tokens - -## Token holder eligibility - -Stacks (STX) token holders don't automatically receive stacking rewards. Instead, they must: - -- Commit to participation before a reward cycle begins -- Commit the minimum amount of STX tokens to secure a reward slot, or pool with others to reach the minimum -- Lock up STX tokens for a specified period -- Provide a supported Bitcoin address to receive rewards (native segwit is not supported) - -The following diagram describes how the minimum STX tokens per slot is determined. More information on [dynamic minimums for stacking](https://stacking.club) is available at stacking.club. - -![Dynamic minimum for individual eligibility](/img/stacking-dynamic-minimum.png) - -Token holders have a variety of providers and tools to support their participation in Stacking. The Stacks website contains a [list of stacking providers and pools](https://stacks.org/stacking#earn). - -## Stacking in the PoX consensus algorithm - -Stacking is a built-in capability of PoX and occurs through a set of actions on the Stacks blockchain. The [full proof-of-transfer implementation details](https://github.com/stacks-network/stacks-blockchain/blob/develop/sip/sip-007-stacking-consensus.md) are in SIP-007. Below is a summary of the most relevant actions of the algorithm. - -![PoX cycles](/img/pox-cycles.png) - -- Stacking happens over reward cycles with a fixed length. In each reward cycle, a set of Bitcoin addresses associated with stacking participants receive BTC rewards -- A reward cycle consists of two phases: prepare and reward -- During the prepare phase, miners decide on an anchor block and a reward set. Mining any descendant forks of the anchor block requires transferring mining funds to the appropriate reward addresses. The reward set is the set of Bitcoin addresses which are eligible to receive funds in the reward cycle -- Miners register as leader candidates for a future election by sending a key transaction that burns cryptocurrency. The transaction also registers the leader's preferred chain tip (must be a descendant of the anchor block) and commitment of funds to 2 addresses from the reward set -- Token holders register for the next rewards cycle by broadcasting a signed message that locks up associated STX tokens for a protocol-specified lockup period, specifies a Bitcoin address to receive the funds, and votes on a Stacks chain tip -- Multiple leaders can commit to the same chain tip. The leader that wins the election and the peers who also burn for that leader collectively share the reward, proportional to how much each one burned -- Token holders' locked up tokens automatically unlock as soon as the lockup period finishes - -## Bitcoin address - -:::danger You must provide a BTC address in one of two formats: - -* [Legacy (P2PKH)](https://en.bitcoin.it/wiki/Transaction#Pay-to-PubkeyHash), which starts with `1`. - -* [Segregated Witness / Segwit (P2SH)](https://en.bitcoin.it/wiki/Pay_to_script_hash), which starts with `3`. The "Native Segwit" format (which starts with `bc1`), for example, is not supported. ::: - -The Stacking contract needs a special format for the Bitcoin address (the reward address). This is required to ensure that miners are able to correctly construct the Bitcoin transaction containing the reward address. - -The address must be specified in the following format using the Clarity language: - -```clar -;; a tuple of a version and hashbytes buffer -(pox-addr (tuple (version (buff 1)) (hashbytes (buff 20)))) -``` - -The `version` buffer must represent what kind of bitcoin address is being submitted. It can be one of the following: - -```js -SerializeP2PKH = 0x00, // hash160(public-key), same as bitcoin's p2pkh -SerializeP2SH = 0x01, // hash160(multisig-redeem-script), same as bitcoin's multisig p2sh -SerializeP2WPKH = 0x02, // hash160(segwit-program-00(p2pkh)), same as bitcoin's p2sh-p2wpkh -SerializeP2WSH = 0x03, // hash160(segwit-program-00(public-keys)), same as bitcoin's p2sh-p2wsh -``` - -The `hashbytes` are the 20 hash bytes of the bitcoin address. You can obtain that from a bitcoin library, for instance using [`bitcoinjs-lib`](https://github.com/bitcoinjs/bitcoinjs-lib): - -```js -const btc = require('bitcoinjs-lib'); -console.log( - '0x' + btc.address.fromBase58Check('1C56LYirKa3PFXFsvhSESgDy2acEHVAEt6').hash.toString('hex') -); -``` - -## Choosing the right Stacking strategy - -[Here](https://blog.stacks.co/stacking-strategy) is an interesting article that may help you choose the right Stacking stategy. - - -## Where to Stacks? - -You can Stack on your own, on a pool or on an exchange: -### Stacking on your own - -Stacking on your own is non-custodial. - -Stacking on your own requires a protocol minimum (amount changes but about 100,000 STX). - -[Hiro Wallet](https://www.hiro.so/wallet) allows stacking on your own. - -### Stacking on a pool - -Stacking on a pool allows Stacking without the requirement of the protocol minumum. - -Some available pools are: - -| Pool | Type | Pays rewards in | Fee | Minimum amount | -| --------------------------------------------------- | ------------- |:---------------:| --- |:--------------:| -| [Friedger's Pool](https://pool.friedger.de/) | Non custodial | STX or xBTC | No | 40 STX | -| [Planbetter](https://planbetter.org/) | Non custodial | BTC | 5% | 200 STX | -| [Stacked](https://staking.staked.us/stacks-staking) | Non custodial | BTC | | 100,000 STX | -| [Xverse](https://www.xverse.app/) | Non custodial | BTC | No | 100 STX | - -### Stacking on an exchange - -Stacking on an exchange is custodial, meaning you are trusting the exchange with your Stacks. - -Several exchanges allow Stacking directly on their sites. Examples are [Okcoin](https://www.okcoin.com) and [Binance](https://www.binance.com/en/staking) - -## Stacking statistics - -You can view all sorts of Stacking data and statistics on [Stacking Club](https://stacking.club) \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md b/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md deleted file mode 100644 index d942d6af8f..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Stacks Blockchain API -description: Interacting with the Stacks 2.0 Blockchain via API ---- - -## Temporal page because of a Crowdin bug \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md b/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md deleted file mode 100644 index e370129d1d..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Technical Specifications -description: Summary of technical specifications of Stacks 2.0 -sidebar_position: 10 ---- - -## Consensus - -- Proof of Transfer (PoX) as described in [SIP-007](https://github.com/stacksgov/sips/blob/main/sips/sip-007/sip-007-stacking-consensus.md) -- Network will transition to Proof of Burn (PoB) as described in [SIP-001](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md) after 10 years. [Learn more about Proof-of-Burn in SIP-001](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md). -- Threat model - - 51% of malicious Stacks mining power can perform a double-spend attack - - 51% of malicious Bitcoin mining power can reorg the Stacks chain -- Different actors and their roles - - Stacks Miners package transactions into blocks, mine them through a Bitcoin transaction, propagate them, and if they win the block race, append microblocks to their winning block until the next block is mined. The next block confirms the microblock stream. - - Stacks Holders may alter the calculation of block limits (subject to a miner veto) and may vote to disable Proof-of-Transfer rewards for a reward cycle. -- Transactions are considered final when the corresponding "block commit" transaction on Bitcoin is finalized. Typically this can by 3-6 confirmations. -- For more details, see [Proof of Transfer](proof-of-transfer). - -## Proof of Transfer Mining - -- Coinbase reward schedule: - - 1000 STX/block for first 4 years - - 500 STX/block for following 4 years - - 250 STX/block for subsequent 4 years - - 125 STX/block in perpetuity after that -- Coinbase rewards accumulate for "missed sortitions": If a Bitcoin block has no sortition (at height N), then any Stacks block mined in a subsequent sortition that builds off of any Stacks chain tip that existed at the penultimate sortition (at height N-1) may claim its coinbase. This encourages miners to keep mining even if Bitcoin fees are high. -- Initial mining bonus: This is a special case of the above to incentivize early miners. Coinbase for all burnchain blocks between the first burn block height (to be chosen by independent miners as part of the Stacks 2.0 launch) and the first sortition winner accumulate and are distributed to miners over a fixed window (to be determined). For instance, say burn block height is 10,000 and first sortition is at block 10500 and distribution window is 100 blocks, then coinbase for the first 500 blocks (10,500 - 10,000) will be distributed evenly to miners who win sortition over the subsequent 100 blocks. -- 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 at least 11,000 satoshis (5,500 sats / [UTXO output](https://learnmeabitcoin.com/technical/utxo)); 2 outputs / block) to avoid "dust." -- For more details, see [Mining](mining). - -## Stacking - -- Stacking works in 2 phases - 1. Prepare phase: In this phase an "anchor block" is chosen. The qualifying set of addresses ("reward set") is determined based on the snapshot of the chain at the anchor block. Length of prepare phase is 100 blocks. Stacking commitments need to be confirmed before this phase starts - 2. Reward phase: In this phase miner BTC commitments are distributed amongst the reward set. Reward cycle length is 2000 BTC blocks (~2 weeks). -- 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/stacksgov/sips/blob/main/sips/sip-007/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.stacks.co/references/stacking-contract#delegate-stx). -- Only two types of BTC reward addresses are supported: [Legacy (P2PKH)](https://en.bitcoin.it/wiki/Transaction#Pay-to-PubkeyHash) or [Segregated Witness / Segwit (P2SH)](https://en.bitcoin.it/wiki/Pay_to_script_hash). Native Segwit is not supported. -- Further reading: [Stacking](stacking) - -## Accounts and Addresses - -- Transactions in the Stacks blockchain originate from, are paid for by, and execute under the authority of accounts -- An account is fully specified by its address + nonce + assets -- 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 (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](accounts) - -## Transactions - -- Transaction 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 - 2. _paying account_ is the account that is billed by the leader for the cost of validating and executing the transaction - 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 -- Transactions can be batched or streamed into blocks. The behavior can be controlled by the anchor mode of a transaction. With streaming ([microblocks](microblocks)), a faster confirmation time is possible. -- 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. -- Mempool limit for concurrent pending transactions is 25 per account -- Pending mempool transactions will be garbage-collected [256 blocks after receipt](https://github.com/stacks-network/stacks-blockchain/blob/master/src/core/mempool.rs#L62). With 10 minutes target block time, this would equal ~42 hours -- [Learn more about transaction encoding in SIP-005](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md#transaction-encoding) -- [Transaction signing and verification are described in SIP-005](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md#transaction-signing-and-verifying) -- All transactions impacting account balance are atomic, a transfer operation can not increment one account’s balance without decrementing another’s. However, transactions that perform multiple account actions (for example, transferring from multiple accounts) may partially complete. -- Transactions can include a memo string (max 34 bytes) - -## See also - -- [Read the full Stacks 2.0: Apps and Smart Contracts for Bitcoin whitepaper](https://cloudflare-ipfs.com/ipfs/QmaGgiVHymeDjAc3aF1AwyhiFFwN97pme5m536cHT4FsAW). - -- [Watch Aaron Blankstein video on Stacks whitepater v2](https://www.youtube.com/watch?v=Wd-Bfe8Sn-Y). \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md b/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md deleted file mode 100644 index 59934a5bde..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Testnet -description: Test your smart contracts and apps -sidebar_position: 2 ---- - -## About testnet - -The testnet is a separate blockchain from the Stacks mainnet analogous to a staging environment. It's a network used by developers to test their apps, smart contracts, or changes to the protocol in a production-like environment. It produces blocks at roughly the same rate as mainnet; about 1 block every 10 minutes on average. The Stacks testnet is rarely reset. - -### Faucet - -The testnet faucet provides you with free Stacks Token (STX) to test with. These are not the same as STX on mainnet and have no value. You can get STX from the faucet on the [Stacks Explorer Sandbox](https://explorer.stacks.co/sandbox/faucet?chain=testnet), or using the [API](https://docs.hiro.so/api#tag/Faucets). - -To get STX tokens from within the Explorer Sandbox, navigate to the "Faucet" tab on the left and click "Request STX" button. - -![](/img/stx_faucet.png) - -You can also try out [Stacking](stacking) by clicking on `I want to stack`. - -:::note -The Explorer Sandbox requires you to login with a Stacks wallet -::: - -### Testnet API - -The hosted Stacks Blockchain API for the testnet is available at this base URL: - -```shell -https://stacks-node-api.testnet.stacks.co/ -``` - -![](/img/api_testnet_status.png) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md b/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md deleted file mode 100644 index 2ff6072384..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Transactions -description: Guide to Stacks 2.0 transactions -sidebar_position: 6 ---- - -## Introduction - -Transactions are the fundamental unit of execution in the Stacks blockchain. Each transaction is originated from a [Stacks 2.0 account](accounts), and is retained in the Stacks blockchain history for eternity. This guide helps you understand Stacks 2.0 transactions. - -## Lifecycle - -Transactions go through phases before being finally confirmed, and available for all, on the Stacks 2.0 network. - -![Transaction lifecycle](/img/tx-lifecycle.png) - -- **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/en/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. - -:::note A transaction can have one of three states once it is registered: `pending`, `success`, or `failed`. ::: - -## Types - -The Stacks 2.0 supports a set of different transaction types: - -| **Type** | **Value** | **Description** | -| ----------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Coinbase | `coinbase` | The first transaction in a new block (an entity holding several transactions). Used to register for block rewards. These are not manually generated and broadcasted like other types of transactions. | -| Token transfer | `token_transfer` | Asset transfer from a sender to a recipient | -| Contract deploy | `smart_contract` | Contract instantiation | -| Contract call | `contract_call` | Contract call for a public, non read-only function | -| Poison Microblock | `poison_microblock` | Punish leaders who intentionally equivocate about the microblocks they package | - -A sample of each transaction type can be found in the [Stacks Blockchain API response definition for transactions](https://docs.hiro.so/api#operation/get_transaction_by_id). - -:::caution Read-only contract call calls do **not** require transactions. Read more about it in the [network guide](network#read-only-function-calls). ::: diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md b/i18n/ja/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md deleted file mode 100644 index fd45c80583..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Clarity Language -description: Overview of the Clarity language constructs -sidebar_label: Clarity Language -tags: - - clarity ---- - -## Clarity Type System - -The Clarity language uses a strong static type system. Function arguments and database schemas require specified types, and use of types is checked during contract launch. The type system does _not_ have a universal super type. - -## Public Functions - -Functions specified via `define-public` statements are _public_ functions and these are the only types of functions which may be called directly through signed blockchain transactions. In addition to being callable directly from a transaction (see the Stacks wire formats for more details on Stacks transactions), public functions may be called by other smart contracts. - -Public functions _must_ return a `(response ...)` type. This is used by Clarity to determine whether or not to materialize any changes from the execution of the function. If a function returns an `(err ...)` type, any mutations on the blockchain state from executing the function (and any function that it called during execution) will be aborted. - -In addition to functions defined via `define-public`, contracts may expose read-only functions. These functions, defined via `define-read-only`, are callable by other smart contracts, and may be queryable via public blockchain explorers. These functions _may not_ mutate any blockchain state. Unlike normal public functions, read-only functions may return any type. - -## Contract Calls - -A smart contract may call functions from other smart contracts using a `(contract-call?)` function. - -This function returns a response type result -- the return value of the called smart contract function. - -We distinguish 2 different types of `contract-call?`: - -### Static dispatch - -The callee is a known, invariant contract available on-chain when the caller contract is deployed. In this case, the callee's principal is provided as the first argument, followed by the name of the method and its arguments: - -```clarity -(contract-call? - .registrar - register-name - name-to-register) -``` - -### Dynamic dispatch - -The callee is passed as an argument, and typed as a trait reference (``). - -```clarity -(define-public (swap (token-a ) - (amount-a uint) - (owner-a principal) - (token-b ) - (amount-b uint) - (owner-b principal))) - (begin - (unwrap! (contract-call? token-a transfer-from? owner-a owner-b amount-a)) - (unwrap! (contract-call? token-b transfer-from? owner-b owner-a amount-b)))) -``` - -Traits can either be locally defined: - -```clarity -(define-trait can-transfer-tokens ( - (transfer-from? (principal principal uint) (response uint))) -``` - -Or imported from an existing contract: - -```clarity -(use-trait can-transfer-tokens - .contract-defining-trait.can-transfer-tokens) -``` - -Looking at trait conformance, callee contracts have two different paths. They can either be "compatible" with a trait by defining methods matching some of the methods defined in a trait, or explicitly declare conformance using the `impl-trait` statement: - -```clarity -(impl-trait .contract-defining-trait.can-transfer-tokens) -``` - -Explicit conformance should be prefered when adequate. It acts as a safeguard by helping the static analysis system to detect deviations in method signatures before contract deployment. - -The following limitations are imposed on contract calls: - -1. On static dispatches, callee smart contracts _must_ exist at the time of creation. -2. No cycles may exist in the call graph of a smart contract. This prevents recursion (and re-entrancy bugs). Such structures can be detected with static analysis of the call graph, and will be rejected by the network. -3. `contract-call?` are for inter-contract calls only. Attempts to execute when the caller is also the callee will abort the transaction. diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md b/i18n/ja/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md deleted file mode 100644 index a6011cca8b..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md +++ /dev/null @@ -1,1388 +0,0 @@ ---- -title: Functions -description: See a detailed list of all functions for the Clarity language. -tags: - - clarity ---- - -## Functions - -Detailed list of all functions for the Clarity language. - -### + (add) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(+ i1 i2...)` -#### description: -Adds a variable number of integer inputs and returns the result. In the event of an _overflow_, throws a runtime error. -#### example: -```clarity -(+ 1 2 3) ;; Returns 6 -(+ 2 3) ;; Returns 5 -(+ 1 2 3 4) ;; Returns 10 -(+ 9 -3) ;; Returns 6 -(+ -3 -2) ;; Returns -5 -``` - -### - (subtract) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(- i1 i2...)` -#### description: -Subtracts a variable number of integer inputs and returns the result. In the event of an _underflow_, throws a runtime error. -#### example: -```clarity -(- 2 1 1) ;; Returns 0 -(- 0 3) ;; Returns -3 -(- 5 -3) ;; Returns 8 -(- -4 -5) ;; Returns 1 -``` - -### * (multiply) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(* i1 i2...)` -#### description: -Multiplies a variable number of integer inputs and returns the result. In the event of an _overflow_, throws a runtime error. -#### example: -```clarity -(* 2 3) ;; Returns 6 -(* 5 2) ;; Returns 10 -(* 2 2 2) ;; Returns 8 -(* 3 -2) ;; Returns -6 -(* -1 -2) ;; Returns 2 -``` - -### / (divide) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(/ i1 i2...)` -#### description: -Divides a variable number of integer inputs and returns the _integer part_ of the result. In the event of _division by zero_, throws a runtime error. - -#### example: -```clarity -(/ 2 3) ;; Returns 0 -(/ 5 2) ;; Returns 2 -(/ 4 2 2) ;; Returns 1 -(/ -10 2) ;; Returns -5 -(/ -8 -2) ;; Returns 4 -(/ -9 4) ;; Returns -2 -``` - -### >= (greater than or equal) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(>= i1 i2)` -#### description: -Compares two integers, returning `true` if `i1` is greater than or equal to `i2` and `false` otherwise. -#### example: -```clarity -(>= 1 1) ;; Returns true -(>= 5 2) ;; Returns true -``` - -### <= (less than or equal) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(<= i1 i2)` -#### description: -Compares two integers, returning true if `i1` is less than or equal to `i2` and `false` otherwise. -#### example: -```clarity -(<= 1 1) ;; Returns true -(<= 5 2) ;; Returns false -``` - -### < (less than) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(< i1 i2)` -#### description: -Compares two integers, returning `true` if `i1` is less than `i2` and `false` otherwise. -#### example: -```clarity -(< 1 2) ;; Returns true -(< 5 2) ;; Returns false -``` - -### > (greater than) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(> i1 i2)` -#### description: -Compares two integers, returning `true` if `i1` is greater than `i2` and false otherwise. -#### example: -```clarity -(> 1 2) ;; Returns false -(> 5 2) ;; Returns true -``` - -### to-int -#### input: `uint` -#### output: `int` -#### signature: `(to-int u)` -#### description: -Tries to convert the `uint` argument to an `int`. Will cause a runtime error and abort if the supplied argument is >= `pow(2, 127)`` -#### example: -```clarity -(to-int u238) ;; Returns 238 -``` - -### to-uint -#### input: `int` -#### output: `uint` -#### signature: `(to-uint i)` -#### description: -Tries to convert the `int` argument to a `uint`. Will cause a runtime error and abort if the supplied argument is negative. -#### example: -```clarity -(to-uint 238) ;; Returns u238 -``` - -### mod -#### input: `int, int | uint, uint` -#### output: `int | uint` -#### signature: `(mod i1 i2)` -#### description: -Returns the integer remainder from integer dividing `i1` by `i2`. In the event of a division by zero, throws a runtime error. -#### example: -```clarity -(mod 2 3) ;; Returns 2 -(mod 5 2) ;; Returns 1 -(mod 7 1) ;; Returns 0 -``` - -### pow -#### input: `int, int | uint, uint` -#### output: `int | uint` -#### signature: `(pow i1 i2)` -#### description: -Returns the result of raising `i1` to the power of `i2`. In the event of an _overflow_, throws a runtime error. -#### example: -```clarity -(pow 2 3) ;; Returns 8 -(pow 2 2) ;; Returns 4 -(pow 7 1) ;; Returns 7 -``` - -### sqrti -#### input: `int | uint` -#### output: `int | uint` -#### signature: `(sqrti n)` -#### description: -Returns the largest integer that is less than or equal to the square root of `n`. Fails on a negative numbers. -#### example: -```clarity -(sqrti u11) ;; Returns u3 -(sqrti 1000000) ;; Returns 1000 -(sqrti u1) ;; Returns u1 -(sqrti 0) ;; Returns 0 -``` - -### log2 -#### input: `int | uint` -#### output: `int | uint` -#### signature: `(log2 n)` -#### description: -Returns the _integer part_ of the power to which the number 2 must be raised to obtain the value `n`. Fails on zero or a negative number. -#### example: -```clarity -(log2 u8) ;; Returns u3 -(log2 8) ;; Returns 3 -(log2 u1) ;; Returns u0 -(log2 1000) ;; Returns 9 -``` - -### xor -#### input: `int, int | uint, uint` -#### output: `int | uint` -#### signature: `(xor i1 i2)` -#### description: -Returns the result of bitwise exclusive or'ing `i1` with `i2`. -#### example: -```clarity -(xor 1 2) ;; Returns 3 -(xor 120 280) ;; Returns 352 -``` - -### and -#### input: `bool, ...` -#### output: `bool` -#### signature: `(and b1 b2 ...)` -#### description: -Returns `true` if all boolean inputs are `true`. Importantly, the supplied arguments are evaluated in-order and lazily. Lazy evaluation means that if one of the arguments returns `false`, the function short-circuits, and no subsequent arguments are evaluated. -#### example: -```clarity -(and true false) ;; Returns false -(and (is-eq (+ 1 2) 1) (is-eq 4 4)) ;; Returns false -(and (is-eq (+ 1 2) 3) (is-eq 4 4)) ;; Returns true -``` - -### or -#### input: `bool, ...` -#### output: `bool` -#### signature: `(or b1 b2 ...)` -#### description: -Returns `true` if any boolean inputs are `true`. Importantly, the supplied arguments are evaluated in-order and lazily. Importantly, the supplied arguments are evaluated in-order and lazily. -#### example: -```clarity -(or true false) ;; Returns true -(or (is-eq (+ 1 2) 1) (is-eq 4 4)) ;; Returns true -(or (is-eq (+ 1 2) 1) (is-eq 3 4)) ;; Returns false -(or (is-eq (+ 1 2) 3) (is-eq 4 4)) ;; Returns true -``` - -### not -#### input: `bool` -#### output: `bool` -#### signature: `(not b1)` -#### description: -Returns the inverse of the boolean input. -#### example: -```clarity -(not true) ;; Returns false -(not (is-eq 1 2)) ;; Returns true -``` - -### is-eq -#### input: `A, A, ...` -#### output: `bool` -#### signature: `(is-eq v1 v2...)` -#### description: -Compares the inputted values, returning `true` if they are all equal. Note that _unlike_ the `(and ...)` function, `(is-eq ...)` will _not_ short-circuit. All values supplied to is-eq _must_ be the same type. -#### example: -```clarity -(is-eq 1 1) ;; Returns true -(is-eq true false) ;; Returns false -(is-eq \"abc\" 234 234) ;; Throws type error -``` - -### if -#### input: `bool, A, A` -#### output: `A` -#### signature: `(if bool1 expr1 expr2)` -#### description: -The `if` function admits a boolean argument and two expressions which must return the same type. In the case that the boolean input is `true`, the `if` function evaluates and returns `expr1`. If the boolean input is `false`, the `if` function evaluates and returns `expr2`. -#### example: -```clarity -(if true 1 2) ;; Returns 1 -(if (> 1 2) 1 2) ;; Returns 2 -``` - -### let -#### input: `((name1 AnyType) (name2 AnyType) ...), AnyType, ... A` -#### output: `A` -#### signature: `(let ((name1 expr1) (name2 expr2) ...) expr-body1 expr-body2 ... expr-body-last)` -#### description: -The `let` function accepts a list of `variable name` and `expression` pairs, evaluating each expression and _binding_ it to the corresponding variable name. `let` bindings are sequential: when a `let` binding is evaluated, it may refer to prior binding. The _context_ created by this set of bindings is used for evaluating its body expressions. The let expression returns the value of the last such body expression. Note: intermediary statements returning a response type must be checked` -#### example: -```clarity -(let ((a 2) (b (+ 5 6 7))) (print a) (print b) (+ a b)) ;; Returns 20 -(let ((a 5) (c (+ a 1)) (d (+ c 1)) (b (+ a c d))) (print a) (print b) (+ a b)) ;; Returns 23 -``` - -### map -#### input: `Function(A, B, ..., N) -> X, sequence_A, sequence_B, ..., sequence_N` -#### output: `(list X)` -#### signature: `(map func sequence_A sequence_B ... sequence_N)` -#### description: -Also, note that, no matter what kind of sequences the inputs are, the output is always a list. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. The `map` function applies the function `func` to each corresponding element of the input sequences, and outputs a _list_ of the same type containing the outputs from those function applications. -#### example: -```clarity -(map not (list true false true false)) ;; Returns (false true false true) -(map + (list 1 2 3) (list 1 2 3) (list 1 2 3)) ;; Returns (3 6 9) -(define-private (a-or-b (char (string-utf8 1))) (if (is-eq char u\"a\") u\"a\" u\"b\")) -(map a-or-b u\"aca\") ;; Returns (u\"a\" u\"b\" u\"a\") -(define-private (zero-or-one (char (buff 1))) (if (is-eq char 0x00) 0x00 0x01)) -(map zero-or-one 0x000102) ;; Returns (0x00 0x01 0x01) -``` - -### fold -#### input: `Function(A, B) -> B, sequence_A, B` -#### output: `B` -#### signature: `(fold func sequence_A initial_B)` -#### description: -The `fold` function condenses `sequence_A` into a value of type `B` by recursively applies the function `func` to each element of the input sequence _and_ the output of a previous application of `func`. - -`fold` uses `initial_B` in the initial application of `func`, along with the first element of `sequence_A`. The resulting value of type `B` is used for the next application of `func`, along with the next element of `sequence_A` and so on. `fold` returns the last value of type `B` returned by these successive applications `func`. - -Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. - -#### example: -```clarity -(fold * (list 2 2 2) 1) ;; Returns 8 -(fold * (list 2 2 2) 0) ;; Returns 0 -;; calculates (- 11 (- 7 (- 3 2))) -(fold - (list 3 7 11) 2) ;; Returns 5 -(define-private (concat-string (a (string-ascii 20)) (b (string-ascii 20))) (unwrap-panic (as-max-len? (concat a b) u20))) -(fold concat-string \"cdef\" \"ab\") ;; Returns \"fedcab\" -(fold concat-string (list \"cd\" \"ef\") \"ab\") ;; Returns \"efcdab\" -(define-private (concat-buff (a (buff 20)) (b (buff 20))) (unwrap-panic (as-max-len? (concat a b) u20))) -(fold concat-buff 0x03040506 0x0102) ;; Returns 0x060504030102 -``` - -### append -#### input: `list A, A` -#### output: `list` -#### signature: `(append (list 1 2 3 4) 5)` -#### description: -The `append` function takes a list and another value with the same entry type, and outputs a list of the same type with max_len += 1. -#### example: -```clarity -(append (list 1 2 3 4) 5) ;; Returns (1 2 3 4 5) -``` - -### concat -#### input: `sequence_A, sequence_A` -#### output: `sequence_A` -#### signature: `(concat sequence1 sequence2)` -#### description: -The `func` argument must be a literal function name. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. - -#### example: -```clarity -(concat (list 1 2) (list 3 4)) ;; Returns (1 2 3 4) -(concat \"hello \" \"world\") ;; Returns \"hello world\" -(concat 0x0102 0x0304) ;; Returns 0x01020304 -``` - -### as-max-len? -#### input: `sequence_A, uint` -#### output: `sequence_A` -#### signature: `(as-max-len? sequence max_length)` -#### description: -The `as-max-len?` function takes a sequence argument and a uint-valued, literal length argument. The function returns an optional type. If the input sequence length is less than or equal to the supplied max_length, this returns `(some sequence)`, otherwise it returns `none`. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. ` -#### example: -```clarity -(as-max-len? (list 2 2 2) u3) ;; Returns (some (2 2 2)) -(as-max-len? (list 1 2 3) u2) ;; Returns none -(as-max-len? \"hello\" u10) ;; Returns (some \"hello\") -(as-max-len? 0x010203 u10) ;; Returns (some 0x010203) -``` - -### len -#### input: `sequence_A` -#### output: `uint` -#### signature: `(len sequence)` -#### description: -The `len` function returns the length of a given sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. ` -#### example: -```clarity -(len \"blockstack\") ;; Returns u10 -(len (list 1 2 3 4 5)) ;; Returns u5 -(len 0x010203) ;; Returns u3 -``` - -### element-at -#### input: `sequence_A, uint` -#### output: `(optional A)` -#### signature: `(element-at sequence index)` -#### description: -The `element-at` function returns the element at `index` in the provided sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. ` -#### example: -```clarity -(element-at \"blockstack\" u5) ;; Returns (some \"s\") -(element-at (list 1 2 3 4 5) u5) ;; Returns none -(element-at (list 1 2 3 4 5) (+ u1 u2)) ;; Returns (some 4) -(element-at \"abcd\" u1) ;; Returns (some \"b\") -(element-at 0xfb01 u1) ;; Returns (some 0x01) -``` - -### index-of -#### input: `sequence_A, A` -#### output: `(optional uint)` -#### signature: `(index-of sequence item)` -#### description: -The `index-of` function returns the first index at which `item` can be found, using `is-eq` checks, in the provided sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. If the target item is not found in the sequence (or if an empty string or buffer is supplied), this function returns `none`. -#### example: -```clarity -(index-of \"blockstack\" \"b\") ;; Returns (some u0) -(index-of \"blockstack\" \"k\") ;; Returns (some u4) -(index-of \"blockstack\" \"\") ;; Returns none -(index-of (list 1 2 3 4 5) 6) ;; Returns none -(index-of 0xfb01 0x01) ;; Returns (some u1) -``` - -### list -#### input: `A, ...` -#### output: `(list A)` -#### signature: `(list expr1 expr2 expr3 ...)` -#### description: -The `list` function constructs a list composed of the inputted values. Each supplied value must be of the same type. -#### example: -```clarity -(list (+ 1 2) 4 5) ;; Returns (3 4 5) -``` - -### var-get -#### input: `VarName` -#### output: `A` -#### signature: `(var-get var-name)` -#### description: -The `var-get` function looks up and returns an entry from a contract's data map. The value is looked up using `var-name`. -#### example: -```clarity -(define-data-var cursor int 6) -(var-get cursor) ;; Returns 6 -``` - -### var-set -#### input: `VarName, AnyType` -#### output: `bool` -#### signature: `(var-set var-name expr1)` -#### description: -The `var-set` function sets the value associated with the input variable to the inputted value. The function always returns `true`. -#### example: -```clarity -(define-data-var cursor int 6) -(var-get cursor) ;; Returns 6 -(var-set cursor (+ (var-get cursor) 1)) ;; Returns true -(var-get cursor) ;; Returns 7 -``` - -### map-get? -#### input: `MapName, tuple` -#### output: `(optional (tuple))` -#### signature: `(map-get? map-name key-tuple)` -#### description: -The `map-get?` function looks up and returns an entry from a contract's data map. The value is looked up using `key-tuple`. If there is no value associated with that key in the data map, the function returns a `none` option. Otherwise, it returns `(some value)`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(map-get? names-map (tuple (name \"blockstack\"))) ;; Returns (some (tuple (id 1337))) -(map-get? names-map { name: \"blockstack\" }) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-set -#### input: `MapName, tuple_A, tuple_B` -#### output: `bool` -#### signature: `(map-set map-name key-tuple value-tuple)` -#### description: -The `map-set` function sets the value associated with the input key to the inputted value. This function performs a _blind_ update; whether or not a value is already associated with the key, the function overwrites that existing association. - -Note: the `value-tuple` requires 1 additional byte for storage in the materialized blockchain state, and therefore the maximum size of a value that may be inserted into a map is MAX_CLARITY_VALUE - 1. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-set names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-insert -#### input: `MapName, tuple_A, tuple_B` -#### output: `bool` -#### signature: `(map-insert map-name key-tuple value-tuple)` -#### description: -The `map-insert` function sets the value associated with the input key to the inputted value if and only if there is not already a value associated with the key in the map. If an insert occurs, the function returns `true`. If a value already existed for this key in the data map, the function returns `false`. - -Note: the `value-tuple` requires 1 additional byte for storage in the materialized blockchain state, and therefore the maximum size of a value that may be inserted into a map is MAX_CLARITY_VALUE - 1. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns false -(map-insert names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-delete -#### input: `MapName, tuple` -#### output: `bool` -#### signature: `(map-delete map-name key-tuple)` -#### description: -The `map-delete` function removes the value associated with the input key for the given map. If an item exists and is removed, the function returns `true`. If a value did not exist for this key in the data map, the function returns `false`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-delete names-map { name: \"blockstack\" }) ;; Returns true -(map-delete names-map { name: \"blockstack\" }) ;; Returns false -(map-delete names-map (tuple (name \"blockstack\"))) ;; Same command, using a shorthand for constructing the tuple -``` - -### tuple -#### input: `(key-name A), (key-name-2 B), ...` -#### output: `(tuple (key-name A) (key-name-2 B) ...)` -#### signature: `(tuple (key0 expr0) (key1 expr1) ...)` -#### description: -The `tuple` special form constructs a typed tuple from the supplied key and expression pairs. A `get` function can use typed tuples as input to select specific values from a given tuple. Key names may not appear multiple times in the same tuple definition. Supplied expressions are evaluated and associated with the expressions' paired key name. - -There is a shorthand using curly brackets of the form {key0: expr0, key1: expr, ...}` -#### example: -```clarity -(tuple (name \"blockstack\") (id 1337)) ;; using tuple -{name: \"blockstack\", id: 1337} ;; using curly brackets -``` - -### get -#### input: `KeyName, (tuple) | (optional (tuple))` -#### output: `A` -#### signature: `(get key-name tuple)` -#### description: -The `get` function fetches the value associated with a given key from the supplied typed tuple. If an `Optional` value is supplied as the inputted tuple, `get` returns an `Optional` type of the specified key in the tuple. If the supplied option is a `(none)` option, get returns `(none)`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(get id (tuple (name \"blockstack\") (id 1337))) ;; Returns 1337 -(get id (map-get? names-map (tuple (name \"blockstack\")))) ;; Returns (some 1337) -(get id (map-get? names-map (tuple (name \"non-existent\")))) ;; Returns none -``` - -### merge -#### input: `tuple, tuple` -#### output: `tuple` -#### signature: `(merge tuple { key1: val1 })` -#### description: -The `merge` function returns a new tuple with the combined fields, without mutating the supplied tuples. -#### example: -```clarity -(define-map users { id: int } { name: (string-ascii 12), address: (optional principal) }) -(map-insert users { id: 1337 } { name: \"john\", address: none }) ;; Returns true -(let ((user (unwrap-panic (map-get? users { id: 1337 })))) -(merge user { address: (some 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) })) ;; Returns (tuple (address (some SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF)) (name \"john\")) -``` - -### begin -#### input: `AnyType, ... A` -#### output: `A` -#### signature: `(begin expr1 expr2 expr3 ... expr-last)` -#### description: -The `begin` function evaluates each of its input expressions, returning the return value of the last such expression. Note: intermediary statements returning a response type must be checked. -#### example: -```clarity -(begin (+ 1 2) 4 5) ;; Returns 5 -``` - -### hash160 -#### input: `buff|uint|int` -#### output: `(buff 20)` -#### signature: `(hash160 value)` -#### description: -The `hash160` function computes `RIPEMD160(SHA256(x))` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(hash160 0) ;; Returns 0xe4352f72356db555721651aa612e00379167b30f -``` - -### sha256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(sha256 value)` -#### description: -The `sha256` function computes `SHA256(x)` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(sha256 0) ;; Returns 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb -``` - -### sha512 -#### input: `buff|uint|int` -#### output: `(buff 64)` -#### signature: `(sha512 value)` -#### description: -The `sha512` function computes `SHA512(x)` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(sha512 1) ;; Returns 0x6fcee9a7b7a7b821d241c03c82377928bc6882e7a08c78a4221199bfa220cdc55212273018ee613317c8293bb8d1ce08d1e017508e94e06ab85a734c99c7cc34 -``` - -### sha512/256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(sha512/256 value)` -#### description: -The `sha512/256` function computes `SHA512/256(x)` (the SHA512 algorithm with the 512/256 initialization vector, truncated to 256 bits) of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(sha512/256 1) ;; Returns 0x515a7e92e7c60522db968d81ff70b80818fc17aeabbec36baf0dda2812e94a86 -``` - -### keccak256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(keccak256 value)` -#### description: -The `keccak256` function computes `KECCAK256(value)` of the inputted value. Note that this differs from the `NIST SHA-3` (that is, FIPS 202) standard. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(keccak256 0) ;; Returns 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4 -``` - -### secp256k1-recover? -#### input: `(buff 32), (buff 65)` -#### output: `(response (buff 33) uint)` -#### signature: `(secp256k1-recover? message-hash signature)` -#### description: -The `secp256k1-recover?` function recovers the public key used to sign the message which sha256 is `message-hash` with the provided `signature`. If the signature does not match, it will return the error code `(err u1).`. If the signature is invalid, it will return the error code `(err u2).`. The signature includes 64 bytes plus an additional recovery id (00..03) for a total of 65 bytes. -#### example: -```clarity -(secp256k1-recover? 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a1301) - ;; Returns (ok 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) - ``` - -### secp256k1-verify -#### input: `(buff 32), (buff 64) | (buff 65), (buff 33)` -#### output: `bool` -#### signature: `(secp256k1-verify message-hash signature public-key)` -#### description: -The `secp256k1-verify` function verifies that the provided signature of the message-hash was signed with the private key that generated the public key. The `message-hash` is the `sha256` of the message. The signature includes 64 bytes plus an optional additional recovery id (00..03) for a total of 64 or 65 bytes. -#### example: -```clarity -(secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a1301 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns true -(secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a13 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns true -(secp256k1-verify 0x0000000000000000000000000000000000000000000000000000000000000000 - 0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns false - ``` - -### print -#### input: `A` -#### output: `A` -#### signature: `(print expr)` -#### description: -The `print` function evaluates and returns its input expression. On Stacks Core nodes configured for development (as opposed to production mining nodes), this function prints the resulting value to `STDOUT` (standard output). -#### example: -```clarity -(print (+ 1 2 3)) ;; Returns 6 -``` - -### contract-call? -#### input: `ContractName, PublicFunctionName, Arg0, ...` -#### output: `(response A B)` -#### signature: `(contract-call? .contract-name function-name arg0 arg1 ...)` -#### description: -The `contract-call?` function executes the given public function of the given contract. You _may not_ use this function to call a public function defined in the current contract. If the public function returns _err_, any database changes resulting from calling `contract-call?` are aborted. If the function returns _ok_, database changes occurred. -#### example: -```clarity - -;; instantiate the sample-contracts/tokens.clar contract first! -(as-contract (contract-call? .tokens mint! u19)) ;; Returns (ok u19) -``` - -### as-contract -#### input: `A` -#### output: `A` -#### signature: `(as-contract expr)` -#### description: -The `as-contract` function switches the current context's `tx-sender` value to the _contract's_ principal and executes `expr` with that context. It returns the resulting value of `expr`. -#### example: -```clarity -(as-contract tx-sender) ;; Returns S1G2081040G2081040G2081040G208105NK8PE5.docs-test -``` - -### contract-of -#### input: `Trait` -#### output: `principal` -#### signature: `(contract-of .contract-name)` -#### description: -The `contract-of` function returns the principal of the contract implementing the trait. -#### example: -```clarity -(use-trait token-a-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) -(define-public (forward-get-balance (user principal) (contract )) - (begin - (ok (contract-of contract)))) ;; returns the principal of the contract implementing -``` - -### principal-of? -#### input: `(buff 33)` -#### output: `(response principal uint)` -#### signature: `(principal-of? public-key)` -#### description: -The `principal-of?` function returns the principal derived from the provided public key. If the `public-key` is invalid, it will return the error code `(err u1).`. ` -#### example: -```clarity -(principal-of? 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns (ok ST1AW6EKPGT61SQ9FNVDS17RKNWT8ZP582VF9HSCP) -``` - -### at-block -#### input: `(buff 32), A` -#### output: `A` -#### signature: `(at-block id-block-hash expr)` -#### description: -The `at-block` function evaluates the expression `expr` _as if_ it were evaluated at the end of the block indicated by the _block-hash_ argument. The `expr` closure must be read-only. - -This hash uniquely identifies Stacks blocks and is unique across Stacks forks. Note: The block identifying hash must be a hash returned by the `id-header-hash` block information property. While the hash returned by `header-hash` is unique within the context of a single fork, it is not unique across Stacks forks. - -The function returns the result of evaluating `expr`. - -#### example: -```clarity -(define-data-var data int 1) -(at-block 0x0000000000000000000000000000000000000000000000000000000000000000 block-height) ;; Returns u0 -(at-block (get-block-info? id-header-hash 0) (var-get data)) ;; Throws NoSuchDataVariable because `data` wasn't initialized at block height 0 -``` - -### get-block-info? -#### input: `BlockInfoPropertyName, BlockHeightInt` -#### output: `(optional buff) | (optional uint)` -#### signature: `(get-block-info? prop-name block-height-expr)` -#### description: -The `get-block-info?` function fetches data for a block of the given block height. The value and type returned are determined by the specified `BlockInfoPropertyName`. If the provided `BlockHeightInt` does not correspond to an existing block prior to the current block, the function returns `none`. The currently available property names are `time`, `header-hash`, `burnchain-header-hash`, `id-header-hash`, `miner-address`, and `vrf-seed`. - -This is a Unix epoch timestamp in seconds which roughly corresponds to when the block was mined. The `time` property returns an integer value of the block header time field. **Warning**: this does not increase monotonically with each block and block times are accurate only to within two hours. See [BIP113](https://github.com/bitcoin/bips/blob/master/bip-0113.mediawiki) for more information. - -The `header-hash`, `burnchain-header-hash`, `id-header-hash`, and `vrf-seed` properties return a 32-byte buffer. - -The `miner-address` property returns a `principal` corresponding to the miner of the given block. - -The `id-header-hash` is the block identifier value that must be used as input to the `at-block` function. - -#### example: -```clarity -(get-block-info? time u0) ;; Returns (some u1557860301) -(get-block-info? header-hash u0) ;; Returns (some 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb) -(get-block-info? vrf-seed u0) ;; Returns (some 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4) -``` - -### err -#### input: `A` -#### output: `(response A B)` -#### signature: `(err value)` -#### description: -The `err` function constructs a response type from the input value. Use `err` for creating return values in public functions. An _err_ value indicates that any database changes during the processing of the function should be rolled back. -#### example: -```clarity -(err true) ;; Returns (err true) -``` - -### ok -#### input: `A` -#### output: `(response A B)` -#### signature: `(ok value)` -#### description: -The `ok` function constructs a response type from the input value. Use `ok` for creating return values in public functions. An _ok_ value indicates that any database changes during the processing of the function should materialize. -#### example: -```clarity -(ok 1) ;; Returns (ok 1) -``` - -### some -#### input: `A` -#### output: `(optional A)` -#### signature: `(some value)` -#### description: -The `some` function constructs a `optional` type from the input value. -#### example: -```clarity -(some 1) ;; Returns (some 1) -(is-none (some 2)) ;; Returns false -``` - -### default-to -#### input: `A, (optional A)` -#### output: `A` -#### signature: `(default-to default-value option-value)` -#### description: -The `default-to` function attempts to 'unpack' the second argument: if the argument is a `(some ...)` option, it returns the inner value of the option. If the second argument is a `(none)` value, `default-to` it returns the value of `default-value`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(default-to 0 (get id (map-get? names-map (tuple (name \"blockstack\"))))) ;; Returns 1337 -(default-to 0 (get id (map-get? names-map (tuple (name \"non-existant\"))))) ;; Returns 0 -``` - -### asserts! -#### input: `bool, C` -#### output: `bool` -#### signature: `(asserts! bool-expr thrown-value)` -#### description: -The `asserts!` function admits a boolean argument and asserts its evaluation: if bool-expr is `true`, `asserts!` returns `true` and proceeds in the program execution. If the supplied argument is returning a false value, `asserts!` _returns_ `thrown-value` and exits the current control-flow. -#### example: -```clarity -(asserts! (is-eq 1 1) (err 1)) ;; Returns true -``` - -### unwrap! -#### input: `(optional A) | (response A B), C` -#### output: `A` -#### signature: `(unwrap! option-input thrown-value)` -#### description: -The `unwrap!` function attempts to 'unpack' the first argument: if the argument is an option type, and the argument is a `(some ...)` option, `unwrap!` returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, `unwrap!` returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `(none)` value, `unwrap!` _returns_ `thrown-value` from the current function and exits the current control-flow. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(define-private (get-name-or-err (name (string-ascii 12))) - (let ((raw-name (unwrap! (define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(define-private (get-name-or-err (name (string-ascii 12))) - (let ((raw-name (unwrap! names-map { name: name }) (err 1)))) - (ok raw-name))) - -(get-name-or-err \"blockstack\") ;; Returns (ok (tuple (id 1337))) -(get-name-or-err \"non-existant\") ;; Returns (err 1) -``` - -### unwrap-err! -#### input: `(response A B), C` -#### output: `B` -#### signature: `(unwrap-err! response-input thrown-value)` -#### description: -The `unwrap-err!` function attempts to 'unpack' the first argument: if the argument is an `(err ...)` response, `unwrap-err!` returns the inner value of the `err`. If the supplied argument is an `(ok ...)` value, `unwrap-err!` _returns_ `thrown-value` from the current function and exits the current control-flow. -#### example: -```clarity -(unwrap-err! (err 1) false) ;; Returns 1 -``` - -### unwrap-panic -#### input: `(optional A) | (response A B)` -#### output: `A` -#### signature: `(unwrap-panic option-input)` -#### description: -The `unwrap` function attempts to 'unpack' its argument: if the argument is an option type, and the argument is a `(some ...)` option, this function returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, it returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `(none)` value, `unwrap` throws a runtime error, aborting any further processing of the current transaction. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(unwrap-panic (map-get? names-map { name: \"blockstack\" })) ;; Returns (tuple (id 1337)) -(unwrap-panic (map-get? names-map { name: \"non-existant\" })) ;; Throws a runtime exception -``` - -### unwrap-err-panic -#### input: `(response A B)` -#### output: `B` -#### signature: `(unwrap-err-panic response-input)` -#### description: -The `unwrap-err` function attempts to 'unpack' the first argument: if the argument is an `(err ...)` response, `unwrap` returns the inner value of the `err`. If the supplied argument is an `(ok ...)` value, `unwrap-err` throws a runtime error, aborting any further processing of the current transaction. -#### example: -```clarity -(unwrap-err-panic (err 1)) ;; Returns 1 -(unwrap-err-panic (ok 1)) ;; Throws a runtime exception -``` - -### match -#### input: `(optional A) name expression expression | (response A B) name expression name expression` -#### output: `C` -#### signature: `(match opt-input some-binding-name some-branch none-branch) | -(match-resp input ok-binding-name ok-branch err-binding-name err-branch)` -#### description: -The `match` function is used to test and destructure optional and response types. - -If the `input` is an optional, it tests whether the provided `input` is a `some` or `none` option, and evaluates `some-branch` or `none-branch` in each respective case. - -Within the `some-branch`, the _contained value_ of the `input` argument is bound to the provided `some-binding-name` name. - -Only _one_ of the branches will be evaluated (similar to `if` statements). - -If the `input` is a response, it tests whether the provided `input` is an `ok` or `err` response type, and evaluates `ok-branch` or `err-branch` in each respective case. - -Within the `ok-branch`, the _contained ok value_ of the `input` argument is bound to the provided `ok-binding-name` name. - -Within the `err-branch`, the _contained err value_ of the `input` argument is bound to the provided `err-binding-name` name. - -Only _one_ of the branches will be evaluated (similar to `if` statements). - -Note: Type checking requires that the type of both the ok and err parts of the response object be determinable. For situations in which one of the parts of a response is untyped, you should use `unwrap-panic` or `unwrap-err-panic` instead of `match`. -#### example: -```clarity - -(define-private (add-10 (x (optional int))) - (match x - value (+ 10 value) - 10)) -(add-10 (some 5)) ;; Returns 15 -(add-10 none) ;; Returns 10 - -(define-private (add-or-pass-err (x (response int (string-ascii 10))) (to-add int)) - (match x - value (ok (+ to-add value)) - err-value (err err-value))) -(add-or-pass-err (ok 5) 20) ;; Returns (ok 25) -(add-or-pass-err (err \"ERROR\") 20) ;; Returns (err \"ERROR\") -``` - -### try! -#### input: `(optional A) | (response A B)` -#### output: `A` -#### signature: `(try! option-input)` -#### description: -The `try!` function attempts to 'unpack' the first argument: if the argument is an option type, and the argument is a `(some ...)` option, `try!` returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, `try!` returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `none` value, `try!` _returns_ either `none` or the `(err ...)` value from the current function and exits the current control-flow. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(try! (define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(define-private (get-name-or-err (name (string-ascii 12))) - (let ((raw-name (unwrap! names-map { name: \"blockstack\" })) ;; Returns (tuple (id 1337)) -(define-private (checked-even (x int)) - (if (is-eq (mod x 2) 0) - (ok x) - (err false))) -(define-private (double-if-even (x int)) - (ok (* 2 (try! (checked-even x))))) -(double-if-even 10) ;; Returns (ok 20) -(double-if-even 3) ;; Returns (err false) -``` - -### is-ok -#### input: `(response A B)` -#### output: `bool` -#### signature: `(is-ok value)` -#### description: -`is-ok` tests a supplied response value, returning `true` if the response was `ok`, and `false` if it was an `err`. -#### example: -```clarity -(is-ok (ok 1)) ;; Returns true -(is-ok (err 1)) ;; Returns false -``` - -### is-none -#### input: `(optional A)` -#### output: `bool` -#### signature: `(is-none value)` -#### description: -`is-none` tests a supplied option value, returning `true` if the option value is `(none)`, and `false` if it is a `(some ...)`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(is-none (get id (map-get? names-map { name: \"blockstack\" }))) ;; Returns false -(is-none (get id (map-get? names-map { name: \"non-existant\" }))) ;; Returns true -``` - -### is-err -#### input: `(response A B)` -#### output: `bool` -#### signature: `(is-err value)` -#### description: -`is-err` tests a supplied response value, returning `true` if the response was an `err`, and `false` if it was an `ok`. -#### example: -```clarity -(is-err (ok 1)) ;; Returns false -(is-err (err 1)) ;; Returns true -``` - -### is-some -#### input: `(optional A)` -#### output: `bool` -#### signature: `(is-some value)` -#### description: -`is-some` tests a supplied option value, returning `true` if the option value is `(some ...)`, and `false` if it is a `none`. -#### example: -```clarity - -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(is-some (get id (map-get? names-map { name: \"blockstack\" }))) ;; Returns true -(is-some (get id (map-get? names-map { name: \"non-existant\" }))) ;; Returns false -``` - -### filter -#### input: `Function(A) -> bool, sequence_A` -#### output: `sequence_A` -#### signature: `(filter func sequence)` -#### description: -The `filter` function applies the input function `func` to each element of the input sequence, and returns the same sequence with any elements removed for which `func` returned `false`. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. ` -#### example: -```clarity - -(filter not (list true false true false)) ;; Returns (false false) -(define-private (is-a (char (string-utf8 1))) (is-eq char u\"a\")) -(filter is-a u\"acabd\") ;; Returns u\"aa\" -(define-private (is-zero (char (buff 1))) (is-eq char 0x00)) -(filter is-zero 0x00010002) ;; Returns 0x0000 -``` - -### ft-get-balance -#### input: `TokenName, principal` -#### output: `uint` -#### signature: `(ft-get-balance token-name principal)` -#### description: -`ft-get-balance` returns `token-name` balance of the principal `principal`. The token type must have been defined using `define-fungible-token`. -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-get-balance stackaroo 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns u100 -``` - -### nft-get-owner? -#### input: `AssetName, A` -#### output: `(optional principal)` -#### signature: `(nft-get-owner? asset-class asset-identifier)` -#### description: -`nft-get-owner?` returns the owner of an asset, identified by `asset-identifier`, or `none` if the asset does not exist. The asset type must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) -(nft-get-owner? stackaroo \"Roo\") ;; Returns (some SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) -(nft-get-owner? stackaroo \"Too\") ;; Returns none -``` - -### ft-transfer? -#### input: `TokenName, uint, principal, principal` -#### output: `(response bool uint)` -#### signature: `(ft-transfer? token-name amount sender recipient)` -#### description: -`ft-transfer?` is used to increase the token balance for the `recipient` principal for a token type defined using `define-fungible-token` by debiting the `sender` principal. In contrast to `stx-transfer?`, any user can transfer the assets. When used, relevant guards need to be added. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- amount to send is non-positive ` -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-transfer? stackaroo u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(ft-transfer? stackaroo u60 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u1) -``` - -### nft-transfer? -#### input: `AssetName, A, principal, principal` -#### output: `(response bool uint)` -#### signature: `(nft-transfer? asset-class asset-identifier sender recipient)` -#### description: -`nft-transfer?` is used to change the owner of an asset identified by `asset-identifier` from `sender` to `recipient`. The `asset-class` must have been defined by `define-non-fungible-token` and `asset-identifier` must be of the type specified in that definition. In contrast to `stx-transfer?`, any user can transfer the asset. When used, relevant guards need to be added. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not own the asset `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- asset identified by asset-identifier does not exist ` -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(nft-transfer? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(nft-transfer? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u1) -(nft-transfer? stackaroo \"Stacka\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u3) -``` - -### nft-mint? -#### input: `AssetName, A, principal` -#### output: `(response bool uint)` -#### signature: `(nft-mint? asset-class asset-identifier recipient)` -#### description: -`nft-mint?` is used to instantiate an asset and set that asset's owner to the `recipient` principal. The asset must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. - -If an asset identified by `asset-identifier` _already exists_, this function will return an error with the following error code: - -`(err u1)` - -Otherwise, on successfuly mint, it returns `(ok true)`. ` -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### ft-mint? -#### input: `TokenName, uint, principal` -#### output: `(response bool uint)` -#### signature: `(ft-mint? token-name amount recipient)` -#### description: -`ft-mint?` is used to increase the token balance for the `recipient` principal for a token type defined using `define-fungible-token`. The increased token balance is _not_ transfered from another principal, but rather minted. - -If a non-positive amount is provided to mint, this function returns `(err 1)`. Otherwise, on successfuly mint, it returns `(ok true)`. ` -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### ft-get-supply -#### input: `TokenName` -#### output: `uint` -#### signature: `(ft-get-supply token-name)` -#### description: -`ft-get-balance` returns `token-name` circulating supply. The token type must have been defined using `define-fungible-token`. -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-get-supply stackaroo) ;; Returns u100 -``` - -### ft-burn? -#### input: `TokenName, uint, principal` -#### output: `(response bool uint)` -#### signature: `(ft-burn? token-name amount sender)` -#### description: -`ft-burn?` is used to decrease the token balance for the `sender` principal for a token type defined using `define-fungible-token`. The decreased token balance is _not_ transfered to another principal, but rather destroyed, reducing the circulating supply. - -If a non-positive amount is provided to burn, this function returns `(err 1)`. Otherwise, on successfuly burn, it returns `(ok true)`. - -#### example: -```clarity - -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(ft-burn? stackaroo u50 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### nft-burn? -#### input: `AssetName, A, principal` -#### output: `(response bool uint)` -#### signature: `(nft-burn? asset-class asset-identifier recipient)` -#### description: -`nft-burn?` is used to burn an asset and remove that asset's owner from the `recipient` principal. The asset must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. - -If an asset identified by `asset-identifier` _doesn't exist_, this function will return an error with the following error code: - -`(err u1)` - -Otherwise, on successfuly burn, it returns `(ok true)`. ` -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(nft-burn? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### stx-get-balance -#### input: `principal` -#### output: `uint` -#### signature: `(stx-get-balance owner)` -#### description: -`stx-get-balance` is used to query the STX balance of the `owner` principal. - -This function returns the STX balance of the `owner` principal. In the event that the `owner` principal isn't materialized, it returns 0. - -#### example: -```clarity -(stx-get-balance 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns u0 -(stx-get-balance (as-contract tx-sender)) ;; Returns u1000 -``` - -### stx-transfer? -#### input: `uint, principal, principal` -#### output: `(response bool uint)` -#### signature: `(stx-transfer? amount sender recipient)` -#### description: -`stx-transfer?` is used to increase the STX balance for the `recipient` principal by debiting the `sender` principal. The `sender` principal _must_ be equal to the current context's `tx-sender`. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- amount to send is non-positive `(err u4)` -- the `sender` principal is not the current `tx-sender` - -#### example: -```clarity - -(as-contract - (stx-transfer? u60 tx-sender 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (ok true) -(as-contract - (stx-transfer? u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR tx-sender)) ;; Returns (err u4) -``` - -### stx-burn? -#### input: `uint, principal` -#### output: `(response bool uint)` -#### signature: `(stx-burn? amount sender)` -#### description: -`stx-burn?` debits the `sender` principal's STX holdings by `amount`, destroying the STX. The `sender` principal _must_ be equal to the current context's `tx-sender`. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u3)` -- amount to send is non-positive `(err u4)` -- the `sender` principal is not the current `tx-sender` - -#### example: -```clarity -(as-contract - (stx-burn? u60 tx-sender)) ;; Returns (ok true) -(as-contract - (stx-burn? u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (err u4) -``` - -### define-constant -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-constant name expression)` -#### description: -`define-constant` is used to define a private constant value in a smart contract. The expression passed into the definition is evaluated at contract launch, in the order that it is supplied in the contract. This can lead to undefined function or undefined variable errors in the event that a function or variable used in the expression has not been defined before the constant. - -Like other kinds of definition statements, `define-constant` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -#### example: -```clarity - -(define-constant four (+ 2 2)) -(+ 4 four) ;; Returns 8 -``` - -### define-private -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-private (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### description: -`define-private` is used to define _private_ functions for a smart contract. Private functions may not be called from other smart contracts, nor may they be invoked directly by users. Instead, these functions may only be invoked by other functions defined in the same smart contract. - -Like other kinds of definition statements, `define-private` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Private functions may return any type. -#### example: -```clarity -(define-private (max-of (i1 int) (i2 int)) - (if (> i1 i2) - i1 - i2)) -(max-of 4 6) ;; Returns 6 -``` - -### define-public -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-public (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### description: -`define-public` is used to define a _public_ function and transaction for a smart contract. Public functions are callable from other smart contracts and may be invoked directly by users by submitting a transaction to the Stacks blockchain. - -Like other kinds of definition statements, `define-public` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Public functions _must_ return a ResponseType (using either `ok` or `err`). Any datamap modifications performed by a public function is aborted if the function returns an `err` type. Public functions may be invoked by other contracts via `contract-call?`. -#### example: -```clarity -(define-public (hello-world (input int)) - (begin (print (+ 2 input)) - (ok input))) -``` - -### define-read-only -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-read-only (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### description: -`define-read-only` is used to define a _public read-only_ function for a smart contract. Such functions are callable from other smart contracts. - -Like other kinds of definition statements, `define-read-only` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Read-only functions may return any type. However, read-only functions may not perform any datamap modifications, or call any functions which perform such modifications. This is enforced both during type checks and during the execution of the function. Public read-only functions may be invoked by other contracts via `contract-call?`. -#### example: -```clarity -(define-read-only (just-return-one-hundred) - (* 10 10)) - ``` - -### define-map -#### input: `MapName, TypeDefinition, TypeDefinition` -#### output: `Not Applicable` -#### signature: `(define-map map-name key-type value-type)` -#### description: -`define-map` is used to define a new datamap for use in a smart contract. Such maps are only modifiable by the current smart contract. - -Maps are defined with a key type and value type, often these types are tuple types. - -Like other kinds of definition statements, `define-map` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). -#### example: -```clarity -(define-map squares { x: int } { square: int }) -(define-private (add-entry (x int)) - (map-insert squares { x: 2 } { square: (* x x) })) -(add-entry 1) -(add-entry 2) -(add-entry 3) -(add-entry 4) -(add-entry 5) -``` - -### define-data-var -#### input: `VarName, TypeDefinition, Value` -#### output: `Not Applicable` -#### signature: `(define-data-var var-name type value)` -#### description: -`define-data-var` is used to define a new persisted variable for use in a smart contract. Such variable are only modifiable by the current smart contract. - -Persisted variable are defined with a type and a value. - -Like other kinds of definition statements, `define-data-var` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). -#### example: -```clarity -(define-data-var size int 0) -(define-private (set-size (value int)) - (var-set size value)) -(set-size 1) -(set-size 2) -``` - -### define-fungible-token -#### input: `TokenName, ` -#### output: `Not Applicable` -#### signature: `(define-fungible-token token-name )` -#### description: -`define-fungible-token` is used to define a new fungible token class for use in the current contract. - -The second argument, if supplied, defines the total supply of the fungible token. This ensures that all calls to the `ft-mint?` function will never be able to create more than `total-supply` tokens. If any such call were to increase the total supply of tokens passed that amount, that invocation of `ft-mint?` will result in a runtime error and abort. - -Like other kinds of definition statements, `define-fungible-token` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Tokens defined using `define-fungible-token` may be used in `ft-transfer?`, `ft-mint?`, and `ft-get-balance` functions` -#### example: -```clarity -(define-fungible-token stacks) -(define-fungible-token limited-supply-stacks u100) -``` - -### define-non-fungible-token -#### input: `AssetName, TypeSignature` -#### output: `Not Applicable` -#### signature: `(define-non-fungible-token asset-name asset-identifier-type)` -#### description: -`define-non-fungible-token` is used to define a new non-fungible token class for use in the current contract. Individual assets are identified by their asset identifier, which must be of the type `asset-identifier-type`. Asset identifiers are _unique_ identifiers. - -Like other kinds of definition statements, `define-non-fungible-token` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Assets defined using `define-non-fungible-token` may be used in `nft-transfer?`, `nft-mint?`, and `nft-get-owner?` functions` -#### example: -```clarity -(define-non-fungible-token names (buff 50)) -``` - -### define-trait -#### input: `VarName, [MethodSignature]` -#### output: `Not Applicable` -#### signature: `(define-trait trait-name ((func1-name (arg1-type arg2-type ...) (return-type))))` -#### description: -`define-trait` is used to define a new trait definition for use in a smart contract. Other contracts can implement a given trait and then have their contract identifier being passed as function arguments in order to be called dynamically with `contract-call?`. - -Traits are defined with a name, and a list functions defined with a name, a list of argument types, and return type. - -Like other kinds of definition statements, `define-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -#### example: -```clarity -(define-trait token-trait - ((transfer? (principal principal uint) (response uint uint)) - (get-balance (principal) (response uint uint)))) -``` - -### use-trait -#### input: `VarName, TraitIdentifier` -#### output: `Not Applicable` -#### signature: `(use-trait trait-alias trait-identifier)` -#### description: -`use-trait` is used to bring a trait, defined in another contract, to the current contract. Subsequent references to an imported trait are signaled with the syntax ``. - -Traits import are defined with a name, used as an alias, and a trait identifier. Trait identifiers can either be using the sugared syntax (.token-a.token-trait), or be fully qualified ('SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait). - -Like other kinds of definition statements, `use-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put such a statement in the middle of a function body). -#### example: -```clarity -(use-trait token-a-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) -(define-public (forward-get-balance (user principal) (contract )) - (begin - (ok 1))) -``` - -### impl-trait -#### input: `TraitIdentifier` -#### output: `Not Applicable` -#### signature: `(impl-trait trait-identifier)` -#### description: -`impl-trait` can be use for asserting that a contract is fully implementing a given trait. Additional checks are being performed when the contract is being published, rejecting the deployment if the contract is violating the trait specification. - -Trait identifiers can either be using the sugared syntax (.token-a.token-trait), or be fully qualified ('SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait). - -Like other kinds of definition statements, `impl-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put such a statement in the middle of a function body). - -#### example: -```clarity -(impl-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) (define-public (get-balance (account principal)) (ok u0)) (define-public (transfer? (from principal) (to principal) (amount uint)) - (ok u0)) -``` \ No newline at end of file diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md b/i18n/ja/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md deleted file mode 100644 index fd62451198..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Keywords -description: See a detailed list of all keywords for the Clarity language. -tags: - - clarity ---- - -![](/img/keywords.jpg) -## Keyword reference - -Detailed list of all keywords for the Clarity language. - - -### contract-caller -#### output: `principal` -#### description: -Returns the caller of the current contract context. If this contract is the first one called by a signed transaction, the caller will be equal to the signing principal. If `contract-call?` was used to invoke a function from a new contract, `contract-caller` changes to the _calling_ contract's principal. If `as-contract` is used to change the `tx-sender` context, `contract-caller` _also_ changes to the same contract principal. -#### example: -```clarity -(print contract-caller) ;; Will print out a Stacks address of the transaction sender -``` - -### tx-sender -#### output: `principal` -#### description: -Returns the original sender of the current transaction, or if `as-contract` was called to modify the sending context, it returns that contract principal. -#### example: -```clarity -(print tx-sender) ;; Will print out a Stacks address of the transaction sender -``` - -### block-height -#### output: `uint` -#### description: -Returns the current block height of the Stacks blockchain as an uint -#### example: -```clarity -(> block-height 1000) ;; returns true if the current block-height has passed 1000 blocks. -``` - -### burn-block-height -#### output: `uint` -#### description: -Returns the current block height of the underlying burn blockchain as a uint -#### example: -```clarity -(> burn-block-height 1000) ;; returns true if the current height of the underlying burn blockchain has passed 1000 blocks. -``` - -### none -#### output: `(optional ?)` -#### description: -Represents the _none_ option indicating no value for a given optional (analogous to a null value). -#### example: -```clarity -(define-public (only-if-positive (a int)) - (if (> a 0) - (some a) - none)) -(only-if-positive 4) ;; Returns (some 4) -(only-if-positive (- 3)) ;; Returns none -``` - -### true -#### output: `bool` -#### description: -Boolean true constant. -#### example: -```clarity -(and true false) ;; Evaluates to false -(or false true) ;; Evaluates to true -``` - -### false -#### output: `bool` -#### description: -Boolean false constant. -#### example: -```clarity -(and true false) ;; Evaluates to false -(or false true) ;; Evaluates to true -``` - -### stx-liquid-supply -#### output: `uint` -#### description: -Returns the total number of micro-STX (uSTX) that are liquid in the system as of this block. -#### example: -```clarity -(print stx-liquid-supply) ;; Will print out the total number of liquid uSTX -``` - -### is-in-regtest -#### output: `bool` -#### description: -Returns whether or not the code is running in a regression test -#### example: -```clarity -(print is-in-regtest) ;; Will print 'true' if the code is running in a regression test -``` - diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md b/i18n/ja/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md deleted file mode 100644 index d22f991413..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Types -description: See a detailed list of all types for the Clarity language. -tags: - - clarity ---- - -## Clarity Type System - -The type system contains the following types: - -| Types | Notes | -| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `int` | signed 128-bit integer | -| `uint` | unsigned 128-bit integer | -| `bool` | boolean value (`true` or `false`) | -| `principal` | object representing a principal (whether a contract principal or standard principal) | -| `(buff max-len)` | byte buffer of 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` (u"A smiley face emoji \u{1F600} as a utf8 string") | -| `(list max-len entry-type)` | list of maximum length `max-len`, with entries of type `entry-type` | -| `{label-0: value-type-0, label-1: value-type-1, ...}` | tuple, group of data values with named fields | -| `(optional some-type)` | an option type for objects that can either be `(some value)` or `none` | -| `(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. | diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md b/i18n/ja/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md deleted file mode 100644 index e75e1d69b9..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Clarity overview -description: Overview and guides for getting started with Clarity -sidebar_label: Write smart contracts -sidebar_position: 2 ---- - -## Introduction - -Clarity is a **decidable** smart contract language that optimizes for predictability and security, designed for the Stacks blockchain. Smart contracts allow developers to encode essential business logic on a blockchain. - -## Smart contracts - -Smart contracts encode and enforce rules for modifying a particular set of data that is shared among people and entities who don't necessarily trust each other. For example, a smart contract can hold funds in escrow until multiple parties agree to release them, create its own ledger and keep track of its own novel tokens (fungible or non-fungible), and even help make supply chains more transparent. - -A smart contract execution can result in new transactions being written to the blockchain. Because smart contracts are programs that exist in a blockchain, anyone can query them, and anyone can submit transactions to execute them. - -Apps can take advantage of smart contracts to manage a global state that is visible to the public. Anyone can audit the blockchain to independently verify that an app's global shared state has been managed correctly according to the smart contract's rules. - -There is a [Clarity Visual Studio Code plugin][] available for syntax assistance and debugging. - -## Use cases - -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 (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 - -## Language design - -Clarity differs from most other smart contract languages in two essential ways: - -- The language is interpreted and broadcast on the blockchain as is (not compiled) -- The language is decidable (not Turing complete) - -Using an interpreted language ensures that the executed code is human-readable and auditable. A decidable language like Clarity makes it possible to determine precisely which code is executed, for any function. - -A Clarity smart contract consists of two parts, a data space and a set of functions. Only the associated smart contract may modify its corresponding data space on the blockchain. Functions may be private and thus callable only from within the smart contract, or public and thus callable from other contracts. Users call smart contracts' public functions by broadcasting a transaction on the blockchain which invokes the public function. Contracts can also call public functions from other smart contracts. - -Note some of the key Clarity language rules and limitations. - -- The only primitive types are booleans, integers, buffers, and principals. -- Recursion is illegal and there are no anonymous functions. -- Looping is only performed via `map`, `filter`, or `fold`. -- There is support for lists, however, the only variable length lists in the language appear as function inputs; there is no support for list operations like append or join. -- Variables are immutable. - -## Explore more - -For language details and references, see the following: - -- [Clarity language overview](./clarity-language/) -- [Understating Principals](principals) -- [Clarity Values](values) - -[Clarity Visual Studio Code plugin]: https://marketplace.visualstudio.com/items?itemName=HiroSystems.clarity-lsp diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md b/i18n/ja/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md deleted file mode 100644 index 912ea694a6..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md +++ /dev/null @@ -1,232 +0,0 @@ ---- -title: Principals -description: 'Clarity: Understanding Principals' -sidebar_position: 1 ---- - -## Introduction - -_Principals_ are a Clarity native type that represents an entity that can have a token balance. This section discusses principals and how they are used in the Clarity. - -## Principals and tx-sender - -Assets in the smart contracting language and blockchain are "owned" by objects of the principal type, meaning that any object of the principal type may own an asset. For the case of public-key hash and multi-signature Stacks addresses, a given principal can operate on their assets by issuing a signed transaction on the blockchain. _Smart contracts_ may also be principals (represented by the smart contract's identifier), however, there is no private key associated with the smart contract, and it cannot broadcast a signed transaction on the blockchain. - -A Clarity contract can use a globally defined `tx-sender` variable to obtain the current principal. The following example defines a transaction type that transfers `amount` microSTX from the sender to a recipient if amount is a multiple of 10, otherwise returning a 400 error code. - -```clarity -(define-public (transfer-to-recipient! (recipient principal) (amount uint)) - (if (is-eq (mod amount 10) 0) - (stx-transfer? amount tx-sender recipient) - (err u400))) -``` - -Clarity provides an additional variable to help smart contracts authenticate a transaction sender. The keyword `contract-caller` returns the principal that _called_ the current contract. If an inter-contract call occurred, `contract-caller` returns the last contract in the stack of callers. For example, suppose there are three contracts A, B, and C, each with an `invoke` function such that `A::invoke` calls `B::invoke` and `B::invoke` calls `C::invoke`. - -When a user Bob issues a transaction that calls `A::invoke`, the value of `contract-caller` in each successive invoke function's body would change: - -```clarity -in A::invoke, contract-caller = Bob -in B::invoke, contract-caller = A -in C::invoke, contract-caller = B -``` - -This allows contracts to make assertions and perform authorization checks using not only the `tx-sender` (which in this example, would always be "Bob"), but also using the `contract-caller`. This could be used to ensure that a particular function is only ever called directly and never called via an inter-contract call (by asserting that `tx-sender` and `contract-caller` are equal). We provide an example of a two different types of authorization checks in the rocket ship example below. - -## Smart contracts as principals - -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, for example: - -```clarity -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-name -``` - -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 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 qualified identifier for the contracts would be: - -```clarity -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-A -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-B -``` - -But, in the contract source code, if the developer wishes to call a function from `contract-A` in `contract-B`, they can write - -```clarity -(contract-call? .contract-A public-function-foo) -``` - -This allows the smart contract developer to modularize their applications across multiple smart contracts _without_ knowing the publishing key a priori. - -In order for a smart contract to operate on assets it owns, smart contracts may use the special `(as-contract ...)` function. This function executes the expression (passed as an argument) with the `tx-sender` set to the contract's principal, rather than the current sender. The `as-contract` function returns the value of the provided expression. - -For example, a smart contract that implements something like a "token faucet" could be implemented as so: - -```clarity -(define-map claimed-before - ((sender principal)) - ((claimed bool))) - -(define-constant err-already-claimed u1) -(define-constant err-faucet-empty u2) -(define-constant stx-amount u1) - -(define-public (claim-from-faucet) - (let ((requester tx-sender)) ;; set a local variable requester = tx-sender - (asserts! (is-none (map-get? claimed-before {sender: requester})) (err err-already-claimed)) - (unwrap! (as-contract (stx-transfer? stx-amount tx-sender requester)) (err err-faucet-empty)) - (map-set claimed-before {sender: requester} {claimed: true}) - (ok stx-amount))) -``` - -In this example, the public function `claim-from-faucet`: - -- Checks if the sender has claimed from the faucet before. -- Assigns the tx sender to a `requester` variable. -- Adds an entry to the tracking map. -- Uses `as-contract` to send 1 microstack - -Unlike other principals, there is no private key associated with a smart contract. As it lacks a private key, a Clarity smart contract cannot broadcast a signed transaction on the blockchain. - -## Example: Authorization checks - -The interactions between `tx-sender`, `contract-caller` and `as-contract` are subtle, but are important when performing authorization checks in a contract. In this example contract, we'll show two different kinds of authorization checks a contract may wish to perform, and then walk through how different ways in which contract functions may be called will pass or fail those checks. - -This contract defines a "rocket-ship" non-fungible-token that a principal may own and manage the authorized pilots. Pilots are principals that are allowed to "fly" the rocket ship. - -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. -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 be called _directly_ by the ship's owner, rather than through a inter-contract-call. - -The second type of check is more restrictive than the first check, and is helpful for guarding very sensitive routines --- it protects users from unknowingly calling a function on a malicious contract that subsequently tries to call sensitive functions on another contract. - -```clarity -;; -;; rockets-base.clar -;; - -(define-non-fungible-token rocket-ship uint) - -;; a map from rocket ships to their allowed -;; pilots -(define-map allowed-pilots - ((rocket-ship uint)) ((pilots (list 10 principal)))) - -;; implementing a contains function via fold -(define-private (contains-check - (y principal) - (to-check { p: principal, result: bool })) - (if (get result to-check) - to-check - { p: (get p to-check), - result: (is-eq (get p to-check) y) })) - -(define-private (contains (x principal) (find-in (list 10 principal))) - (get result (fold contains-check find-in - { p: x, result: false }))) - -(define-read-only (is-my-ship (ship uint)) - (is-eq (some tx-sender) (nft-get-owner? rocket-ship ship))) - -;; this function will print a message -;; (and emit an event) if the tx-sender was -;; an authorized flyer. -;; -;; here we use tx-sender, because we want -;; to allow the user to let other contracts -;; fly the ship on behalf of users - -(define-public (fly-ship (ship uint)) - (let ((pilots (default-to - (list) - (get pilots (map-get? allowed-pilots { rocket-ship: ship }))))) - (if (contains tx-sender pilots) - (begin (print "Flew the rocket-ship!") - (ok true)) - (begin (print "Tried to fly without permission!") - (ok false))))) -;; -;; Authorize a new pilot. -;; -;; here we want to ensure that this function -;; was called _directly_ by the user by -;; checking that tx-sender and contract-caller are equal. -;; if any other contract is in the call stack, contract-caller -;; would be updated to a different principal. -;; -(define-public (authorize-pilot (ship uint) (pilot principal)) - (begin - ;; sender must equal caller: an intermediate contract is - ;; not issuing this call. - (asserts! (asserts! (is-eq tx-sender contract-caller) (err u1)) - ;; sender must own the rocket ship - (asserts! (is-eq (some tx-sender) - (nft-get-owner? rocket-ship ship)) (err u2)) - (let ((prev-pilots (default-to - (list) - (get pilots (map-get? allowed-pilots { rocket-ship: ship }))))) - ;; don't add a pilot already in the list - (asserts! (not (contains pilot prev-pilots)) (err u3)) - ;; append to the list, and check that it is less than - ;; the allowed maximum - (match (as-max-len? -``` - -### Extending functionality: Multi-flyer contract - -The authorization scheme for `fly-ship` allows pilots to fly rocket-ships from other contracts. This allows other contracts to provide new functionality built around calling that function. - -For example, we can create a contract that calls `fly-ship` for multiple rocket-ships in a single transaction: - -```clarity -;; -;; rockets-multi.clar -;; - -(define-private (call-fly (ship uint)) - (unwrap! (contract-call? .rockets-base fly-ship ship) false)) -;; try to fly all the ships, returning a list of whether -;; or not we were able to fly the supplied ships -(define-public (fly-all (ships (list 10 uint))) - (ok (map call-fly ships))) -``` - -### Authorization for Contract-Owned Assets - -The check in `authorize-pilot` protects users from malicious contracts, but how would such a scheme support contract-owned assets? This is what the `as-contract` function is used for. The `as-contract` function executes the supplied closure as if the sender of the transaction was the current contract, rather than the user -- it does this by updating `tx-sender` to the current contract principal. We can use this to, for example, create a smart contract rocket-ship-line: - -```clarity -;; -;; rockets-ship-line.clar -;; - -(define-constant line-ceo 'SP19Y6GRV9X778VFS1V8WT2H502WFK33XZXADJWZ) - -(define-data-var employed-pilots (list 10 principal) (list)) - -;; This function will: -;; * check that it is called by the line-ceo -;; * check that the rocket is owned by the contract -;; * authorize each employed pilot to the ship -(define-public (add-managed-rocket (ship uint)) - (begin - ;; 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 - (asserts! (contract-call? .rockets-base is-my-ship ship) (err u2)) - ;; register all of our pilots on the ship - (add-pilots-to ship))))) - -;; add all the pilots to a ship using fold -- -;; the fold checks the return type of previous calls, -;; skipping subsequent contract-calls if one fails. -(define-private (add-pilot-via-fold (pilot principal) (prior-result (response uint uint))) - (let ((ship (try! prior-result))) - (try! (contract-call? .rockets-base authorize-pilot ship pilot)) - (ok ship))) -(define-private (add-pilots-to (ship uint)) - (fold add-pilot-via-fold (var-get employed-pilots) (ok ship))) -``` - -In order for the contract to add each pilot to a new ship, the contract must call `authorize-pilot`. However, the contract wants to perform this action on behalf of a ship the _contract_ owns, not the transaction sender. To do this, the contract uses `as-contract`. diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md b/i18n/ja/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md deleted file mode 100644 index a01e37bc04..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Resources -description: 'Resources' -sidebar_position: 8 ---- - -# External resources - - -[Clarity book](https://book.clarity-lang.org/) - -[Clarity Universe](https://stacks.org/clarity-universe) - -[Hiro Clarity tutorials](https://docs.hiro.so/tutorials) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md b/i18n/ja/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md deleted file mode 100644 index ed65829518..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Clarity development software -description: The following tools are useful when developing Clarity smart contracts -sidebar_position: 4 ---- - -## Language Server Protocol for Clarity (including Visual Studio Code extension) - -The Language Server Protocol (LSP) defines the protocol used between an editor or IDE and a language server that provides language features like auto complete, go to definition, find all references etc. - -This makes programming in Clarity easier and much more intuitive. - -![Clarity LSP Screenshot](https://raw.githubusercontent.com/hirosystems/clarity-lsp/21b64298ca117dc41358eb9dce4605cc4a448a4c/images/screenshot.png?raw=true) - - -Clarity LSP repository is available [here](https://github.com/hirosystems/clarity-lsp). The extension for Visual Studio Code can be downloaded directly from [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=HiroSystems.clarity-lsp), but can be and older version. For a more up to date version you can also download it from [open-vsx](https://open-vsx.org/extension/hirosystems/clarity-lsp). - -## Clarity REPL - -A read—eval—print loop (REPL), also termed an interactive toplevel or language shell, is a simple, interactive computer programming environment that takes single user inputs (that is, single expressions), evaluates (executes) them, and returns the result to the user; a program written in a REPL environment is executed piecewise. - -![Clarity-repl](https://github.com/hirosystems/clarity-repl/blob/develop/docs/images/screenshot.png?raw=true) - -Instructions on how to install Clarity REPL can be found [here](https://github.com/hirosystems/clarity-repl). - -## Clarinet - -Clarinet is a Clarity runtime packaged as a command line tool, designed to facilitate smart contract understanding, development, testing and deployment. Clarinet consists of a Clarity REPL and a testing harness, which, when used together allow you to rapidly develop and test a Clarity smart contract, with the need to deploy the contract to a local devnet or testnet. - -![Clarinet](https://github.com/hirosystems/clarinet/blob/develop/docs/images/demo.gif?raw=true) - -Installation instructions, including build from source instructions can be found [here](https://github.com/hirosystems/clarinet). If you prefer you can directly download the latest compiled realease for Windows, Mac and Linux [here](https://github.com/hirosystems/clarinet/releases). - -[Clarinet 101](https://www.youtube.com/playlist?list=PL5Ujm489LoJaAz9kUJm8lYUWdGJ2AnQTb) contains multiple Clarinet video tutorials - -### Getting started with Clarinet - -You can verify you have Clarinet installed by checking its version: - -```bash -$ clarinet --version -clarinet 0.70 -``` - -More detailed information on using Clarinet is available [here](https://book.clarity-lang.org/ch07-00-using-clarinet.html). However to get you started, the following commands are important to know. - -Create a new project and enter its directory: - -```bash -clarinet new my-project && cd my-project -``` - -Create a new contract inside `my-project`: - -```bash -clarinet contract new mycoolcontract -``` - -Check the syntax of Clarity: - -```bash -clarity check -``` - -To test your contract: - -```bash -clarinet test -``` - -Enter Clarinet's console: - -```bash -clarinet console -``` diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md b/i18n/ja/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md deleted file mode 100644 index 2754709092..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Tokens -description: Learn about token support within Clarity -sidebar_position: 3 ---- - -## Introduction - -A fundamental use of blockchain technology is the representation, store, and transfer of value between users of a blockchain. Cryptocurrency is a very common use of blockchain technology, and remains one of the primary drivers of adoption of blockchain technology. Cryptocurrencies are represented by blockchain tokens: individual units of value within a given blockchain ecosystem. Blockchain tokens can extend beyond just digital currency, however, and recent developments throughout the cryptocurrency community have demonstrated potential for the use of blockchain to tokenize and represent not just money but other tangible assets. - -A blockchain token is a digital asset that can be verifiably owned by a user of a blockchain. Blockchain tokens are governed by a set of rules that are defined by either the blockchain itself (in the case of native tokens) or by a smart contract on a blockchain. Rules can vary depending on the nature and the use of the token. - -Tokens on a blockchain fall into two general categories, depending on their properties: [fungible][] or [non-fungible][]. The following sections discuss the properties of both types of tokens, and provide information about implementation of the two types of tokens on Stacks. - -## Fungible tokens - -A core property of any token on a blockchain is fungibility. A fungible token is a token that's mutually interchangable or capable of mutual substitution. In other words, one quantity or part of a fungible token can be replaced by an equal quantity or part of the same fungible token. Fungible tokens are often used to represent real-world fungible assets like currency. The STX token is an example of a fungible token. Other examples include stablecoins, tokens that represent voting rights in a DAO, or tokens that algorithmically track the price of stocks. - -Fungible tokens form one of the most important value propositions for blockchain technology, the ability to store value and exchange that value through both internal and external transactions. Because fungible tokens can be divided into smaller parts and recombined into the same value representation, they serve a great utility for transferring value between blockchain users. - -The primary fungible token on the Stacks blockchain is the native token, STX. Because the Stacks blockchain allows for the creation of \[smart contracts\]\[\], other fungible tokens can be created on the Stacks blockchain as well. [SIP-010][] specifies the standard for fungible tokens on the Stacks blockchain. This specification defines the functions and traits that a fungible token on Stacks _must_ have. This specification defines the functions and traits that a fungible token on Stacks _must_ have. - -### Understanding the fungible token standard - -The [SIP-010][] standard is an interface definition that allows Stacks applications and wallets to interact with fungible tokens in a standard way. Supporting the standard reduces complexity for token creators to get their tokens into the ecosystem. Under the [SIP-010][] standard, fungible tokens must have the following characteristics: - -- Ability to transfer a specified amount of the token to a recipient (`transfer`). The recipient is required to be a Stacks principal. -- Ability to obtain the human-readable name of the token (`get-name`). -- Ability to obtain a short name (ticker symbol) for the token (`get-symbol`). -- Ability to get the number of decimals in the token representation (`get-decimals`). This is used to construct a representation of the token that humans would be familiar dealing with. For example, the US dollar has 2 decimals, if the base unit is cents. -- Ability to get the balance of the token for a particular Stacks principal (`get-balance-of`). -- Ability to get the total supply of the token (`get-total-supply`). -- A URI to metadata associated with the token (`get-token-uri`). This can resolve to off-chain metadata about the token or contract, such as an image icon for the token or a description. - -## Non-fungible tokens (NFTs) - -Non-fungible tokens (NFTs) are a type of token that are not interchangeable. NFTs have unique traits (usually in the form of attached metadata) that restrict the abillity to replace them with identical tokens. An NFT is a token that is unique, such as a piece of art, or ownership rights to a real-world asset such as a house. - -NFTs alone don't have an inherent value, like a currency. The value of an NFT is derived from the assets that the NFT represents. The use of NFTs are myriad, including digital art, collectibles, domain names, and representation of ownership of content rights. NFTs can be used as digital certificates that track the authenticty of real world items, or digitize the ownership rights to property. - -As with fungible tokens, NFTs on the Stacks blockchain are created with smart contracts. [SIP-009][] specifies the standard for NFTs on the Stacks blockchain. This specification defines the functions and traits that an NFT _must_ have, but most NFTs have more functions or traits attached than those solely described by the specification. By complying with this standard, non-fungible tokens on Stacks can be easily represented by wallets that support Stacks. - -### Understanding the non-fungible token standard - -The [SIP-009][] standard is an interface definition that the Stacks ecosystem aligned on. With support for this standard across wallets and tools, it becomes easy to interact with NFTs. Under the [SIP-009][] standard, NFT contract must have the following characteristics: - -- Ability to obtain the last token identifier (`get-last-token-id`). This id represents the upper limit of NFTs issued by the contract. -- A URI to metadata associated with a specific token identifier. (`get-token-uri`). This URI could resolve to a JSON file with information about the creator, associated media files, descriptions, signatures, and more. -- Ability to verify the owner for a given token identifier (`get-owner`). The owner resolves to a [Stacks principal](principals). -- Ability to transfer an NFT to a recipient (`transfer`). The recipient is required to be a Stacks principal. - -## Further reading - -- [The Difference Between Fungible and Non-Fungible Tokens](https://101blockchains.com/fungible-vs-non-fungible-tokens/) -- [Explain It Like I Am 5: NFTs](https://messari.io/article/explain-it-like-i-am-5-nfts) - -[fungible]: #fungible-tokens -[non-fungible]: #non-fungible-tokens-nfts -[SIP-010]: https://github.com/hstove/sips/blob/feat/sip-10-ft/sips/sip-010/sip-010-fungible-token-standard.md -[SIP-009]: https://github.com/stacksgov/sips/blob/main/sips/sip-009/sip-009-nft-standard.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md b/i18n/ja/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md deleted file mode 100644 index fc4765aa0c..0000000000 --- a/i18n/ja/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md +++ /dev/null @@ -1,301 +0,0 @@ ---- -title: Clarity Values -description: Learn how to deal with Clarity Values in JavaScript -sidebar_position: 2 ---- - -## Introduction - -The Clarity language makes use of a strong static 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/hirosystems/stacks.js/tree/master/packages/transactions) library makes this easy, as we will demonstrate below. - -## Clarity Types - -Please see the following page for information on [Clarity Types](../write-smart-contracts/clarity-language/language-types). - -## Constructing Clarity Values and accessing their data - -Clarity values can be constructed with functions provided by the [@stacks/transactions](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library. These functions simply output javascript objects that contain a value and a numerical representation of the Clarity type information. The Clarity types are encoded as follows: - -```typescript -export enum ClarityType { - Int = 0, - UInt = 1, - Buffer = 2, - BoolTrue = 3, - BoolFalse = 4, - PrincipalStandard = 5, - PrincipalContract = 6, - ResponseOk = 7, - ResponseErr = 8, - OptionalNone = 9, - OptionalSome = 10, - List = 11, - Tuple = 12, - StringASCII = 13, - StringUTF8 = 14, -} -``` - -`ClarityValue` objects can be serialized and included in transactions that interact with published Clarity contracts. - -Here are examples of how to construct each type of Clarity value, and how to access its data if it has any: - -### Booleans - -```typescript -const t = trueCV(); -// { type: ClarityType.BoolTrue } - -const f = falseCV(); -// { type: ClarityType.BoolFalse } -``` - -Boolean Clarity Values don't contain any underlying data. They are simply objects with `type` information. - -### Optional Values - -```typescript -const nothing: NoneCV = noneCV(); -// { type: ClarityType.OptionalNone } - -const something: SomeCV = someCV(trueCV()); -// { type: ClarityType.OptionalSome, value: { type: 4 } } -``` - -Optional Clarity Values can either be nothing (an empty type that has no data), or something (a wrapped value). - -If you are dealing with a function or contract function that returns an `OptionalCV`, you should always check what type it is before trying to access its value. - -```typescript -const maybeVal: OptionalCV = await callReadOnlyFunction(...); - -if (maybeVal.type === ClarityType.OptionalSome) { - console.log(maybeVal.value); -} else if (maybeVal.type === ClarityType.OptionalNone) { - // deal with `none` value -} -``` - -### Buffers - -```typescript -const buffer = Buffer.from('foo'); -const bufCV: BufferCV = bufferCV(buffer); -// { type: ClarityType.Buffer, buffer: } -``` - -### Integers - -Clarity supports both integers and unsigned integers. - -```typescript -const i: IntCV = intCV(-10); -// { type: ClarityType.Int, value: BN { ... } } - -const u: UIntCV = uintCV(10); -// { type: ClarityType.UInt, value: BN { ... } } -``` - -Clarity value ints store their underlying data as `BigNum` values from the [bn.js](https://github.com/indutny/bn.js/) library. - -In order to display/print Clarity (u)int values, use the `cvToString(val)` method. - -If you wish to perform arithmetic operations using Clarity (u)int values, you must use methods from the `BigNum` api on their underlying `BigNum` values, and the construct a new Clarity value out of the result. For example: - -```typescript -const x = intCV(1); -const y = intCV(2); - -x.value.add(y.value); -// 3 -``` - -### Strings - -```typescript -const ascii: StringAsciiCV = stringAsciiCV('hello world'); -// { type: ClarityType.StringASCII, data: 'hello world' } - -const utf8: StringUtf8CV = stringUtf8CV('hello 🌾'); -// { type: ClarityType.StringUTF8, data: 'hello 🌾' } -``` - -Clarity supports both ascii and utf8 strings. - -### Principals - -```typescript -const address = 'SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B'; -const contractName = 'contract-name'; - -const spCV = standardPrincipalCV(address); -// { -// type: ClarityType.PrincipalStandard -// address: { -// type: StacksMessageType.Address, -// version: AddressVersion.MainnetSingleSig, -// hash160: "SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B" -// } -// } - -const cpCV = contractPrincipalCV(address, contractName); -// { -// type: ClarityType.PrincipalContract, -// contractName: { -// type: StacksMessageType.LengthPrefixedString, -// content: 'contract-name', -// lengthPrefixBytes: 1, -// maxLengthBytes: 128, -// }, -// address: { -// type: StacksMessageType.Address, -// version: AddressVersion.MainnetSingleSig, -// hash160: "SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B" -// } -// } -``` - -Both kinds of Clarity principal values contain `type` information and an `address` object. Contract principals also contain a `contractName`. - -### Response Values - -```typescript -const errCV = responseErrorCV(trueCV()); -// { type: ResponseErr, value: { type: ClarityType.BoolTrue } } - -const okCV = responseOkCV(falseCV()); -// { type: ResponseOk, value: { type: ClarityType.BoolFalse } } -``` - -Response Clarity Values will either have the type `ClarityType.ResponseOk` or `ClarityType.ResponseErr`. They both contain a Clarity Value. Often this value will be an integer error code if the response is an `Error`. - -### Tuples - -```typescript -const tupCV = tupleCV({ - a: intCV(1), - b: trueCV(), - c: falseCV(), -}); -// { -// type: ClarityType.Tuple, -// data: { -// a: { type: ClarityType.Int, value: BN { ... } }, -// b: { type: ClarityType.BoolTrue }, -// c: { type: ClarityType.BoolFalse }, -// } -// } - -console.log(tupCV.data['b']); -// { type: ClarityType.BoolTrue } -``` - -Tuples in Clarity are typed and contain named fields. The tuple above, for example, contains three fields with the names **a**, **b** and **c**, and the types of their values are `Int`, `Boolean` and `Boolean`, respectively. - -Clarity tuples are represented in JavaScript as objects and a tuple's data can be accessed by its `data` field, where the underlying JS object is stored. - -### Lists - -```typescript -const l = listCV([trueCV(), falseCV()]); -// { type: ClarityType.List, list: [{ type: ClarityType.BoolTrue }] } - -console.log(l.list[0]); -// { type: ClarityType.BoolTrue } -``` - -Lists, in Clarity, are homogeneous, meaning they can only contain elements of a singular (Clarity) type. Make sure to avoid constructing lists that have elements of multiple types. - -A Clarity lists underlying data can be accessed via its `list` field. - -## Using Clarity Values - -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](../understand-stacks/transactions#construction). - -## Utilizing Clarity Values from Transaction Responses - -`Read-only` Clarity functions can return Clarity values as a response. These `read-only` functions can be accessed easily in JavaScript via the [`callReadOnlyFunction()`](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions#calling-read-only-contract-function) function included in `@stacks/transactions`, which returns a `ClarityValue`. - -As mentioned above, `ClarityValues` are simply javascript objects containing a value and its associated Clarity type information. These object types are defined [here](https://github.com/hirosystems/stacks.js/tree/1f2b5fd8bdf1c2b5866e8171163594d7708a8c7a/packages/transactions/src/clarity/types). - -When you are calling a `read-only` contract function, you will always know what type the function will return, since functions in Clarity are strongly typed. - -It is common for Clarity functions to return values wrapped in a `Response`, in order to indicate if there was success or an error. - -Since every `ClarityValue` has a `type` field, the type of the result of a `read-only` function call can be checked and acted upon like so: - -```typescript -const contractAddress = 'ST3KC0MTNW34S1ZXD36JYKFD3JJMWA01M55DSJ4JE'; -const contractName = 'kv-store'; -const functionName = 'get-value'; -const buffer = bufferCVFromString('foo'); -const network = new StacksTestnet(); // for mainnet, use `StacksMainnet()` -const senderAddress = 'ST2F4BK4GZH6YFBNHYDDGN4T1RKBA7DA1BJZPJEJJ'; - -const options = { - contractAddress, - contractName, - functionName, - functionArgs: [buffer], - network, - senderAddress, -}; - -// make a read-only call to a contract function that -// returns a Response -const result: ResponseCV = await callReadOnlyFunction(options); - -if (result.type === ClarityType.ResponseOk) { - console.log(cvToString(result.value)); -} else if (result.type === ClarityType.ResponseErr) { - throw new Error(`kv-store contract error: ${result.value.data}`); -} -``` - -### ClarityValues to/from Hex - -If you receive a response from a transaction in the form of a `hex` string, you can deserialize it into a Clarity value like so: - -```javascript -import { hexToCV } from '@stacks/transactions'; - -let cv = hexToCV('hex_string'); -``` - -Similarly, you can convert a Clarity value to `hex` string like so: - -```javascript -import { cvToHex, trueCV } from '@stacks/transactions'; - -let trueHex = cvToHex(trueCV()); -``` - -## Debugging Clarity Values - -Sometimes you might receive a Clarity value that you were not expecting. Logging the value to your console won't always prove to be useful, unless you have memorized the Clarity value type enum values. - -In order to figure out what kind of value you are dealing with, you can use the `cvToString()` function to convert the Clarity value to a more easily readable string. - -For example, calling `cvToString()` on a large `tuple` might yield something like: - -``` -(tuple - (a -1) - (b u1) - (c 0x74657374) - (d true) - (e (some true)) - (f none) - (g SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B) - (h SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B.test) - (i (ok true)) - (j (err false)) - (k (list true false)) - (l (tuple (a true) (b false))) - (m "hello world") - (n u"hello \u{1234}"))` -``` diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/blockchain/index.md b/i18n/ko/docusaurus-plugin-content-docs/current/blockchain/index.md deleted file mode 100644 index 13db24ec30..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/blockchain/index.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: Blockchain -description: Stacks Blockchain -sidebar_position: 6 ---- - -Below is a guide to start working locally with the Stacks Blockchain. - -Code repository is [here](https://github.com/stacks-network/stacks-blockchain). - -## Getting started with the Stacks Blockchain - -### Download and build stacks-blockchain - -The first step is to ensure that you have Rust and the support software installed. - -```bash -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -``` - -:::info -For building on Windows, follow the rustup installer instructions at https://rustup.rs/ -::: - -From there, you can clone the Stacks Blockchain repository: - -```bash -git clone --depth=1 https://github.com/stacks-network/stacks-blockchain.git - -cd stacks-blockchain -``` - -Then build the project: - -```bash -cargo build -``` - -Run the tests: - -```bash -cargo test testnet -- --test-threads=1 -``` - -### Encode and sign transactions - -Here, we have generated a keypair that will be used for signing the upcoming transactions: - -```bash -cargo run --bin blockstack-cli generate-sk --testnet - -# Output -# { -# secretKey: "b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001", -# publicKey: "02781d2d3a545afdb7f6013a8241b9e400475397516a0d0f76863c6742210539b5", -# stacksAddress: "ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH" -# } -``` - -This keypair is already registered in the `testnet-follower-conf.toml` file, so it can be used as presented here. - -We will interact with the following simple contract `kv-store`. In our examples, we will assume this contract is saved to `./kv-store.clar`: - -```scheme -(define-map store { key: (string-ascii 32) } { value: (string-ascii 32) }) - -(define-public (get-value (key (string-ascii 32))) - (match (map-get? store { key: key }) - entry (ok (get value entry)) - (err 0))) - -(define-public (set-value (key (string-ascii 32)) (value (string-ascii 32))) - (begin - (map-set store { key: key } { value: value }) - (ok true))) -``` - -We want to publish this contract on chain, then issue some transactions that interact with it by setting some keys and getting some values, so we can observe read and writes. - -Our first step is to generate and sign, using your private key, the transaction that will publish the contract `kv-store`. To do that, we will use the subcommand `blockstack-cli` that has the following usage: - -```bash -blockstack-cli (options) publish [publisher-secret-key-hex] [fee-rate] [nonce] [contract-name] [file-name.clar] -``` - -With the following arguments: - -```bash -cargo run --bin blockstack-cli publish b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 515 0 kv-store ./kv-store.clar --testnet -``` - -The `515` is the transaction fee, denominated in microSTX. Right now, the testnet requires one microSTX per byte minimum, and this transaction should be less than 515 bytes. The third argument `0` is a nonce, that must be increased monotonically with each new transaction. - -This command will output the **binary format** of the transaction. In our case, we want to pipe this output and dump it to a file that will be used later in this tutorial. - -```bash -cargo run --bin blockstack-cli publish b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 515 0 kv-store ./kv-store.clar --testnet | xxd -r -p > tx1.bin -``` - -### Run the testnet - -You can observe the state machine in action locally by running: - -```bash -cargo stacks-node start --config=./testnet/stacks-node/conf/testnet-follower-conf.toml -``` - -`testnet-follower-conf.toml` is a configuration file that you can use for setting genesis balances or configuring Event observers. You can grant an address an initial account balance by adding the following entries: - -``` -[[ustx_balance]] -address = "ST2VHM28V9E5QCRD6C73215KAPSBKQGPWTEE5CMQT" -amount = 100000000 -``` - -The `address` field is the Stacks testnet address, and the `amount` field is the number of microSTX to grant to it in the genesis block. The addresses of the private keys used in the tutorial below are already added. - -### Publish your contract - -Assuming that the testnet is running, we can publish our `kv-store` contract. - -In another terminal (or file explorer), you can move the `tx1.bin` generated earlier, to the mempool: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx1.bin http://localhost:20443/v2/transactions -``` - -In the terminal window running the testnet, you can observe the state machine's reactions. - -### Reading from / Writing to the contract - -Now that our contract has been published on chain, let's try to submit some read / write transactions. We will start by trying to read the value associated with the key `foo`. - -To do that, we will use the subcommand: - -```bash -cargo run --bin blockstack-cli contract-call --help -``` - -With the following arguments: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 1 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store get-value -e \"foo\" --testnet | xxd -r -p > tx2.bin -``` - -`contract-call` generates and signs a contract-call transaction. - -We can submit the transaction by moving it to the mempool path: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx2.bin http://localhost:20443/v2/transactions -``` - -Similarly, we can generate a transaction that would be setting the key `foo` to the value `bar`: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 2 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store set-value -e \"foo\" -e \"bar\" --testnet | xxd -r -p > tx3.bin -``` - -And submit it by moving it to the mempool path: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx3.bin http://localhost:20443/v2/transactions -``` - -Finally, we can issue a third transaction, reading the key `foo` again, for ensuring that the previous transaction has successfully updated the state machine: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 3 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store get-value -e \"foo\" --testnet | xxd -r -p > tx4.bin -``` - -And submit this last transaction by moving it to the mempool path: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx4.bin http://localhost:20443/v2/transactions -``` - -Congratulations, you can now [write your own smart contracts with Clarity](write-smart-contracts/). diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/blockchain/networks.md b/i18n/ko/docusaurus-plugin-content-docs/current/blockchain/networks.md deleted file mode 100644 index fe9725352c..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/blockchain/networks.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Stacks Blockchain Networks -description: Stacks Blockchain Networks -sidebar_position: 3 ---- - -### Stacks Blockchain Networks - -- [x] **Krypton** is a Stacks 2 testnet with a fixed, two-minute block time, called `regtest`. Regtest is generally unstable for regular use, and is reset often. See the [regtest documentation](understand-stacks/testnet) for more information on using regtest. - -- [x] **Testnet** (old Xenon) is the Stacks 2 public testnet, which runs PoX against the Bitcoin testnet. It is the full implementation of the Stacks 2 blockchain, and should be considered a stable testnet for developing Clarity smart contracts. See the [testnet documentation](understand-stacks/testnet) for more information on the public testnet. - -- [x] **Mainnet** is the fully functional Stacks 2 blockchain, see the [Stacks overview](understand-stacks/) for information on running a Stacks node, mining, stacking, and writing Clarity smart contracts. diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md b/i18n/ko/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md deleted file mode 100644 index cf4f84a2da..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Stacks Blockchain API -description: Interacting with the Stacks 2.0 Blockchain via API -sidebar_position: 4 ---- - -## Introduction - -:::tip API Documentation Official API Documentation is available [here](https://stacks-network.github.io/stacks-blockchain/). ::: - - -The Stacks 2.0 Blockchain API allows you to query the Stacks 2.0 blockchain and interact with smart contracts. It was built to maintain pageable materialized views of the Stacks 2.0 Blockchain. - -:::caution The RESTful API is developed by Hiro. Hiro also hosts a public API node for easy onboarding. Using it requires you to trust the hosted server, but provides a faster onboarding experience. You can [run your own API server](https://docs.hiro.so/get-started/running-api-node) ::: - -The RESTful JSON API can be used without any authorization. The basepath for the API is: - -```bash -# for mainnet, replace `testnet` with `mainnet` -https://stacks-node-api.testnet.stacks.co/ -``` - -:::note This documentation only covers endpoints that are exposed on a Stacks node, referred to as the RPC API. For full documentation on the RESTful API, check out the [Hiro's API reference](https://docs.hiro.so/api). ::: - -### Stacks Node RPC API - -The [stacks-node implementation](https://github.com/stacks-network/stacks-blockchain/) exposes JSON RPC endpoints. - -All `/v2/` routes a proxied to a Hiro-hosted Stacks Node. For a trustless architecture, you should make these requests to a self-hosted node. - -## Proxied Stacks Node RPC API endpoints - -The Stacks 2.0 Blockchain API is centrally hosted. However, every running Stacks node exposes an RPC API, which allows you to interact with the underlying blockchain. Instead of using a centrally hosted API, you can directly access the RPC API of a locally hosted Node. - -:::tip -The Stacks Blockchain API proxies to Node RPC endpoints -::: - -While the Node RPC API doesn't give the same functionality as the hosted Stacks 2.0 Blockchain API, you get similar functionality in a way that is scoped to that specific node. The RPC API includes the following endpoints: - -- [POST /v2/transactions](https://docs.hiro.so/api#operation/post_core_node_transactions) -- [GET /v2/contracts/interface/{contract_address}/{contract_name}](https://docs.hiro.so/api#operation/get_contract_interface) -- [POST /v2/map_entry/{contract_address}/{contract_name}/{map_name}](https://docs.hiro.so/api#operation/get_contract_data_map_entry) -- [GET /v2/contracts/source/{contract_address}/{contract_name}](https://docs.hiro.so/api#operation/get_contract_source) -- [GET /v2/accounts/{principal}](https://docs.hiro.so/api#operation/get_account_info) -- [POST /v2/contracts/call-read/{contract_address}/{contract_name}/{function_name}](https://docs.hiro.so/api#operation/call_read_only_function) -- [GET /v2/fees/transfer](https://docs.hiro.so/api#operation/get_fee_transfer) -- [GET /v2/info](https://docs.hiro.so/api#operation/get_core_api_info) - -:::caution If you run a local node, it exposes an HTTP server on port `20443`. The info endpoint would be `localhost:20443/v2/info`. ::: diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md b/i18n/ko/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md deleted file mode 100644 index 71e3542302..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Stacks Releases -description: Stacks Blockchain Releases -sidebar_position: 2 ---- - -:::info -This page needs contributions. Help us improve it. -::: - -### Stacks Blockchain Releases - -All releases are published [here](https://github.com/stacks-network/stacks-blockchain/releases). Most important ones are described below. - -### Stacks 2.1 - -Scheduled for release at the end of 2022. - -More information on [what to expect with Stacks 2.1](https://stacks.org/stacks-21-what-to-expect). - -#### Stacks 2.05 -Activated on [Bitcoin block 713000](https://explorer.stacks.co/txid/0xece8e369310b5ff9b92ef11181ae0d2457ac0c821376d4a96c4998763e22ad04?chain=mainnet). - -This breaking change enables storage cost for list to be based on actual length and change in number of indexed I/O operations. More info on this [blog post](https://www.stacks.org/stacks-2-05?ref=docs-website). - -#### Stacks 2.0 -Activated on January 14th 2021 - -This hard fork enables Stacking, Clarity smart contracts, scalable transactions, and also building directly on Bitcoin. More info [here](https://forum.stacks.org/t/path-to-mainnet-for-stx-holders-things-to-know-ahead-of-stacks-2-0/11529). - -#### Stacks Genesis -Released on 2018, October 30th UTC+6 at Bitcoin block height 547921 - -This hard fork addresses registration of digital assets with Stacks token and also distribution of Stacks token to the existing purchasers. More info [here](https://blog.blockstack.org/the-launch-of-the-stacks-genesis-block/?ref=docs-website). - diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md b/i18n/ko/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md deleted file mode 100644 index 25ec969824..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Deploy tips -description: Learn some common methods for deploying your application. ---- - -## Introduction - -Stacks applications are web applications that authenticate users with Stacks Auth and store data with Gaia. Both of these technologies can be accessed on the client side. As such, Stacks apps tend to be simple in design and operation, since in many cases, they don’t have to host anything besides the application’s assets. - -## Where to deploy your application - -Before users can interact with your application, you must deploy it on a server that is accessible over the internet. Deploying requires that you: - -- Configure or customize the files in the `public` directory. -- Build your application site for deployment. -- Copy your generated application files to your production server. - -If you first populated your application with the Stacks application generator, your application contains the starting blocks for configuring, building, and deploying your app. For example, the React template builds out a scaffolding with the following building blocks. - -| File or Directory | Description | -| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| node_modules/react-scripts | A set of scripts for that helps you kick off React projects without configuring, so you do not have to set up your project by yourself. | -| package.json | Contains a scripts section that includes a reference to the react-scripts, which are a dependency. This script creates a build directory containing your files for deployment. | -| public/favicon.ico | An example shortcut icon. | -| public/index.html | An entry page for an application. | -| public/manifest.json | A JSON file that describes your web application to the browser. | -| cors | Contains example deployment files for cross-origin request configuration. | - -If you use the generator to build JavasScript or Vue scaffolding, your project configuration files will be different. - -Regardless of which scaffolding you use, you must customize and extend this basic scaffolding as needed by your application. For example, you may want to add more properties to the `manifest.json` file. Since every application is different, Stacks Auth cannot give you specific instructions on how to do this. The steps you take are specific to your application. - -## Stacks Authentication and deployment - -When your application authenticates users with Stacks, the Stacks Wallet at on URL requests a resource (the app manifest) from your DApp. A request for a resource outside of the origin (the Stacks Wallet) 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 (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) - -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 Stacks 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`: - -```html -Access-Control-Allow-Origin: * Access-Control-Allow-Headers: "X-Requested-With, Content-Type, -Origin, Authorization, Accept, Client-Security-Token, Accept-Encoding" Access-Control-Allow-Methods: -"POST, GET, OPTIONS, DELETE, PUT" -``` - -Consult the documentation for your hosting service to learn how to configure CORS on that service. - -## Deployment and Radiks - -If you are deploying a Stacks application that uses [Radiks](https://github.com/stacks-network/radiks), your deployment includes a server and a database component. You must take this into account when deploying your application. You may want to choose a service such as [Heroku](https://www.heroku.com) or [Digital Ocean](https://www.digitalocean.com) if your app uses Radiks. diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/build-apps/index.md b/i18n/ko/docusaurus-plugin-content-docs/current/build-apps/index.md deleted file mode 100644 index 23714cba5d..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/build-apps/index.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Build apps with Stacks -description: Authenticate users, sign transactions and store data with the Stacks blockchain -sidebar_position: 3 -sidebar_label: Build apps ---- - -## Introduction - -Apps built with the Stacks blockchain give users control over their digital identities, assets, and data. - -Unlike most cloud-based apps, they are "decentralized" since they don't depend on any centralized platform, server, or database to function. Rather, they use the Stacks blockchain to authenticate users and facilitate read and write requests for them without any single point of failure or trust. - -Stacks provides three main functions for building apps: - - - -- **Authentication**: Register and sign users in with identities on the Stacks blockchain -- **Transaction signing**: Prompt users to sign and broadcast transactions to the Stacks blockchain -- **Data storage**: Save and retrieve data for users with [Gaia](../gaia) - - -All three of these integrations can be used together to create powerful new user experiences that rival or exceed those of traditional apps—all while protecting your users' digital rights. - -While integration is possible for any type of app, most of the resources available here are for web developers experienced with JavaScript. See [Hiro developer docs](https://docs.hiro.so) for more information on the available app development libraries for Stacks. - -## [References](references) - -[Authentication](references/authentication) - -[BNS](references/bns) - -[Gaia](../gaia/) - diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md b/i18n/ko/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md deleted file mode 100644 index 727b4e2163..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: NoCodeClarity -description: Launch apps for the Stacks blockchain through no code platforms like Bubble. ---- - -## Introduction - -![](https://d1muf25xaso8hp.cloudfront.net/https%3A%2F%2Fs3.amazonaws.com%2Fappforest_uf%2Ff1653407713550x759333524803365600%2FLogo%2520of%2520NoCodeClarity.png?w=179&h=84&auto=compress&dpr=1&fit=max) - -[NoCodeClarity](https://nocodeclarity.com) allows people to create applications for the Stacks blockchain without coding. - -## Stacks Plug-In on bubble - -The [Stacks-No-Code-Plugin](https://bubble.io/plugin/the-stacks-plug-in-1645467277638x949839693014368300) released in May 2022 and it can easily be installed on Bubble with a few clicks allowing users to deploy applications with no coding knowledge. [Bubble](https://bubble.io/blog/explaining-bubble-to-investors/) is the first No Code platform that the Stacks plugin launched on. More platforms are in the roadmap of NoCodeClarity, founded by Christopher Perceptions and Sergio Gongora. The Stacks plugin was created through the support of the Stacks Foundation via a grant in January 2022 and NoCodeClarity was awarded a $100,000 grant in June 2022 to expand the roadmap. - -Additional [instructions](https://s3.amazonaws.com/appforest_uf/f1654202471526x991633667675927800/Instructions%20v2.docx.pdf) are also available. Tutorials and step by step guides will be released soon. - -The Stacks-No-Code-Plugin code is [publicly available on Github](https://github.com/nocodeclarity/Stacks-No-Code-Plugin). - -![](/img/bubble-stacks-plugin.png) - -## Demo page - -A demo page is available [here](https://test-stacks-plugin.bubbleapps.io/version-test). - -## NoCodeClarity videos - -NodeCodeClarity has their own [youtube channel](https://www.youtube.com/channel/UC9Ep0VQ-GQ-yDzt-wmIElRA). - -Videos: - -* [NoCodeClarity Setup](https://www.youtube.com/watch?v=WanXlpBGl0w) -* [NoCodeClarity - Part 1 of the plugin](https://www.youtube.com/watch?v=o6d3hrzNqVI&t=248s) -* [NoCodeClarity - Part 2 of the plugin](https://www.youtube.com/watch?v=0rzMdsrRg80) -* [Sneak Peek of the No Code Stacks Wallet Template](https://www.youtube.com/watch?v=Xe6Yv0rF6XM) \ No newline at end of file diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md b/i18n/ko/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md deleted file mode 100644 index 86a8568663..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Authentication -description: Register and sign in users with identities on the Stacks blockchain ---- - -## Introduction - -This guide explains how authentication is performed on the Stacks blockchain. - -Authentication provides a way for users to identify themselves to an app while retaining complete control over their credentials and personal details. It can be integrated alone or used in conjunction with [transaction signing](https://docs.hiro.so/get-started/transactions#signature-and-verification) and [data storage](https://docs.stacks.co/build-apps/references/gaia), for which it is a prerequisite. - -Users who register for your app can subsequently authenticate to any other app with support for the [Blockchain Naming System](bns) and vice versa. - -## How it works - -The authentication flow with Stacks is similar to the typical client-server flow used by centralized sign in services (for example, OAuth). However, with Stacks the authentication flow happens entirely client-side. - -An app and authenticator, such as [the Stacks Wallet](https://www.hiro.so/wallet/install-web), communicate during the authentication flow by passing back and forth two tokens. The requesting app sends the authenticator an `authRequest` token. Once a user approves authentication, the authenticator responds to the app with an `authResponse` token. - -These tokens are are based on [a JSON Web Token (JWT) standard](https://tools.ietf.org/html/rfc7519) with additional support for the `secp256k1` curve used by Bitcoin and many other cryptocurrencies. They are passed via URL query strings. - -When a user chooses to authenticate an app, it sends the `authRequest` token to the authenticator via a URL query string with an equally named parameter: - -`https://wallet.hiro.so/...?authRequest=j902120cn829n1jnvoa...` - -When the authenticator receives the request, it generates an `authResponse` token for the app using an _ephemeral transit key_ . The ephemeral transit key is just used for the particular instance of the app, in this case, to sign the `authRequest`. - -The app stores the ephemeral transit key during request generation. The public portion of the transit key is passed in the `authRequest` token. The authenticator uses the public portion of the key to encrypt an _app private key_ which is returned via the `authResponse`. - -The authenticator generates the app private key from the user's _identity address private key_ and the app's domain. The app private key serves three functions: - -1. It is used to create credentials that give the app access to a storage bucket in the user's Gaia hub -2. It is used in the end-to-end encryption of files stored for the app in the user's Gaia storage. -3. It serves as a cryptographic secret that apps can use to perform other cryptographic functions. - -Finally, the app private key is deterministic, meaning that the same private key will always be generated for a given Stacks address and domain. - -The first two of these functions are particularly relevant to [data storage with Stacks.js](https://docs.stacks.co/docs/gaia). - -## Key pairs - -Authentication with Stacks makes extensive use of public key cryptography generally and ECDSA with the `secp256k1` curve in particular. - -The following sections describe the three public-private key pairs used, including how they're generated, where they're used and to whom private keys are disclosed. - -### Transit private key - -The transit private is an ephemeral key that is used to encrypt secrets that need to be passed from the authenticator to the app during the authentication process. It is randomly generated by the app at the beginning of the authentication response. - -The public key that corresponds to the transit private key is stored in a single element array in the `public_keys` key of the authentication request token. The authenticator encrypts secret data such as the app private key using this public key and sends it back to the app when the user signs in to the app. The transit private key signs the app authentication request. - -### Identity address private key - -The identity address private key is derived from the user's keychain phrase and is the private key of the Stacks username that the user chooses to use to sign in to the app. It is a secret owned by the user and never leaves the user's instance of the authenticator. - -This private key signs the authentication response token for an app to indicate that the user approves sign in to that app. - -### App private key - -The app private key is an app-specific private key that is generated from the user's identity address private key using the `domain_name` as input. - -The app private key is securely shared with the app on each authentication, encrypted by the authenticator with the transit public key. Because the transit key is only stored on the client side, this prevents a man-in-the-middle attack where a server or internet provider could potentially snoop on the app private key. diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/build-apps/references/bns.md b/i18n/ko/docusaurus-plugin-content-docs/current/build-apps/references/bns.md deleted file mode 100644 index 32b045dc83..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/build-apps/references/bns.md +++ /dev/null @@ -1,241 +0,0 @@ ---- -title: Blockchain Naming System -description: Binds Stacks usernames to off-chain state ---- - -Blockchain Naming System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of control. - -The Stacks V1 blockchain implemented BNS through first-order name operations. In Stacks V2, BNS is instead implemented through a smart-contract loaded during the genesis block. - -Names in BNS have three properties: - -- **Names are globally unique.** The protocol does not allow name collisions, and all well-behaved nodes resolve a given name to the same state. -- **Names are human-meaningful.** Each name is chosen by its creator. -- **Names are strongly owned.** Only the name's owner can change the state it resolves to. Specifically, a name is owned by one or more ECDSA private keys. - -The Stacks blockchain insures that each node's BNS view is synchronized to all of the other nodes in the world, so queries on one node will be the same on other nodes. Stacks blockchain nodes allow a name's owner to bind up to 40Kb of off-chain state to their name, which will be replicated to all other Stacks blockchain nodes via a P2P network. - -The biggest consequence for developers is that in BNS, reading name state is fast and cheap but writing name state is slow and expensive. This is because registering and modifying names requires one or more transactions to be sent to the underlying blockchain, and BNS nodes will not process them until they are sufficiently confirmed. Users and developers need to acquire and spend the requisite cryptocurrency (STX) to send BNS transactions. - -## Motivation behind naming systems - -We rely on naming systems in everyday life, and they play a critical role in many different applications. For example, when you look up a friend on social media, you are using the platform's naming system to resolve their name to their profile. When you look up a website, you are using the Domain Name Service to resolve the hostname to its host's IP address. When you check out a Git branch, you are using your Git client to resolve the branch name to a commit hash. When you look up someone's PGP key on a keyserver, you are resolving their key ID to their public key. - -What kinds of things do we want to be true about names? In BNS, names are globally unique, names are human-meaningful, and names are strongly owned. However, if you look at these examples, you'll see that each of them only guarantees _two_ of these properties. This limits how useful they can be. - -- In DNS and social media, names are globally unique and human-readable, but not strongly owned. The system operator has the final say as to what each names resolves to. - - - **Problem**: Clients must trust the system to make the right choice in what a given name resolves to. This includes trusting that no one but the system administrators can make these changes. - -- In Git, branch names are human-meaningful and strongly owned, but not globally unique. Two different Git nodes may resolve the same branch name to different unrelated repository states. - - - **Problem**: Since names can refer to conflicting state, developers have to figure out some other mechanism to resolve ambiguities. In Git's case, the user has to manually intervene. - -- In PGP, names are key IDs. They are are globally unique and cryptographically owned, but not human-readable. PGP key IDs are derived from the keys they reference. - - **Problem**: These names are difficult for most users to remember since they do not carry semantic information relating to their use in the system. - -BNS names have all three properties, and none of these problems. This makes it a powerful tool for building all kinds of network applications. With BNS, we can do the following and more: - -- Build domain name services where hostnames can't be hijacked. -- Build social media platforms where user names can't be stolen by phishers. -- Build version control systems where repository branches do not conflict. -- Build public-key infrastructure where it's easy for users to discover and remember each other's keys. - -## Organization of BNS - -BNS names are organized into a global name hierarchy. There are three different layers in this hierarchy related to naming: - -- **Namespaces**. These are the top-level names in the hierarchy. An analogy to BNS namespaces are DNS top-level domains. Existing BNS namespaces include `.id`, `.podcast`, and `.helloworld`. All other names belong to exactly one namespace. Anyone can create a namespace, but in order for the namespace to be persisted, it must be _launched_ so that anyone can register names in it. Namespaces are not owned by their creators. - -- **BNS names**. These are names whose records are stored directly on the blockchain. The ownership and state of these names are controlled by sending blockchain transactions. Example names include `verified.podcast` and `muneeb.id`. Anyone can create a BNS name, as long as the namespace that contains it exists already. - -- **BNS subdomains**. These are names whose records are stored off-chain, but are collectively anchored to the blockchain. The ownership and state for these names lives within the P2P network data. While BNS subdomains are owned by separate private keys, a BNS name owner must broadcast their subdomain state. Example subdomains include `jude.personal.id` and `podsaveamerica.verified.podcast`. Unlike BNS namespaces and names, the state of BNS subdomains is _not_ part of the blockchain consensus rules. - -A feature comparison matrix summarizing the similarities and differences between these name objects is presented below: - -| Feature | **Namespaces** | **BNS names** | **BNS Subdomains** | -| -------------------------------------- | -------------- | ------------- | ------------------ | -| Globally unique | X | X | X | -| Human-meaningful | X | X | X | -| Owned by a private key | | X | X | -| Anyone can create | X | X | [1] | -| Owner can update | | X | [1] | -| State hosted on-chain | X | X | | -| State hosted off-chain | | X | X | -| Behavior controlled by consensus rules | X | X | | -| May have an expiration date | | X | | - -[1] Requires the cooperation of a BNS name owner to broadcast its transactions - -## Namespaces - -Namespaces are the top-level naming objects in BNS. - -They control a few properties about the names within them: - -- How expensive they are to register -- How long they last before they have to be renewed -- Who (if anyone) receives the name registration fees -- Who is allowed to seed the namespace with its initial names. - -At the time of this writing, by far the largest BNS namespace is the `.id` namespace. Names in the `.id` namespace are meant for resolving user identities. Short names in `.id` are more expensive than long names, and have to be renewed by their owners every two years. Name registration fees are not paid to anyone in particular---they are instead sent to a "black hole" where they are rendered unspendable (the intention is to discourage ID squatters). - -Unlike DNS, _anyone_ can create a namespace and set its properties. Namespaces are created on a first-come first-serve basis, and once created, they last 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 (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`). - -Namespaces can be between 1 and 19 characters long, and are composed of the characters `a-z`, `0-9`, `-`, and `_`. - -## Subdomains - -BNS names are strongly owned because the owner of its private key can generate valid transactions that update its zone file hash and owner. However, this comes at the cost of requiring a name owner to pay for the underlying transaction in the blockchain. Moreover, this approach limits the rate of BNS name registrations and operations to the underlying blockchain's transaction bandwidth. - -BNS overcomes this with subdomains. A **BNS subdomain** is a type of BNS name whose state and owner are stored outside of the blockchain, but whose existence and operation history are anchored to the blockchain. Like their on-chain counterparts, subdomains are globally unique, strongly owned, and human-readable. BNS gives them their own name state and public keys. Unlike on-chain names, subdomains can be created and managed cheaply, because they are broadcast to the BNS network in batches. A single blockchain transaction can send up to 120 subdomain operations. - -This is achieved by storing subdomain records in the BNS name zone files. An on-chain name owner broadcasts subdomain operations by encoding them as `TXT` records within a DNS zone file. To broadcast the zone file, the name owner sets the new zone file hash with a `NAME_UPDATE` transaction and replicates the zone file. This, in turn, replicates all subdomain operations it contains, and anchors the set of subdomain operations to an on-chain transaction. The BNS node's consensus rules ensure that only valid subdomain operations from _valid_ `NAME_UPDATE` transactions will ever be stored. - -For example, the name `verified.podcast` once wrote the zone file hash `247121450ca0e9af45e85a82e61cd525cd7ba023`, which is the hash of the following zone file: - -```bash -$TTL 3600 -1yeardaily TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxeWVhcmRhaWx5CiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMXllYXJkYWlseS9oZWFkLmpzb24iCg==" -2dopequeens TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAyZG9wZXF1ZWVucwokVFRMIDM2MDAKX2h0dHAuX3RjcCBVUkkgMTAgMSAiaHR0cHM6Ly9waC5kb3Rwb2RjYXN0LmNvLzJkb3BlcXVlZW5zL2hlYWQuanNvbiIK" -10happier TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxMGhhcHBpZXIKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8xMGhhcHBpZXIvaGVhZC5qc29uIgo=" -31thoughts TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzMXRob3VnaHRzCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzF0aG91Z2h0cy9oZWFkLmpzb24iCg==" -359 TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzNTkKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8zNTkvaGVhZC5qc29uIgo=" -30for30 TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzMGZvcjMwCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzBmb3IzMC9oZWFkLmpzb24iCg==" -onea TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiBvbmVhCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vb25lYS9oZWFkLmpzb24iCg==" -10minuteteacher TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxMG1pbnV0ZXRlYWNoZXIKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8xMG1pbnV0ZXRlYWNoZXIvaGVhZC5qc29uIgo=" -36questionsthepodcastmusical TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzNnF1ZXN0aW9uc3RoZXBvZGNhc3RtdXNpY2FsCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzZxdWVzdGlvbnN0aGVwb2RjYXN0bXVzaWNhbC9oZWFkLmpzb24iCg==" -_http._tcp URI 10 1 "https://dotpodcast.co/" -``` - -Each `TXT` record in this zone file encodes a subdomain-creation. For example, `1yeardaily.verified.podcast` resolves to: - -```json -{ - "address": "1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH", - "blockchain": "bitcoin", - "last_txid": "d87a22ebab3455b7399bfef8a41791935f94bc97aee55967edd5a87f22cce339", - "status": "registered_subdomain", - "zonefile_hash": "e7acc97fd42c48ed94fd4d41f674eddbee5557e3", - "zonefile_txt": "$ORIGIN 1yeardaily\n$TTL 3600\n_http._tcp URI 10 1 \"https://ph.dotpodcast.co/1yeardaily/head.json\"\n" -} -``` - -This information was extracted from the `1yeardaily` `TXT` resource record in the zone file for `verified.podcast`. - -### Subdomain Lifecycle - -Note that `1yeardaily.verified.podcast` has a different public key hash (address) than `verified.podcast`. A BNS node will only process a subsequent subdomain operation on `1yeardaily.verified.podcast` if it includes a signature from this address's private key. `verified.podcast` cannot generate updates; only the owner of `1yeardaily.verified.podcast can do so`. - -The lifecycle of a subdomain and its operations is shown in Figure 2. - -``` - subdomain subdomain subdomain - creation update transfer -+----------------+ +----------------+ +----------------+ -| cicero | | cicero | | cicero | -| owner="1Et..." | signed | owner="1Et..." | signed | owner="1cJ..." | -| zf0="7e4..." |<--------| zf0="111..." |<--------| zf0="111..." |<---- ... -| seqn=0 | | seqn=1 | | seqn=2 | -| | | sig="xxxx" | | sig="xxxx" | -+----------------+ +----------------+ +----------------+ - | | | - | off-chain | | -~ ~ ~ ~ | ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~|~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ | ~ ~ ~ ~ ~ ~ ~ ... - | on-chain | | - V V (zone file hash ) V -+----------------+ +----------------+ +----------------+ -| res_publica.id | | jude.id | | res_publica.id | -| NAME_UPDATE |<--------| NAME_UPDATE |<--------| NAME_UPDATE |<---- ... -+----------------+ +----------------+ +----------------+ - blockchain blockchain blockchain - block block block - - -Figure 2: Subdomain lifetime with respect to on-chain name operations .A new -subdomain operation will only be accepted if it has a later "sequence=" number, -and a valid signature in "sig=" over the transaction body .The "sig=" field -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." -However, any on-chain name ("jude.id" in this case) can broadcast a subdomain -update for "cicero.res_publica.id." -``` - -Subdomain operations are ordered by sequence number, starting at 0. Each new subdomain operation must include: - -- The next sequence number -- The public key that hashes to the previous subdomain transaction's address -- A signature from the corresponding private key over the entire subdomain operation. - -If two correctly signed but conflicting subdomain operations are discovered (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 subdomain's operations will be able to determine the valid sequence of state-transitions it has undergone, and determine the current zone file and public key hash for the subdomain. - -### Subdomain Creation and Management - -Unlike an on-chain name, a subdomain owner needs an on-chain name owner's help to broadcast their subdomain operations. In particular: - -- A subdomain-creation transaction can only be processed by the owner of the on-chain name that shares its suffix. For example, only the owner of `res_publica.id` can broadcast subdomain-creation transactions for subdomain names ending in `.res_publica.id`. -- A subdomain-transfer transaction can only be broadcast by the owner of the on-chain name that created it. For example, the owner of `cicero.res_publica.id` needs the owner of `res_publica.id` to broadcast a subdomain-transfer transaction to change `cicero.res_publica.id`'s public key. -- In order to send a subdomain-creation or subdomain-transfer, all of an on-chain name owner's zone files must be present in the Atlas network. This lets the BNS node prove the _absence_ of any conflicting subdomain-creation and subdomain-transfer operations when processing new zone files. -- A subdomain update transaction can be broadcast by _any_ on-chain name owner, but the subdomain owner needs to find one who will cooperate. For example, the owner of `verified.podcast` can broadcast a subdomain-update transaction created by the owner of `cicero.res_publica.id`. - -That said, to create a subdomain, the subdomain owner generates a subdomain-creation operation for their desired name and gives it to the on-chain name owner. - -Once created, a subdomain owner can use any on-chain name owner to broadcast a subdomain-update operation. To do so, they generate and sign the requisite subdomain operation and give it to an on-chain name owner, who then packages it with other subdomain operations into a DNS zone file and broadcasts it to the network. - -If the subdomain owner wants to change the address of their subdomain, they need to sign a subdomain-transfer operation and give it to the on-chain name owner who created the subdomain. They then package it into a zone file and broadcast it. - -### Subdomain Registrars - -Because subdomain names are cheap, developers may be inclined to run subdomain registrars on behalf of their applications. For example, the name `personal.id` is used to register usernames without requiring them to spend any Bitcoin. - -We supply a reference implementation of a [BNS Subdomain Registrar](https://github.com/stacks-network/subdomain-registrar) to help developers broadcast subdomain operations. Users would still own their subdomain names; the registrar simply gives developers a convenient way for them to register and manage them in the context of a particular application. - -# BNS and DID Standards - -BNS names are compliant with the emerging [Decentralized Identity Foundation](http://identity.foundation) protocol specification for decentralized identifiers (DIDs). - -Each name in BNS has an associated DID. The DID format for BNS is: - -```bash - did:stack:v0:{address}-{index} -``` - -Where: - -- `{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 `did:stack:v0:1dARRtzHPAFRNE7Yup2Md9w18XEQAtLiV-0`, because the name `personal.id` was the first-ever name created by `1dARRtzHPAFRNE7Yup2Md9w18XEQAtLiV`. - -As another example, the DID for `jude.id` is `did:stack:v0:16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg-1`. Here, the address `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` had created one earlier name in history prior to this one (which happens to be `abcdefgh123456.id`). - -The purpose of a DID is to provide an eternal identifier for a public key. The public key may change, but the DID will not. - -Stacks Blockchain implements a DID method of its own in order to be compatible with other systems that use DIDs for public key resolution. In order for a DID to be resolvable, all of the following must be true for a name: - -- The name must exist -- The name's zone file hash must be the hash of a well-formed DNS zone file -- The DNS zone file must be present in the Stacks node's data. -- The DNS zone file must contain a `URI` resource record that points to a signed JSON Web Token -- The public key that signed the JSON Web Token (and is included with it) must hash to the address that owns the name - -Not all names will have DIDs that resolve to public keys. However, names created by standard tooling will have DIDs that do. - -A RESTful API is under development. - -## DID Encoding for Subdomains - -Every name and subdomain in BNS has a DID. The encoding is slightly different 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 (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 subdomains owned by a single private key, and version byte 50 for subdomains owned by a m-of-n set of private keys. That is, subdomain DID addresses start with `S` or `M`, respectively. - -The `{index}` field for a subdomain's DID is distinct from the `{index}` field for a BNS name's DID, even if the same created both names and subdomains. For example, the name `abcdefgh123456.id` has the DID `did:stack:v0:16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg-0`, because it was the first name created by `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg`. However, `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` _also_ created `jude.statism.id` as its first subdomain name. The DID for `jude.statism.id` is `did:stack:v0:SSXMcDiCZ7yFSQSUj7mWzmDcdwYhq97p2i-0`. Note that the address `SSXMcDiCZ7yFSQSUj7mWzmDcdwYhq97p2i` encodes the same public key hash as the address `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` (the only difference between these two strings is that the first is base58check-encoded with version byte 0, and the second is encoded with version byte 63). diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/build-apps/references/references.md b/i18n/ko/docusaurus-plugin-content-docs/current/build-apps/references/references.md deleted file mode 100644 index babe5e119a..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/build-apps/references/references.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: References -sidebar_label: References ---- - -[Authentication](./authentication) - -[Blockchain Naming System](./bns) - -[Hiro example apps](https://docs.hiro.so/example-apps) \ No newline at end of file diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/contribute/docs.md b/i18n/ko/docusaurus-plugin-content-docs/current/contribute/docs.md deleted file mode 100644 index 77705451b8..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/contribute/docs.md +++ /dev/null @@ -1,207 +0,0 @@ ---- -title: Contribute to docs -description: Learn how this site is built, and how you can contribute to it. ---- - -## Introduction - -Thank you for your interest in contributing and helping make these docs as good as they can be. - -This docs site is built on the open source platform [Discosaurus 2](https://docusaurus.io/) and most of its content is written in Markdown files. All of the code for this site is free and open source, located at the [GitHub repository here](https://github.com/stacks-network/docs). - -:::tip Don't know what Markdown is? Want to learn? Here is a [helpful guide](https://guides.github.com/features/mastering-markdown/). - -Don't want to learn it? No need to. Write [in plain text an issue on Github](https://github.com/stacks-network/docs/issues/new?assignees=&labels=documentation&template=add-documentation.md&title=%5BAdd+docs%5D) ::: - -:::info You need a free [Github](https://www.github.com) account to add or edit any content. ::: - -To edit any page, just click on the *Edit this page* button at the bottom of each page and submit your changes online. - -To add new content, they are two different ways to do it, the [easy way](#easy-way) and the [advanced way](#advanced-way). - -## Easy way - -[**Simply click here and enter the text of the article you wish to add.**](https://github.com/stacks-network/docs/issues/new?assignees=&labels=documentation&template=add-documentation.md&title=%5BAdd+docs%5D) - -This will open up an issue on github using our template. -## Advanced way - -For more advanced changes you can follow the next steps. - -You can also test the site locally using this method. -### Steps - -1. Fork the [docs reposiroty](https://github.com/stacks-network/docs) by clicking on the *Fork* button in the upper right of the screen. -2. Clone your fork to your local machine with this command `git clone git@github.com:/docs.git stacks_docs` -3. Enter your project folder `cd stacks_docs` -4. Create a branch `git checkout -b feat/my-feature-branch`. -5. You can optionally preview your changes in real time with: - - `npm install` (to install dependencies). - - `npx docusaurus start` to start a local copy of the site. A web browser will open at http://localhost:3000, so you can see a preview of yourhanges in real time. -6. Make the changes you wish and then commit them with this kind of message: `git commit -am "feat: some new feature or content"`. -7. Push to to GitHub with `git push --set-upstream origin feature/my-feature-branch`. -8. Visit GitHub and make your pull request. - -## Aditional information -### Running and building the site locally (optional) - -You can start the page locally with the following command. This is enough to preview your changes. -```bash -npx docusaurus start -``` - -Before running this command for the first time you will need to run `npm install` to install dependencies. - -The docs site will be accessible at this url: [`http://localhost:3000`](http://localhost:3000). - - -After you finished your changes, you can also build the entire site with the following command (not usually needed): -```bash -npm run build -``` - -:::tip `npx docusaurus start` will only load the default language (english). To test all languages you can build with `npm run build` and then preview your build with `npm run serve`. ::: - -### An alternative: Working in browser - -As an alterative to working locally, you can also use the web IDE gitpod that provides an environment to contribute directly from within your browser. - -You only need to have a github account and open [this link](https://gitpod.io/#https://github.com/stacks-network/docs). - -### Folder structure of the site - -If you are interested in only adding new documentation content to the site, the files that will be important to you are located within `./docs/*`: - -```bash -docs/ - build-apps - contribute/ - faq/ - gaia/ - nodes-and-miners/ - noteworthy-contracts/ - references/ - understand-stack/ - write-smart-contracts/ -``` - -The routing for this site is file based, meaning if you created a folder within `/docs/gaia/` named `testing` and in it a file named `test1.md`, you would be able to navigate to `http://localhost:3000/gaia/testing/test1` and you would see whatever content is in that markdown file. - -All the docs in English are stored in the folder `/docs/`. - -To add new English content simply add a markdown file (.md) into any subfolder in docs, and it will be automatically displayed in the category of that folder. - -All the docs in other languages are stored under the folder `i18n`, but these files should never be edited using GitHub as they are overwritten by Crowdin every time new translations are added. **To make changes in other languages**, you must do so using Crowdin. Please refer to [translations](translations) instead. - -### Frontmatter - -Frontmatter is the top part of any markdown document that is written in a language called [YAML](https://yaml.org/). It looks like this: - -```yaml ---- -title: This is my page title -description: A short, concise sentence describing what is on this page ---- -``` - -Frontmatter gives us the ability to define some things within a page that the site can use, such as a page title or page description. When adding any new page, please include a `title` and `description`. - - - -### Use Conventional Commits - -We use the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) as and commits naming convention. Use it while contributing, please. - -### Code blocks - -To write a code block, you need to wrap your code in ` ```language `, and end your code block with ` ``` `. Here is an example of ` ```clarity `. - -```clarity -(define-data-var counter int 0) - -(define-public (get-counter) - (ok (var-get counter))) -``` -### Admonitions - -You can use the following admonitions to highlight content. - -```md -:::note -Some **content** with _markdown_ `syntax`. -::: - -:::tip -Some **content** with _markdown_ `syntax`. -::: - -:::info -Some **content** with _markdown_ `syntax`. -::: - -:::caution -Some **content** with _markdown_ `syntax`. -::: - -:::danger -Some **content** with _markdown_ `syntax`. -::: - -:::tip My personalized title -Some **content** with _markdown_ `syntax`. -::: -``` - -Which renders: - -:::note - -Some **content** with _markdown_ `syntax`. - -::: - -:::tip - -Some **content** with _markdown_ `syntax`. - -::: - -:::info - -Some **content** with _markdown_ `syntax`. - -::: - -:::caution - -Some **content** with _markdown_ `syntax`. - -::: - -:::danger - -Some **content** with _markdown_ `syntax`. - -::: - -:::tip My personalized title - -Some **content** with _markdown_ `syntax`. - -::: \ No newline at end of file diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/contribute/index.md b/i18n/ko/docusaurus-plugin-content-docs/current/contribute/index.md deleted file mode 100644 index ac81d899bd..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/contribute/index.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Contribute -description: Contribute to the Stacks ecosystem. -sidebar_position: 10 -sidebar_label: "Contribute" ---- - -You can contribute to the Stacks ecosystem in multiple ways: - - - -### Documentation - -Contribute to the Stacks Docs on this website. More info [here](docs). - -### Translations - -Help us reach more people with translations. More details [here](translations). - - - -### Articles - -Write an article or a blog post about Stacks. A good place to start is [Stacks Forum](https://forum.stacks.org). - -### Github - -If you are familiar with Github they are multiple repositories of the Stack Ecosystem that you can contribute to. - -- https://github.com/stacks-network/ diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/contribute/translations.md b/i18n/ko/docusaurus-plugin-content-docs/current/contribute/translations.md deleted file mode 100644 index bd9a452333..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/contribute/translations.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Contribute with translations -description: Want to help tranlating these docs to your local language? ---- - -## Help with translations - -Translations are managed with Crowdin. -Anybody can colaborate and no technichal skills are required, as it's all done on the browser. - -To help with translation please go to [this page](https://crowdin.com/project/docsstacksco), click any language and start translating. - -All help is appreciated. - -:::caution -Please don't add any translations to the Github repository, as the translated pages get rewritten from Crowdin. Translations need to be added on Crodin intead. -::: - -### Common issues on translations - -When translating in Crowdin, please only translate the texts and not the html code. - -If you acccidently modify the html tags you will get errors like shown below (`Seems like some formating tags are missing` or `Translation contains tag that source text doesn't have`). These errors will prevent your translation getting published until the tags are left as they were in the original text. - -![](/img/crowdin-qa-issue-formatting_tags_missing.png) ![](/img/crowdin-qa-issue-tag_source.png) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/faq/faq.md b/i18n/ko/docusaurus-plugin-content-docs/current/faq/faq.md deleted file mode 100644 index dde584e583..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/faq/faq.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: General FAQs -description: Frequently Asked Questions -sidebar_label: "FAQ" -sidebar_position: 10 ---- - -![](/img/glasses.png) - -## Why is my transfer still pending? - -Commonly it's because your fee is too low or your [nonce](#what-is-nonce) is incorrect. - -More information can be found [here](https://www.hiro.so/wallet-faq/why-is-my-stacks-transaction-pending). There are also [best practices and known issues](https://forum.stacks.org/t/transactions-in-mempool-best-practices-and-known-issues/11659) and [diagnosing pending transactions](https://forum.stacks.org/t/diagnosing-pending-transactions/11908). - -There is also this [script](https://github.com/citycoins/scripts/blob/main/getnetworkstatus.js) to look at either the first 200 transactions or all the transactions in the mempool, to then return the maximum adn average fee values. We've noticed that using 1.5-2x the average fee in the mempool will generally get things processed within 6-10 blocks even during high congestion. - -There is also this [script](https://github.com/citycoins/scripts/blob/main/gettxstatus.js) to track a pending transaction until it reaches a final status. - -## What is Nonce? - -A nonce is used to make sure that every transaction goes in right order. Nonce starts at 0, so the very first transaction from an address should set to nonce=0. You can find the nonce of your wallet address by searching the address in any [Stacks blockchain explorer](https://explorer.stacks.co/). You can also user `$ stx balance
`. - -If you have a transaction nonce that is less than your account nonce, the transaction is unmineable and will (should) disappear after 256 blocks. This does not affect future transactions and therefore can be just ignored, they are in the past. - -If you have a transaction nonce that is equal to your account nonce, then that transaction is valid and should be the next in line to be processed next. - -If you have a transaction nonce that is higher than your account nonce, then there needs to be a chain of transactions starting with your account nonce in order for it to be processed. E.g. Your account nonce is 10 but the pending transaction has a nonce of 12. It will not be mineable until a transaction with nonces 10 and 11 are processed. - -## Whats a Replace-by-fee (RBF)? - -A replace-by-fee (RBF) transaction tells the blockchain that you would like to replace one transaction with another, while specifying a fee that is higher than the original transaction fee. A transaction can be replaced with **any other transaction**, and is not limited to the same operation. - -This can be used to effectively **cancel a transaction** by replacing it with something else, like a small STX transfer to another owned address. - -This can be used to **raise the fee for a pending transaction** so it is considered by miners during periods of high congestion. This can also be used to _resubmit_ a transaction, in the sense that the RBF transaction gets a new txid and gets considered again (or faster) by miners. E.g. I submit my transaction with 1 STX fee at block 54,123. By block 54,133 I see my tx hasn’t been picked up, so I RBF with 1.1 STX. Then wait 10 blocks again, and RBF again if not received. There’s a balance between doing this too often and keeping a consistent pace, but it has been seen to help get transactions through, especially when new ones are constantly flooding in. - -The replacement transaction needs to use the same nonce as the original transaction with a fee increase of at least 0.000001 STX. E.g. Your original transaction has a fee of 0.03 STX, the new RBF transaction must have a fee of 0.030001 STX or above. - -RBF transactions process in one of two ways: - -- If miners pick up the original transaction before the RBF transaction is received, then the original transaction is processed and the replacement transaction goes into an unmineable state. It will eventually disappear and doesn’t affect future transactions. -- If miners pick up the replaced transaction then the new transaction is processed instead of the original, and the status of the original transaction is set to “droppped_replaced_by_fee”. This status is not shown on the explorer but can be seen when querying the txid. - -Submitting multiple transactions for the same action can slow things down in a few ways. - -- If the total spent in 2 or 3 transactions is more than can be spent in a single transaction, the transactions appear unmineable. -- If the fees for multiple transactions exceed the STX balance, the transactions will be unmineable. - -## What are .btc domains? - -[This forum post](https://forum.stacks.org/t/btc-domains-are-live/12065) explains all the benefits of .btc domains. They can currently be purchased in [btc.us](https://btc.us/) - -## What is the blockchain trilemma? - -## Stacks vs. Solana vs. Polygon: How Do They Compare From a Developer Perspective? - -[This blog post answers the question](https://www.hiro.so/blog/stacks-vs-solana-vs-polygon-how-do-they-compare-from-a-developer-perspective). - -## What Does Lightning’s Taro Proposal Mean for Stacks? - -[This blog post answers the question](https://www.hiro.so/blog/what-does-lightnings-taro-proposal-mean-for-stacks). - - -## Is Stacks a [PoS chain](https://en.wikipedia.org/wiki/Proof_of_stake)?[¹][] - -No. - -The act of block production requires an extrinsic expenditure — it is not tied to owning the native token, as would be required in PoS. The only way to produce blocks in the Stacks chain is to transfer Bitcoin to a predetermined randomized list of Bitcoin addresses. Moreover, the Stacks blockchain can fork, and there exists a protocol to rank forks by quality independent of the set of miners and the tokens they hold. These two properties further distinguish it from PoS chains, which cannot fork due to the inability to identify a canonical fork without trusting a 3rd party to decree a particular fork as valid. The ability to fork allows the Stacks blockchain to survive failure modes that would crash a PoS chain. - -## Is Stacks a [sidechain](https://en.bitcoin.it/wiki/Sidechain)?[¹][] - -No. - -For two key reasons. - -First, the history of all Stacks blocks produced is recorded to Bitcoin. This means that the act of producing a private Stacks fork is at least as hard as reorging the Bitcoin chain. This in turn makes it so attacks on the chain that rely on creating private forks (such as selfish mining and double-spending) are much harder to carry out profitably, since all honest participants can see the attack coming before it happens and have a chance to apply countermeasures. Sidechains offer no such security benefit. - -Second, the Stacks blockchain has its own token; it does not represent pegged Bitcoin. This means that the safety of the canonical fork of the Stacks blockchain is underpinned by its entire token economy’s value, whereas the safety of a sidechain’s canonical fork is underpinned only by whatever system-specific measures incentivize its validators to produce blocks honestly, or the Bitcoin miners’ willingness to process peg-in requests (whichever is the weaker guarantee). - - -## Is Stacks a [layer-2 system](https://academy.binance.com/en/glossary/layer-2) for Bitcoin?[¹][] - -No. - -Stacks blockchain is a layer-1 blockchain, which uses a novel and unique mining protocol called proof-of-transfer (PoX). A PoX blockchain runs in parallel to another blockchain (Bitcoin in Stacks’ case), which it uses as a reliable broadcast medium for its block headers. It's a sovereign system in its own right. The Stacks blockchain state is distinct from Bitcoin, and is wholly maintained by and for Stacks nodes. Stacks transactions are separate from Bitcoin transactions. Layer-2 systems like Lightning are designed to help scale Bitcoin payment transactions, whereas Stacks is designed to bring new use-cases to Bitcoin through smart contracts. Stacks is not designed as a Bitcoin layer-2 scalability solution. - - -## Is Stacks a [merged-mined chain](https://en.bitcoin.it/wiki/Merged_mining_specification)?[¹][] - -No. - -The only block producers on the Stacks chain are Stacks miners. Bitcoin miners do not participate in Stacks block validation, and do not claim Stacks block rewards. Moreover, Stacks is not a [blind merged-mined chain](https://github.com/bitcoin/bips/blob/master/bip-0301.mediawiki), because STX block winners are public and randomly chosen (instead of highest-bid-wins), and its tokens are minted according to a schedule that is independent of the degree of miner commitment or Bitcoin transferred (instead of minted only by one-way pegs from Bitcoin). This ensures that Stacks is able to make forward progress without opt-in from Bitcoin miners, and it ensures that Stacks miners are adequately compensated for keeping the system alive regardless of transaction volume. - -## Whats the difference between Stacks and Ethereum?[²][] -**Computation and Storage** Stacks does all computation and storage outside of the blockchain, and uses the blockchain only as a “shared source of truth” between clients. By contrast, Ethereum does all computation and most application storage in the blockchain itself. Like Ethereum, if two Stacks nodes see the same underlying blockchain, they will independently run the same computations and produce the same state. Unlike Ethereum, there is no Stacks-specific blockchain. - -**Programming Language and Tooling** Stacks’s programming model is based on running off-chain programs. These programs can be written and debugged in any language you want. By contrast, Ethereum’s programming model is based on running on-chain “smart contracts.” These are written and debugged with a whole new set of tools, like Solidity and Serpent. - -**Scalability of On-chain Computation** Stacks is designed around a “virtual chain” concept, where nodes only need to reach consensus on the shared “virtual chain” they’re interested in. Virtual chains do not interact with one another, and a single blockchain can host many virtual chains. Although Stacks’s specific virtual chain is not Turing-complete (i.e. it’s a list of instructions to build the name database), it is possible to create Turing-complete virtual chains like Ethereum. These virtual chains can live in any blockchain for which there exists a driver, and virtual chain clients only need to execute their virtual chain transactions (i.e. Stacks only processes Stacks virtual chain transactions). - -By contrast, because smart contracts run on-chain and can call one another, all Ethereum nodes need to process all smart contracts’ computations in order to reach consensus. This can get expensive as the number of running smart contracts grow, which takes the form of gas fee increases. - -**Scalability of Off-chain Computation** Stacks applications are very similar to Web applications today and almost never need to interact with the blockchain. For most Stacks applications, the blockchain is only used to authenticate the application’s code and data before the user runs it. By contrast, Ethereum applications usually require an application-specific smart contract, and must interact with the blockchain to carry out its operations. - - -[¹]: https://stacks.org/stacks-blockchain -[²]: https://forum.stacks.org/t/what-is-the-difference-between-blockstack-and-ethereum/781 diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/gaia/configuration.md b/i18n/ko/docusaurus-plugin-content-docs/current/gaia/configuration.md deleted file mode 100644 index a6a530cd70..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/gaia/configuration.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Configuration -description: Configuring Gaia Hub ---- - -## Configuration files - -The following configuration files exist in the folder `deploy/configs/gaia/`: - -``` -admin-config.json -hub-config.json -reader-config.json -``` - -## GAIA Admin Service - -You can also use the GAIA Admin Service to remotely administer it with an API Key. It will require you to install `npm` with a `apt install npm`. Once `npm` is installed you can continue with the steps in the [GAIA Admin Service](https://github.com/stacks-network/gaia/blob/master/admin/README.md). - -## Driver Selection - -The Gaia hub currently supports the following drivers: - -``` -'aws' == Amazon S3 -'azure' == Azure Blob Storage -'disk' == Local disk -'google-cloud' === Google Cloud Storage -``` - -Set the driver you wish to use in your [config.json](https://github.com/stacks-network/gaia/blob/master/hub/config.sample.json) file with the `driver` parameter. Many drivers additionally accept the `bucket` parameter, which controls the bucket name that files should be written to. - -These driver may require you to provide additional credentials for performing writes to the backends. See `config.sample.json` for fields for those credentials. In some cases, the driver can use a system configured credential for the backend (e.g., if you are logged into your AWS CLI account, and run the hub from that environment, it won't need to read credentials from your `config.json`). - -_Note:_ The disk driver requires a \*nix like filesystem interface, and will not work correctly when trying to run in a Windows environment. ::: - -## Note on SSL - -We _strongly_ recommend that you deploy your Gaia hub with SSL enabled. Otherwise, the tokens used to authenticate with the Gaia hub may be stolen by attackers, which could allow them to execute writes on your behalf. -Configuration options are available to run the hub with an `https` Node.js server. -Otherwise, a reverse proxy web server such as nginx or Apache can be used. - -## Require Correct Hub URL - -If you turn on the `requireCorrectHubUrl` option in your `config.json` file, your Gaia hub will require that authentication requests correctly include the `hubURL` they are trying to connect with. This is used to prevent a malicious gaia hub from using an authentication token for itself on other Gaia hubs. - -By default, the Gaia hub will validate that the supplied URL matches `https://${config.serverName}`, but if there are multiple valid URLs for clients to reach the hub at, you can include a list in your `config.json`: - -```javascript -{ - .... - serverName: "normalserver.com" - validHubUrls: [ "https://specialserver.com/", - "https://legacyurl.info" ] - .... -} -``` - -## The readURL parameter - -By default, the gaia hub drivers will return read URLs which point directly at the written content. For example, an S3 driver would return the URL directly to the S3 file. However, if you configure a CDN or domain to point at that same bucket, you can use the `readURL` parameter to tell the gaia hub that files can be read from the given URL. For example, the `hub.blockstack.org` Gaia Hub is configured to return a read URL that looks like `https://gaia.blockstack.org/hub/`. - -Unset this configuration parameter if you do not intend to deploy any caching. - -## Minimum Proofs Requirement - -The gaia hub can also be configured to require a minimum number of social proofs in a user's profile to accept writes from that user. This can be used as a kind of spam-control mechanism. However, we recommend for the smoothest operation of your gaia hub, to set the `proofsConfig.proofsRequired` configuration key to `0`. - -## CDN & Replicated Hubs - -- https://docs.microsoft.com/en-us/azure/storage/blobs/storage-https-custom-domain-cdn - -- The hub implementation is designed to be ran from a single Node.js instance. If the hub instance is sharded (e.g. replicated hubs via load balancing), then any given `bucket` (identified by URI segment) must be served by the same instance, At least a couple elements of the Gaia Hub depend on this: token invalidation in-memory caching, and resource endpoint 409 contention behavior. diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md b/i18n/ko/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md deleted file mode 100644 index 558cbb14f5..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Deploy Gaia Hub -description: Steps and tutorials ---- - -## Deploy your GAIA hub - -Tutorials to deploy your own GAIA hub are currently available for [Linux](./setup-linux), [MacOS](./setup-mac) and [Amazon EC2 / CloudFormation](./gaia-on-ec2). - -Regardless of what server the Gaia Hub runs on, the storage it uses can currently be deployed on multiple platforms: - -- Local disk (the server itself) -- Amazon S3 -- Azure Blob Storage -- Google Cloud - -:::tip -Support for IPFS is under development. -::: \ No newline at end of file diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md b/i18n/ko/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md deleted file mode 100644 index 2067e7d57c..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Amazon EC2 -description: Use a template to deploy a Gaia hub on Amazon EC2 -tags: - - tutorial - - gaia ---- - -## Introduction - -The template provided on this page provides an easy way to deploy a Gaia hub directly to Amazon EC2. You can use this template to deploy your own Gaia hub to your Amazon Web Services (AWS) account. Amazon EC2 is an affordable and convenient cloud computing provider. The template provides a one-click deploy for Amazon EC2 with either S3 or EBS as a storage provider. - -## Prerequisites - -This procedure uses Amazon CloudFormation to configure an EC2 cloud compute provider to run the Gaia hub service with an S3 or EBS provider for file storage. You should have access to an AWS account either through your personal account or through a corporate account. This account should have permissions to create resources. - -Additionally, you must also own a domain name and be able to update the DNS records associated with that domain name. - -## Setup steps - -### Step 1 - Create Stack - -Use a link in the table to launch the [CloudFormation](https://console.aws.amazon.com/cloudformation/) template in the AWS region that you wish to deploy a Gaia hub. - -![Create stack](/img/cloudformation-create-stack.png) - -### Step 2 - Setup stack using template - -You need to configure the template with the appropiate values for your hub and domain it runs on. - -Select `Template is ready` and `Amazon S3 URL` and enter the following Amazon S3 URL: -``` -https://s3-external-1.amazonaws.com/cf-templates-vzldibfi2mw8-us-east-1/2022160J6G-cloudformation.yaml -``` - -If you prefer you can instead select `Template is ready` and `Upload a template file` to upload the template file `cloudformation.yaml`. - -The latest `cloudformation.yaml` file can be downloaded [here](https://raw.githubusercontent.com/stacks-network/gaia/master/deploy/cloudformation.yaml). On most browsers you can right-click on that page and click on `Save page as` to download the file. Alternatively, you can copy/paste the text into a text file called `cloudformation.yaml`. - -Then click `Next`. - -![Specify template](/img/cloudformation-specify-template.png) - -### Step 3 - Specify stack details - -Specify the stack details and then click `Next`: ![Specify template](/img/cloudformation-specify-stack-details.png) - -| Field | Value | Notes | -| --------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Stack name | _a unique name in your AWS account_ | e.g.: my_gaia_hub | -| DomainName | _your-domain_ | | -| EmailAddress | _your email address_ | | -| GaiaBucketName | _S3 bucket name_ | The template combines this name with the stack name to create a unique S3 bucket. The template ignores this field if GaiaStorageType is set to `disk`. | -| GaiaStorageType | `s3` or `disk` | Select the GaiaStorageType of which to use as a backend for the Gaia Hub. Selecting `s3` causes the template to create an S3 bucket based on the name given in the previous field. Selecting `disk` causes the template to attach a separate EBS volume to the EC2 instance for Hub storage. | -| InstaceType | t2.micro | Select the instance type you want. Default value is `t2.micro`. | -| KeyName | | In the KeyName drop-down, select an [EC2 KeyPair](https://console.aws.amazon.com/ec2/v2/home?region=us-east-1#KeyPairs:) to enable SSH access to the EC2 instance. You should download the `.pem` keyfile for this pair from the EC2 console. For more information see the [EC2 key pair documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html#prepare-key-pair) | -| SSHLocation | 0.0.0.0/0 | Leave the SSHLocation field with the default value of `0.0.0.0/0` to enable SSH access from any IP address. If you wish to restrict SSH access to the EC2 instance to a certain IP, you can update this field. | -| SubnetId | _subnetid_ | Select a public subnet | -| VpcId | _vpcid_ | | - -### Step 4 - Configure stack options - -Configure any stack options that fit your desired setup and click `Next`. All these fields are optional. - -![Specify template](/img/cloudformation-stack-options.png) - -### Step 5 - Review - -Review the configuration of your Gaia hub, select the checkbox to acknowledge that AWS may create IAM resources with custom names and click on `Create stack`. - -![Specify template](/img/cloudformation-iam-resources.png) - -### Step 6 - Retrieve the public IP of your Gaia hub - -Your stack can take several minutes to launch. You can monitor the Events tab of your hub to review the current progress of the launch. When the launch is complete, the Outputs tab displays information about the hub. Select the PublicIP and copy it to configure your domain name. - -Create an `A` DNS record pointing to the given IP in your domain. - -Wait a few minutes for the DNS record to propagate, and your should be able to access your Gaia hub with SSH. - -## Accessing your Gaia hub with SSH - -To SSH into your Gaia hub EC2 host directly, you must have the keyfile used in container creation. Access the host with the following command in your terminal: - -```bash -ssh -i admin@ -``` - -:::tip If you can only access SSH with the IP but not with the DNS name and you wish to do so, you can optionally activate it by following these steps: - - Open your [AWS Console](https://console.aws.amazon.com) - Click on `Service` -> VPC - Open Your VPCs - Select your VPC connected to your Gaia Hub - Click `Actions` -> `Edit DNS Hostnames` -> Change `DNS hostnames` to `Enable` -::: -## Graphical representation of the cloudformation template - -![](/img/cloudformation-gaia-template1-designer.png) \ No newline at end of file diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/gaia/gaia.md b/i18n/ko/docusaurus-plugin-content-docs/current/gaia/gaia.md deleted file mode 100644 index 1070857350..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/gaia/gaia.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Gaia -description: Decentralized storage architecture for off-chain data -sidebar_position: 5 -tags: - - gaia ---- - -## Introduction - -Apps built with the Stacks blockchain store off-chain data using a storage system called Gaia. - -Whereas public transactional metadata is best stored on the Stacks blockchain, user application data can often be stored more efficiently and privately in Gaia storage. - -Storing data off of the blockchain ensures that Stacks applications can provide users with high performance and high availability for data reads and writes without introducing central trust parties. - -:::tip Latest whitepaper of GAIA (May 2022) is available [here](https://dev1-gaia-hub.s3.amazonaws.com/GAIA_Whitepaper.pdf) ::: - -## Understand Gaia in the Stacks architecture - -The following diagram depicts the Stacks architecture and Gaia's place in it: - -![Stacks Architecture](/img/architecture.png) - -Blockchains require consensus among large numbers of people, so they can be slow. Additionally, a blockchain is not designed to hold a lot of data. This means using a blockchain for every bit of data a user might write and store is expensive. For example, imagine if an application were storing every tweet in the chain. - -The Stacks blockchain addresses performance problems using a layered approach. The base layer consists of the Stacks blockchain and the Blockchain Naming System (BNS). The blockchain governs ownership of identities in the Stacks network. Identities can be names such as domain names, usernames, or application names. - -When an identity is created, its creation is recorded in the Stacks blockchain. Identities make up the primary data stored into the Stacks blockchain. These identities correspond to routing data in the OSI stack. The routing data is stored in the Atlas Peer Network, the second layer. Every core node that joins the Stacks Network is able to obtain an entire copy of this routing data. Stacks uses the routing data to associate identities (domain names, user names, and application names) with a particular storage location in the final layer, the Gaia Storage System. - -A Gaia Storage System consists of a _hub service_ and storage resource on a cloud software provider. The storage provider can be any commercial provider such as Azure, DigitalOcean, Amazon EC2, and so forth. Typically the compute resource and the storage resource reside same cloud vendor, though this is not a requirement. Gaia currently has driver support for S3, Azure Blob Storage, Google Cloud Platform and local disk, but the driver model allows for other backend support as well. - -Gaia stores data as a simple key-value store. When an identity is created, a corresponding data store is associated with that identity on Gaia. When a user logs into a dApp, the authentication process gives the application the URL of a Gaia hub, which then writes to storage on behalf of that user. - -The Stacks blockchain stores only identity data. Data created by the actions of an identity is stored in a Gaia Storage System. Each user has profile data. When a user interacts with a decentralized dApp that application stores application data on behalf of the user. Because Gaia stores user and application data off the blockchain, a Stacks DApp is typically more performant than DApps created on other blockchains. - -## User control or how is Gaia decentralized? - -A Gaia hub runs as a service which writes to data storage. The storage itself is a simple key-value store. The hub service writes to data storage by requiring a valid authentication token from a requestor. Typically, the hub service runs on a compute resource and the storage itself on separate, dedicated storage resource. Typically, both resources belong to the same cloud computing provider. - -![Gaiastorage](/img/gaia-storage.png) - -Gaia's approach to decentralization focuses on user control of data and its storage. Users can choose a Gaia hub provider. If a user can choose which Gaia hub provider to use, then that choice is all the decentralization required to enable user-controlled applications. Moreover, Gaia defines a uniform API for applications to access that data. - -The control of user data lies in the way that user data is accessed. When an application fetches a file `data.txt` for a given user `alice.id`, the lookup will follow these steps: - -1. Fetch the `zonefile` for `alice.id`. -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. Find the read-only url out of the profile's `appsMeta` section (e.g. `https://example-app.gaia.alice.org`). -6. Fetch the file from `https://example-app.gaia.alice.org/data.txt`. - -Because `alice.id` has access to her [zonefile](https://docs.stacks.co/references/bns-contract#name-update), 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. - -:::caution -Users with existing identities cannot yet migrate their data from one hub to another. -::: - -Applications writing directly on behalf of `alice.id` do not need to perform a lookup. Instead, the [Stacks authentication flow](https://stacks.js.org) provides Alice's chosen gaia hub URL to the application. This authentication flow _is also_ within Alice's control because Alice's wallet _must_ generate the authentication response. - -## Understand data storage - -A Gaia hub stores the written data _exactly_ as given. It offers minimal guarantees about the data. It does not ensure that data is validly formatted, contains valid signatures, or is encrypted. Rather, the design philosophy is that these concerns are client-side concerns. - -Client libraries (such as [`Stacks.js`](https://stacks.js.org/)) are capable of providing these guarantees. A liberal definition of the [end-to-end principle](https://en.wikipedia.org/wiki/End-to-end_principle) guides this design decision. - -When an application writes to a Gaia hub, an authentication token, key, and the data are passed to the Gaia hub. - -![Gaia writes](/img/gaia-writes.png) - -The token ensures the app has the authorization to write to the hub on the user's behalf. - -## Gaia versus other storage systems - -Here's how Gaia stacks up against other decentralized storage systems. Features that are common to all storage systems are omitted for brevity. - -| Features | [Gaia](https://github.com/stacks-network/gaia) | [Sia](https://sia.tech/) | [Storj](https://storj.io/) | [IPFS](https://ipfs.io/) | [DAT](https://datproject.org/) | [SSB](https://www.scuttlebutt.nz/) | -| ------------------------------------------ | ---------------------------------------------- | ------------------------ | -------------------------- | ------------------------ | ------------------------------ | ---------------------------------- | -| User controls where data is hosted | X | | | | | | -| Data can be viewed in a normal Web browser | X | | | X | | | -| Data is read/write | X | | | | X | X | -| Data can be deleted | X | | | | X | X | -| Data can be listed | X | X | X | | X | X | -| Deleted data space is reclaimed | X | X | X | X | | | -| Data lookups have predictable performance | X | | X | | | | -| Writes permission can be delegated | X | | | | | | -| Listing permission can be delegated | X | | | | | | -| Supports multiple backends natively | X | | X | | | | -| Data is globally addressable | X | X | X | X | X | | -| Needs a cryptocurrency to work | | X | X | | | | -| Data is content-addressed | | X | X | X | X | X | diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/gaia/setup-linux.md b/i18n/ko/docusaurus-plugin-content-docs/current/gaia/setup-linux.md deleted file mode 100644 index db427f890a..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/gaia/setup-linux.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: Linux -description: Steps to setup a GAIA hub on a Linux server (fresh install). This example is using Debian, but should work on any Linux distribution. It uses docker compose in the backgroud. -tags: - - tutorial - - gaia ---- - -This configuration will setup the following 4 docker containers: - -- Nginx with certbot on TCP ports 80 and 443. -- Gaia hub on TCP port 3000. -- Gaia admin on TCP port 8009. -- Gaia reader on TCP port 8008 - -**1. Update the system and install the dependencies and software we will use to test:** - -```bash -apt update && apt upgrade -y && apt install -y git vim gnupg jq -``` - -**2. Install [docker](https://docs.docker.com/engine/install/debian/) and [docker-compose](https://docs.docker.com/compose/cli-command/#install-on-linux)** in your OS. -For our example we install _docker_ with: - -```bash -curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg - -echo \ - "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian \ - $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null - -apt update && apt install -y docker-ce docker-ce-cli containerd.io -``` - -Install _docker-compose_ by downloading the [latest-release](https://github.com/docker/compose/releases): - -```bash -VERSION_DC=$(curl --silent https://api.github.com/repos/docker/compose/releases/latest | jq .name -r) -DESTINATION_DC=~/.docker/cli-plugins -mkdir -p ${DESTINATION_DC} -curl -SL https://github.com/docker/compose/releases/download/${VERSION_DC}/docker-compose-linux-x86_64 -o ${DESTINATION_DC}/docker-compose -chmod +x ${DESTINATION_DC}/docker-compose -``` - -**3. Clone the GAIA repository** and enter it's docker directory. - -```bash -git clone https://github.com/stacks-network/gaia.git && cd gaia/deploy/docker -``` - -**4. Copy and edit appropiate .env file**. -In the folder `./deploy/docker/` they are different sample files for different configurations like using aws, azure or disk among others. In this example we will store the data localy so we will copy the _disk_ file and update the domain and email fields. Please change `gaia.site.com` and `gaiarocks@mydomain.com` accordingly. Note you need both for the SSL certificate to be created correctly. - -```bash -export MYGAIADOMAIN=gaia.site.com -export MYGAIAEMAIL=gaiarocks@mydomain.com -cp sample-disk.env disk.env -sed -i 's/my-domain.com/'"$MYGAIADOMAIN"'/g' disk.env -sed -i 's/my-email@example.com/'"$MYGAIAEMAIL"'/g' disk.env - -``` - -**5. Start GAIA HUB service** - -To start GAIA HUB - -```bash -./gaiahub.sh start -``` - -To stop GAIA HUB - -```bash -./gaiahub.sh stop -``` - -To view GAIA HUB status - -```bash -./gaiahub.sh status -``` - -**6. Verify server works locally** with the following command: - -```bash -curl -sk http://localhost/hub_info | jq -``` - -A correct result should look similar to this: - -```bash - { - "challenge_text": "[\"gaiahub\",\"0\",\"gaia-0\",\"blockstack_storage_please_sign\"]", - "latest_auth_version": "v1", - "max_file_upload_size_megabytes": 20, - "read_url_prefix": "https://gaia.site.com/reader/" - } -``` - -**7. Test your GAIA HUB** Running `gaia_test.js` will test your GAIA Hub, by trying to connect to it, uploading a file and downloading it again. - -First install all required dependencies with: - -```bash -npm install -``` - -Then, from the root folder of the project type: - -```bash -node ./deploy/gaia_test.js https://yourgaiaurl -``` - -A correct result will be something like this: - -``` -Will run a test for the GAIA HUB: https://gaia.mydomain.com -Generating some test keys... -Private key: 5aacc60fc2a429e1f02be139f3cac82061c6a980******************** -Public key: 025691f17f2ab80dc4af363bb9c7aac59e9e1db6ae8ff668202582a3f4ec9678ff -Address: 15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS -[DEBUG] connectToGaiaHub: https://gaia.mydomain.com/hub_info -[DEBUG] uploadToGaiaHub: uploading testing.txt to https://gaia.mydomain.com -File uploaded successfully. -Upload to gaia hub thinks it can read it from: https://gaia.mydomain.com/reader/15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS/testing.txt -Hub info thinks it can read it from : https://gaia.mydomain.com/reader/15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS/testing.txt -Let's now try to fetch the uploaded file... -File fetched successfully. Contents of file: GAIA ROCKS! -``` diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/gaia/setup-mac.md b/i18n/ko/docusaurus-plugin-content-docs/current/gaia/setup-mac.md deleted file mode 100644 index 808833b212..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/gaia/setup-mac.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: MacOS -description: MacOS for local testing/development -tags: - - tutorial ---- - -The following assumes you have [Docker Installed](https://docs.docker.com/docker-for-mac/install/) - -- Recommended to also have [MacOS Homebrew](https://docs.brew.sh/Installation) installed -- Use Homebrew to install jq with `brew install jq` - -In your working directory: - -**1. Clone a copy of the [gaia repo](https://github.com/stacks-network/gaia):** - -```bash -$ git clone -b master --single-branch https://github.com/stacks-network/gaia -``` - -**2. Change your cwd:** - -```bash -$ cd gaia/deploy/docker -``` - -**3. Create a copy of sample-disk.env and fill out the values:** - -``` -$ cp sample-disk.env disk.env -# Update the DOMAIN_NAME variable to `localhost` -``` - -**4. Start the server:** - -``` -$ docker-compose -f docker-compose-base.yaml -f docker-compose-disk.yaml --env-file disk.env up -``` - -**5. Verify the server is responding locally:** - -``` -$ curl -sk https://localhost/hub_info | jq - { - "challenge_text": "[\"gaiahub\",\"0\",\"gaia-0\",\"blockstack_storage_please_sign\"]", - "latest_auth_version": "v1", - "max_file_upload_size_megabytes": 20, - "read_url_prefix": "https://localhost/reader/" - } -``` - -### Modifying the configuration for your gaia-hub - -Two methods exist: - -1. Edit the `gaia/deploy/configs/gaia/hub-config.json` using `vim` or other - -- requires a restart of the containers: `docker-compose -f docker-compose-base.yaml -f docker-compose-disk.yaml --env-file disk.env restart` - -2. Use the running `admin` container to modify any config values, and also reload the hub when complete: - -- [GitHub - Gaia Admin README.md](https://github.com/stacks-network/gaia/blob/master/admin/README.md) - -``` -$ export API_KEY="hello" -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - -H 'Content-Type: application/json' \ - -X POST \ - --data-raw '{"serverName": "myserver"}' \ - http://localhost:8009/v1/admin/config - -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - -X POST \ - http://localhost:8009/v1/admin/reload - -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - http://localhost:8009/v1/admin/config | jq -``` diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/governance/_index.md b/i18n/ko/docusaurus-plugin-content-docs/current/governance/_index.md deleted file mode 100644 index 1ecdf67871..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/governance/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Governance -description: Governance -sidebar_position: 9 ---- - -This page needs contributions. Help us write it! \ No newline at end of file diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/governance/index.md b/i18n/ko/docusaurus-plugin-content-docs/current/governance/index.md deleted file mode 100644 index 91b0215b5f..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/governance/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Governance -description: Governance -sidebar_position: 9 ---- - -![](/img/stacks-governance.png) - -This page needs contributions. Help us write it! - -Governance in web3 is driven by the community. - -How can I get involved ? - -[Governance Resources website](https://resources.stacksgov.com) - -[Github - Stack Community Governance](https://github.com/stacksgov) - -:::tip Community Calls Monthly community calls are recorded and available [here](https://www.youtube.com/playlist?list=PLg717Ri_rTnwwYjQYlc7rIP6x2FaTNn7f) ::: diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/governance/sips.md b/i18n/ko/docusaurus-plugin-content-docs/current/governance/sips.md deleted file mode 100644 index 29ac1ae1ed..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/governance/sips.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: SIPs -description: SIPs -sidebar_position: 9 ---- - -## Stacks Improvement Proposals (SIPs) - -Stacks improvement proposals (SIPs) are aimed at describing the implementation of the Stacks blockchain, as well as proposing improvements. - -The SIP process [(SIP-000)](https://github.com/stacksgov/sips/blob/main/sips/sip-000/sip-000-stacks-improvement-proposal-process.md) describes how to make a SIP and get it ratified. - -They should contain concise technical specifications of features or standards and the rationale behind it. SIPs are intended to be the primary medium for proposing new features, for collecting community input on a system-wide issue, and for documenting design decisions. - -The SIPs are located in the [stacksgov/sips](https://github.com/stacksgov/sips) repository as part of the [Stacks Community Governance organization](https://github.com/stacksgov). - -Anyone in the Stacks community can submit a SIP. - -:::tip Stacks Improvement Proposals Community Calls SIP Meeting calls are recorded and available [here](https://www.youtube.com/playlist?list=PLg717Ri_rTnx5kuaWqp3cUAtwQk_yzslT) - -More details of the meetings are available [here](https://github.com/stacksgov/sips/issues/79) ::: - -## Ratified SIPSs - -- [x] [SIP 001: Burn Election](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md) -- [x] [SIP 002: Clarity, a language for predictable smart contracts](https://github.com/stacksgov/sips/blob/main/sips/sip-002/sip-002-smart-contract-language.md) -- [x] [SIP 003: Peer Network](https://github.com/stacksgov/sips/blob/main/sips/sip-003/sip-003-peer-network.md) -- [x] [SIP 004: Cryptographic Committment to Materialized Views](https://github.com/stacksgov/sips/blob/main/sips/sip-004/sip-004-materialized-view.md) -- [x] [SIP 005: Blocks, Transactions, and Accounts](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md) -- [x] [SIP 006: Clarity Execution Cost Assessment](https://github.com/stacksgov/sips/blob/main/sips/sip-006/sip-006-runtime-cost-assessment.md) -- [x] [SIP 007: Stacking Consensus](https://github.com/stacksgov/sips/blob/main/sips/sip-007/sip-007-stacking-consensus.md) -- [x] [SIP 008: Clarity Parsing and Analysis Cost Assessment](https://github.com/stacksgov/sips/blob/main/sips/sip-008/sip-008-analysis-cost-assessment.md) -- [x] [SIP 009: Standard Trait Definition for Non-Fungible Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-009/sip-009-nft-standard.md) -- [x] [SIP 010: Standard Trait Definition for Fungible Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-010/sip-010-fungible-token-standard.md) -- [x] [SIP 012: Burn Height Selection for a Network Upgrade to Introduce New Cost-Limits](https://github.com/stacksgov/sips/blob/main/sips/sip-012/sip-012-cost-limits-network-upgrade.md) -- [x] [SIP-016: Metadata for Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-016/sip-016-token-metadata.md) - -## How to Get Involved - -There are several ways you can get involved with the SIP process: - -* **Join the weekly SIP Meeting call** listed [here](https://community.stacks.org/events). - -* **SIP Editor**. SIP editors help SIP authors make sure their SIPs are well-formed and follow the right process. They help get SIPs ready for deep review by advancing it them from Draft to Accepted status. If you want to become a SIP editor, open an issue with your name and email to ask to be added to the list of SIP editors. - -* **Join a CAB** (Consideration Advisory Board). SIPs fall under the purview of one or more considerations. A full list is in [this github](https://github.com/stacksgov/sips/tree/main/considerations) directory. Currently they are: Diversity, Economics, Ethics, Governance and Technical. Members of SIP consideration advisory boards use their domain expertise to give Accepted SIPs a deep read, and give the authors any/all feedback to help make the SIP workable. If you want to join a board, reach out to the board's chairperson via the listed contact information. - -* **Steering Committee**. The Steering Committee organizes the consideration advisory boards and votes to advance Recommended SIPs to Activation-in-Progress status, and then to either Ratified or Rejected status. Once they are in the process of being activated, they use a SIP's Activation section to determine whether or not the Stacks ecosystem has ratified or rejected the SIP. Joining this committee requires the consent of the Stacks Foundation board. diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/intro.md b/i18n/ko/docusaurus-plugin-content-docs/current/intro.md deleted file mode 100644 index 84f1eaa649..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/intro.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_label: "Home" -sidebar_position: 1 ---- - -# Stacks Docs Introduction - -Welcome to the community driven official Stacks Documentation. - -Learn about Stacks mining, the STX token, and the Clarity smart contract language. - -![](/img/Bitcoinet-L_2.svg) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md b/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md deleted file mode 100644 index dd7194f504..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Stacks on DigitalOcean -description: A guide to setup Stacks on DigitalOcean -sidebar_position: 4 -tags: - - tutorial ---- - -## Introduction - -This is a step by step guide to deploy the [Stacks Blockchain on DigitalOcean](https://marketplace.digitalocean.com/apps/stacks-blockchain). Code is hosted on this [Github repository](https://github.com/stacks-network/stacks-blockchain-docker). - -## Steps - -#### Step 1 - -Go to the [Stacks Blockchain page](https://marketplace.digitalocean.com/apps/stacks-blockchain) in DigitalOcean's marketplace. Click on `Create Stacks Blockchain Droplet`. - -#### Step 2 - -Choose a plan (it will only allow you to select a plan that meets the minimum requirements) and your prefered datacenter region. ![](/img/sh_digitalocean-choose-plan.png) - -#### Step 3 - -Enter a root password or enable SSH keys if your prefer. - -![](/img/sh_digitalocean-choose-authentication.png) - -#### Step 4 - -You can leave the rest of the options as they are and click on `Create Droplet` - -#### Step 5 - -You will need to wait a few seconds for the droplet to get created. Once created click on it to see more information. - -![](/img/sh_digitalocean-creating-droplet.png) - -![](/img/sh_digitalocean-created-droplet.png) - -### Step 6 - -Congratulations! You are now running the Stacks Blockchain. You can click on `Console` for a terminal window to open or login using SSH to the public IP you've been assigned to with user `root`. - -![](/img/sh_digitalocean-console-button.png) ![](/img/sh_digitalocean-console.png) - -## Getting started after deploying Stacks Blockchain - -Once droplet is launched, initial startup can take several minutes while BNS data is imported (this is a one time operation). - -To keep track of the progress, you can `ssh root@your_droplet_public_ipv4` to the host and run: `/opt/stacks-blockchain-docker/manage.sh -n mainnet -a logs`. - -Once the stacks blockchain starts to sync with peers, application ports will open and nginx port 80 will now start proxying requests. - -Use `http://your_droplet_public_ipv4` to access the data directly, with output being similar to: - -```json -{ - "server_version": "stacks-blockchain-api v3.0.3 (master:cd0c8aef)", - "status": "ready", - "chain_tip": { - "block_height": 16220, - "block_hash": "0x3123fba9c0de6b569573494cf83c1d5d198a66bfd5f48ef97949b6bf11ba13be", - "index_block_hash": "0xeec960fbbd6186b4ccac85ce12adba72be497d881f81e077305c90955b51a6ae" - } -} -``` - -All services are managed by a [systemd unit file](https://github.com/stacksfoundation/stacks-machine-images/blob/master/files/etc/systemd/system/stacks.service) that is set to start on boot. - -Manual control is also possible via the [manage.sh script](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/manage.sh) at `/opt/stacks-blockchain-docker/manage.sh` on the host. - -Full details on how to use the manage.sh script is [available here](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/README.md#quickstart). - -## API Creation - -In addition to creating a Droplet from the Stacks Blockchain 1-Click App via the control panel, you can also use the [DigitalOcean API](https://digitalocean.com/docs/api). - -As an example, to create a 4GB Stacks Blockchain Droplet in the SFO2 region, you can use the following curl command. You’ll need to either save your [API access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/) to an environment variable or substitute it into the command below. - -```bash -curl -X POST -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer '$TOKEN'' -d \ - '{"name":"choose_a_name","region":"sfo2","size":"s-2vcpu-4gb","image":"stacksfoundation-stacksblockchain"}' \ - "https://api.digitalocean.com/v2/droplets" -``` diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md b/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md deleted file mode 100644 index b6cbb9754a..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Nodes and Miners -description: Nodes and Miners -sidebar_position: 7 ---- - -Here are all the steps to run nodes and miners, both on mainnet and testnet. - -## What's a Stacks node? - -## What's a Stacks miner? diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md b/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md deleted file mode 100644 index 40397a51e0..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Miner costs and fees -description: Miner Cost and Fee Estimation -sidebar_position: 8 ---- - -## Configuring Cost and Fee Estimation - -Fee and cost estimators can be configured via the config section `[fee_estimation]`: - -``` -[fee_estimation] -cost_estimator = naive_pessimistic -fee_estimator = fuzzed_weighted_median_fee_rate -fee_rate_fuzzer_fraction = 0.1 -fee_rate_window_size = 5 -cost_metric = proportion_dot_product -log_error = true -enabled = true -``` - -Fee and cost estimators observe transactions on the network and use the observed costs of those transactions to build estimates for viable fee rates and expected execution costs for transactions. Estimators and metrics can be selected using the configuration fields above, though the default values are the only options currently. `log_error` controls whether or not the INFO logger will display information about the cost estimator accuracy as new costs are observed. Setting `enabled = false` turns off the cost estimators. Cost estimators are **not** consensus-critical components, but rather can be used by miners to rank transactions in the mempool or client to determine appropriate fee rates for transactions before broadcasting them. - -The `fuzzed_weighted_median_fee_rate` uses a median estimate from a window of the fees paid in the last `fee_rate_window_size` blocks. Estimates are then randomly "fuzzed" using uniform random fuzz of size up to `fee_rate_fuzzer_fraction` of the base estimate. diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md b/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md deleted file mode 100644 index 061f4a2511..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md +++ /dev/null @@ -1,343 +0,0 @@ ---- -title: Mine mainnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 mainnet -sidebar_position: 5 -tags: - - tutorial ---- - -## Introduction - -Make sure you've followed the [run a node](run-a-node) procedure. Once completed it's only a few more steps to run a proof-of-burn miner on the mainnet. - -If you're interested in mining on the testnet, you can find instructions on how to do that [here](miner-testnet): - -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining): - -## Running bitcoind locally - -To participate as a miner on mainnet, you must have access to a mainnet bitcoin node. One way to accomplish this is to run bitcoind locally. [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements) - -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. - -Next, start bitcoind with the following configuration: - -```toml -server=1 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=1 -banscore=1 -bind=0.0.0.0:8333 -rpcbind=0.0.0.0:8332 -rpcport=8332 -``` - -Finally, start bitcoind as follows: - -```bash -bitcoind -conf=path/to/bitcoin.conf -``` - -It may take a few days for the node to synchronize with the Bitcoin mainnet. - -## Running a miner - -First, a keychain needs to be generated. With this keychain, we'll purchase some BTC from a crytpocurrency exchange, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. We'll use the `make_keychain` command. - -```bash -npx @stacks/cli make_keychain 2>/dev/null | json_pp > keychain.txt -``` - -After this runs, you should see some JSON in the new `keychain.txt` file that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -**Don't lose this information** - we'll need to use the `privateKey` field later on. - -The above BTC address will then need to be imported into the BTC network. - -```bash -bitcoin-cli -rpcport=8332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - - - -Once imported, we need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - - - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/mainnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `make_keychain` command. Replace the `seed` field with your private key. Save and close this configuration file. - -To run your miner, run this in the command line: - -```bash -stacks-node start --config=./testnet/stacks-node/conf/mainnet-miner-conf.toml -``` - -Your node should start. It will take some time to sync, and then your miner will be running. - -### Creating an optimized binary - -The steps above are great for trying to run a node temporarily. If you want to host a node on a server somewhere, you might want to generate an optimized binary. To do so, use the same configuration as above, but run: - -```bash -cd testnet/stacks-node -cargo build --release --bin stacks-node -``` - -The above code will compile an optimized binary. To use it, run: - -```bash -cd ../.. -./target/release/stacks-node start --config=./mainnet-miner-conf.toml -``` - -To read more about the technical details of mining on the Stacks 2.0 network, have a look at [the mining guide](../understand-stacks/mining). - -### Enable debug logging - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -STACKS_LOG_DEBUG=1 stacks-node mainnet -``` - -## Running a miner in Windows - -### Prerequisites - -Make sure are [running a node](run-a-node) and [running bitcoind locally](#running-bitcoind-locally) before starting this tutorial. - -### Generate keychain and get mainnet tokens in Windows - -To setup the miner, first we need to generate a keychain. With this keychain, we'll purchase some BTC from a crytpocurrency exchange, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. To get a keychain, the simplest way is to use the `stacks-cli`. - -Generate a keychain: - -```bash -npm install --global @stacks/cli -stx make_keychain > cli_keychain.json -type cli_keychain.json -``` - -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -The above BTC address will then need to be imported into the BTC network. - -```bash -bitcoin-cli -rpcport=8332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - -Once imported, we need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Update configuration file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/mainnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Run the miner - -To start your miner, run this in the command line: - -```bash -stacks-node start --config=testnet/stacks-node/conf/mainnet-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](/img/windows-defender.png) - -Your node should start. It will take some time to sync, and then your miner will be running. - -### Enable debug logging in Windows - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=mainnet-miner-conf.toml -``` - -## Optional: Running with Docker - -Alternatively, you can run the mainnet node with Docker. - -:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: - -### Generate keychain and get tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null -``` - -We need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Update configuration file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/mainnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Start the miner - -:::info The ENV VARS `RUST_BACKTRACE` and `STACKS_LOG_DEBUG` are optional. If removed, debug logs will be disabled ::: - -```bash -docker run -d \ - --name stacks_miner \ - --rm \ - --network host \ - -e RUST_BACKTRACE="full" \ - -e STACKS_LOG_DEBUG="1" \ - -v "$(pwd)/testnet/stacks-node/conf/mainnet-miner-conf.toml:/src/stacks-node/mainnet-miner-conf.toml" \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain:latest \ -/bin/stacks-node start --config /src/stacks-node/mainnet-miner-conf.toml -``` - -You can review the node logs with this command: - -```bash -docker logs -f stacks_miner -``` - -## Optional: Running in Kubernetes with Helm - -In addition, you're also able to run a mainnet node in a Kubernetes cluster using the [stacks-blockchain Helm chart](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). - -Ensure you have the following prerequisites installed on your machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [minikube](https://minikube.sigs.k8s.io/docs/start/) (Only needed if standing up a local Kubernetes cluster) -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [helm](https://helm.sh/docs/intro/install/) - -### Generate keychain and get some tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null -``` - -We need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Install the chart and run the miner - -To install the chart with the release name `my-release` and run the node as a miner: - -```bash -minikube start # Only run this if standing up a local Kubernetes cluster -helm repo add blockstack https://charts.blockstack.xyz -helm install my-release blockstack/stacks-blockchain \ - --set config.node.miner=true \ - --set config.node.seed="replace-with-your-privateKey-from-generate-keychain-step" \ - --set config.burnchain.mode="mainnet" -``` - -You can review the node logs with this command: - -```bash -kubectl logs -l app.kubernetes.io/name=stacks-blockchain -``` - -For more information on the Helm chart and configuration options, please refer to the [chart's homepage](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md b/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md deleted file mode 100644 index 56374190c1..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md +++ /dev/null @@ -1,336 +0,0 @@ ---- -title: Mine testnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 testnet -sidebar_position: 4 -tags: - - tutorial ---- - -## Introduction - -Make sure you've followed the [Run a node](run-a-node) procedure. Once completed it's only a few more steps to run a proof-of-burn miner on the testnet. - -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining). - -## Running bitcoind locally - -To participate as a miner on Testnet, you must have access to a testnet bitcoin node. One way to accomplish this is to run bitcoind locally. [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements) - -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. - -Next, start bitcoind with the following configuration: - -```toml -server=1 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password -testnet=1 -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=1 -banscore=1 - -[test] -bind=0.0.0.0:18333 -rpcbind=0.0.0.0:18332 -rpcport=18332 -``` - -Finally, start bitcoind as follows: - -```bash -bitcoind -conf=path/to/bitcoin.conf -``` - -It may take a few hours for the node to synchronize with the Bitcoin testnet. - -## Running a miner - -First, a keychain needs to be generated. With this keychain, we'll get some testnet BTC from a faucet, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. To get a keychain, the simplest way is to use the `stacks-cli`. - -```bash -npx @stacks/cli make_keychain -t 2>/dev/null | json_pp > keychain.txt -``` - -After this runs, you should see some JSON in the new `keychain.txt` file that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -**Don't lose this information** - we'll need to use the `privateKey` field later on. - -The above BTC address will then need to be imported into the BTC testnet network. - -```bash -bitcoin-cli -rpcport=18332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - -Once imported, we need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). You'll be sent `0.01` testnet BTC to that address. - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/testnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/testnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `make_keychain` command. Replace the `seed` field with your private key. Save and close this configuration file. - -To run your miner, run this in the command line: - -```bash -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. - -### Creating an optimized binary - -The steps above are great for trying to run a node temporarily. If you want to host a node on a server somewhere, you might want to generate an optimized binary. To do so, use the same configuration as above, but run: - -```bash -cd testnet/stacks-node -cargo build --release --bin stacks-node -``` - -The above code will compile an optimized binary. To use it, run: - -```bash -cd ../.. -./target/release/stacks-node start --config=./testnet/conf/testnet-follower-conf.toml -``` - -To read more about the technical details of mining on the Stacks 2.0 network, have a look at [the minig guide](../understand-stacks/mining): - -### Enable debug logging - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -STACKS_LOG_DEBUG=1 stacks-node testnet -``` - -## Running a miner in Windows - -### Prerequisites - -Make sure are [running a testnet node](run-a-node) before starting this tutorial. - -### Generate keychain and get testnet tokens in Windows - -To setup the miner, first, we need to generate a keychain. With this keychain, we'll get some testnet BTC from a faucet, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. We'll use the `stx make-keychain` command, and pass `-t` to indicate that we want a testnet keychain. - -Generate a keychain: - -```bash -npm install --global @stacks/cli -stx make_keychain -t > cli_keychain.json -type cli_keychain.json -``` - -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -Request BTC from faucet: - -We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). - -### Update configuration file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/testnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/testnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Run the miner - -To start your miner, run this in the command line: - -```bash -stacks-node start --config=testnet/stacks-node/conf/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](/img/windows-defender.png) - - - -Your node should start. It will take some time to sync, and then your miner will be running. - -### Enable debug logging in Windows - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=testnet-miner-conf.toml -``` - -## Optional: Running with Docker - -Alternatively, you can run the testnet node with Docker. - -:::warning Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: - -### Generate keychain and get testnet tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` - -We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). - -### Update config file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/testnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/testnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Start the miner - -:::info The ENV VARS `RUST_BACKTRACE` and `STACKS_LOG_DEBUG` are optional. If removed, debug logs will be disabled ::: - -```bash -docker run -d \ - --name stacks_miner \ - --rm \ - --network host \ - -e RUST_BACKTRACE="full" \ - -e STACKS_LOG_DEBUG="1" \ - -v "$(pwd))/testnet/stacks-node/conf/testnet-miner-conf.toml:/src/stacks-node/testnet-miner-conf.toml" \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain:latest \ -/bin/stacks-node start --config /src/stacks-node/testnet-miner-conf.toml -``` - -You can review the node logs with this command: - -```bash -docker logs -f stacks_miner -``` - -## Optional: Running in Kubernetes with Helm - -In addition, you're also able to run a testnet node in a Kubernetes cluster using the [stacks-blockchain Helm chart](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). - -Ensure you have the following prerequisites installed on your machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [minikube](https://minikube.sigs.k8s.io/docs/start/) (Only needed if standing up a local Kubernetes cluster) -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [helm](https://helm.sh/docs/intro/install/) - -### Generate keychain and get some testnet tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` - -We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). - -### Install the chart and run the miner - -To install the chart with the release name `my-release` and run the node as a miner: - -```bash -minikube start # Only run this if standing up a local Kubernetes cluster -helm repo add blockstack https://charts.blockstack.xyz -helm install my-release blockstack/stacks-blockchain \ - --set config.node.miner=true \ - --set config.node.seed="replace-with-your-privateKey-from-generate-keychain-step" -``` - -You can review the node logs with this command: - -```bash -kubectl logs -l app.kubernetes.io/name=stacks-blockchain -``` - -For more information on the Helm chart and configuration options, please refer to the [chart's homepage](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md b/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md deleted file mode 100644 index 94d938c5ca..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md +++ /dev/null @@ -1,351 +0,0 @@ ---- -title: Run a node -description: Set up and run a Stacks node -sidebar_position: 1 -tags: - - tutorial ---- - -## Stacks Blockchain with Docker - -Run your own Stacks Blockchain node easily with just few commands. - -This tutorial describes a simple and effective [quickstart](#quickstart) to run a Stacks node using public scripts hosted in [Stacks Blockchain repository](https://github.com/stacks-network/stacks-blockchain-docker). Valid for mainnet, testnet and mocknet. - -## **Quickstart** - -1. **Clone the stacks-blockchain-docker repository locally** - -```bash -git clone https://github.com/stacks-network/stacks-blockchain-docker && cd stacks-blockchain-docker -``` - -2. **Optionally, create/copy `.env` file**. If file `.env` doesn't exist when launched it will be created from `sample.env` automatically. - -```bash -cp sample.env .env -``` - -_You may also use a symlink as an alternative to copying: `ln -s sample.env .env`_ - -3. **Optionally, ensure all images are up to date** - -```bash -./manage.sh -n -a pull -``` - -4. **Start the Services** - -```bash -./manage.sh -n -a start -``` - -- With optional proxy: - -```bash -./manage.sh -n -a start -f proxy -``` - -- With optional bitcoin node: - -```bash -./manage.sh -n -a start -f bitcoin -``` - -5. **Stop the Services** - -```bash -./manage.sh -n -a stop -``` - -6. **Retrieve Service Logs** - -```bash -./manage.sh -n -a logs -``` - -- Export docker log files to `./exported-logs`: - -This will create one log file for every running service, for example: postgres.log, stacks-blockain.log, stacks-blockchain-api.log and bitcoin-core.log. -Notice that each time you run this command the log files will be overwritten. - -```bash -./manage.sh -n -a logs export -``` - -7. **Restart all services** - -```bash -./manage.sh -n -a restart -``` - -- With optional proxy: - -```bash -./manage.sh -n -a restart -f proxy -``` - -8. **Delete** all data in `./persistent-data/` and/or data of the Bitcoin blockchain. - - This data is owned by root, so you will need to run it with sudo privileges so it can delete the data. - -```bash -$ sudo ./manage.sh -n -a reset - -Please confirm what persistent data you wish to delete: - -0. Cancel -1. Delete Persistent data for Stacks testnet only and leave Bitcoin blockchain data unaffected. -2. Delete Persistent data for Stacks testnet and Bitcoin blockchain data in ./persistent-data/blockchain-bitcoin -3. Delete Persistent data for Bitcoin blockchain data in ./persistent-data/blockchain-bitcoin only. -Please note that BNS data will never get deleted. - -Type 0, 1, 2 or 3: 2 - -Ok. Delete Stacks and Bitcoin data. -[ Success ] Persistent data deleted for Bitcoin blockchain. -[ Success ] Persistent data deleted for Stacks testnet. - -``` - -9. **Download BNS data to** `./persistent-data/bns-data` - -```bash -./manage.sh bns -``` - -10. **Export stacks-blockchain-api events** (_Not applicable for mocknet_) - -```bash -./manage.sh -n -a export -# check logs for completion -./manage.sh -n -a restart -``` - -11. **Replay stacks-blockchain-api events** (_Not applicable for mocknet_) - -```bash -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart -``` - -## **Running also a bitcoin node (Optional)** - -Stacks needs to use a Bitcoin node, and by default when you run a Stacks node you will be using a public Bitcoin node, which is configured in the `.env` file. Default values is `BITCOIN_NODE=bitcoin.mainnet.stacks.org`. - -However, you can optionaly run both nodes together and configured in a way that you Stacks node will use your own Bitcoin node instead of a public one. - -If you run the script with a bitcoin node it will download and build it directly from source for increased security. This process which only needs to happen once can take up to 20-30 minutes depending on the speed of your system. Also, once the bitcoin node is up and running it will need an additional time for sync for the first time (can be hours for testnet and days for mainnet). - -### Why run Stacks node with your own Bitcoin node? - -Because running your own Bitcoin node will give you higher security and improved perfomance. - -* **Improved perfomance**: The Bitcoin node will serve you blocks faster, as well as UTXOs for your miner (if you run one). -* **Higher security**: The Bitcoin node will also have validated all bitcoin transactions the Stacks node consumes. If you don't run your own Bitcoin node, you're relying on the SPV headers to vouch for the validity of Bitcoin blocks. - -The disadvantage of running your own Bitcoin node is that you need the extra space to store the Bitcoin blockchain (about 500GB) and the initial time it will take to download this data the first time. - -### Example - -You can run easily run your Stacks node with your own Bitcoin node by adding the flag `bitcoin`. This is available only for testnet and mainnet. - -Example: `./manage.sh -n mainnet -a start -f bitcoin` or `./manage.sh -n testnet -a start -f bitcoin` - -### Bitcoin node configuration - -In the `.env` file there is the variable `BITCOIN_BLOCKCHAIN_FOLDER`. As the bitcoin blockchain can be large (over 500GB) you optionally change this variable to any location of your choosing. If you have previously used the [bitcoin core application](https://bitcoin.org/en/bitcoin-core/) and already have the bitcoin blockchain synced, you can use the same data folder and avoid redownloading the entire bitcoin blockchain. - -## **Accessing the services** - -:::tip For networks other than `mocknet`, downloading the initial headers can take several minutes. Until the headers are downloaded, the `/v2/info` endpoints won't return any data. - -Use the command `./manage.sh -n -a logs` to check the sync progress. ::: - -**stacks-blockchain**: - -- Ports `20443-20444` are exposed to `localhost` - -```bash -curl -sL localhost:20443/v2/info | jq -``` - -**stacks-blockchain-api**: - -- Port `3999` are exposed to `localhost` - -```bash -curl -sL localhost:3999/v2/info | jq -``` - -**proxy**: - -- Port `80` is exposed to `localhost` - -```bash -curl -sL localhost/v2/info | jq -curl -sL localhost/ | jq -``` - ---- - -## Upgrades - -⚠️ For upgrades to running instances of this repo, you'll need to [run the event-replay](https://github.com/hirosystems/stacks-blockchain-api#event-replay): - -```bash -./manage.sh -n -a stop -./manage.sh -n -a export -./manage.sh -n -a import -./manage.sh -n -a restart -``` - ---- - -## **Workarounds to potential issues** - -_**Port(s) already in use**_: - -- 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. `3999` and edit your `.env` file to use the new port. - -```bash -netstat -anl | grep 3999 -``` - -``` -tcp46 0 0 *.3999 *.* LISTEN -``` - -_**Containers not starting (hanging on start)**_: - -- Occasionally, docker can get **stuck** and not allow new containers to start. If this happens, simply restart your docker daemon and try again. - -_**Database Issues**_: - -- For any of the various Postgres/sync issues, it may be easier to simply remove the persistent data dir. Note that doing so will result in a longer startup time as the data is repopulated. - -```bash -./manage.sh -n -a stop -./manage.sh -n -a reset -./manage.sh -n -a start -``` - -_**API Missing Parent Block Error**_: - -- If the Stacks blockchain is no longer syncing blocks, and the API reports an error similar to this:\ - `Error processing core node block message DB does not contain a parent block at height 1970 with index_hash 0x3367f1abe0ee35b10e77fbcaa00d3ca452355478068a0662ec492bb30ee0f13e"`,\ - The API (and by extension the DB) is out of sync with the blockchain. \ - The only known method to recover is to resync from genesis (**event-replay _may_ work, but in all likelihood will restore data to the same broken state**). - -- To attempt the event-replay - -```bash -./manage.sh -n -a stop -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart -``` - -- To wipe data and re-sync from genesis - -```bash -./manage.sh -n -a stop -./manage.sh -n -a reset -./manage.sh -n -a restart -``` - - -## **Requirements:** - -- [Docker](https://docs.docker.com/get-docker/) >= `17.09` -- [docker-compose](https://github.com/docker/compose/releases/) >= `1.27.4` -- [git](https://git-scm.com/downloads) -- [jq binary](https://stedolan.github.io/jq/download/) -- [sed](https://www.gnu.org/software/sed/) -- Machine with (at a minimum): - - 4GB memory - - 1 Vcpu - - 50GB storage (600GB if you optionally also run the bitcoin mainnet node) - -:::caution MacOS with an M1 processor is NOT recommended - -The way Docker for Mac on an Arm chip is designed makes the I/O incredibly slow, and blockchains are **_very_** heavy on I/O. This only seems to affect MacOS, other Arm based systems like Raspberry Pi's seem to work fine. - -::: - - -### Install/Update docker-compose - -:::note `docker-compose` executable is required, even though recent versions of Docker contain `compose` natively ::: - -- [Install Docker-compose](https://docs.docker.com/compose/install/) -- [Docker Desktop for Mac](https://docs.docker.com/docker-for-mac/install/) -- [Docker Desktop for Windows](https://docs.docker.com/docker-for-windows/install/) -- [Docker Engine for Linux](https://docs.docker.com/engine/install/#server) - -First, check if you have `docker-compose` installed locally. - -To do that, run this command in your terminal : - -```bash -docker-compose --version -``` - -Output should look something very similar to this : - -``` -docker-compose version 1.27.4, build 40524192 -``` - -If the command is not found, or the version is < `1.27.4`, run the following to install the latest to `/usr/local/bin/docker-compose`: - -```bash -#You will need to have jq installed, or this snippet won't run. -VERSION=$(curl --silent https://api.github.com/repos/docker/compose/releases/latest | jq .name -r) -DESTINATION=/usr/local/bin/docker-compose -sudo curl -L https://github.com/docker/compose/releases/download/${VERSION}/docker-compose-$(uname -s)-$(uname -m) -o $DESTINATION -sudo chmod 755 $DESTINATION -``` - -### Security note on docker - -The Docker daemon always runs as the root user so by default you will need root privileges to interact with it. - -The script `manage.sh` uses docker, so to avoid the requirement of needing to run the script with root privileges it is prefered to be able to *manage Docker as a non-root user*, following [these simple tests](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user). - -This will avoid the need of running the script with root privileges for all operations except the removal of data. - -### Configuration files you can edit - -The following files can be modified to personalize your node configuration, but generally most of them should be left as-is. All these files will be created from the sample copy if they don't exist at runtime (for example `.env` is created from `sample.env`). However these files will never be modified by the application once created and will never be pushed back to github, so your changes will be safe. - -* `.env` -* `./conf/mainnet/Config.toml` -* `./conf/mainnet/bitcoin.conf` -* `./conf/testnet/Config.toml` -* `./conf/testnet/bitcoin.conf` - -By default: - -- BNS data is **not** enabled/imported - - To enable, uncomment `# BNS_IMPORT_DIR=/bns-data` in `./env` - - Download BNS data: `./manage.sh bns` -- Fungible token metadata is **not** enabled - - To enable, uncomment `# STACKS_API_ENABLE_FT_METADATA=1` in `./env` -- Non-Fungible token metadata is **not** enabled - - To enable, uncomment `# STACKS_API_ENABLE_NFT_METADATA=1` in `./env` -- Verbose logging is **not** enabled - - To enable, uncomment `# VERBOSE=true` in `./env` -- Bitcoin blockchain folder is configured in `BITCOIN_BLOCKCHAIN_FOLDER` in `./env` - -### Local Data Dirs - -Directories will be created on first start that will store persistent data under `./persistent-data/` - -`` can be 1 of: - -- mainnet -- testnet -- mocknet diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md b/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md deleted file mode 100644 index 09db354d0d..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md +++ /dev/null @@ -1,188 +0,0 @@ ---- -title: Running a mainnet node -description: Set up and run a mainnet node with Docker -sidebar_position: 3 -tags: - - tutorial ---- - -## Introduction - -This procedure demonstrates how to run a local mainnet node using Docker images. - -:::caution -This procedure focuses on Unix-like operating systems (Linux and MacOS). This procedure has not been tested on Windows. -::: - -## Prerequisites - -Running a node has no specialized hardware requirements. Users have been successful in running nodes on Raspberry Pi boards and other system-on-chip architectures. In order to complete this procedure, you must have the following software installed on the node host machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [curl](https://curl.se/download.html) -- [jq](https://stedolan.github.io/jq/download/) - -### Firewall configuration - -In order for the API node services to work correctly, you must configure any network firewall rules to allow traffic on the ports discussed in this section. The details of network and firewall configuration are highly specific to your machine and network, so a detailed example isn't provided. - -The following ports must open on the host machine: - -Ingress: - -- stacks-blockchain (open to `0.0.0.0/0`): - - `20443 TCP` - - `20444 TCP` - -Egress: - -- `8332` -- `8333` -- `20443-20444` - -These egress ports are for syncing stacks-blockchain and Bitcoin headers. If they're not open, the sync will fail. - -## Step 1: initial setup - -In order to run the mainnet node, you must download the Docker images and create a directory structure to hold the persistent data from the services. Download and configure the Docker images with the following commands: - -```sh -docker pull blockstack/stacks-blockchain -``` - -Create a directory structure for the service data with the following command: - -```sh -mkdir -p ./stacks-node/{persistent-data/stacks-blockchain/mainnet,config/mainnet} && cd stacks-node -``` - -## Step 2: running Stacks blockchain - -First, create the `./config/mainnet/Config.toml` file and add the following content to the file using a text editor: - -```toml -[node] -working_dir = "/root/stacks-node/data" -rpc_bind = "0.0.0.0:20443" -p2p_bind = "0.0.0.0:20444" -bootstrap_node = "02da7a464ac770ae8337a343670778b93410f2f3fef6bea98dd1c3e9224459d36b@seed-0.mainnet.stacks.co:20444,02afeae522aab5f8c99a00ddf75fbcb4a641e052dd48836408d9cf437344b63516@seed-1.mainnet.stacks.co:20444,03652212ea76be0ed4cd83a25c06e57819993029a7b9999f7d63c36340b34a4e62@seed-2.mainnet.stacks.co:20444" -wait_time_for_microblocks = 10000 - -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "bitcoin.blockstack.com" -username = "blockstack" -password = "blockstacksystem" -rpc_port = 8332 -peer_port = 8333 - -[connection_options] -read_only_call_limit_write_length = 0 -read_only_call_limit_read_length = 100000 -read_only_call_limit_write_count = 0 -read_only_call_limit_read_count = 30 -read_only_call_limit_runtime = 1000000000 -``` - -Start the `stacks-blockchain` container with the following command: - -```sh -docker run -d --rm \ - --name stacks-blockchain \ - -v $(pwd)/persistent-data/stacks-blockchain/mainnet:/root/stacks-node/data \ - -v $(pwd)/config/mainnet:/src/stacks-node \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain \ -/bin/stacks-node start --config /src/stacks-node/Config.toml -``` - -You can verify the running `stacks-blockchain` container with the command: - -```sh -docker ps --filter name=stacks-blockchain -``` - -## Step 3: verifying the services - -:::note -The initial burnchain header sync can take several minutes, until this is done the following commands will not work -::: - -To verify the `stacks-blockchain` burnchain header sync progress: - -```sh -docker logs stacks-blockchain -``` - -The output should be similar to the following: - -``` -INFO [1626290705.886954] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.2% (8000 out of 691034) -INFO [1626290748.103291] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.4% (10000 out of 691034) -INFO [1626290776.956535] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.7% (12000 out of 691034) -``` - -To verify the `stacks-blockchain` tip height is progressing use the following command: - -```sh -curl -sL localhost:20443/v2/info | jq -``` - -If the instance is running you should recieve terminal output similar to the following: - -```json -{ - "peer_version": 402653184, - "pox_consensus": "89d752034e73ed10d3b97e6bcf3cff53367b4166", - "burn_block_height": 666143, - "stable_pox_consensus": "707f26d9d0d1b4c62881a093c99f9232bc74e744", - "stable_burn_block_height": 666136, - "server_version": "stacks-node 2.0.11.1.0-rc1 (master:67dccdf, release build, linux [x86_64])", - "network_id": 1, - "parent_network_id": 3652501241, - "stacks_tip_height": 61, - "stacks_tip": "e08b2fe3dce36fd6d015c2a839c8eb0885cbe29119c1e2a581f75bc5814bce6f", - "stacks_tip_consensus_hash": "ad9f4cb6155a5b4f5dcb719d0f6bee043038bc63", - "genesis_chainstate_hash": "74237aa39aa50a83de11a4f53e9d3bb7d43461d1de9873f402e5453ae60bc59b", - "unanchored_tip": "74d172df8f8934b468c5b0af2efdefe938e9848772d69bcaeffcfe1d6c6ef041", - "unanchored_seq": 0, - "exit_at_block_height": null -} -``` - -## Stopping the mainnet node - -Use the following commands to stop the local mainnet node: - -```sh -docker stop stacks-blockchain -``` - -## Optional. Run stacks node with own bitcoin node - -It's encouraged to use your own bitcoin node when possible. - -To do this simply update the `stacks-node/config/mainnet/Config.toml` file with the details of your bitcoin node. For example: - -``` -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "localhost" -username = "rpc username" -password = "rpc password" -rpc_port = 8332 -peer_port = 8333 -``` - -The rpc configuration of your bitcoin node is out of the scope of this document, but you can find more information on how to set it up [here](https://developer.bitcoin.org/examples/intro.html). - -## Additional reading - - - -- [Running a Stacks API node](https://docs.hiro.so/get-started/running-api-node) -- [Running a Stacks testnet node](running-testnet-node) - diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md b/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md deleted file mode 100644 index da01ce2ea1..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: Running a testnet node -description: Set up and run a testnet node with Docker -sidebar_position: 2 -tags: - - tutorial ---- - -## Introduction - -This procedure demonstrates how to run a local testnet node using Docker images. - -:::caution -This procedure focuses on Unix-like operating systems (Linux and MacOS). This procedure has not been tested on Windows. -::: - -## Prerequisites - -Running a node has no specialized hardware requirements. Users have been successful in running nodes on Raspberry Pi boards and other system-on-chip architectures. In order to complete this procedure, you must have the following software installed on the node host machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [curl](https://curl.se/download.html) -- [jq](https://stedolan.github.io/jq/download/) - -### Firewall configuration - -In order for the API node services to work correctly, you must configure any network firewall rules to allow traffic on the ports discussed in this section. The details of network and firewall configuration are highly specific to your machine and network, so a detailed example isn't provided. - -The following ports must open on the host machine: - -Ingress: - -- stacks-blockchain (open to `0.0.0.0/0`): - - `20443 TCP` - - `20444 TCP` - -Egress: - -- `18332` -- `18333` -- `20443-20444` - -These egress ports are for syncing stacks-blockchain and Bitcoin headers. If they're not open, the sync will fail. - -## Step 1: initial setup - -In order to run the testnet node, you must download the Docker images and create a directory structure to hold the persistent data from the services. Download and configure the Docker images with the following commands: - -```sh -docker pull blockstack/stacks-blockchain -``` - -Create a directory structure for the service data with the following command: - -```sh -mkdir -p ./stacks-node/persistent-data/stacks-blockchain/testnet && cd stacks-node -``` - -## Step 2: running Stacks blockchain - -Start the stacks-blockchain container with the following command: - -```sh -docker run -d --rm \ - --name stacks-blockchain \ - -v $(pwd)/persistent-data/stacks-blockchain/testnet:/root/stacks-node/data \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain \ -/bin/stacks-node testnet -``` - -You can verify the running stacks-blockchain container with the command: - -```sh -docker ps --filter name=stacks-blockchain -``` - -## Step 3: verifying the services - -:::info -The initial burnchain header sync can take several minutes, until this is done the following commands will not work -::: - -To verify the stacks-blockchain burnchain header sync progress: - -```sh -docker logs stacks-blockchain -``` - -The output should be similar to the following: - -``` -INFO [1626290705.886954] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.2% (8000 out of 2034380) -INFO [1626290748.103291] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.4% (10000 out of 2034380) -INFO [1626290776.956535] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.7% (12000 out of 2034380) -``` - -To verify the stacks-blockchain tip height is progressing use the following command: - -```sh -curl -sL localhost:20443/v2/info | jq -``` - -If the instance is running you should recieve terminal output similar to the following: - -```json -{ - "peer_version": 4207599105, - "pox_consensus": "12f7fa85e5099755a00b7eaecded1aa27af61748", - "burn_block_height": 2034380, - "stable_pox_consensus": "5cc4e0403ff6a1a4bd17dae9600c7c13d0b10bdf", - "stable_burn_block_height": 2034373, - "server_version": "stacks-node 2.0.11.2.0-rc1 (develop:7b6d3ee+, release build, linux [x86_64])", - "network_id": 2147483648, - "parent_network_id": 118034699, - "stacks_tip_height": 509, - "stacks_tip": "e0ee952e9891709d196080ca638ad07e6146d4c362e6afe4bb46f42d5fe584e8", - "stacks_tip_consensus_hash": "12f7fa85e5099755a00b7eaecded1aa27af61748", - "genesis_chainstate_hash": "74237aa39aa50a83de11a4f53e9d3bb7d43461d1de9873f402e5453ae60bc59b", - "unanchored_tip": "32bc86590f11504f17904ee7f5cb05bcf71a68a35f0bb3bc2d31aca726090842", - "unanchored_seq": 0, - "exit_at_block_height": null -} -``` - -## Stopping the testnet node - -Use the following commands to stop the local testnet node: - -```sh -docker stop stacks-blockchain -``` - -## Additional reading - - - -- [Running a Stacks API node](https://docs.hiro.so/get-started/running-api-node) -- [Running a Stacks mainnet node](running-mainnet-node) - diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md b/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md deleted file mode 100644 index 89af343dc6..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md +++ /dev/null @@ -1,506 +0,0 @@ ---- -title: Stacks Node Configuration -description: Configuration parameters and options for the stacks-node binary -sidebar_position: 6 ---- - -## Usage - -```bash -stacks-node sub-command [--subcommand-option ] -``` - -## Subcommands - -:::caution The `stacks-node` binary may have deprecated commands that are not documented on this page. Deprecated commands may be accessible until they are fully removed from the sources. ::: - -### mocknet - -Start a node based on a fast local setup emulating a burnchain. Ideal for smart contract development. - -Example: - -```bash -stacks-node mocknet -``` - -### krypton - -Start a node that will join and stream blocks from the public krypton regtest, powered by Blockstack via [Proof of Transfer](../understand-stacks#consensus-mechanism). - -Example: - -```bash -stacks-node krypton -``` - -### testnet - -Start a node that will join and stream blocks from the public testnet. - -Example: - -```bash -stacks-node testnet -``` - -### mainnet - -Start a node that joins and streams blocks from the public mainnet. - -Example: - -```bash -stacks-node mainnet -``` - -### start - -Start a node with a config of your own. Can be used for joining a network, starting a new chain, or replacing default values used by the `mocknet` or `testnet` subcommands. - -#### Arguments - -**--config**: relative or absolute path to the TOML config file. Required. - -Example: - -```bash -stacks-node start --config=/path/to/config.toml -``` - -See [Configuration File Options](#configuration-file-options) for more information. - -#### version - -Displays information about the current version and the release cycle. - -Example: - -```bash -stacks-node version -``` - -#### help - -Displays a help message. - -Example: - -```bash -stacks-node help -``` - -## Configuration File Options - -The TOML configuration file has multiple sections under which an option may be placed. - -To see a list of example configurations, [please see this page](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf). - -### Section: node - -Contains various configuration options pertaining to the stacks-node. - -Example: - -```toml -[node] -rpc_bind = "0.0.0.0:20443" -p2p_bind = "0.0.0.0:20444" -# Enter your private key here -seed = "replace-with-your-private-key" -miner = true -``` - -#### working_dir (optional) - -Absolute path to the directory which the stacks-node will use for storing various data. - -Example: - -```toml -working_dir = "/root/stacks-node" -``` - -#### rpc_bind - -Address and port stacks-node should bind to for RPC connections. - -Example: - -```toml -rpc_bind = "0.0.0.0:20443" -``` - -#### p2p_bind - -Address and port stacks-node should bind to for P2P connections. - -Example: - -```toml -p2p_bind = "0.0.0.0:20444" -``` - -#### data_url (optional) - -Address and port from which the stacks-node will be receiving incoming rpc connections. - -Example: - -```toml -data_url = "1.2.3.4:20443" -``` - -#### p2p_address (optional) - -Address and port from which the stacks-node will be receiving incoming p2p connections. - -Example: - -```toml -p2p_address = "1.2.3.4:20444" -``` - -#### bootstrap_node (optional) - -Public key, address, and port stacks-node should use to pull transaction data from when starting. - -Example: - -```toml -bootstrap_node = "047435c194e9b01b3d7f7a2802d6684a3af68d05bbf4ec8f17021980d777691f1d51651f7f1d566532c804da506c117bbf79ad62eea81213ba58f8808b4d9504ad@testnet.blockstack.org:20444" -``` - -#### wait_time_for_microblocks (optional) - -The amount of time (in milliseconds) that a node will wait before trying to mine a block, after catching up to the anchored chain tip. This gives the current leader time to broadcast microblocks that will get included in that mined block. - -Example: - -```toml -wait_time_for_microblocks = 15000 -``` - -#### seed (optional) - -The private key to use for mining. Only needed if `miner` is set to `true`. - -Example: - -```toml -seed = "replace-with-your-private-key" -``` - -#### local_peer_seed (optional) - -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. - -Example: - -```toml -local_peer_seed = "replace-with-your-private-key" -``` - -#### miner (optional) - -Determines whether the stacks-node is running a follower (`false`) or a miner (`true`). Defaults to `false` if omitted. - -Example: - -```toml -miner = true -``` - -#### mine_microblocks (optional) - -Determines whether the stacks-node will mine microblocks. Will only take effect if `miner` is set to `true`. - -Example: - -```toml -mine_microblocks = true -``` - -#### prometheus_bind (optional) - -Address and port stacks-node should open for Prometheus metrics collection. - -Example: - -```toml -prometheus_bind = "0.0.0.0:9153" -``` - -### Section: events_observer (optional) - -Contains options for watching events emitted by a local [stacks-blockchain-api](https://github.com/hirosystems/stacks-blockchain-api) service. - -:::info -This section can be repeated multiple times. -::: - -Example: - -```toml -[[events_observer]] -endpoint = "address-to-my-local.stacks-node-api.com:3700" -retry_count = 255 -events_keys = ["*"] -``` - -#### endpoint - -Address and port to a stacks-node-api to watch for events. - -Example: - -```toml -endpoint = "address-to-my-local.stacks-node-api.com:3700" -``` - -#### retry_count - -Number of times to retry sending events to the endpoint before failing. - -Example: - -```toml -retry_count = 255 -``` - -#### events_keys - -Event keys for which to watch. The emitted node events can be restricted by account, function name and event type. Asterix ("\*") can be used to emit all events. - -Examples: - -```toml -events_keys = ["*"] -``` - -```toml -events_keys = [ - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.store::print", - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.contract.ft-token", - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.contract.nft-token", - "stx" -] -``` - -### Section: connection_options (optional) - -Specifies configuration options for others connecting to the stacks node. - -Example: - -```toml -[connection_options] -public_ip_address = "1.2.3.4:20444" -download_interval = 60 -walk_interval = 30 -``` - -#### public_ip_address - -The advertised public IP of this stacks-node. - -Example: - -```toml -public_ip_address = "1.2.3.4:20444" -``` - -#### download_interval - -Time (in seconds) between attempts to download blocks. - -Example: - -```toml -download_interval = 60 -``` - -#### walk_interval - -Time (in seconds) between attempts to walk the neighborhood. - -Example: - -```toml -walk_interval = 30 -``` - -#### read_only_call_limit_read_length - -Total number of bytes allowed to be read by an individual read-only function call. - -Example: - -```toml -read_only_call_limit_read_length = 100000 -``` - -#### read_only_call_limit_read_count - -Total number of independent read operations permitted for an individual read-only function call. - -Example: - -```toml -read_only_call_limit_read_count = 30 -``` - -#### read_only_call_limit_runtime - -[Runtime cost](https://github.com/stacksgov/sips/blob/2d3fd9bf8da7a04f588d90ff6252173d7609d7bf/sips/sip-006/sip-006-runtime-cost-assessment.md#introduction) limit for an individual read-only function call. - -Example: - -```toml -read_only_call_limit_runtime = 1000000000 -``` - -### Section: burnchain - -This section contains configuration options pertaining to the blockchain the stacks-node binds to on the backend for proof-of-transfer (BTC). - -Example: - -```toml -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "your.bitcoind.node.org" -rpc_port = 8332 -peer_port = 8333 -``` - -#### chain - -The blockchain stacks-node binds to on the backend for proof-of-transfer. Only value supported: `"bitcoin"`. - -Example: - -```toml -chain = "bitcoin" -``` - -#### mode - -The profile or test phase of which to run stacks-node. Valid values are `"mocknet"`, `"helium"`, `"neon"`, `"argon"`, `"krypton"`, `"xenon"`. - -Example: - -```toml -mode = "xenon" -``` - -#### peer_host - -Domain name of the host running the backend Bitcoin blockchain. It's required to either run a personal Bitcoin node locally, or to use a publicly hosted Bitcoin node. - -Example: - -```toml -peer_host = "your.bitcoind.node.org" -``` - -#### rpc_port - -peer_host's port stacks-node will connect to for RPC connections. - -Example: - -```toml -rpc_port = 8332 -``` - -#### peer_port - -peer_host's port stacks-node will connect to for P2P connections. - -Example: - -```toml -peer_port = 8333 -``` - -#### burn_fee_cap (optional) - -Maximum amount (in Satoshis) of "burn commitment" to broadcast for the next block's leader election. - -Example: - -```toml -burn_fee_cap = 30000 -``` - -#### satoshis_per_byte (optional) - -Amount (in Satoshis) per [virtual byte](https://en.bitcoin.it/wiki/Weight_units). This is used to compute the transaction fees. - -Example: - -```toml -satoshis_per_byte = 50 -``` - -So total transaction cost would be `(estimated_tx_size * satoshis_per_byte) + burn_fee_cap`. - -#### commit_anchor_block_within (optional) - -Sets the time period (in milliseconds) for commitments. Only used when `mode` is set to `"helium"`. - -Example: - -```toml -commit_anchor_block_within = 10000 -``` - -### Section: ustx_balance (testnet/regtest only) - -This section contains configuration options pertaining to the genesis block allocation for an address in micro-STX. If a user changes these values, their node may be in conflict with other nodes on the network and find themselves unable to sync with other nodes. - -:::info -This section can repeat multiple times, and thus is in double-brackets. Each section can define only one address. This section is ignored if running a node on mainnet. -::: - -Example: - -```toml -[[ustx_balance]] -address = "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6" -amount = 10000000000000000 - -[[ustx_balance]] -address = "ST11NJTTKGVT6D1HY4NJRVQWMQM7TVAR091EJ8P2Y" -amount = 10000000000000000 - -[[ustx_balance]] -address = "ST1HB1T8WRNBYB0Y3T7WXZS38NKKPTBR3EG9EPJKR" -amount = 10000000000000000 - -[[ustx_balance]] -address = "STRYYQQ9M8KAF4NS7WNZQYY59X93XEKR31JP64CP" -amount = 10000000000000000 -``` - -#### address - -Address which maintains a micro-STX balance. - -Example: - -```toml -address = "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6" -``` - -#### amount - -The balance of micro-STX given to the address at the start of the node. - -Example: - -```toml -amount = 10000000000000000 -``` diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md b/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md deleted file mode 100644 index 094e3f03a1..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Verify Miner -description: Verify node is operating as miner -sidebar_position: 7 ---- - -You can verify that your node is operating as a miner by checking its log output to verify that it was able to find its Bitcoin UTXOs: - -```bash -$ head -n 100 /path/to/your/node/logs | grep -i utxo -INFO [1630127492.031042] [testnet/stacks-node/src/run_loop/neon.rs:146] [main] Miner node: checking UTXOs at address: -INFO [1630127492.062652] [testnet/stacks-node/src/run_loop/neon.rs:164] [main] UTXOs found - will run as a Miner node -``` \ No newline at end of file diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json b/i18n/ko/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json deleted file mode 100644 index f5de305558..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Noteworthy Contracts", - "position": 4, - "link": { - "type": "generated-index", - "description": "Specific deployed Clarity Contracts worth mentioning." - } -} \ No newline at end of file diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md b/i18n/ko/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md deleted file mode 100644 index 99723a9ff2..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md +++ /dev/null @@ -1,362 +0,0 @@ ---- -title: BNS Contract -description: The Blockchain Naming System. ---- - -![](/img/satoshi-btc.png) - -## Introduction - -The Blockchain Naming System (BNS) is implemented as a smart contract using Clarity. - -Below is a list of public and read-only functions as well as error codes that can be returned by those methods: -* [Public functions](#public-functions) -* [Read-only functions](#read-only-functions) -* [Error codes](#error-codes) - -## Public functions - - -### name-import - -#### Input: `(buff 20), (buff 48), principal, (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-import namespace name beneficiary zonefile-hash)` -#### Description: -Imports name to a revealed namespace. Each imported name is given both an owner and some off-chain state. - -### name-preorder - -#### Input: `(buff 20), uint` -#### Output: `(response uint int)` -#### Signature: `(name-preorder hashed-salted-fqn stx-to-burn)` -#### Description: -Preorders a name by telling all BNS nodes the salted hash of the BNS name. It pays the registration fee to the namespace owner's designated address. - -### name-register - -#### Input: `(buff 20), (buff 48), (buff 20), (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-register namespace name salt zonefile-hash)` -#### Description: -Reveals the salt and the name to all BNS nodes, and assigns the name an initial public key hash and zone file hash. - -### name-renewal - -#### Input: `(buff 20), (buff 48), uint, (optional principal), (optional (buff 20))` -#### Output: `(response bool int)` -#### Signature: `(name-renewal namespace name stx-to-burn new-owner zonefile-hash)` -#### Description: -Depending in the namespace rules, a name can expire. For example, names in the .id namespace expire after 2 years. You need to send a name renewal every so often to keep your name. - -You will pay the registration cost of your name to the namespace's designated burn address when you renew it. When a name expires, it enters a \"grace period\". The period is set to 5000 blocks (a month) but can be configured for each namespace. - -It will stop resolving in the grace period, and all of the above operations will cease to be honored by the BNS consensus rules. You may, however, send a NAME_RENEWAL during this grace period to preserve your name. After the grace period, everybody can register that name again. If your name is in a namespace where names do not expire, then you never need to use this transaction. -### name-revoke - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(name-revoke namespace name)` -#### Description: -Makes a name unresolvable. The BNS consensus rules stipulate that once a name is revoked, no one can change its public key hash or its zone file hash. The name's zone file hash is set to null to prevent it from resolving. You should only do this if your private key is compromised, or if you want to render your name unusable for whatever reason. - -### name-transfer - -#### Input: `(buff 20), (buff 48), principal, (optional (buff 20))` -#### Output: `(response bool int)` -#### Signature: `(name-transfer namespace name new-owner zonefile-hash)` -#### Description: -Changes the name's public key hash. You would send a name transfer transaction if you wanted to: -* Change your private key -* Send the name to someone else or -* Update your zone file - -When transferring a name, you have the option to also clear the name's zone file hash (i.e. set it to null). This is useful for when you send the name to someone else, so the recipient's name does not resolve to your zone file. - -### name-update - -#### Input: `(buff 20), (buff 48), (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-update namespace name zonefile-hash)` -#### Description: -Changes the name's zone file hash. You would send a name update transaction if you wanted to change the name's zone file contents. For example, you would do this if you want to deploy your own Gaia hub and want other people to read from it. - -### namespace-preorder - -#### Input: `(buff 20), uint` -#### Output: `(response uint int)` -#### Signature: `(namespace-preorder hashed-salted-namespace stx-to-burn)` -#### Description: -Registers the salted hash of the namespace with BNS nodes, and burns the requisite amount of cryptocurrency. Additionally, this step proves to the BNS nodes that user has honored the BNS consensus rules by including a recent consensus hash in the transaction. Returns pre-order's expiration date (in blocks). - -### namespace-ready - -#### Input: `(buff 20)` -#### Output: `(response bool int)` -#### Signature: `(namespace-ready namespace)` -#### Description: -Launches the namespace and makes it available to the public. Once a namespace is launched, anyone can register a name in it if they pay the appropriate amount of cryptocurrency. - -### namespace-reveal - -#### Input: `(buff 20), (buff 20), uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, principal` -#### Output: `(response bool int)` -#### Signature: `(namespace-reveal namespace namespace-salt p-func-base p-func-coeff p-func-b1 p-func-b2 p-func-b3 p-func-b4 p-func-b5 p-func-b6 p-func-b7 p-func-b8 p-func-b9 p-func-b10 p-func-b11 p-func-b12 p-func-b13 p-func-b14 p-func-b15 p-func-b16 p-func-non-alpha-discount p-func-no-vowel-discount lifetime namespace-import)` -#### Description: -Reveals the salt and the namespace ID (after a namespace preorder). It reveals how long names last in this namespace before they expire or must be renewed, and it sets a price function for the namespace that determines how cheap or expensive names its will be.All of the parameters prefixed by `p` make up the `price function`. These parameters govern the pricing and lifetime of names in the namespace. - -The rules for a namespace are as follows: - -* a name can fall into one of 16 buckets, measured by length. Bucket 16 incorporates all names at least 16 characters long. - -* the pricing structure applies a multiplicative penalty for having numeric characters, or punctuation characters. - -* the price of a name in a bucket is `((coeff) * (base) ^ (bucket exponent)) / ((numeric discount multiplier) * (punctuation discount multiplier))` - -Example: - -* base = 10 -* coeff = 2 -* nonalpha discount: 10 -* no-vowel discount: 10 -* buckets 1, 2: 9 -* buckets 3, 4, 5, 6: 8 -* buckets 7, 8, 9, 10, 11, 12, 13, 14: 7 -* buckets 15, 16+: - - -## Read-only functions - -### can-name-be-registered - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(can-name-be-registered namespace name)` -#### Description: -Returns true if the provided name can be registered. - -### can-namespace-be-registered - -#### Input: `(buff 20)` -#### Output: `(response bool UnknownType)` -#### Signature: `(can-namespace-be-registered namespace)` -#### Description: -Returns true if the provided namespace is available. - -### can-receive-name - -#### Input: `principal` -#### Output: `(response bool int)` -#### Signature: `(can-receive-name owner)` -#### Description: -Returns true if the provided name can be received. That is, if it is not curretly owned, a previous lease is expired, and the name wasn't revoked. - -### get-name-price - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response uint int)` -#### Signature: `(get-name-price namespace name)` -#### Description: -Gets the price for a name. - -### get-namespace-price - -#### Input: `(buff 20)` -#### Output: `(response uint int)` -#### Signature: `(get-namespace-price namespace)` -#### Description: -Gets the price for a namespace. - -### get-namespace-properties - -#### Input: `(buff 20)` -#### Output: `(response (tuple (namespace (buff 20)) (properties (tuple (can-update-price-function bool) (launched-at (optional uint)) (lifetime uint) (namespace-import principal) (price-function (tuple (base uint) (buckets (list 16 uint)) (coeff uint) (no-vowel-discount uint) (nonalpha-discount uint))) (revealed-at uint)))) int)` -#### Signature: `(get-namespace-properties namespace)` -#### Description: -Get namespace properties. - -### is-name-lease-expired - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(is-name-lease-expired namespace name)` -#### Description: -Return true if the provided name lease is expired. - -### name-resolve - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response (tuple (lease-ending-at (optional uint)) (lease-started-at uint) (owner principal) (zonefile-hash (buff 20))) int)` -#### Signature: `(name-resolve namespace name)` -#### Description: -Get name registration details. - -### resolve-principal - -#### Input: `principal` -#### Output: `(response (tuple (name (buff 48)) (namespace (buff 20))) (tuple (code int) (name (optional (tuple (name (buff 48)) (namespace (buff 20)))))))` -#### Signature: `(resolve-principal owner)` -#### Description: -Returns the registered name that a principal owns if there is one. A principal can only own one name at a time. - -## Error codes - -### ERR_INSUFFICIENT_FUNDS -#### type: `int` -#### value: `4001` - -### ERR_NAMESPACE_ALREADY_EXISTS -#### type: `int` -#### value: `1006` - -### ERR_NAMESPACE_ALREADY_LAUNCHED -#### type: `int` -#### value: `1014` - -### ERR_NAMESPACE_BLANK -#### type: `int` -#### value: `1013` - -### ERR_NAMESPACE_CHARSET_INVALID -#### type: `int` -#### value: `1016` - -### ERR_NAMESPACE_HASH_MALFORMED -#### type: `int` -#### value: `1015` - -### ERR_NAMESPACE_NOT_FOUND -#### type: `int` -#### value: `1005` - -### ERR_NAMESPACE_NOT_LAUNCHED -#### type: `int` -#### value: `1007` - -### ERR_NAMESPACE_OPERATION_UNAUTHORIZED -#### type: `int` -#### value: `1011` - -### ERR_NAMESPACE_PREORDER_ALREADY_EXISTS -#### type: `int` -#### value: `1003` - -### ERR_NAMESPACE_PREORDER_CLAIMABILITY_EXPIRED -#### type: `int` -#### value: `1009` - -### ERR_NAMESPACE_PREORDER_EXPIRED -#### type: `int` -#### value: `1002` - -### ERR_NAMESPACE_PREORDER_LAUNCHABILITY_EXPIRED -#### type: `int` -#### value: `1010` - -### ERR_NAMESPACE_PREORDER_NOT_FOUND -#### type: `int` -#### value: `1001` - -### ERR_NAMESPACE_PRICE_FUNCTION_INVALID -#### type: `int` -#### value: `1008` - -### ERR_NAMESPACE_STX_BURNT_INSUFFICIENT -#### type: `int` -#### value: `1012` - -### ERR_NAMESPACE_UNAVAILABLE -#### type: `int` -#### value: `1004` - -### ERR_NAME_ALREADY_CLAIMED -#### type: `int` -#### value: `2011` - -### ERR_NAME_BLANK -#### type: `int` -#### value: `2010` - -### ERR_NAME_CHARSET_INVALID -#### type: `int` -#### value: `2022` - -### ERR_NAME_CLAIMABILITY_EXPIRED -#### type: `int` -#### value: `2012` - -### ERR_NAME_COULD_NOT_BE_MINTED -#### type: `int` -#### value: `2020` - -### ERR_NAME_COULD_NOT_BE_TRANSFERED -#### type: `int` -#### value: `2021` - -### ERR_NAME_EXPIRED -#### type: `int` -#### value: `2008` - -### ERR_NAME_GRACE_PERIOD -#### type: `int` -#### value: `2009` - -### ERR_NAME_HASH_MALFORMED -#### type: `int` -#### value: `2017` - -### ERR_NAME_NOT_FOUND -#### type: `int` -#### value: `2013` - -### ERR_NAME_NOT_RESOLVABLE -#### type: `int` -#### value: `2019` - -### ERR_NAME_OPERATION_UNAUTHORIZED -#### type: `int` -#### value: `2006` - -### ERR_NAME_PREORDERED_BEFORE_NAMESPACE_LAUNCH -#### type: `int` -#### value: `2018` - -### ERR_NAME_PREORDER_ALREADY_EXISTS -#### type: `int` -#### value: `2016` - -### ERR_NAME_PREORDER_EXPIRED -#### type: `int` -#### value: `2002` - -### ERR_NAME_PREORDER_FUNDS_INSUFFICIENT -#### type: `int` -#### value: `2003` - -### ERR_NAME_PREORDER_NOT_FOUND -#### type: `int` -#### value: `2001` - -### ERR_NAME_REVOKED -#### type: `int` -#### value: `2014` - -### ERR_NAME_STX_BURNT_INSUFFICIENT -#### type: `int` -#### value: `2007` - -### ERR_NAME_TRANSFER_FAILED -#### type: `int` -#### value: `2015` - -### ERR_NAME_UNAVAILABLE -#### type: `int` -#### value: `2004` - -### ERR_PANIC -#### type: `int` -#### value: `0` - -### ERR_PRINCIPAL_ALREADY_ASSOCIATED -#### type: `int` -#### value: `3001` diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md b/i18n/ko/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md deleted file mode 100644 index ce1b1ba859..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -title: Stacking Contract -description: See a detailed list of all functions and error codes of the Stacking contract. ---- - -## Introduction - -Stacking is implemented as a smart contract using Clarity. You can always find the Stacking contract identifier using the Stacks Blockchain API [`v2/pox` endpoint](https://docs.hiro.so/api#operation/get_pox_info). - -Below is a list of public and read-only functions as well as error codes that can be returned by those methods: - -* [Public functions](#public-functions) -* [Read-only functions](#read-only-functions) -* [Error codes](#error-codes) - -## Public functions - -### allow-contract-caller -#### input: `principal, (optional uint)` -#### output: `(response bool int)` -#### signature: `(allow-contract-caller caller until-burn-ht)` -#### description: -Give a contract-caller authorization to call stacking methods. Normally, stacking methods may only be invoked by _direct_ transactions (i.e., the `tx-sender` issues a direct `contract-call` to the stacking methods). - -By issuing an allowance, the tx-sender may call through the allowed contract. - -### delegate-stack-stx -#### input: `principal, uint, (tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint` -#### output: `(response (tuple (lock-amount uint) (stacker principal) (unlock-burn-height uint)) int)` -#### signature: `(delegate-stack-stx stacker amount-ustx pox-addr start-burn-ht lock-period)` -#### description: -As a delegate, stack the given principal's STX using `partial-stacked-by-cycle`. - -Once the delegate has stacked > minimum, the delegate should call `stack-aggregation-commit`. - -### delegate-stx -#### input: `uint, principal, (optional uint), (optional (tuple (hashbytes (buff 20)) (version (buff 1))))` -#### output: `(response bool int)` -#### signature: `(delegate-stx amount-ustx delegate-to until-burn-ht pox-addr)` -#### description: -Delegate to `delegate-to` the ability to stack from a given address. - -This method _does not_ lock the funds, rather, it allows the delegate to issue the stacking lock. - -The caller specifies: - -* amount-ustx: the total amount of ustx the delegate may be allowed to lock -* until-burn-ht: an optional burn height at which this delegation expiration -* pox-addr: an optional p2pkh or p2sh address to which any rewards *must* be sent - -### disallow-contract-caller -#### input: `principal` -#### output: `(response bool int)` -#### signature: `(disallow-contract-caller caller)` -#### description: -Revokes authorization from a contract to invoke stacking methods through contract-calls - -### reject-pox -#### input: -#### output: `(response bool int)` -#### signature: `(reject-pox)` -#### description: -Reject Stacking for this reward cycle. - -`tx-sender` votes all its uSTX for rejection. - -Note that unlike Stacking, rejecting PoX does not lock the tx-sender's tokens: PoX rejection acts like a coin vote. - -### revoke-delegate-stx -#### input: -#### output: `(response bool int)` -#### signature: `(revoke-delegate-stx)` -#### description: -Revoke a Stacking delegate relationship. A particular Stacker may only have one delegate, so this method does not take any parameters, and just revokes the Stacker's current delegate (if one exists). - -### stack-aggregation-commit -#### input: `(tuple (hashbytes (buff 20)) (version (buff 1))), uint` -#### output: `(response bool int)` -#### signature: `(stack-aggregation-commit pox-addr reward-cycle)` -#### description: -Commit partially stacked STX. - -This allows a stacker/delegate to lock fewer STX than the minimal threshold in multiple transactions, - -so long as: - -1. The pox-addr is the same. -2. This \"commit\" transaction is called _before_ the PoX anchor block. - -This ensures that each entry in the reward set returned to the stacks-node is greater than the threshold, - - but does not require it be all locked up within a single transaction - -### stack-stx -#### input: `uint, (tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint` -#### output: `(response (tuple (lock-amount uint) (stacker principal) (unlock-burn-height uint)) int)` -#### signature: `(stack-stx amount-ustx pox-addr start-burn-ht lock-period)` -#### description: -Lock up some uSTX for stacking! Note that the given amount here is in micro-STX (uSTX). - -The STX will be locked for the given number of reward cycles (lock-period). - -This is the self-service interface. tx-sender will be the Stacker. - -* The given stacker cannot currently be stacking. -* You will need the minimum uSTX threshold. This isn't determined until the reward cycle begins, but this method still requires stacking over the _absolute minimum_ amount, which can be obtained by calling `get-stacking-minimum`. -* The pox-addr argument must represent a valid reward address. Right now, this must be a Bitcoin p2pkh or p2sh address. It cannot be a native Segwit address, but it may be a p2wpkh-p2sh or p2wsh-p2sh address. - -The tokens will unlock and be returned to the Stacker (tx-sender) automatically. - -## Read-only functions - -### can-stack-stx -#### input: `(tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint, uint` -#### output: `(response bool int)` -#### signature: `(can-stack-stx pox-addr amount-ustx first-reward-cycle num-cycles)` -#### description: -Evaluate if a participant can stack an amount of STX for a given period. - -### get-pox-info -#### input: -#### output: `(response (tuple (current-rejection-votes uint) (first-burnchain-block-height uint) (min-amount-ustx uint) (prepare-cycle-length uint) (rejection-fraction uint) (reward-cycle-id uint) (reward-cycle-length uint) (total-liquid-supply-ustx uint)) UnknownType)` -#### signature: `(get-pox-info)` -#### description: -Returns information about PoX status. - -### get-pox-rejection -#### input: `principal, uint` -#### output: `(optional (tuple (amount uint)))` -#### signature: `(get-pox-rejection stacker reward-cycle)` -#### description: -Returns the amount of uSTX that a given principal used to reject a PoX cycle. - -### get-stacker-info -#### input: `principal` -#### output: `(optional (tuple (amount-ustx uint) (first-reward-cycle uint) (lock-period uint) (pox-addr (tuple (hashbytes (buff 20)) (version (buff 1))))))` -#### signature: `(get-stacker-info stacker)` -#### description: -Returns the _current_ stacking information for `stacker. If the information is expired, or if there's never been such a stacker, then returns none. - -### get-stacking-minimum -#### input: -#### output: `uint` -#### signature: `(get-stacking-minimum)` -#### description: -Returns the absolute minimum amount that could be validly Stacked (the threshold to Stack in a given reward cycle may be higher than this - -### get-total-ustx-stacked -#### input: `uint` -#### output: `uint` -#### signature: `(get-total-ustx-stacked reward-cycle)` -#### description: -Returns the amount of currently participating uSTX in the given cycle. - -### is-pox-active -#### input: `uint` -#### output: `bool` -#### signature: `(is-pox-active reward-cycle)` -#### description: -Returns whether or not PoX has been rejected at a given PoX cycle. -## Error codes - -### ERR_DELEGATION_EXPIRES_DURING_LOCK -#### type: `int` -#### value: `21` - -### ERR_DELEGATION_POX_ADDR_REQUIRED -#### type: `int` -#### value: `23` - -### ERR_DELEGATION_TOO_MUCH_LOCKED -#### type: `int` -#### value: `22` - -### ERR_INVALID_START_BURN_HEIGHT -#### type: `int` -#### value: `24` - -### ERR_NOT_ALLOWED -#### type: `int` -#### value: `19` - -### ERR_STACKING_ALREADY_DELEGATED -#### type: `int` -#### value: `20` - -### ERR_STACKING_ALREADY_REJECTED -#### type: `int` -#### value: `17` - -### ERR_STACKING_ALREADY_STACKED -#### type: `int` -#### value: `3` - -### ERR_STACKING_EXPIRED -#### type: `int` -#### value: `5` - -### ERR_STACKING_INSUFFICIENT_FUNDS -#### type: `int` -#### value: `1` - -### ERR_STACKING_INVALID_AMOUNT -#### type: `int` -#### value: `18` - -### ERR_STACKING_INVALID_LOCK_PERIOD -#### type: `int` -#### value: `2` - -### ERR_STACKING_INVALID_POX_ADDRESS -#### type: `int` -#### value: `13` - -### ERR_STACKING_NO_SUCH_PRINCIPAL -#### type: `int` -#### value: `4` - -### ERR_STACKING_PERMISSION_DENIED -#### type: `int` -#### value: `9` - -### ERR_STACKING_POX_ADDRESS_IN_USE -#### type: `int` -#### value: `12` - -### ERR_STACKING_STX_LOCKED -#### type: `int` -#### value: `6` - -### ERR_STACKING_THRESHOLD_NOT_MET -#### type: `int` -#### value: `11` - -### ERR_STACKING_UNREACHABLE -#### type: `int` -#### value: `255` \ No newline at end of file diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md b/i18n/ko/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md deleted file mode 100644 index 5f38edfb57..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: xBTC -description: Wrapped BTC on Stacks ---- - -![](/img/xbtc-icon.webp) - -## Introduction - -[Wrapped.com](https://www.wrapped.com) has brought Bitcoin (xBTC) to the Stacks ecosystem. - -xBTC is backed 1:1 by Bitcoin and empowers developers to expand the Bitcoin DeFi ecosystem. - -The reserves are publicly visible [here](https://open.wrapped.com/reserves/). - -## Contract - -[SP3DX3H4FEYZJZ586MFBS25ZW3HZDMEW92260R2PR.Wrapped-Bitcoin](https://explorer.stacks.co/txid/SP3DX3H4FEYZJZ586MFBS25ZW3HZDMEW92260R2PR.Wrapped-Bitcoin?chain=mainnet) - -## Examples of uses - -[Friedger Mining Pool](https://pool.friedger.de/) currrently supports Stacking rewards payments in xBTC (optional). - - -## More information - -* [Blog post announcement](https://www.stacks.co/blog/tokensoft-wrapped-fundamental-bitcoin-defi-building-blocks-xbtc) by Muneeb Ali - -* Video: [Why xBTC is Important For Bitcoin to Grow](https://www.youtube.com/watch?v=xIoadrfSdi4) \ No newline at end of file diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/references/_category_.json b/i18n/ko/docusaurus-plugin-content-docs/current/references/_category_.json deleted file mode 100644 index 3805ab0783..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/references/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "References", - "position": 9, - "link": { - "type": "generated-index", - "description": "Stacks references." - } -} \ No newline at end of file diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/references/glossary.md b/i18n/ko/docusaurus-plugin-content-docs/current/references/glossary.md deleted file mode 100644 index f97908371a..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/references/glossary.md +++ /dev/null @@ -1,215 +0,0 @@ ---- -title: Glossary -description: A comprehensive list of terms used within the ecosystem. ---- - -A comprehensive list of terms used within the ecosystem. - -#### App Review -An incentive mechanism for application developers in the early stage (first four years) of the ecosystem and helps with bootstrapping the two-sided market. - -#### Atlas -A peer network provide a global index for discovery. - -#### Bitcoin (BTC) address -A string of letters and numbers. `3E53XjqK4Cxt71BGeP2VhpcotM8LZ853C8` Sharing this address allows anyone to send Bitcoin to the address. - -#### block -A discrete group of records written to a blockchain that can effectively be identified and referenced by the use of headers that contain a digital fingerprint of the records each block contains. - -#### blockchain -A database created and shared by the members of a peer-to-peer computer network which each member of that network can independently trust due to the rules governing the database’s creation. A blockchain can therefore be used to replace centralized databases. - -#### Blockchain Name System (BNS) -Replacement for DNS. More info [here](../noteworthy-contracts/bns-contract). - -#### Blockstack Browser -A deprecated application for accessing identity and storage. - -#### Blockstack Owner Address - -Looks like a bitcoin address but starts with `ID` for example: `ID-1J3PUxY5uDShUnHRrMyU6yKtoHEUPhKULs` - -#### Burning -Burning a token means that the token is transferred to an address that is a black hole—one that is not owned by any entity and for which guessing the applicable private key is effectively impossible based on known mathematical principles. This effectively destroys the token by making it unavailable for future use and decreases the total number of tokens available from that point forward. - -#### consensus hash -A consensus hash is a cryptographic hash that each node calculates at each block. It is derived from the accepted state transitions in the last-processed block and a geometric series of prior-calculated consensus hashes. - -#### Consensus rules -"The rules governing the creation of new valid records in a blockchain database and the mining algorithms used for this purpose. - -#### control plane -The part of a network that carries signaling traffic and is responsible for routing. Control packets originate from or are destined for a router. Functions of the control plane include system configuration and management. - -#### core node -A server that runs Stacks Blockchain services. - -#### crypto-asset -A digital asset which utilises cryptography, peer-to-peer networking and a public ledger to regulate the creation of new units, verify transactions and secure the transactions without the intervention of any middleman. - -#### cryptography -The practise and study of encryption and decryption - encoding data so that it can only be decoded by specific individuals. A system for encrypting and decrypting data is a cryptosystem. - -#### DAO -See Decentralized Autonomous Organization. - -#### decentralized application (DApp) -A DApp is a service that enables direct interaction between end users and providers (e.g. connecting buyers and sellers in some marketplace, owners and stores in file storage). A term coined by Ethereum. See their glossary: http://ethdocs.org/en/latest/glossary.html#dapp" - -#### Decentralized Autonomous Organization -A type of contract or suite of contracts on the blockchain that is intented to codify, enforce or automate the processes of an organization. - -#### digital asset -Also referred to as a crypto-asset. Any set of unique digital information—including, for example, programs, decentralized programs, isolated chunks of programming code, collections of data, e-mail or web addresses or cryptocurrency tokens—that is capable of being stored and uniquely tracked on a computer network such as the Stacks network and over which a user can maintain control through that network. - -#### digital fingerprint -A digital fingerprint is a unique number of a fixed length that can be produced by running any set of digital information through something called a cryptographic hash function. Each set of digital information (including a digital asset, and the digital record of any network operation on that digital asset) should (as a practical matter) have a unique digital fingerprint, which allows that set of digital information to be identified. However, it is almost impossible to recreate a digital asset from its digital fingerprint. The Blockstack network uses industry-standard algorithms such as SHA-256 to create digital fingerprints. - -#### digital signature -A digital signature is a sequence of digital information combining a user’s private key and any digital information that the user wishes to sign. Any other party can use the user’s paired public key to verify that the digital signature is authentic, i.e. that the public key was generated from a particular piece of digital information and the user’s private key. - -#### distributed hash tables (DHT) -A form of network used to store some content in the form of key/value pairs. ... This experimental project try to avoid keeping all the blockchain, but instead prefers to store it in a DHT. - -#### ephemeral key -A cryptographic key is called ephemeral if it is generated for each execution of a key establishment process. - -#### fork -The term fork is used to refer both to any situation where there are two or more competing versions of a blockchain on a network (a situation that may arise and resolve itself in the ordinary course of network operations due to lags in communication between core nodes) and any software update that is proposed for adoption by the core nodes of a blockchain network that may result in a persistent fork on the network, with core nodes that adopt the update recognizing one version of the blockchain and those which do not recognizing another. - -#### Gaia -Decentralized storage architecture for off-chain data. More info [here](../gaia). - -#### genesis block -The genesis block is the first block of the Stacks blockchain, which will create the initial 1.32 billion Stacks Tokens. - -#### id.blockstack -An identifier in the Blockstack, for example meepers.id.blockstack. This is your name & identity that is registered in the .id namespace on Blockstack. Your personal data and storage are built around this ID. Apps that want to access your data use your permission and identity to find it. An id is usually a shorthand for a longer, hash ID string, for example ID-1Fj9kkw15P51Fj9kkw15P5xJmyefWhLKrQMKNPREfaqsJ" - -#### identity - -A way to identify a person or an organization on the Stacks network. An identity is unique, both `meepers.id.blockstack` or `chad.id` are examples of IDs. - -#### identity management (IDM) -Identity management, also known as identity and access management is, in computer security, the security and business discipline that enables the right individuals to access the right resources at the right times and for the right reason". - -#### know your customer (KYC) -Or KYC, is a popular term used in the banking or financial field. KYC is a process where financial institutions, insurers and other companies obtain information about the identity and address of the customers as part of risk management. - -#### light clients -Clients that can independently validate the existence of transactions by downloading only block headers and not the entire blockchain. - -#### magic recovery code - -A long encrypted string, for example: `36mWivFdy0YPH2z31EflpQz/Y0UMrOrJ++lH=0EI7c3mop2JuRBm5WXxSTazJsUjOA...` Do not share the QR code that accompanied your recovery code either. This is a QR code: - -![](/img/qr-code.png) - -#### mesh network -A local network topology in which the infrastructure nodes (i.e. bridges, switches, and other infrastructure devices) connect directly, dynamically and non-hierarchically to as many other nodes as possible and cooperate with one another to efficiently route data from/to clients. - -#### mining -Mining generally refers to the process of performing certain functions for a network such as adding new records to a blockchain in exchange for mining rewards; it may also refer to other mechanisms whereby rewards (usually in the form of cryptocurrency) are provided for performing other tasks helpful to the network. - -#### mining power -A miner’s (or group of miners’) mining power is equal to the probability it will be selected to write a new block to the blockchain. Depending on the mechanism for mining, this is usually related to the overall share of computing power or cryptoassets the miner or miners possess relative to all miners for that blockchain. - -#### mining rewards -Mining rewards are newly issued tokens received by miners in exchange for adding new records to the blockchain or other activities beneficial to the network. - -#### name -An identifier or name. Names are a type of digital asset in the Stacks network. If you have signed into the Stacks Wallet, you might have created a name. If an application developer registered an application within Stacks, then they registered a name. Public Stacking pools can also have a name. - -#### network operation -A network operation is any change to the information about a digital asset (or smart contract) stored on a blockchain, including, for example, a change in the digital asset’s owner, or a change in the location at which it is stored on the network. How and when these network operations are performed for each digital asset is governed, on the Blockstack network, either by the Stacks Node software or a smart contract. - -#### NFT -Non fungible token. - -#### private key - -Private keys matches a corresponding public key. A public key also looks like a string of letters and numbers: - -![](/img/private.png) - -The exact format of the public and private key depend on the software you use to create them. - -#### proof-of-burn mining -The consensus algorithm used in the Stacks blockchain where miners destroy a proof-of-work-based cryptocurrency (currently Bitcoin) to get tokens; this enables the functionality where nodes can select between conflicting blockchain forks, as the blockchain fork with the most amount of cryptocurrency burned is considered to be the correct fork. - -#### proof-of-work -A proof-of-work system or proof-of-work mining is a mining mechanism where miners must expend computing power to solve complicated cryptographic puzzles, and prove that they have done so by writing the solution to the blockchain, in order to be allowed to add blocks to a blockchain. This is the mining system used, for example, by Bitcoin. - -#### public key -Public and private key pair comprise of two uniquely related cryptographic keys. It looks like a long random string of letters and numbers: `3048 0241 00C9 18FA CF8D EB2D EFD5 FD37 89B9 E069 EA97 FC20 …` The exact format of the public and private key depend on the software you use to create them. - -#### Public Key Infrastructure (PKI) -A system which returns a cryptographic public key associated with a name. - -#### replicated state machines (RSMs) -This is a model for reasoning about distributed computer programs -- any program (plus it's input) can be represented as a state machine, and when trying to get a distributed set of servers to agree on the output of an algorithm, you can model that process as N different state machines" - -#### Secret recovery Key, -Used to access an identity on the Stacks blockchain. A 24-word sequence of words for example: `applied binge crisp pictorial fiery` `dancing agreeable frogs light finish ping apple` - -#### seed phrase - -Used to access Stacks Wallet software. The seed phrase consists of 24 words in a sequence. Both the word *and its position the sequence* are important. Write down your seed phrase and store it in a secure location such as a safe deposit box. When you write the seed phrase down, include its position, for example,`1-frog, 2-horse, 3-building` and so on until you reach a final position `24-ocean`. -#### smart contract -A smart contract is a computer program written to a blockchain such as the Stacks blockchain by developers. This computer program defines the various network operations that can be performed on the digital assets on the blockchain, the computations that can be performed using the smart contract, along with defining various important properties of the respective digital assets like ownership rights and the cost in fuel required to register the digital assets. - -#### soft fork -A soft fork is a proposed update to the software governing the network that results in a post-update network that is compatible with the network as it existed prior to the update, because it restricts the network operations that can be performed after the update. - -#### Stacks (STX) address - - A STX address is a string of letters and numbers starting with an `SP` or `SM`, for example: `SM3KJBA4RZ7Z20KD2HBXNSXVPCR1D3CRAV6Q05MKT` If you created a software-only wallet with the Stacks Wallet software, the wallet has a single STX address which is also sometimes called the *wallet address*. You access a software wallet with a *seed phrase*. " - -#### Stacks blockchain -The Stacks blockchain is the custom blockchain being developed for use by the Stacks network that will use the Stacks token as its native currency and which will include the genesis block and subsequent blocks created by the mining activities described in the Stacks Network—Development of the Stacks network. - -#### Stacks Explorer -An application that allow you to view and search transactions in the blockchain. For example, https://explorer.stacks.co. - -#### Stacks node -A complete version of our open-source software available on Github at https://github.com/stacks-network/stacks-blockchain/ that governs the creation of the blockchain, the smart contracts that may be written to our blockchain, and other systems that make up the Stacks network, when run on the systems and devices of our users and developers. - -#### Stacks wallet -An application for accessing assets, identity and storage. Examples are the [Hiro Wallet](https://www.hiro.so/wallet), [xverse](https://www.xverse.app/) and [dcent](https://dcentwallet.com/). More information and example [here](../services-using-stacks/wallets). - -#### storage hub -A Gaia instance run by a hub provider or software. A Gaia hub stores data in a separate, addressed location. - -#### storage provider -A third-party company cloud or software provider that hosts one or more Gaia storage hubs. - -#### transaction -A transaction is a unit of work within a block. - -#### transaction fee -Fees paid by participants in a transaction to miners. - -#### two-sided market problem -Economic platforms having two distinct user groups that provide each other with network benefits. The Stacks platform is a classic two-sided market. - -#### username -A shorthand name for your id.blockstack. - -#### virtual blockchain -A layer that sits on top of a blockchain that introduces new functionality and operations without requiring changes to the underlying blockchain. - -#### wallet address -A wallet address is the form in which a public key can be presented and recorded on a blockchain. Wallet addresses are therefore used to assign the ownership of digital assets on the Blockstack network. - -#### watch-only wallet -A wallet without send and receive ability. You can view only balances and transaction history. - -#### web of trust mining -Web-of-trust mining provides incentive mechanisms for users where an initial trusted-set of unique users is curated in the genesis block and, in the future, the initial set of users can expand the web-of-trust after the network goes live. - -#### web3 -The exact definition is still under discussion, but it general refers to the 3rd generation of the web that is based on blockchain technology and incorporates decentralized and token-based economics. - -#### zone file -A Domain Name System (DNS) zone file is a text file that describes a DNS zone. A DNS zone is a subset, often a single domain, of the hierarchical domain name structure of the DNS. diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/references/nft.md b/i18n/ko/docusaurus-plugin-content-docs/current/references/nft.md deleted file mode 100644 index 033ee0a71a..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/references/nft.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: NFTs on Stacks -description: A list of sites that operate NFTs on Stacks ---- - -List of sites that operate NFTS on Stacks on alphabetical order. - -### [Byzantion](https://byzantion.xyz/) - -![website-screenshot](/img/sh_nft_byzantion.png) - -### [Gamma](https://gamma.io/) -![website-screenshot](/img/sh_nft_gamma.png) - -### [Megapont](https://www.megapont.com/) - -![website-screenshot](/img/sh_nft_megapont.png) - -### [StacksArt](https://www.stacksart.com/) - -![website-screenshot](/img/sh_nft_stacksart.png) - diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md b/i18n/ko/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md deleted file mode 100644 index dc6e507d5e..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Stacks info sites -description: A list of sites on alphabetical order that display status and stats of the Stacks network. ---- - -### [Haystack](https://haystack.tools/mempool) - -![website-screenshot](/img/sh_haystacks.png) - -### [Stacksdata](https://stacksdata.info/) - -![website-screenshot](/img/sh_stacksdata.png) - -### [Stacksonchain](https://stacksonchain.com) - -![website-screenshot](/img/sh_stacksonchain.png) - -### [Status Hiro](https://status.hiro.so/) - -![website-screenshot](/img/sh_statushiro.png) - -### [Stxstats](https://www.stxstats.co/) - -![website-screenshot](/img/sh_stxstats.png) - -### [Novuminsights](https://stacks.novuminsights.com/health) - -![website-screenshot](/img/sh_novuminsights.png) - -### [Onstacks](https://app.onstacks.com/) - -![website-screenshot](/img/sh_onstacks.png) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json b/i18n/ko/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json deleted file mode 100644 index ebd63f366c..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Services using Stacks", - "position": 8, - "link": { - "type": "generated-index", - "description": "An 'always incomplete' list of services that use Stacks." - } -} \ No newline at end of file diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md b/i18n/ko/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md deleted file mode 100644 index 51defacba7..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: DeFi -description: De-Fi sites on Stacks -sidebar_position: 2 ---- - -They are multiple De-Fi sites that operate on the Stacks blockchain. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Alex - -[Alex](https://app.alexlab.co) ![](/img/sh_alex.png) - -## Arkadiko - -[Arkadiko](https://arkadiko.finance/) ![](/img/sh_arkadiko.png) - -## Catamaran Swaps - -[Catamaran Swaps](https://www.catamaranswaps.org/) allows trustless exchange of digital assets. - -![](/img/sh_catamaran.png) - -## Lnswap - -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange - -![](/img/sh_lnswap.png) - -## Neoswap - -[Neoswap](https://neoswap.party) - -![](/img/sh_neoswap.png) - -## Stackswap - -[Stackswap](https://app.stackswap.org/v2) - -![](/img/sh_stackswap.png) - diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/services-using-stacks/more.md b/i18n/ko/docusaurus-plugin-content-docs/current/services-using-stacks/more.md deleted file mode 100644 index df0b3e2254..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/services-using-stacks/more.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: More -description: More services built on Stacks. -sidebar_position: 5 ---- - -List of sites on alphabetical order added by the community. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Citycoins - -[Citycoins](https://citycoins.co) - -![](/img/sh_citycoins.png) - -## Sigle - -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. - -![](/img/sh_sigle.png) \ No newline at end of file diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md b/i18n/ko/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md deleted file mode 100644 index bfa0505dc9..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: NFTs -description: NFTs on Stacks -sidebar_position: 3 ---- - -List of sites that operate NFTS on Stacks on alphabetical order. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -### [Byzantion](https://byzantion.xyz/) - -![website-screenshot](/img/sh_nft_byzantion.png) - -### [Gamma](https://gamma.io/) -![website-screenshot](/img/sh_nft_gamma.png) - -### [Megapont](https://www.megapont.com/) - -![website-screenshot](/img/sh_nft_megapont.png) - -### [StacksArt](https://www.stacksart.com/) - -![website-screenshot](/img/sh_nft_stacksart.png) - -### [Superfandom](https://superfandom.io/) - -![website-screenshot](/img/sh_superfandom.png) \ No newline at end of file diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/services-using-stacks/other.md b/i18n/ko/docusaurus-plugin-content-docs/current/services-using-stacks/other.md deleted file mode 100644 index 199fc41da5..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/services-using-stacks/other.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Other Stacks sites -description: A list of sites on alphabetical order built on Stacks. -sidebar_position: 4 ---- - -List of sites on alphabetical order added by the community. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Alex -[Alex](https://app.alexlab.co) - -## Sigle - -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. \ No newline at end of file diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md b/i18n/ko/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md deleted file mode 100644 index 35ced8dac6..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Stacks info sites -description: Status and stats of the Stacks network. -sidebar_position: 1 ---- - -A list of sites on alphabetical order that display status and stats of the Stacks network. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -### [Haystack](https://haystack.tools/mempool) - -![website-screenshot](/img/sh_haystacks.png) - -### [Stacksdata](https://stacksdata.info/) - -![website-screenshot](/img/sh_stacksdata.png) - -### [Stacksonchain](https://stacksonchain.com) - -![website-screenshot](/img/sh_stacksonchain.png) - -### [Status Hiro](https://status.hiro.so/) - -![website-screenshot](/img/sh_statushiro.png) - -### [Stxstats](https://www.stxstats.co/) - -![website-screenshot](/img/sh_stxstats.png) - -### [Novuminsights](https://stacks.novuminsights.com/health) - -![website-screenshot](/img/sh_novuminsights.png) - -### [Onstacks](https://app.onstacks.com/) - -![website-screenshot](/img/sh_onstacks.png) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md b/i18n/ko/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md deleted file mode 100644 index d4b4cbf18c..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Swaps -description: A list of sites that allow Swaps -sidebar_position: 2 ---- - -They are multiple sites that allow you to make swaps using the Stacks blockchain. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Catamaran Swaps - -[Catamaran Swaps](https://www.catamaranswaps.org/) allows trustless exchange of digital assets. - -![](/img/sh_catamaran.png) - -## Lnswap - -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange - -![](/img/sh_lnswap.png) - -## Neoswap - -[Neoswap](https://neoswap.party) - -![](/img/sh_neoswap.png) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md b/i18n/ko/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md deleted file mode 100644 index e5ea6c5b45..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Wallets -description: Wallets for Stacks -sidebar_position: 4 ---- - -A list of hardware and software wallets for Stacks - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Blockchain.com - -[Blockchain.com](https://www.blockchain.com/wallet) - -![](/img/sh_blockchain.png) -## Boom - -[Boom](https://boom.money) - -![](/img/sh_boom.png) - -## Dcent wallet - -[D'CENT](https://dcentwallet.com) - -![](/img/sh_dcent.png) -## Hiro Wallet - -[Hiro Wallet](https://www.hiro.so/wallet) - -![](/img/sh_hirowallet.png) - -## Neptune - -[Neptune](https://neptunewallet.io) - -![](/img/sh_neptunewallet.png) - -## Xverse - -[Xverse](https://www.xverse.app/) - -![](/img/sh_xverse.png) - -## Wise - -[Wise](https://wiseapp.id) - -![](/img/sh_wiseapp.png) \ No newline at end of file diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md b/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md deleted file mode 100644 index bd2c361985..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md +++ /dev/null @@ -1,214 +0,0 @@ ---- -title: Accounts -description: Guide to Stacks 2.0 accounts -sidebar_position: 5 ---- - -## Introduction - -Stacks 2.0 accounts are entities that own assets, like Stacks (STX) tokens. An account has an address, private key, nonce, and one or more asset balances. - -:::tip The encryption algorithm used in Stacks 2.0 is **[secp256k1](https://en.bitcoinwiki.org/wiki/Secp256k1)**. - -Additionally, [Ed25519](https://ed25519.cr.yp.to/) is also used just for the VRF (Verifiable Random Function). ::: - -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. - -:::tip -The transaction type doesn't need to be a token transfer - contract deploy and contract call transactions can change the balances of an account -::: - -## Creation - -An account is generated from a 24-word mnemonic phrase. This is often referred to as the **seed phrase**. The seed phrase provides access to Stacks 2.0 accounts. - -:::danger -If the seed phrase is lost, access to the associated account cannot be restored. No person or organization, including Blockstack, can recover a lost seed phrase. -::: - -The easiest way to generate a new Stacks 2.0 account is to use the [Stacks CLI](https://github.com/hirosystems/stacks.js/tree/master/packages/cli): - -```bash -# install CLI globally -npm install --global @stacks/cli - -# generate a new account and store details in a new file -# '-t' option makes this a testnet account -stx make_keychain -t > cli_keychain.json -``` - -`make_keychain` creates the following file: - -```js -{ - "mnemonic": "aaa bbb ccc ddd ...", - "keyInfo": { - "privateKey": "5a3f1f15245bb3fb...", - "address": "STJRM2AMVF90ER6G3RW1QTF85E3HZH37006D5ER1", - "btcAddress": "biwSd6KTEvJcyX2R8oyfgj5REuLzczMYC1", - "wif": "L4HXn7PLmzoNW...", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -| Field | Description | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `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.privateKey` | Private key for the account. Required for token transfers and often referred to as `senderKey` | -| `keyInfo.address` | Stacks address for the account | -| `keyInfo.btcAddress` | Corresponding BTC address for the account. | -| `keyInfo.wif` | Private key of the btcAddress in compressed format. | -| `keyInfo.index` | Nonce for the account, starting at 0 | - -Note that a new account automatically exists for each new private key. There is no need to manually instantiate an account on the Stacks 2.0 blockchain. - -:::tip Addresses are created by generating the [RIPEMD-160 hash](https://en.wikipedia.org/wiki/RIPEMD#RIPEMD-160_hashes) of the [SHA256](https://en.bitcoinwiki.org/wiki/SHA-256) of the public key. BTC addresses are encoded with [Base58Check](https://en.bitcoin.it/wiki/Base58Check_encoding). For Stacks addresses, [c32check](https://github.com/stacks-network/c32check) is used. Deriving an address from a public key can be done without internet access, for instance using the c32check `c32addressDecode` method. ::: - -Alternatively to the CLI creation, the [Stacks Transactions JS](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library can be used: - -```js -import { - makeRandomPrivKey, - privateKeyToString, - getAddressFromPrivateKey, - TransactionVersion, -} from '@stacks/transactions'; - -const privateKey = makeRandomPrivKey(); - -// Get public key from private -const publicKey = getPublicKey(privateKey); - -const stacksAddress = getAddressFromPrivateKey( - privateKeyToString(privateKey), - TransactionVersion.Testnet // remove for Mainnet addresses -); -``` - -A second alternative would be to use [stacks-gen](https://github.com/psq/stacks-gen). This tool will generate all the keys you need in one place, including the values needed for calling the stacking contract, and also a WIF key for use with `bitcoind`. - -#### stacks-gen prerequisite - -Install [npx](https://github.com/npm/npx) if not already installed. (npx will check whether `` exists in \$PATH, or in the local project binaries, and execute that. If `` is not found, it will be installed prior to execution). - -``` -npm install -g npx -``` - -#### stacks-gen usage - -``` -npx -q stacks-gen sk --testnet - -{ - "phrase": "guide air pet hat friend anchor harvest dog depart matter deny awkward sign almost speak short dragon rare private fame depart elevator snake chef", - "private": "0351764dc07ee1ad038ff49c0e020799f0a350dd0769017ea09460e150a6401901", - "public": "022d82baea2d041ac281bebafab11571f45db4f163a9e3f8640b1c804a4ac6f662", - "stacks": "ST16JQQNQXVNGR8RZ1D52TMH5MFHTXVPHRV6YE19C", - "stacking": "{ hashbytes: 0x4d2bdeb7eeeb0c231f0b4a2d5225a3e3aeeed1c6, version: 0x00 }", - "btc": "mnYzsxxW271GkmyMnRfiopEkaEpeqLtDy8", - "wif": "cMh9kwaCEttgTQYkyMUYQVbdm5ZarZdBHErcq7mXUChXXCo7CFEh" -} -``` - -:::tip The stacking object with hashbytes and a version represents the bitcoin address derived from the Stacks address. Read more about the [bitcoin address format](stacking#bitcoin-address). ::: - -Full documentation available at [stacks-gen](https://github.com/psq/stacks-gen). - -## Querying - -### Get Stacks (STX) balance and nonce - -STX balance and nonce can be obtained through the [`GET /v2/accounts/`](https://docs.hiro.so/api#operation/get_account_info) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/accounts/' -``` - -Sample response: - -```js -{ - "balance": "0x0000000000000000002386f26f3f40ec", - "nonce": 17 -} -``` - -:::tip -The balance string represents an unsigned 128-bit integer (big-endian) in hex encoding -::: - -### Get all token balances - -All token balances can be obtained through the [`GET /extended/v1/address//balances`](https://docs.hiro.so/api#operation/get_account_balance) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/address//balances' -``` - -Sample response: - -```js -{ - "stx": { - "balance": "0", - "total_sent": "0", - "total_received": "0" - }, - "fungible_tokens": {}, - "non_fungible_tokens": {} -} -``` - -:::tip Stacks accounts cannot hold bitcoins. The best way to obtain corresponding BTC balances is to derive the BTC address from the Stacks address (using [`c32check`](https://github.com/stacks-network/c32check#c32tob58-b58toc32)) and query the Bitcoin network. ::: - -### Get all asset events - -All asset events associated with the account can be obtained through the [`GET /extended/v1/address//assets`](https://docs.hiro.so/api#operation/get_account_balance) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/address//assets' -``` - -Sample response: - -```js -{ - "limit": 20, - "offset": 0, - "total": 0, - "results": [ - { - "event_index": 5, - "event_type": "non_fungible_token_asset", - "asset": { - "asset_event_type": "transfer", - "asset_id": "ST2W14YX9SFVDB1ZGHSH40CX1YQAP9XKRAYSSVYAG.hello_world::hello-nft", - "sender": "SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR", - "recipient": "SM2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQVX8X0G", - "value": { - "hex": "0x0100000000000000000000000000000001", - "repr": "u1" - } - } - }, - { - "event_index": 3, - "event_type": "fungible_token_asset", - "asset": { - "asset_event_type": "mint", - "asset_id": "ST2W14YX9SFVDB1ZGHSH40CX1YQAP9XKRAYSSVYAG.hello_world::novel-token-19", - "sender": "", - "recipient": "SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR", - "amount": "12" - } - } - ] -} -``` diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/index.md b/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/index.md deleted file mode 100644 index 1533219df9..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/index.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Understand Stacks -description: Learn more about the Stacks 2.0 blockchain -sidebar_position: 1 ---- - -![](/img/SBC-L-2x-10.png) -## Introduction - -Stacks 2.0 is a layer-1 blockchain that connects to Bitcoin and brings smart contracts and decentralized apps to it. Smart contracts and apps developed on the Stacks platform are natively integrated with the security, stability, and economic power of Bitcoin. - -## Capabilities - -Read more about the features provided by the Stacks 2.0 blockchain. - - - -:::tip Check out the [technical specifications](technical-specs) for a brief overview ::: - - - - -A detailed [comparison of the Stacks blockchain to other blockchain technologies][] is available at the Stacks Foundation blog. -### Consensus mechanism -![](/img/pages/stacking.svg) Stacks 2.0 implements a new mining mechanism called Proof of Transfer ("PoX"). PoX is a consensus algorithm between two blockchains. It uses an established blockchain (in this case Bitcoin) to secure a new blockchain (Stacks). - -PoX connects to Bitcoin with a 1:1 block ratio, meaning anything that happens on the Stacks blockchain can be verified on the Bitcoin Blockchain. - -Instead of burning electricity on proof of work, PoX reuses already minted bitcoins as "proof of computation" and miners represent their cost of mining in bitcoins directly. - - -[Read more about Proof of Transfer](proof-of-transfer) -### Mining - -![](/img/pages/testnet-sm.svg) Mining is required to make the network usable, trustworthy, and secure. Miners verify incoming transactions, participate in the consensus mechanism, and write new blocks to the blockchain. - -To incentivize mining, miners receive freshly minted Stacks (STX) tokens if they win the bid for becoming the leader of the next round. - -[Read more about Mining](mining) - -### Stacking - -Bitcoins used for miner bids are sent to a set of specific addresses corresponding to Stacks (STX) tokens holders that are actively participating in consensus ("Stackers"). Thus, rather than being destroyed, the bitcoins consumed in the mining process go to productive Stacks holders as a reward based on their holdings of Stacks and participation in the Stacking algorithm. - -Stackers have to lock up their Stacks (STX) tokens for a certain period of time. - -[Read more about Stacking](stacking) - -### Smart contracts - -![](/img/pages/write-smart-contracts-sm.svg) Clarity is a new language for smart contracts on the Stacks 2.0 blockchain. The Clarity smart contract language optimizes for predictability and security. - -Stacks 2.0 anchors clarity smart contracts to Bitcoin making it possible for smart contracts to operate based on actions seen on the bitcoin blockchain. - -:::note The [Clarity open-source project](https://clarity-lang.org/) is supported by Stacks and [Algorand](https://www.algorand.com/) ::: - - -Clarity is distinct from other languages designed for writing smart contracts in a few ways: - -- **Predictability**: The Clarity language uses precise and unambiguous syntax that allows developers to predict exactly how their contracts will be executed. -- **Security**: The Clarity language allows users to supply their own conditions for transactions that ensure that a contract may never unexpectedly transfer a token owned by a user. -- **No compiler**: Contracts written in Clarity are broadcasted on the Stacks blockchain exactly as they are written by developers. This ensures that the code developers wrote, analyzed, and tested, is exactly what gets executed. - -[Read more about Clarity](../write-smart-contracts/clarity-language/) - -## Guides - -Read one of our guides to understand the ins and outs of the Stacks 2.0 blockchain. - -* [Account](../understand-stacks/accounts) -* [Transactions](../understand-stacks/transactions) -* [Network](../understand-stacks/network) -* [Microblocks](../understand-stacks/microblocks) - -[comparison of the Stacks blockchain to other blockchain technologies]: https://stacks.org/stacks-blockchain diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md b/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md deleted file mode 100644 index de64c617f4..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: Microblocks -description: Guide to Stacks Microblocks -sidebar_position: 8 ---- - -## Introduction - -Microblocks are a protocol-level feature of the Stacks blockchain that solve the technical challenge of transaction latency. Because each Stacks block is anchored to a Bitcoin block through the [Proof-of-Transfer consensus mechanism](../understand-stacks/proof-of-transfer), Stacks is necessarily limited to the same block times as the Bitcoin network. Microblocks allow the Stacks blockchain to perform state transitions between anchor blocks. - -Microblocks are a powerful mechanism for developers to create performant, high quality applications on Stacks, while still inheriting the security of Bitcoin. - -## Transaction states - -The [Stacks block production model](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.) is described in SIP-001. The standard outlines the mechanism by which elected block leaders can produce blocks on the Stacks blockchain either by batching transactions or by streaming them. Microblocks are the product of the streaming model. - -If a block leader has elected to mine microblocks, the leader selects transactions from the mempool and package them into microblocks during the current epoch. Microblocks are blocks of transactions included by a miner after the previous anchor block has been mined, but before the next block is selected. Transactions included in microblocks are processed by the network: their results are known. - -Consider a transaction from the perspective of the number of block confirmations it has. A transaction included in a microblock might have the following example lifecycle: - -``` -Transaction 1 is broadcast to the mempool. It has 0 confirmations. -Transaction 1 is included in a microblock. It still has 0 confirmations, but the results of the transaction are known -Transaction 1 is included in the next anchor block. It has 1 confirmation. -The next Stacks block confirms the previous block. Transaction 1 has 2 confirmations. -The next Stacks block confirms the previous block. Transaction 1 has 3 confirmations. -... -``` - -Consider a similar transaction that is not included in a microblock: - -``` -Transaction 2 is broadcast to the mempool. It has 0 confirmations. -Transaction 2 is included in the next anchor block. It has 1 confirmation. -The next Stacks block confirms the previous block. Transaction 2 has 2 confirmations. -The next Stacks block confirms the previous block. Transaction 2 has 3 confirmations. -``` - -The lifecycles of the two transactions are similar, but the difference is pending state. Many Bitcoin wallets display 0-confirmation balances: your wallet balance with any mempool transactions already applied. This is useful because it tells you when you've sent a transaction or received one. With smart contracts, displaying pending state is not as straightforward, because smart contracts do not just transfer inputs to outputs, they may call other contracts, emit events, or perform other computations. A transaction processed in a microblock generates all that information. - -:::tip -If a transaction is dependent on a chain state that could by altered by previous transactions with serious -implications, you should carefully consider whether it should be performed using microblocks. -::: - -## Enabling microblocks - -Miners can choose to enable or disable microblocks in their mining configuration. As a best practice, miners should enable microblock mining. When an application or user submits a transaction, the transaction can include an argument that requires the transaction to be in a microblock, an anchor block, or in either. - -### Transactions - -Transactions include an option that controls if a miner should include them in microblocks or in anchor blocks. The anchor mode transaction option is an optional argument that controls whether a transaction must be included in an anchor block or a microblock, or is eligible for either. - -### Mining - -Stacks miners must enable microblocks in their miner configuration to implement the block streaming model. For more information, see [mining microblocks](../understand-stacks/mining#microblocks). - -## Developing with microblocks - -In most cases, information from transactions included in microblocks should be treated like information from any other block. Wallets and explorers should display the consequences of microblock transactions as the current state of the network. This state should be acknowledged as tentative. - -A microblock transaction can end up being reorganized in the next block rather than just being confirmed as-is. Because of this, your UI should communicate to users if the outputs of a transaction changed, or if the transaction's associated block changed. This is the same outcome as if a 1-block fork occurred. - -### Stacks.js libraries - -Stacks.js provides the [AnchorMode][] argument on transaction objects so that your application can set the microblocks preference for transactions. - -### API - -:::danger API support for microblocks is a work-in-progress. Review the [API documentation][microblocks_api] carefully to ensure that you are up-to-date on the latest implementation details for microblocks. ::: - -The Stacks Blockchain API exposes microblocks through several endpoints. Please review the [Stacks Blockchain API guide][] for more details. - -## Best practices - -Working with microblocks is a design decision that you must make for your own application. When working with microblocks, the following best practices are recommended. - -### Handling nonce - -Nonce handling with microblocks is challenging because the next account nonce must take into account any nonce values included in microblocks, which may not yet be included in an anchor block. The Stacks Blockchain API [provides an endpoint][] to retrieve the next nonce for a given principal. - -### Application design - -The state of microblock transactions should be carefully communicated to users. No transaction is final until it's included in an anchor block, and your application design should reflect this. - -The following guidelines are provided as an initial set of best practices for UI design when incorporating microblocks into your application. - -#### Explorers - -Display pending state, but warn that a transaction is still pending. Indicate visually that displayed balances depend on pending state. - -#### Wallets - -Display pending state, but warn that a transaction is still pending. Indicate visually that displayed balances depend on pending state. - -#### Exchanges - -Continue to count confirmations, microblocks should be considered pending. - -#### Applications - -Microblock communication is highly app-dependent. For some applications, displaying a pending or 0-confirmation transaction as confirmed may be fine. For example, storing data on the chain, or querying the BNS contract. For other applications, such as the transfer of real value, waiting for 3-confirmations would be prudent before displaying the state as confirmed. - -[AnchorMode]: https://stacks.js.org/enums/transactions.AnchorMode.html -[Stacks Blockchain API guide]: https://docs.hiro.so/get-started/stacks-blockchain-api#microblocks-support -[provides an endpoint]: https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling -[microblocks_api]: https://docs.hiro.so/api#tag/Microblocks diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/mining.md b/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/mining.md deleted file mode 100644 index fa1f56ed3f..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/mining.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Mining -description: A guide to mining on Stacks 2.0 -sidebar_position: 4 ---- - -## Introduction - -This guide highlights some technical details related to mining on the Stacks 2.0 network. - -For steps on how to setup your own miner please refer to [miner on tesnet](nodes-and-miners/miner-testnet.md) and [miner on mainnet](nodes-and-miners/miner-testnet.md). - -## Mining frequency - -A new Stacks block may be mined once per Bitcoin block. To be considered for mining a block, a miner must have a block commit included in a Bitcoin block. If a miner wishes to update their commitment after submission, they may use Bitcoin Replace-By-Fee. - -## Coinbase rewards - -Miners receive coinbase rewards for blocks they win. - -The reward amounts are: - -- 1000 STX per block are released in the first 4 years of mining -- 500 STX per block are released during the following 4 years -- 250 STX per block are released during the following 4 years -- 125 STX per block are released from then on indefinitely. - -These "halvings" are synchronized with Bitcoin halvings. - -![coinbase rewards](/img/pages/coinbase-rewards.png) - -## Transaction fees - -Miners receive Stacks fees for transactions mined in any block they produce. - -For transactions mined in microblocks, the miner that produces the microblock receives 40% of the fees, while the miner that confirms the microblock receives 60% of the fees. - -## Reward maturity - -Block rewards and transaction fees take 100 blocks on the Bitcoin blockchain to mature. After successfully mining a block your rewards appear in your Stacks account after ~24 hours. - -## Mining with proof-of-transfer - -Miners commit Bitcoin to **two** addresses in every leader block commit. The amount committed to each address must be the same. The addresses are chosen from the current reward set of stacking participants. Addresses are chosen using a verifiable-random-function, and determining the correct two addresses for a given block requires monitoring the Stacks chain. - -![mining with pox](/img/pages/mining-with-pox.png) - -## 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, 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. - -While there is no minimum BTC commitment enforced by the protocol, in practice, there's a floor constrained by [dust](https://unchained-capital.com/blog/dust-thermodynamics/)": basically, if the fees for a transaction exceed the value of the spent output, it's considered dust. How dust is [calculated](https://github.com/bitcoin/bitcoin/blob/master/src/policy/policy.cpp#L14) depends on a number of factors, we've found 5,500 satoshis to be good lower bound per [output](https://learnmeabitcoin.com/technical/output). Bitcoin transactions from Stacks miners contain two outputs (for Proof-of-Transfer), so a commitment of at least 11,000 satoshis / block is recommended. - -To calculate the amount of BTC to send miners should: - -- Guess the price BTC/STX for the next day (100 blocks later) -- Guess the total amount of BTCs committed by all miners - -## Microblocks - -The Stacks blockchain produces blocks at the same rate as the Bitcoin blockchain. In order to provide lower latency transactions, miners can opt to enable microblocks. Microblocks allow the current block leader to stream transactions and include their state transitions in the current epoch. - -If a block leader opts to produce microblocks, the next leader builds the chain tip off the last microblock that the current leader produces. - -The block streaming model is described in [SIP-001][]. - -[SIP-001]: https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md#operation-as-a-leader diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/network.md b/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/network.md deleted file mode 100644 index 6efcc385ec..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/network.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: Network -description: Guide to the Stacks 2.0 network -sidebar_position: 7 ---- - -## Tokens - -Stacks (STX) tokens are the native tokens on the Stacks 2.0 blockchain. The smallest fraction is one micro-STX. 1,000,000 micro-STX make one Stacks (STX). - -STX amounts should be stored as integers (8 bytes long), and represent the amount of micro-STX. For display purposes, micro-STX are divided by 1,000,000 (decimal precision of 6). - -## 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 in bytes. The fee rate is a market determined variable. For the [testnet](testnet), it is set to 1 micro-STX. - -Fee estimates can obtained through the [`GET /v2/fees/transfer`](https://docs.hiro.so/api#operation/get_fee_transfer) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/fees/transfer' -``` - -The API will respond with the fee rate (as integer): - -```json -1 -``` - -[The Stacks Transactions JS library](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) supports fee estimation for: - -- token transfers (`estimateTransfer`) -- contract deploys (`estimateContractDeploy`) -- non read-only contract calls (`estimateContractFunctionCall`) - -:::tip For an implementation using a different language than JavaScript, please review [this reference implementation](https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/src/builders.ts#L97). ::: - -## Nonces - -Every account carries a [nonce property](https://en.wikipedia.org/wiki/Cryptographic_nonce) that indicates the number of transactions processed for the given account. Nonces are one-time codes, starting at `0` for new accounts, and incremented by 1 on every transaction. - -Nonces are added to all transactions and help identify them in order to ensure transactions are processed in order and to avoid duplicated processing. - -:::tip -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 is constructed, the most recent nonce of the account needs to fetched and set. - -:::tip The API provides an endpoint to [simplify nonce handling](https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling). ::: - -## Confirmations - -The Stacks 2.0 network is anchored onto the bitcoin network. This allows transactions on Stacks to inherit the same finality and security of the Bitcoin blockchain. - -The time to mine a block, to confirm transactions, will eventually match the expected "block time" of the bitcoin network: 10 minutes. - -:::tip Transactions can also be mined in [microblocks](microblocks), reducing the latency significantly. ::: - -The block time is hardcoded and will change throughout the implementation phases of the [testnet](testnet). The current block time can be obtained through the [`GET /extended/v1/info/network_block_times`](https://docs.hiro.so/api#operation/get_network_block_times) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/info/network_block_times' -``` - -The API will respond with the block time (in seconds): - -```js -{ - "testnet": { - "target_block_time": 120 - }, - "mainnet": { - "target_block_time": 600 - } -} -``` - -## Read-only function calls - -Smart contracts can expose public function calls. For functions that make state modifications to the blockchain, transactions need to be generated and broadcasted. - -However, for read-only function calls, transactions are **not** required. Instead, these calls can be done using the [Stacks Blockchain API](https://docs.hiro.so/get-started/stacks-blockchain-api). - -:::tip -Read-only function calls do not require transaction fees -::: - -A read-only contract call can be done using the [`POST /v2/contracts/call-read///`](https://docs.hiro.so/api#operation/call_read_only_function) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl --location --request POST 'https://stacks-node-api.testnet.stacks.co/v2/contracts/call-read///' \ ---header 'Content-Type: application/json' \ ---data-raw '{ - "sender": ".", - "arguments": [, ...] -}' -``` - -Sample response for a successful call: - -```js -{ - "okay": true, - "result": "" -} -``` - -:::tip To set the function call arguments and read the result, [Clarity values](../write-smart-contracts/values) need to be serialized into a hexadecimal string. The [Stacks Transactions JS](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library supports these operations ::: - -## Querying - -Stacks 2.0 network details can be queried using the [Stacks Blockchain API](https://docs.hiro.so/get-started/stacks-blockchain-api). - -### Health check - -The [status checker](https://stacks-status.com/) is a service that provides a user interface to quickly review the health of the Stacks 2.0 blockchain. - -### Network info - -The network information can be obtained using the [`GET /v2/info`](https://docs.hiro.so/api#operation/get_core_api_info) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/info' -``` - -Sample response: - -```js -{ - "peer_version": 385875968, - "burn_consensus": "826401d65cf3671210a3fb135d827d549c0b4d37", - "burn_block_height": 1972, - "stable_burn_consensus": "e27ea23f199076bc41a729d76a813e125b725f64", - "stable_burn_block_height": 1971, - "server_version": "blockstack-core 0.0.1 => 23.0.0.0 (master:bdd042242+, release build, linux [x86_64]", - "network_id": 2147483648, - "parent_network_id": 3669344250, - "stacks_tip_height": 933, - "stacks_tip": "1f601823fbcc5b6b2215b2ff59d2818fba61ee4a3cea426d8bc3dbb268005d8f", - "stacks_tip_burn_block": "54c56a9685545c45accf42b5dcb2787c97eda8185a1c794daf9b5a59d4807abc", - "unanchored_tip": "71948ee211dac3b241eb65d881637f649d0d49ac08ee4a41c29217d3026d7aae", - "exit_at_block_height": 28160 -} -``` diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md b/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md deleted file mode 100644 index c933f7af68..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Proof of Transfer -description: Understand the proof-of-transfer consensus mechanism -sidebar_position: 3 ---- - -## Overview - -Consensus algorithms for blockchains require compute or financial resources to secure the blockchain. The general practice of decentralized consensus is to make it practically infeasible for any single malicious actor to have enough computing power or ownership stake to attack the network. - -Popular consensus mechanisms in modern blockchains include proof-of-work, in which nodes dedicate computing resources, and proof-of-stake, in which nodes dedicate financial resources to secure the network. - -Proof-of-burn is a novel consensus mechanism where miners compete by ‘burning’ (destroying) a proof-of-work cryptocurrency as a proxy for computing resources. - -Proof-of-transfer (PoX) is an extension of the proof-of-burn mechanism. 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. - -![PoX mechanism](/img/pox-mechanism.png) - -This allows network participants to secure the PoX cryptocurrency network and earn a reward in the base cryptocurrency. Thus, proof-of-transfer blockchains are anchored on their chosen proof-of-work chain. Stacks uses [Bitcoin](#why-bitcoin) as its anchor chain. - -![PoX participants](/img/pox-participants.png) - -## Why Bitcoin? - -There are a number of reasons that Stacks chose Bitcoin as the blockchain to power consensus. It's the oldest blockchain protocol, having launched in 2009, and has become a recognized asset outside of the cryptocurrency community. BTC has held the highest market capitalization of any cryptocurrency for the past decade. - -Bitcoin champions simplicity and stability, and has stood the test of time. Influencing or attacking the network is infeasible or impractical for any potential hackers. It's one of the only cryptocurrencies to capture public attention. Bitcoin is a household name, and is recognized as an asset by governments, large corporations, and legacy banking institutions. Lastly, Bitcoin is largely considered a reliable store of value, and provides extensive infrastructure to support the proof-of-transfer consensus mechanism. - -SIP-001 provides a full [list of reasons why Bitcoin was chosen to secure Stacks](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md). - -![btc-stacks](/img/pox-why-bitcoin.png) - -## Blocks and microblocks - -The Stacks blockchain allows for increased transaction throughput using a mechanism called microblocks. Bitcoin and Stacks progress in lockstep, and their blocks are confirmed simultaneously. On Stacks, this is referred to as an ‘anchor block’. An entire block of Stacks transactions corresponds to a single Bitcoin transaction. This significantly improves cost/byte ratio for processing Stacks transactions. Because of simultaneous block production, Bitcoin acts as a rate-limiter for creating Stacks blocks, thereby preventing denial-of-service attacks on its peer network. - -However, in between Stacks anchor blocks settling on the Bitcoin blockchain, there are also a varying number of microblocks that allow rapid settlement of Stacks transactions with a high degree of confidence. This allows Stacks transaction throughput to scale independently of Bitcoin, while still periodically establishing finality with the Bitcoin chain. The Stacks blockchain adopts a block streaming model whereby each leader can adaptively select and package transactions into their block as they arrive in the mempool. Therefore when an anchor block is confirmed, all of the transactions in the parent microblock stream are packaged and processed. This is an unprecedented method for achieving scalability without creating a totally separate protocol from Bitcoin. - -![stx-microblock](/img/stx-microblocks.png) - -## Unlocking Bitcoin capital - -Stacks also unlocks the hundreds of billions in capital in Bitcoin, and gives Bitcoiners new opportunities to use and earn BTC. Stacks is a accompaniment to the Bitcoin ecosystem, and the two networks working in tandem enables totally novel ways of using BTC. The Stacks ecosystem makes interactive cryptocurrency applications available to Bitcoin holders. Additionally, By stacking STX tokens and participating in the PoX consensus mechanism, users have the opportunity to earn BTC while securing the Stacks chain. - -![Unlocking Bitcoin](/img/pox-unlocking-btc.png) - -## Clarity and the Bitcoin state - -Clarity smart contracts also have unique visibility into the state of the Bitcoin blockchain. This means that contract logic in a Clarity file has the ability to trigger when specific Bitcoin transactions are confirmed. Clarity smart contracts have a built in Simple Payment Verification (SPV) proofs for Bitcoin that make interacting with Bitcoin’s state much simpler for developers. Additionally, Clarity contracts can fork with the original Bitcoin chain. Therefore, in an edge case where Bitcoin forks, developers wouldn’t have to worry about adjusting the deployment of their smart contracts. - -## See also - -- [Read the full PoX whitepaper](https://community.stacks.org/pox) -- [Watch Executive Chair of Hiro Muneeb Ali and Evangelist Joe Bender give an overview of Stack's breakthrough PoX mining mechanism](https://www.youtube.com/watch?v=NY_eUrIcWOY) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md b/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md deleted file mode 100644 index 5f3863e8dd..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: Stacking -description: Introduction to the reward mechanism of Proof-of-Transfer -sidebar_position: 9 ---- - -## Introduction - -Stacking rewards Stacks (STX) token holders with bitcoin for providing a valuable service to the network by locking up their tokens for a certain time. - -![](/img/stacking.png) - -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. - -:::info The Stacking consensus algorithm is implemented as a smart contract, using [Clarity](../write-smart-contracts/). [Read more about the contract](../noteworthy-contracts/stacking-contract). ::: - -## Stacking flow - -The Stacking mechanism can be presented as a flow of actions: - -![Stacking flow](/img/stacking-illustration.png) - -1. Make API calls to get details about the upcoming reward cycle -2. For a specific Stacks account, confirm eligibility -3. Confirm the BTC reward address and the lockup duration -4. The transaction is broadcasted and the STX tokens are locked. This needs to happen before the prepare phase of the next reward cycle, the last 100 Bitcoin blocks of the ongoing reward phase -5. The Stacking mechanism executes reward cycles and sends out rewards to the set BTC reward address -6. During the lockup period, details about unlocking timing, rewards and more can be obtained -7. Once the lockup period is passed, the tokens are released and accessible again -8. Display reward history, including details like earnings for previous reward cycles - -:::info Keep in mind that the target duration for a reward cycles is ~2 weeks. This duration is based on the target block time of the network (10 minutes) and can be higher at times due to [confirmation time variances](https://www.blockchain.com/charts/median-confirmation-time) of the bitcoin network. ::: - -## Stacking delegation flow - -The Stacking flow is different for delegation use cases: - -![Delegated tacking flow](/img/stacking-delegation-illustration.png) - -- Before Stacking can be initiated for a token holder, the delegator needs to be granted permission to Stack on behalf of the account owner. The permission is restricted to the maximum amount the delegator is allowed to Stack. The maximum amount is not limited by the available funds and can be set much higher. An account can only be associated with one single delegator -- The account has to define the delegation relationship. They can optionally restrict the Bitcoin reward address that must be used for payouts, and the expiration burn block height for the permission, thus limiting the time a delegator has permission to Stack -- Delegators have to lock Stacks from different accounts ("pooling phase") until they reach the minimum amount of Stacks required to participate in Stacking -- Once a delegator locks enough STX tokens, they can finalize and commit their participation in the next reward cycle -- Certain delegation relationships may allow the STX holder to receive the payout directly from the miner (step 5/6) -- The termination of the delegation relationship can either happen automatically based on set expiration rules or by actively revoking delegation rights - -## PoX mining - -PoX mining is a modification of Proof-of-Burn (PoB) mining, where instead of sending the committed Bitcoin to a burn address, it's transferred to eligible STX holders that participate in the stacking protocol. - -:::note -A PoX miner can only receive newly minted STX tokens when they transfer Bitcoin to eligible owners of STX tokens -::: - -![Mining flow](/img/pox-mining-flow.png) - -Miners run Stacks nodes with mining enabled to participate in the PoX mechanism. The node implements the PoX mechanism, which ensures proper handling and incentives through four key phases: - -- Registration: miners register for a future election by sending consensus data to the network -- Commitment: registered miners transfer Bitcoin to participate in the election. Committed BTC are sent to a set participating STX token holders -- Election: a verifiable random function chooses one miner to write a new block on the Stacks blockchain -- Assembly: the elected miner writes the new block and collects rewards in form of new STX tokens - -## Token holder eligibility - -Stacks (STX) token holders don't automatically receive stacking rewards. Instead, they must: - -- Commit to participation before a reward cycle begins -- Commit the minimum amount of STX tokens to secure a reward slot, or pool with others to reach the minimum -- Lock up STX tokens for a specified period -- Provide a supported Bitcoin address to receive rewards (native segwit is not supported) - -The following diagram describes how the minimum STX tokens per slot is determined. More information on [dynamic minimums for stacking](https://stacking.club) is available at stacking.club. - -![Dynamic minimum for individual eligibility](/img/stacking-dynamic-minimum.png) - -Token holders have a variety of providers and tools to support their participation in Stacking. The Stacks website contains a [list of stacking providers and pools](https://stacks.org/stacking#earn). - -## Stacking in the PoX consensus algorithm - -Stacking is a built-in capability of PoX and occurs through a set of actions on the Stacks blockchain. The [full proof-of-transfer implementation details](https://github.com/stacks-network/stacks-blockchain/blob/develop/sip/sip-007-stacking-consensus.md) are in SIP-007. Below is a summary of the most relevant actions of the algorithm. - -![PoX cycles](/img/pox-cycles.png) - -- Stacking happens over reward cycles with a fixed length. In each reward cycle, a set of Bitcoin addresses associated with stacking participants receive BTC rewards -- A reward cycle consists of two phases: prepare and reward -- During the prepare phase, miners decide on an anchor block and a reward set. Mining any descendant forks of the anchor block requires transferring mining funds to the appropriate reward addresses. The reward set is the set of Bitcoin addresses which are eligible to receive funds in the reward cycle -- Miners register as leader candidates for a future election by sending a key transaction that burns cryptocurrency. The transaction also registers the leader's preferred chain tip (must be a descendant of the anchor block) and commitment of funds to 2 addresses from the reward set -- Token holders register for the next rewards cycle by broadcasting a signed message that locks up associated STX tokens for a protocol-specified lockup period, specifies a Bitcoin address to receive the funds, and votes on a Stacks chain tip -- Multiple leaders can commit to the same chain tip. The leader that wins the election and the peers who also burn for that leader collectively share the reward, proportional to how much each one burned -- Token holders' locked up tokens automatically unlock as soon as the lockup period finishes - -## Bitcoin address - -:::danger You must provide a BTC address in one of two formats: - -* [Legacy (P2PKH)](https://en.bitcoin.it/wiki/Transaction#Pay-to-PubkeyHash), which starts with `1`. - -* [Segregated Witness / Segwit (P2SH)](https://en.bitcoin.it/wiki/Pay_to_script_hash), which starts with `3`. The "Native Segwit" format (which starts with `bc1`), for example, is not supported. ::: - -The Stacking contract needs a special format for the Bitcoin address (the reward address). This is required to ensure that miners are able to correctly construct the Bitcoin transaction containing the reward address. - -The address must be specified in the following format using the Clarity language: - -```clar -;; a tuple of a version and hashbytes buffer -(pox-addr (tuple (version (buff 1)) (hashbytes (buff 20)))) -``` - -The `version` buffer must represent what kind of bitcoin address is being submitted. It can be one of the following: - -```js -SerializeP2PKH = 0x00, // hash160(public-key), same as bitcoin's p2pkh -SerializeP2SH = 0x01, // hash160(multisig-redeem-script), same as bitcoin's multisig p2sh -SerializeP2WPKH = 0x02, // hash160(segwit-program-00(p2pkh)), same as bitcoin's p2sh-p2wpkh -SerializeP2WSH = 0x03, // hash160(segwit-program-00(public-keys)), same as bitcoin's p2sh-p2wsh -``` - -The `hashbytes` are the 20 hash bytes of the bitcoin address. You can obtain that from a bitcoin library, for instance using [`bitcoinjs-lib`](https://github.com/bitcoinjs/bitcoinjs-lib): - -```js -const btc = require('bitcoinjs-lib'); -console.log( - '0x' + btc.address.fromBase58Check('1C56LYirKa3PFXFsvhSESgDy2acEHVAEt6').hash.toString('hex') -); -``` - -## Choosing the right Stacking strategy - -[Here](https://blog.stacks.co/stacking-strategy) is an interesting article that may help you choose the right Stacking stategy. - - -## Where to Stacks? - -You can Stack on your own, on a pool or on an exchange: -### Stacking on your own - -Stacking on your own is non-custodial. - -Stacking on your own requires a protocol minimum (amount changes but about 100,000 STX). - -[Hiro Wallet](https://www.hiro.so/wallet) allows stacking on your own. - -### Stacking on a pool - -Stacking on a pool allows Stacking without the requirement of the protocol minumum. - -Some available pools are: - -| Pool | Type | Pays rewards in | Fee | Minimum amount | -| --------------------------------------------------- | ------------- |:---------------:| --- |:--------------:| -| [Friedger's Pool](https://pool.friedger.de/) | Non custodial | STX or xBTC | No | 40 STX | -| [Planbetter](https://planbetter.org/) | Non custodial | BTC | 5% | 200 STX | -| [Stacked](https://staking.staked.us/stacks-staking) | Non custodial | BTC | | 100,000 STX | -| [Xverse](https://www.xverse.app/) | Non custodial | BTC | No | 100 STX | - -### Stacking on an exchange - -Stacking on an exchange is custodial, meaning you are trusting the exchange with your Stacks. - -Several exchanges allow Stacking directly on their sites. Examples are [Okcoin](https://www.okcoin.com) and [Binance](https://www.binance.com/en/staking) - -## Stacking statistics - -You can view all sorts of Stacking data and statistics on [Stacking Club](https://stacking.club) \ No newline at end of file diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md b/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md deleted file mode 100644 index d942d6af8f..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Stacks Blockchain API -description: Interacting with the Stacks 2.0 Blockchain via API ---- - -## Temporal page because of a Crowdin bug \ No newline at end of file diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md b/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md deleted file mode 100644 index e370129d1d..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Technical Specifications -description: Summary of technical specifications of Stacks 2.0 -sidebar_position: 10 ---- - -## Consensus - -- Proof of Transfer (PoX) as described in [SIP-007](https://github.com/stacksgov/sips/blob/main/sips/sip-007/sip-007-stacking-consensus.md) -- Network will transition to Proof of Burn (PoB) as described in [SIP-001](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md) after 10 years. [Learn more about Proof-of-Burn in SIP-001](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md). -- Threat model - - 51% of malicious Stacks mining power can perform a double-spend attack - - 51% of malicious Bitcoin mining power can reorg the Stacks chain -- Different actors and their roles - - Stacks Miners package transactions into blocks, mine them through a Bitcoin transaction, propagate them, and if they win the block race, append microblocks to their winning block until the next block is mined. The next block confirms the microblock stream. - - Stacks Holders may alter the calculation of block limits (subject to a miner veto) and may vote to disable Proof-of-Transfer rewards for a reward cycle. -- Transactions are considered final when the corresponding "block commit" transaction on Bitcoin is finalized. Typically this can by 3-6 confirmations. -- For more details, see [Proof of Transfer](proof-of-transfer). - -## Proof of Transfer Mining - -- Coinbase reward schedule: - - 1000 STX/block for first 4 years - - 500 STX/block for following 4 years - - 250 STX/block for subsequent 4 years - - 125 STX/block in perpetuity after that -- Coinbase rewards accumulate for "missed sortitions": If a Bitcoin block has no sortition (at height N), then any Stacks block mined in a subsequent sortition that builds off of any Stacks chain tip that existed at the penultimate sortition (at height N-1) may claim its coinbase. This encourages miners to keep mining even if Bitcoin fees are high. -- Initial mining bonus: This is a special case of the above to incentivize early miners. Coinbase for all burnchain blocks between the first burn block height (to be chosen by independent miners as part of the Stacks 2.0 launch) and the first sortition winner accumulate and are distributed to miners over a fixed window (to be determined). For instance, say burn block height is 10,000 and first sortition is at block 10500 and distribution window is 100 blocks, then coinbase for the first 500 blocks (10,500 - 10,000) will be distributed evenly to miners who win sortition over the subsequent 100 blocks. -- 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 at least 11,000 satoshis (5,500 sats / [UTXO output](https://learnmeabitcoin.com/technical/utxo)); 2 outputs / block) to avoid "dust." -- For more details, see [Mining](mining). - -## Stacking - -- Stacking works in 2 phases - 1. Prepare phase: In this phase an "anchor block" is chosen. The qualifying set of addresses ("reward set") is determined based on the snapshot of the chain at the anchor block. Length of prepare phase is 100 blocks. Stacking commitments need to be confirmed before this phase starts - 2. Reward phase: In this phase miner BTC commitments are distributed amongst the reward set. Reward cycle length is 2000 BTC blocks (~2 weeks). -- 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/stacksgov/sips/blob/main/sips/sip-007/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.stacks.co/references/stacking-contract#delegate-stx). -- Only two types of BTC reward addresses are supported: [Legacy (P2PKH)](https://en.bitcoin.it/wiki/Transaction#Pay-to-PubkeyHash) or [Segregated Witness / Segwit (P2SH)](https://en.bitcoin.it/wiki/Pay_to_script_hash). Native Segwit is not supported. -- Further reading: [Stacking](stacking) - -## Accounts and Addresses - -- Transactions in the Stacks blockchain originate from, are paid for by, and execute under the authority of accounts -- An account is fully specified by its address + nonce + assets -- 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 (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](accounts) - -## Transactions - -- Transaction 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 - 2. _paying account_ is the account that is billed by the leader for the cost of validating and executing the transaction - 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 -- Transactions can be batched or streamed into blocks. The behavior can be controlled by the anchor mode of a transaction. With streaming ([microblocks](microblocks)), a faster confirmation time is possible. -- 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. -- Mempool limit for concurrent pending transactions is 25 per account -- Pending mempool transactions will be garbage-collected [256 blocks after receipt](https://github.com/stacks-network/stacks-blockchain/blob/master/src/core/mempool.rs#L62). With 10 minutes target block time, this would equal ~42 hours -- [Learn more about transaction encoding in SIP-005](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md#transaction-encoding) -- [Transaction signing and verification are described in SIP-005](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md#transaction-signing-and-verifying) -- All transactions impacting account balance are atomic, a transfer operation can not increment one account’s balance without decrementing another’s. However, transactions that perform multiple account actions (for example, transferring from multiple accounts) may partially complete. -- Transactions can include a memo string (max 34 bytes) - -## See also - -- [Read the full Stacks 2.0: Apps and Smart Contracts for Bitcoin whitepaper](https://cloudflare-ipfs.com/ipfs/QmaGgiVHymeDjAc3aF1AwyhiFFwN97pme5m536cHT4FsAW). - -- [Watch Aaron Blankstein video on Stacks whitepater v2](https://www.youtube.com/watch?v=Wd-Bfe8Sn-Y). \ No newline at end of file diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md b/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md deleted file mode 100644 index 59934a5bde..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Testnet -description: Test your smart contracts and apps -sidebar_position: 2 ---- - -## About testnet - -The testnet is a separate blockchain from the Stacks mainnet analogous to a staging environment. It's a network used by developers to test their apps, smart contracts, or changes to the protocol in a production-like environment. It produces blocks at roughly the same rate as mainnet; about 1 block every 10 minutes on average. The Stacks testnet is rarely reset. - -### Faucet - -The testnet faucet provides you with free Stacks Token (STX) to test with. These are not the same as STX on mainnet and have no value. You can get STX from the faucet on the [Stacks Explorer Sandbox](https://explorer.stacks.co/sandbox/faucet?chain=testnet), or using the [API](https://docs.hiro.so/api#tag/Faucets). - -To get STX tokens from within the Explorer Sandbox, navigate to the "Faucet" tab on the left and click "Request STX" button. - -![](/img/stx_faucet.png) - -You can also try out [Stacking](stacking) by clicking on `I want to stack`. - -:::note -The Explorer Sandbox requires you to login with a Stacks wallet -::: - -### Testnet API - -The hosted Stacks Blockchain API for the testnet is available at this base URL: - -```shell -https://stacks-node-api.testnet.stacks.co/ -``` - -![](/img/api_testnet_status.png) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md b/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md deleted file mode 100644 index 2ff6072384..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Transactions -description: Guide to Stacks 2.0 transactions -sidebar_position: 6 ---- - -## Introduction - -Transactions are the fundamental unit of execution in the Stacks blockchain. Each transaction is originated from a [Stacks 2.0 account](accounts), and is retained in the Stacks blockchain history for eternity. This guide helps you understand Stacks 2.0 transactions. - -## Lifecycle - -Transactions go through phases before being finally confirmed, and available for all, on the Stacks 2.0 network. - -![Transaction lifecycle](/img/tx-lifecycle.png) - -- **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/en/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. - -:::note A transaction can have one of three states once it is registered: `pending`, `success`, or `failed`. ::: - -## Types - -The Stacks 2.0 supports a set of different transaction types: - -| **Type** | **Value** | **Description** | -| ----------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Coinbase | `coinbase` | The first transaction in a new block (an entity holding several transactions). Used to register for block rewards. These are not manually generated and broadcasted like other types of transactions. | -| Token transfer | `token_transfer` | Asset transfer from a sender to a recipient | -| Contract deploy | `smart_contract` | Contract instantiation | -| Contract call | `contract_call` | Contract call for a public, non read-only function | -| Poison Microblock | `poison_microblock` | Punish leaders who intentionally equivocate about the microblocks they package | - -A sample of each transaction type can be found in the [Stacks Blockchain API response definition for transactions](https://docs.hiro.so/api#operation/get_transaction_by_id). - -:::caution Read-only contract call calls do **not** require transactions. Read more about it in the [network guide](network#read-only-function-calls). ::: diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md b/i18n/ko/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md deleted file mode 100644 index fd45c80583..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Clarity Language -description: Overview of the Clarity language constructs -sidebar_label: Clarity Language -tags: - - clarity ---- - -## Clarity Type System - -The Clarity language uses a strong static type system. Function arguments and database schemas require specified types, and use of types is checked during contract launch. The type system does _not_ have a universal super type. - -## Public Functions - -Functions specified via `define-public` statements are _public_ functions and these are the only types of functions which may be called directly through signed blockchain transactions. In addition to being callable directly from a transaction (see the Stacks wire formats for more details on Stacks transactions), public functions may be called by other smart contracts. - -Public functions _must_ return a `(response ...)` type. This is used by Clarity to determine whether or not to materialize any changes from the execution of the function. If a function returns an `(err ...)` type, any mutations on the blockchain state from executing the function (and any function that it called during execution) will be aborted. - -In addition to functions defined via `define-public`, contracts may expose read-only functions. These functions, defined via `define-read-only`, are callable by other smart contracts, and may be queryable via public blockchain explorers. These functions _may not_ mutate any blockchain state. Unlike normal public functions, read-only functions may return any type. - -## Contract Calls - -A smart contract may call functions from other smart contracts using a `(contract-call?)` function. - -This function returns a response type result -- the return value of the called smart contract function. - -We distinguish 2 different types of `contract-call?`: - -### Static dispatch - -The callee is a known, invariant contract available on-chain when the caller contract is deployed. In this case, the callee's principal is provided as the first argument, followed by the name of the method and its arguments: - -```clarity -(contract-call? - .registrar - register-name - name-to-register) -``` - -### Dynamic dispatch - -The callee is passed as an argument, and typed as a trait reference (``). - -```clarity -(define-public (swap (token-a ) - (amount-a uint) - (owner-a principal) - (token-b ) - (amount-b uint) - (owner-b principal))) - (begin - (unwrap! (contract-call? token-a transfer-from? owner-a owner-b amount-a)) - (unwrap! (contract-call? token-b transfer-from? owner-b owner-a amount-b)))) -``` - -Traits can either be locally defined: - -```clarity -(define-trait can-transfer-tokens ( - (transfer-from? (principal principal uint) (response uint))) -``` - -Or imported from an existing contract: - -```clarity -(use-trait can-transfer-tokens - .contract-defining-trait.can-transfer-tokens) -``` - -Looking at trait conformance, callee contracts have two different paths. They can either be "compatible" with a trait by defining methods matching some of the methods defined in a trait, or explicitly declare conformance using the `impl-trait` statement: - -```clarity -(impl-trait .contract-defining-trait.can-transfer-tokens) -``` - -Explicit conformance should be prefered when adequate. It acts as a safeguard by helping the static analysis system to detect deviations in method signatures before contract deployment. - -The following limitations are imposed on contract calls: - -1. On static dispatches, callee smart contracts _must_ exist at the time of creation. -2. No cycles may exist in the call graph of a smart contract. This prevents recursion (and re-entrancy bugs). Such structures can be detected with static analysis of the call graph, and will be rejected by the network. -3. `contract-call?` are for inter-contract calls only. Attempts to execute when the caller is also the callee will abort the transaction. diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md b/i18n/ko/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md deleted file mode 100644 index a6011cca8b..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md +++ /dev/null @@ -1,1388 +0,0 @@ ---- -title: Functions -description: See a detailed list of all functions for the Clarity language. -tags: - - clarity ---- - -## Functions - -Detailed list of all functions for the Clarity language. - -### + (add) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(+ i1 i2...)` -#### description: -Adds a variable number of integer inputs and returns the result. In the event of an _overflow_, throws a runtime error. -#### example: -```clarity -(+ 1 2 3) ;; Returns 6 -(+ 2 3) ;; Returns 5 -(+ 1 2 3 4) ;; Returns 10 -(+ 9 -3) ;; Returns 6 -(+ -3 -2) ;; Returns -5 -``` - -### - (subtract) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(- i1 i2...)` -#### description: -Subtracts a variable number of integer inputs and returns the result. In the event of an _underflow_, throws a runtime error. -#### example: -```clarity -(- 2 1 1) ;; Returns 0 -(- 0 3) ;; Returns -3 -(- 5 -3) ;; Returns 8 -(- -4 -5) ;; Returns 1 -``` - -### * (multiply) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(* i1 i2...)` -#### description: -Multiplies a variable number of integer inputs and returns the result. In the event of an _overflow_, throws a runtime error. -#### example: -```clarity -(* 2 3) ;; Returns 6 -(* 5 2) ;; Returns 10 -(* 2 2 2) ;; Returns 8 -(* 3 -2) ;; Returns -6 -(* -1 -2) ;; Returns 2 -``` - -### / (divide) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(/ i1 i2...)` -#### description: -Divides a variable number of integer inputs and returns the _integer part_ of the result. In the event of _division by zero_, throws a runtime error. - -#### example: -```clarity -(/ 2 3) ;; Returns 0 -(/ 5 2) ;; Returns 2 -(/ 4 2 2) ;; Returns 1 -(/ -10 2) ;; Returns -5 -(/ -8 -2) ;; Returns 4 -(/ -9 4) ;; Returns -2 -``` - -### >= (greater than or equal) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(>= i1 i2)` -#### description: -Compares two integers, returning `true` if `i1` is greater than or equal to `i2` and `false` otherwise. -#### example: -```clarity -(>= 1 1) ;; Returns true -(>= 5 2) ;; Returns true -``` - -### <= (less than or equal) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(<= i1 i2)` -#### description: -Compares two integers, returning true if `i1` is less than or equal to `i2` and `false` otherwise. -#### example: -```clarity -(<= 1 1) ;; Returns true -(<= 5 2) ;; Returns false -``` - -### < (less than) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(< i1 i2)` -#### description: -Compares two integers, returning `true` if `i1` is less than `i2` and `false` otherwise. -#### example: -```clarity -(< 1 2) ;; Returns true -(< 5 2) ;; Returns false -``` - -### > (greater than) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(> i1 i2)` -#### description: -Compares two integers, returning `true` if `i1` is greater than `i2` and false otherwise. -#### example: -```clarity -(> 1 2) ;; Returns false -(> 5 2) ;; Returns true -``` - -### to-int -#### input: `uint` -#### output: `int` -#### signature: `(to-int u)` -#### description: -Tries to convert the `uint` argument to an `int`. Will cause a runtime error and abort if the supplied argument is >= `pow(2, 127)`` -#### example: -```clarity -(to-int u238) ;; Returns 238 -``` - -### to-uint -#### input: `int` -#### output: `uint` -#### signature: `(to-uint i)` -#### description: -Tries to convert the `int` argument to a `uint`. Will cause a runtime error and abort if the supplied argument is negative. -#### example: -```clarity -(to-uint 238) ;; Returns u238 -``` - -### mod -#### input: `int, int | uint, uint` -#### output: `int | uint` -#### signature: `(mod i1 i2)` -#### description: -Returns the integer remainder from integer dividing `i1` by `i2`. In the event of a division by zero, throws a runtime error. -#### example: -```clarity -(mod 2 3) ;; Returns 2 -(mod 5 2) ;; Returns 1 -(mod 7 1) ;; Returns 0 -``` - -### pow -#### input: `int, int | uint, uint` -#### output: `int | uint` -#### signature: `(pow i1 i2)` -#### description: -Returns the result of raising `i1` to the power of `i2`. In the event of an _overflow_, throws a runtime error. -#### example: -```clarity -(pow 2 3) ;; Returns 8 -(pow 2 2) ;; Returns 4 -(pow 7 1) ;; Returns 7 -``` - -### sqrti -#### input: `int | uint` -#### output: `int | uint` -#### signature: `(sqrti n)` -#### description: -Returns the largest integer that is less than or equal to the square root of `n`. Fails on a negative numbers. -#### example: -```clarity -(sqrti u11) ;; Returns u3 -(sqrti 1000000) ;; Returns 1000 -(sqrti u1) ;; Returns u1 -(sqrti 0) ;; Returns 0 -``` - -### log2 -#### input: `int | uint` -#### output: `int | uint` -#### signature: `(log2 n)` -#### description: -Returns the _integer part_ of the power to which the number 2 must be raised to obtain the value `n`. Fails on zero or a negative number. -#### example: -```clarity -(log2 u8) ;; Returns u3 -(log2 8) ;; Returns 3 -(log2 u1) ;; Returns u0 -(log2 1000) ;; Returns 9 -``` - -### xor -#### input: `int, int | uint, uint` -#### output: `int | uint` -#### signature: `(xor i1 i2)` -#### description: -Returns the result of bitwise exclusive or'ing `i1` with `i2`. -#### example: -```clarity -(xor 1 2) ;; Returns 3 -(xor 120 280) ;; Returns 352 -``` - -### and -#### input: `bool, ...` -#### output: `bool` -#### signature: `(and b1 b2 ...)` -#### description: -Returns `true` if all boolean inputs are `true`. Importantly, the supplied arguments are evaluated in-order and lazily. Lazy evaluation means that if one of the arguments returns `false`, the function short-circuits, and no subsequent arguments are evaluated. -#### example: -```clarity -(and true false) ;; Returns false -(and (is-eq (+ 1 2) 1) (is-eq 4 4)) ;; Returns false -(and (is-eq (+ 1 2) 3) (is-eq 4 4)) ;; Returns true -``` - -### or -#### input: `bool, ...` -#### output: `bool` -#### signature: `(or b1 b2 ...)` -#### description: -Returns `true` if any boolean inputs are `true`. Importantly, the supplied arguments are evaluated in-order and lazily. Importantly, the supplied arguments are evaluated in-order and lazily. -#### example: -```clarity -(or true false) ;; Returns true -(or (is-eq (+ 1 2) 1) (is-eq 4 4)) ;; Returns true -(or (is-eq (+ 1 2) 1) (is-eq 3 4)) ;; Returns false -(or (is-eq (+ 1 2) 3) (is-eq 4 4)) ;; Returns true -``` - -### not -#### input: `bool` -#### output: `bool` -#### signature: `(not b1)` -#### description: -Returns the inverse of the boolean input. -#### example: -```clarity -(not true) ;; Returns false -(not (is-eq 1 2)) ;; Returns true -``` - -### is-eq -#### input: `A, A, ...` -#### output: `bool` -#### signature: `(is-eq v1 v2...)` -#### description: -Compares the inputted values, returning `true` if they are all equal. Note that _unlike_ the `(and ...)` function, `(is-eq ...)` will _not_ short-circuit. All values supplied to is-eq _must_ be the same type. -#### example: -```clarity -(is-eq 1 1) ;; Returns true -(is-eq true false) ;; Returns false -(is-eq \"abc\" 234 234) ;; Throws type error -``` - -### if -#### input: `bool, A, A` -#### output: `A` -#### signature: `(if bool1 expr1 expr2)` -#### description: -The `if` function admits a boolean argument and two expressions which must return the same type. In the case that the boolean input is `true`, the `if` function evaluates and returns `expr1`. If the boolean input is `false`, the `if` function evaluates and returns `expr2`. -#### example: -```clarity -(if true 1 2) ;; Returns 1 -(if (> 1 2) 1 2) ;; Returns 2 -``` - -### let -#### input: `((name1 AnyType) (name2 AnyType) ...), AnyType, ... A` -#### output: `A` -#### signature: `(let ((name1 expr1) (name2 expr2) ...) expr-body1 expr-body2 ... expr-body-last)` -#### description: -The `let` function accepts a list of `variable name` and `expression` pairs, evaluating each expression and _binding_ it to the corresponding variable name. `let` bindings are sequential: when a `let` binding is evaluated, it may refer to prior binding. The _context_ created by this set of bindings is used for evaluating its body expressions. The let expression returns the value of the last such body expression. Note: intermediary statements returning a response type must be checked` -#### example: -```clarity -(let ((a 2) (b (+ 5 6 7))) (print a) (print b) (+ a b)) ;; Returns 20 -(let ((a 5) (c (+ a 1)) (d (+ c 1)) (b (+ a c d))) (print a) (print b) (+ a b)) ;; Returns 23 -``` - -### map -#### input: `Function(A, B, ..., N) -> X, sequence_A, sequence_B, ..., sequence_N` -#### output: `(list X)` -#### signature: `(map func sequence_A sequence_B ... sequence_N)` -#### description: -Also, note that, no matter what kind of sequences the inputs are, the output is always a list. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. The `map` function applies the function `func` to each corresponding element of the input sequences, and outputs a _list_ of the same type containing the outputs from those function applications. -#### example: -```clarity -(map not (list true false true false)) ;; Returns (false true false true) -(map + (list 1 2 3) (list 1 2 3) (list 1 2 3)) ;; Returns (3 6 9) -(define-private (a-or-b (char (string-utf8 1))) (if (is-eq char u\"a\") u\"a\" u\"b\")) -(map a-or-b u\"aca\") ;; Returns (u\"a\" u\"b\" u\"a\") -(define-private (zero-or-one (char (buff 1))) (if (is-eq char 0x00) 0x00 0x01)) -(map zero-or-one 0x000102) ;; Returns (0x00 0x01 0x01) -``` - -### fold -#### input: `Function(A, B) -> B, sequence_A, B` -#### output: `B` -#### signature: `(fold func sequence_A initial_B)` -#### description: -The `fold` function condenses `sequence_A` into a value of type `B` by recursively applies the function `func` to each element of the input sequence _and_ the output of a previous application of `func`. - -`fold` uses `initial_B` in the initial application of `func`, along with the first element of `sequence_A`. The resulting value of type `B` is used for the next application of `func`, along with the next element of `sequence_A` and so on. `fold` returns the last value of type `B` returned by these successive applications `func`. - -Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. - -#### example: -```clarity -(fold * (list 2 2 2) 1) ;; Returns 8 -(fold * (list 2 2 2) 0) ;; Returns 0 -;; calculates (- 11 (- 7 (- 3 2))) -(fold - (list 3 7 11) 2) ;; Returns 5 -(define-private (concat-string (a (string-ascii 20)) (b (string-ascii 20))) (unwrap-panic (as-max-len? (concat a b) u20))) -(fold concat-string \"cdef\" \"ab\") ;; Returns \"fedcab\" -(fold concat-string (list \"cd\" \"ef\") \"ab\") ;; Returns \"efcdab\" -(define-private (concat-buff (a (buff 20)) (b (buff 20))) (unwrap-panic (as-max-len? (concat a b) u20))) -(fold concat-buff 0x03040506 0x0102) ;; Returns 0x060504030102 -``` - -### append -#### input: `list A, A` -#### output: `list` -#### signature: `(append (list 1 2 3 4) 5)` -#### description: -The `append` function takes a list and another value with the same entry type, and outputs a list of the same type with max_len += 1. -#### example: -```clarity -(append (list 1 2 3 4) 5) ;; Returns (1 2 3 4 5) -``` - -### concat -#### input: `sequence_A, sequence_A` -#### output: `sequence_A` -#### signature: `(concat sequence1 sequence2)` -#### description: -The `func` argument must be a literal function name. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. - -#### example: -```clarity -(concat (list 1 2) (list 3 4)) ;; Returns (1 2 3 4) -(concat \"hello \" \"world\") ;; Returns \"hello world\" -(concat 0x0102 0x0304) ;; Returns 0x01020304 -``` - -### as-max-len? -#### input: `sequence_A, uint` -#### output: `sequence_A` -#### signature: `(as-max-len? sequence max_length)` -#### description: -The `as-max-len?` function takes a sequence argument and a uint-valued, literal length argument. The function returns an optional type. If the input sequence length is less than or equal to the supplied max_length, this returns `(some sequence)`, otherwise it returns `none`. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. ` -#### example: -```clarity -(as-max-len? (list 2 2 2) u3) ;; Returns (some (2 2 2)) -(as-max-len? (list 1 2 3) u2) ;; Returns none -(as-max-len? \"hello\" u10) ;; Returns (some \"hello\") -(as-max-len? 0x010203 u10) ;; Returns (some 0x010203) -``` - -### len -#### input: `sequence_A` -#### output: `uint` -#### signature: `(len sequence)` -#### description: -The `len` function returns the length of a given sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. ` -#### example: -```clarity -(len \"blockstack\") ;; Returns u10 -(len (list 1 2 3 4 5)) ;; Returns u5 -(len 0x010203) ;; Returns u3 -``` - -### element-at -#### input: `sequence_A, uint` -#### output: `(optional A)` -#### signature: `(element-at sequence index)` -#### description: -The `element-at` function returns the element at `index` in the provided sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. ` -#### example: -```clarity -(element-at \"blockstack\" u5) ;; Returns (some \"s\") -(element-at (list 1 2 3 4 5) u5) ;; Returns none -(element-at (list 1 2 3 4 5) (+ u1 u2)) ;; Returns (some 4) -(element-at \"abcd\" u1) ;; Returns (some \"b\") -(element-at 0xfb01 u1) ;; Returns (some 0x01) -``` - -### index-of -#### input: `sequence_A, A` -#### output: `(optional uint)` -#### signature: `(index-of sequence item)` -#### description: -The `index-of` function returns the first index at which `item` can be found, using `is-eq` checks, in the provided sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. If the target item is not found in the sequence (or if an empty string or buffer is supplied), this function returns `none`. -#### example: -```clarity -(index-of \"blockstack\" \"b\") ;; Returns (some u0) -(index-of \"blockstack\" \"k\") ;; Returns (some u4) -(index-of \"blockstack\" \"\") ;; Returns none -(index-of (list 1 2 3 4 5) 6) ;; Returns none -(index-of 0xfb01 0x01) ;; Returns (some u1) -``` - -### list -#### input: `A, ...` -#### output: `(list A)` -#### signature: `(list expr1 expr2 expr3 ...)` -#### description: -The `list` function constructs a list composed of the inputted values. Each supplied value must be of the same type. -#### example: -```clarity -(list (+ 1 2) 4 5) ;; Returns (3 4 5) -``` - -### var-get -#### input: `VarName` -#### output: `A` -#### signature: `(var-get var-name)` -#### description: -The `var-get` function looks up and returns an entry from a contract's data map. The value is looked up using `var-name`. -#### example: -```clarity -(define-data-var cursor int 6) -(var-get cursor) ;; Returns 6 -``` - -### var-set -#### input: `VarName, AnyType` -#### output: `bool` -#### signature: `(var-set var-name expr1)` -#### description: -The `var-set` function sets the value associated with the input variable to the inputted value. The function always returns `true`. -#### example: -```clarity -(define-data-var cursor int 6) -(var-get cursor) ;; Returns 6 -(var-set cursor (+ (var-get cursor) 1)) ;; Returns true -(var-get cursor) ;; Returns 7 -``` - -### map-get? -#### input: `MapName, tuple` -#### output: `(optional (tuple))` -#### signature: `(map-get? map-name key-tuple)` -#### description: -The `map-get?` function looks up and returns an entry from a contract's data map. The value is looked up using `key-tuple`. If there is no value associated with that key in the data map, the function returns a `none` option. Otherwise, it returns `(some value)`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(map-get? names-map (tuple (name \"blockstack\"))) ;; Returns (some (tuple (id 1337))) -(map-get? names-map { name: \"blockstack\" }) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-set -#### input: `MapName, tuple_A, tuple_B` -#### output: `bool` -#### signature: `(map-set map-name key-tuple value-tuple)` -#### description: -The `map-set` function sets the value associated with the input key to the inputted value. This function performs a _blind_ update; whether or not a value is already associated with the key, the function overwrites that existing association. - -Note: the `value-tuple` requires 1 additional byte for storage in the materialized blockchain state, and therefore the maximum size of a value that may be inserted into a map is MAX_CLARITY_VALUE - 1. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-set names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-insert -#### input: `MapName, tuple_A, tuple_B` -#### output: `bool` -#### signature: `(map-insert map-name key-tuple value-tuple)` -#### description: -The `map-insert` function sets the value associated with the input key to the inputted value if and only if there is not already a value associated with the key in the map. If an insert occurs, the function returns `true`. If a value already existed for this key in the data map, the function returns `false`. - -Note: the `value-tuple` requires 1 additional byte for storage in the materialized blockchain state, and therefore the maximum size of a value that may be inserted into a map is MAX_CLARITY_VALUE - 1. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns false -(map-insert names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-delete -#### input: `MapName, tuple` -#### output: `bool` -#### signature: `(map-delete map-name key-tuple)` -#### description: -The `map-delete` function removes the value associated with the input key for the given map. If an item exists and is removed, the function returns `true`. If a value did not exist for this key in the data map, the function returns `false`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-delete names-map { name: \"blockstack\" }) ;; Returns true -(map-delete names-map { name: \"blockstack\" }) ;; Returns false -(map-delete names-map (tuple (name \"blockstack\"))) ;; Same command, using a shorthand for constructing the tuple -``` - -### tuple -#### input: `(key-name A), (key-name-2 B), ...` -#### output: `(tuple (key-name A) (key-name-2 B) ...)` -#### signature: `(tuple (key0 expr0) (key1 expr1) ...)` -#### description: -The `tuple` special form constructs a typed tuple from the supplied key and expression pairs. A `get` function can use typed tuples as input to select specific values from a given tuple. Key names may not appear multiple times in the same tuple definition. Supplied expressions are evaluated and associated with the expressions' paired key name. - -There is a shorthand using curly brackets of the form {key0: expr0, key1: expr, ...}` -#### example: -```clarity -(tuple (name \"blockstack\") (id 1337)) ;; using tuple -{name: \"blockstack\", id: 1337} ;; using curly brackets -``` - -### get -#### input: `KeyName, (tuple) | (optional (tuple))` -#### output: `A` -#### signature: `(get key-name tuple)` -#### description: -The `get` function fetches the value associated with a given key from the supplied typed tuple. If an `Optional` value is supplied as the inputted tuple, `get` returns an `Optional` type of the specified key in the tuple. If the supplied option is a `(none)` option, get returns `(none)`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(get id (tuple (name \"blockstack\") (id 1337))) ;; Returns 1337 -(get id (map-get? names-map (tuple (name \"blockstack\")))) ;; Returns (some 1337) -(get id (map-get? names-map (tuple (name \"non-existent\")))) ;; Returns none -``` - -### merge -#### input: `tuple, tuple` -#### output: `tuple` -#### signature: `(merge tuple { key1: val1 })` -#### description: -The `merge` function returns a new tuple with the combined fields, without mutating the supplied tuples. -#### example: -```clarity -(define-map users { id: int } { name: (string-ascii 12), address: (optional principal) }) -(map-insert users { id: 1337 } { name: \"john\", address: none }) ;; Returns true -(let ((user (unwrap-panic (map-get? users { id: 1337 })))) -(merge user { address: (some 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) })) ;; Returns (tuple (address (some SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF)) (name \"john\")) -``` - -### begin -#### input: `AnyType, ... A` -#### output: `A` -#### signature: `(begin expr1 expr2 expr3 ... expr-last)` -#### description: -The `begin` function evaluates each of its input expressions, returning the return value of the last such expression. Note: intermediary statements returning a response type must be checked. -#### example: -```clarity -(begin (+ 1 2) 4 5) ;; Returns 5 -``` - -### hash160 -#### input: `buff|uint|int` -#### output: `(buff 20)` -#### signature: `(hash160 value)` -#### description: -The `hash160` function computes `RIPEMD160(SHA256(x))` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(hash160 0) ;; Returns 0xe4352f72356db555721651aa612e00379167b30f -``` - -### sha256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(sha256 value)` -#### description: -The `sha256` function computes `SHA256(x)` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(sha256 0) ;; Returns 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb -``` - -### sha512 -#### input: `buff|uint|int` -#### output: `(buff 64)` -#### signature: `(sha512 value)` -#### description: -The `sha512` function computes `SHA512(x)` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(sha512 1) ;; Returns 0x6fcee9a7b7a7b821d241c03c82377928bc6882e7a08c78a4221199bfa220cdc55212273018ee613317c8293bb8d1ce08d1e017508e94e06ab85a734c99c7cc34 -``` - -### sha512/256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(sha512/256 value)` -#### description: -The `sha512/256` function computes `SHA512/256(x)` (the SHA512 algorithm with the 512/256 initialization vector, truncated to 256 bits) of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(sha512/256 1) ;; Returns 0x515a7e92e7c60522db968d81ff70b80818fc17aeabbec36baf0dda2812e94a86 -``` - -### keccak256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(keccak256 value)` -#### description: -The `keccak256` function computes `KECCAK256(value)` of the inputted value. Note that this differs from the `NIST SHA-3` (that is, FIPS 202) standard. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(keccak256 0) ;; Returns 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4 -``` - -### secp256k1-recover? -#### input: `(buff 32), (buff 65)` -#### output: `(response (buff 33) uint)` -#### signature: `(secp256k1-recover? message-hash signature)` -#### description: -The `secp256k1-recover?` function recovers the public key used to sign the message which sha256 is `message-hash` with the provided `signature`. If the signature does not match, it will return the error code `(err u1).`. If the signature is invalid, it will return the error code `(err u2).`. The signature includes 64 bytes plus an additional recovery id (00..03) for a total of 65 bytes. -#### example: -```clarity -(secp256k1-recover? 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a1301) - ;; Returns (ok 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) - ``` - -### secp256k1-verify -#### input: `(buff 32), (buff 64) | (buff 65), (buff 33)` -#### output: `bool` -#### signature: `(secp256k1-verify message-hash signature public-key)` -#### description: -The `secp256k1-verify` function verifies that the provided signature of the message-hash was signed with the private key that generated the public key. The `message-hash` is the `sha256` of the message. The signature includes 64 bytes plus an optional additional recovery id (00..03) for a total of 64 or 65 bytes. -#### example: -```clarity -(secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a1301 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns true -(secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a13 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns true -(secp256k1-verify 0x0000000000000000000000000000000000000000000000000000000000000000 - 0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns false - ``` - -### print -#### input: `A` -#### output: `A` -#### signature: `(print expr)` -#### description: -The `print` function evaluates and returns its input expression. On Stacks Core nodes configured for development (as opposed to production mining nodes), this function prints the resulting value to `STDOUT` (standard output). -#### example: -```clarity -(print (+ 1 2 3)) ;; Returns 6 -``` - -### contract-call? -#### input: `ContractName, PublicFunctionName, Arg0, ...` -#### output: `(response A B)` -#### signature: `(contract-call? .contract-name function-name arg0 arg1 ...)` -#### description: -The `contract-call?` function executes the given public function of the given contract. You _may not_ use this function to call a public function defined in the current contract. If the public function returns _err_, any database changes resulting from calling `contract-call?` are aborted. If the function returns _ok_, database changes occurred. -#### example: -```clarity - -;; instantiate the sample-contracts/tokens.clar contract first! -(as-contract (contract-call? .tokens mint! u19)) ;; Returns (ok u19) -``` - -### as-contract -#### input: `A` -#### output: `A` -#### signature: `(as-contract expr)` -#### description: -The `as-contract` function switches the current context's `tx-sender` value to the _contract's_ principal and executes `expr` with that context. It returns the resulting value of `expr`. -#### example: -```clarity -(as-contract tx-sender) ;; Returns S1G2081040G2081040G2081040G208105NK8PE5.docs-test -``` - -### contract-of -#### input: `Trait` -#### output: `principal` -#### signature: `(contract-of .contract-name)` -#### description: -The `contract-of` function returns the principal of the contract implementing the trait. -#### example: -```clarity -(use-trait token-a-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) -(define-public (forward-get-balance (user principal) (contract )) - (begin - (ok (contract-of contract)))) ;; returns the principal of the contract implementing -``` - -### principal-of? -#### input: `(buff 33)` -#### output: `(response principal uint)` -#### signature: `(principal-of? public-key)` -#### description: -The `principal-of?` function returns the principal derived from the provided public key. If the `public-key` is invalid, it will return the error code `(err u1).`. ` -#### example: -```clarity -(principal-of? 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns (ok ST1AW6EKPGT61SQ9FNVDS17RKNWT8ZP582VF9HSCP) -``` - -### at-block -#### input: `(buff 32), A` -#### output: `A` -#### signature: `(at-block id-block-hash expr)` -#### description: -The `at-block` function evaluates the expression `expr` _as if_ it were evaluated at the end of the block indicated by the _block-hash_ argument. The `expr` closure must be read-only. - -This hash uniquely identifies Stacks blocks and is unique across Stacks forks. Note: The block identifying hash must be a hash returned by the `id-header-hash` block information property. While the hash returned by `header-hash` is unique within the context of a single fork, it is not unique across Stacks forks. - -The function returns the result of evaluating `expr`. - -#### example: -```clarity -(define-data-var data int 1) -(at-block 0x0000000000000000000000000000000000000000000000000000000000000000 block-height) ;; Returns u0 -(at-block (get-block-info? id-header-hash 0) (var-get data)) ;; Throws NoSuchDataVariable because `data` wasn't initialized at block height 0 -``` - -### get-block-info? -#### input: `BlockInfoPropertyName, BlockHeightInt` -#### output: `(optional buff) | (optional uint)` -#### signature: `(get-block-info? prop-name block-height-expr)` -#### description: -The `get-block-info?` function fetches data for a block of the given block height. The value and type returned are determined by the specified `BlockInfoPropertyName`. If the provided `BlockHeightInt` does not correspond to an existing block prior to the current block, the function returns `none`. The currently available property names are `time`, `header-hash`, `burnchain-header-hash`, `id-header-hash`, `miner-address`, and `vrf-seed`. - -This is a Unix epoch timestamp in seconds which roughly corresponds to when the block was mined. The `time` property returns an integer value of the block header time field. **Warning**: this does not increase monotonically with each block and block times are accurate only to within two hours. See [BIP113](https://github.com/bitcoin/bips/blob/master/bip-0113.mediawiki) for more information. - -The `header-hash`, `burnchain-header-hash`, `id-header-hash`, and `vrf-seed` properties return a 32-byte buffer. - -The `miner-address` property returns a `principal` corresponding to the miner of the given block. - -The `id-header-hash` is the block identifier value that must be used as input to the `at-block` function. - -#### example: -```clarity -(get-block-info? time u0) ;; Returns (some u1557860301) -(get-block-info? header-hash u0) ;; Returns (some 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb) -(get-block-info? vrf-seed u0) ;; Returns (some 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4) -``` - -### err -#### input: `A` -#### output: `(response A B)` -#### signature: `(err value)` -#### description: -The `err` function constructs a response type from the input value. Use `err` for creating return values in public functions. An _err_ value indicates that any database changes during the processing of the function should be rolled back. -#### example: -```clarity -(err true) ;; Returns (err true) -``` - -### ok -#### input: `A` -#### output: `(response A B)` -#### signature: `(ok value)` -#### description: -The `ok` function constructs a response type from the input value. Use `ok` for creating return values in public functions. An _ok_ value indicates that any database changes during the processing of the function should materialize. -#### example: -```clarity -(ok 1) ;; Returns (ok 1) -``` - -### some -#### input: `A` -#### output: `(optional A)` -#### signature: `(some value)` -#### description: -The `some` function constructs a `optional` type from the input value. -#### example: -```clarity -(some 1) ;; Returns (some 1) -(is-none (some 2)) ;; Returns false -``` - -### default-to -#### input: `A, (optional A)` -#### output: `A` -#### signature: `(default-to default-value option-value)` -#### description: -The `default-to` function attempts to 'unpack' the second argument: if the argument is a `(some ...)` option, it returns the inner value of the option. If the second argument is a `(none)` value, `default-to` it returns the value of `default-value`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(default-to 0 (get id (map-get? names-map (tuple (name \"blockstack\"))))) ;; Returns 1337 -(default-to 0 (get id (map-get? names-map (tuple (name \"non-existant\"))))) ;; Returns 0 -``` - -### asserts! -#### input: `bool, C` -#### output: `bool` -#### signature: `(asserts! bool-expr thrown-value)` -#### description: -The `asserts!` function admits a boolean argument and asserts its evaluation: if bool-expr is `true`, `asserts!` returns `true` and proceeds in the program execution. If the supplied argument is returning a false value, `asserts!` _returns_ `thrown-value` and exits the current control-flow. -#### example: -```clarity -(asserts! (is-eq 1 1) (err 1)) ;; Returns true -``` - -### unwrap! -#### input: `(optional A) | (response A B), C` -#### output: `A` -#### signature: `(unwrap! option-input thrown-value)` -#### description: -The `unwrap!` function attempts to 'unpack' the first argument: if the argument is an option type, and the argument is a `(some ...)` option, `unwrap!` returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, `unwrap!` returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `(none)` value, `unwrap!` _returns_ `thrown-value` from the current function and exits the current control-flow. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(define-private (get-name-or-err (name (string-ascii 12))) - (let ((raw-name (unwrap! (define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(define-private (get-name-or-err (name (string-ascii 12))) - (let ((raw-name (unwrap! names-map { name: name }) (err 1)))) - (ok raw-name))) - -(get-name-or-err \"blockstack\") ;; Returns (ok (tuple (id 1337))) -(get-name-or-err \"non-existant\") ;; Returns (err 1) -``` - -### unwrap-err! -#### input: `(response A B), C` -#### output: `B` -#### signature: `(unwrap-err! response-input thrown-value)` -#### description: -The `unwrap-err!` function attempts to 'unpack' the first argument: if the argument is an `(err ...)` response, `unwrap-err!` returns the inner value of the `err`. If the supplied argument is an `(ok ...)` value, `unwrap-err!` _returns_ `thrown-value` from the current function and exits the current control-flow. -#### example: -```clarity -(unwrap-err! (err 1) false) ;; Returns 1 -``` - -### unwrap-panic -#### input: `(optional A) | (response A B)` -#### output: `A` -#### signature: `(unwrap-panic option-input)` -#### description: -The `unwrap` function attempts to 'unpack' its argument: if the argument is an option type, and the argument is a `(some ...)` option, this function returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, it returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `(none)` value, `unwrap` throws a runtime error, aborting any further processing of the current transaction. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(unwrap-panic (map-get? names-map { name: \"blockstack\" })) ;; Returns (tuple (id 1337)) -(unwrap-panic (map-get? names-map { name: \"non-existant\" })) ;; Throws a runtime exception -``` - -### unwrap-err-panic -#### input: `(response A B)` -#### output: `B` -#### signature: `(unwrap-err-panic response-input)` -#### description: -The `unwrap-err` function attempts to 'unpack' the first argument: if the argument is an `(err ...)` response, `unwrap` returns the inner value of the `err`. If the supplied argument is an `(ok ...)` value, `unwrap-err` throws a runtime error, aborting any further processing of the current transaction. -#### example: -```clarity -(unwrap-err-panic (err 1)) ;; Returns 1 -(unwrap-err-panic (ok 1)) ;; Throws a runtime exception -``` - -### match -#### input: `(optional A) name expression expression | (response A B) name expression name expression` -#### output: `C` -#### signature: `(match opt-input some-binding-name some-branch none-branch) | -(match-resp input ok-binding-name ok-branch err-binding-name err-branch)` -#### description: -The `match` function is used to test and destructure optional and response types. - -If the `input` is an optional, it tests whether the provided `input` is a `some` or `none` option, and evaluates `some-branch` or `none-branch` in each respective case. - -Within the `some-branch`, the _contained value_ of the `input` argument is bound to the provided `some-binding-name` name. - -Only _one_ of the branches will be evaluated (similar to `if` statements). - -If the `input` is a response, it tests whether the provided `input` is an `ok` or `err` response type, and evaluates `ok-branch` or `err-branch` in each respective case. - -Within the `ok-branch`, the _contained ok value_ of the `input` argument is bound to the provided `ok-binding-name` name. - -Within the `err-branch`, the _contained err value_ of the `input` argument is bound to the provided `err-binding-name` name. - -Only _one_ of the branches will be evaluated (similar to `if` statements). - -Note: Type checking requires that the type of both the ok and err parts of the response object be determinable. For situations in which one of the parts of a response is untyped, you should use `unwrap-panic` or `unwrap-err-panic` instead of `match`. -#### example: -```clarity - -(define-private (add-10 (x (optional int))) - (match x - value (+ 10 value) - 10)) -(add-10 (some 5)) ;; Returns 15 -(add-10 none) ;; Returns 10 - -(define-private (add-or-pass-err (x (response int (string-ascii 10))) (to-add int)) - (match x - value (ok (+ to-add value)) - err-value (err err-value))) -(add-or-pass-err (ok 5) 20) ;; Returns (ok 25) -(add-or-pass-err (err \"ERROR\") 20) ;; Returns (err \"ERROR\") -``` - -### try! -#### input: `(optional A) | (response A B)` -#### output: `A` -#### signature: `(try! option-input)` -#### description: -The `try!` function attempts to 'unpack' the first argument: if the argument is an option type, and the argument is a `(some ...)` option, `try!` returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, `try!` returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `none` value, `try!` _returns_ either `none` or the `(err ...)` value from the current function and exits the current control-flow. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(try! (define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(define-private (get-name-or-err (name (string-ascii 12))) - (let ((raw-name (unwrap! names-map { name: \"blockstack\" })) ;; Returns (tuple (id 1337)) -(define-private (checked-even (x int)) - (if (is-eq (mod x 2) 0) - (ok x) - (err false))) -(define-private (double-if-even (x int)) - (ok (* 2 (try! (checked-even x))))) -(double-if-even 10) ;; Returns (ok 20) -(double-if-even 3) ;; Returns (err false) -``` - -### is-ok -#### input: `(response A B)` -#### output: `bool` -#### signature: `(is-ok value)` -#### description: -`is-ok` tests a supplied response value, returning `true` if the response was `ok`, and `false` if it was an `err`. -#### example: -```clarity -(is-ok (ok 1)) ;; Returns true -(is-ok (err 1)) ;; Returns false -``` - -### is-none -#### input: `(optional A)` -#### output: `bool` -#### signature: `(is-none value)` -#### description: -`is-none` tests a supplied option value, returning `true` if the option value is `(none)`, and `false` if it is a `(some ...)`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(is-none (get id (map-get? names-map { name: \"blockstack\" }))) ;; Returns false -(is-none (get id (map-get? names-map { name: \"non-existant\" }))) ;; Returns true -``` - -### is-err -#### input: `(response A B)` -#### output: `bool` -#### signature: `(is-err value)` -#### description: -`is-err` tests a supplied response value, returning `true` if the response was an `err`, and `false` if it was an `ok`. -#### example: -```clarity -(is-err (ok 1)) ;; Returns false -(is-err (err 1)) ;; Returns true -``` - -### is-some -#### input: `(optional A)` -#### output: `bool` -#### signature: `(is-some value)` -#### description: -`is-some` tests a supplied option value, returning `true` if the option value is `(some ...)`, and `false` if it is a `none`. -#### example: -```clarity - -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(is-some (get id (map-get? names-map { name: \"blockstack\" }))) ;; Returns true -(is-some (get id (map-get? names-map { name: \"non-existant\" }))) ;; Returns false -``` - -### filter -#### input: `Function(A) -> bool, sequence_A` -#### output: `sequence_A` -#### signature: `(filter func sequence)` -#### description: -The `filter` function applies the input function `func` to each element of the input sequence, and returns the same sequence with any elements removed for which `func` returned `false`. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. ` -#### example: -```clarity - -(filter not (list true false true false)) ;; Returns (false false) -(define-private (is-a (char (string-utf8 1))) (is-eq char u\"a\")) -(filter is-a u\"acabd\") ;; Returns u\"aa\" -(define-private (is-zero (char (buff 1))) (is-eq char 0x00)) -(filter is-zero 0x00010002) ;; Returns 0x0000 -``` - -### ft-get-balance -#### input: `TokenName, principal` -#### output: `uint` -#### signature: `(ft-get-balance token-name principal)` -#### description: -`ft-get-balance` returns `token-name` balance of the principal `principal`. The token type must have been defined using `define-fungible-token`. -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-get-balance stackaroo 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns u100 -``` - -### nft-get-owner? -#### input: `AssetName, A` -#### output: `(optional principal)` -#### signature: `(nft-get-owner? asset-class asset-identifier)` -#### description: -`nft-get-owner?` returns the owner of an asset, identified by `asset-identifier`, or `none` if the asset does not exist. The asset type must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) -(nft-get-owner? stackaroo \"Roo\") ;; Returns (some SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) -(nft-get-owner? stackaroo \"Too\") ;; Returns none -``` - -### ft-transfer? -#### input: `TokenName, uint, principal, principal` -#### output: `(response bool uint)` -#### signature: `(ft-transfer? token-name amount sender recipient)` -#### description: -`ft-transfer?` is used to increase the token balance for the `recipient` principal for a token type defined using `define-fungible-token` by debiting the `sender` principal. In contrast to `stx-transfer?`, any user can transfer the assets. When used, relevant guards need to be added. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- amount to send is non-positive ` -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-transfer? stackaroo u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(ft-transfer? stackaroo u60 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u1) -``` - -### nft-transfer? -#### input: `AssetName, A, principal, principal` -#### output: `(response bool uint)` -#### signature: `(nft-transfer? asset-class asset-identifier sender recipient)` -#### description: -`nft-transfer?` is used to change the owner of an asset identified by `asset-identifier` from `sender` to `recipient`. The `asset-class` must have been defined by `define-non-fungible-token` and `asset-identifier` must be of the type specified in that definition. In contrast to `stx-transfer?`, any user can transfer the asset. When used, relevant guards need to be added. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not own the asset `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- asset identified by asset-identifier does not exist ` -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(nft-transfer? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(nft-transfer? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u1) -(nft-transfer? stackaroo \"Stacka\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u3) -``` - -### nft-mint? -#### input: `AssetName, A, principal` -#### output: `(response bool uint)` -#### signature: `(nft-mint? asset-class asset-identifier recipient)` -#### description: -`nft-mint?` is used to instantiate an asset and set that asset's owner to the `recipient` principal. The asset must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. - -If an asset identified by `asset-identifier` _already exists_, this function will return an error with the following error code: - -`(err u1)` - -Otherwise, on successfuly mint, it returns `(ok true)`. ` -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### ft-mint? -#### input: `TokenName, uint, principal` -#### output: `(response bool uint)` -#### signature: `(ft-mint? token-name amount recipient)` -#### description: -`ft-mint?` is used to increase the token balance for the `recipient` principal for a token type defined using `define-fungible-token`. The increased token balance is _not_ transfered from another principal, but rather minted. - -If a non-positive amount is provided to mint, this function returns `(err 1)`. Otherwise, on successfuly mint, it returns `(ok true)`. ` -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### ft-get-supply -#### input: `TokenName` -#### output: `uint` -#### signature: `(ft-get-supply token-name)` -#### description: -`ft-get-balance` returns `token-name` circulating supply. The token type must have been defined using `define-fungible-token`. -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-get-supply stackaroo) ;; Returns u100 -``` - -### ft-burn? -#### input: `TokenName, uint, principal` -#### output: `(response bool uint)` -#### signature: `(ft-burn? token-name amount sender)` -#### description: -`ft-burn?` is used to decrease the token balance for the `sender` principal for a token type defined using `define-fungible-token`. The decreased token balance is _not_ transfered to another principal, but rather destroyed, reducing the circulating supply. - -If a non-positive amount is provided to burn, this function returns `(err 1)`. Otherwise, on successfuly burn, it returns `(ok true)`. - -#### example: -```clarity - -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(ft-burn? stackaroo u50 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### nft-burn? -#### input: `AssetName, A, principal` -#### output: `(response bool uint)` -#### signature: `(nft-burn? asset-class asset-identifier recipient)` -#### description: -`nft-burn?` is used to burn an asset and remove that asset's owner from the `recipient` principal. The asset must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. - -If an asset identified by `asset-identifier` _doesn't exist_, this function will return an error with the following error code: - -`(err u1)` - -Otherwise, on successfuly burn, it returns `(ok true)`. ` -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(nft-burn? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### stx-get-balance -#### input: `principal` -#### output: `uint` -#### signature: `(stx-get-balance owner)` -#### description: -`stx-get-balance` is used to query the STX balance of the `owner` principal. - -This function returns the STX balance of the `owner` principal. In the event that the `owner` principal isn't materialized, it returns 0. - -#### example: -```clarity -(stx-get-balance 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns u0 -(stx-get-balance (as-contract tx-sender)) ;; Returns u1000 -``` - -### stx-transfer? -#### input: `uint, principal, principal` -#### output: `(response bool uint)` -#### signature: `(stx-transfer? amount sender recipient)` -#### description: -`stx-transfer?` is used to increase the STX balance for the `recipient` principal by debiting the `sender` principal. The `sender` principal _must_ be equal to the current context's `tx-sender`. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- amount to send is non-positive `(err u4)` -- the `sender` principal is not the current `tx-sender` - -#### example: -```clarity - -(as-contract - (stx-transfer? u60 tx-sender 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (ok true) -(as-contract - (stx-transfer? u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR tx-sender)) ;; Returns (err u4) -``` - -### stx-burn? -#### input: `uint, principal` -#### output: `(response bool uint)` -#### signature: `(stx-burn? amount sender)` -#### description: -`stx-burn?` debits the `sender` principal's STX holdings by `amount`, destroying the STX. The `sender` principal _must_ be equal to the current context's `tx-sender`. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u3)` -- amount to send is non-positive `(err u4)` -- the `sender` principal is not the current `tx-sender` - -#### example: -```clarity -(as-contract - (stx-burn? u60 tx-sender)) ;; Returns (ok true) -(as-contract - (stx-burn? u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (err u4) -``` - -### define-constant -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-constant name expression)` -#### description: -`define-constant` is used to define a private constant value in a smart contract. The expression passed into the definition is evaluated at contract launch, in the order that it is supplied in the contract. This can lead to undefined function or undefined variable errors in the event that a function or variable used in the expression has not been defined before the constant. - -Like other kinds of definition statements, `define-constant` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -#### example: -```clarity - -(define-constant four (+ 2 2)) -(+ 4 four) ;; Returns 8 -``` - -### define-private -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-private (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### description: -`define-private` is used to define _private_ functions for a smart contract. Private functions may not be called from other smart contracts, nor may they be invoked directly by users. Instead, these functions may only be invoked by other functions defined in the same smart contract. - -Like other kinds of definition statements, `define-private` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Private functions may return any type. -#### example: -```clarity -(define-private (max-of (i1 int) (i2 int)) - (if (> i1 i2) - i1 - i2)) -(max-of 4 6) ;; Returns 6 -``` - -### define-public -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-public (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### description: -`define-public` is used to define a _public_ function and transaction for a smart contract. Public functions are callable from other smart contracts and may be invoked directly by users by submitting a transaction to the Stacks blockchain. - -Like other kinds of definition statements, `define-public` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Public functions _must_ return a ResponseType (using either `ok` or `err`). Any datamap modifications performed by a public function is aborted if the function returns an `err` type. Public functions may be invoked by other contracts via `contract-call?`. -#### example: -```clarity -(define-public (hello-world (input int)) - (begin (print (+ 2 input)) - (ok input))) -``` - -### define-read-only -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-read-only (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### description: -`define-read-only` is used to define a _public read-only_ function for a smart contract. Such functions are callable from other smart contracts. - -Like other kinds of definition statements, `define-read-only` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Read-only functions may return any type. However, read-only functions may not perform any datamap modifications, or call any functions which perform such modifications. This is enforced both during type checks and during the execution of the function. Public read-only functions may be invoked by other contracts via `contract-call?`. -#### example: -```clarity -(define-read-only (just-return-one-hundred) - (* 10 10)) - ``` - -### define-map -#### input: `MapName, TypeDefinition, TypeDefinition` -#### output: `Not Applicable` -#### signature: `(define-map map-name key-type value-type)` -#### description: -`define-map` is used to define a new datamap for use in a smart contract. Such maps are only modifiable by the current smart contract. - -Maps are defined with a key type and value type, often these types are tuple types. - -Like other kinds of definition statements, `define-map` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). -#### example: -```clarity -(define-map squares { x: int } { square: int }) -(define-private (add-entry (x int)) - (map-insert squares { x: 2 } { square: (* x x) })) -(add-entry 1) -(add-entry 2) -(add-entry 3) -(add-entry 4) -(add-entry 5) -``` - -### define-data-var -#### input: `VarName, TypeDefinition, Value` -#### output: `Not Applicable` -#### signature: `(define-data-var var-name type value)` -#### description: -`define-data-var` is used to define a new persisted variable for use in a smart contract. Such variable are only modifiable by the current smart contract. - -Persisted variable are defined with a type and a value. - -Like other kinds of definition statements, `define-data-var` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). -#### example: -```clarity -(define-data-var size int 0) -(define-private (set-size (value int)) - (var-set size value)) -(set-size 1) -(set-size 2) -``` - -### define-fungible-token -#### input: `TokenName, ` -#### output: `Not Applicable` -#### signature: `(define-fungible-token token-name )` -#### description: -`define-fungible-token` is used to define a new fungible token class for use in the current contract. - -The second argument, if supplied, defines the total supply of the fungible token. This ensures that all calls to the `ft-mint?` function will never be able to create more than `total-supply` tokens. If any such call were to increase the total supply of tokens passed that amount, that invocation of `ft-mint?` will result in a runtime error and abort. - -Like other kinds of definition statements, `define-fungible-token` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Tokens defined using `define-fungible-token` may be used in `ft-transfer?`, `ft-mint?`, and `ft-get-balance` functions` -#### example: -```clarity -(define-fungible-token stacks) -(define-fungible-token limited-supply-stacks u100) -``` - -### define-non-fungible-token -#### input: `AssetName, TypeSignature` -#### output: `Not Applicable` -#### signature: `(define-non-fungible-token asset-name asset-identifier-type)` -#### description: -`define-non-fungible-token` is used to define a new non-fungible token class for use in the current contract. Individual assets are identified by their asset identifier, which must be of the type `asset-identifier-type`. Asset identifiers are _unique_ identifiers. - -Like other kinds of definition statements, `define-non-fungible-token` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Assets defined using `define-non-fungible-token` may be used in `nft-transfer?`, `nft-mint?`, and `nft-get-owner?` functions` -#### example: -```clarity -(define-non-fungible-token names (buff 50)) -``` - -### define-trait -#### input: `VarName, [MethodSignature]` -#### output: `Not Applicable` -#### signature: `(define-trait trait-name ((func1-name (arg1-type arg2-type ...) (return-type))))` -#### description: -`define-trait` is used to define a new trait definition for use in a smart contract. Other contracts can implement a given trait and then have their contract identifier being passed as function arguments in order to be called dynamically with `contract-call?`. - -Traits are defined with a name, and a list functions defined with a name, a list of argument types, and return type. - -Like other kinds of definition statements, `define-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -#### example: -```clarity -(define-trait token-trait - ((transfer? (principal principal uint) (response uint uint)) - (get-balance (principal) (response uint uint)))) -``` - -### use-trait -#### input: `VarName, TraitIdentifier` -#### output: `Not Applicable` -#### signature: `(use-trait trait-alias trait-identifier)` -#### description: -`use-trait` is used to bring a trait, defined in another contract, to the current contract. Subsequent references to an imported trait are signaled with the syntax ``. - -Traits import are defined with a name, used as an alias, and a trait identifier. Trait identifiers can either be using the sugared syntax (.token-a.token-trait), or be fully qualified ('SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait). - -Like other kinds of definition statements, `use-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put such a statement in the middle of a function body). -#### example: -```clarity -(use-trait token-a-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) -(define-public (forward-get-balance (user principal) (contract )) - (begin - (ok 1))) -``` - -### impl-trait -#### input: `TraitIdentifier` -#### output: `Not Applicable` -#### signature: `(impl-trait trait-identifier)` -#### description: -`impl-trait` can be use for asserting that a contract is fully implementing a given trait. Additional checks are being performed when the contract is being published, rejecting the deployment if the contract is violating the trait specification. - -Trait identifiers can either be using the sugared syntax (.token-a.token-trait), or be fully qualified ('SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait). - -Like other kinds of definition statements, `impl-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put such a statement in the middle of a function body). - -#### example: -```clarity -(impl-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) (define-public (get-balance (account principal)) (ok u0)) (define-public (transfer? (from principal) (to principal) (amount uint)) - (ok u0)) -``` \ No newline at end of file diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md b/i18n/ko/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md deleted file mode 100644 index fd62451198..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Keywords -description: See a detailed list of all keywords for the Clarity language. -tags: - - clarity ---- - -![](/img/keywords.jpg) -## Keyword reference - -Detailed list of all keywords for the Clarity language. - - -### contract-caller -#### output: `principal` -#### description: -Returns the caller of the current contract context. If this contract is the first one called by a signed transaction, the caller will be equal to the signing principal. If `contract-call?` was used to invoke a function from a new contract, `contract-caller` changes to the _calling_ contract's principal. If `as-contract` is used to change the `tx-sender` context, `contract-caller` _also_ changes to the same contract principal. -#### example: -```clarity -(print contract-caller) ;; Will print out a Stacks address of the transaction sender -``` - -### tx-sender -#### output: `principal` -#### description: -Returns the original sender of the current transaction, or if `as-contract` was called to modify the sending context, it returns that contract principal. -#### example: -```clarity -(print tx-sender) ;; Will print out a Stacks address of the transaction sender -``` - -### block-height -#### output: `uint` -#### description: -Returns the current block height of the Stacks blockchain as an uint -#### example: -```clarity -(> block-height 1000) ;; returns true if the current block-height has passed 1000 blocks. -``` - -### burn-block-height -#### output: `uint` -#### description: -Returns the current block height of the underlying burn blockchain as a uint -#### example: -```clarity -(> burn-block-height 1000) ;; returns true if the current height of the underlying burn blockchain has passed 1000 blocks. -``` - -### none -#### output: `(optional ?)` -#### description: -Represents the _none_ option indicating no value for a given optional (analogous to a null value). -#### example: -```clarity -(define-public (only-if-positive (a int)) - (if (> a 0) - (some a) - none)) -(only-if-positive 4) ;; Returns (some 4) -(only-if-positive (- 3)) ;; Returns none -``` - -### true -#### output: `bool` -#### description: -Boolean true constant. -#### example: -```clarity -(and true false) ;; Evaluates to false -(or false true) ;; Evaluates to true -``` - -### false -#### output: `bool` -#### description: -Boolean false constant. -#### example: -```clarity -(and true false) ;; Evaluates to false -(or false true) ;; Evaluates to true -``` - -### stx-liquid-supply -#### output: `uint` -#### description: -Returns the total number of micro-STX (uSTX) that are liquid in the system as of this block. -#### example: -```clarity -(print stx-liquid-supply) ;; Will print out the total number of liquid uSTX -``` - -### is-in-regtest -#### output: `bool` -#### description: -Returns whether or not the code is running in a regression test -#### example: -```clarity -(print is-in-regtest) ;; Will print 'true' if the code is running in a regression test -``` - diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md b/i18n/ko/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md deleted file mode 100644 index d22f991413..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Types -description: See a detailed list of all types for the Clarity language. -tags: - - clarity ---- - -## Clarity Type System - -The type system contains the following types: - -| Types | Notes | -| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `int` | signed 128-bit integer | -| `uint` | unsigned 128-bit integer | -| `bool` | boolean value (`true` or `false`) | -| `principal` | object representing a principal (whether a contract principal or standard principal) | -| `(buff max-len)` | byte buffer of 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` (u"A smiley face emoji \u{1F600} as a utf8 string") | -| `(list max-len entry-type)` | list of maximum length `max-len`, with entries of type `entry-type` | -| `{label-0: value-type-0, label-1: value-type-1, ...}` | tuple, group of data values with named fields | -| `(optional some-type)` | an option type for objects that can either be `(some value)` or `none` | -| `(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. | diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md b/i18n/ko/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md deleted file mode 100644 index e75e1d69b9..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Clarity overview -description: Overview and guides for getting started with Clarity -sidebar_label: Write smart contracts -sidebar_position: 2 ---- - -## Introduction - -Clarity is a **decidable** smart contract language that optimizes for predictability and security, designed for the Stacks blockchain. Smart contracts allow developers to encode essential business logic on a blockchain. - -## Smart contracts - -Smart contracts encode and enforce rules for modifying a particular set of data that is shared among people and entities who don't necessarily trust each other. For example, a smart contract can hold funds in escrow until multiple parties agree to release them, create its own ledger and keep track of its own novel tokens (fungible or non-fungible), and even help make supply chains more transparent. - -A smart contract execution can result in new transactions being written to the blockchain. Because smart contracts are programs that exist in a blockchain, anyone can query them, and anyone can submit transactions to execute them. - -Apps can take advantage of smart contracts to manage a global state that is visible to the public. Anyone can audit the blockchain to independently verify that an app's global shared state has been managed correctly according to the smart contract's rules. - -There is a [Clarity Visual Studio Code plugin][] available for syntax assistance and debugging. - -## Use cases - -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 (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 - -## Language design - -Clarity differs from most other smart contract languages in two essential ways: - -- The language is interpreted and broadcast on the blockchain as is (not compiled) -- The language is decidable (not Turing complete) - -Using an interpreted language ensures that the executed code is human-readable and auditable. A decidable language like Clarity makes it possible to determine precisely which code is executed, for any function. - -A Clarity smart contract consists of two parts, a data space and a set of functions. Only the associated smart contract may modify its corresponding data space on the blockchain. Functions may be private and thus callable only from within the smart contract, or public and thus callable from other contracts. Users call smart contracts' public functions by broadcasting a transaction on the blockchain which invokes the public function. Contracts can also call public functions from other smart contracts. - -Note some of the key Clarity language rules and limitations. - -- The only primitive types are booleans, integers, buffers, and principals. -- Recursion is illegal and there are no anonymous functions. -- Looping is only performed via `map`, `filter`, or `fold`. -- There is support for lists, however, the only variable length lists in the language appear as function inputs; there is no support for list operations like append or join. -- Variables are immutable. - -## Explore more - -For language details and references, see the following: - -- [Clarity language overview](./clarity-language/) -- [Understating Principals](principals) -- [Clarity Values](values) - -[Clarity Visual Studio Code plugin]: https://marketplace.visualstudio.com/items?itemName=HiroSystems.clarity-lsp diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md b/i18n/ko/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md deleted file mode 100644 index 912ea694a6..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md +++ /dev/null @@ -1,232 +0,0 @@ ---- -title: Principals -description: 'Clarity: Understanding Principals' -sidebar_position: 1 ---- - -## Introduction - -_Principals_ are a Clarity native type that represents an entity that can have a token balance. This section discusses principals and how they are used in the Clarity. - -## Principals and tx-sender - -Assets in the smart contracting language and blockchain are "owned" by objects of the principal type, meaning that any object of the principal type may own an asset. For the case of public-key hash and multi-signature Stacks addresses, a given principal can operate on their assets by issuing a signed transaction on the blockchain. _Smart contracts_ may also be principals (represented by the smart contract's identifier), however, there is no private key associated with the smart contract, and it cannot broadcast a signed transaction on the blockchain. - -A Clarity contract can use a globally defined `tx-sender` variable to obtain the current principal. The following example defines a transaction type that transfers `amount` microSTX from the sender to a recipient if amount is a multiple of 10, otherwise returning a 400 error code. - -```clarity -(define-public (transfer-to-recipient! (recipient principal) (amount uint)) - (if (is-eq (mod amount 10) 0) - (stx-transfer? amount tx-sender recipient) - (err u400))) -``` - -Clarity provides an additional variable to help smart contracts authenticate a transaction sender. The keyword `contract-caller` returns the principal that _called_ the current contract. If an inter-contract call occurred, `contract-caller` returns the last contract in the stack of callers. For example, suppose there are three contracts A, B, and C, each with an `invoke` function such that `A::invoke` calls `B::invoke` and `B::invoke` calls `C::invoke`. - -When a user Bob issues a transaction that calls `A::invoke`, the value of `contract-caller` in each successive invoke function's body would change: - -```clarity -in A::invoke, contract-caller = Bob -in B::invoke, contract-caller = A -in C::invoke, contract-caller = B -``` - -This allows contracts to make assertions and perform authorization checks using not only the `tx-sender` (which in this example, would always be "Bob"), but also using the `contract-caller`. This could be used to ensure that a particular function is only ever called directly and never called via an inter-contract call (by asserting that `tx-sender` and `contract-caller` are equal). We provide an example of a two different types of authorization checks in the rocket ship example below. - -## Smart contracts as principals - -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, for example: - -```clarity -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-name -``` - -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 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 qualified identifier for the contracts would be: - -```clarity -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-A -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-B -``` - -But, in the contract source code, if the developer wishes to call a function from `contract-A` in `contract-B`, they can write - -```clarity -(contract-call? .contract-A public-function-foo) -``` - -This allows the smart contract developer to modularize their applications across multiple smart contracts _without_ knowing the publishing key a priori. - -In order for a smart contract to operate on assets it owns, smart contracts may use the special `(as-contract ...)` function. This function executes the expression (passed as an argument) with the `tx-sender` set to the contract's principal, rather than the current sender. The `as-contract` function returns the value of the provided expression. - -For example, a smart contract that implements something like a "token faucet" could be implemented as so: - -```clarity -(define-map claimed-before - ((sender principal)) - ((claimed bool))) - -(define-constant err-already-claimed u1) -(define-constant err-faucet-empty u2) -(define-constant stx-amount u1) - -(define-public (claim-from-faucet) - (let ((requester tx-sender)) ;; set a local variable requester = tx-sender - (asserts! (is-none (map-get? claimed-before {sender: requester})) (err err-already-claimed)) - (unwrap! (as-contract (stx-transfer? stx-amount tx-sender requester)) (err err-faucet-empty)) - (map-set claimed-before {sender: requester} {claimed: true}) - (ok stx-amount))) -``` - -In this example, the public function `claim-from-faucet`: - -- Checks if the sender has claimed from the faucet before. -- Assigns the tx sender to a `requester` variable. -- Adds an entry to the tracking map. -- Uses `as-contract` to send 1 microstack - -Unlike other principals, there is no private key associated with a smart contract. As it lacks a private key, a Clarity smart contract cannot broadcast a signed transaction on the blockchain. - -## Example: Authorization checks - -The interactions between `tx-sender`, `contract-caller` and `as-contract` are subtle, but are important when performing authorization checks in a contract. In this example contract, we'll show two different kinds of authorization checks a contract may wish to perform, and then walk through how different ways in which contract functions may be called will pass or fail those checks. - -This contract defines a "rocket-ship" non-fungible-token that a principal may own and manage the authorized pilots. Pilots are principals that are allowed to "fly" the rocket ship. - -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. -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 be called _directly_ by the ship's owner, rather than through a inter-contract-call. - -The second type of check is more restrictive than the first check, and is helpful for guarding very sensitive routines --- it protects users from unknowingly calling a function on a malicious contract that subsequently tries to call sensitive functions on another contract. - -```clarity -;; -;; rockets-base.clar -;; - -(define-non-fungible-token rocket-ship uint) - -;; a map from rocket ships to their allowed -;; pilots -(define-map allowed-pilots - ((rocket-ship uint)) ((pilots (list 10 principal)))) - -;; implementing a contains function via fold -(define-private (contains-check - (y principal) - (to-check { p: principal, result: bool })) - (if (get result to-check) - to-check - { p: (get p to-check), - result: (is-eq (get p to-check) y) })) - -(define-private (contains (x principal) (find-in (list 10 principal))) - (get result (fold contains-check find-in - { p: x, result: false }))) - -(define-read-only (is-my-ship (ship uint)) - (is-eq (some tx-sender) (nft-get-owner? rocket-ship ship))) - -;; this function will print a message -;; (and emit an event) if the tx-sender was -;; an authorized flyer. -;; -;; here we use tx-sender, because we want -;; to allow the user to let other contracts -;; fly the ship on behalf of users - -(define-public (fly-ship (ship uint)) - (let ((pilots (default-to - (list) - (get pilots (map-get? allowed-pilots { rocket-ship: ship }))))) - (if (contains tx-sender pilots) - (begin (print "Flew the rocket-ship!") - (ok true)) - (begin (print "Tried to fly without permission!") - (ok false))))) -;; -;; Authorize a new pilot. -;; -;; here we want to ensure that this function -;; was called _directly_ by the user by -;; checking that tx-sender and contract-caller are equal. -;; if any other contract is in the call stack, contract-caller -;; would be updated to a different principal. -;; -(define-public (authorize-pilot (ship uint) (pilot principal)) - (begin - ;; sender must equal caller: an intermediate contract is - ;; not issuing this call. - (asserts! (asserts! (is-eq tx-sender contract-caller) (err u1)) - ;; sender must own the rocket ship - (asserts! (is-eq (some tx-sender) - (nft-get-owner? rocket-ship ship)) (err u2)) - (let ((prev-pilots (default-to - (list) - (get pilots (map-get? allowed-pilots { rocket-ship: ship }))))) - ;; don't add a pilot already in the list - (asserts! (not (contains pilot prev-pilots)) (err u3)) - ;; append to the list, and check that it is less than - ;; the allowed maximum - (match (as-max-len? -``` - -### Extending functionality: Multi-flyer contract - -The authorization scheme for `fly-ship` allows pilots to fly rocket-ships from other contracts. This allows other contracts to provide new functionality built around calling that function. - -For example, we can create a contract that calls `fly-ship` for multiple rocket-ships in a single transaction: - -```clarity -;; -;; rockets-multi.clar -;; - -(define-private (call-fly (ship uint)) - (unwrap! (contract-call? .rockets-base fly-ship ship) false)) -;; try to fly all the ships, returning a list of whether -;; or not we were able to fly the supplied ships -(define-public (fly-all (ships (list 10 uint))) - (ok (map call-fly ships))) -``` - -### Authorization for Contract-Owned Assets - -The check in `authorize-pilot` protects users from malicious contracts, but how would such a scheme support contract-owned assets? This is what the `as-contract` function is used for. The `as-contract` function executes the supplied closure as if the sender of the transaction was the current contract, rather than the user -- it does this by updating `tx-sender` to the current contract principal. We can use this to, for example, create a smart contract rocket-ship-line: - -```clarity -;; -;; rockets-ship-line.clar -;; - -(define-constant line-ceo 'SP19Y6GRV9X778VFS1V8WT2H502WFK33XZXADJWZ) - -(define-data-var employed-pilots (list 10 principal) (list)) - -;; This function will: -;; * check that it is called by the line-ceo -;; * check that the rocket is owned by the contract -;; * authorize each employed pilot to the ship -(define-public (add-managed-rocket (ship uint)) - (begin - ;; 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 - (asserts! (contract-call? .rockets-base is-my-ship ship) (err u2)) - ;; register all of our pilots on the ship - (add-pilots-to ship))))) - -;; add all the pilots to a ship using fold -- -;; the fold checks the return type of previous calls, -;; skipping subsequent contract-calls if one fails. -(define-private (add-pilot-via-fold (pilot principal) (prior-result (response uint uint))) - (let ((ship (try! prior-result))) - (try! (contract-call? .rockets-base authorize-pilot ship pilot)) - (ok ship))) -(define-private (add-pilots-to (ship uint)) - (fold add-pilot-via-fold (var-get employed-pilots) (ok ship))) -``` - -In order for the contract to add each pilot to a new ship, the contract must call `authorize-pilot`. However, the contract wants to perform this action on behalf of a ship the _contract_ owns, not the transaction sender. To do this, the contract uses `as-contract`. diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md b/i18n/ko/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md deleted file mode 100644 index a01e37bc04..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Resources -description: 'Resources' -sidebar_position: 8 ---- - -# External resources - - -[Clarity book](https://book.clarity-lang.org/) - -[Clarity Universe](https://stacks.org/clarity-universe) - -[Hiro Clarity tutorials](https://docs.hiro.so/tutorials) diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md b/i18n/ko/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md deleted file mode 100644 index ed65829518..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Clarity development software -description: The following tools are useful when developing Clarity smart contracts -sidebar_position: 4 ---- - -## Language Server Protocol for Clarity (including Visual Studio Code extension) - -The Language Server Protocol (LSP) defines the protocol used between an editor or IDE and a language server that provides language features like auto complete, go to definition, find all references etc. - -This makes programming in Clarity easier and much more intuitive. - -![Clarity LSP Screenshot](https://raw.githubusercontent.com/hirosystems/clarity-lsp/21b64298ca117dc41358eb9dce4605cc4a448a4c/images/screenshot.png?raw=true) - - -Clarity LSP repository is available [here](https://github.com/hirosystems/clarity-lsp). The extension for Visual Studio Code can be downloaded directly from [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=HiroSystems.clarity-lsp), but can be and older version. For a more up to date version you can also download it from [open-vsx](https://open-vsx.org/extension/hirosystems/clarity-lsp). - -## Clarity REPL - -A read—eval—print loop (REPL), also termed an interactive toplevel or language shell, is a simple, interactive computer programming environment that takes single user inputs (that is, single expressions), evaluates (executes) them, and returns the result to the user; a program written in a REPL environment is executed piecewise. - -![Clarity-repl](https://github.com/hirosystems/clarity-repl/blob/develop/docs/images/screenshot.png?raw=true) - -Instructions on how to install Clarity REPL can be found [here](https://github.com/hirosystems/clarity-repl). - -## Clarinet - -Clarinet is a Clarity runtime packaged as a command line tool, designed to facilitate smart contract understanding, development, testing and deployment. Clarinet consists of a Clarity REPL and a testing harness, which, when used together allow you to rapidly develop and test a Clarity smart contract, with the need to deploy the contract to a local devnet or testnet. - -![Clarinet](https://github.com/hirosystems/clarinet/blob/develop/docs/images/demo.gif?raw=true) - -Installation instructions, including build from source instructions can be found [here](https://github.com/hirosystems/clarinet). If you prefer you can directly download the latest compiled realease for Windows, Mac and Linux [here](https://github.com/hirosystems/clarinet/releases). - -[Clarinet 101](https://www.youtube.com/playlist?list=PL5Ujm489LoJaAz9kUJm8lYUWdGJ2AnQTb) contains multiple Clarinet video tutorials - -### Getting started with Clarinet - -You can verify you have Clarinet installed by checking its version: - -```bash -$ clarinet --version -clarinet 0.70 -``` - -More detailed information on using Clarinet is available [here](https://book.clarity-lang.org/ch07-00-using-clarinet.html). However to get you started, the following commands are important to know. - -Create a new project and enter its directory: - -```bash -clarinet new my-project && cd my-project -``` - -Create a new contract inside `my-project`: - -```bash -clarinet contract new mycoolcontract -``` - -Check the syntax of Clarity: - -```bash -clarity check -``` - -To test your contract: - -```bash -clarinet test -``` - -Enter Clarinet's console: - -```bash -clarinet console -``` diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md b/i18n/ko/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md deleted file mode 100644 index 2754709092..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Tokens -description: Learn about token support within Clarity -sidebar_position: 3 ---- - -## Introduction - -A fundamental use of blockchain technology is the representation, store, and transfer of value between users of a blockchain. Cryptocurrency is a very common use of blockchain technology, and remains one of the primary drivers of adoption of blockchain technology. Cryptocurrencies are represented by blockchain tokens: individual units of value within a given blockchain ecosystem. Blockchain tokens can extend beyond just digital currency, however, and recent developments throughout the cryptocurrency community have demonstrated potential for the use of blockchain to tokenize and represent not just money but other tangible assets. - -A blockchain token is a digital asset that can be verifiably owned by a user of a blockchain. Blockchain tokens are governed by a set of rules that are defined by either the blockchain itself (in the case of native tokens) or by a smart contract on a blockchain. Rules can vary depending on the nature and the use of the token. - -Tokens on a blockchain fall into two general categories, depending on their properties: [fungible][] or [non-fungible][]. The following sections discuss the properties of both types of tokens, and provide information about implementation of the two types of tokens on Stacks. - -## Fungible tokens - -A core property of any token on a blockchain is fungibility. A fungible token is a token that's mutually interchangable or capable of mutual substitution. In other words, one quantity or part of a fungible token can be replaced by an equal quantity or part of the same fungible token. Fungible tokens are often used to represent real-world fungible assets like currency. The STX token is an example of a fungible token. Other examples include stablecoins, tokens that represent voting rights in a DAO, or tokens that algorithmically track the price of stocks. - -Fungible tokens form one of the most important value propositions for blockchain technology, the ability to store value and exchange that value through both internal and external transactions. Because fungible tokens can be divided into smaller parts and recombined into the same value representation, they serve a great utility for transferring value between blockchain users. - -The primary fungible token on the Stacks blockchain is the native token, STX. Because the Stacks blockchain allows for the creation of \[smart contracts\]\[\], other fungible tokens can be created on the Stacks blockchain as well. [SIP-010][] specifies the standard for fungible tokens on the Stacks blockchain. This specification defines the functions and traits that a fungible token on Stacks _must_ have. This specification defines the functions and traits that a fungible token on Stacks _must_ have. - -### Understanding the fungible token standard - -The [SIP-010][] standard is an interface definition that allows Stacks applications and wallets to interact with fungible tokens in a standard way. Supporting the standard reduces complexity for token creators to get their tokens into the ecosystem. Under the [SIP-010][] standard, fungible tokens must have the following characteristics: - -- Ability to transfer a specified amount of the token to a recipient (`transfer`). The recipient is required to be a Stacks principal. -- Ability to obtain the human-readable name of the token (`get-name`). -- Ability to obtain a short name (ticker symbol) for the token (`get-symbol`). -- Ability to get the number of decimals in the token representation (`get-decimals`). This is used to construct a representation of the token that humans would be familiar dealing with. For example, the US dollar has 2 decimals, if the base unit is cents. -- Ability to get the balance of the token for a particular Stacks principal (`get-balance-of`). -- Ability to get the total supply of the token (`get-total-supply`). -- A URI to metadata associated with the token (`get-token-uri`). This can resolve to off-chain metadata about the token or contract, such as an image icon for the token or a description. - -## Non-fungible tokens (NFTs) - -Non-fungible tokens (NFTs) are a type of token that are not interchangeable. NFTs have unique traits (usually in the form of attached metadata) that restrict the abillity to replace them with identical tokens. An NFT is a token that is unique, such as a piece of art, or ownership rights to a real-world asset such as a house. - -NFTs alone don't have an inherent value, like a currency. The value of an NFT is derived from the assets that the NFT represents. The use of NFTs are myriad, including digital art, collectibles, domain names, and representation of ownership of content rights. NFTs can be used as digital certificates that track the authenticty of real world items, or digitize the ownership rights to property. - -As with fungible tokens, NFTs on the Stacks blockchain are created with smart contracts. [SIP-009][] specifies the standard for NFTs on the Stacks blockchain. This specification defines the functions and traits that an NFT _must_ have, but most NFTs have more functions or traits attached than those solely described by the specification. By complying with this standard, non-fungible tokens on Stacks can be easily represented by wallets that support Stacks. - -### Understanding the non-fungible token standard - -The [SIP-009][] standard is an interface definition that the Stacks ecosystem aligned on. With support for this standard across wallets and tools, it becomes easy to interact with NFTs. Under the [SIP-009][] standard, NFT contract must have the following characteristics: - -- Ability to obtain the last token identifier (`get-last-token-id`). This id represents the upper limit of NFTs issued by the contract. -- A URI to metadata associated with a specific token identifier. (`get-token-uri`). This URI could resolve to a JSON file with information about the creator, associated media files, descriptions, signatures, and more. -- Ability to verify the owner for a given token identifier (`get-owner`). The owner resolves to a [Stacks principal](principals). -- Ability to transfer an NFT to a recipient (`transfer`). The recipient is required to be a Stacks principal. - -## Further reading - -- [The Difference Between Fungible and Non-Fungible Tokens](https://101blockchains.com/fungible-vs-non-fungible-tokens/) -- [Explain It Like I Am 5: NFTs](https://messari.io/article/explain-it-like-i-am-5-nfts) - -[fungible]: #fungible-tokens -[non-fungible]: #non-fungible-tokens-nfts -[SIP-010]: https://github.com/hstove/sips/blob/feat/sip-10-ft/sips/sip-010/sip-010-fungible-token-standard.md -[SIP-009]: https://github.com/stacksgov/sips/blob/main/sips/sip-009/sip-009-nft-standard.md diff --git a/i18n/ko/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md b/i18n/ko/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md deleted file mode 100644 index fc4765aa0c..0000000000 --- a/i18n/ko/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md +++ /dev/null @@ -1,301 +0,0 @@ ---- -title: Clarity Values -description: Learn how to deal with Clarity Values in JavaScript -sidebar_position: 2 ---- - -## Introduction - -The Clarity language makes use of a strong static 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/hirosystems/stacks.js/tree/master/packages/transactions) library makes this easy, as we will demonstrate below. - -## Clarity Types - -Please see the following page for information on [Clarity Types](../write-smart-contracts/clarity-language/language-types). - -## Constructing Clarity Values and accessing their data - -Clarity values can be constructed with functions provided by the [@stacks/transactions](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library. These functions simply output javascript objects that contain a value and a numerical representation of the Clarity type information. The Clarity types are encoded as follows: - -```typescript -export enum ClarityType { - Int = 0, - UInt = 1, - Buffer = 2, - BoolTrue = 3, - BoolFalse = 4, - PrincipalStandard = 5, - PrincipalContract = 6, - ResponseOk = 7, - ResponseErr = 8, - OptionalNone = 9, - OptionalSome = 10, - List = 11, - Tuple = 12, - StringASCII = 13, - StringUTF8 = 14, -} -``` - -`ClarityValue` objects can be serialized and included in transactions that interact with published Clarity contracts. - -Here are examples of how to construct each type of Clarity value, and how to access its data if it has any: - -### Booleans - -```typescript -const t = trueCV(); -// { type: ClarityType.BoolTrue } - -const f = falseCV(); -// { type: ClarityType.BoolFalse } -``` - -Boolean Clarity Values don't contain any underlying data. They are simply objects with `type` information. - -### Optional Values - -```typescript -const nothing: NoneCV = noneCV(); -// { type: ClarityType.OptionalNone } - -const something: SomeCV = someCV(trueCV()); -// { type: ClarityType.OptionalSome, value: { type: 4 } } -``` - -Optional Clarity Values can either be nothing (an empty type that has no data), or something (a wrapped value). - -If you are dealing with a function or contract function that returns an `OptionalCV`, you should always check what type it is before trying to access its value. - -```typescript -const maybeVal: OptionalCV = await callReadOnlyFunction(...); - -if (maybeVal.type === ClarityType.OptionalSome) { - console.log(maybeVal.value); -} else if (maybeVal.type === ClarityType.OptionalNone) { - // deal with `none` value -} -``` - -### Buffers - -```typescript -const buffer = Buffer.from('foo'); -const bufCV: BufferCV = bufferCV(buffer); -// { type: ClarityType.Buffer, buffer: } -``` - -### Integers - -Clarity supports both integers and unsigned integers. - -```typescript -const i: IntCV = intCV(-10); -// { type: ClarityType.Int, value: BN { ... } } - -const u: UIntCV = uintCV(10); -// { type: ClarityType.UInt, value: BN { ... } } -``` - -Clarity value ints store their underlying data as `BigNum` values from the [bn.js](https://github.com/indutny/bn.js/) library. - -In order to display/print Clarity (u)int values, use the `cvToString(val)` method. - -If you wish to perform arithmetic operations using Clarity (u)int values, you must use methods from the `BigNum` api on their underlying `BigNum` values, and the construct a new Clarity value out of the result. For example: - -```typescript -const x = intCV(1); -const y = intCV(2); - -x.value.add(y.value); -// 3 -``` - -### Strings - -```typescript -const ascii: StringAsciiCV = stringAsciiCV('hello world'); -// { type: ClarityType.StringASCII, data: 'hello world' } - -const utf8: StringUtf8CV = stringUtf8CV('hello 🌾'); -// { type: ClarityType.StringUTF8, data: 'hello 🌾' } -``` - -Clarity supports both ascii and utf8 strings. - -### Principals - -```typescript -const address = 'SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B'; -const contractName = 'contract-name'; - -const spCV = standardPrincipalCV(address); -// { -// type: ClarityType.PrincipalStandard -// address: { -// type: StacksMessageType.Address, -// version: AddressVersion.MainnetSingleSig, -// hash160: "SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B" -// } -// } - -const cpCV = contractPrincipalCV(address, contractName); -// { -// type: ClarityType.PrincipalContract, -// contractName: { -// type: StacksMessageType.LengthPrefixedString, -// content: 'contract-name', -// lengthPrefixBytes: 1, -// maxLengthBytes: 128, -// }, -// address: { -// type: StacksMessageType.Address, -// version: AddressVersion.MainnetSingleSig, -// hash160: "SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B" -// } -// } -``` - -Both kinds of Clarity principal values contain `type` information and an `address` object. Contract principals also contain a `contractName`. - -### Response Values - -```typescript -const errCV = responseErrorCV(trueCV()); -// { type: ResponseErr, value: { type: ClarityType.BoolTrue } } - -const okCV = responseOkCV(falseCV()); -// { type: ResponseOk, value: { type: ClarityType.BoolFalse } } -``` - -Response Clarity Values will either have the type `ClarityType.ResponseOk` or `ClarityType.ResponseErr`. They both contain a Clarity Value. Often this value will be an integer error code if the response is an `Error`. - -### Tuples - -```typescript -const tupCV = tupleCV({ - a: intCV(1), - b: trueCV(), - c: falseCV(), -}); -// { -// type: ClarityType.Tuple, -// data: { -// a: { type: ClarityType.Int, value: BN { ... } }, -// b: { type: ClarityType.BoolTrue }, -// c: { type: ClarityType.BoolFalse }, -// } -// } - -console.log(tupCV.data['b']); -// { type: ClarityType.BoolTrue } -``` - -Tuples in Clarity are typed and contain named fields. The tuple above, for example, contains three fields with the names **a**, **b** and **c**, and the types of their values are `Int`, `Boolean` and `Boolean`, respectively. - -Clarity tuples are represented in JavaScript as objects and a tuple's data can be accessed by its `data` field, where the underlying JS object is stored. - -### Lists - -```typescript -const l = listCV([trueCV(), falseCV()]); -// { type: ClarityType.List, list: [{ type: ClarityType.BoolTrue }] } - -console.log(l.list[0]); -// { type: ClarityType.BoolTrue } -``` - -Lists, in Clarity, are homogeneous, meaning they can only contain elements of a singular (Clarity) type. Make sure to avoid constructing lists that have elements of multiple types. - -A Clarity lists underlying data can be accessed via its `list` field. - -## Using Clarity Values - -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](../understand-stacks/transactions#construction). - -## Utilizing Clarity Values from Transaction Responses - -`Read-only` Clarity functions can return Clarity values as a response. These `read-only` functions can be accessed easily in JavaScript via the [`callReadOnlyFunction()`](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions#calling-read-only-contract-function) function included in `@stacks/transactions`, which returns a `ClarityValue`. - -As mentioned above, `ClarityValues` are simply javascript objects containing a value and its associated Clarity type information. These object types are defined [here](https://github.com/hirosystems/stacks.js/tree/1f2b5fd8bdf1c2b5866e8171163594d7708a8c7a/packages/transactions/src/clarity/types). - -When you are calling a `read-only` contract function, you will always know what type the function will return, since functions in Clarity are strongly typed. - -It is common for Clarity functions to return values wrapped in a `Response`, in order to indicate if there was success or an error. - -Since every `ClarityValue` has a `type` field, the type of the result of a `read-only` function call can be checked and acted upon like so: - -```typescript -const contractAddress = 'ST3KC0MTNW34S1ZXD36JYKFD3JJMWA01M55DSJ4JE'; -const contractName = 'kv-store'; -const functionName = 'get-value'; -const buffer = bufferCVFromString('foo'); -const network = new StacksTestnet(); // for mainnet, use `StacksMainnet()` -const senderAddress = 'ST2F4BK4GZH6YFBNHYDDGN4T1RKBA7DA1BJZPJEJJ'; - -const options = { - contractAddress, - contractName, - functionName, - functionArgs: [buffer], - network, - senderAddress, -}; - -// make a read-only call to a contract function that -// returns a Response -const result: ResponseCV = await callReadOnlyFunction(options); - -if (result.type === ClarityType.ResponseOk) { - console.log(cvToString(result.value)); -} else if (result.type === ClarityType.ResponseErr) { - throw new Error(`kv-store contract error: ${result.value.data}`); -} -``` - -### ClarityValues to/from Hex - -If you receive a response from a transaction in the form of a `hex` string, you can deserialize it into a Clarity value like so: - -```javascript -import { hexToCV } from '@stacks/transactions'; - -let cv = hexToCV('hex_string'); -``` - -Similarly, you can convert a Clarity value to `hex` string like so: - -```javascript -import { cvToHex, trueCV } from '@stacks/transactions'; - -let trueHex = cvToHex(trueCV()); -``` - -## Debugging Clarity Values - -Sometimes you might receive a Clarity value that you were not expecting. Logging the value to your console won't always prove to be useful, unless you have memorized the Clarity value type enum values. - -In order to figure out what kind of value you are dealing with, you can use the `cvToString()` function to convert the Clarity value to a more easily readable string. - -For example, calling `cvToString()` on a large `tuple` might yield something like: - -``` -(tuple - (a -1) - (b u1) - (c 0x74657374) - (d true) - (e (some true)) - (f none) - (g SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B) - (h SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B.test) - (i (ok true)) - (j (err false)) - (k (list true false)) - (l (tuple (a true) (b false))) - (m "hello world") - (n u"hello \u{1234}"))` -``` diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/blockchain/index.md b/i18n/pt/docusaurus-plugin-content-docs/current/blockchain/index.md deleted file mode 100644 index 13db24ec30..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/blockchain/index.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: Blockchain -description: Stacks Blockchain -sidebar_position: 6 ---- - -Below is a guide to start working locally with the Stacks Blockchain. - -Code repository is [here](https://github.com/stacks-network/stacks-blockchain). - -## Getting started with the Stacks Blockchain - -### Download and build stacks-blockchain - -The first step is to ensure that you have Rust and the support software installed. - -```bash -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -``` - -:::info -For building on Windows, follow the rustup installer instructions at https://rustup.rs/ -::: - -From there, you can clone the Stacks Blockchain repository: - -```bash -git clone --depth=1 https://github.com/stacks-network/stacks-blockchain.git - -cd stacks-blockchain -``` - -Then build the project: - -```bash -cargo build -``` - -Run the tests: - -```bash -cargo test testnet -- --test-threads=1 -``` - -### Encode and sign transactions - -Here, we have generated a keypair that will be used for signing the upcoming transactions: - -```bash -cargo run --bin blockstack-cli generate-sk --testnet - -# Output -# { -# secretKey: "b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001", -# publicKey: "02781d2d3a545afdb7f6013a8241b9e400475397516a0d0f76863c6742210539b5", -# stacksAddress: "ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH" -# } -``` - -This keypair is already registered in the `testnet-follower-conf.toml` file, so it can be used as presented here. - -We will interact with the following simple contract `kv-store`. In our examples, we will assume this contract is saved to `./kv-store.clar`: - -```scheme -(define-map store { key: (string-ascii 32) } { value: (string-ascii 32) }) - -(define-public (get-value (key (string-ascii 32))) - (match (map-get? store { key: key }) - entry (ok (get value entry)) - (err 0))) - -(define-public (set-value (key (string-ascii 32)) (value (string-ascii 32))) - (begin - (map-set store { key: key } { value: value }) - (ok true))) -``` - -We want to publish this contract on chain, then issue some transactions that interact with it by setting some keys and getting some values, so we can observe read and writes. - -Our first step is to generate and sign, using your private key, the transaction that will publish the contract `kv-store`. To do that, we will use the subcommand `blockstack-cli` that has the following usage: - -```bash -blockstack-cli (options) publish [publisher-secret-key-hex] [fee-rate] [nonce] [contract-name] [file-name.clar] -``` - -With the following arguments: - -```bash -cargo run --bin blockstack-cli publish b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 515 0 kv-store ./kv-store.clar --testnet -``` - -The `515` is the transaction fee, denominated in microSTX. Right now, the testnet requires one microSTX per byte minimum, and this transaction should be less than 515 bytes. The third argument `0` is a nonce, that must be increased monotonically with each new transaction. - -This command will output the **binary format** of the transaction. In our case, we want to pipe this output and dump it to a file that will be used later in this tutorial. - -```bash -cargo run --bin blockstack-cli publish b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 515 0 kv-store ./kv-store.clar --testnet | xxd -r -p > tx1.bin -``` - -### Run the testnet - -You can observe the state machine in action locally by running: - -```bash -cargo stacks-node start --config=./testnet/stacks-node/conf/testnet-follower-conf.toml -``` - -`testnet-follower-conf.toml` is a configuration file that you can use for setting genesis balances or configuring Event observers. You can grant an address an initial account balance by adding the following entries: - -``` -[[ustx_balance]] -address = "ST2VHM28V9E5QCRD6C73215KAPSBKQGPWTEE5CMQT" -amount = 100000000 -``` - -The `address` field is the Stacks testnet address, and the `amount` field is the number of microSTX to grant to it in the genesis block. The addresses of the private keys used in the tutorial below are already added. - -### Publish your contract - -Assuming that the testnet is running, we can publish our `kv-store` contract. - -In another terminal (or file explorer), you can move the `tx1.bin` generated earlier, to the mempool: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx1.bin http://localhost:20443/v2/transactions -``` - -In the terminal window running the testnet, you can observe the state machine's reactions. - -### Reading from / Writing to the contract - -Now that our contract has been published on chain, let's try to submit some read / write transactions. We will start by trying to read the value associated with the key `foo`. - -To do that, we will use the subcommand: - -```bash -cargo run --bin blockstack-cli contract-call --help -``` - -With the following arguments: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 1 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store get-value -e \"foo\" --testnet | xxd -r -p > tx2.bin -``` - -`contract-call` generates and signs a contract-call transaction. - -We can submit the transaction by moving it to the mempool path: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx2.bin http://localhost:20443/v2/transactions -``` - -Similarly, we can generate a transaction that would be setting the key `foo` to the value `bar`: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 2 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store set-value -e \"foo\" -e \"bar\" --testnet | xxd -r -p > tx3.bin -``` - -And submit it by moving it to the mempool path: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx3.bin http://localhost:20443/v2/transactions -``` - -Finally, we can issue a third transaction, reading the key `foo` again, for ensuring that the previous transaction has successfully updated the state machine: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 3 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store get-value -e \"foo\" --testnet | xxd -r -p > tx4.bin -``` - -And submit this last transaction by moving it to the mempool path: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx4.bin http://localhost:20443/v2/transactions -``` - -Congratulations, you can now [write your own smart contracts with Clarity](write-smart-contracts/). diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/blockchain/networks.md b/i18n/pt/docusaurus-plugin-content-docs/current/blockchain/networks.md deleted file mode 100644 index fe9725352c..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/blockchain/networks.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Stacks Blockchain Networks -description: Stacks Blockchain Networks -sidebar_position: 3 ---- - -### Stacks Blockchain Networks - -- [x] **Krypton** is a Stacks 2 testnet with a fixed, two-minute block time, called `regtest`. Regtest is generally unstable for regular use, and is reset often. See the [regtest documentation](understand-stacks/testnet) for more information on using regtest. - -- [x] **Testnet** (old Xenon) is the Stacks 2 public testnet, which runs PoX against the Bitcoin testnet. It is the full implementation of the Stacks 2 blockchain, and should be considered a stable testnet for developing Clarity smart contracts. See the [testnet documentation](understand-stacks/testnet) for more information on the public testnet. - -- [x] **Mainnet** is the fully functional Stacks 2 blockchain, see the [Stacks overview](understand-stacks/) for information on running a Stacks node, mining, stacking, and writing Clarity smart contracts. diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md b/i18n/pt/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md deleted file mode 100644 index 6f2664be72..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Stacks Blockchain API -description: Interacting with the Stacks 2.0 Blockchain via API -sidebar_position: 4 ---- - -## Introduction - -:::tip API Documentation Official API Documentation is available [here](https://stacks-network.github.io/stacks-blockchain/). ::: - - -The Stacks 2.0 Blockchain API allows you to query the Stacks 2.0 blockchain and interact with smart contracts. It was built to maintain pageable materialized views of the Stacks 2.0 Blockchain. - -:::caution The RESTful API is developed by Hiro. Hiro also hosts a public API node for easy onboarding. Using it requires you to trust the hosted server, but provides a faster onboarding experience. You can [run your own API server](https://docs.hiro.so/get-started/running-api-node) ::: - -The RESTful JSON API can be used without any authorization. The basepath for the API is: - -```bash -# for mainnet, replace `testnet` with `mainnet` -https://stacks-node-api.testnet.stacks.co/ -``` - -:::note This documentation only covers endpoints that are exposed on a Stacks node, referred to as the RPC API. For full documentation on the RESTful API, check out the [Hiro's API reference](https://docs.hiro.so/api). ::: - -### Stacks Node RPC API - -The [stacks-node implementation](https://github.com/stacks-network/stacks-blockchain/) exposes JSON RPC endpoints. - -All `/v2/` routes a proxied to a Hiro-hosted Stacks Node. For a trustless architecture, you should make these requests to a self-hosted node. - -## Proxied Stacks Node RPC API endpoints - -The Stacks 2.0 Blockchain API is centrally hosted. However, every running Stacks node exposes an RPC API, which allows you to interact with the underlying blockchain. Instead of using a centrally hosted API, you can directly access the RPC API of a locally hosted Node. - -:::tip The Stacks Blockchain API proxies to Node RPC endpoints -::: - -While the Node RPC API doesn't give the same functionality as the hosted Stacks 2.0 Blockchain API, you get similar functionality in a way that is scoped to that specific node. The RPC API includes the following endpoints: - -- [POST /v2/transactions](https://docs.hiro.so/api#operation/post_core_node_transactions) -- [GET /v2/contracts/interface/{contract_address}/{contract_name}](https://docs.hiro.so/api#operation/get_contract_interface) -- [POST /v2/map_entry/{contract_address}/{contract_name}/{map_name}](https://docs.hiro.so/api#operation/get_contract_data_map_entry) -- [GET /v2/contracts/source/{contract_address}/{contract_name}](https://docs.hiro.so/api#operation/get_contract_source) -- [GET /v2/accounts/{principal}](https://docs.hiro.so/api#operation/get_account_info) -- [POST /v2/contracts/call-read/{contract_address}/{contract_name}/{function_name}](https://docs.hiro.so/api#operation/call_read_only_function) -- [GET /v2/fees/transfer](https://docs.hiro.so/api#operation/get_fee_transfer) -- [GET /v2/info](https://docs.hiro.so/api#operation/get_core_api_info) - -:::caution If you run a local node, it exposes an HTTP server on port `20443`. The info endpoint would be `localhost:20443/v2/info`. ::: diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md b/i18n/pt/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md deleted file mode 100644 index 71e3542302..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Stacks Releases -description: Stacks Blockchain Releases -sidebar_position: 2 ---- - -:::info -This page needs contributions. Help us improve it. -::: - -### Stacks Blockchain Releases - -All releases are published [here](https://github.com/stacks-network/stacks-blockchain/releases). Most important ones are described below. - -### Stacks 2.1 - -Scheduled for release at the end of 2022. - -More information on [what to expect with Stacks 2.1](https://stacks.org/stacks-21-what-to-expect). - -#### Stacks 2.05 -Activated on [Bitcoin block 713000](https://explorer.stacks.co/txid/0xece8e369310b5ff9b92ef11181ae0d2457ac0c821376d4a96c4998763e22ad04?chain=mainnet). - -This breaking change enables storage cost for list to be based on actual length and change in number of indexed I/O operations. More info on this [blog post](https://www.stacks.org/stacks-2-05?ref=docs-website). - -#### Stacks 2.0 -Activated on January 14th 2021 - -This hard fork enables Stacking, Clarity smart contracts, scalable transactions, and also building directly on Bitcoin. More info [here](https://forum.stacks.org/t/path-to-mainnet-for-stx-holders-things-to-know-ahead-of-stacks-2-0/11529). - -#### Stacks Genesis -Released on 2018, October 30th UTC+6 at Bitcoin block height 547921 - -This hard fork addresses registration of digital assets with Stacks token and also distribution of Stacks token to the existing purchasers. More info [here](https://blog.blockstack.org/the-launch-of-the-stacks-genesis-block/?ref=docs-website). - diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md b/i18n/pt/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md deleted file mode 100644 index f7949ceb15..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Deploy tips -description: Learn some common methods for deploying your application. ---- - -## Introduction - -Stacks applications are web applications that authenticate users with Stacks Auth and store data with Gaia. Both of these technologies can be accessed on the client side. As such, Stacks apps tend to be simple in design and operation, since in many cases, they don’t have to host anything besides the application’s assets. - -## Where to deploy your application - -Before users can interact with your application, you must deploy it on a server that is accessible over the internet. Deploying requires that you: - -- Configure or customize the files in the `public` directory. -- Build your application site for deployment. -- Copy your generated application files to your production server. - -If you first populated your application with the Stacks application generator, your application contains the starting blocks for configuring, building, and deploying your app. For example, the React template builds out a scaffolding with the following building blocks. - -| File or Directory | Description | -| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| node_modules/react-scripts | A set of scripts for that helps you kick off React projects without configuring, so you do not have to set up your project by yourself. | -| package.json | Contains a scripts section that includes a reference to the react-scripts, which are a dependency. This script creates a build directory containing your files for deployment. | -| public/favicon.ico | An example shortcut icon. | -| public/index.html | An entry page for an application. | -| public/manifest.json | A JSON file that describes your web application to the browser. | -| cors | Contains example deployment files for cross-origin request configuration. | - -If you use the generator to build JavasScript or Vue scaffolding, your project configuration files will be different. - -Regardless of which scaffolding you use, you must customize and extend this basic scaffolding as needed by your application. For example, you may want to add more properties to the `manifest.json` file. Since every application is different, Stacks Auth cannot give you specific instructions on how to do this. The steps you take are specific to your application. - -## Stacks Authentication and deployment - -When your application authenticates users with Stacks, the Stacks Wallet at on URL requests a resource (the app manifest) from your DApp. A request for a resource outside of the origin (the Stacks Wallet) 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 (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) - -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 Stacks 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`: - -```html -Access-Control-Allow-Origin: * Access-Control-Allow-Headers: "X-Requested-With, Content-Type, Origin, Authorization, Accept, Client-Security-Token, Accept-Encoding" Access-Control-Allow-Methods: "POST, GET, OPTIONS, DELETE, PUT" -``` - -Consult the documentation for your hosting service to learn how to configure CORS on that service. - -## Deployment and Radiks - -If you are deploying a Stacks application that uses [Radiks](https://github.com/stacks-network/radiks), your deployment includes a server and a database component. You must take this into account when deploying your application. You may want to choose a service such as [Heroku](https://www.heroku.com) or [Digital Ocean](https://www.digitalocean.com) if your app uses Radiks. diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/build-apps/index.md b/i18n/pt/docusaurus-plugin-content-docs/current/build-apps/index.md deleted file mode 100644 index 23714cba5d..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/build-apps/index.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Build apps with Stacks -description: Authenticate users, sign transactions and store data with the Stacks blockchain -sidebar_position: 3 -sidebar_label: Build apps ---- - -## Introduction - -Apps built with the Stacks blockchain give users control over their digital identities, assets, and data. - -Unlike most cloud-based apps, they are "decentralized" since they don't depend on any centralized platform, server, or database to function. Rather, they use the Stacks blockchain to authenticate users and facilitate read and write requests for them without any single point of failure or trust. - -Stacks provides three main functions for building apps: - - - -- **Authentication**: Register and sign users in with identities on the Stacks blockchain -- **Transaction signing**: Prompt users to sign and broadcast transactions to the Stacks blockchain -- **Data storage**: Save and retrieve data for users with [Gaia](../gaia) - - -All three of these integrations can be used together to create powerful new user experiences that rival or exceed those of traditional apps—all while protecting your users' digital rights. - -While integration is possible for any type of app, most of the resources available here are for web developers experienced with JavaScript. See [Hiro developer docs](https://docs.hiro.so) for more information on the available app development libraries for Stacks. - -## [References](references) - -[Authentication](references/authentication) - -[BNS](references/bns) - -[Gaia](../gaia/) - diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md b/i18n/pt/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md deleted file mode 100644 index 727b4e2163..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: NoCodeClarity -description: Launch apps for the Stacks blockchain through no code platforms like Bubble. ---- - -## Introduction - -![](https://d1muf25xaso8hp.cloudfront.net/https%3A%2F%2Fs3.amazonaws.com%2Fappforest_uf%2Ff1653407713550x759333524803365600%2FLogo%2520of%2520NoCodeClarity.png?w=179&h=84&auto=compress&dpr=1&fit=max) - -[NoCodeClarity](https://nocodeclarity.com) allows people to create applications for the Stacks blockchain without coding. - -## Stacks Plug-In on bubble - -The [Stacks-No-Code-Plugin](https://bubble.io/plugin/the-stacks-plug-in-1645467277638x949839693014368300) released in May 2022 and it can easily be installed on Bubble with a few clicks allowing users to deploy applications with no coding knowledge. [Bubble](https://bubble.io/blog/explaining-bubble-to-investors/) is the first No Code platform that the Stacks plugin launched on. More platforms are in the roadmap of NoCodeClarity, founded by Christopher Perceptions and Sergio Gongora. The Stacks plugin was created through the support of the Stacks Foundation via a grant in January 2022 and NoCodeClarity was awarded a $100,000 grant in June 2022 to expand the roadmap. - -Additional [instructions](https://s3.amazonaws.com/appforest_uf/f1654202471526x991633667675927800/Instructions%20v2.docx.pdf) are also available. Tutorials and step by step guides will be released soon. - -The Stacks-No-Code-Plugin code is [publicly available on Github](https://github.com/nocodeclarity/Stacks-No-Code-Plugin). - -![](/img/bubble-stacks-plugin.png) - -## Demo page - -A demo page is available [here](https://test-stacks-plugin.bubbleapps.io/version-test). - -## NoCodeClarity videos - -NodeCodeClarity has their own [youtube channel](https://www.youtube.com/channel/UC9Ep0VQ-GQ-yDzt-wmIElRA). - -Videos: - -* [NoCodeClarity Setup](https://www.youtube.com/watch?v=WanXlpBGl0w) -* [NoCodeClarity - Part 1 of the plugin](https://www.youtube.com/watch?v=o6d3hrzNqVI&t=248s) -* [NoCodeClarity - Part 2 of the plugin](https://www.youtube.com/watch?v=0rzMdsrRg80) -* [Sneak Peek of the No Code Stacks Wallet Template](https://www.youtube.com/watch?v=Xe6Yv0rF6XM) \ No newline at end of file diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md b/i18n/pt/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md deleted file mode 100644 index 86a8568663..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Authentication -description: Register and sign in users with identities on the Stacks blockchain ---- - -## Introduction - -This guide explains how authentication is performed on the Stacks blockchain. - -Authentication provides a way for users to identify themselves to an app while retaining complete control over their credentials and personal details. It can be integrated alone or used in conjunction with [transaction signing](https://docs.hiro.so/get-started/transactions#signature-and-verification) and [data storage](https://docs.stacks.co/build-apps/references/gaia), for which it is a prerequisite. - -Users who register for your app can subsequently authenticate to any other app with support for the [Blockchain Naming System](bns) and vice versa. - -## How it works - -The authentication flow with Stacks is similar to the typical client-server flow used by centralized sign in services (for example, OAuth). However, with Stacks the authentication flow happens entirely client-side. - -An app and authenticator, such as [the Stacks Wallet](https://www.hiro.so/wallet/install-web), communicate during the authentication flow by passing back and forth two tokens. The requesting app sends the authenticator an `authRequest` token. Once a user approves authentication, the authenticator responds to the app with an `authResponse` token. - -These tokens are are based on [a JSON Web Token (JWT) standard](https://tools.ietf.org/html/rfc7519) with additional support for the `secp256k1` curve used by Bitcoin and many other cryptocurrencies. They are passed via URL query strings. - -When a user chooses to authenticate an app, it sends the `authRequest` token to the authenticator via a URL query string with an equally named parameter: - -`https://wallet.hiro.so/...?authRequest=j902120cn829n1jnvoa...` - -When the authenticator receives the request, it generates an `authResponse` token for the app using an _ephemeral transit key_ . The ephemeral transit key is just used for the particular instance of the app, in this case, to sign the `authRequest`. - -The app stores the ephemeral transit key during request generation. The public portion of the transit key is passed in the `authRequest` token. The authenticator uses the public portion of the key to encrypt an _app private key_ which is returned via the `authResponse`. - -The authenticator generates the app private key from the user's _identity address private key_ and the app's domain. The app private key serves three functions: - -1. It is used to create credentials that give the app access to a storage bucket in the user's Gaia hub -2. It is used in the end-to-end encryption of files stored for the app in the user's Gaia storage. -3. It serves as a cryptographic secret that apps can use to perform other cryptographic functions. - -Finally, the app private key is deterministic, meaning that the same private key will always be generated for a given Stacks address and domain. - -The first two of these functions are particularly relevant to [data storage with Stacks.js](https://docs.stacks.co/docs/gaia). - -## Key pairs - -Authentication with Stacks makes extensive use of public key cryptography generally and ECDSA with the `secp256k1` curve in particular. - -The following sections describe the three public-private key pairs used, including how they're generated, where they're used and to whom private keys are disclosed. - -### Transit private key - -The transit private is an ephemeral key that is used to encrypt secrets that need to be passed from the authenticator to the app during the authentication process. It is randomly generated by the app at the beginning of the authentication response. - -The public key that corresponds to the transit private key is stored in a single element array in the `public_keys` key of the authentication request token. The authenticator encrypts secret data such as the app private key using this public key and sends it back to the app when the user signs in to the app. The transit private key signs the app authentication request. - -### Identity address private key - -The identity address private key is derived from the user's keychain phrase and is the private key of the Stacks username that the user chooses to use to sign in to the app. It is a secret owned by the user and never leaves the user's instance of the authenticator. - -This private key signs the authentication response token for an app to indicate that the user approves sign in to that app. - -### App private key - -The app private key is an app-specific private key that is generated from the user's identity address private key using the `domain_name` as input. - -The app private key is securely shared with the app on each authentication, encrypted by the authenticator with the transit public key. Because the transit key is only stored on the client side, this prevents a man-in-the-middle attack where a server or internet provider could potentially snoop on the app private key. diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/build-apps/references/bns.md b/i18n/pt/docusaurus-plugin-content-docs/current/build-apps/references/bns.md deleted file mode 100644 index b4d93658df..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/build-apps/references/bns.md +++ /dev/null @@ -1,238 +0,0 @@ ---- -title: Blockchain Naming System -description: Binds Stacks usernames to off-chain state ---- - -Blockchain Naming System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of control. - -The Stacks V1 blockchain implemented BNS through first-order name operations. In Stacks V2, BNS is instead implemented through a smart-contract loaded during the genesis block. - -Names in BNS have three properties: - -- **Names are globally unique.** The protocol does not allow name collisions, and all well-behaved nodes resolve a given name to the same state. -- **Names are human-meaningful.** Each name is chosen by its creator. -- **Names are strongly owned.** Only the name's owner can change the state it resolves to. Specifically, a name is owned by one or more ECDSA private keys. - -The Stacks blockchain insures that each node's BNS view is synchronized to all of the other nodes in the world, so queries on one node will be the same on other nodes. Stacks blockchain nodes allow a name's owner to bind up to 40Kb of off-chain state to their name, which will be replicated to all other Stacks blockchain nodes via a P2P network. - -The biggest consequence for developers is that in BNS, reading name state is fast and cheap but writing name state is slow and expensive. This is because registering and modifying names requires one or more transactions to be sent to the underlying blockchain, and BNS nodes will not process them until they are sufficiently confirmed. Users and developers need to acquire and spend the requisite cryptocurrency (STX) to send BNS transactions. - -## Motivation behind naming systems - -We rely on naming systems in everyday life, and they play a critical role in many different applications. For example, when you look up a friend on social media, you are using the platform's naming system to resolve their name to their profile. When you look up a website, you are using the Domain Name Service to resolve the hostname to its host's IP address. When you check out a Git branch, you are using your Git client to resolve the branch name to a commit hash. When you look up someone's PGP key on a keyserver, you are resolving their key ID to their public key. - -What kinds of things do we want to be true about names? In BNS, names are globally unique, names are human-meaningful, and names are strongly owned. However, if you look at these examples, you'll see that each of them only guarantees _two_ of these properties. This limits how useful they can be. - -- In DNS and social media, names are globally unique and human-readable, but not strongly owned. The system operator has the final say as to what each names resolves to. - - - **Problem**: Clients must trust the system to make the right choice in what a given name resolves to. This includes trusting that no one but the system administrators can make these changes. - -- In Git, branch names are human-meaningful and strongly owned, but not globally unique. Two different Git nodes may resolve the same branch name to different unrelated repository states. - - - **Problem**: Since names can refer to conflicting state, developers have to figure out some other mechanism to resolve ambiguities. In Git's case, the user has to manually intervene. - -- In PGP, names are key IDs. They are are globally unique and cryptographically owned, but not human-readable. PGP key IDs are derived from the keys they reference. - - **Problem**: These names are difficult for most users to remember since they do not carry semantic information relating to their use in the system. - -BNS names have all three properties, and none of these problems. This makes it a powerful tool for building all kinds of network applications. With BNS, we can do the following and more: - -- Build domain name services where hostnames can't be hijacked. -- Build social media platforms where user names can't be stolen by phishers. -- Build version control systems where repository branches do not conflict. -- Build public-key infrastructure where it's easy for users to discover and remember each other's keys. - -## Organization of BNS - -BNS names are organized into a global name hierarchy. There are three different layers in this hierarchy related to naming: - -- **Namespaces**. These are the top-level names in the hierarchy. An analogy to BNS namespaces are DNS top-level domains. Existing BNS namespaces include `.id`, `.podcast`, and `.helloworld`. All other names belong to exactly one namespace. Anyone can create a namespace, but in order for the namespace to be persisted, it must be _launched_ so that anyone can register names in it. Namespaces are not owned by their creators. - -- **BNS names**. These are names whose records are stored directly on the blockchain. The ownership and state of these names are controlled by sending blockchain transactions. Example names include `verified.podcast` and `muneeb.id`. Anyone can create a BNS name, as long as the namespace that contains it exists already. - -- **BNS subdomains**. These are names whose records are stored off-chain, but are collectively anchored to the blockchain. The ownership and state for these names lives within the P2P network data. While BNS subdomains are owned by separate private keys, a BNS name owner must broadcast their subdomain state. Example subdomains include `jude.personal.id` and `podsaveamerica.verified.podcast`. Unlike BNS namespaces and names, the state of BNS subdomains is _not_ part of the blockchain consensus rules. - -A feature comparison matrix summarizing the similarities and differences between these name objects is presented below: - -| Feature | **Namespaces** | **BNS names** | **BNS Subdomains** | -| -------------------------------------- | -------------- | ------------- | ------------------ | -| Globally unique | X | X | X | -| Human-meaningful | X | X | X | -| Owned by a private key | | X | X | -| Anyone can create | X | X | [1] | -| Owner can update | | X | [1] | -| State hosted on-chain | X | X | | -| State hosted off-chain | | X | X | -| Behavior controlled by consensus rules | X | X | | -| May have an expiration date | | X | | - -[1] Requires the cooperation of a BNS name owner to broadcast its transactions - -## Namespaces - -Namespaces are the top-level naming objects in BNS. - -They control a few properties about the names within them: - -- How expensive they are to register -- How long they last before they have to be renewed -- Who (if anyone) receives the name registration fees -- Who is allowed to seed the namespace with its initial names. - -At the time of this writing, by far the largest BNS namespace is the `.id` namespace. Names in the `.id` namespace are meant for resolving user identities. Short names in `.id` are more expensive than long names, and have to be renewed by their owners every two years. Name registration fees are not paid to anyone in particular---they are instead sent to a "black hole" where they are rendered unspendable (the intention is to discourage ID squatters). - -Unlike DNS, _anyone_ can create a namespace and set its properties. Namespaces are created on a first-come first-serve basis, and once created, they last 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 (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`). - -Namespaces can be between 1 and 19 characters long, and are composed of the characters `a-z`, `0-9`, `-`, and `_`. - -## Subdomains - -BNS names are strongly owned because the owner of its private key can generate valid transactions that update its zone file hash and owner. However, this comes at the cost of requiring a name owner to pay for the underlying transaction in the blockchain. Moreover, this approach limits the rate of BNS name registrations and operations to the underlying blockchain's transaction bandwidth. - -BNS overcomes this with subdomains. A **BNS subdomain** is a type of BNS name whose state and owner are stored outside of the blockchain, but whose existence and operation history are anchored to the blockchain. Like their on-chain counterparts, subdomains are globally unique, strongly owned, and human-readable. BNS gives them their own name state and public keys. Unlike on-chain names, subdomains can be created and managed cheaply, because they are broadcast to the BNS network in batches. A single blockchain transaction can send up to 120 subdomain operations. - -This is achieved by storing subdomain records in the BNS name zone files. An on-chain name owner broadcasts subdomain operations by encoding them as `TXT` records within a DNS zone file. To broadcast the zone file, the name owner sets the new zone file hash with a `NAME_UPDATE` transaction and replicates the zone file. This, in turn, replicates all subdomain operations it contains, and anchors the set of subdomain operations to an on-chain transaction. The BNS node's consensus rules ensure that only valid subdomain operations from _valid_ `NAME_UPDATE` transactions will ever be stored. - -For example, the name `verified.podcast` once wrote the zone file hash `247121450ca0e9af45e85a82e61cd525cd7ba023`, which is the hash of the following zone file: - -```bash -$TTL 3600 -1yeardaily TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxeWVhcmRhaWx5CiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMXllYXJkYWlseS9oZWFkLmpzb24iCg==" -2dopequeens TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAyZG9wZXF1ZWVucwokVFRMIDM2MDAKX2h0dHAuX3RjcCBVUkkgMTAgMSAiaHR0cHM6Ly9waC5kb3Rwb2RjYXN0LmNvLzJkb3BlcXVlZW5zL2hlYWQuanNvbiIK" -10happier TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxMGhhcHBpZXIKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8xMGhhcHBpZXIvaGVhZC5qc29uIgo=" -31thoughts TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzMXRob3VnaHRzCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzF0aG91Z2h0cy9oZWFkLmpzb24iCg==" -359 TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzNTkKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8zNTkvaGVhZC5qc29uIgo=" -30for30 TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzMGZvcjMwCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzBmb3IzMC9oZWFkLmpzb24iCg==" -onea TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiBvbmVhCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vb25lYS9oZWFkLmpzb24iCg==" -10minuteteacher TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxMG1pbnV0ZXRlYWNoZXIKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8xMG1pbnV0ZXRlYWNoZXIvaGVhZC5qc29uIgo=" -36questionsthepodcastmusical TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzNnF1ZXN0aW9uc3RoZXBvZGNhc3RtdXNpY2FsCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzZxdWVzdGlvbnN0aGVwb2RjYXN0bXVzaWNhbC9oZWFkLmpzb24iCg==" -_http._tcp URI 10 1 "https://dotpodcast.co/" -``` - -Each `TXT` record in this zone file encodes a subdomain-creation. For example, `1yeardaily.verified.podcast` resolves to: - -```json -{ - "address": "1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH", - "blockchain": "bitcoin", - "last_txid": "d87a22ebab3455b7399bfef8a41791935f94bc97aee55967edd5a87f22cce339", - "status": "registered_subdomain", - "zonefile_hash": "e7acc97fd42c48ed94fd4d41f674eddbee5557e3", - "zonefile_txt": "$ORIGIN 1yeardaily\n$TTL 3600\n_http._tcp URI 10 1 \"https://ph.dotpodcast.co/1yeardaily/head.json\"\n" -} -``` - -This information was extracted from the `1yeardaily` `TXT` resource record in the zone file for `verified.podcast`. - -### Subdomain Lifecycle - -Note that `1yeardaily.verified.podcast` has a different public key hash (address) than `verified.podcast`. A BNS node will only process a subsequent subdomain operation on `1yeardaily.verified.podcast` if it includes a signature from this address's private key. `verified.podcast` cannot generate updates; only the owner of `1yeardaily.verified.podcast can do so`. - -The lifecycle of a subdomain and its operations is shown in Figure 2. - -``` - subdomain subdomain subdomain - creation update transfer -+----------------+ +----------------+ +----------------+ -| cicero | | cicero | | cicero | -| owner="1Et..." | signed | owner="1Et..." | signed | owner="1cJ..." | -| zf0="7e4..." |<--------| zf0="111..." |<--------| zf0="111..." |<---- ... -| seqn=0 | | seqn=1 | | seqn=2 | -| | | sig="xxxx" | | sig="xxxx" | -+----------------+ +----------------+ +----------------+ - | | | - | off-chain | | -~ ~ ~ ~ | ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~|~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ | ~ ~ ~ ~ ~ ~ ~ ... - | on-chain | | - V V (zone file hash ) V -+----------------+ +----------------+ +----------------+ -| res_publica.id | | jude.id | | res_publica.id | -| NAME_UPDATE |<--------| NAME_UPDATE |<--------| NAME_UPDATE |<---- ... -+----------------+ +----------------+ +----------------+ - blockchain blockchain blockchain - block block block Figure 2: Subdomain lifetime with respect to on-chain name operations . A new -subdomain operation will only be accepted if it has a later "sequence=" number, -and a valid signature in "sig=" over the transaction body . The "sig=" field -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." -However, any on-chain name ("jude.id" in this case) can broadcast a subdomain -update for "cicero.res_publica.id." -``` - -Subdomain operations are ordered by sequence number, starting at 0. Each new subdomain operation must include: - -- The next sequence number -- The public key that hashes to the previous subdomain transaction's address -- A signature from the corresponding private key over the entire subdomain operation. - -If two correctly signed but conflicting subdomain operations are discovered (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 subdomain's operations will be able to determine the valid sequence of state-transitions it has undergone, and determine the current zone file and public key hash for the subdomain. - -### Subdomain Creation and Management - -Unlike an on-chain name, a subdomain owner needs an on-chain name owner's help to broadcast their subdomain operations. In particular: - -- A subdomain-creation transaction can only be processed by the owner of the on-chain name that shares its suffix. For example, only the owner of `res_publica.id` can broadcast subdomain-creation transactions for subdomain names ending in `.res_publica.id`. -- A subdomain-transfer transaction can only be broadcast by the owner of the on-chain name that created it. For example, the owner of `cicero.res_publica.id` needs the owner of `res_publica.id` to broadcast a subdomain-transfer transaction to change `cicero.res_publica.id`'s public key. -- In order to send a subdomain-creation or subdomain-transfer, all of an on-chain name owner's zone files must be present in the Atlas network. This lets the BNS node prove the _absence_ of any conflicting subdomain-creation and subdomain-transfer operations when processing new zone files. -- A subdomain update transaction can be broadcast by _any_ on-chain name owner, but the subdomain owner needs to find one who will cooperate. For example, the owner of `verified.podcast` can broadcast a subdomain-update transaction created by the owner of `cicero.res_publica.id`. - -That said, to create a subdomain, the subdomain owner generates a subdomain-creation operation for their desired name and gives it to the on-chain name owner. - -Once created, a subdomain owner can use any on-chain name owner to broadcast a subdomain-update operation. To do so, they generate and sign the requisite subdomain operation and give it to an on-chain name owner, who then packages it with other subdomain operations into a DNS zone file and broadcasts it to the network. - -If the subdomain owner wants to change the address of their subdomain, they need to sign a subdomain-transfer operation and give it to the on-chain name owner who created the subdomain. They then package it into a zone file and broadcast it. - -### Subdomain Registrars - -Because subdomain names are cheap, developers may be inclined to run subdomain registrars on behalf of their applications. For example, the name `personal.id` is used to register usernames without requiring them to spend any Bitcoin. - -We supply a reference implementation of a [BNS Subdomain Registrar](https://github.com/stacks-network/subdomain-registrar) to help developers broadcast subdomain operations. Users would still own their subdomain names; the registrar simply gives developers a convenient way for them to register and manage them in the context of a particular application. - -# BNS and DID Standards - -BNS names are compliant with the emerging [Decentralized Identity Foundation](http://identity.foundation) protocol specification for decentralized identifiers (DIDs). - -Each name in BNS has an associated DID. The DID format for BNS is: - -```bash - did:stack:v0:{address}-{index} -``` - -Where: - -- `{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 `did:stack:v0:1dARRtzHPAFRNE7Yup2Md9w18XEQAtLiV-0`, because the name `personal.id` was the first-ever name created by `1dARRtzHPAFRNE7Yup2Md9w18XEQAtLiV`. - -As another example, the DID for `jude.id` is `did:stack:v0:16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg-1`. Here, the address `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` had created one earlier name in history prior to this one (which happens to be `abcdefgh123456.id`). - -The purpose of a DID is to provide an eternal identifier for a public key. The public key may change, but the DID will not. - -Stacks Blockchain implements a DID method of its own in order to be compatible with other systems that use DIDs for public key resolution. In order for a DID to be resolvable, all of the following must be true for a name: - -- The name must exist -- The name's zone file hash must be the hash of a well-formed DNS zone file -- The DNS zone file must be present in the Stacks node's data. -- The DNS zone file must contain a `URI` resource record that points to a signed JSON Web Token -- The public key that signed the JSON Web Token (and is included with it) must hash to the address that owns the name - -Not all names will have DIDs that resolve to public keys. However, names created by standard tooling will have DIDs that do. - -A RESTful API is under development. - -## DID Encoding for Subdomains - -Every name and subdomain in BNS has a DID. The encoding is slightly different 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 (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 subdomains owned by a single private key, and version byte 50 for subdomains owned by a m-of-n set of private keys. That is, subdomain DID addresses start with `S` or `M`, respectively. - -The `{index}` field for a subdomain's DID is distinct from the `{index}` field for a BNS name's DID, even if the same created both names and subdomains. For example, the name `abcdefgh123456.id` has the DID `did:stack:v0:16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg-0`, because it was the first name created by `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg`. However, `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` _also_ created `jude.statism.id` as its first subdomain name. The DID for `jude.statism.id` is `did:stack:v0:SSXMcDiCZ7yFSQSUj7mWzmDcdwYhq97p2i-0`. Note that the address `SSXMcDiCZ7yFSQSUj7mWzmDcdwYhq97p2i` encodes the same public key hash as the address `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` (the only difference between these two strings is that the first is base58check-encoded with version byte 0, and the second is encoded with version byte 63). diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/build-apps/references/references.md b/i18n/pt/docusaurus-plugin-content-docs/current/build-apps/references/references.md deleted file mode 100644 index babe5e119a..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/build-apps/references/references.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: References -sidebar_label: References ---- - -[Authentication](./authentication) - -[Blockchain Naming System](./bns) - -[Hiro example apps](https://docs.hiro.so/example-apps) \ No newline at end of file diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/contribute/docs.md b/i18n/pt/docusaurus-plugin-content-docs/current/contribute/docs.md deleted file mode 100644 index 77705451b8..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/contribute/docs.md +++ /dev/null @@ -1,207 +0,0 @@ ---- -title: Contribute to docs -description: Learn how this site is built, and how you can contribute to it. ---- - -## Introduction - -Thank you for your interest in contributing and helping make these docs as good as they can be. - -This docs site is built on the open source platform [Discosaurus 2](https://docusaurus.io/) and most of its content is written in Markdown files. All of the code for this site is free and open source, located at the [GitHub repository here](https://github.com/stacks-network/docs). - -:::tip Don't know what Markdown is? Want to learn? Here is a [helpful guide](https://guides.github.com/features/mastering-markdown/). - -Don't want to learn it? No need to. Write [in plain text an issue on Github](https://github.com/stacks-network/docs/issues/new?assignees=&labels=documentation&template=add-documentation.md&title=%5BAdd+docs%5D) ::: - -:::info You need a free [Github](https://www.github.com) account to add or edit any content. ::: - -To edit any page, just click on the *Edit this page* button at the bottom of each page and submit your changes online. - -To add new content, they are two different ways to do it, the [easy way](#easy-way) and the [advanced way](#advanced-way). - -## Easy way - -[**Simply click here and enter the text of the article you wish to add.**](https://github.com/stacks-network/docs/issues/new?assignees=&labels=documentation&template=add-documentation.md&title=%5BAdd+docs%5D) - -This will open up an issue on github using our template. -## Advanced way - -For more advanced changes you can follow the next steps. - -You can also test the site locally using this method. -### Steps - -1. Fork the [docs reposiroty](https://github.com/stacks-network/docs) by clicking on the *Fork* button in the upper right of the screen. -2. Clone your fork to your local machine with this command `git clone git@github.com:/docs.git stacks_docs` -3. Enter your project folder `cd stacks_docs` -4. Create a branch `git checkout -b feat/my-feature-branch`. -5. You can optionally preview your changes in real time with: - - `npm install` (to install dependencies). - - `npx docusaurus start` to start a local copy of the site. A web browser will open at http://localhost:3000, so you can see a preview of yourhanges in real time. -6. Make the changes you wish and then commit them with this kind of message: `git commit -am "feat: some new feature or content"`. -7. Push to to GitHub with `git push --set-upstream origin feature/my-feature-branch`. -8. Visit GitHub and make your pull request. - -## Aditional information -### Running and building the site locally (optional) - -You can start the page locally with the following command. This is enough to preview your changes. -```bash -npx docusaurus start -``` - -Before running this command for the first time you will need to run `npm install` to install dependencies. - -The docs site will be accessible at this url: [`http://localhost:3000`](http://localhost:3000). - - -After you finished your changes, you can also build the entire site with the following command (not usually needed): -```bash -npm run build -``` - -:::tip `npx docusaurus start` will only load the default language (english). To test all languages you can build with `npm run build` and then preview your build with `npm run serve`. ::: - -### An alternative: Working in browser - -As an alterative to working locally, you can also use the web IDE gitpod that provides an environment to contribute directly from within your browser. - -You only need to have a github account and open [this link](https://gitpod.io/#https://github.com/stacks-network/docs). - -### Folder structure of the site - -If you are interested in only adding new documentation content to the site, the files that will be important to you are located within `./docs/*`: - -```bash -docs/ - build-apps - contribute/ - faq/ - gaia/ - nodes-and-miners/ - noteworthy-contracts/ - references/ - understand-stack/ - write-smart-contracts/ -``` - -The routing for this site is file based, meaning if you created a folder within `/docs/gaia/` named `testing` and in it a file named `test1.md`, you would be able to navigate to `http://localhost:3000/gaia/testing/test1` and you would see whatever content is in that markdown file. - -All the docs in English are stored in the folder `/docs/`. - -To add new English content simply add a markdown file (.md) into any subfolder in docs, and it will be automatically displayed in the category of that folder. - -All the docs in other languages are stored under the folder `i18n`, but these files should never be edited using GitHub as they are overwritten by Crowdin every time new translations are added. **To make changes in other languages**, you must do so using Crowdin. Please refer to [translations](translations) instead. - -### Frontmatter - -Frontmatter is the top part of any markdown document that is written in a language called [YAML](https://yaml.org/). It looks like this: - -```yaml ---- -title: This is my page title -description: A short, concise sentence describing what is on this page ---- -``` - -Frontmatter gives us the ability to define some things within a page that the site can use, such as a page title or page description. When adding any new page, please include a `title` and `description`. - - - -### Use Conventional Commits - -We use the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) as and commits naming convention. Use it while contributing, please. - -### Code blocks - -To write a code block, you need to wrap your code in ` ```language `, and end your code block with ` ``` `. Here is an example of ` ```clarity `. - -```clarity -(define-data-var counter int 0) - -(define-public (get-counter) - (ok (var-get counter))) -``` -### Admonitions - -You can use the following admonitions to highlight content. - -```md -:::note -Some **content** with _markdown_ `syntax`. -::: - -:::tip -Some **content** with _markdown_ `syntax`. -::: - -:::info -Some **content** with _markdown_ `syntax`. -::: - -:::caution -Some **content** with _markdown_ `syntax`. -::: - -:::danger -Some **content** with _markdown_ `syntax`. -::: - -:::tip My personalized title -Some **content** with _markdown_ `syntax`. -::: -``` - -Which renders: - -:::note - -Some **content** with _markdown_ `syntax`. - -::: - -:::tip - -Some **content** with _markdown_ `syntax`. - -::: - -:::info - -Some **content** with _markdown_ `syntax`. - -::: - -:::caution - -Some **content** with _markdown_ `syntax`. - -::: - -:::danger - -Some **content** with _markdown_ `syntax`. - -::: - -:::tip My personalized title - -Some **content** with _markdown_ `syntax`. - -::: \ No newline at end of file diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/contribute/index.md b/i18n/pt/docusaurus-plugin-content-docs/current/contribute/index.md deleted file mode 100644 index ac81d899bd..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/contribute/index.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Contribute -description: Contribute to the Stacks ecosystem. -sidebar_position: 10 -sidebar_label: "Contribute" ---- - -You can contribute to the Stacks ecosystem in multiple ways: - - - -### Documentation - -Contribute to the Stacks Docs on this website. More info [here](docs). - -### Translations - -Help us reach more people with translations. More details [here](translations). - - - -### Articles - -Write an article or a blog post about Stacks. A good place to start is [Stacks Forum](https://forum.stacks.org). - -### Github - -If you are familiar with Github they are multiple repositories of the Stack Ecosystem that you can contribute to. - -- https://github.com/stacks-network/ diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/contribute/translations.md b/i18n/pt/docusaurus-plugin-content-docs/current/contribute/translations.md deleted file mode 100644 index 49a9d366ad..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/contribute/translations.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Contribute with translations -description: Want to help tranlating these docs to your local language? ---- - -## Help with translations - -Translations are managed with Crowdin. -Anybody can colaborate and no technichal skills are required, as it's all done on the browser. - -To help with translation please go to [this page](https://crowdin.com/project/docsstacksco), click any language and start translating. - -All help is appreciated. - -:::caution Please don't add any translations to the Github repository, as the translated pages get rewritten from Crowdin. Translations need to be added on Crodin intead. -::: - -### Common issues on translations - -When translating in Crowdin, please only translate the texts and not the html code. - -If you acccidently modify the html tags you will get errors like shown below (`Seems like some formating tags are missing` or `Translation contains tag that source text doesn't have`). These errors will prevent your translation getting published until the tags are left as they were in the original text. - -![](/img/crowdin-qa-issue-formatting_tags_missing.png) ![](/img/crowdin-qa-issue-tag_source.png) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/faq/faq.md b/i18n/pt/docusaurus-plugin-content-docs/current/faq/faq.md deleted file mode 100644 index 06a710474a..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/faq/faq.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: General FAQs -description: Frequently Asked Questions -sidebar_label: "FAQ" -sidebar_position: 10 ---- - -![](/img/glasses.png) - -## Why is my transfer still pending? - -Commonly it's because your fee is too low or your [nonce](#what-is-nonce) is incorrect. - -More information can be found [here](https://www.hiro.so/wallet-faq/why-is-my-stacks-transaction-pending). There are also [best practices and known issues](https://forum.stacks.org/t/transactions-in-mempool-best-practices-and-known-issues/11659) and [diagnosing pending transactions](https://forum.stacks.org/t/diagnosing-pending-transactions/11908). - -There is also this [script](https://github.com/citycoins/scripts/blob/main/getnetworkstatus.js) to look at either the first 200 transactions or all the transactions in the mempool, to then return the maximum adn average fee values. We've noticed that using 1.5-2x the average fee in the mempool will generally get things processed within 6-10 blocks even during high congestion. - -There is also this [script](https://github.com/citycoins/scripts/blob/main/gettxstatus.js) to track a pending transaction until it reaches a final status. - -## What is Nonce? - -A nonce is used to make sure that every transaction goes in right order. Nonce starts at 0, so the very first transaction from an address should set to nonce=0. You can find the nonce of your wallet address by searching the address in any [Stacks blockchain explorer](https://explorer.stacks.co/). You can also user `$ stx balance
`. - -If you have a transaction nonce that is less than your account nonce, the transaction is unmineable and will (should) disappear after 256 blocks. This does not affect future transactions and therefore can be just ignored, they are in the past. - -If you have a transaction nonce that is equal to your account nonce, then that transaction is valid and should be the next in line to be processed next. - -If you have a transaction nonce that is higher than your account nonce, then there needs to be a chain of transactions starting with your account nonce in order for it to be processed. E.g. Your account nonce is 10 but the pending transaction has a nonce of 12. It will not be mineable until a transaction with nonces 10 and 11 are processed. - -## Whats a Replace-by-fee (RBF)? - -A replace-by-fee (RBF) transaction tells the blockchain that you would like to replace one transaction with another, while specifying a fee that is higher than the original transaction fee. A transaction can be replaced with **any other transaction**, and is not limited to the same operation. - -This can be used to effectively **cancel a transaction** by replacing it with something else, like a small STX transfer to another owned address. - -This can be used to **raise the fee for a pending transaction** so it is considered by miners during periods of high congestion. This can also be used to _resubmit_ a transaction, in the sense that the RBF transaction gets a new txid and gets considered again (or faster) by miners. E.g. I submit my transaction with 1 STX fee at block 54,123. By block 54,133 I see my tx hasn’t been picked up, so I RBF with 1.1 STX. Then wait 10 blocks again, and RBF again if not received. There’s a balance between doing this too often and keeping a consistent pace, but it has been seen to help get transactions through, especially when new ones are constantly flooding in. - -The replacement transaction needs to use the same nonce as the original transaction with a fee increase of at least 0.000001 STX. E.g. Your original transaction has a fee of 0.03 STX, the new RBF transaction must have a fee of 0.030001 STX or above. - -RBF transactions process in one of two ways: - -- If miners pick up the original transaction before the RBF transaction is received, then the original transaction is processed and the replacement transaction goes into an unmineable state. It will eventually disappear and doesn’t affect future transactions. -- If miners pick up the replaced transaction then the new transaction is processed instead of the original, and the status of the original transaction is set to “droppped_replaced_by_fee”. This status is not shown on the explorer but can be seen when querying the txid. - -Submitting multiple transactions for the same action can slow things down in a few ways. - -- If the total spent in 2 or 3 transactions is more than can be spent in a single transaction, the transactions appear unmineable. -- If the fees for multiple transactions exceed the STX balance, the transactions will be unmineable. - -## What are .btc domains? - -[This forum post](https://forum.stacks.org/t/btc-domains-are-live/12065) explains all the benefits of .btc domains. They can currently be purchased in [btc.us](https://btc.us/) - -## What is the blockchain trilemma? - -## Stacks vs. Solana vs. Polygon: How Do They Compare From a Developer Perspective? - -[This blog post answers the question](https://www.hiro.so/blog/stacks-vs-solana-vs-polygon-how-do-they-compare-from-a-developer-perspective). - -## What Does Lightning’s Taro Proposal Mean for Stacks? - -[This blog post answers the question](https://www.hiro.so/blog/what-does-lightnings-taro-proposal-mean-for-stacks). - - -## Is Stacks a [PoS chain](https://en.wikipedia.org/wiki/Proof_of_stake)?[¹][] - -No. - -The act of block production requires an extrinsic expenditure — it is not tied to owning the native token, as would be required in PoS. The act of block production requires an extrinsic expenditure — it is not tied to owning the native token, as would be required in PoS. The only way to produce blocks in the Stacks chain is to transfer Bitcoin to a predetermined randomized list of Bitcoin addresses. Moreover, the Stacks blockchain can fork, and there exists a protocol to rank forks by quality independent of the set of miners and the tokens they hold. These two properties further distinguish it from PoS chains, which cannot fork due to the inability to identify a canonical fork without trusting a 3rd party to decree a particular fork as valid. The ability to fork allows the Stacks blockchain to survive failure modes that would crash a PoS chain. - -## Is Stacks a [sidechain](https://en.bitcoin.it/wiki/Sidechain)?[¹][] - -No. - -For two key reasons. - -First, the history of all Stacks blocks produced is recorded to Bitcoin. This means that the act of producing a private Stacks fork is at least as hard as reorging the Bitcoin chain. This in turn makes it so attacks on the chain that rely on creating private forks (such as selfish mining and double-spending) are much harder to carry out profitably, since all honest participants can see the attack coming before it happens and have a chance to apply countermeasures. Sidechains offer no such security benefit. - -Second, the Stacks blockchain has its own token; it does not represent pegged Bitcoin. This means that the safety of the canonical fork of the Stacks blockchain is underpinned by its entire token economy’s value, whereas the safety of a sidechain’s canonical fork is underpinned only by whatever system-specific measures incentivize its validators to produce blocks honestly, or the Bitcoin miners’ willingness to process peg-in requests (whichever is the weaker guarantee). - - -## Is Stacks a [layer-2 system](https://academy.binance.com/en/glossary/layer-2) for Bitcoin?[¹][] - -No. - -Stacks blockchain is a layer-1 blockchain, which uses a novel and unique mining protocol called proof-of-transfer (PoX). A PoX blockchain runs in parallel to another blockchain (Bitcoin in Stacks’ case), which it uses as a reliable broadcast medium for its block headers. It's a sovereign system in its own right. The Stacks blockchain state is distinct from Bitcoin, and is wholly maintained by and for Stacks nodes. Stacks transactions are separate from Bitcoin transactions. Layer-2 systems like Lightning are designed to help scale Bitcoin payment transactions, whereas Stacks is designed to bring new use-cases to Bitcoin through smart contracts. Stacks is not designed as a Bitcoin layer-2 scalability solution. - - -## Is Stacks a [merged-mined chain](https://en.bitcoin.it/wiki/Merged_mining_specification)?[¹][] - -No. - -The only block producers on the Stacks chain are Stacks miners. Bitcoin miners do not participate in Stacks block validation, and do not claim Stacks block rewards. Moreover, Stacks is not a [blind merged-mined chain](https://github.com/bitcoin/bips/blob/master/bip-0301.mediawiki), because STX block winners are public and randomly chosen (instead of highest-bid-wins), and its tokens are minted according to a schedule that is independent of the degree of miner commitment or Bitcoin transferred (instead of minted only by one-way pegs from Bitcoin). This ensures that Stacks is able to make forward progress without opt-in from Bitcoin miners, and it ensures that Stacks miners are adequately compensated for keeping the system alive regardless of transaction volume. - -## Whats the difference between Stacks and Ethereum?[²][] -**Computation and Storage** Stacks does all computation and storage outside of the blockchain, and uses the blockchain only as a “shared source of truth” between clients. By contrast, Ethereum does all computation and most application storage in the blockchain itself. Like Ethereum, if two Stacks nodes see the same underlying blockchain, they will independently run the same computations and produce the same state. Unlike Ethereum, there is no Stacks-specific blockchain. - -**Programming Language and Tooling** Stacks’s programming model is based on running off-chain programs. These programs can be written and debugged in any language you want. By contrast, Ethereum’s programming model is based on running on-chain “smart contracts.” These are written and debugged with a whole new set of tools, like Solidity and Serpent. - -**Scalability of On-chain Computation** Stacks is designed around a “virtual chain” concept, where nodes only need to reach consensus on the shared “virtual chain” they’re interested in. Virtual chains do not interact with one another, and a single blockchain can host many virtual chains. Although Stacks’s specific virtual chain is not Turing-complete (i.e. it’s a list of instructions to build the name database), it is possible to create Turing-complete virtual chains like Ethereum. These virtual chains can live in any blockchain for which there exists a driver, and virtual chain clients only need to execute their virtual chain transactions (i.e. Stacks only processes Stacks virtual chain transactions). Stacks only processes Stacks virtual chain transactions). - -By contrast, because smart contracts run on-chain and can call one another, all Ethereum nodes need to process all smart contracts’ computations in order to reach consensus. This can get expensive as the number of running smart contracts grow, which takes the form of gas fee increases. - -**Scalability of Off-chain Computation** Stacks applications are very similar to Web applications today and almost never need to interact with the blockchain. For most Stacks applications, the blockchain is only used to authenticate the application’s code and data before the user runs it. By contrast, Ethereum applications usually require an application-specific smart contract, and must interact with the blockchain to carry out its operations. - - -[¹]: https://stacks.org/stacks-blockchain -[²]: https://forum.stacks.org/t/what-is-the-difference-between-blockstack-and-ethereum/781 diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/gaia/configuration.md b/i18n/pt/docusaurus-plugin-content-docs/current/gaia/configuration.md deleted file mode 100644 index a6a530cd70..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/gaia/configuration.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Configuration -description: Configuring Gaia Hub ---- - -## Configuration files - -The following configuration files exist in the folder `deploy/configs/gaia/`: - -``` -admin-config.json -hub-config.json -reader-config.json -``` - -## GAIA Admin Service - -You can also use the GAIA Admin Service to remotely administer it with an API Key. It will require you to install `npm` with a `apt install npm`. Once `npm` is installed you can continue with the steps in the [GAIA Admin Service](https://github.com/stacks-network/gaia/blob/master/admin/README.md). - -## Driver Selection - -The Gaia hub currently supports the following drivers: - -``` -'aws' == Amazon S3 -'azure' == Azure Blob Storage -'disk' == Local disk -'google-cloud' === Google Cloud Storage -``` - -Set the driver you wish to use in your [config.json](https://github.com/stacks-network/gaia/blob/master/hub/config.sample.json) file with the `driver` parameter. Many drivers additionally accept the `bucket` parameter, which controls the bucket name that files should be written to. - -These driver may require you to provide additional credentials for performing writes to the backends. See `config.sample.json` for fields for those credentials. In some cases, the driver can use a system configured credential for the backend (e.g., if you are logged into your AWS CLI account, and run the hub from that environment, it won't need to read credentials from your `config.json`). - -_Note:_ The disk driver requires a \*nix like filesystem interface, and will not work correctly when trying to run in a Windows environment. ::: - -## Note on SSL - -We _strongly_ recommend that you deploy your Gaia hub with SSL enabled. Otherwise, the tokens used to authenticate with the Gaia hub may be stolen by attackers, which could allow them to execute writes on your behalf. -Configuration options are available to run the hub with an `https` Node.js server. -Otherwise, a reverse proxy web server such as nginx or Apache can be used. - -## Require Correct Hub URL - -If you turn on the `requireCorrectHubUrl` option in your `config.json` file, your Gaia hub will require that authentication requests correctly include the `hubURL` they are trying to connect with. This is used to prevent a malicious gaia hub from using an authentication token for itself on other Gaia hubs. - -By default, the Gaia hub will validate that the supplied URL matches `https://${config.serverName}`, but if there are multiple valid URLs for clients to reach the hub at, you can include a list in your `config.json`: - -```javascript -{ - .... - serverName: "normalserver.com" - validHubUrls: [ "https://specialserver.com/", - "https://legacyurl.info" ] - .... -} -``` - -## The readURL parameter - -By default, the gaia hub drivers will return read URLs which point directly at the written content. For example, an S3 driver would return the URL directly to the S3 file. However, if you configure a CDN or domain to point at that same bucket, you can use the `readURL` parameter to tell the gaia hub that files can be read from the given URL. For example, the `hub.blockstack.org` Gaia Hub is configured to return a read URL that looks like `https://gaia.blockstack.org/hub/`. - -Unset this configuration parameter if you do not intend to deploy any caching. - -## Minimum Proofs Requirement - -The gaia hub can also be configured to require a minimum number of social proofs in a user's profile to accept writes from that user. This can be used as a kind of spam-control mechanism. However, we recommend for the smoothest operation of your gaia hub, to set the `proofsConfig.proofsRequired` configuration key to `0`. - -## CDN & Replicated Hubs - -- https://docs.microsoft.com/en-us/azure/storage/blobs/storage-https-custom-domain-cdn - -- The hub implementation is designed to be ran from a single Node.js instance. If the hub instance is sharded (e.g. replicated hubs via load balancing), then any given `bucket` (identified by URI segment) must be served by the same instance, At least a couple elements of the Gaia Hub depend on this: token invalidation in-memory caching, and resource endpoint 409 contention behavior. diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md b/i18n/pt/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md deleted file mode 100644 index 558cbb14f5..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Deploy Gaia Hub -description: Steps and tutorials ---- - -## Deploy your GAIA hub - -Tutorials to deploy your own GAIA hub are currently available for [Linux](./setup-linux), [MacOS](./setup-mac) and [Amazon EC2 / CloudFormation](./gaia-on-ec2). - -Regardless of what server the Gaia Hub runs on, the storage it uses can currently be deployed on multiple platforms: - -- Local disk (the server itself) -- Amazon S3 -- Azure Blob Storage -- Google Cloud - -:::tip -Support for IPFS is under development. -::: \ No newline at end of file diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md b/i18n/pt/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md deleted file mode 100644 index 8f2b139876..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: Amazon EC2 -description: Use a template to deploy a Gaia hub on Amazon EC2 -tags: - - tutorial - - gaia ---- - -## Introduction - -The template provided on this page provides an easy way to deploy a Gaia hub directly to Amazon EC2. You can use this template to deploy your own Gaia hub to your Amazon Web Services (AWS) account. Amazon EC2 is an affordable and convenient cloud computing provider. The template provides a one-click deploy for Amazon EC2 with either S3 or EBS as a storage provider. - -## Prerequisites - -This procedure uses Amazon CloudFormation to configure an EC2 cloud compute provider to run the Gaia hub service with an S3 or EBS provider for file storage. You should have access to an AWS account either through your personal account or through a corporate account. This account should have permissions to create resources. - -Additionally, you must also own a domain name and be able to update the DNS records associated with that domain name. - -## Setup steps - -### Step 1 - Create Stack - -Use a link in the table to launch the [CloudFormation](https://console.aws.amazon.com/cloudformation/) template in the AWS region that you wish to deploy a Gaia hub. - -![Create stack](/img/cloudformation-create-stack.png) - -### Step 2 - Setup stack using template - -You need to configure the template with the appropiate values for your hub and domain it runs on. - -Select `Template is ready` and `Amazon S3 URL` and enter the following Amazon S3 URL: -``` -https://s3-external-1.amazonaws.com/cf-templates-vzldibfi2mw8-us-east-1/2022160J6G-cloudformation.yaml -``` - -If you prefer you can instead select `Template is ready` and `Upload a template file` to upload the template file `cloudformation.yaml`. - -The latest `cloudformation.yaml` file can be downloaded [here](https://raw.githubusercontent.com/stacks-network/gaia/master/deploy/cloudformation.yaml). On most browsers you can right-click on that page and click on `Save page as` to download the file. Alternatively, you can copy/paste the text into a text file called `cloudformation.yaml`. - -Then click `Next`. - -![Specify template](/img/cloudformation-specify-template.png) - -### Step 3 - Specify stack details - -Specify the stack details and then click `Next`: ![Specify template](/img/cloudformation-specify-stack-details.png) - -| Field | Value | Notes | -| --------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Stack name | _a unique name in your AWS account_ | e.g.: my_gaia_hub | -| DomainName | _your-domain_ | | -| EmailAddress | _your email address_ | | -| GaiaBucketName | _S3 bucket name_ | The template combines this name with the stack name to create a unique S3 bucket. The template ignores this field if GaiaStorageType is set to `disk`. | -| GaiaStorageType | `s3` or `disk` | Select the GaiaStorageType of which to use as a backend for the Gaia Hub. Selecting `s3` causes the template to create an S3 bucket based on the name given in the previous field. Selecting `disk` causes the template to attach a separate EBS volume to the EC2 instance for Hub storage. | -| InstaceType | t2.micro | Select the instance type you want. Default value is `t2.micro`. | -| KeyName | | In the KeyName drop-down, select an [EC2 KeyPair](https://console.aws.amazon.com/ec2/v2/home?region=us-east-1#KeyPairs:) to enable SSH access to the EC2 instance. You should download the `.pem` keyfile for this pair from the EC2 console. For more information see the [EC2 key pair documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html#prepare-key-pair) | -| SSHLocation | 0.0.0.0/0 | Leave the SSHLocation field with the default value of `0.0.0.0/0` to enable SSH access from any IP address. If you wish to restrict SSH access to the EC2 instance to a certain IP, you can update this field. | -| SubnetId | _subnetid_ | Select a public subnet | -| VpcId | _vpcid_ | | - -### Step 4 - Configure stack options - -Configure any stack options that fit your desired setup and click `Next`. All these fields are optional. - -![Specify template](/img/cloudformation-stack-options.png) - -### Step 5 - Review - -Review the configuration of your Gaia hub, select the checkbox to acknowledge that AWS may create IAM resources with custom names and click on `Create stack`. - -![Specify template](/img/cloudformation-iam-resources.png) - -### Step 6 - Retrieve the public IP of your Gaia hub - -Your stack can take several minutes to launch. You can monitor the Events tab of your hub to review the current progress of the launch. When the launch is complete, the Outputs tab displays information about the hub. Select the PublicIP and copy it to configure your domain name. - -Create an `A` DNS record pointing to the given IP in your domain. - -Wait a few minutes for the DNS record to propagate, and your should be able to access your Gaia hub with SSH. - -## Accessing your Gaia hub with SSH - -To SSH into your Gaia hub EC2 host directly, you must have the keyfile used in container creation. Access the host with the following command in your terminal: - -```bash -ssh -i admin@ -``` - -:::tip If you can only access SSH with the IP but not with the DNS name and you wish to do so, you can optionally activate it by following these steps: - - Open your [AWS Console](https://console.aws.amazon.com) - Click on `Service` -> VPC Open Your VPCs Select your VPC connected to your Gaia Hub Click `Actions` -> `Edit DNS Hostnames` -> Change `DNS hostnames` to `Enable` -::: -## Graphical representation of the cloudformation template - -![](/img/cloudformation-gaia-template1-designer.png) \ No newline at end of file diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/gaia/gaia.md b/i18n/pt/docusaurus-plugin-content-docs/current/gaia/gaia.md deleted file mode 100644 index db5f975f8e..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/gaia/gaia.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: Gaia -description: Decentralized storage architecture for off-chain data -sidebar_position: 5 -tags: - - gaia ---- - -## Introduction - -Apps built with the Stacks blockchain store off-chain data using a storage system called Gaia. - -Whereas public transactional metadata is best stored on the Stacks blockchain, user application data can often be stored more efficiently and privately in Gaia storage. - -Storing data off of the blockchain ensures that Stacks applications can provide users with high performance and high availability for data reads and writes without introducing central trust parties. - -:::tip Latest whitepaper of GAIA (May 2022) is available [here](https://dev1-gaia-hub.s3.amazonaws.com/GAIA_Whitepaper.pdf) ::: - -## Understand Gaia in the Stacks architecture - -The following diagram depicts the Stacks architecture and Gaia's place in it: - -![Stacks Architecture](/img/architecture.png) - -Blockchains require consensus among large numbers of people, so they can be slow. Additionally, a blockchain is not designed to hold a lot of data. This means using a blockchain for every bit of data a user might write and store is expensive. For example, imagine if an application were storing every tweet in the chain. - -The Stacks blockchain addresses performance problems using a layered approach. The base layer consists of the Stacks blockchain and the Blockchain Naming System (BNS). The blockchain governs ownership of identities in the Stacks network. Identities can be names such as domain names, usernames, or application names. - -When an identity is created, its creation is recorded in the Stacks blockchain. Identities make up the primary data stored into the Stacks blockchain. These identities correspond to routing data in the OSI stack. The routing data is stored in the Atlas Peer Network, the second layer. Every core node that joins the Stacks Network is able to obtain an entire copy of this routing data. Stacks uses the routing data to associate identities (domain names, user names, and application names) with a particular storage location in the final layer, the Gaia Storage System. - -A Gaia Storage System consists of a _hub service_ and storage resource on a cloud software provider. The storage provider can be any commercial provider such as Azure, DigitalOcean, Amazon EC2, and so forth. Typically the compute resource and the storage resource reside same cloud vendor, though this is not a requirement. Gaia currently has driver support for S3, Azure Blob Storage, Google Cloud Platform and local disk, but the driver model allows for other backend support as well. - -Gaia stores data as a simple key-value store. When an identity is created, a corresponding data store is associated with that identity on Gaia. When a user logs into a dApp, the authentication process gives the application the URL of a Gaia hub, which then writes to storage on behalf of that user. - -The Stacks blockchain stores only identity data. Data created by the actions of an identity is stored in a Gaia Storage System. Each user has profile data. When a user interacts with a decentralized dApp that application stores application data on behalf of the user. Because Gaia stores user and application data off the blockchain, a Stacks DApp is typically more performant than DApps created on other blockchains. - -## User control or how is Gaia decentralized? - -A Gaia hub runs as a service which writes to data storage. The storage itself is a simple key-value store. The hub service writes to data storage by requiring a valid authentication token from a requestor. Typically, the hub service runs on a compute resource and the storage itself on separate, dedicated storage resource. Typically, both resources belong to the same cloud computing provider. - -![Gaiastorage](/img/gaia-storage.png) - -Gaia's approach to decentralization focuses on user control of data and its storage. Users can choose a Gaia hub provider. If a user can choose which Gaia hub provider to use, then that choice is all the decentralization required to enable user-controlled applications. Moreover, Gaia defines a uniform API for applications to access that data. - -The control of user data lies in the way that user data is accessed. When an application fetches a file `data.txt` for a given user `alice.id`, the lookup will follow these steps: - -1. Fetch the `zonefile` for `alice.id`. -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. Find the read-only url out of the profile's `appsMeta` section (e.g. `https://example-app.gaia.alice.org`). -6. Fetch the file from `https://example-app.gaia.alice.org/data.txt`. - -Because `alice.id` has access to her [zonefile](https://docs.stacks.co/references/bns-contract#name-update), 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. - -:::caution Users with existing identities cannot yet migrate their data from one hub to another. -::: - -Applications writing directly on behalf of `alice.id` do not need to perform a lookup. Instead, the [Stacks authentication flow](https://stacks.js.org) provides Alice's chosen gaia hub URL to the application. This authentication flow _is also_ within Alice's control because Alice's wallet _must_ generate the authentication response. - -## Understand data storage - -A Gaia hub stores the written data _exactly_ as given. It offers minimal guarantees about the data. It does not ensure that data is validly formatted, contains valid signatures, or is encrypted. Rather, the design philosophy is that these concerns are client-side concerns. - -Client libraries (such as [`Stacks.js`](https://stacks.js.org/)) are capable of providing these guarantees. A liberal definition of the [end-to-end principle](https://en.wikipedia.org/wiki/End-to-end_principle) guides this design decision. - -When an application writes to a Gaia hub, an authentication token, key, and the data are passed to the Gaia hub. - -![Gaia writes](/img/gaia-writes.png) - -The token ensures the app has the authorization to write to the hub on the user's behalf. - -## Gaia versus other storage systems - -Here's how Gaia stacks up against other decentralized storage systems. Features that are common to all storage systems are omitted for brevity. - -| Features | [Gaia](https://github.com/stacks-network/gaia) | [Sia](https://sia.tech/) | [Storj](https://storj.io/) | [IPFS](https://ipfs.io/) | [DAT](https://datproject.org/) | [SSB](https://www.scuttlebutt.nz/) | -| ------------------------------------------ | ---------------------------------------------- | ------------------------ | -------------------------- | ------------------------ | ------------------------------ | ---------------------------------- | -| User controls where data is hosted | X | | | | | | -| Data can be viewed in a normal Web browser | X | | | X | | | -| Data is read/write | X | | | | X | X | -| Data can be deleted | X | | | | X | X | -| Data can be listed | X | X | X | | X | X | -| Deleted data space is reclaimed | X | X | X | X | | | -| Data lookups have predictable performance | X | | X | | | | -| Writes permission can be delegated | X | | | | | | -| Listing permission can be delegated | X | | | | | | -| Supports multiple backends natively | X | | X | | | | -| Data is globally addressable | X | X | X | X | X | | -| Needs a cryptocurrency to work | | X | X | | | | -| Data is content-addressed | | X | X | X | X | X | diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/gaia/setup-linux.md b/i18n/pt/docusaurus-plugin-content-docs/current/gaia/setup-linux.md deleted file mode 100644 index 1338c8f865..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/gaia/setup-linux.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: Linux -description: Steps to setup a GAIA hub on a Linux server (fresh install). This example is using Debian, but should work on any Linux distribution. It uses docker compose in the backgroud. -tags: - - tutorial - - gaia ---- - -This configuration will setup the following 4 docker containers: - -- Nginx with certbot on TCP ports 80 and 443. -- Gaia hub on TCP port 3000. -- Gaia admin on TCP port 8009. -- Gaia reader on TCP port 8008 - -**1. Update the system and install the dependencies and software we will use to test:** - -```bash -apt update && apt upgrade -y && apt install -y git vim gnupg jq -``` - -**3. Clone the GAIA repository** and enter it's docker directory. - -```bash -curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg - -echo \ - "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian \ - $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null - -apt update && apt install -y docker-ce docker-ce-cli containerd.io -``` - -Install _docker-compose_ by downloading the [latest-release](https://github.com/docker/compose/releases): - -```bash -VERSION_DC=$(curl --silent https://api.github.com/repos/docker/compose/releases/latest | jq .name -r) -DESTINATION_DC=~/.docker/cli-plugins -mkdir -p ${DESTINATION_DC} -curl -SL https://github.com/docker/compose/releases/download/${VERSION_DC}/docker-compose-linux-x86_64 -o ${DESTINATION_DC}/docker-compose -chmod +x ${DESTINATION_DC}/docker-compose -``` - -**2. Test your GAIA HUB** Running `gaia_test.js` will test your GAIA Hub, by trying to connect to it, uploading a file and downloading it again. - -```bash -git clone https://github.com/stacks-network/gaia.git && cd gaia/deploy/docker -``` - -**4. Copy and edit appropiate .env file**. -In the folder `./deploy/docker/` they are different sample files for different configurations like using aws, azure or disk among others. In this example we will store the data localy so we will copy the _disk_ file and update the domain and email fields. Please change `gaia.site.com` and `gaiarocks@mydomain.com` accordingly. Note you need both for the SSL certificate to be created correctly. - -```bash -export MYGAIADOMAIN=gaia.site.com -export MYGAIAEMAIL=gaiarocks@mydomain.com -cp sample-disk.env disk.env -sed -i 's/my-domain.com/'"$MYGAIADOMAIN"'/g' disk.env -sed -i 's/my-email@example.com/'"$MYGAIAEMAIL"'/g' disk.env - -``` - -**5. Start GAIA HUB service** - -To start GAIA HUB - -```bash -./gaiahub.sh start -``` - -To stop GAIA HUB - -```bash -./gaiahub.sh stop -``` - -To view GAIA HUB status - -```bash -./gaiahub.sh status -``` - -**6. Verify server works locally** with the following command: - -```bash -curl -sk http://localhost/hub_info | jq -``` - -A correct result should look similar to this: - -```bash - { - "challenge_text": "[\"gaiahub\",\"0\",\"gaia-0\",\"blockstack_storage_please_sign\"]", - "latest_auth_version": "v1", - "max_file_upload_size_megabytes": 20, - "read_url_prefix": "https://gaia.site.com/reader/" - } -``` - -**2. Test your GAIA HUB** Running `gaia_test.js` will test your GAIA Hub, by trying to connect to it, uploading a file and downloading it again. - -First install all required dependencies with: - -```bash -npm install -``` - -Then, from the root folder of the project type: - -```bash -node ./deploy/gaia_test.js https://yourgaiaurl -``` - -A correct result will be something like this: - -``` -Will run a test for the GAIA HUB: https://gaia.mydomain.com Generating some test keys... -Private key: 5aacc60fc2a429e1f02be139f3cac82061c6a980******************** Public key: 025691f17f2ab80dc4af363bb9c7aac59e9e1db6ae8ff668202582a3f4ec9678ff Address: 15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS -[DEBUG] connectToGaiaHub: https://gaia.mydomain.com/hub_info -[DEBUG] uploadToGaiaHub: uploading testing.txt to https://gaia.mydomain.com File uploaded successfully. -Upload to gaia hub thinks it can read it from: https://gaia.mydomain.com/reader/15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS/testing.txt Hub info thinks it can read it from : https://gaia.mydomain.com/reader/15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS/testing.txt Let's now try to fetch the uploaded file... -File fetched successfully. Contents of file: GAIA ROCKS! -``` diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/gaia/setup-mac.md b/i18n/pt/docusaurus-plugin-content-docs/current/gaia/setup-mac.md deleted file mode 100644 index 808833b212..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/gaia/setup-mac.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: MacOS -description: MacOS for local testing/development -tags: - - tutorial ---- - -The following assumes you have [Docker Installed](https://docs.docker.com/docker-for-mac/install/) - -- Recommended to also have [MacOS Homebrew](https://docs.brew.sh/Installation) installed -- Use Homebrew to install jq with `brew install jq` - -In your working directory: - -**1. Clone a copy of the [gaia repo](https://github.com/stacks-network/gaia):** - -```bash -$ git clone -b master --single-branch https://github.com/stacks-network/gaia -``` - -**2. Change your cwd:** - -```bash -$ cd gaia/deploy/docker -``` - -**3. Create a copy of sample-disk.env and fill out the values:** - -``` -$ cp sample-disk.env disk.env -# Update the DOMAIN_NAME variable to `localhost` -``` - -**4. Start the server:** - -``` -$ docker-compose -f docker-compose-base.yaml -f docker-compose-disk.yaml --env-file disk.env up -``` - -**5. Verify the server is responding locally:** - -``` -$ curl -sk https://localhost/hub_info | jq - { - "challenge_text": "[\"gaiahub\",\"0\",\"gaia-0\",\"blockstack_storage_please_sign\"]", - "latest_auth_version": "v1", - "max_file_upload_size_megabytes": 20, - "read_url_prefix": "https://localhost/reader/" - } -``` - -### Modifying the configuration for your gaia-hub - -Two methods exist: - -1. Edit the `gaia/deploy/configs/gaia/hub-config.json` using `vim` or other - -- requires a restart of the containers: `docker-compose -f docker-compose-base.yaml -f docker-compose-disk.yaml --env-file disk.env restart` - -2. Use the running `admin` container to modify any config values, and also reload the hub when complete: - -- [GitHub - Gaia Admin README.md](https://github.com/stacks-network/gaia/blob/master/admin/README.md) - -``` -$ export API_KEY="hello" -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - -H 'Content-Type: application/json' \ - -X POST \ - --data-raw '{"serverName": "myserver"}' \ - http://localhost:8009/v1/admin/config - -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - -X POST \ - http://localhost:8009/v1/admin/reload - -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - http://localhost:8009/v1/admin/config | jq -``` diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/governance/_index.md b/i18n/pt/docusaurus-plugin-content-docs/current/governance/_index.md deleted file mode 100644 index 1ecdf67871..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/governance/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Governance -description: Governance -sidebar_position: 9 ---- - -This page needs contributions. Help us write it! \ No newline at end of file diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/governance/index.md b/i18n/pt/docusaurus-plugin-content-docs/current/governance/index.md deleted file mode 100644 index 91b0215b5f..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/governance/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Governance -description: Governance -sidebar_position: 9 ---- - -![](/img/stacks-governance.png) - -This page needs contributions. Help us write it! - -Governance in web3 is driven by the community. - -How can I get involved ? - -[Governance Resources website](https://resources.stacksgov.com) - -[Github - Stack Community Governance](https://github.com/stacksgov) - -:::tip Community Calls Monthly community calls are recorded and available [here](https://www.youtube.com/playlist?list=PLg717Ri_rTnwwYjQYlc7rIP6x2FaTNn7f) ::: diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/governance/sips.md b/i18n/pt/docusaurus-plugin-content-docs/current/governance/sips.md deleted file mode 100644 index 29ac1ae1ed..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/governance/sips.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: SIPs -description: SIPs -sidebar_position: 9 ---- - -## Stacks Improvement Proposals (SIPs) - -Stacks improvement proposals (SIPs) are aimed at describing the implementation of the Stacks blockchain, as well as proposing improvements. - -The SIP process [(SIP-000)](https://github.com/stacksgov/sips/blob/main/sips/sip-000/sip-000-stacks-improvement-proposal-process.md) describes how to make a SIP and get it ratified. - -They should contain concise technical specifications of features or standards and the rationale behind it. SIPs are intended to be the primary medium for proposing new features, for collecting community input on a system-wide issue, and for documenting design decisions. - -The SIPs are located in the [stacksgov/sips](https://github.com/stacksgov/sips) repository as part of the [Stacks Community Governance organization](https://github.com/stacksgov). - -Anyone in the Stacks community can submit a SIP. - -:::tip Stacks Improvement Proposals Community Calls SIP Meeting calls are recorded and available [here](https://www.youtube.com/playlist?list=PLg717Ri_rTnx5kuaWqp3cUAtwQk_yzslT) - -More details of the meetings are available [here](https://github.com/stacksgov/sips/issues/79) ::: - -## Ratified SIPSs - -- [x] [SIP 001: Burn Election](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md) -- [x] [SIP 002: Clarity, a language for predictable smart contracts](https://github.com/stacksgov/sips/blob/main/sips/sip-002/sip-002-smart-contract-language.md) -- [x] [SIP 003: Peer Network](https://github.com/stacksgov/sips/blob/main/sips/sip-003/sip-003-peer-network.md) -- [x] [SIP 004: Cryptographic Committment to Materialized Views](https://github.com/stacksgov/sips/blob/main/sips/sip-004/sip-004-materialized-view.md) -- [x] [SIP 005: Blocks, Transactions, and Accounts](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md) -- [x] [SIP 006: Clarity Execution Cost Assessment](https://github.com/stacksgov/sips/blob/main/sips/sip-006/sip-006-runtime-cost-assessment.md) -- [x] [SIP 007: Stacking Consensus](https://github.com/stacksgov/sips/blob/main/sips/sip-007/sip-007-stacking-consensus.md) -- [x] [SIP 008: Clarity Parsing and Analysis Cost Assessment](https://github.com/stacksgov/sips/blob/main/sips/sip-008/sip-008-analysis-cost-assessment.md) -- [x] [SIP 009: Standard Trait Definition for Non-Fungible Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-009/sip-009-nft-standard.md) -- [x] [SIP 010: Standard Trait Definition for Fungible Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-010/sip-010-fungible-token-standard.md) -- [x] [SIP 012: Burn Height Selection for a Network Upgrade to Introduce New Cost-Limits](https://github.com/stacksgov/sips/blob/main/sips/sip-012/sip-012-cost-limits-network-upgrade.md) -- [x] [SIP-016: Metadata for Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-016/sip-016-token-metadata.md) - -## How to Get Involved - -There are several ways you can get involved with the SIP process: - -* **Join the weekly SIP Meeting call** listed [here](https://community.stacks.org/events). - -* **SIP Editor**. SIP editors help SIP authors make sure their SIPs are well-formed and follow the right process. They help get SIPs ready for deep review by advancing it them from Draft to Accepted status. If you want to become a SIP editor, open an issue with your name and email to ask to be added to the list of SIP editors. - -* **Join a CAB** (Consideration Advisory Board). SIPs fall under the purview of one or more considerations. A full list is in [this github](https://github.com/stacksgov/sips/tree/main/considerations) directory. Currently they are: Diversity, Economics, Ethics, Governance and Technical. Members of SIP consideration advisory boards use their domain expertise to give Accepted SIPs a deep read, and give the authors any/all feedback to help make the SIP workable. If you want to join a board, reach out to the board's chairperson via the listed contact information. - -* **Steering Committee**. The Steering Committee organizes the consideration advisory boards and votes to advance Recommended SIPs to Activation-in-Progress status, and then to either Ratified or Rejected status. Once they are in the process of being activated, they use a SIP's Activation section to determine whether or not the Stacks ecosystem has ratified or rejected the SIP. Joining this committee requires the consent of the Stacks Foundation board. diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/intro.md b/i18n/pt/docusaurus-plugin-content-docs/current/intro.md deleted file mode 100644 index 84f1eaa649..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/intro.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_label: "Home" -sidebar_position: 1 ---- - -# Stacks Docs Introduction - -Welcome to the community driven official Stacks Documentation. - -Learn about Stacks mining, the STX token, and the Clarity smart contract language. - -![](/img/Bitcoinet-L_2.svg) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md b/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md deleted file mode 100644 index dd7194f504..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Stacks on DigitalOcean -description: A guide to setup Stacks on DigitalOcean -sidebar_position: 4 -tags: - - tutorial ---- - -## Introduction - -This is a step by step guide to deploy the [Stacks Blockchain on DigitalOcean](https://marketplace.digitalocean.com/apps/stacks-blockchain). Code is hosted on this [Github repository](https://github.com/stacks-network/stacks-blockchain-docker). - -## Steps - -#### Step 1 - -Go to the [Stacks Blockchain page](https://marketplace.digitalocean.com/apps/stacks-blockchain) in DigitalOcean's marketplace. Click on `Create Stacks Blockchain Droplet`. - -#### Step 2 - -Choose a plan (it will only allow you to select a plan that meets the minimum requirements) and your prefered datacenter region. ![](/img/sh_digitalocean-choose-plan.png) - -#### Step 3 - -Enter a root password or enable SSH keys if your prefer. - -![](/img/sh_digitalocean-choose-authentication.png) - -#### Step 4 - -You can leave the rest of the options as they are and click on `Create Droplet` - -#### Step 5 - -You will need to wait a few seconds for the droplet to get created. Once created click on it to see more information. - -![](/img/sh_digitalocean-creating-droplet.png) - -![](/img/sh_digitalocean-created-droplet.png) - -### Step 6 - -Congratulations! You are now running the Stacks Blockchain. You can click on `Console` for a terminal window to open or login using SSH to the public IP you've been assigned to with user `root`. - -![](/img/sh_digitalocean-console-button.png) ![](/img/sh_digitalocean-console.png) - -## Getting started after deploying Stacks Blockchain - -Once droplet is launched, initial startup can take several minutes while BNS data is imported (this is a one time operation). - -To keep track of the progress, you can `ssh root@your_droplet_public_ipv4` to the host and run: `/opt/stacks-blockchain-docker/manage.sh -n mainnet -a logs`. - -Once the stacks blockchain starts to sync with peers, application ports will open and nginx port 80 will now start proxying requests. - -Use `http://your_droplet_public_ipv4` to access the data directly, with output being similar to: - -```json -{ - "server_version": "stacks-blockchain-api v3.0.3 (master:cd0c8aef)", - "status": "ready", - "chain_tip": { - "block_height": 16220, - "block_hash": "0x3123fba9c0de6b569573494cf83c1d5d198a66bfd5f48ef97949b6bf11ba13be", - "index_block_hash": "0xeec960fbbd6186b4ccac85ce12adba72be497d881f81e077305c90955b51a6ae" - } -} -``` - -All services are managed by a [systemd unit file](https://github.com/stacksfoundation/stacks-machine-images/blob/master/files/etc/systemd/system/stacks.service) that is set to start on boot. - -Manual control is also possible via the [manage.sh script](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/manage.sh) at `/opt/stacks-blockchain-docker/manage.sh` on the host. - -Full details on how to use the manage.sh script is [available here](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/README.md#quickstart). - -## API Creation - -In addition to creating a Droplet from the Stacks Blockchain 1-Click App via the control panel, you can also use the [DigitalOcean API](https://digitalocean.com/docs/api). - -As an example, to create a 4GB Stacks Blockchain Droplet in the SFO2 region, you can use the following curl command. You’ll need to either save your [API access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/) to an environment variable or substitute it into the command below. - -```bash -curl -X POST -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer '$TOKEN'' -d \ - '{"name":"choose_a_name","region":"sfo2","size":"s-2vcpu-4gb","image":"stacksfoundation-stacksblockchain"}' \ - "https://api.digitalocean.com/v2/droplets" -``` diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md b/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md deleted file mode 100644 index b6cbb9754a..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Nodes and Miners -description: Nodes and Miners -sidebar_position: 7 ---- - -Here are all the steps to run nodes and miners, both on mainnet and testnet. - -## What's a Stacks node? - -## What's a Stacks miner? diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md b/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md deleted file mode 100644 index 40397a51e0..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Miner costs and fees -description: Miner Cost and Fee Estimation -sidebar_position: 8 ---- - -## Configuring Cost and Fee Estimation - -Fee and cost estimators can be configured via the config section `[fee_estimation]`: - -``` -[fee_estimation] -cost_estimator = naive_pessimistic -fee_estimator = fuzzed_weighted_median_fee_rate -fee_rate_fuzzer_fraction = 0.1 -fee_rate_window_size = 5 -cost_metric = proportion_dot_product -log_error = true -enabled = true -``` - -Fee and cost estimators observe transactions on the network and use the observed costs of those transactions to build estimates for viable fee rates and expected execution costs for transactions. Estimators and metrics can be selected using the configuration fields above, though the default values are the only options currently. `log_error` controls whether or not the INFO logger will display information about the cost estimator accuracy as new costs are observed. Setting `enabled = false` turns off the cost estimators. Cost estimators are **not** consensus-critical components, but rather can be used by miners to rank transactions in the mempool or client to determine appropriate fee rates for transactions before broadcasting them. - -The `fuzzed_weighted_median_fee_rate` uses a median estimate from a window of the fees paid in the last `fee_rate_window_size` blocks. Estimates are then randomly "fuzzed" using uniform random fuzz of size up to `fee_rate_fuzzer_fraction` of the base estimate. diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md b/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md deleted file mode 100644 index 941ff9ac13..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md +++ /dev/null @@ -1,342 +0,0 @@ ---- -title: Mine mainnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 mainnet -sidebar_position: 5 -tags: - - tutorial ---- - -## Introduction - -Make sure you've followed the [run a node](run-a-node) procedure. Once completed it's only a few more steps to run a proof-of-burn miner on the mainnet. - -If you're interested in mining on the testnet, you can find instructions on how to do that [here](miner-testnet): - -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining): - -## Running bitcoind locally - -To participate as a miner on mainnet, you must have access to a mainnet bitcoin node. One way to accomplish this is to run bitcoind locally. [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements) - -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. - -Next, start bitcoind with the following configuration: - -```toml -server=1 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=1 -banscore=1 -bind=0.0.0.0:8333 -rpcbind=0.0.0.0:8332 -rpcport=8332 -``` - -Finally, start bitcoind as follows: - -```bash -bitcoind -conf=path/to/bitcoin.conf -``` - -It may take a few days for the node to synchronize with the Bitcoin mainnet. - -## Running a miner - -First, a keychain needs to be generated. With this keychain, we'll purchase some BTC from a crytpocurrency exchange, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. We'll use the `make_keychain` command. - -```bash -npx @stacks/cli make_keychain 2>/dev/null | json_pp > keychain.txt -``` - -After this runs, you should see some JSON in the new `keychain.txt` file that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -**Don't lose this information** - we'll need to use the `privateKey` field later on. - -The above BTC address will then need to be imported into the BTC network. - -```bash -bitcoin-cli -rpcport=8332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - - - -Once imported, we need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - - - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/mainnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `make_keychain` command. Replace the `seed` field with your private key. Save and close this configuration file. - -To run your miner, run this in the command line: - -```bash -stacks-node start --config=./testnet/stacks-node/conf/mainnet-miner-conf.toml -``` - -Your node should start. It will take some time to sync, and then your miner will be running. - -### Creating an optimized binary - -The steps above are great for trying to run a node temporarily. If you want to host a node on a server somewhere, you might want to generate an optimized binary. To do so, use the same configuration as above, but run: - -```bash -cd testnet/stacks-node -cargo build --release --bin stacks-node -``` - -The above code will compile an optimized binary. To use it, run: - -```bash -cd ../.. -./target/release/stacks-node start --config=./mainnet-miner-conf.toml -``` - -To read more about the technical details of mining on the Stacks 2.0 network, have a look at [the mining guide](../understand-stacks/mining). - -### Enable debug logging - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -STACKS_LOG_DEBUG=1 stacks-node mainnet -``` - -## Running a miner in Windows - -### Prerequisites - -Make sure are [running a node](run-a-node) and [running bitcoind locally](#running-bitcoind-locally) before starting this tutorial. - -### Generate keychain and get mainnet tokens in Windows - -To setup the miner, first we need to generate a keychain. With this keychain, we'll purchase some BTC from a crytpocurrency exchange, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. To get a keychain, the simplest way is to use the `stacks-cli`. - -Generate a keychain: - -```bash -npm install --global @stacks/cli -stx make_keychain > cli_keychain.json -type cli_keychain.json -``` - -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -The above BTC address will then need to be imported into the BTC network. - -```bash -bitcoin-cli -rpcport=8332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - -Once imported, we need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Update configuration file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/mainnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Run the miner - -To start your miner, run this in the command line: - -```bash -stacks-node start --config=testnet/stacks-node/conf/mainnet-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](/img/windows-defender.png) - -Your node should start. It will take some time to sync, and then your miner will be running. - -### Enable debug logging in Windows - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=mainnet-miner-conf.toml -``` - -## Optional: Running with Docker - -Alternatively, you can run the mainnet node with Docker. - -:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: - -### Generate keychain and get tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null -``` - -We need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Update configuration file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/mainnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Start the miner - -:::info The ENV VARS `RUST_BACKTRACE` and `STACKS_LOG_DEBUG` are optional. If removed, debug logs will be disabled ::: - -```bash -docker run -d \ - --name stacks_miner \ - --rm \ - --network host \ - -e RUST_BACKTRACE="full" \ - -e STACKS_LOG_DEBUG="1" \ - -v "$(pwd)/testnet/stacks-node/conf/mainnet-miner-conf.toml:/src/stacks-node/mainnet-miner-conf.toml" \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain:latest \ -/bin/stacks-node start --config /src/stacks-node/mainnet-miner-conf.toml -``` - -You can review the node logs with this command: - -```bash -docker logs -f stacks_miner -``` - -## Optional: Running in Kubernetes with Helm - -In addition, you're also able to run a mainnet node in a Kubernetes cluster using the [stacks-blockchain Helm chart](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). - -Ensure you have the following prerequisites installed on your machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [minikube](https://minikube.sigs.k8s.io/docs/start/) (Only needed if standing up a local Kubernetes cluster) -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [helm](https://helm.sh/docs/intro/install/) - -### Generate keychain and get some tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null -``` - -We need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Install the chart and run the miner - -To install the chart with the release name `my-release` and run the node as a miner: - -```bash -minikube start # Only run this if standing up a local Kubernetes cluster -helm repo add blockstack https://charts.blockstack.xyz -helm install my-release blockstack/stacks-blockchain \ - --set config.node.miner=true \ - --set config.node.seed="replace-with-your-privateKey-from-generate-keychain-step" \ - --set config.burnchain.mode="mainnet" -``` - -You can review the node logs with this command: - -```bash -kubectl logs -l app.kubernetes.io/name=stacks-blockchain -``` - -For more information on the Helm chart and configuration options, please refer to the [chart's homepage](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md b/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md deleted file mode 100644 index 1bee3a9923..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md +++ /dev/null @@ -1,335 +0,0 @@ ---- -title: Mine testnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 testnet -sidebar_position: 4 -tags: - - tutorial ---- - -## Introduction - -Make sure you've followed the [Run a node](run-a-node) procedure. Once completed it's only a few more steps to run a proof-of-burn miner on the testnet. - -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining). - -## Running bitcoind locally - -To participate as a miner on Testnet, you must have access to a testnet bitcoin node. One way to accomplish this is to run bitcoind locally. [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements) - -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. - -Next, start bitcoind with the following configuration: - -```toml -server=1 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password -testnet=1 -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=1 -banscore=1 - -[test] -bind=0.0.0.0:18333 -rpcbind=0.0.0.0:18332 -rpcport=18332 -``` - -Finally, start bitcoind as follows: - -```bash -bitcoind -conf=path/to/bitcoin.conf -``` - -It may take a few hours for the node to synchronize with the Bitcoin testnet. - -## Running a miner - -First, a keychain needs to be generated. With this keychain, we'll get some testnet BTC from a faucet, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. To get a keychain, the simplest way is to use the `stacks-cli`. - -```bash -npx @stacks/cli make_keychain -t 2>/dev/null | json_pp > keychain.txt -``` - -After this runs, you should see some JSON in the new `keychain.txt` file that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -**Don't lose this information** - we'll need to use the `privateKey` field later on. - -The above BTC address will then need to be imported into the BTC testnet network. - -```bash -bitcoin-cli -rpcport=18332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - -Once imported, we need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). You'll be sent `0.01` testnet BTC to that address. - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/testnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/testnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `make_keychain` command. Replace the `seed` field with your private key. Save and close this configuration file. - -To run your miner, run this in the command line: - -```bash -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. - -### Creating an optimized binary - -The steps above are great for trying to run a node temporarily. If you want to host a node on a server somewhere, you might want to generate an optimized binary. To do so, use the same configuration as above, but run: - -```bash -cd testnet/stacks-node -cargo build --release --bin stacks-node -``` - -The above code will compile an optimized binary. To use it, run: - -```bash -cd ../.. -./target/release/stacks-node start --config=./testnet/conf/testnet-follower-conf.toml -``` - -To read more about the technical details of mining on the Stacks 2.0 network, have a look at [the minig guide](../understand-stacks/mining): - -### Enable debug logging - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -STACKS_LOG_DEBUG=1 stacks-node testnet -``` - -## Running a miner in Windows - -### Prerequisites - -Make sure are [running a testnet node](run-a-node) before starting this tutorial. - -### Generate keychain and get testnet tokens in Windows - -To setup the miner, first, we need to generate a keychain. With this keychain, we'll get some testnet BTC from a faucet, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. We'll use the `stx make-keychain` command, and pass `-t` to indicate that we want a testnet keychain. - -Generate a keychain: - -```bash -npm install --global @stacks/cli -stx make_keychain -t > cli_keychain.json -type cli_keychain.json -``` - -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -Request BTC from faucet: - -We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). - -### Update configuration file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/testnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/testnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Run the miner - -To start your miner, run this in the command line: - -```bash -stacks-node start --config=testnet/stacks-node/conf/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](/img/windows-defender.png) - - - -Your node should start. It will take some time to sync, and then your miner will be running. - -### Enable debug logging in Windows - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=testnet-miner-conf.toml -``` - -## Optional: Running with Docker - -Alternatively, you can run the testnet node with Docker. - -:::warning Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: - -### Generate keychain and get testnet tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` - -We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). - -### Update config file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/testnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/testnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Start the miner - -:::info The ENV VARS `RUST_BACKTRACE` and `STACKS_LOG_DEBUG` are optional. If removed, debug logs will be disabled ::: - -```bash -docker run -d \ - --name stacks_miner \ - --rm \ - --network host \ - -e RUST_BACKTRACE="full" \ - -e STACKS_LOG_DEBUG="1" \ - -v "$(pwd))/testnet/stacks-node/conf/testnet-miner-conf.toml:/src/stacks-node/testnet-miner-conf.toml" \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain:latest \ -/bin/stacks-node start --config /src/stacks-node/testnet-miner-conf.toml -``` - -You can review the node logs with this command: - -```bash -docker logs -f stacks_miner -``` - -## Optional: Running in Kubernetes with Helm - -In addition, you're also able to run a testnet node in a Kubernetes cluster using the [stacks-blockchain Helm chart](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). - -Ensure you have the following prerequisites installed on your machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [minikube](https://minikube.sigs.k8s.io/docs/start/) (Only needed if standing up a local Kubernetes cluster) -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [helm](https://helm.sh/docs/intro/install/) - -### Generate keychain and get some testnet tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` - -We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). - -### Install the chart and run the miner - -To install the chart with the release name `my-release` and run the node as a miner: - -```bash -minikube start # Only run this if standing up a local Kubernetes cluster -helm repo add blockstack https://charts.blockstack.xyz -helm install my-release blockstack/stacks-blockchain \ - --set config.node.miner=true \ - --set config.node.seed="replace-with-your-privateKey-from-generate-keychain-step" -``` - -You can review the node logs with this command: - -```bash -kubectl logs -l app.kubernetes.io/name=stacks-blockchain -``` - -For more information on the Helm chart and configuration options, please refer to the [chart's homepage](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md b/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md deleted file mode 100644 index 94d938c5ca..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md +++ /dev/null @@ -1,351 +0,0 @@ ---- -title: Run a node -description: Set up and run a Stacks node -sidebar_position: 1 -tags: - - tutorial ---- - -## Stacks Blockchain with Docker - -Run your own Stacks Blockchain node easily with just few commands. - -This tutorial describes a simple and effective [quickstart](#quickstart) to run a Stacks node using public scripts hosted in [Stacks Blockchain repository](https://github.com/stacks-network/stacks-blockchain-docker). Valid for mainnet, testnet and mocknet. - -## **Quickstart** - -1. **Clone the stacks-blockchain-docker repository locally** - -```bash -git clone https://github.com/stacks-network/stacks-blockchain-docker && cd stacks-blockchain-docker -``` - -2. **Optionally, create/copy `.env` file**. If file `.env` doesn't exist when launched it will be created from `sample.env` automatically. - -```bash -cp sample.env .env -``` - -_You may also use a symlink as an alternative to copying: `ln -s sample.env .env`_ - -3. **Optionally, ensure all images are up to date** - -```bash -./manage.sh -n -a pull -``` - -4. **Start the Services** - -```bash -./manage.sh -n -a start -``` - -- With optional proxy: - -```bash -./manage.sh -n -a start -f proxy -``` - -- With optional bitcoin node: - -```bash -./manage.sh -n -a start -f bitcoin -``` - -5. **Stop the Services** - -```bash -./manage.sh -n -a stop -``` - -6. **Retrieve Service Logs** - -```bash -./manage.sh -n -a logs -``` - -- Export docker log files to `./exported-logs`: - -This will create one log file for every running service, for example: postgres.log, stacks-blockain.log, stacks-blockchain-api.log and bitcoin-core.log. -Notice that each time you run this command the log files will be overwritten. - -```bash -./manage.sh -n -a logs export -``` - -7. **Restart all services** - -```bash -./manage.sh -n -a restart -``` - -- With optional proxy: - -```bash -./manage.sh -n -a restart -f proxy -``` - -8. **Delete** all data in `./persistent-data/` and/or data of the Bitcoin blockchain. - - This data is owned by root, so you will need to run it with sudo privileges so it can delete the data. - -```bash -$ sudo ./manage.sh -n -a reset - -Please confirm what persistent data you wish to delete: - -0. Cancel -1. Delete Persistent data for Stacks testnet only and leave Bitcoin blockchain data unaffected. -2. Delete Persistent data for Stacks testnet and Bitcoin blockchain data in ./persistent-data/blockchain-bitcoin -3. Delete Persistent data for Bitcoin blockchain data in ./persistent-data/blockchain-bitcoin only. -Please note that BNS data will never get deleted. - -Type 0, 1, 2 or 3: 2 - -Ok. Delete Stacks and Bitcoin data. -[ Success ] Persistent data deleted for Bitcoin blockchain. -[ Success ] Persistent data deleted for Stacks testnet. - -``` - -9. **Download BNS data to** `./persistent-data/bns-data` - -```bash -./manage.sh bns -``` - -10. **Export stacks-blockchain-api events** (_Not applicable for mocknet_) - -```bash -./manage.sh -n -a export -# check logs for completion -./manage.sh -n -a restart -``` - -11. **Replay stacks-blockchain-api events** (_Not applicable for mocknet_) - -```bash -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart -``` - -## **Running also a bitcoin node (Optional)** - -Stacks needs to use a Bitcoin node, and by default when you run a Stacks node you will be using a public Bitcoin node, which is configured in the `.env` file. Default values is `BITCOIN_NODE=bitcoin.mainnet.stacks.org`. - -However, you can optionaly run both nodes together and configured in a way that you Stacks node will use your own Bitcoin node instead of a public one. - -If you run the script with a bitcoin node it will download and build it directly from source for increased security. This process which only needs to happen once can take up to 20-30 minutes depending on the speed of your system. Also, once the bitcoin node is up and running it will need an additional time for sync for the first time (can be hours for testnet and days for mainnet). - -### Why run Stacks node with your own Bitcoin node? - -Because running your own Bitcoin node will give you higher security and improved perfomance. - -* **Improved perfomance**: The Bitcoin node will serve you blocks faster, as well as UTXOs for your miner (if you run one). -* **Higher security**: The Bitcoin node will also have validated all bitcoin transactions the Stacks node consumes. If you don't run your own Bitcoin node, you're relying on the SPV headers to vouch for the validity of Bitcoin blocks. - -The disadvantage of running your own Bitcoin node is that you need the extra space to store the Bitcoin blockchain (about 500GB) and the initial time it will take to download this data the first time. - -### Example - -You can run easily run your Stacks node with your own Bitcoin node by adding the flag `bitcoin`. This is available only for testnet and mainnet. - -Example: `./manage.sh -n mainnet -a start -f bitcoin` or `./manage.sh -n testnet -a start -f bitcoin` - -### Bitcoin node configuration - -In the `.env` file there is the variable `BITCOIN_BLOCKCHAIN_FOLDER`. As the bitcoin blockchain can be large (over 500GB) you optionally change this variable to any location of your choosing. If you have previously used the [bitcoin core application](https://bitcoin.org/en/bitcoin-core/) and already have the bitcoin blockchain synced, you can use the same data folder and avoid redownloading the entire bitcoin blockchain. - -## **Accessing the services** - -:::tip For networks other than `mocknet`, downloading the initial headers can take several minutes. Until the headers are downloaded, the `/v2/info` endpoints won't return any data. - -Use the command `./manage.sh -n -a logs` to check the sync progress. ::: - -**stacks-blockchain**: - -- Ports `20443-20444` are exposed to `localhost` - -```bash -curl -sL localhost:20443/v2/info | jq -``` - -**stacks-blockchain-api**: - -- Port `3999` are exposed to `localhost` - -```bash -curl -sL localhost:3999/v2/info | jq -``` - -**proxy**: - -- Port `80` is exposed to `localhost` - -```bash -curl -sL localhost/v2/info | jq -curl -sL localhost/ | jq -``` - ---- - -## Upgrades - -⚠️ For upgrades to running instances of this repo, you'll need to [run the event-replay](https://github.com/hirosystems/stacks-blockchain-api#event-replay): - -```bash -./manage.sh -n -a stop -./manage.sh -n -a export -./manage.sh -n -a import -./manage.sh -n -a restart -``` - ---- - -## **Workarounds to potential issues** - -_**Port(s) already in use**_: - -- 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. `3999` and edit your `.env` file to use the new port. - -```bash -netstat -anl | grep 3999 -``` - -``` -tcp46 0 0 *.3999 *.* LISTEN -``` - -_**Containers not starting (hanging on start)**_: - -- Occasionally, docker can get **stuck** and not allow new containers to start. If this happens, simply restart your docker daemon and try again. - -_**Database Issues**_: - -- For any of the various Postgres/sync issues, it may be easier to simply remove the persistent data dir. Note that doing so will result in a longer startup time as the data is repopulated. - -```bash -./manage.sh -n -a stop -./manage.sh -n -a reset -./manage.sh -n -a start -``` - -_**API Missing Parent Block Error**_: - -- If the Stacks blockchain is no longer syncing blocks, and the API reports an error similar to this:\ - `Error processing core node block message DB does not contain a parent block at height 1970 with index_hash 0x3367f1abe0ee35b10e77fbcaa00d3ca452355478068a0662ec492bb30ee0f13e"`,\ - The API (and by extension the DB) is out of sync with the blockchain. \ - The only known method to recover is to resync from genesis (**event-replay _may_ work, but in all likelihood will restore data to the same broken state**). - -- To attempt the event-replay - -```bash -./manage.sh -n -a stop -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart -``` - -- To wipe data and re-sync from genesis - -```bash -./manage.sh -n -a stop -./manage.sh -n -a reset -./manage.sh -n -a restart -``` - - -## **Requirements:** - -- [Docker](https://docs.docker.com/get-docker/) >= `17.09` -- [docker-compose](https://github.com/docker/compose/releases/) >= `1.27.4` -- [git](https://git-scm.com/downloads) -- [jq binary](https://stedolan.github.io/jq/download/) -- [sed](https://www.gnu.org/software/sed/) -- Machine with (at a minimum): - - 4GB memory - - 1 Vcpu - - 50GB storage (600GB if you optionally also run the bitcoin mainnet node) - -:::caution MacOS with an M1 processor is NOT recommended - -The way Docker for Mac on an Arm chip is designed makes the I/O incredibly slow, and blockchains are **_very_** heavy on I/O. This only seems to affect MacOS, other Arm based systems like Raspberry Pi's seem to work fine. - -::: - - -### Install/Update docker-compose - -:::note `docker-compose` executable is required, even though recent versions of Docker contain `compose` natively ::: - -- [Install Docker-compose](https://docs.docker.com/compose/install/) -- [Docker Desktop for Mac](https://docs.docker.com/docker-for-mac/install/) -- [Docker Desktop for Windows](https://docs.docker.com/docker-for-windows/install/) -- [Docker Engine for Linux](https://docs.docker.com/engine/install/#server) - -First, check if you have `docker-compose` installed locally. - -To do that, run this command in your terminal : - -```bash -docker-compose --version -``` - -Output should look something very similar to this : - -``` -docker-compose version 1.27.4, build 40524192 -``` - -If the command is not found, or the version is < `1.27.4`, run the following to install the latest to `/usr/local/bin/docker-compose`: - -```bash -#You will need to have jq installed, or this snippet won't run. -VERSION=$(curl --silent https://api.github.com/repos/docker/compose/releases/latest | jq .name -r) -DESTINATION=/usr/local/bin/docker-compose -sudo curl -L https://github.com/docker/compose/releases/download/${VERSION}/docker-compose-$(uname -s)-$(uname -m) -o $DESTINATION -sudo chmod 755 $DESTINATION -``` - -### Security note on docker - -The Docker daemon always runs as the root user so by default you will need root privileges to interact with it. - -The script `manage.sh` uses docker, so to avoid the requirement of needing to run the script with root privileges it is prefered to be able to *manage Docker as a non-root user*, following [these simple tests](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user). - -This will avoid the need of running the script with root privileges for all operations except the removal of data. - -### Configuration files you can edit - -The following files can be modified to personalize your node configuration, but generally most of them should be left as-is. All these files will be created from the sample copy if they don't exist at runtime (for example `.env` is created from `sample.env`). However these files will never be modified by the application once created and will never be pushed back to github, so your changes will be safe. - -* `.env` -* `./conf/mainnet/Config.toml` -* `./conf/mainnet/bitcoin.conf` -* `./conf/testnet/Config.toml` -* `./conf/testnet/bitcoin.conf` - -By default: - -- BNS data is **not** enabled/imported - - To enable, uncomment `# BNS_IMPORT_DIR=/bns-data` in `./env` - - Download BNS data: `./manage.sh bns` -- Fungible token metadata is **not** enabled - - To enable, uncomment `# STACKS_API_ENABLE_FT_METADATA=1` in `./env` -- Non-Fungible token metadata is **not** enabled - - To enable, uncomment `# STACKS_API_ENABLE_NFT_METADATA=1` in `./env` -- Verbose logging is **not** enabled - - To enable, uncomment `# VERBOSE=true` in `./env` -- Bitcoin blockchain folder is configured in `BITCOIN_BLOCKCHAIN_FOLDER` in `./env` - -### Local Data Dirs - -Directories will be created on first start that will store persistent data under `./persistent-data/` - -`` can be 1 of: - -- mainnet -- testnet -- mocknet diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md b/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md deleted file mode 100644 index c3d36daebd..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md +++ /dev/null @@ -1,186 +0,0 @@ ---- -title: Running a mainnet node -description: Set up and run a mainnet node with Docker -sidebar_position: 3 -tags: - - tutorial ---- - -## Introduction - -This procedure demonstrates how to run a local mainnet node using Docker images. - -:::caution This procedure focuses on Unix-like operating systems (Linux and MacOS). This procedure has not been tested on Windows. -::: - -## Prerequisites - -Running a node has no specialized hardware requirements. Users have been successful in running nodes on Raspberry Pi boards and other system-on-chip architectures. In order to complete this procedure, you must have the following software installed on the node host machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [curl](https://curl.se/download.html) -- [jq](https://stedolan.github.io/jq/download/) - -### Firewall configuration - -In order for the API node services to work correctly, you must configure any network firewall rules to allow traffic on the ports discussed in this section. The details of network and firewall configuration are highly specific to your machine and network, so a detailed example isn't provided. - -The following ports must open on the host machine: - -Ingress: - -- stacks-blockchain (open to `0.0.0.0/0`): - - `20443 TCP` - - `20444 TCP` - -Egress: - -- `8332` -- `8333` -- `20443-20444` - -These egress ports are for syncing stacks-blockchain and Bitcoin headers. If they're not open, the sync will fail. - -## Step 1: initial setup - -In order to run the mainnet node, you must download the Docker images and create a directory structure to hold the persistent data from the services. Download and configure the Docker images with the following commands: - -```sh -docker pull blockstack/stacks-blockchain -``` - -Create a directory structure for the service data with the following command: - -```sh -mkdir -p ./stacks-node/{persistent-data/stacks-blockchain/mainnet,config/mainnet} && cd stacks-node -``` - -## Step 2: running Stacks blockchain - -First, create the `./config/mainnet/Config.toml` file and add the following content to the file using a text editor: - -```toml -[node] -working_dir = "/root/stacks-node/data" -rpc_bind = "0.0.0.0:20443" -p2p_bind = "0.0.0.0:20444" -bootstrap_node = "02da7a464ac770ae8337a343670778b93410f2f3fef6bea98dd1c3e9224459d36b@seed-0.mainnet.stacks.co:20444,02afeae522aab5f8c99a00ddf75fbcb4a641e052dd48836408d9cf437344b63516@seed-1.mainnet.stacks.co:20444,03652212ea76be0ed4cd83a25c06e57819993029a7b9999f7d63c36340b34a4e62@seed-2.mainnet.stacks.co:20444" -wait_time_for_microblocks = 10000 - -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "bitcoin.blockstack.com" -username = "blockstack" -password = "blockstacksystem" -rpc_port = 8332 -peer_port = 8333 - -[connection_options] -read_only_call_limit_write_length = 0 -read_only_call_limit_read_length = 100000 -read_only_call_limit_write_count = 0 -read_only_call_limit_read_count = 30 -read_only_call_limit_runtime = 1000000000 -``` - -Start the `stacks-blockchain` container with the following command: - -```sh -docker run -d --rm \ - --name stacks-blockchain \ - -v $(pwd)/persistent-data/stacks-blockchain/mainnet:/root/stacks-node/data \ - -v $(pwd)/config/mainnet:/src/stacks-node \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain \ -/bin/stacks-node start --config /src/stacks-node/Config.toml -``` - -You can verify the running `stacks-blockchain` container with the command: - -```sh -docker ps --filter name=stacks-blockchain -``` - -## Step 3: verifying the services - -:::note The initial burnchain header sync can take several minutes, until this is done the following commands will not work -::: - -To verify the `stacks-blockchain` burnchain header sync progress: - -```sh -docker logs stacks-blockchain -``` - -The output should be similar to the following: - -``` -INFO [1626290705.886954] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.2% (8000 out of 691034) -INFO [1626290748.103291] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.4% (10000 out of 691034) -INFO [1626290776.956535] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.7% (12000 out of 691034) -``` - -To verify the `stacks-blockchain` tip height is progressing use the following command: - -```sh -curl -sL localhost:20443/v2/info | jq -``` - -If the instance is running you should recieve terminal output similar to the following: - -```json -{ - "peer_version": 402653184, - "pox_consensus": "89d752034e73ed10d3b97e6bcf3cff53367b4166", - "burn_block_height": 666143, - "stable_pox_consensus": "707f26d9d0d1b4c62881a093c99f9232bc74e744", - "stable_burn_block_height": 666136, - "server_version": "stacks-node 2.0.11.1.0-rc1 (master:67dccdf, release build, linux [x86_64])", - "network_id": 1, - "parent_network_id": 3652501241, - "stacks_tip_height": 61, - "stacks_tip": "e08b2fe3dce36fd6d015c2a839c8eb0885cbe29119c1e2a581f75bc5814bce6f", - "stacks_tip_consensus_hash": "ad9f4cb6155a5b4f5dcb719d0f6bee043038bc63", - "genesis_chainstate_hash": "74237aa39aa50a83de11a4f53e9d3bb7d43461d1de9873f402e5453ae60bc59b", - "unanchored_tip": "74d172df8f8934b468c5b0af2efdefe938e9848772d69bcaeffcfe1d6c6ef041", - "unanchored_seq": 0, - "exit_at_block_height": null -} -``` - -## Stopping the mainnet node - -Use the following commands to stop the local mainnet node: - -```sh -docker stop stacks-blockchain -``` - -## Optional. Run stacks node with own bitcoin node - -It's encouraged to use your own bitcoin node when possible. - -To do this simply update the `stacks-node/config/mainnet/Config.toml` file with the details of your bitcoin node. For example: - -``` -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "localhost" -username = "rpc username" -password = "rpc password" -rpc_port = 8332 -peer_port = 8333 -``` - -The rpc configuration of your bitcoin node is out of the scope of this document, but you can find more information on how to set it up [here](https://developer.bitcoin.org/examples/intro.html). - -## Additional reading - - - -- [Running a Stacks API node](https://docs.hiro.so/get-started/running-api-node) -- [Running a Stacks testnet node](running-testnet-node) - diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md b/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md deleted file mode 100644 index 2af673c556..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -title: Running a testnet node -description: Set up and run a testnet node with Docker -sidebar_position: 2 -tags: - - tutorial ---- - -## Introduction - -This procedure demonstrates how to run a local testnet node using Docker images. - -:::caution This procedure focuses on Unix-like operating systems (Linux and MacOS). This procedure has not been tested on Windows. -::: - -## Prerequisites - -Running a node has no specialized hardware requirements. Users have been successful in running nodes on Raspberry Pi boards and other system-on-chip architectures. In order to complete this procedure, you must have the following software installed on the node host machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [curl](https://curl.se/download.html) -- [jq](https://stedolan.github.io/jq/download/) - -### Firewall configuration - -In order for the API node services to work correctly, you must configure any network firewall rules to allow traffic on the ports discussed in this section. The details of network and firewall configuration are highly specific to your machine and network, so a detailed example isn't provided. - -The following ports must open on the host machine: - -Ingress: - -- stacks-blockchain (open to `0.0.0.0/0`): - - `20443 TCP` - - `20444 TCP` - -Egress: - -- `18332` -- `18333` -- `20443-20444` - -These egress ports are for syncing stacks-blockchain and Bitcoin headers. If they're not open, the sync will fail. - -## Step 1: initial setup - -In order to run the testnet node, you must download the Docker images and create a directory structure to hold the persistent data from the services. Download and configure the Docker images with the following commands: - -```sh -docker pull blockstack/stacks-blockchain -``` - -Create a directory structure for the service data with the following command: - -```sh -mkdir -p ./stacks-node/persistent-data/stacks-blockchain/testnet && cd stacks-node -``` - -## Step 2: running Stacks blockchain - -Start the stacks-blockchain container with the following command: - -```sh -docker run -d --rm \ - --name stacks-blockchain \ - -v $(pwd)/persistent-data/stacks-blockchain/testnet:/root/stacks-node/data \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain \ -/bin/stacks-node testnet -``` - -You can verify the running stacks-blockchain container with the command: - -```sh -docker ps --filter name=stacks-blockchain -``` - -## Step 3: verifying the services - -:::info The initial burnchain header sync can take several minutes, until this is done the following commands will not work -::: - -To verify the stacks-blockchain burnchain header sync progress: - -```sh -docker logs stacks-blockchain -``` - -The output should be similar to the following: - -``` -INFO [1626290705.886954] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.2% (8000 out of 2034380) -INFO [1626290748.103291] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.4% (10000 out of 2034380) -INFO [1626290776.956535] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.7% (12000 out of 2034380) -``` - -To verify the stacks-blockchain tip height is progressing use the following command: - -```sh -curl -sL localhost:20443/v2/info | jq -``` - -If the instance is running you should recieve terminal output similar to the following: - -```json -{ - "peer_version": 4207599105, - "pox_consensus": "12f7fa85e5099755a00b7eaecded1aa27af61748", - "burn_block_height": 2034380, - "stable_pox_consensus": "5cc4e0403ff6a1a4bd17dae9600c7c13d0b10bdf", - "stable_burn_block_height": 2034373, - "server_version": "stacks-node 2.0.11.2.0-rc1 (develop:7b6d3ee+, release build, linux [x86_64])", - "network_id": 2147483648, - "parent_network_id": 118034699, - "stacks_tip_height": 509, - "stacks_tip": "e0ee952e9891709d196080ca638ad07e6146d4c362e6afe4bb46f42d5fe584e8", - "stacks_tip_consensus_hash": "12f7fa85e5099755a00b7eaecded1aa27af61748", - "genesis_chainstate_hash": "74237aa39aa50a83de11a4f53e9d3bb7d43461d1de9873f402e5453ae60bc59b", - "unanchored_tip": "32bc86590f11504f17904ee7f5cb05bcf71a68a35f0bb3bc2d31aca726090842", - "unanchored_seq": 0, - "exit_at_block_height": null -} -``` - -## Stopping the testnet node - -Use the following commands to stop the local testnet node: - -```sh -docker stop stacks-blockchain -``` - -## Additional reading - - - -- [Running a Stacks API node](https://docs.hiro.so/get-started/running-api-node) -- [Running a Stacks mainnet node](running-mainnet-node) - diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md b/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md deleted file mode 100644 index 9ea58d7a89..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md +++ /dev/null @@ -1,504 +0,0 @@ ---- -title: Stacks Node Configuration -description: Configuration parameters and options for the stacks-node binary -sidebar_position: 6 ---- - -## Usage - -```bash -stacks-node sub-command [--subcommand-option ] -``` - -## Subcommands - -:::caution The `stacks-node` binary may have deprecated commands that are not documented on this page. Deprecated commands may be accessible until they are fully removed from the sources. ::: - -### mocknet - -Start a node based on a fast local setup emulating a burnchain. Ideal for smart contract development. - -Example: - -```bash -stacks-node mocknet -``` - -### krypton - -Start a node that will join and stream blocks from the public krypton regtest, powered by Blockstack via [Proof of Transfer](../understand-stacks#consensus-mechanism). - -Example: - -```bash -stacks-node krypton -``` - -### testnet - -Start a node that will join and stream blocks from the public testnet. - -Example: - -```bash -stacks-node testnet -``` - -### mainnet - -Start a node that joins and streams blocks from the public mainnet. - -Example: - -```bash -stacks-node mainnet -``` - -### start - -Start a node with a config of your own. Can be used for joining a network, starting a new chain, or replacing default values used by the `mocknet` or `testnet` subcommands. - -#### Arguments - -**--config**: relative or absolute path to the TOML config file. Required. - -Example: - -```bash -stacks-node start --config=/path/to/config.toml -``` - -See [Configuration File Options](#configuration-file-options) for more information. - -#### version - -Displays information about the current version and the release cycle. - -Example: - -```bash -stacks-node version -``` - -#### help - -Displays a help message. - -Example: - -```bash -stacks-node help -``` - -## Configuration File Options - -The TOML configuration file has multiple sections under which an option may be placed. - -To see a list of example configurations, [please see this page](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf). - -### Section: node - -Contains various configuration options pertaining to the stacks-node. - -Example: - -```toml -[node] -rpc_bind = "0.0.0.0:20443" -p2p_bind = "0.0.0.0:20444" -# Enter your private key here -seed = "replace-with-your-private-key" -miner = true -``` - -#### working_dir (optional) - -Absolute path to the directory which the stacks-node will use for storing various data. - -Example: - -```toml -working_dir = "/root/stacks-node" -``` - -#### rpc_bind - -Address and port stacks-node should bind to for RPC connections. - -Example: - -```toml -rpc_bind = "0.0.0.0:20443" -``` - -#### p2p_bind - -Address and port stacks-node should bind to for P2P connections. - -Example: - -```toml -p2p_bind = "0.0.0.0:20444" -``` - -#### data_url (optional) - -Address and port from which the stacks-node will be receiving incoming rpc connections. - -Example: - -```toml -data_url = "1.2.3.4:20443" -``` - -#### p2p_address (optional) - -Address and port from which the stacks-node will be receiving incoming p2p connections. - -Example: - -```toml -p2p_address = "1.2.3.4:20444" -``` - -#### bootstrap_node (optional) - -Public key, address, and port stacks-node should use to pull transaction data from when starting. - -Example: - -```toml -bootstrap_node = "047435c194e9b01b3d7f7a2802d6684a3af68d05bbf4ec8f17021980d777691f1d51651f7f1d566532c804da506c117bbf79ad62eea81213ba58f8808b4d9504ad@testnet.blockstack.org:20444" -``` - -#### wait_time_for_microblocks (optional) - -The amount of time (in milliseconds) that a node will wait before trying to mine a block, after catching up to the anchored chain tip. This gives the current leader time to broadcast microblocks that will get included in that mined block. This gives the current leader time to broadcast microblocks that will get included in that mined block. - -Example: - -```toml -wait_time_for_microblocks = 15000 -``` - -#### seed (optional) - -The private key to use for mining. Only needed if `miner` is set to `true`. - -Example: - -```toml -seed = "replace-with-your-private-key" -``` - -#### local_peer_seed (optional) - -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. - -Example: - -```toml -local_peer_seed = "replace-with-your-private-key" -``` - -#### miner (optional) - -Determines whether the stacks-node is running a follower (`false`) or a miner (`true`). Defaults to `false` if omitted. - -Example: - -```toml -miner = true -``` - -#### mine_microblocks (optional) - -Determines whether the stacks-node will mine microblocks. Will only take effect if `miner` is set to `true`. - -Example: - -```toml -mine_microblocks = true -``` - -#### prometheus_bind (optional) - -Address and port stacks-node should open for Prometheus metrics collection. - -Example: - -```toml -prometheus_bind = "0.0.0.0:9153" -``` - -### Section: events_observer (optional) - -Contains options for watching events emitted by a local [stacks-blockchain-api](https://github.com/hirosystems/stacks-blockchain-api) service. - -:::info This section can be repeated multiple times. -::: - -Example: - -```toml -[[events_observer]] -endpoint = "address-to-my-local.stacks-node-api.com:3700" -retry_count = 255 -events_keys = ["*"] -``` - -#### endpoint - -Address and port to a stacks-node-api to watch for events. - -Example: - -```toml -endpoint = "address-to-my-local.stacks-node-api.com:3700" -``` - -#### retry_count - -Number of times to retry sending events to the endpoint before failing. - -Example: - -```toml -retry_count = 255 -``` - -#### events_keys - -Event keys for which to watch. The emitted node events can be restricted by account, function name and event type. Asterix ("\*") can be used to emit all events. - -Examples: - -```toml -events_keys = ["*"] -``` - -```toml -events_keys = [ - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.store::print", - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.contract.ft-token", - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.contract.nft-token", - "stx" -] -``` - -### Section: connection_options (optional) - -Specifies configuration options for others connecting to the stacks node. - -Example: - -```toml -[connection_options] -public_ip_address = "1.2.3.4:20444" -download_interval = 60 -walk_interval = 30 -``` - -#### public_ip_address - -The advertised public IP of this stacks-node. - -Example: - -```toml -public_ip_address = "1.2.3.4:20444" -``` - -#### download_interval - -Time (in seconds) between attempts to download blocks. - -Example: - -```toml -download_interval = 60 -``` - -#### walk_interval - -Time (in seconds) between attempts to walk the neighborhood. - -Example: - -```toml -walk_interval = 30 -``` - -#### read_only_call_limit_read_length - -Total number of bytes allowed to be read by an individual read-only function call. - -Example: - -```toml -read_only_call_limit_read_length = 100000 -``` - -#### read_only_call_limit_read_count - -Total number of independent read operations permitted for an individual read-only function call. - -Example: - -```toml -read_only_call_limit_read_count = 30 -``` - -#### read_only_call_limit_runtime - -[Runtime cost](https://github.com/stacksgov/sips/blob/2d3fd9bf8da7a04f588d90ff6252173d7609d7bf/sips/sip-006/sip-006-runtime-cost-assessment.md#introduction) limit for an individual read-only function call. - -Example: - -```toml -read_only_call_limit_runtime = 1000000000 -``` - -### Section: burnchain - -This section contains configuration options pertaining to the blockchain the stacks-node binds to on the backend for proof-of-transfer (BTC). - -Example: - -```toml -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "your.bitcoind.node.org" -rpc_port = 8332 -peer_port = 8333 -``` - -#### chain - -The blockchain stacks-node binds to on the backend for proof-of-transfer. Only value supported: `"bitcoin"`. - -Example: - -```toml -chain = "bitcoin" -``` - -#### mode - -The profile or test phase of which to run stacks-node. Valid values are `"mocknet"`, `"helium"`, `"neon"`, `"argon"`, `"krypton"`, `"xenon"`. - -Example: - -```toml -mode = "xenon" -``` - -#### peer_host - -Domain name of the host running the backend Bitcoin blockchain. It's required to either run a personal Bitcoin node locally, or to use a publicly hosted Bitcoin node. - -Example: - -```toml -peer_host = "your.bitcoind.node.org" -``` - -#### rpc_port - -peer_host's port stacks-node will connect to for RPC connections. - -Example: - -```toml -rpc_port = 8332 -``` - -#### peer_port - -peer_host's port stacks-node will connect to for P2P connections. - -Example: - -```toml -peer_port = 8333 -``` - -#### burn_fee_cap (optional) - -Maximum amount (in Satoshis) of "burn commitment" to broadcast for the next block's leader election. - -Example: - -```toml -burn_fee_cap = 30000 -``` - -#### satoshis_per_byte (optional) - -Amount (in Satoshis) per [virtual byte](https://en.bitcoin.it/wiki/Weight_units). This is used to compute the transaction fees. - -Example: - -```toml -satoshis_per_byte = 50 -``` - -So total transaction cost would be `(estimated_tx_size * satoshis_per_byte) + burn_fee_cap`. - -#### commit_anchor_block_within (optional) - -Sets the time period (in milliseconds) for commitments. Only used when `mode` is set to `"helium"`. - -Example: - -```toml -commit_anchor_block_within = 10000 -``` - -### Section: ustx_balance (testnet/regtest only) - -This section contains configuration options pertaining to the genesis block allocation for an address in micro-STX. If a user changes these values, their node may be in conflict with other nodes on the network and find themselves unable to sync with other nodes. - -:::info This section can repeat multiple times, and thus is in double-brackets. Each section can define only one address. This section is ignored if running a node on mainnet. -::: - -Example: - -```toml -[[ustx_balance]] -address = "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6" -amount = 10000000000000000 - -[[ustx_balance]] -address = "ST11NJTTKGVT6D1HY4NJRVQWMQM7TVAR091EJ8P2Y" -amount = 10000000000000000 - -[[ustx_balance]] -address = "ST1HB1T8WRNBYB0Y3T7WXZS38NKKPTBR3EG9EPJKR" -amount = 10000000000000000 - -[[ustx_balance]] -address = "STRYYQQ9M8KAF4NS7WNZQYY59X93XEKR31JP64CP" -amount = 10000000000000000 -``` - -#### address - -Address which maintains a micro-STX balance. - -Example: - -```toml -address = "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6" -``` - -#### amount - -The balance of micro-STX given to the address at the start of the node. - -Example: - -```toml -amount = 10000000000000000 -``` diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md b/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md deleted file mode 100644 index 094e3f03a1..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Verify Miner -description: Verify node is operating as miner -sidebar_position: 7 ---- - -You can verify that your node is operating as a miner by checking its log output to verify that it was able to find its Bitcoin UTXOs: - -```bash -$ head -n 100 /path/to/your/node/logs | grep -i utxo -INFO [1630127492.031042] [testnet/stacks-node/src/run_loop/neon.rs:146] [main] Miner node: checking UTXOs at address: -INFO [1630127492.062652] [testnet/stacks-node/src/run_loop/neon.rs:164] [main] UTXOs found - will run as a Miner node -``` \ No newline at end of file diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json b/i18n/pt/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json deleted file mode 100644 index f5de305558..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Noteworthy Contracts", - "position": 4, - "link": { - "type": "generated-index", - "description": "Specific deployed Clarity Contracts worth mentioning." - } -} \ No newline at end of file diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md b/i18n/pt/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md deleted file mode 100644 index 7f2d87b3bd..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md +++ /dev/null @@ -1,362 +0,0 @@ ---- -title: BNS Contract -description: The Blockchain Naming System. ---- - -![](/img/satoshi-btc.png) - -## Introduction - -The Blockchain Naming System (BNS) is implemented as a smart contract using Clarity. - -Below is a list of public and read-only functions as well as error codes that can be returned by those methods: -* [Public functions](#public-functions) -* [Read-only functions](#read-only-functions) -* [Error codes](#error-codes) - -## Public functions - - -### name-import - -#### Input: `(buff 20), (buff 48), principal, (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-import namespace name beneficiary zonefile-hash)` -#### Description: -Imports name to a revealed namespace. Each imported name is given both an owner and some off-chain state. - -### name-preorder - -#### Input: `(buff 20), uint` -#### Output: `(response uint int)` -#### Signature: `(name-preorder hashed-salted-fqn stx-to-burn)` -#### Description: -Preorders a name by telling all BNS nodes the salted hash of the BNS name. It pays the registration fee to the namespace owner's designated address. - -### name-register - -#### Input: `(buff 20), (buff 48), (buff 20), (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-register namespace name salt zonefile-hash)` -#### Description: -Reveals the salt and the name to all BNS nodes, and assigns the name an initial public key hash and zone file hash. - -### name-renewal - -#### Input: `(buff 20), (buff 48), uint, (optional principal), (optional (buff 20))` -#### Output: `(response bool int)` -#### Signature: `(name-renewal namespace name stx-to-burn new-owner zonefile-hash)` -#### Description: -Depending in the namespace rules, a name can expire. For example, names in the .id namespace expire after 2 years. You need to send a name renewal every so often to keep your name. - -You will pay the registration cost of your name to the namespace's designated burn address when you renew it. When a name expires, it enters a \"grace period\". The period is set to 5000 blocks (a month) but can be configured for each namespace. - -It will stop resolving in the grace period, and all of the above operations will cease to be honored by the BNS consensus rules. You may, however, send a NAME_RENEWAL during this grace period to preserve your name. After the grace period, everybody can register that name again. If your name is in a namespace where names do not expire, then you never need to use this transaction. -### name-revoke - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(name-revoke namespace name)` -#### Description: -Makes a name unresolvable. The BNS consensus rules stipulate that once a name is revoked, no one can change its public key hash or its zone file hash. The name's zone file hash is set to null to prevent it from resolving. You should only do this if your private key is compromised, or if you want to render your name unusable for whatever reason. - -### name-transfer - -#### Input: `(buff 20), (buff 48), principal, (optional (buff 20))` -#### Output: `(response bool int)` -#### Signature: `(name-transfer namespace name new-owner zonefile-hash)` -#### Description: -Changes the name's public key hash. You would send a name transfer transaction if you wanted to: -* Change your private key -* Send the name to someone else or -* Update your zone file - -When transferring a name, you have the option to also clear the name's zone file hash (i.e. set it to null). This is useful for when you send the name to someone else, so the recipient's name does not resolve to your zone file. - -### name-update - -#### Input: `(buff 20), (buff 48), (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-update namespace name zonefile-hash)` -#### Description: -Changes the name's zone file hash. You would send a name update transaction if you wanted to change the name's zone file contents. For example, you would do this if you want to deploy your own Gaia hub and want other people to read from it. - -### namespace-preorder - -#### Input: `(buff 20), uint` -#### Output: `(response uint int)` -#### Signature: `(namespace-preorder hashed-salted-namespace stx-to-burn)` -#### Description: -Registers the salted hash of the namespace with BNS nodes, and burns the requisite amount of cryptocurrency. Additionally, this step proves to the BNS nodes that user has honored the BNS consensus rules by including a recent consensus hash in the transaction. Returns pre-order's expiration date (in blocks). - -### namespace-ready - -#### Input: `(buff 20)` -#### Output: `(response bool int)` -#### Signature: `(namespace-ready namespace)` -#### Description: -Launches the namespace and makes it available to the public. Once a namespace is launched, anyone can register a name in it if they pay the appropriate amount of cryptocurrency. - -### namespace-reveal - -#### Input: `(buff 20), (buff 20), uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, principal` -#### Output: `(response bool int)` -#### Signature: `(namespace-reveal namespace namespace-salt p-func-base p-func-coeff p-func-b1 p-func-b2 p-func-b3 p-func-b4 p-func-b5 p-func-b6 p-func-b7 p-func-b8 p-func-b9 p-func-b10 p-func-b11 p-func-b12 p-func-b13 p-func-b14 p-func-b15 p-func-b16 p-func-non-alpha-discount p-func-no-vowel-discount lifetime namespace-import)` -#### Description: -Reveals the salt and the namespace ID (after a namespace preorder). It reveals how long names last in this namespace before they expire or must be renewed, and it sets a price function for the namespace that determines how cheap or expensive names its will be. All of the parameters prefixed by `p` make up the `price function`. These parameters govern the pricing and lifetime of names in the namespace. - -The rules for a namespace are as follows: - -* a name can fall into one of 16 buckets, measured by length. Bucket 16 incorporates all names at least 16 characters long. - -* the pricing structure applies a multiplicative penalty for having numeric characters, or punctuation characters. - -* the price of a name in a bucket is `((coeff) * (base) ^ (bucket exponent)) / ((numeric discount multiplier) * (punctuation discount multiplier))` - -Example: - -* base = 10 -* coeff = 2 -* nonalpha discount: 10 -* no-vowel discount: 10 -* buckets 1, 2: 9 -* buckets 3, 4, 5, 6: 8 -* buckets 7, 8, 9, 10, 11, 12, 13, 14: 7 -* buckets 15, 16+: - - -## Read-only functions - -### can-name-be-registered - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(can-name-be-registered namespace name)` -#### Description: -Returns true if the provided name can be registered. - -### can-namespace-be-registered - -#### Input: `(buff 20)` -#### Output: `(response bool UnknownType)` -#### Signature: `(can-namespace-be-registered namespace)` -#### Description: -Returns true if the provided namespace is available. - -### can-receive-name - -#### Input: `principal` -#### Output: `(response bool int)` -#### Signature: `(can-receive-name owner)` -#### Description: -Returns true if the provided name can be received. That is, if it is not curretly owned, a previous lease is expired, and the name wasn't revoked. - -### get-name-price - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response uint int)` -#### Signature: `(get-name-price namespace name)` -#### Description: -Gets the price for a name. - -### get-namespace-price - -#### Input: `(buff 20)` -#### Output: `(response uint int)` -#### Signature: `(get-namespace-price namespace)` -#### Description: -Gets the price for a namespace. - -### get-namespace-properties - -#### Input: `(buff 20)` -#### Output: `(response (tuple (namespace (buff 20)) (properties (tuple (can-update-price-function bool) (launched-at (optional uint)) (lifetime uint) (namespace-import principal) (price-function (tuple (base uint) (buckets (list 16 uint)) (coeff uint) (no-vowel-discount uint) (nonalpha-discount uint))) (revealed-at uint)))) int)` -#### Signature: `(get-namespace-properties namespace)` -#### Description: -Get namespace properties. - -### is-name-lease-expired - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(is-name-lease-expired namespace name)` -#### Description: -Return true if the provided name lease is expired. - -### name-resolve - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response (tuple (lease-ending-at (optional uint)) (lease-started-at uint) (owner principal) (zonefile-hash (buff 20))) int)` -#### Signature: `(name-resolve namespace name)` -#### Description: -Get name registration details. - -### resolve-principal - -#### Input: `principal` -#### Output: `(response (tuple (name (buff 48)) (namespace (buff 20))) (tuple (code int) (name (optional (tuple (name (buff 48)) (namespace (buff 20)))))))` -#### Signature: `(resolve-principal owner)` -#### Description: -Returns the registered name that a principal owns if there is one. A principal can only own one name at a time. - -## Error codes - -### ERR_INSUFFICIENT_FUNDS -#### type: `int` -#### value: `4001` - -### ERR_NAMESPACE_ALREADY_EXISTS -#### type: `int` -#### value: `1006` - -### ERR_NAMESPACE_ALREADY_LAUNCHED -#### type: `int` -#### value: `1014` - -### ERR_NAMESPACE_BLANK -#### type: `int` -#### value: `1013` - -### ERR_NAMESPACE_CHARSET_INVALID -#### type: `int` -#### value: `1016` - -### ERR_NAMESPACE_HASH_MALFORMED -#### type: `int` -#### value: `1015` - -### ERR_NAMESPACE_NOT_FOUND -#### type: `int` -#### value: `1005` - -### ERR_NAMESPACE_NOT_LAUNCHED -#### type: `int` -#### value: `1007` - -### ERR_NAMESPACE_OPERATION_UNAUTHORIZED -#### type: `int` -#### value: `1011` - -### ERR_NAMESPACE_PREORDER_ALREADY_EXISTS -#### type: `int` -#### value: `1003` - -### ERR_NAMESPACE_PREORDER_CLAIMABILITY_EXPIRED -#### type: `int` -#### value: `1009` - -### ERR_NAMESPACE_PREORDER_EXPIRED -#### type: `int` -#### value: `1002` - -### ERR_NAMESPACE_PREORDER_LAUNCHABILITY_EXPIRED -#### type: `int` -#### value: `1010` - -### ERR_NAMESPACE_PREORDER_NOT_FOUND -#### type: `int` -#### value: `1001` - -### ERR_NAMESPACE_PRICE_FUNCTION_INVALID -#### type: `int` -#### value: `1008` - -### ERR_NAMESPACE_STX_BURNT_INSUFFICIENT -#### type: `int` -#### value: `1012` - -### ERR_NAMESPACE_UNAVAILABLE -#### type: `int` -#### value: `1004` - -### ERR_NAME_ALREADY_CLAIMED -#### type: `int` -#### value: `2011` - -### ERR_NAME_BLANK -#### type: `int` -#### value: `2010` - -### ERR_NAME_CHARSET_INVALID -#### type: `int` -#### value: `2022` - -### ERR_NAME_CLAIMABILITY_EXPIRED -#### type: `int` -#### value: `2012` - -### ERR_NAME_COULD_NOT_BE_MINTED -#### type: `int` -#### value: `2020` - -### ERR_NAME_COULD_NOT_BE_TRANSFERED -#### type: `int` -#### value: `2021` - -### ERR_NAME_EXPIRED -#### type: `int` -#### value: `2008` - -### ERR_NAME_GRACE_PERIOD -#### type: `int` -#### value: `2009` - -### ERR_NAME_HASH_MALFORMED -#### type: `int` -#### value: `2017` - -### ERR_NAME_NOT_FOUND -#### type: `int` -#### value: `2013` - -### ERR_NAME_NOT_RESOLVABLE -#### type: `int` -#### value: `2019` - -### ERR_NAME_OPERATION_UNAUTHORIZED -#### type: `int` -#### value: `2006` - -### ERR_NAME_PREORDERED_BEFORE_NAMESPACE_LAUNCH -#### type: `int` -#### value: `2018` - -### ERR_NAME_PREORDER_ALREADY_EXISTS -#### type: `int` -#### value: `2016` - -### ERR_NAME_PREORDER_EXPIRED -#### type: `int` -#### value: `2002` - -### ERR_NAME_PREORDER_FUNDS_INSUFFICIENT -#### type: `int` -#### value: `2003` - -### ERR_NAME_PREORDER_NOT_FOUND -#### type: `int` -#### value: `2001` - -### ERR_NAME_REVOKED -#### type: `int` -#### value: `2014` - -### ERR_NAME_STX_BURNT_INSUFFICIENT -#### type: `int` -#### value: `2007` - -### ERR_NAME_TRANSFER_FAILED -#### type: `int` -#### value: `2015` - -### ERR_NAME_UNAVAILABLE -#### type: `int` -#### value: `2004` - -### ERR_PANIC -#### type: `int` -#### value: `0` - -### ERR_PRINCIPAL_ALREADY_ASSOCIATED -#### type: `int` -#### value: `3001` diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md b/i18n/pt/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md deleted file mode 100644 index ce1b1ba859..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -title: Stacking Contract -description: See a detailed list of all functions and error codes of the Stacking contract. ---- - -## Introduction - -Stacking is implemented as a smart contract using Clarity. You can always find the Stacking contract identifier using the Stacks Blockchain API [`v2/pox` endpoint](https://docs.hiro.so/api#operation/get_pox_info). - -Below is a list of public and read-only functions as well as error codes that can be returned by those methods: - -* [Public functions](#public-functions) -* [Read-only functions](#read-only-functions) -* [Error codes](#error-codes) - -## Public functions - -### allow-contract-caller -#### input: `principal, (optional uint)` -#### output: `(response bool int)` -#### signature: `(allow-contract-caller caller until-burn-ht)` -#### description: -Give a contract-caller authorization to call stacking methods. Normally, stacking methods may only be invoked by _direct_ transactions (i.e., the `tx-sender` issues a direct `contract-call` to the stacking methods). - -By issuing an allowance, the tx-sender may call through the allowed contract. - -### delegate-stack-stx -#### input: `principal, uint, (tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint` -#### output: `(response (tuple (lock-amount uint) (stacker principal) (unlock-burn-height uint)) int)` -#### signature: `(delegate-stack-stx stacker amount-ustx pox-addr start-burn-ht lock-period)` -#### description: -As a delegate, stack the given principal's STX using `partial-stacked-by-cycle`. - -Once the delegate has stacked > minimum, the delegate should call `stack-aggregation-commit`. - -### delegate-stx -#### input: `uint, principal, (optional uint), (optional (tuple (hashbytes (buff 20)) (version (buff 1))))` -#### output: `(response bool int)` -#### signature: `(delegate-stx amount-ustx delegate-to until-burn-ht pox-addr)` -#### description: -Delegate to `delegate-to` the ability to stack from a given address. - -This method _does not_ lock the funds, rather, it allows the delegate to issue the stacking lock. - -The caller specifies: - -* amount-ustx: the total amount of ustx the delegate may be allowed to lock -* until-burn-ht: an optional burn height at which this delegation expiration -* pox-addr: an optional p2pkh or p2sh address to which any rewards *must* be sent - -### disallow-contract-caller -#### input: `principal` -#### output: `(response bool int)` -#### signature: `(disallow-contract-caller caller)` -#### description: -Revokes authorization from a contract to invoke stacking methods through contract-calls - -### reject-pox -#### input: -#### output: `(response bool int)` -#### signature: `(reject-pox)` -#### description: -Reject Stacking for this reward cycle. - -`tx-sender` votes all its uSTX for rejection. - -Note that unlike Stacking, rejecting PoX does not lock the tx-sender's tokens: PoX rejection acts like a coin vote. - -### revoke-delegate-stx -#### input: -#### output: `(response bool int)` -#### signature: `(revoke-delegate-stx)` -#### description: -Revoke a Stacking delegate relationship. A particular Stacker may only have one delegate, so this method does not take any parameters, and just revokes the Stacker's current delegate (if one exists). - -### stack-aggregation-commit -#### input: `(tuple (hashbytes (buff 20)) (version (buff 1))), uint` -#### output: `(response bool int)` -#### signature: `(stack-aggregation-commit pox-addr reward-cycle)` -#### description: -Commit partially stacked STX. - -This allows a stacker/delegate to lock fewer STX than the minimal threshold in multiple transactions, - -so long as: - -1. The pox-addr is the same. -2. This \"commit\" transaction is called _before_ the PoX anchor block. - -This ensures that each entry in the reward set returned to the stacks-node is greater than the threshold, - - but does not require it be all locked up within a single transaction - -### stack-stx -#### input: `uint, (tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint` -#### output: `(response (tuple (lock-amount uint) (stacker principal) (unlock-burn-height uint)) int)` -#### signature: `(stack-stx amount-ustx pox-addr start-burn-ht lock-period)` -#### description: -Lock up some uSTX for stacking! Note that the given amount here is in micro-STX (uSTX). - -The STX will be locked for the given number of reward cycles (lock-period). - -This is the self-service interface. tx-sender will be the Stacker. - -* The given stacker cannot currently be stacking. -* You will need the minimum uSTX threshold. This isn't determined until the reward cycle begins, but this method still requires stacking over the _absolute minimum_ amount, which can be obtained by calling `get-stacking-minimum`. -* The pox-addr argument must represent a valid reward address. Right now, this must be a Bitcoin p2pkh or p2sh address. It cannot be a native Segwit address, but it may be a p2wpkh-p2sh or p2wsh-p2sh address. - -The tokens will unlock and be returned to the Stacker (tx-sender) automatically. - -## Read-only functions - -### can-stack-stx -#### input: `(tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint, uint` -#### output: `(response bool int)` -#### signature: `(can-stack-stx pox-addr amount-ustx first-reward-cycle num-cycles)` -#### description: -Evaluate if a participant can stack an amount of STX for a given period. - -### get-pox-info -#### input: -#### output: `(response (tuple (current-rejection-votes uint) (first-burnchain-block-height uint) (min-amount-ustx uint) (prepare-cycle-length uint) (rejection-fraction uint) (reward-cycle-id uint) (reward-cycle-length uint) (total-liquid-supply-ustx uint)) UnknownType)` -#### signature: `(get-pox-info)` -#### description: -Returns information about PoX status. - -### get-pox-rejection -#### input: `principal, uint` -#### output: `(optional (tuple (amount uint)))` -#### signature: `(get-pox-rejection stacker reward-cycle)` -#### description: -Returns the amount of uSTX that a given principal used to reject a PoX cycle. - -### get-stacker-info -#### input: `principal` -#### output: `(optional (tuple (amount-ustx uint) (first-reward-cycle uint) (lock-period uint) (pox-addr (tuple (hashbytes (buff 20)) (version (buff 1))))))` -#### signature: `(get-stacker-info stacker)` -#### description: -Returns the _current_ stacking information for `stacker. If the information is expired, or if there's never been such a stacker, then returns none. - -### get-stacking-minimum -#### input: -#### output: `uint` -#### signature: `(get-stacking-minimum)` -#### description: -Returns the absolute minimum amount that could be validly Stacked (the threshold to Stack in a given reward cycle may be higher than this - -### get-total-ustx-stacked -#### input: `uint` -#### output: `uint` -#### signature: `(get-total-ustx-stacked reward-cycle)` -#### description: -Returns the amount of currently participating uSTX in the given cycle. - -### is-pox-active -#### input: `uint` -#### output: `bool` -#### signature: `(is-pox-active reward-cycle)` -#### description: -Returns whether or not PoX has been rejected at a given PoX cycle. -## Error codes - -### ERR_DELEGATION_EXPIRES_DURING_LOCK -#### type: `int` -#### value: `21` - -### ERR_DELEGATION_POX_ADDR_REQUIRED -#### type: `int` -#### value: `23` - -### ERR_DELEGATION_TOO_MUCH_LOCKED -#### type: `int` -#### value: `22` - -### ERR_INVALID_START_BURN_HEIGHT -#### type: `int` -#### value: `24` - -### ERR_NOT_ALLOWED -#### type: `int` -#### value: `19` - -### ERR_STACKING_ALREADY_DELEGATED -#### type: `int` -#### value: `20` - -### ERR_STACKING_ALREADY_REJECTED -#### type: `int` -#### value: `17` - -### ERR_STACKING_ALREADY_STACKED -#### type: `int` -#### value: `3` - -### ERR_STACKING_EXPIRED -#### type: `int` -#### value: `5` - -### ERR_STACKING_INSUFFICIENT_FUNDS -#### type: `int` -#### value: `1` - -### ERR_STACKING_INVALID_AMOUNT -#### type: `int` -#### value: `18` - -### ERR_STACKING_INVALID_LOCK_PERIOD -#### type: `int` -#### value: `2` - -### ERR_STACKING_INVALID_POX_ADDRESS -#### type: `int` -#### value: `13` - -### ERR_STACKING_NO_SUCH_PRINCIPAL -#### type: `int` -#### value: `4` - -### ERR_STACKING_PERMISSION_DENIED -#### type: `int` -#### value: `9` - -### ERR_STACKING_POX_ADDRESS_IN_USE -#### type: `int` -#### value: `12` - -### ERR_STACKING_STX_LOCKED -#### type: `int` -#### value: `6` - -### ERR_STACKING_THRESHOLD_NOT_MET -#### type: `int` -#### value: `11` - -### ERR_STACKING_UNREACHABLE -#### type: `int` -#### value: `255` \ No newline at end of file diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md b/i18n/pt/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md deleted file mode 100644 index 5f38edfb57..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: xBTC -description: Wrapped BTC on Stacks ---- - -![](/img/xbtc-icon.webp) - -## Introduction - -[Wrapped.com](https://www.wrapped.com) has brought Bitcoin (xBTC) to the Stacks ecosystem. - -xBTC is backed 1:1 by Bitcoin and empowers developers to expand the Bitcoin DeFi ecosystem. - -The reserves are publicly visible [here](https://open.wrapped.com/reserves/). - -## Contract - -[SP3DX3H4FEYZJZ586MFBS25ZW3HZDMEW92260R2PR.Wrapped-Bitcoin](https://explorer.stacks.co/txid/SP3DX3H4FEYZJZ586MFBS25ZW3HZDMEW92260R2PR.Wrapped-Bitcoin?chain=mainnet) - -## Examples of uses - -[Friedger Mining Pool](https://pool.friedger.de/) currrently supports Stacking rewards payments in xBTC (optional). - - -## More information - -* [Blog post announcement](https://www.stacks.co/blog/tokensoft-wrapped-fundamental-bitcoin-defi-building-blocks-xbtc) by Muneeb Ali - -* Video: [Why xBTC is Important For Bitcoin to Grow](https://www.youtube.com/watch?v=xIoadrfSdi4) \ No newline at end of file diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/references/_category_.json b/i18n/pt/docusaurus-plugin-content-docs/current/references/_category_.json deleted file mode 100644 index 3805ab0783..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/references/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "References", - "position": 9, - "link": { - "type": "generated-index", - "description": "Stacks references." - } -} \ No newline at end of file diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/references/glossary.md b/i18n/pt/docusaurus-plugin-content-docs/current/references/glossary.md deleted file mode 100644 index f97908371a..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/references/glossary.md +++ /dev/null @@ -1,215 +0,0 @@ ---- -title: Glossary -description: A comprehensive list of terms used within the ecosystem. ---- - -A comprehensive list of terms used within the ecosystem. - -#### App Review -An incentive mechanism for application developers in the early stage (first four years) of the ecosystem and helps with bootstrapping the two-sided market. - -#### Atlas -A peer network provide a global index for discovery. - -#### Bitcoin (BTC) address -A string of letters and numbers. `3E53XjqK4Cxt71BGeP2VhpcotM8LZ853C8` Sharing this address allows anyone to send Bitcoin to the address. - -#### block -A discrete group of records written to a blockchain that can effectively be identified and referenced by the use of headers that contain a digital fingerprint of the records each block contains. - -#### blockchain -A database created and shared by the members of a peer-to-peer computer network which each member of that network can independently trust due to the rules governing the database’s creation. A blockchain can therefore be used to replace centralized databases. - -#### Blockchain Name System (BNS) -Replacement for DNS. More info [here](../noteworthy-contracts/bns-contract). - -#### Blockstack Browser -A deprecated application for accessing identity and storage. - -#### Blockstack Owner Address - -Looks like a bitcoin address but starts with `ID` for example: `ID-1J3PUxY5uDShUnHRrMyU6yKtoHEUPhKULs` - -#### Burning -Burning a token means that the token is transferred to an address that is a black hole—one that is not owned by any entity and for which guessing the applicable private key is effectively impossible based on known mathematical principles. This effectively destroys the token by making it unavailable for future use and decreases the total number of tokens available from that point forward. - -#### consensus hash -A consensus hash is a cryptographic hash that each node calculates at each block. It is derived from the accepted state transitions in the last-processed block and a geometric series of prior-calculated consensus hashes. - -#### Consensus rules -"The rules governing the creation of new valid records in a blockchain database and the mining algorithms used for this purpose. - -#### control plane -The part of a network that carries signaling traffic and is responsible for routing. Control packets originate from or are destined for a router. Functions of the control plane include system configuration and management. - -#### core node -A server that runs Stacks Blockchain services. - -#### crypto-asset -A digital asset which utilises cryptography, peer-to-peer networking and a public ledger to regulate the creation of new units, verify transactions and secure the transactions without the intervention of any middleman. - -#### cryptography -The practise and study of encryption and decryption - encoding data so that it can only be decoded by specific individuals. A system for encrypting and decrypting data is a cryptosystem. - -#### DAO -See Decentralized Autonomous Organization. - -#### decentralized application (DApp) -A DApp is a service that enables direct interaction between end users and providers (e.g. connecting buyers and sellers in some marketplace, owners and stores in file storage). A term coined by Ethereum. See their glossary: http://ethdocs.org/en/latest/glossary.html#dapp" - -#### Decentralized Autonomous Organization -A type of contract or suite of contracts on the blockchain that is intented to codify, enforce or automate the processes of an organization. - -#### digital asset -Also referred to as a crypto-asset. Any set of unique digital information—including, for example, programs, decentralized programs, isolated chunks of programming code, collections of data, e-mail or web addresses or cryptocurrency tokens—that is capable of being stored and uniquely tracked on a computer network such as the Stacks network and over which a user can maintain control through that network. - -#### digital fingerprint -A digital fingerprint is a unique number of a fixed length that can be produced by running any set of digital information through something called a cryptographic hash function. Each set of digital information (including a digital asset, and the digital record of any network operation on that digital asset) should (as a practical matter) have a unique digital fingerprint, which allows that set of digital information to be identified. However, it is almost impossible to recreate a digital asset from its digital fingerprint. The Blockstack network uses industry-standard algorithms such as SHA-256 to create digital fingerprints. - -#### digital signature -A digital signature is a sequence of digital information combining a user’s private key and any digital information that the user wishes to sign. Any other party can use the user’s paired public key to verify that the digital signature is authentic, i.e. that the public key was generated from a particular piece of digital information and the user’s private key. - -#### distributed hash tables (DHT) -A form of network used to store some content in the form of key/value pairs. ... This experimental project try to avoid keeping all the blockchain, but instead prefers to store it in a DHT. - -#### ephemeral key -A cryptographic key is called ephemeral if it is generated for each execution of a key establishment process. - -#### fork -The term fork is used to refer both to any situation where there are two or more competing versions of a blockchain on a network (a situation that may arise and resolve itself in the ordinary course of network operations due to lags in communication between core nodes) and any software update that is proposed for adoption by the core nodes of a blockchain network that may result in a persistent fork on the network, with core nodes that adopt the update recognizing one version of the blockchain and those which do not recognizing another. - -#### Gaia -Decentralized storage architecture for off-chain data. More info [here](../gaia). - -#### genesis block -The genesis block is the first block of the Stacks blockchain, which will create the initial 1.32 billion Stacks Tokens. - -#### id.blockstack -An identifier in the Blockstack, for example meepers.id.blockstack. This is your name & identity that is registered in the .id namespace on Blockstack. Your personal data and storage are built around this ID. Apps that want to access your data use your permission and identity to find it. An id is usually a shorthand for a longer, hash ID string, for example ID-1Fj9kkw15P51Fj9kkw15P5xJmyefWhLKrQMKNPREfaqsJ" - -#### identity - -A way to identify a person or an organization on the Stacks network. An identity is unique, both `meepers.id.blockstack` or `chad.id` are examples of IDs. - -#### identity management (IDM) -Identity management, also known as identity and access management is, in computer security, the security and business discipline that enables the right individuals to access the right resources at the right times and for the right reason". - -#### know your customer (KYC) -Or KYC, is a popular term used in the banking or financial field. KYC is a process where financial institutions, insurers and other companies obtain information about the identity and address of the customers as part of risk management. - -#### light clients -Clients that can independently validate the existence of transactions by downloading only block headers and not the entire blockchain. - -#### magic recovery code - -A long encrypted string, for example: `36mWivFdy0YPH2z31EflpQz/Y0UMrOrJ++lH=0EI7c3mop2JuRBm5WXxSTazJsUjOA...` Do not share the QR code that accompanied your recovery code either. This is a QR code: - -![](/img/qr-code.png) - -#### mesh network -A local network topology in which the infrastructure nodes (i.e. bridges, switches, and other infrastructure devices) connect directly, dynamically and non-hierarchically to as many other nodes as possible and cooperate with one another to efficiently route data from/to clients. - -#### mining -Mining generally refers to the process of performing certain functions for a network such as adding new records to a blockchain in exchange for mining rewards; it may also refer to other mechanisms whereby rewards (usually in the form of cryptocurrency) are provided for performing other tasks helpful to the network. - -#### mining power -A miner’s (or group of miners’) mining power is equal to the probability it will be selected to write a new block to the blockchain. Depending on the mechanism for mining, this is usually related to the overall share of computing power or cryptoassets the miner or miners possess relative to all miners for that blockchain. - -#### mining rewards -Mining rewards are newly issued tokens received by miners in exchange for adding new records to the blockchain or other activities beneficial to the network. - -#### name -An identifier or name. Names are a type of digital asset in the Stacks network. If you have signed into the Stacks Wallet, you might have created a name. If an application developer registered an application within Stacks, then they registered a name. Public Stacking pools can also have a name. - -#### network operation -A network operation is any change to the information about a digital asset (or smart contract) stored on a blockchain, including, for example, a change in the digital asset’s owner, or a change in the location at which it is stored on the network. How and when these network operations are performed for each digital asset is governed, on the Blockstack network, either by the Stacks Node software or a smart contract. - -#### NFT -Non fungible token. - -#### private key - -Private keys matches a corresponding public key. A public key also looks like a string of letters and numbers: - -![](/img/private.png) - -The exact format of the public and private key depend on the software you use to create them. - -#### proof-of-burn mining -The consensus algorithm used in the Stacks blockchain where miners destroy a proof-of-work-based cryptocurrency (currently Bitcoin) to get tokens; this enables the functionality where nodes can select between conflicting blockchain forks, as the blockchain fork with the most amount of cryptocurrency burned is considered to be the correct fork. - -#### proof-of-work -A proof-of-work system or proof-of-work mining is a mining mechanism where miners must expend computing power to solve complicated cryptographic puzzles, and prove that they have done so by writing the solution to the blockchain, in order to be allowed to add blocks to a blockchain. This is the mining system used, for example, by Bitcoin. - -#### public key -Public and private key pair comprise of two uniquely related cryptographic keys. It looks like a long random string of letters and numbers: `3048 0241 00C9 18FA CF8D EB2D EFD5 FD37 89B9 E069 EA97 FC20 …` The exact format of the public and private key depend on the software you use to create them. - -#### Public Key Infrastructure (PKI) -A system which returns a cryptographic public key associated with a name. - -#### replicated state machines (RSMs) -This is a model for reasoning about distributed computer programs -- any program (plus it's input) can be represented as a state machine, and when trying to get a distributed set of servers to agree on the output of an algorithm, you can model that process as N different state machines" - -#### Secret recovery Key, -Used to access an identity on the Stacks blockchain. A 24-word sequence of words for example: `applied binge crisp pictorial fiery` `dancing agreeable frogs light finish ping apple` - -#### seed phrase - -Used to access Stacks Wallet software. The seed phrase consists of 24 words in a sequence. Both the word *and its position the sequence* are important. Write down your seed phrase and store it in a secure location such as a safe deposit box. When you write the seed phrase down, include its position, for example,`1-frog, 2-horse, 3-building` and so on until you reach a final position `24-ocean`. -#### smart contract -A smart contract is a computer program written to a blockchain such as the Stacks blockchain by developers. This computer program defines the various network operations that can be performed on the digital assets on the blockchain, the computations that can be performed using the smart contract, along with defining various important properties of the respective digital assets like ownership rights and the cost in fuel required to register the digital assets. - -#### soft fork -A soft fork is a proposed update to the software governing the network that results in a post-update network that is compatible with the network as it existed prior to the update, because it restricts the network operations that can be performed after the update. - -#### Stacks (STX) address - - A STX address is a string of letters and numbers starting with an `SP` or `SM`, for example: `SM3KJBA4RZ7Z20KD2HBXNSXVPCR1D3CRAV6Q05MKT` If you created a software-only wallet with the Stacks Wallet software, the wallet has a single STX address which is also sometimes called the *wallet address*. You access a software wallet with a *seed phrase*. " - -#### Stacks blockchain -The Stacks blockchain is the custom blockchain being developed for use by the Stacks network that will use the Stacks token as its native currency and which will include the genesis block and subsequent blocks created by the mining activities described in the Stacks Network—Development of the Stacks network. - -#### Stacks Explorer -An application that allow you to view and search transactions in the blockchain. For example, https://explorer.stacks.co. - -#### Stacks node -A complete version of our open-source software available on Github at https://github.com/stacks-network/stacks-blockchain/ that governs the creation of the blockchain, the smart contracts that may be written to our blockchain, and other systems that make up the Stacks network, when run on the systems and devices of our users and developers. - -#### Stacks wallet -An application for accessing assets, identity and storage. Examples are the [Hiro Wallet](https://www.hiro.so/wallet), [xverse](https://www.xverse.app/) and [dcent](https://dcentwallet.com/). More information and example [here](../services-using-stacks/wallets). - -#### storage hub -A Gaia instance run by a hub provider or software. A Gaia hub stores data in a separate, addressed location. - -#### storage provider -A third-party company cloud or software provider that hosts one or more Gaia storage hubs. - -#### transaction -A transaction is a unit of work within a block. - -#### transaction fee -Fees paid by participants in a transaction to miners. - -#### two-sided market problem -Economic platforms having two distinct user groups that provide each other with network benefits. The Stacks platform is a classic two-sided market. - -#### username -A shorthand name for your id.blockstack. - -#### virtual blockchain -A layer that sits on top of a blockchain that introduces new functionality and operations without requiring changes to the underlying blockchain. - -#### wallet address -A wallet address is the form in which a public key can be presented and recorded on a blockchain. Wallet addresses are therefore used to assign the ownership of digital assets on the Blockstack network. - -#### watch-only wallet -A wallet without send and receive ability. You can view only balances and transaction history. - -#### web of trust mining -Web-of-trust mining provides incentive mechanisms for users where an initial trusted-set of unique users is curated in the genesis block and, in the future, the initial set of users can expand the web-of-trust after the network goes live. - -#### web3 -The exact definition is still under discussion, but it general refers to the 3rd generation of the web that is based on blockchain technology and incorporates decentralized and token-based economics. - -#### zone file -A Domain Name System (DNS) zone file is a text file that describes a DNS zone. A DNS zone is a subset, often a single domain, of the hierarchical domain name structure of the DNS. diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/references/nft.md b/i18n/pt/docusaurus-plugin-content-docs/current/references/nft.md deleted file mode 100644 index 033ee0a71a..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/references/nft.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: NFTs on Stacks -description: A list of sites that operate NFTs on Stacks ---- - -List of sites that operate NFTS on Stacks on alphabetical order. - -### [Byzantion](https://byzantion.xyz/) - -![website-screenshot](/img/sh_nft_byzantion.png) - -### [Gamma](https://gamma.io/) -![website-screenshot](/img/sh_nft_gamma.png) - -### [Megapont](https://www.megapont.com/) - -![website-screenshot](/img/sh_nft_megapont.png) - -### [StacksArt](https://www.stacksart.com/) - -![website-screenshot](/img/sh_nft_stacksart.png) - diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md b/i18n/pt/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md deleted file mode 100644 index dc6e507d5e..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Stacks info sites -description: A list of sites on alphabetical order that display status and stats of the Stacks network. ---- - -### [Haystack](https://haystack.tools/mempool) - -![website-screenshot](/img/sh_haystacks.png) - -### [Stacksdata](https://stacksdata.info/) - -![website-screenshot](/img/sh_stacksdata.png) - -### [Stacksonchain](https://stacksonchain.com) - -![website-screenshot](/img/sh_stacksonchain.png) - -### [Status Hiro](https://status.hiro.so/) - -![website-screenshot](/img/sh_statushiro.png) - -### [Stxstats](https://www.stxstats.co/) - -![website-screenshot](/img/sh_stxstats.png) - -### [Novuminsights](https://stacks.novuminsights.com/health) - -![website-screenshot](/img/sh_novuminsights.png) - -### [Onstacks](https://app.onstacks.com/) - -![website-screenshot](/img/sh_onstacks.png) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json b/i18n/pt/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json deleted file mode 100644 index ebd63f366c..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Services using Stacks", - "position": 8, - "link": { - "type": "generated-index", - "description": "An 'always incomplete' list of services that use Stacks." - } -} \ No newline at end of file diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md b/i18n/pt/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md deleted file mode 100644 index 51defacba7..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: DeFi -description: De-Fi sites on Stacks -sidebar_position: 2 ---- - -They are multiple De-Fi sites that operate on the Stacks blockchain. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Alex - -[Alex](https://app.alexlab.co) ![](/img/sh_alex.png) - -## Arkadiko - -[Arkadiko](https://arkadiko.finance/) ![](/img/sh_arkadiko.png) - -## Catamaran Swaps - -[Catamaran Swaps](https://www.catamaranswaps.org/) allows trustless exchange of digital assets. - -![](/img/sh_catamaran.png) - -## Lnswap - -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange - -![](/img/sh_lnswap.png) - -## Neoswap - -[Neoswap](https://neoswap.party) - -![](/img/sh_neoswap.png) - -## Stackswap - -[Stackswap](https://app.stackswap.org/v2) - -![](/img/sh_stackswap.png) - diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/services-using-stacks/more.md b/i18n/pt/docusaurus-plugin-content-docs/current/services-using-stacks/more.md deleted file mode 100644 index df0b3e2254..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/services-using-stacks/more.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: More -description: More services built on Stacks. -sidebar_position: 5 ---- - -List of sites on alphabetical order added by the community. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Citycoins - -[Citycoins](https://citycoins.co) - -![](/img/sh_citycoins.png) - -## Sigle - -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. - -![](/img/sh_sigle.png) \ No newline at end of file diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md b/i18n/pt/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md deleted file mode 100644 index bfa0505dc9..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: NFTs -description: NFTs on Stacks -sidebar_position: 3 ---- - -List of sites that operate NFTS on Stacks on alphabetical order. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -### [Byzantion](https://byzantion.xyz/) - -![website-screenshot](/img/sh_nft_byzantion.png) - -### [Gamma](https://gamma.io/) -![website-screenshot](/img/sh_nft_gamma.png) - -### [Megapont](https://www.megapont.com/) - -![website-screenshot](/img/sh_nft_megapont.png) - -### [StacksArt](https://www.stacksart.com/) - -![website-screenshot](/img/sh_nft_stacksart.png) - -### [Superfandom](https://superfandom.io/) - -![website-screenshot](/img/sh_superfandom.png) \ No newline at end of file diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/services-using-stacks/other.md b/i18n/pt/docusaurus-plugin-content-docs/current/services-using-stacks/other.md deleted file mode 100644 index 199fc41da5..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/services-using-stacks/other.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Other Stacks sites -description: A list of sites on alphabetical order built on Stacks. -sidebar_position: 4 ---- - -List of sites on alphabetical order added by the community. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Alex -[Alex](https://app.alexlab.co) - -## Sigle - -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. \ No newline at end of file diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md b/i18n/pt/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md deleted file mode 100644 index 35ced8dac6..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Stacks info sites -description: Status and stats of the Stacks network. -sidebar_position: 1 ---- - -A list of sites on alphabetical order that display status and stats of the Stacks network. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -### [Haystack](https://haystack.tools/mempool) - -![website-screenshot](/img/sh_haystacks.png) - -### [Stacksdata](https://stacksdata.info/) - -![website-screenshot](/img/sh_stacksdata.png) - -### [Stacksonchain](https://stacksonchain.com) - -![website-screenshot](/img/sh_stacksonchain.png) - -### [Status Hiro](https://status.hiro.so/) - -![website-screenshot](/img/sh_statushiro.png) - -### [Stxstats](https://www.stxstats.co/) - -![website-screenshot](/img/sh_stxstats.png) - -### [Novuminsights](https://stacks.novuminsights.com/health) - -![website-screenshot](/img/sh_novuminsights.png) - -### [Onstacks](https://app.onstacks.com/) - -![website-screenshot](/img/sh_onstacks.png) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md b/i18n/pt/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md deleted file mode 100644 index d4b4cbf18c..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Swaps -description: A list of sites that allow Swaps -sidebar_position: 2 ---- - -They are multiple sites that allow you to make swaps using the Stacks blockchain. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Catamaran Swaps - -[Catamaran Swaps](https://www.catamaranswaps.org/) allows trustless exchange of digital assets. - -![](/img/sh_catamaran.png) - -## Lnswap - -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange - -![](/img/sh_lnswap.png) - -## Neoswap - -[Neoswap](https://neoswap.party) - -![](/img/sh_neoswap.png) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md b/i18n/pt/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md deleted file mode 100644 index e5ea6c5b45..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Wallets -description: Wallets for Stacks -sidebar_position: 4 ---- - -A list of hardware and software wallets for Stacks - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Blockchain.com - -[Blockchain.com](https://www.blockchain.com/wallet) - -![](/img/sh_blockchain.png) -## Boom - -[Boom](https://boom.money) - -![](/img/sh_boom.png) - -## Dcent wallet - -[D'CENT](https://dcentwallet.com) - -![](/img/sh_dcent.png) -## Hiro Wallet - -[Hiro Wallet](https://www.hiro.so/wallet) - -![](/img/sh_hirowallet.png) - -## Neptune - -[Neptune](https://neptunewallet.io) - -![](/img/sh_neptunewallet.png) - -## Xverse - -[Xverse](https://www.xverse.app/) - -![](/img/sh_xverse.png) - -## Wise - -[Wise](https://wiseapp.id) - -![](/img/sh_wiseapp.png) \ No newline at end of file diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md b/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md deleted file mode 100644 index b48e119ab3..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md +++ /dev/null @@ -1,211 +0,0 @@ ---- -title: Accounts -description: Guide to Stacks 2.0 accounts -sidebar_position: 5 ---- - -## Introduction - -Stacks 2.0 accounts are entities that own assets, like Stacks (STX) tokens. An account has an address, private key, nonce, and one or more asset balances. - -:::tip The encryption algorithm used in Stacks 2.0 is **[secp256k1](https://en.bitcoinwiki.org/wiki/Secp256k1)**. - -Additionally, [Ed25519](https://ed25519.cr.yp.to/) is also used just for the VRF (Verifiable Random Function). ::: - -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. - -:::tip The transaction type doesn't need to be a token transfer - contract deploy and contract call transactions can change the balances of an account -::: - -## Creation - -An account is generated from a 24-word mnemonic phrase. This is often referred to as the **seed phrase**. The seed phrase provides access to Stacks 2.0 accounts. - -:::danger If the seed phrase is lost, access to the associated account cannot be restored. No person or organization, including Blockstack, can recover a lost seed phrase. -::: - -The easiest way to generate a new Stacks 2.0 account is to use the [Stacks CLI](https://github.com/hirosystems/stacks.js/tree/master/packages/cli): - -```bash -# install CLI globally -npm install --global @stacks/cli - -# generate a new account and store details in a new file -# '-t' option makes this a testnet account -stx make_keychain -t > cli_keychain.json -``` - -`make_keychain` creates the following file: - -```js -{ - "mnemonic": "aaa bbb ccc ddd ...", - "keyInfo": { - "privateKey": "5a3f1f15245bb3fb...", - "address": "STJRM2AMVF90ER6G3RW1QTF85E3HZH37006D5ER1", - "btcAddress": "biwSd6KTEvJcyX2R8oyfgj5REuLzczMYC1", - "wif": "L4HXn7PLmzoNW...", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -| Field | Description | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `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.privateKey` | Private key for the account. Required for token transfers and often referred to as `senderKey` | -| `keyInfo.address` | Stacks address for the account | -| `keyInfo.btcAddress` | Corresponding BTC address for the account. | -| `keyInfo.wif` | Private key of the btcAddress in compressed format. | -| `keyInfo.index` | Nonce for the account, starting at 0 | - -Note that a new account automatically exists for each new private key. There is no need to manually instantiate an account on the Stacks 2.0 blockchain. - -:::tip Addresses are created by generating the [RIPEMD-160 hash](https://en.wikipedia.org/wiki/RIPEMD#RIPEMD-160_hashes) of the [SHA256](https://en.bitcoinwiki.org/wiki/SHA-256) of the public key. BTC addresses are encoded with [Base58Check](https://en.bitcoin.it/wiki/Base58Check_encoding). For Stacks addresses, [c32check](https://github.com/stacks-network/c32check) is used. Deriving an address from a public key can be done without internet access, for instance using the c32check `c32addressDecode` method. ::: - -Alternatively to the CLI creation, the [Stacks Transactions JS](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library can be used: - -```js -import { - makeRandomPrivKey, - privateKeyToString, - getAddressFromPrivateKey, - TransactionVersion, -} from '@stacks/transactions'; - -const privateKey = makeRandomPrivKey(); - -// Get public key from private -const publicKey = getPublicKey(privateKey); - -const stacksAddress = getAddressFromPrivateKey( - privateKeyToString(privateKey), - TransactionVersion. Testnet // remove for Mainnet addresses -); -``` - -A second alternative would be to use [stacks-gen](https://github.com/psq/stacks-gen). This tool will generate all the keys you need in one place, including the values needed for calling the stacking contract, and also a WIF key for use with `bitcoind`. - -#### stacks-gen prerequisite - -Install [npx](https://github.com/npm/npx) if not already installed. (npx will check whether `` exists in \$PATH, or in the local project binaries, and execute that. If `` is not found, it will be installed prior to execution). - -``` -npm install -g npx -``` - -#### stacks-gen usage - -``` -npx -q stacks-gen sk --testnet - -{ - "phrase": "guide air pet hat friend anchor harvest dog depart matter deny awkward sign almost speak short dragon rare private fame depart elevator snake chef", - "private": "0351764dc07ee1ad038ff49c0e020799f0a350dd0769017ea09460e150a6401901", - "public": "022d82baea2d041ac281bebafab11571f45db4f163a9e3f8640b1c804a4ac6f662", - "stacks": "ST16JQQNQXVNGR8RZ1D52TMH5MFHTXVPHRV6YE19C", - "stacking": "{ hashbytes: 0x4d2bdeb7eeeb0c231f0b4a2d5225a3e3aeeed1c6, version: 0x00 }", - "btc": "mnYzsxxW271GkmyMnRfiopEkaEpeqLtDy8", - "wif": "cMh9kwaCEttgTQYkyMUYQVbdm5ZarZdBHErcq7mXUChXXCo7CFEh" -} -``` - -:::tip The stacking object with hashbytes and a version represents the bitcoin address derived from the Stacks address. Read more about the [bitcoin address format](stacking#bitcoin-address). ::: - -Full documentation available at [stacks-gen](https://github.com/psq/stacks-gen). - -## Querying - -### Get Stacks (STX) balance and nonce - -STX balance and nonce can be obtained through the [`GET /v2/accounts/`](https://docs.hiro.so/api#operation/get_account_info) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/accounts/' -``` - -Sample response: - -```js -{ - "balance": "0x0000000000000000002386f26f3f40ec", - "nonce": 17 -} -``` - -:::tip The balance string represents an unsigned 128-bit integer (big-endian) in hex encoding -::: - -### Get all token balances - -All token balances can be obtained through the [`GET /extended/v1/address//balances`](https://docs.hiro.so/api#operation/get_account_balance) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/address//balances' -``` - -Sample response: - -```js -{ - "stx": { - "balance": "0", - "total_sent": "0", - "total_received": "0" - }, - "fungible_tokens": {}, - "non_fungible_tokens": {} -} -``` - -:::tip Stacks accounts cannot hold bitcoins. The best way to obtain corresponding BTC balances is to derive the BTC address from the Stacks address (using [`c32check`](https://github.com/stacks-network/c32check#c32tob58-b58toc32)) and query the Bitcoin network. ::: - -### Get all asset events - -All asset events associated with the account can be obtained through the [`GET /extended/v1/address//assets`](https://docs.hiro.so/api#operation/get_account_balance) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/address//assets' -``` - -Sample response: - -```js -{ - "limit": 20, - "offset": 0, - "total": 0, - "results": [ - { - "event_index": 5, - "event_type": "non_fungible_token_asset", - "asset": { - "asset_event_type": "transfer", - "asset_id": "ST2W14YX9SFVDB1ZGHSH40CX1YQAP9XKRAYSSVYAG.hello_world::hello-nft", - "sender": "SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR", - "recipient": "SM2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQVX8X0G", - "value": { - "hex": "0x0100000000000000000000000000000001", - "repr": "u1" - } - } - }, - { - "event_index": 3, - "event_type": "fungible_token_asset", - "asset": { - "asset_event_type": "mint", - "asset_id": "ST2W14YX9SFVDB1ZGHSH40CX1YQAP9XKRAYSSVYAG.hello_world::novel-token-19", - "sender": "", - "recipient": "SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR", - "amount": "12" - } - } - ] -} -``` diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/index.md b/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/index.md deleted file mode 100644 index 1533219df9..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/index.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Understand Stacks -description: Learn more about the Stacks 2.0 blockchain -sidebar_position: 1 ---- - -![](/img/SBC-L-2x-10.png) -## Introduction - -Stacks 2.0 is a layer-1 blockchain that connects to Bitcoin and brings smart contracts and decentralized apps to it. Smart contracts and apps developed on the Stacks platform are natively integrated with the security, stability, and economic power of Bitcoin. - -## Capabilities - -Read more about the features provided by the Stacks 2.0 blockchain. - - - -:::tip Check out the [technical specifications](technical-specs) for a brief overview ::: - - - - -A detailed [comparison of the Stacks blockchain to other blockchain technologies][] is available at the Stacks Foundation blog. -### Consensus mechanism -![](/img/pages/stacking.svg) Stacks 2.0 implements a new mining mechanism called Proof of Transfer ("PoX"). PoX is a consensus algorithm between two blockchains. It uses an established blockchain (in this case Bitcoin) to secure a new blockchain (Stacks). - -PoX connects to Bitcoin with a 1:1 block ratio, meaning anything that happens on the Stacks blockchain can be verified on the Bitcoin Blockchain. - -Instead of burning electricity on proof of work, PoX reuses already minted bitcoins as "proof of computation" and miners represent their cost of mining in bitcoins directly. - - -[Read more about Proof of Transfer](proof-of-transfer) -### Mining - -![](/img/pages/testnet-sm.svg) Mining is required to make the network usable, trustworthy, and secure. Miners verify incoming transactions, participate in the consensus mechanism, and write new blocks to the blockchain. - -To incentivize mining, miners receive freshly minted Stacks (STX) tokens if they win the bid for becoming the leader of the next round. - -[Read more about Mining](mining) - -### Stacking - -Bitcoins used for miner bids are sent to a set of specific addresses corresponding to Stacks (STX) tokens holders that are actively participating in consensus ("Stackers"). Thus, rather than being destroyed, the bitcoins consumed in the mining process go to productive Stacks holders as a reward based on their holdings of Stacks and participation in the Stacking algorithm. - -Stackers have to lock up their Stacks (STX) tokens for a certain period of time. - -[Read more about Stacking](stacking) - -### Smart contracts - -![](/img/pages/write-smart-contracts-sm.svg) Clarity is a new language for smart contracts on the Stacks 2.0 blockchain. The Clarity smart contract language optimizes for predictability and security. - -Stacks 2.0 anchors clarity smart contracts to Bitcoin making it possible for smart contracts to operate based on actions seen on the bitcoin blockchain. - -:::note The [Clarity open-source project](https://clarity-lang.org/) is supported by Stacks and [Algorand](https://www.algorand.com/) ::: - - -Clarity is distinct from other languages designed for writing smart contracts in a few ways: - -- **Predictability**: The Clarity language uses precise and unambiguous syntax that allows developers to predict exactly how their contracts will be executed. -- **Security**: The Clarity language allows users to supply their own conditions for transactions that ensure that a contract may never unexpectedly transfer a token owned by a user. -- **No compiler**: Contracts written in Clarity are broadcasted on the Stacks blockchain exactly as they are written by developers. This ensures that the code developers wrote, analyzed, and tested, is exactly what gets executed. - -[Read more about Clarity](../write-smart-contracts/clarity-language/) - -## Guides - -Read one of our guides to understand the ins and outs of the Stacks 2.0 blockchain. - -* [Account](../understand-stacks/accounts) -* [Transactions](../understand-stacks/transactions) -* [Network](../understand-stacks/network) -* [Microblocks](../understand-stacks/microblocks) - -[comparison of the Stacks blockchain to other blockchain technologies]: https://stacks.org/stacks-blockchain diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md b/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md deleted file mode 100644 index daf7b58e0b..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: Microblocks -description: Guide to Stacks Microblocks -sidebar_position: 8 ---- - -## Introduction - -Microblocks are a protocol-level feature of the Stacks blockchain that solve the technical challenge of transaction latency. Because each Stacks block is anchored to a Bitcoin block through the [Proof-of-Transfer consensus mechanism](../understand-stacks/proof-of-transfer), Stacks is necessarily limited to the same block times as the Bitcoin network. Microblocks allow the Stacks blockchain to perform state transitions between anchor blocks. - -Microblocks are a powerful mechanism for developers to create performant, high quality applications on Stacks, while still inheriting the security of Bitcoin. - -## Transaction states - -The [Stacks block production model](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.) is described in SIP-001. The standard outlines the mechanism by which elected block leaders can produce blocks on the Stacks blockchain either by batching transactions or by streaming them. Microblocks are the product of the streaming model. - -If a block leader has elected to mine microblocks, the leader selects transactions from the mempool and package them into microblocks during the current epoch. Microblocks are blocks of transactions included by a miner after the previous anchor block has been mined, but before the next block is selected. Transactions included in microblocks are processed by the network: their results are known. - -Consider a transaction from the perspective of the number of block confirmations it has. A transaction included in a microblock might have the following example lifecycle: - -``` -Transaction 1 is broadcast to the mempool. It has 0 confirmations. -Transaction 1 is included in a microblock. It still has 0 confirmations, but the results of the transaction are known Transaction 1 is included in the next anchor block. It has 1 confirmation. -The next Stacks block confirms the previous block. Transaction 1 has 2 confirmations. -The next Stacks block confirms the previous block. Transaction 1 has 3 confirmations. -... -``` - -Consider a similar transaction that is not included in a microblock: - -``` -Transaction 2 is broadcast to the mempool. It has 0 confirmations. -Transaction 2 is included in the next anchor block. It has 1 confirmation. -The next Stacks block confirms the previous block. Transaction 2 has 2 confirmations. -The next Stacks block confirms the previous block. Transaction 2 has 3 confirmations. -``` - -The lifecycles of the two transactions are similar, but the difference is pending state. Many Bitcoin wallets display 0-confirmation balances: your wallet balance with any mempool transactions already applied. This is useful because it tells you when you've sent a transaction or received one. With smart contracts, displaying pending state is not as straightforward, because smart contracts do not just transfer inputs to outputs, they may call other contracts, emit events, or perform other computations. A transaction processed in a microblock generates all that information. - -:::tip If a transaction is dependent on a chain state that could by altered by previous transactions with serious -implications, you should carefully consider whether it should be performed using microblocks. -::: - -## Enabling microblocks - -Miners can choose to enable or disable microblocks in their mining configuration. As a best practice, miners should enable microblock mining. When an application or user submits a transaction, the transaction can include an argument that requires the transaction to be in a microblock, an anchor block, or in either. - -### Transactions - -Transactions include an option that controls if a miner should include them in microblocks or in anchor blocks. The anchor mode transaction option is an optional argument that controls whether a transaction must be included in an anchor block or a microblock, or is eligible for either. - -### Mining - -Stacks miners must enable microblocks in their miner configuration to implement the block streaming model. For more information, see [mining microblocks](../understand-stacks/mining#microblocks). - -## Developing with microblocks - -In most cases, information from transactions included in microblocks should be treated like information from any other block. Wallets and explorers should display the consequences of microblock transactions as the current state of the network. This state should be acknowledged as tentative. - -A microblock transaction can end up being reorganized in the next block rather than just being confirmed as-is. Because of this, your UI should communicate to users if the outputs of a transaction changed, or if the transaction's associated block changed. This is the same outcome as if a 1-block fork occurred. - -### Stacks.js libraries - -Stacks.js provides the [AnchorMode][] argument on transaction objects so that your application can set the microblocks preference for transactions. - -### API - -:::danger API support for microblocks is a work-in-progress. Review the [API documentation][microblocks_api] carefully to ensure that you are up-to-date on the latest implementation details for microblocks. ::: - -The Stacks Blockchain API exposes microblocks through several endpoints. Please review the [Stacks Blockchain API guide][] for more details. - -## Best practices - -Working with microblocks is a design decision that you must make for your own application. When working with microblocks, the following best practices are recommended. - -### Handling nonce - -Nonce handling with microblocks is challenging because the next account nonce must take into account any nonce values included in microblocks, which may not yet be included in an anchor block. The Stacks Blockchain API [provides an endpoint][] to retrieve the next nonce for a given principal. - -### Application design - -The state of microblock transactions should be carefully communicated to users. No transaction is final until it's included in an anchor block, and your application design should reflect this. - -The following guidelines are provided as an initial set of best practices for UI design when incorporating microblocks into your application. - -#### Explorers - -Display pending state, but warn that a transaction is still pending. Indicate visually that displayed balances depend on pending state. - -#### Wallets - -Display pending state, but warn that a transaction is still pending. Indicate visually that displayed balances depend on pending state. - -#### Exchanges - -Continue to count confirmations, microblocks should be considered pending. - -#### Applications - -Microblock communication is highly app-dependent. For some applications, displaying a pending or 0-confirmation transaction as confirmed may be fine. For example, storing data on the chain, or querying the BNS contract. For other applications, such as the transfer of real value, waiting for 3-confirmations would be prudent before displaying the state as confirmed. - -[AnchorMode]: https://stacks.js.org/enums/transactions.AnchorMode.html -[Stacks Blockchain API guide]: https://docs.hiro.so/get-started/stacks-blockchain-api#microblocks-support -[provides an endpoint]: https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling -[microblocks_api]: https://docs.hiro.so/api#tag/Microblocks diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/mining.md b/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/mining.md deleted file mode 100644 index fa1f56ed3f..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/mining.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Mining -description: A guide to mining on Stacks 2.0 -sidebar_position: 4 ---- - -## Introduction - -This guide highlights some technical details related to mining on the Stacks 2.0 network. - -For steps on how to setup your own miner please refer to [miner on tesnet](nodes-and-miners/miner-testnet.md) and [miner on mainnet](nodes-and-miners/miner-testnet.md). - -## Mining frequency - -A new Stacks block may be mined once per Bitcoin block. To be considered for mining a block, a miner must have a block commit included in a Bitcoin block. If a miner wishes to update their commitment after submission, they may use Bitcoin Replace-By-Fee. - -## Coinbase rewards - -Miners receive coinbase rewards for blocks they win. - -The reward amounts are: - -- 1000 STX per block are released in the first 4 years of mining -- 500 STX per block are released during the following 4 years -- 250 STX per block are released during the following 4 years -- 125 STX per block are released from then on indefinitely. - -These "halvings" are synchronized with Bitcoin halvings. - -![coinbase rewards](/img/pages/coinbase-rewards.png) - -## Transaction fees - -Miners receive Stacks fees for transactions mined in any block they produce. - -For transactions mined in microblocks, the miner that produces the microblock receives 40% of the fees, while the miner that confirms the microblock receives 60% of the fees. - -## Reward maturity - -Block rewards and transaction fees take 100 blocks on the Bitcoin blockchain to mature. After successfully mining a block your rewards appear in your Stacks account after ~24 hours. - -## Mining with proof-of-transfer - -Miners commit Bitcoin to **two** addresses in every leader block commit. The amount committed to each address must be the same. The addresses are chosen from the current reward set of stacking participants. Addresses are chosen using a verifiable-random-function, and determining the correct two addresses for a given block requires monitoring the Stacks chain. - -![mining with pox](/img/pages/mining-with-pox.png) - -## 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, 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. - -While there is no minimum BTC commitment enforced by the protocol, in practice, there's a floor constrained by [dust](https://unchained-capital.com/blog/dust-thermodynamics/)": basically, if the fees for a transaction exceed the value of the spent output, it's considered dust. How dust is [calculated](https://github.com/bitcoin/bitcoin/blob/master/src/policy/policy.cpp#L14) depends on a number of factors, we've found 5,500 satoshis to be good lower bound per [output](https://learnmeabitcoin.com/technical/output). Bitcoin transactions from Stacks miners contain two outputs (for Proof-of-Transfer), so a commitment of at least 11,000 satoshis / block is recommended. - -To calculate the amount of BTC to send miners should: - -- Guess the price BTC/STX for the next day (100 blocks later) -- Guess the total amount of BTCs committed by all miners - -## Microblocks - -The Stacks blockchain produces blocks at the same rate as the Bitcoin blockchain. In order to provide lower latency transactions, miners can opt to enable microblocks. Microblocks allow the current block leader to stream transactions and include their state transitions in the current epoch. - -If a block leader opts to produce microblocks, the next leader builds the chain tip off the last microblock that the current leader produces. - -The block streaming model is described in [SIP-001][]. - -[SIP-001]: https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md#operation-as-a-leader diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/network.md b/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/network.md deleted file mode 100644 index be6653e431..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/network.md +++ /dev/null @@ -1,149 +0,0 @@ ---- -title: Network -description: Guide to the Stacks 2.0 network -sidebar_position: 7 ---- - -## Tokens - -Stacks (STX) tokens are the native tokens on the Stacks 2.0 blockchain. The smallest fraction is one micro-STX. 1,000,000 micro-STX make one Stacks (STX). - -STX amounts should be stored as integers (8 bytes long), and represent the amount of micro-STX. For display purposes, micro-STX are divided by 1,000,000 (decimal precision of 6). - -## 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 in bytes. The fee rate is a market determined variable. For the [testnet](testnet), it is set to 1 micro-STX. - -Fee estimates can obtained through the [`GET /v2/fees/transfer`](https://docs.hiro.so/api#operation/get_fee_transfer) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/fees/transfer' -``` - -The API will respond with the fee rate (as integer): - -```json -1 -``` - -[The Stacks Transactions JS library](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) supports fee estimation for: - -- token transfers (`estimateTransfer`) -- contract deploys (`estimateContractDeploy`) -- non read-only contract calls (`estimateContractFunctionCall`) - -:::tip For an implementation using a different language than JavaScript, please review [this reference implementation](https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/src/builders.ts#L97). ::: - -## Nonces - -Every account carries a [nonce property](https://en.wikipedia.org/wiki/Cryptographic_nonce) that indicates the number of transactions processed for the given account. Nonces are one-time codes, starting at `0` for new accounts, and incremented by 1 on every transaction. - -Nonces are added to all transactions and help identify them in order to ensure transactions are processed in order and to avoid duplicated processing. - -:::tip 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 is constructed, the most recent nonce of the account needs to fetched and set. - -:::tip The API provides an endpoint to [simplify nonce handling](https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling). ::: - -## Confirmations - -The Stacks 2.0 network is anchored onto the bitcoin network. This allows transactions on Stacks to inherit the same finality and security of the Bitcoin blockchain. - -The time to mine a block, to confirm transactions, will eventually match the expected "block time" of the bitcoin network: 10 minutes. - -:::tip Transactions can also be mined in [microblocks](microblocks), reducing the latency significantly. ::: - -The block time is hardcoded and will change throughout the implementation phases of the [testnet](testnet). The current block time can be obtained through the [`GET /extended/v1/info/network_block_times`](https://docs.hiro.so/api#operation/get_network_block_times) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/info/network_block_times' -``` - -The API will respond with the block time (in seconds): - -```js -{ - "testnet": { - "target_block_time": 120 - }, - "mainnet": { - "target_block_time": 600 - } -} -``` - -## Read-only function calls - -Smart contracts can expose public function calls. For functions that make state modifications to the blockchain, transactions need to be generated and broadcasted. - -However, for read-only function calls, transactions are **not** required. Instead, these calls can be done using the [Stacks Blockchain API](https://docs.hiro.so/get-started/stacks-blockchain-api). - -:::tip Read-only function calls do not require transaction fees -::: - -A read-only contract call can be done using the [`POST /v2/contracts/call-read///`](https://docs.hiro.so/api#operation/call_read_only_function) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl --location --request POST 'https://stacks-node-api.testnet.stacks.co/v2/contracts/call-read///' \ ---header 'Content-Type: application/json' \ ---data-raw '{ - "sender": ".", - "arguments": [, ...] -}' -}' -}' -}' -``` - -Sample response for a successful call: - -```js -{ - "okay": true, - "result": "" -} -``` - -:::tip To set the function call arguments and read the result, [Clarity values](../write-smart-contracts/values) need to be serialized into a hexadecimal string. The [Stacks Transactions JS](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library supports these operations ::: - -## Querying - -Stacks 2.0 network details can be queried using the [Stacks Blockchain API](https://docs.hiro.so/get-started/stacks-blockchain-api). - -### Health check - -The [status checker](https://stacks-status.com/) is a service that provides a user interface to quickly review the health of the Stacks 2.0 blockchain. - -### Network info - -The network information can be obtained using the [`GET /v2/info`](https://docs.hiro.so/api#operation/get_core_api_info) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/info' -``` - -Sample response: - -```js -{ - "peer_version": 385875968, - "burn_consensus": "826401d65cf3671210a3fb135d827d549c0b4d37", - "burn_block_height": 1972, - "stable_burn_consensus": "e27ea23f199076bc41a729d76a813e125b725f64", - "stable_burn_block_height": 1971, - "server_version": "blockstack-core 0.0.1 => 23.0.0.0 (master:bdd042242+, release build, linux [x86_64]", - "network_id": 2147483648, - "parent_network_id": 3669344250, - "stacks_tip_height": 933, - "stacks_tip": "1f601823fbcc5b6b2215b2ff59d2818fba61ee4a3cea426d8bc3dbb268005d8f", - "stacks_tip_burn_block": "54c56a9685545c45accf42b5dcb2787c97eda8185a1c794daf9b5a59d4807abc", - "unanchored_tip": "71948ee211dac3b241eb65d881637f649d0d49ac08ee4a41c29217d3026d7aae", - "exit_at_block_height": 28160 -} -``` diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md b/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md deleted file mode 100644 index c933f7af68..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Proof of Transfer -description: Understand the proof-of-transfer consensus mechanism -sidebar_position: 3 ---- - -## Overview - -Consensus algorithms for blockchains require compute or financial resources to secure the blockchain. The general practice of decentralized consensus is to make it practically infeasible for any single malicious actor to have enough computing power or ownership stake to attack the network. - -Popular consensus mechanisms in modern blockchains include proof-of-work, in which nodes dedicate computing resources, and proof-of-stake, in which nodes dedicate financial resources to secure the network. - -Proof-of-burn is a novel consensus mechanism where miners compete by ‘burning’ (destroying) a proof-of-work cryptocurrency as a proxy for computing resources. - -Proof-of-transfer (PoX) is an extension of the proof-of-burn mechanism. 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. - -![PoX mechanism](/img/pox-mechanism.png) - -This allows network participants to secure the PoX cryptocurrency network and earn a reward in the base cryptocurrency. Thus, proof-of-transfer blockchains are anchored on their chosen proof-of-work chain. Stacks uses [Bitcoin](#why-bitcoin) as its anchor chain. - -![PoX participants](/img/pox-participants.png) - -## Why Bitcoin? - -There are a number of reasons that Stacks chose Bitcoin as the blockchain to power consensus. It's the oldest blockchain protocol, having launched in 2009, and has become a recognized asset outside of the cryptocurrency community. BTC has held the highest market capitalization of any cryptocurrency for the past decade. - -Bitcoin champions simplicity and stability, and has stood the test of time. Influencing or attacking the network is infeasible or impractical for any potential hackers. It's one of the only cryptocurrencies to capture public attention. Bitcoin is a household name, and is recognized as an asset by governments, large corporations, and legacy banking institutions. Lastly, Bitcoin is largely considered a reliable store of value, and provides extensive infrastructure to support the proof-of-transfer consensus mechanism. - -SIP-001 provides a full [list of reasons why Bitcoin was chosen to secure Stacks](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md). - -![btc-stacks](/img/pox-why-bitcoin.png) - -## Blocks and microblocks - -The Stacks blockchain allows for increased transaction throughput using a mechanism called microblocks. Bitcoin and Stacks progress in lockstep, and their blocks are confirmed simultaneously. On Stacks, this is referred to as an ‘anchor block’. An entire block of Stacks transactions corresponds to a single Bitcoin transaction. This significantly improves cost/byte ratio for processing Stacks transactions. Because of simultaneous block production, Bitcoin acts as a rate-limiter for creating Stacks blocks, thereby preventing denial-of-service attacks on its peer network. - -However, in between Stacks anchor blocks settling on the Bitcoin blockchain, there are also a varying number of microblocks that allow rapid settlement of Stacks transactions with a high degree of confidence. This allows Stacks transaction throughput to scale independently of Bitcoin, while still periodically establishing finality with the Bitcoin chain. The Stacks blockchain adopts a block streaming model whereby each leader can adaptively select and package transactions into their block as they arrive in the mempool. Therefore when an anchor block is confirmed, all of the transactions in the parent microblock stream are packaged and processed. This is an unprecedented method for achieving scalability without creating a totally separate protocol from Bitcoin. - -![stx-microblock](/img/stx-microblocks.png) - -## Unlocking Bitcoin capital - -Stacks also unlocks the hundreds of billions in capital in Bitcoin, and gives Bitcoiners new opportunities to use and earn BTC. Stacks is a accompaniment to the Bitcoin ecosystem, and the two networks working in tandem enables totally novel ways of using BTC. The Stacks ecosystem makes interactive cryptocurrency applications available to Bitcoin holders. Additionally, By stacking STX tokens and participating in the PoX consensus mechanism, users have the opportunity to earn BTC while securing the Stacks chain. - -![Unlocking Bitcoin](/img/pox-unlocking-btc.png) - -## Clarity and the Bitcoin state - -Clarity smart contracts also have unique visibility into the state of the Bitcoin blockchain. This means that contract logic in a Clarity file has the ability to trigger when specific Bitcoin transactions are confirmed. Clarity smart contracts have a built in Simple Payment Verification (SPV) proofs for Bitcoin that make interacting with Bitcoin’s state much simpler for developers. Additionally, Clarity contracts can fork with the original Bitcoin chain. Therefore, in an edge case where Bitcoin forks, developers wouldn’t have to worry about adjusting the deployment of their smart contracts. - -## See also - -- [Read the full PoX whitepaper](https://community.stacks.org/pox) -- [Watch Executive Chair of Hiro Muneeb Ali and Evangelist Joe Bender give an overview of Stack's breakthrough PoX mining mechanism](https://www.youtube.com/watch?v=NY_eUrIcWOY) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md b/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md deleted file mode 100644 index 07cba4d2c1..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: Stacking -description: Introduction to the reward mechanism of Proof-of-Transfer -sidebar_position: 9 ---- - -## Introduction - -Stacking rewards Stacks (STX) token holders with bitcoin for providing a valuable service to the network by locking up their tokens for a certain time. - -![](/img/stacking.png) - -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. - -:::info The Stacking consensus algorithm is implemented as a smart contract, using [Clarity](../write-smart-contracts/). [Read more about the contract](../noteworthy-contracts/stacking-contract). ::: - -## Stacking flow - -The Stacking mechanism can be presented as a flow of actions: - -![Stacking flow](/img/stacking-illustration.png) - -1. Make API calls to get details about the upcoming reward cycle -2. For a specific Stacks account, confirm eligibility -3. Confirm the BTC reward address and the lockup duration -4. The transaction is broadcasted and the STX tokens are locked. This needs to happen before the prepare phase of the next reward cycle, the last 100 Bitcoin blocks of the ongoing reward phase -5. The Stacking mechanism executes reward cycles and sends out rewards to the set BTC reward address -6. During the lockup period, details about unlocking timing, rewards and more can be obtained -7. Once the lockup period is passed, the tokens are released and accessible again -8. Display reward history, including details like earnings for previous reward cycles - -:::info Keep in mind that the target duration for a reward cycles is ~2 weeks. This duration is based on the target block time of the network (10 minutes) and can be higher at times due to [confirmation time variances](https://www.blockchain.com/charts/median-confirmation-time) of the bitcoin network. ::: - -## Stacking delegation flow - -The Stacking flow is different for delegation use cases: - -![Delegated tacking flow](/img/stacking-delegation-illustration.png) - -- Before Stacking can be initiated for a token holder, the delegator needs to be granted permission to Stack on behalf of the account owner. The permission is restricted to the maximum amount the delegator is allowed to Stack. The maximum amount is not limited by the available funds and can be set much higher. An account can only be associated with one single delegator -- The account has to define the delegation relationship. They can optionally restrict the Bitcoin reward address that must be used for payouts, and the expiration burn block height for the permission, thus limiting the time a delegator has permission to Stack -- Delegators have to lock Stacks from different accounts ("pooling phase") until they reach the minimum amount of Stacks required to participate in Stacking -- Once a delegator locks enough STX tokens, they can finalize and commit their participation in the next reward cycle -- Certain delegation relationships may allow the STX holder to receive the payout directly from the miner (step 5/6) -- The termination of the delegation relationship can either happen automatically based on set expiration rules or by actively revoking delegation rights - -## PoX mining - -PoX mining is a modification of Proof-of-Burn (PoB) mining, where instead of sending the committed Bitcoin to a burn address, it's transferred to eligible STX holders that participate in the stacking protocol. - -:::note A PoX miner can only receive newly minted STX tokens when they transfer Bitcoin to eligible owners of STX tokens -::: - -![Mining flow](/img/pox-mining-flow.png) - -Miners run Stacks nodes with mining enabled to participate in the PoX mechanism. The node implements the PoX mechanism, which ensures proper handling and incentives through four key phases: - -- Registration: miners register for a future election by sending consensus data to the network -- Commitment: registered miners transfer Bitcoin to participate in the election. Committed BTC are sent to a set participating STX token holders -- Election: a verifiable random function chooses one miner to write a new block on the Stacks blockchain -- Assembly: the elected miner writes the new block and collects rewards in form of new STX tokens - -## Token holder eligibility - -Stacks (STX) token holders don't automatically receive stacking rewards. Instead, they must: - -- Commit to participation before a reward cycle begins -- Commit the minimum amount of STX tokens to secure a reward slot, or pool with others to reach the minimum -- Lock up STX tokens for a specified period -- Provide a supported Bitcoin address to receive rewards (native segwit is not supported) - -The following diagram describes how the minimum STX tokens per slot is determined. More information on [dynamic minimums for stacking](https://stacking.club) is available at stacking.club. - -![Dynamic minimum for individual eligibility](/img/stacking-dynamic-minimum.png) - -Token holders have a variety of providers and tools to support their participation in Stacking. The Stacks website contains a [list of stacking providers and pools](https://stacks.org/stacking#earn). - -## Stacking in the PoX consensus algorithm - -Stacking is a built-in capability of PoX and occurs through a set of actions on the Stacks blockchain. The [full proof-of-transfer implementation details](https://github.com/stacks-network/stacks-blockchain/blob/develop/sip/sip-007-stacking-consensus.md) are in SIP-007. Below is a summary of the most relevant actions of the algorithm. - -![PoX cycles](/img/pox-cycles.png) - -- Stacking happens over reward cycles with a fixed length. In each reward cycle, a set of Bitcoin addresses associated with stacking participants receive BTC rewards -- A reward cycle consists of two phases: prepare and reward -- During the prepare phase, miners decide on an anchor block and a reward set. Mining any descendant forks of the anchor block requires transferring mining funds to the appropriate reward addresses. The reward set is the set of Bitcoin addresses which are eligible to receive funds in the reward cycle -- Miners register as leader candidates for a future election by sending a key transaction that burns cryptocurrency. The transaction also registers the leader's preferred chain tip (must be a descendant of the anchor block) and commitment of funds to 2 addresses from the reward set -- Token holders register for the next rewards cycle by broadcasting a signed message that locks up associated STX tokens for a protocol-specified lockup period, specifies a Bitcoin address to receive the funds, and votes on a Stacks chain tip -- Multiple leaders can commit to the same chain tip. Multiple leaders can commit to the same chain tip. Multiple leaders can commit to the same chain tip. Multiple leaders can commit to the same chain tip. The leader that wins the election and the peers who also burn for that leader collectively share the reward, proportional to how much each one burned -- Token holders' locked up tokens automatically unlock as soon as the lockup period finishes - -## Bitcoin address - -:::danger You must provide a BTC address in one of two formats: - -* [Legacy (P2PKH)](https://en.bitcoin.it/wiki/Transaction#Pay-to-PubkeyHash), which starts with `1`. - -* [Segregated Witness / Segwit (P2SH)](https://en.bitcoin.it/wiki/Pay_to_script_hash), which starts with `3`. The "Native Segwit" format (which starts with `bc1`), for example, is not supported. ::: - -The Stacking contract needs a special format for the Bitcoin address (the reward address). This is required to ensure that miners are able to correctly construct the Bitcoin transaction containing the reward address. - -The address must be specified in the following format using the Clarity language: - -```clar -;; a tuple of a version and hashbytes buffer -(pox-addr (tuple (version (buff 1)) (hashbytes (buff 20)))) -``` - -The `version` buffer must represent what kind of bitcoin address is being submitted. It can be one of the following: - -```js -SerializeP2PKH = 0x00, // hash160(public-key), same as bitcoin's p2pkh SerializeP2SH = 0x01, // hash160(multisig-redeem-script), same as bitcoin's multisig p2sh SerializeP2WPKH = 0x02, // hash160(segwit-program-00(p2pkh)), same as bitcoin's p2sh-p2wpkh SerializeP2WSH = 0x03, // hash160(segwit-program-00(public-keys)), same as bitcoin's p2sh-p2wsh -``` - -The `hashbytes` are the 20 hash bytes of the bitcoin address. You can obtain that from a bitcoin library, for instance using [`bitcoinjs-lib`](https://github.com/bitcoinjs/bitcoinjs-lib): - -```js -const btc = require('bitcoinjs-lib'); -console.log( - '0x' + btc.address.fromBase58Check('1C56LYirKa3PFXFsvhSESgDy2acEHVAEt6').hash.toString('hex') -); -``` - -## Choosing the right Stacking strategy - -[Here](https://blog.stacks.co/stacking-strategy) is an interesting article that may help you choose the right Stacking stategy. - - -## Where to Stacks? - -You can Stack on your own, on a pool or on an exchange: -### Stacking on your own - -Stacking on your own is non-custodial. - -Stacking on your own requires a protocol minimum (amount changes but about 100,000 STX). - -[Hiro Wallet](https://www.hiro.so/wallet) allows stacking on your own. - -### Stacking on a pool - -Stacking on a pool allows Stacking without the requirement of the protocol minumum. - -Some available pools are: - -| Pool | Type | Pays rewards in | Fee | Minimum amount | -| --------------------------------------------------- | ------------- |:---------------:| --- |:--------------:| -| [Friedger's Pool](https://pool.friedger.de/) | Non custodial | STX or xBTC | No | 40 STX | -| [Planbetter](https://planbetter.org/) | Non custodial | BTC | 5% | 200 STX | -| [Stacked](https://staking.staked.us/stacks-staking) | Non custodial | BTC | | 100,000 STX | -| [Xverse](https://www.xverse.app/) | Non custodial | BTC | No | 100 STX | - -### Stacking on an exchange - -Stacking on an exchange is custodial, meaning you are trusting the exchange with your Stacks. - -Several exchanges allow Stacking directly on their sites. Examples are [Okcoin](https://www.okcoin.com) and [Binance](https://www.binance.com/en/staking) - -## Stacking statistics - -You can view all sorts of Stacking data and statistics on [Stacking Club](https://stacking.club) \ No newline at end of file diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md b/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md deleted file mode 100644 index d942d6af8f..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Stacks Blockchain API -description: Interacting with the Stacks 2.0 Blockchain via API ---- - -## Temporal page because of a Crowdin bug \ No newline at end of file diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md b/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md deleted file mode 100644 index e370129d1d..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Technical Specifications -description: Summary of technical specifications of Stacks 2.0 -sidebar_position: 10 ---- - -## Consensus - -- Proof of Transfer (PoX) as described in [SIP-007](https://github.com/stacksgov/sips/blob/main/sips/sip-007/sip-007-stacking-consensus.md) -- Network will transition to Proof of Burn (PoB) as described in [SIP-001](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md) after 10 years. [Learn more about Proof-of-Burn in SIP-001](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md). -- Threat model - - 51% of malicious Stacks mining power can perform a double-spend attack - - 51% of malicious Bitcoin mining power can reorg the Stacks chain -- Different actors and their roles - - Stacks Miners package transactions into blocks, mine them through a Bitcoin transaction, propagate them, and if they win the block race, append microblocks to their winning block until the next block is mined. The next block confirms the microblock stream. - - Stacks Holders may alter the calculation of block limits (subject to a miner veto) and may vote to disable Proof-of-Transfer rewards for a reward cycle. -- Transactions are considered final when the corresponding "block commit" transaction on Bitcoin is finalized. Typically this can by 3-6 confirmations. -- For more details, see [Proof of Transfer](proof-of-transfer). - -## Proof of Transfer Mining - -- Coinbase reward schedule: - - 1000 STX/block for first 4 years - - 500 STX/block for following 4 years - - 250 STX/block for subsequent 4 years - - 125 STX/block in perpetuity after that -- Coinbase rewards accumulate for "missed sortitions": If a Bitcoin block has no sortition (at height N), then any Stacks block mined in a subsequent sortition that builds off of any Stacks chain tip that existed at the penultimate sortition (at height N-1) may claim its coinbase. This encourages miners to keep mining even if Bitcoin fees are high. -- Initial mining bonus: This is a special case of the above to incentivize early miners. Coinbase for all burnchain blocks between the first burn block height (to be chosen by independent miners as part of the Stacks 2.0 launch) and the first sortition winner accumulate and are distributed to miners over a fixed window (to be determined). For instance, say burn block height is 10,000 and first sortition is at block 10500 and distribution window is 100 blocks, then coinbase for the first 500 blocks (10,500 - 10,000) will be distributed evenly to miners who win sortition over the subsequent 100 blocks. -- 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 at least 11,000 satoshis (5,500 sats / [UTXO output](https://learnmeabitcoin.com/technical/utxo)); 2 outputs / block) to avoid "dust." -- For more details, see [Mining](mining). - -## Stacking - -- Stacking works in 2 phases - 1. Prepare phase: In this phase an "anchor block" is chosen. The qualifying set of addresses ("reward set") is determined based on the snapshot of the chain at the anchor block. Length of prepare phase is 100 blocks. Stacking commitments need to be confirmed before this phase starts - 2. Reward phase: In this phase miner BTC commitments are distributed amongst the reward set. Reward cycle length is 2000 BTC blocks (~2 weeks). -- 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/stacksgov/sips/blob/main/sips/sip-007/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.stacks.co/references/stacking-contract#delegate-stx). -- Only two types of BTC reward addresses are supported: [Legacy (P2PKH)](https://en.bitcoin.it/wiki/Transaction#Pay-to-PubkeyHash) or [Segregated Witness / Segwit (P2SH)](https://en.bitcoin.it/wiki/Pay_to_script_hash). Native Segwit is not supported. -- Further reading: [Stacking](stacking) - -## Accounts and Addresses - -- Transactions in the Stacks blockchain originate from, are paid for by, and execute under the authority of accounts -- An account is fully specified by its address + nonce + assets -- 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 (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](accounts) - -## Transactions - -- Transaction 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 - 2. _paying account_ is the account that is billed by the leader for the cost of validating and executing the transaction - 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 -- Transactions can be batched or streamed into blocks. The behavior can be controlled by the anchor mode of a transaction. With streaming ([microblocks](microblocks)), a faster confirmation time is possible. -- 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. -- Mempool limit for concurrent pending transactions is 25 per account -- Pending mempool transactions will be garbage-collected [256 blocks after receipt](https://github.com/stacks-network/stacks-blockchain/blob/master/src/core/mempool.rs#L62). With 10 minutes target block time, this would equal ~42 hours -- [Learn more about transaction encoding in SIP-005](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md#transaction-encoding) -- [Transaction signing and verification are described in SIP-005](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md#transaction-signing-and-verifying) -- All transactions impacting account balance are atomic, a transfer operation can not increment one account’s balance without decrementing another’s. However, transactions that perform multiple account actions (for example, transferring from multiple accounts) may partially complete. -- Transactions can include a memo string (max 34 bytes) - -## See also - -- [Read the full Stacks 2.0: Apps and Smart Contracts for Bitcoin whitepaper](https://cloudflare-ipfs.com/ipfs/QmaGgiVHymeDjAc3aF1AwyhiFFwN97pme5m536cHT4FsAW). - -- [Watch Aaron Blankstein video on Stacks whitepater v2](https://www.youtube.com/watch?v=Wd-Bfe8Sn-Y). \ No newline at end of file diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md b/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md deleted file mode 100644 index 4fb78f9c06..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Testnet -description: Test your smart contracts and apps -sidebar_position: 2 ---- - -## About testnet - -The testnet is a separate blockchain from the Stacks mainnet analogous to a staging environment. It's a network used by developers to test their apps, smart contracts, or changes to the protocol in a production-like environment. It produces blocks at roughly the same rate as mainnet; about 1 block every 10 minutes on average. The Stacks testnet is rarely reset. - -### Faucet - -The testnet faucet provides you with free Stacks Token (STX) to test with. These are not the same as STX on mainnet and have no value. You can get STX from the faucet on the [Stacks Explorer Sandbox](https://explorer.stacks.co/sandbox/faucet?chain=testnet), or using the [API](https://docs.hiro.so/api#tag/Faucets). - -To get STX tokens from within the Explorer Sandbox, navigate to the "Faucet" tab on the left and click "Request STX" button. - -![](/img/stx_faucet.png) - -You can also try out [Stacking](stacking) by clicking on `I want to stack`. - -:::note The Explorer Sandbox requires you to login with a Stacks wallet -::: - -### Testnet API - -The hosted Stacks Blockchain API for the testnet is available at this base URL: - -```shell -https://stacks-node-api.testnet.stacks.co/ -``` - -![](/img/api_testnet_status.png) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md b/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md deleted file mode 100644 index 2ff6072384..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Transactions -description: Guide to Stacks 2.0 transactions -sidebar_position: 6 ---- - -## Introduction - -Transactions are the fundamental unit of execution in the Stacks blockchain. Each transaction is originated from a [Stacks 2.0 account](accounts), and is retained in the Stacks blockchain history for eternity. This guide helps you understand Stacks 2.0 transactions. - -## Lifecycle - -Transactions go through phases before being finally confirmed, and available for all, on the Stacks 2.0 network. - -![Transaction lifecycle](/img/tx-lifecycle.png) - -- **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/en/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. - -:::note A transaction can have one of three states once it is registered: `pending`, `success`, or `failed`. ::: - -## Types - -The Stacks 2.0 supports a set of different transaction types: - -| **Type** | **Value** | **Description** | -| ----------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Coinbase | `coinbase` | The first transaction in a new block (an entity holding several transactions). Used to register for block rewards. These are not manually generated and broadcasted like other types of transactions. | -| Token transfer | `token_transfer` | Asset transfer from a sender to a recipient | -| Contract deploy | `smart_contract` | Contract instantiation | -| Contract call | `contract_call` | Contract call for a public, non read-only function | -| Poison Microblock | `poison_microblock` | Punish leaders who intentionally equivocate about the microblocks they package | - -A sample of each transaction type can be found in the [Stacks Blockchain API response definition for transactions](https://docs.hiro.so/api#operation/get_transaction_by_id). - -:::caution Read-only contract call calls do **not** require transactions. Read more about it in the [network guide](network#read-only-function-calls). ::: diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md b/i18n/pt/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md deleted file mode 100644 index fd45c80583..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Clarity Language -description: Overview of the Clarity language constructs -sidebar_label: Clarity Language -tags: - - clarity ---- - -## Clarity Type System - -The Clarity language uses a strong static type system. Function arguments and database schemas require specified types, and use of types is checked during contract launch. The type system does _not_ have a universal super type. - -## Public Functions - -Functions specified via `define-public` statements are _public_ functions and these are the only types of functions which may be called directly through signed blockchain transactions. In addition to being callable directly from a transaction (see the Stacks wire formats for more details on Stacks transactions), public functions may be called by other smart contracts. - -Public functions _must_ return a `(response ...)` type. This is used by Clarity to determine whether or not to materialize any changes from the execution of the function. If a function returns an `(err ...)` type, any mutations on the blockchain state from executing the function (and any function that it called during execution) will be aborted. - -In addition to functions defined via `define-public`, contracts may expose read-only functions. These functions, defined via `define-read-only`, are callable by other smart contracts, and may be queryable via public blockchain explorers. These functions _may not_ mutate any blockchain state. Unlike normal public functions, read-only functions may return any type. - -## Contract Calls - -A smart contract may call functions from other smart contracts using a `(contract-call?)` function. - -This function returns a response type result -- the return value of the called smart contract function. - -We distinguish 2 different types of `contract-call?`: - -### Static dispatch - -The callee is a known, invariant contract available on-chain when the caller contract is deployed. In this case, the callee's principal is provided as the first argument, followed by the name of the method and its arguments: - -```clarity -(contract-call? - .registrar - register-name - name-to-register) -``` - -### Dynamic dispatch - -The callee is passed as an argument, and typed as a trait reference (``). - -```clarity -(define-public (swap (token-a ) - (amount-a uint) - (owner-a principal) - (token-b ) - (amount-b uint) - (owner-b principal))) - (begin - (unwrap! (contract-call? token-a transfer-from? owner-a owner-b amount-a)) - (unwrap! (contract-call? token-b transfer-from? owner-b owner-a amount-b)))) -``` - -Traits can either be locally defined: - -```clarity -(define-trait can-transfer-tokens ( - (transfer-from? (principal principal uint) (response uint))) -``` - -Or imported from an existing contract: - -```clarity -(use-trait can-transfer-tokens - .contract-defining-trait.can-transfer-tokens) -``` - -Looking at trait conformance, callee contracts have two different paths. They can either be "compatible" with a trait by defining methods matching some of the methods defined in a trait, or explicitly declare conformance using the `impl-trait` statement: - -```clarity -(impl-trait .contract-defining-trait.can-transfer-tokens) -``` - -Explicit conformance should be prefered when adequate. It acts as a safeguard by helping the static analysis system to detect deviations in method signatures before contract deployment. - -The following limitations are imposed on contract calls: - -1. On static dispatches, callee smart contracts _must_ exist at the time of creation. -2. No cycles may exist in the call graph of a smart contract. This prevents recursion (and re-entrancy bugs). Such structures can be detected with static analysis of the call graph, and will be rejected by the network. -3. `contract-call?` are for inter-contract calls only. Attempts to execute when the caller is also the callee will abort the transaction. diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md b/i18n/pt/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md deleted file mode 100644 index 2acbb0cc93..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md +++ /dev/null @@ -1,1382 +0,0 @@ ---- -title: Functions -description: See a detailed list of all functions for the Clarity language. -tags: - - clarity ---- - -## Functions - -Detailed list of all functions for the Clarity language. - -### + (add) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(+ i1 i2...)` -#### description: -Adds a variable number of integer inputs and returns the result. In the event of an _overflow_, throws a runtime error. -#### example: -```clarity -(+ 1 2 3) ;; Returns 6 -(+ 2 3) ;; Returns 5 -(+ 1 2 3 4) ;; Returns 10 -(+ 9 -3) ;; Returns 6 -(+ -3 -2) ;; Returns -5 -``` - -### - (subtract) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(- i1 i2...)` -#### description: -Subtracts a variable number of integer inputs and returns the result. In the event of an _underflow_, throws a runtime error. -#### example: -```clarity -(- 2 1 1) ;; Returns 0 -(- 0 3) ;; Returns -3 -(- 5 -3) ;; Returns 8 -(- -4 -5) ;; Returns 1 -``` - -### * (multiply) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(* i1 i2...)` -#### description: -Multiplies a variable number of integer inputs and returns the result. In the event of an _overflow_, throws a runtime error. -#### example: -```clarity -(* 2 3) ;; Returns 6 -(* 5 2) ;; Returns 10 -(* 2 2 2) ;; Returns 8 -(* 3 -2) ;; Returns -6 -(* -1 -2) ;; Returns 2 -``` - -### / (divide) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(/ i1 i2...)` -#### description: -Divides a variable number of integer inputs and returns the _integer part_ of the result. In the event of _division by zero_, throws a runtime error. - -#### example: -```clarity -(/ 2 3) ;; Returns 0 -(/ 5 2) ;; Returns 2 -(/ 4 2 2) ;; Returns 1 -(/ -10 2) ;; Returns -5 -(/ -8 -2) ;; Returns 4 -(/ -9 4) ;; Returns -2 -``` - -### >= (greater than or equal) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(>= i1 i2)` -#### description: -Compares two integers, returning `true` if `i1` is greater than or equal to `i2` and `false` otherwise. -#### example: -```clarity -(>= 1 1) ;; Returns true -(>= 5 2) ;; Returns true -``` - -### <= (less than or equal) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(<= i1 i2)` -#### description: -Compares two integers, returning true if `i1` is less than or equal to `i2` and `false` otherwise. -#### example: -```clarity -(<= 1 1) ;; Returns true -(<= 5 2) ;; Returns false -``` - -### < (less than) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(< i1 i2)` -#### description: -Compares two integers, returning `true` if `i1` is less than `i2` and `false` otherwise. -#### example: -```clarity -(< 1 2) ;; Returns true -(< 5 2) ;; Returns false -``` - -### > (greater than) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(> i1 i2)` -#### description: -Compares two integers, returning `true` if `i1` is greater than `i2` and false otherwise. -#### example: -```clarity -(> 1 2) ;; Returns false -(> 5 2) ;; Returns true -``` - -### to-int -#### input: `uint` -#### output: `int` -#### signature: `(to-int u)` -#### description: -Tries to convert the `uint` argument to an `int`. Will cause a runtime error and abort if the supplied argument is >= `pow(2, 127)`` -#### example: -```clarity -(to-int u238) ;; Returns 238 -``` - -### to-uint -#### input: `int` -#### output: `uint` -#### signature: `(to-uint i)` -#### description: -Tries to convert the `int` argument to a `uint`. Will cause a runtime error and abort if the supplied argument is negative. -#### example: -```clarity -(to-uint 238) ;; Returns u238 -``` - -### mod -#### input: `int, int | uint, uint` -#### output: `int | uint` -#### signature: `(mod i1 i2)` -#### description: -Returns the integer remainder from integer dividing `i1` by `i2`. In the event of a division by zero, throws a runtime error. -#### example: -```clarity -(mod 2 3) ;; Returns 2 -(mod 5 2) ;; Returns 1 -(mod 7 1) ;; Returns 0 -``` - -### pow -#### input: `int, int | uint, uint` -#### output: `int | uint` -#### signature: `(pow i1 i2)` -#### description: -Returns the result of raising `i1` to the power of `i2`. In the event of an _overflow_, throws a runtime error. -#### example: -```clarity -(pow 2 3) ;; Returns 8 -(pow 2 2) ;; Returns 4 -(pow 7 1) ;; Returns 7 -``` - -### sqrti -#### input: `int | uint` -#### output: `int | uint` -#### signature: `(sqrti n)` -#### description: -Returns the largest integer that is less than or equal to the square root of `n`. Fails on a negative numbers. -#### example: -```clarity -(sqrti u11) ;; Returns u3 -(sqrti 1000000) ;; Returns 1000 -(sqrti u1) ;; Returns u1 -(sqrti 0) ;; Returns 0 -``` - -### log2 -#### input: `int | uint` -#### output: `int | uint` -#### signature: `(log2 n)` -#### description: -Returns the _integer part_ of the power to which the number 2 must be raised to obtain the value `n`. Fails on zero or a negative number. -#### example: -```clarity -(log2 u8) ;; Returns u3 -(log2 8) ;; Returns 3 -(log2 u1) ;; Returns u0 -(log2 1000) ;; Returns 9 -``` - -### xor -#### input: `int, int | uint, uint` -#### output: `int | uint` -#### signature: `(xor i1 i2)` -#### description: -Returns the result of bitwise exclusive or'ing `i1` with `i2`. -#### example: -```clarity -(xor 1 2) ;; Returns 3 -(xor 120 280) ;; Returns 352 -``` - -### and -#### input: `bool, ...` -#### output: `bool` -#### signature: `(and b1 b2 ...)` -#### description: -Returns `true` if all boolean inputs are `true`. Importantly, the supplied arguments are evaluated in-order and lazily. Lazy evaluation means that if one of the arguments returns `false`, the function short-circuits, and no subsequent arguments are evaluated. -#### example: -```clarity -(and true false) ;; Returns false -(and (is-eq (+ 1 2) 1) (is-eq 4 4)) ;; Returns false -(and (is-eq (+ 1 2) 3) (is-eq 4 4)) ;; Returns true -``` - -### or -#### input: `bool, ...` -#### output: `bool` -#### signature: `(or b1 b2 ...)` -#### description: -Returns `true` if any boolean inputs are `true`. Importantly, the supplied arguments are evaluated in-order and lazily. Lazy evaluation means that if one of the arguments returns `true`, the function short-circuits, and no subsequent arguments are evaluated. -#### example: -```clarity -(or true false) ;; Returns true -(or (is-eq (+ 1 2) 1) (is-eq 4 4)) ;; Returns true -(or (is-eq (+ 1 2) 1) (is-eq 3 4)) ;; Returns false -(or (is-eq (+ 1 2) 3) (is-eq 4 4)) ;; Returns true -``` - -### not -#### input: `bool` -#### output: `bool` -#### signature: `(not b1)` -#### description: -Returns the inverse of the boolean input. -#### example: -```clarity -(not true) ;; Returns false -(not (is-eq 1 2)) ;; Returns true -``` - -### is-eq -#### input: `A, A, ...` -#### output: `bool` -#### signature: `(is-eq v1 v2...)` -#### description: -Compares the inputted values, returning `true` if they are all equal. Note that _unlike_ the `(and ...)` function, `(is-eq ...)` will _not_ short-circuit. All values supplied to is-eq _must_ be the same type. -#### example: -```clarity -(is-eq 1 1) ;; Returns true -(is-eq true false) ;; Returns false -(is-eq \"abc\" 234 234) ;; Throws type error -``` - -### if -#### input: `bool, A, A` -#### output: `A` -#### signature: `(if bool1 expr1 expr2)` -#### description: -The `if` function admits a boolean argument and two expressions which must return the same type. In the case that the boolean input is `true`, the `if` function evaluates and returns `expr1`. If the boolean input is `false`, the `if` function evaluates and returns `expr2`. -#### example: -```clarity -(if true 1 2) ;; Returns 1 -(if (> 1 2) 1 2) ;; Returns 2 -``` - -### let -#### input: `((name1 AnyType) (name2 AnyType) ...), AnyType, ... A` -#### output: `A` -#### signature: `(let ((name1 expr1) (name2 expr2) ...) expr-body1 expr-body2 ... expr-body-last)` -#### description: -The `let` function accepts a list of `variable name` and `expression` pairs, evaluating each expression and _binding_ it to the corresponding variable name. `let` bindings are sequential: when a `let` binding is evaluated, it may refer to prior binding. The _context_ created by this set of bindings is used for evaluating its body expressions. The let expression returns the value of the last such body expression. Note: intermediary statements returning a response type must be checked` -#### example: -```clarity -(let ((a 2) (b (+ 5 6 7))) (print a) (print b) (+ a b)) ;; Returns 20 -(let ((a 5) (c (+ a 1)) (d (+ c 1)) (b (+ a c d))) (print a) (print b) (+ a b)) ;; Returns 23 -``` - -### map -#### input: `Function(A, B, ..., N) -> X, sequence_A, sequence_B, ..., sequence_N` -#### output: `(list X)` -#### signature: `(map func sequence_A sequence_B ... sequence_N)` -#### description: -The `map` function applies the function `func` to each corresponding element of the input sequences, and outputs a _list_ of the same type containing the outputs from those function applications. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. Also, note that, no matter what kind of sequences the inputs are, the output is always a list. -#### example: -```clarity -(map not (list true false true false)) ;; Returns (false true false true) -(map + (list 1 2 3) (list 1 2 3) (list 1 2 3)) ;; Returns (3 6 9) -(define-private (a-or-b (char (string-utf8 1))) (if (is-eq char u\"a\") u\"a\" u\"b\")) -(map a-or-b u\"aca\") ;; Returns (u\"a\" u\"b\" u\"a\") -(define-private (zero-or-one (char (buff 1))) (if (is-eq char 0x00) 0x00 0x01)) -(map zero-or-one 0x000102) ;; Returns (0x00 0x01 0x01) -``` - -### fold -#### input: `Function(A, B) -> B, sequence_A, B` -#### output: `B` -#### signature: `(fold func sequence_A initial_B)` -#### description: -The `fold` function condenses `sequence_A` into a value of type `B` by recursively applies the function `func` to each element of the input sequence _and_ the output of a previous application of `func`. - -`fold` uses `initial_B` in the initial application of `func`, along with the first element of `sequence_A`. The resulting value of type `B` is used for the next application of `func`, along with the next element of `sequence_A` and so on. `fold` returns the last value of type `B` returned by these successive applications `func`. - -Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. - -#### example: -```clarity -(fold * (list 2 2 2) 1) ;; Returns 8 -(fold * (list 2 2 2) 0) ;; Returns 0 -;; calculates (- 11 (- 7 (- 3 2))) -(fold - (list 3 7 11) 2) ;; Returns 5 -(define-private (concat-string (a (string-ascii 20)) (b (string-ascii 20))) (unwrap-panic (as-max-len? (concat a b) u20))) -(fold concat-string \"cdef\" \"ab\") ;; Returns \"fedcab\" -(fold concat-string (list \"cd\" \"ef\") \"ab\") ;; Returns \"efcdab\" -(define-private (concat-buff (a (buff 20)) (b (buff 20))) (unwrap-panic (as-max-len? (concat a b) u20))) -(fold concat-buff 0x03040506 0x0102) ;; Returns 0x060504030102 -``` - -### append -#### input: `list A, A` -#### output: `list` -#### signature: `(append (list 1 2 3 4) 5)` -#### description: -The `append` function takes a list and another value with the same entry type, and outputs a list of the same type with max_len += 1. -#### example: -```clarity -(append (list 1 2 3 4) 5) ;; Returns (1 2 3 4 5) -``` - -### concat -#### input: `sequence_A, sequence_A` -#### output: `sequence_A` -#### signature: `(concat sequence1 sequence2)` -#### description: -The `concat` function takes two sequences of the same type, and returns a concatenated sequence of the same type, with the resulting sequence_len = sequence1_len + sequence2_len. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`. - -#### example: -```clarity -(concat (list 1 2) (list 3 4)) ;; Returns (1 2 3 4) -(concat \"hello \" \"world\") ;; Returns \"hello world\" -(concat 0x0102 0x0304) ;; Returns 0x01020304 -``` - -### as-max-len? -#### input: `sequence_A, uint` -#### output: `sequence_A` -#### signature: `(as-max-len? sequence max_length)` -#### description: -The `as-max-len?` function takes a sequence argument and a uint-valued, literal length argument. The function returns an optional type. If the input sequence length is less than or equal to the supplied max_length, this returns `(some sequence)`, otherwise it returns `none`. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`. ` -#### example: -```clarity -(as-max-len? (list 2 2 2) u3) ;; Returns (some (2 2 2)) -(as-max-len? (list 1 2 3) u2) ;; Returns none -(as-max-len? \"hello\" u10) ;; Returns (some \"hello\") -(as-max-len? 0x010203 u10) ;; Returns (some 0x010203) -``` - -### len -#### input: `sequence_A` -#### output: `uint` -#### signature: `(len sequence)` -#### description: -The `len` function returns the length of a given sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`. ` -#### example: -```clarity -(len \"blockstack\") ;; Returns u10 -(len (list 1 2 3 4 5)) ;; Returns u5 -(len 0x010203) ;; Returns u3 -``` - -### element-at -#### input: `sequence_A, uint` -#### output: `(optional A)` -#### signature: `(element-at sequence index)` -#### description: -The `element-at` function returns the element at `index` in the provided sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. ` -#### example: -```clarity -(element-at \"blockstack\" u5) ;; Returns (some \"s\") -(element-at (list 1 2 3 4 5) u5) ;; Returns none -(element-at (list 1 2 3 4 5) (+ u1 u2)) ;; Returns (some 4) -(element-at \"abcd\" u1) ;; Returns (some \"b\") -(element-at 0xfb01 u1) ;; Returns (some 0x01) -``` - -### index-of -#### input: `sequence_A, A` -#### output: `(optional uint)` -#### signature: `(index-of sequence item)` -#### description: -The `index-of` function returns the first index at which `item` can be found, using `is-eq` checks, in the provided sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. If the target item is not found in the sequence (or if an empty string or buffer is supplied), this function returns `none`. -#### example: -```clarity -(index-of \"blockstack\" \"b\") ;; Returns (some u0) -(index-of \"blockstack\" \"k\") ;; Returns (some u4) -(index-of \"blockstack\" \"\") ;; Returns none -(index-of (list 1 2 3 4 5) 6) ;; Returns none -(index-of 0xfb01 0x01) ;; Returns (some u1) -``` - -### list -#### input: `A, ...` -#### output: `(list A)` -#### signature: `(list expr1 expr2 expr3 ...)` -#### description: -The `list` function constructs a list composed of the inputted values. Each supplied value must be of the same type. -#### example: -```clarity -(list (+ 1 2) 4 5) ;; Returns (3 4 5) -``` - -### var-get -#### input: `VarName` -#### output: `A` -#### signature: `(var-get var-name)` -#### description: -The `var-get` function looks up and returns an entry from a contract's data map. The value is looked up using `var-name`. -#### example: -```clarity -(define-data-var cursor int 6) -(var-get cursor) ;; Returns 6 -``` - -### var-set -#### input: `VarName, AnyType` -#### output: `bool` -#### signature: `(var-set var-name expr1)` -#### description: -The `var-set` function sets the value associated with the input variable to the inputted value. The function always returns `true`. -#### example: -```clarity -(define-data-var cursor int 6) -(var-get cursor) ;; Returns 6 -(var-set cursor (+ (var-get cursor) 1)) ;; Returns true -(var-get cursor) ;; Returns 7 -``` - -### map-get? -#### input: `MapName, tuple` -#### output: `(optional (tuple))` -#### signature: `(map-get? map-name key-tuple)` -#### description: -The `map-get?` function looks up and returns an entry from a contract's data map. The value is looked up using `key-tuple`. If there is no value associated with that key in the data map, the function returns a `none` option. Otherwise, it returns `(some value)`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(map-get? names-map (tuple (name \"blockstack\"))) ;; Returns (some (tuple (id 1337))) -(map-get? names-map { name: \"blockstack\" }) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-set -#### input: `MapName, tuple_A, tuple_B` -#### output: `bool` -#### signature: `(map-set map-name key-tuple value-tuple)` -#### description: -The `map-set` function sets the value associated with the input key to the inputted value. This function performs a _blind_ update; whether or not a value is already associated with the key, the function overwrites that existing association. - -Note: the `value-tuple` requires 1 additional byte for storage in the materialized blockchain state, and therefore the maximum size of a value that may be inserted into a map is MAX_CLARITY_VALUE - 1. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-set names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-insert -#### input: `MapName, tuple_A, tuple_B` -#### output: `bool` -#### signature: `(map-insert map-name key-tuple value-tuple)` -#### description: -The `map-insert` function sets the value associated with the input key to the inputted value if and only if there is not already a value associated with the key in the map. If an insert occurs, the function returns `true`. If a value already existed for this key in the data map, the function returns `false`. - -Note: the `value-tuple` requires 1 additional byte for storage in the materialized blockchain state, and therefore the maximum size of a value that may be inserted into a map is MAX_CLARITY_VALUE - 1. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns false -(map-insert names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-delete -#### input: `MapName, tuple` -#### output: `bool` -#### signature: `(map-delete map-name key-tuple)` -#### description: -The `map-delete` function removes the value associated with the input key for the given map. If an item exists and is removed, the function returns `true`. If a value did not exist for this key in the data map, the function returns `false`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-delete names-map { name: \"blockstack\" }) ;; Returns true -(map-delete names-map { name: \"blockstack\" }) ;; Returns false -(map-delete names-map (tuple (name \"blockstack\"))) ;; Same command, using a shorthand for constructing the tuple -``` - -### tuple -#### input: `(key-name A), (key-name-2 B), ...` -#### output: `(tuple (key-name A) (key-name-2 B) ...)` -#### signature: `(tuple (key0 expr0) (key1 expr1) ...)` -#### description: -The `tuple` special form constructs a typed tuple from the supplied key and expression pairs. A `get` function can use typed tuples as input to select specific values from a given tuple. Key names may not appear multiple times in the same tuple definition. Supplied expressions are evaluated and associated with the expressions' paired key name. - -There is a shorthand using curly brackets of the form {key0: expr0, key1: expr, ...}` -#### example: -```clarity -(tuple (name \"blockstack\") (id 1337)) ;; using tuple -{name: \"blockstack\", id: 1337} ;; using curly brackets -``` - -### get -#### input: `KeyName, (tuple) | (optional (tuple))` -#### output: `A` -#### signature: `(get key-name tuple)` -#### description: -The `get` function fetches the value associated with a given key from the supplied typed tuple. If an `Optional` value is supplied as the inputted tuple, `get` returns an `Optional` type of the specified key in the tuple. If the supplied option is a `(none)` option, get returns `(none)`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(get id (tuple (name \"blockstack\") (id 1337))) ;; Returns 1337 -(get id (map-get? names-map (tuple (name \"blockstack\")))) ;; Returns (some 1337) -(get id (map-get? names-map (tuple (name \"non-existent\")))) ;; Returns none -``` - -### merge -#### input: `tuple, tuple` -#### output: `tuple` -#### signature: `(merge tuple { key1: val1 })` -#### description: -The `merge` function returns a new tuple with the combined fields, without mutating the supplied tuples. -#### example: -```clarity -(define-map users { id: int } { name: (string-ascii 12), address: (optional principal) }) -(map-insert users { id: 1337 } { name: \"john\", address: none }) ;; Returns true -(let ((user (unwrap-panic (map-get? users { id: 1337 })))) -(merge user { address: (some 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) })) ;; Returns (tuple (address (some SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF)) (name \"john\")) -``` - -### begin -#### input: `AnyType, ... A` -#### output: `A` -#### signature: `(begin expr1 expr2 expr3 ... expr-last)` -#### description: -The `begin` function evaluates each of its input expressions, returning the return value of the last such expression. Note: intermediary statements returning a response type must be checked. -#### example: -```clarity -(begin (+ 1 2) 4 5) ;; Returns 5 -``` - -### hash160 -#### input: `buff|uint|int` -#### output: `(buff 20)` -#### signature: `(hash160 value)` -#### description: -The `hash160` function computes `RIPEMD160(SHA256(x))` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(hash160 0) ;; Returns 0xe4352f72356db555721651aa612e00379167b30f -``` - -### sha256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(sha256 value)` -#### description: -The `sha256` function computes `SHA256(x)` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(sha256 0) ;; Returns 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb -``` - -### sha512 -#### input: `buff|uint|int` -#### output: `(buff 64)` -#### signature: `(sha512 value)` -#### description: -The `sha512` function computes `SHA512(x)` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(sha512 1) ;; Returns 0x6fcee9a7b7a7b821d241c03c82377928bc6882e7a08c78a4221199bfa220cdc55212273018ee613317c8293bb8d1ce08d1e017508e94e06ab85a734c99c7cc34 -``` - -### sha512/256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(sha512/256 value)` -#### description: -The `sha512/256` function computes `SHA512/256(x)` (the SHA512 algorithm with the 512/256 initialization vector, truncated to 256 bits) of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(sha512/256 1) ;; Returns 0x515a7e92e7c60522db968d81ff70b80818fc17aeabbec36baf0dda2812e94a86 -``` - -### keccak256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(keccak256 value)` -#### description: -The `keccak256` function computes `KECCAK256(value)` of the inputted value. Note that this differs from the `NIST SHA-3` (that is, FIPS 202) standard. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(keccak256 0) ;; Returns 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4 -``` - -### secp256k1-recover? -#### input: `(buff 32), (buff 65)` -#### output: `(response (buff 33) uint)` -#### signature: `(secp256k1-recover? message-hash signature)` -#### description: -The `secp256k1-recover?` function recovers the public key used to sign the message which sha256 is `message-hash` with the provided `signature`. If the signature does not match, it will return the error code `(err u1).`. If the signature is invalid, it will return the error code `(err u2).`. The signature includes 64 bytes plus an additional recovery id (00..03) for a total of 65 bytes. -#### example: -```clarity -(secp256k1-recover? 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a1301) - ;; Returns (ok 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) - ``` - -### secp256k1-verify -#### input: `(buff 32), (buff 64) | (buff 65), (buff 33)` -#### output: `bool` -#### signature: `(secp256k1-verify message-hash signature public-key)` -#### description: -The `secp256k1-verify` function verifies that the provided signature of the message-hash was signed with the private key that generated the public key. The `message-hash` is the `sha256` of the message. The signature includes 64 bytes plus an optional additional recovery id (00..03) for a total of 64 or 65 bytes. -#### example: -```clarity -(secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a1301 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns true -(secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a13 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns true -(secp256k1-verify 0x0000000000000000000000000000000000000000000000000000000000000000 - 0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns false - ``` - -### print -#### input: `A` -#### output: `A` -#### signature: `(print expr)` -#### description: -The `print` function evaluates and returns its input expression. On Stacks Core nodes configured for development (as opposed to production mining nodes), this function prints the resulting value to `STDOUT` (standard output). -#### example: -```clarity -(print (+ 1 2 3)) ;; Returns 6 -``` - -### contract-call? -#### input: `ContractName, PublicFunctionName, Arg0, ...` -#### output: `(response A B)` -#### signature: `(contract-call? .contract-name function-name arg0 arg1 ...)` -#### description: -The `contract-call?` function executes the given public function of the given contract. You _may not_ use this function to call a public function defined in the current contract. If the public function returns _err_, any database changes resulting from calling `contract-call?` are aborted. If the function returns _ok_, database changes occurred. -#### example: -```clarity - -;; instantiate the sample-contracts/tokens.clar contract first! -(as-contract (contract-call? .tokens mint! u19)) ;; Returns (ok u19) -``` - -### as-contract -#### input: `A` -#### output: `A` -#### signature: `(as-contract expr)` -#### description: -The `as-contract` function switches the current context's `tx-sender` value to the _contract's_ principal and executes `expr` with that context. It returns the resulting value of `expr`. -#### example: -```clarity -(as-contract tx-sender) ;; Returns S1G2081040G2081040G2081040G208105NK8PE5.docs-test -``` - -### contract-of -#### input: `Trait` -#### output: `principal` -#### signature: `(contract-of .contract-name)` -#### description: -The `contract-of` function returns the principal of the contract implementing the trait. -#### example: -```clarity -(use-trait token-a-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) -(define-public (forward-get-balance (user principal) (contract )) - (begin - (ok (contract-of contract)))) ;; returns the principal of the contract implementing -``` - -### principal-of? -#### input: `(buff 33)` -#### output: `(response principal uint)` -#### signature: `(principal-of? public-key)` -#### description: -The `principal-of?` function returns the principal derived from the provided public key. If the `public-key` is invalid, it will return the error code `(err u1).`. ` -#### example: -```clarity -(principal-of? 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns (ok ST1AW6EKPGT61SQ9FNVDS17RKNWT8ZP582VF9HSCP) -``` - -### at-block -#### input: `(buff 32), A` -#### output: `A` -#### signature: `(at-block id-block-hash expr)` -#### description: -The `at-block` function evaluates the expression `expr` _as if_ it were evaluated at the end of the block indicated by the _block-hash_ argument. The `expr` closure must be read-only. - -Note: The block identifying hash must be a hash returned by the `id-header-hash` block information property. This hash uniquely identifies Stacks blocks and is unique across Stacks forks. While the hash returned by `header-hash` is unique within the context of a single fork, it is not unique across Stacks forks. - -The function returns the result of evaluating `expr`. - -#### example: -```clarity -(define-data-var data int 1) -(at-block 0x0000000000000000000000000000000000000000000000000000000000000000 block-height) ;; Returns u0 -(at-block (get-block-info? id-header-hash 0) (var-get data)) ;; Throws NoSuchDataVariable because `data` wasn't initialized at block height 0 -``` - -### get-block-info? -#### input: `BlockInfoPropertyName, BlockHeightInt` -#### output: `(optional buff) | (optional uint)` -#### signature: `(get-block-info? prop-name block-height-expr)` -#### description: -The `get-block-info?` function fetches data for a block of the given block height. The value and type returned are determined by the specified `BlockInfoPropertyName`. If the provided `BlockHeightInt` does not correspond to an existing block prior to the current block, the function returns `none`. The currently available property names are `time`, `header-hash`, `burnchain-header-hash`, `id-header-hash`, `miner-address`, and `vrf-seed`. - -The `time` property returns an integer value of the block header time field. This is a Unix epoch timestamp in seconds which roughly corresponds to when the block was mined. **Warning**: this does not increase monotonically with each block and block times are accurate only to within two hours. See [BIP113](https://github.com/bitcoin/bips/blob/master/bip-0113.mediawiki) for more information. - -The `header-hash`, `burnchain-header-hash`, `id-header-hash`, and `vrf-seed` properties return a 32-byte buffer. - -The `miner-address` property returns a `principal` corresponding to the miner of the given block. - -The `id-header-hash` is the block identifier value that must be used as input to the `at-block` function. - -#### example: -```clarity -(get-block-info? time u0) ;; Returns (some u1557860301) -(get-block-info? header-hash u0) ;; Returns (some 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb) -(get-block-info? vrf-seed u0) ;; Returns (some 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4) -``` - -### err -#### input: `A` -#### output: `(response A B)` -#### signature: `(err value)` -#### description: -The `err` function constructs a response type from the input value. Use `err` for creating return values in public functions. An _err_ value indicates that any database changes during the processing of the function should be rolled back. -#### example: -```clarity -(err true) ;; Returns (err true) -``` - -### ok -#### input: `A` -#### output: `(response A B)` -#### signature: `(ok value)` -#### description: -The `ok` function constructs a response type from the input value. Use `ok` for creating return values in public functions. An _ok_ value indicates that any database changes during the processing of the function should materialize. -#### example: -```clarity -(ok 1) ;; Returns (ok 1) -``` - -### some -#### input: `A` -#### output: `(optional A)` -#### signature: `(some value)` -#### description: -The `some` function constructs a `optional` type from the input value. -#### example: -```clarity -(some 1) ;; Returns (some 1) -(is-none (some 2)) ;; Returns false -``` - -### default-to -#### input: `A, (optional A)` -#### output: `A` -#### signature: `(default-to default-value option-value)` -#### description: -The `default-to` function attempts to 'unpack' the second argument: if the argument is a `(some ...)` option, it returns the inner value of the option. If the second argument is a `(none)` value, `default-to` it returns the value of `default-value`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(default-to 0 (get id (map-get? names-map (tuple (name \"blockstack\"))))) ;; Returns 1337 -(default-to 0 (get id (map-get? names-map (tuple (name \"non-existant\"))))) ;; Returns 0 -``` - -### asserts! -#### input: `bool, C` -#### output: `bool` -#### signature: `(asserts! bool-expr thrown-value)` -#### description: -The `asserts!` function admits a boolean argument and asserts its evaluation: if bool-expr is `true`, `asserts!` returns `true` and proceeds in the program execution. If the supplied argument is returning a false value, `asserts!` _returns_ `thrown-value` and exits the current control-flow. -#### example: -```clarity -(asserts! (is-eq 1 1) (err 1)) ;; Returns true -``` - -### unwrap! -#### input: `(optional A) | (response A B), C` -#### output: `A` -#### signature: `(unwrap! option-input thrown-value)` -#### description: -The `unwrap!` function attempts to 'unpack' the first argument: if the argument is an option type, and the argument is a `(some ...)` option, `unwrap!` returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, `unwrap!` returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `(none)` value, `unwrap!` _returns_ `thrown-value` from the current function and exits the current control-flow. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(define-private (get-name-or-err (name (string-ascii 12))) - (let ((raw-name (unwrap! (map-get? names-map { name: name }) (err 1)))) - (ok raw-name))) - -(get-name-or-err \"blockstack\") ;; Returns (ok (tuple (id 1337))) -(get-name-or-err \"non-existant\") ;; Returns (err 1) -``` - -### unwrap-err! -#### input: `(response A B), C` -#### output: `B` -#### signature: `(unwrap-err! response-input thrown-value)` -#### description: -The `unwrap-err!` function attempts to 'unpack' the first argument: if the argument is an `(err ...)` response, `unwrap-err!` returns the inner value of the `err`. If the supplied argument is an `(ok ...)` value, `unwrap-err!` _returns_ `thrown-value` from the current function and exits the current control-flow. -#### example: -```clarity -(unwrap-err! (err 1) false) ;; Returns 1 -``` - -### unwrap-panic -#### input: `(optional A) | (response A B)` -#### output: `A` -#### signature: `(unwrap-panic option-input)` -#### description: -The `unwrap` function attempts to 'unpack' its argument: if the argument is an option type, and the argument is a `(some ...)` option, this function returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, it returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `(none)` value, `unwrap` throws a runtime error, aborting any further processing of the current transaction. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(unwrap-panic (map-get? names-map { name: \"blockstack\" })) ;; Returns (tuple (id 1337)) -(unwrap-panic (map-get? names-map { name: \"non-existant\" })) ;; Throws a runtime exception -``` - -### unwrap-err-panic -#### input: `(response A B)` -#### output: `B` -#### signature: `(unwrap-err-panic response-input)` -#### description: -The `unwrap-err` function attempts to 'unpack' the first argument: if the argument is an `(err ...)` response, `unwrap` returns the inner value of the `err`. If the supplied argument is an `(ok ...)` value, `unwrap-err` throws a runtime error, aborting any further processing of the current transaction. -#### example: -```clarity -(unwrap-err-panic (err 1)) ;; Returns 1 -(unwrap-err-panic (ok 1)) ;; Throws a runtime exception -``` - -### match -#### input: `(optional A) name expression expression | (response A B) name expression name expression` -#### output: `C` -#### signature: `(match opt-input some-binding-name some-branch none-branch) | -(match-resp input ok-binding-name ok-branch err-binding-name err-branch)` -#### description: -The `match` function is used to test and destructure optional and response types. - -If the `input` is an optional, it tests whether the provided `input` is a `some` or `none` option, and evaluates `some-branch` or `none-branch` in each respective case. - -Within the `some-branch`, the _contained value_ of the `input` argument is bound to the provided `some-binding-name` name. - -Only _one_ of the branches will be evaluated (similar to `if` statements). - -If the `input` is a response, it tests whether the provided `input` is an `ok` or `err` response type, and evaluates `ok-branch` or `err-branch` in each respective case. - -Within the `ok-branch`, the _contained ok value_ of the `input` argument is bound to the provided `ok-binding-name` name. - -Within the `err-branch`, the _contained err value_ of the `input` argument is bound to the provided `err-binding-name` name. - -Only _one_ of the branches will be evaluated (similar to `if` statements). - -Note: Type checking requires that the type of both the ok and err parts of the response object be determinable. For situations in which one of the parts of a response is untyped, you should use `unwrap-panic` or `unwrap-err-panic` instead of `match`. -#### example: -```clarity - -(define-private (add-10 (x (optional int))) - (match x - value (+ 10 value) - 10)) -(add-10 (some 5)) ;; Returns 15 -(add-10 none) ;; Returns 10 - -(define-private (add-or-pass-err (x (response int (string-ascii 10))) (to-add int)) - (match x - value (ok (+ to-add value)) - err-value (err err-value))) -(add-or-pass-err (ok 5) 20) ;; Returns (ok 25) -(add-or-pass-err (err \"ERROR\") 20) ;; Returns (err \"ERROR\") -``` - -### try! -#### input: `(optional A) | (response A B)` -#### output: `A` -#### signature: `(try! option-input)` -#### description: -The `try!` function attempts to 'unpack' the first argument: if the argument is an option type, and the argument is a `(some ...)` option, `try!` returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, `try!` returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `none` value, `try!` _returns_ either `none` or the `(err ...)` value from the current function and exits the current control-flow. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(try! (map-get? names-map { name: \"blockstack\" })) ;; Returns (tuple (id 1337)) -(define-private (checked-even (x int)) - (if (is-eq (mod x 2) 0) - (ok x) - (err false))) -(define-private (double-if-even (x int)) - (ok (* 2 (try! (checked-even x))))) -(double-if-even 10) ;; Returns (ok 20) -(double-if-even 3) ;; Returns (err false) -``` - -### is-ok -#### input: `(response A B)` -#### output: `bool` -#### signature: `(is-ok value)` -#### description: -`is-ok` tests a supplied response value, returning `true` if the response was `ok`, and `false` if it was an `err`. -#### example: -```clarity -(is-ok (ok 1)) ;; Returns true -(is-ok (err 1)) ;; Returns false -``` - -### is-none -#### input: `(optional A)` -#### output: `bool` -#### signature: `(is-none value)` -#### description: -`is-none` tests a supplied option value, returning `true` if the option value is `(none)`, and `false` if it is a `(some ...)`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(is-none (get id (map-get? names-map { name: \"blockstack\" }))) ;; Returns false -(is-none (get id (map-get? names-map { name: \"non-existant\" }))) ;; Returns true -``` - -### is-err -#### input: `(response A B)` -#### output: `bool` -#### signature: `(is-err value)` -#### description: -`is-err` tests a supplied response value, returning `true` if the response was an `err`, and `false` if it was an `ok`. -#### example: -```clarity -(is-err (ok 1)) ;; Returns false -(is-err (err 1)) ;; Returns true -``` - -### is-some -#### input: `(optional A)` -#### output: `bool` -#### signature: `(is-some value)` -#### description: -`is-some` tests a supplied option value, returning `true` if the option value is `(some ...)`, and `false` if it is a `none`. -#### example: -```clarity - -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(is-some (get id (map-get? names-map { name: \"blockstack\" }))) ;; Returns true -(is-some (get id (map-get? names-map { name: \"non-existant\" }))) ;; Returns false -``` - -### filter -#### input: `Function(A) -> bool, sequence_A` -#### output: `sequence_A` -#### signature: `(filter func sequence)` -#### description: -The `filter` function applies the input function `func` to each element of the input sequence, and returns the same sequence with any elements removed for which `func` returned `false`. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. ` -#### example: -```clarity - -(filter not (list true false true false)) ;; Returns (false false) -(define-private (is-a (char (string-utf8 1))) (is-eq char u\"a\")) -(filter is-a u\"acabd\") ;; Returns u\"aa\" -(define-private (is-zero (char (buff 1))) (is-eq char 0x00)) -(filter is-zero 0x00010002) ;; Returns 0x0000 -``` - -### ft-get-balance -#### input: `TokenName, principal` -#### output: `uint` -#### signature: `(ft-get-balance token-name principal)` -#### description: -`ft-get-balance` returns `token-name` balance of the principal `principal`. The token type must have been defined using `define-fungible-token`. -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-get-balance stackaroo 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns u100 -``` - -### nft-get-owner? -#### input: `AssetName, A` -#### output: `(optional principal)` -#### signature: `(nft-get-owner? asset-class asset-identifier)` -#### description: -`nft-get-owner?` returns the owner of an asset, identified by `asset-identifier`, or `none` if the asset does not exist. The asset type must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) -(nft-get-owner? stackaroo \"Roo\") ;; Returns (some SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) -(nft-get-owner? stackaroo \"Too\") ;; Returns none -``` - -### ft-transfer? -#### input: `TokenName, uint, principal, principal` -#### output: `(response bool uint)` -#### signature: `(ft-transfer? token-name amount sender recipient)` -#### description: -`ft-transfer?` is used to increase the token balance for the `recipient` principal for a token type defined using `define-fungible-token` by debiting the `sender` principal. In contrast to `stx-transfer?`, any user can transfer the assets. When used, relevant guards need to be added. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- amount to send is non-positive ` -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-transfer? stackaroo u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(ft-transfer? stackaroo u60 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u1) -``` - -### nft-transfer? -#### input: `AssetName, A, principal, principal` -#### output: `(response bool uint)` -#### signature: `(nft-transfer? asset-class asset-identifier sender recipient)` -#### description: -`nft-transfer?` is used to change the owner of an asset identified by `asset-identifier` from `sender` to `recipient`. The `asset-class` must have been defined by `define-non-fungible-token` and `asset-identifier` must be of the type specified in that definition. In contrast to `stx-transfer?`, any user can transfer the asset. When used, relevant guards need to be added. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not own the asset `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- asset identified by asset-identifier does not exist ` -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(nft-transfer? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(nft-transfer? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u1) -(nft-transfer? stackaroo \"Stacka\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u3) -``` - -### nft-mint? -#### input: `AssetName, A, principal` -#### output: `(response bool uint)` -#### signature: `(nft-mint? asset-class asset-identifier recipient)` -#### description: -`nft-mint?` is used to instantiate an asset and set that asset's owner to the `recipient` principal. The asset must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. - -If an asset identified by `asset-identifier` _already exists_, this function will return an error with the following error code: - -`(err u1)` - -Otherwise, on successfuly mint, it returns `(ok true)`. ` -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### ft-mint? -#### input: `TokenName, uint, principal` -#### output: `(response bool uint)` -#### signature: `(ft-mint? token-name amount recipient)` -#### description: -`ft-mint?` is used to increase the token balance for the `recipient` principal for a token type defined using `define-fungible-token`. The increased token balance is _not_ transfered from another principal, but rather minted. - -If a non-positive amount is provided to mint, this function returns `(err 1)`. Otherwise, on successfuly mint, it returns `(ok true)`. ` -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### ft-get-supply -#### input: `TokenName` -#### output: `uint` -#### signature: `(ft-get-supply token-name)` -#### description: -`ft-get-balance` returns `token-name` circulating supply. The token type must have been defined using `define-fungible-token`. -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-get-supply stackaroo) ;; Returns u100 -``` - -### ft-burn? -#### input: `TokenName, uint, principal` -#### output: `(response bool uint)` -#### signature: `(ft-burn? token-name amount sender)` -#### description: -`ft-burn?` is used to decrease the token balance for the `sender` principal for a token type defined using `define-fungible-token`. The decreased token balance is _not_ transfered to another principal, but rather destroyed, reducing the circulating supply. - -If a non-positive amount is provided to burn, this function returns `(err 1)`. Otherwise, on successfuly burn, it returns `(ok true)`. - -#### example: -```clarity - -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(ft-burn? stackaroo u50 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### nft-burn? -#### input: `AssetName, A, principal` -#### output: `(response bool uint)` -#### signature: `(nft-burn? asset-class asset-identifier recipient)` -#### description: -`nft-burn?` is used to burn an asset and remove that asset's owner from the `recipient` principal. The asset must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. - -If an asset identified by `asset-identifier` _doesn't exist_, this function will return an error with the following error code: - -`(err u1)` - -Otherwise, on successfuly burn, it returns `(ok true)`. ` -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(nft-burn? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### stx-get-balance -#### input: `principal` -#### output: `uint` -#### signature: `(stx-get-balance owner)` -#### description: -`stx-get-balance` is used to query the STX balance of the `owner` principal. - -This function returns the STX balance of the `owner` principal. In the event that the `owner` principal isn't materialized, it returns 0. - -#### example: -```clarity -(stx-get-balance 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns u0 -(stx-get-balance (as-contract tx-sender)) ;; Returns u1000 -``` - -### stx-transfer? -#### input: `uint, principal, principal` -#### output: `(response bool uint)` -#### signature: `(stx-transfer? amount sender recipient)` -#### description: -`stx-transfer?` is used to increase the STX balance for the `recipient` principal by debiting the `sender` principal. The `sender` principal _must_ be equal to the current context's `tx-sender`. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- amount to send is non-positive `(err u4)` -- the `sender` principal is not the current `tx-sender` - -#### example: -```clarity - -(as-contract - (stx-transfer? u60 tx-sender 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (ok true) -(as-contract - (stx-transfer? u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR tx-sender)) ;; Returns (err u4) -``` - -### stx-burn? -#### input: `uint, principal` -#### output: `(response bool uint)` -#### signature: `(stx-burn? amount sender)` -#### description: -`stx-burn?` debits the `sender` principal's STX holdings by `amount`, destroying the STX. The `sender` principal _must_ be equal to the current context's `tx-sender`. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u3)` -- amount to send is non-positive `(err u4)` -- the `sender` principal is not the current `tx-sender` - -#### example: -```clarity -(as-contract - (stx-burn? u60 tx-sender)) ;; Returns (ok true) -(as-contract - (stx-burn? u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (err u4) -``` - -### define-constant -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-constant name expression)` -#### description: -`define-constant` is used to define a private constant value in a smart contract. The expression passed into the definition is evaluated at contract launch, in the order that it is supplied in the contract. This can lead to undefined function or undefined variable errors in the event that a function or variable used in the expression has not been defined before the constant. - -Like other kinds of definition statements, `define-constant` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -#### example: -```clarity - -(define-constant four (+ 2 2)) -(+ 4 four) ;; Returns 8 -``` - -### define-private -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-private (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### description: -`define-private` is used to define _private_ functions for a smart contract. Private functions may not be called from other smart contracts, nor may they be invoked directly by users. Instead, these functions may only be invoked by other functions defined in the same smart contract. - -Like other kinds of definition statements, `define-private` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Private functions may return any type. -#### example: -```clarity -(define-private (max-of (i1 int) (i2 int)) - (if (> i1 i2) - i1 - i2)) -(max-of 4 6) ;; Returns 6 -``` - -### define-public -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-public (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### description: -`define-public` is used to define a _public_ function and transaction for a smart contract. Public functions are callable from other smart contracts and may be invoked directly by users by submitting a transaction to the Stacks blockchain. - -Like other kinds of definition statements, `define-public` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Public functions _must_ return a ResponseType (using either `ok` or `err`). Any datamap modifications performed by a public function is aborted if the function returns an `err` type. Public functions may be invoked by other contracts via `contract-call?`. -#### example: -```clarity -(define-public (hello-world (input int)) - (begin (print (+ 2 input)) - (ok input))) -``` - -### define-read-only -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-read-only (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### description: -`define-read-only` is used to define a _public read-only_ function for a smart contract. Such functions are callable from other smart contracts. - -Like other kinds of definition statements, `define-read-only` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Read-only functions may return any type. However, read-only functions may not perform any datamap modifications, or call any functions which perform such modifications. This is enforced both during type checks and during the execution of the function. Public read-only functions may be invoked by other contracts via `contract-call?`. -#### example: -```clarity -(define-read-only (just-return-one-hundred) - (* 10 10)) - ``` - -### define-map -#### input: `MapName, TypeDefinition, TypeDefinition` -#### output: `Not Applicable` -#### signature: `(define-map map-name key-type value-type)` -#### description: -`define-map` is used to define a new datamap for use in a smart contract. Such maps are only modifiable by the current smart contract. - -Maps are defined with a key type and value type, often these types are tuple types. - -Like other kinds of definition statements, `define-map` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). -#### example: -```clarity -(define-map squares { x: int } { square: int }) -(define-private (add-entry (x int)) - (map-insert squares { x: 2 } { square: (* x x) })) -(add-entry 1) -(add-entry 2) -(add-entry 3) -(add-entry 4) -(add-entry 5) -``` - -### define-data-var -#### input: `VarName, TypeDefinition, Value` -#### output: `Not Applicable` -#### signature: `(define-data-var var-name type value)` -#### description: -`define-data-var` is used to define a new persisted variable for use in a smart contract. Such variable are only modifiable by the current smart contract. - -Persisted variable are defined with a type and a value. - -Like other kinds of definition statements, `define-data-var` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). -#### example: -```clarity -(define-data-var size int 0) -(define-private (set-size (value int)) - (var-set size value)) -(set-size 1) -(set-size 2) -``` - -### define-fungible-token -#### input: `TokenName, ` -#### output: `Not Applicable` -#### signature: `(define-fungible-token token-name )` -#### description: -`define-fungible-token` is used to define a new fungible token class for use in the current contract. - -The second argument, if supplied, defines the total supply of the fungible token. This ensures that all calls to the `ft-mint?` function will never be able to create more than `total-supply` tokens. If any such call were to increase the total supply of tokens passed that amount, that invocation of `ft-mint?` will result in a runtime error and abort. - -Like other kinds of definition statements, `define-fungible-token` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Tokens defined using `define-fungible-token` may be used in `ft-transfer?`, `ft-mint?`, and `ft-get-balance` functions` -#### example: -```clarity -(define-fungible-token stacks) -(define-fungible-token limited-supply-stacks u100) -``` - -### define-non-fungible-token -#### input: `AssetName, TypeSignature` -#### output: `Not Applicable` -#### signature: `(define-non-fungible-token asset-name asset-identifier-type)` -#### description: -`define-non-fungible-token` is used to define a new non-fungible token class for use in the current contract. Individual assets are identified by their asset identifier, which must be of the type `asset-identifier-type`. Asset identifiers are _unique_ identifiers. - -Like other kinds of definition statements, `define-non-fungible-token` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Assets defined using `define-non-fungible-token` may be used in `nft-transfer?`, `nft-mint?`, and `nft-get-owner?` functions` -#### example: -```clarity -(define-non-fungible-token names (buff 50)) -``` - -### define-trait -#### input: `VarName, [MethodSignature]` -#### output: `Not Applicable` -#### signature: `(define-trait trait-name ((func1-name (arg1-type arg2-type ...) (return-type))))` -#### description: -`define-trait` is used to define a new trait definition for use in a smart contract. Other contracts can implement a given trait and then have their contract identifier being passed as function arguments in order to be called dynamically with `contract-call?`. - -Traits are defined with a name, and a list functions defined with a name, a list of argument types, and return type. - -Like other kinds of definition statements, `define-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -#### example: -```clarity -(define-trait token-trait - ((transfer? (principal principal uint) (response uint uint)) - (get-balance (principal) (response uint uint)))) -``` - -### use-trait -#### input: `VarName, TraitIdentifier` -#### output: `Not Applicable` -#### signature: `(use-trait trait-alias trait-identifier)` -#### description: -`use-trait` is used to bring a trait, defined in another contract, to the current contract. Subsequent references to an imported trait are signaled with the syntax ``. - -Traits import are defined with a name, used as an alias, and a trait identifier. Trait identifiers can either be using the sugared syntax (.token-a.token-trait), or be fully qualified ('SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait). - -Like other kinds of definition statements, `use-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put such a statement in the middle of a function body). -#### example: -```clarity -(use-trait token-a-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) -(define-public (forward-get-balance (user principal) (contract )) - (begin - (ok 1))) -``` - -### impl-trait -#### input: `TraitIdentifier` -#### output: `Not Applicable` -#### signature: `(impl-trait trait-identifier)` -#### description: -`impl-trait` can be use for asserting that a contract is fully implementing a given trait. Additional checks are being performed when the contract is being published, rejecting the deployment if the contract is violating the trait specification. - -Trait identifiers can either be using the sugared syntax (.token-a.token-trait), or be fully qualified ('SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait). - -Like other kinds of definition statements, `impl-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put such a statement in the middle of a function body). - -#### example: -```clarity -(impl-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) (define-public (get-balance (account principal)) (ok u0)) (define-public (transfer? (from principal) (to principal) (amount uint)) - (ok u0)) -``` \ No newline at end of file diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md b/i18n/pt/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md deleted file mode 100644 index fd62451198..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Keywords -description: See a detailed list of all keywords for the Clarity language. -tags: - - clarity ---- - -![](/img/keywords.jpg) -## Keyword reference - -Detailed list of all keywords for the Clarity language. - - -### contract-caller -#### output: `principal` -#### description: -Returns the caller of the current contract context. If this contract is the first one called by a signed transaction, the caller will be equal to the signing principal. If `contract-call?` was used to invoke a function from a new contract, `contract-caller` changes to the _calling_ contract's principal. If `as-contract` is used to change the `tx-sender` context, `contract-caller` _also_ changes to the same contract principal. -#### example: -```clarity -(print contract-caller) ;; Will print out a Stacks address of the transaction sender -``` - -### tx-sender -#### output: `principal` -#### description: -Returns the original sender of the current transaction, or if `as-contract` was called to modify the sending context, it returns that contract principal. -#### example: -```clarity -(print tx-sender) ;; Will print out a Stacks address of the transaction sender -``` - -### block-height -#### output: `uint` -#### description: -Returns the current block height of the Stacks blockchain as an uint -#### example: -```clarity -(> block-height 1000) ;; returns true if the current block-height has passed 1000 blocks. -``` - -### burn-block-height -#### output: `uint` -#### description: -Returns the current block height of the underlying burn blockchain as a uint -#### example: -```clarity -(> burn-block-height 1000) ;; returns true if the current height of the underlying burn blockchain has passed 1000 blocks. -``` - -### none -#### output: `(optional ?)` -#### description: -Represents the _none_ option indicating no value for a given optional (analogous to a null value). -#### example: -```clarity -(define-public (only-if-positive (a int)) - (if (> a 0) - (some a) - none)) -(only-if-positive 4) ;; Returns (some 4) -(only-if-positive (- 3)) ;; Returns none -``` - -### true -#### output: `bool` -#### description: -Boolean true constant. -#### example: -```clarity -(and true false) ;; Evaluates to false -(or false true) ;; Evaluates to true -``` - -### false -#### output: `bool` -#### description: -Boolean false constant. -#### example: -```clarity -(and true false) ;; Evaluates to false -(or false true) ;; Evaluates to true -``` - -### stx-liquid-supply -#### output: `uint` -#### description: -Returns the total number of micro-STX (uSTX) that are liquid in the system as of this block. -#### example: -```clarity -(print stx-liquid-supply) ;; Will print out the total number of liquid uSTX -``` - -### is-in-regtest -#### output: `bool` -#### description: -Returns whether or not the code is running in a regression test -#### example: -```clarity -(print is-in-regtest) ;; Will print 'true' if the code is running in a regression test -``` - diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md b/i18n/pt/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md deleted file mode 100644 index d22f991413..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Types -description: See a detailed list of all types for the Clarity language. -tags: - - clarity ---- - -## Clarity Type System - -The type system contains the following types: - -| Types | Notes | -| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `int` | signed 128-bit integer | -| `uint` | unsigned 128-bit integer | -| `bool` | boolean value (`true` or `false`) | -| `principal` | object representing a principal (whether a contract principal or standard principal) | -| `(buff max-len)` | byte buffer of 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` (u"A smiley face emoji \u{1F600} as a utf8 string") | -| `(list max-len entry-type)` | list of maximum length `max-len`, with entries of type `entry-type` | -| `{label-0: value-type-0, label-1: value-type-1, ...}` | tuple, group of data values with named fields | -| `(optional some-type)` | an option type for objects that can either be `(some value)` or `none` | -| `(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. | diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md b/i18n/pt/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md deleted file mode 100644 index e75e1d69b9..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Clarity overview -description: Overview and guides for getting started with Clarity -sidebar_label: Write smart contracts -sidebar_position: 2 ---- - -## Introduction - -Clarity is a **decidable** smart contract language that optimizes for predictability and security, designed for the Stacks blockchain. Smart contracts allow developers to encode essential business logic on a blockchain. - -## Smart contracts - -Smart contracts encode and enforce rules for modifying a particular set of data that is shared among people and entities who don't necessarily trust each other. For example, a smart contract can hold funds in escrow until multiple parties agree to release them, create its own ledger and keep track of its own novel tokens (fungible or non-fungible), and even help make supply chains more transparent. - -A smart contract execution can result in new transactions being written to the blockchain. Because smart contracts are programs that exist in a blockchain, anyone can query them, and anyone can submit transactions to execute them. - -Apps can take advantage of smart contracts to manage a global state that is visible to the public. Anyone can audit the blockchain to independently verify that an app's global shared state has been managed correctly according to the smart contract's rules. - -There is a [Clarity Visual Studio Code plugin][] available for syntax assistance and debugging. - -## Use cases - -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 (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 - -## Language design - -Clarity differs from most other smart contract languages in two essential ways: - -- The language is interpreted and broadcast on the blockchain as is (not compiled) -- The language is decidable (not Turing complete) - -Using an interpreted language ensures that the executed code is human-readable and auditable. A decidable language like Clarity makes it possible to determine precisely which code is executed, for any function. - -A Clarity smart contract consists of two parts, a data space and a set of functions. Only the associated smart contract may modify its corresponding data space on the blockchain. Functions may be private and thus callable only from within the smart contract, or public and thus callable from other contracts. Users call smart contracts' public functions by broadcasting a transaction on the blockchain which invokes the public function. Contracts can also call public functions from other smart contracts. - -Note some of the key Clarity language rules and limitations. - -- The only primitive types are booleans, integers, buffers, and principals. -- Recursion is illegal and there are no anonymous functions. -- Looping is only performed via `map`, `filter`, or `fold`. -- There is support for lists, however, the only variable length lists in the language appear as function inputs; there is no support for list operations like append or join. -- Variables are immutable. - -## Explore more - -For language details and references, see the following: - -- [Clarity language overview](./clarity-language/) -- [Understating Principals](principals) -- [Clarity Values](values) - -[Clarity Visual Studio Code plugin]: https://marketplace.visualstudio.com/items?itemName=HiroSystems.clarity-lsp diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md b/i18n/pt/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md deleted file mode 100644 index 2305d10d9d..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md +++ /dev/null @@ -1,244 +0,0 @@ ---- -title: Principals -description: 'Clarity: Understanding Principals' -sidebar_position: 1 ---- - -## Introduction - -_Principals_ are a Clarity native type that represents an entity that can have a token balance. This section discusses principals and how they are used in the Clarity. - -## Principals and tx-sender - -Assets in the smart contracting language and blockchain are "owned" by objects of the principal type, meaning that any object of the principal type may own an asset. For the case of public-key hash and multi-signature Stacks addresses, a given principal can operate on their assets by issuing a signed transaction on the blockchain. _Smart contracts_ may also be principals (represented by the smart contract's identifier), however, there is no private key associated with the smart contract, and it cannot broadcast a signed transaction on the blockchain. - -A Clarity contract can use a globally defined `tx-sender` variable to obtain the current principal. The following example defines a transaction type that transfers `amount` microSTX from the sender to a recipient if amount is a multiple of 10, otherwise returning a 400 error code. - -```clarity -(define-public (transfer-to-recipient! (recipient principal) (amount uint)) - (if (is-eq (mod amount 10) 0) - (stx-transfer? amount tx-sender recipient) - (err u400))) -``` - -Clarity provides an additional variable to help smart contracts authenticate a transaction sender. The keyword `contract-caller` returns the principal that _called_ the current contract. If an inter-contract call occurred, `contract-caller` returns the last contract in the stack of callers. For example, suppose there are three contracts A, B, and C, each with an `invoke` function such that `A::invoke` calls `B::invoke` and `B::invoke` calls `C::invoke`. - -When a user Bob issues a transaction that calls `A::invoke`, the value of `contract-caller` in each successive invoke function's body would change: - -```clarity -in A::invoke, contract-caller = Bob -in B::invoke, contract-caller = A -in C::invoke, contract-caller = B -``` - -This allows contracts to make assertions and perform authorization checks using not only the `tx-sender` (which in this example, would always be "Bob"), but also using the `contract-caller`. This could be used to ensure that a particular function is only ever called directly and never called via an inter-contract call (by asserting that `tx-sender` and `contract-caller` are equal). We provide an example of a two different types of authorization checks in the rocket ship example below. - -## Smart contracts as principals - -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, for example: - -```clarity -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-name -``` - -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 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 qualified identifier for the contracts would be: - -```clarity -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-A -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-B -``` - -But, in the contract source code, if the developer wishes to call a function from `contract-A` in `contract-B`, they can write - -```clarity -(contract-call? .contract-A public-function-foo) -``` - -This allows the smart contract developer to modularize their applications across multiple smart contracts _without_ knowing the publishing key a priori. - -In order for a smart contract to operate on assets it owns, smart contracts may use the special `(as-contract ...)` function. This function executes the expression (passed as an argument) with the `tx-sender` set to the contract's principal, rather than the current sender. The `as-contract` function returns the value of the provided expression. - -For example, a smart contract that implements something like a "token faucet" could be implemented as so: - -```clarity -(define-map claimed-before - ((sender principal)) - ((claimed bool))) - -(define-constant err-already-claimed u1) -(define-constant err-faucet-empty u2) -(define-constant stx-amount u1) - -(define-public (claim-from-faucet) - (let ((requester tx-sender)) ;; set a local variable requester = tx-sender - (asserts! (is-none (map-get? claimed-before {sender: requester})) (err err-already-claimed)) - (unwrap! (as-contract (stx-transfer? stx-amount tx-sender requester)) (err err-faucet-empty)) - (map-set claimed-before {sender: requester} {claimed: true}) - (ok stx-amount))) -``` - -In this example, the public function `claim-from-faucet`: - -- Checks if the sender has claimed from the faucet before. -- Assigns the tx sender to a `requester` variable. -- Adds an entry to the tracking map. -- Uses `as-contract` to send 1 microstack - -Unlike other principals, there is no private key associated with a smart contract. As it lacks a private key, a Clarity smart contract cannot broadcast a signed transaction on the blockchain. - -## Example: Authorization checks - -The interactions between `tx-sender`, `contract-caller` and `as-contract` are subtle, but are important when performing authorization checks in a contract. In this example contract, we'll show two different kinds of authorization checks a contract may wish to perform, and then walk through how different ways in which contract functions may be called will pass or fail those checks. - -This contract defines a "rocket-ship" non-fungible-token that a principal may own and manage the authorized pilots. Pilots are principals that are allowed to "fly" the rocket ship. - -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. -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 be called _directly_ by the ship's owner, rather than through a inter-contract-call. - -The second type of check is more restrictive than the first check, and is helpful for guarding very sensitive routines --- it protects users from unknowingly calling a function on a malicious contract that subsequently tries to call sensitive functions on another contract. - -```clarity -;; -;; rockets-base.clar -;; - -(define-non-fungible-token rocket-ship uint) - -;; a map from rocket ships to their allowed -;; pilots -(define-map allowed-pilots - ((rocket-ship uint)) ((pilots (list 10 principal)))) - -;; implementing a contains function via fold -(define-private (contains-check - (y principal) - (to-check { p: principal, result: bool })) - (if (get result to-check) - to-check - { p: (get p to-check), - result: (is-eq (get p to-check) y) })) - -(define-private (contains (x principal) (find-in (list 10 principal))) - (get result (fold contains-check find-in - { p: x, result: false }))) - -(define-read-only (is-my-ship (ship uint)) - (is-eq (some tx-sender) (nft-get-owner? rocket-ship ship))) - -;; this function will print a message -;; (and emit an event) if the tx-sender was -;; an authorized flyer. -;; -;; here we use tx-sender, because we want -;; to allow the user to let other contracts -;; fly the ship on behalf of users - -(define-public (fly-ship (ship uint)) - (let ((pilots (default-to - (list) - (get pilots (map-get? allowed-pilots { rocket-ship: ship }))))) - (if (contains tx-sender pilots) - (begin (print "Flew the rocket-ship!") - (ok true)) - (begin (print "Tried to fly without permission!") - (ok false))))) -;; -;; Authorize a new pilot. - (ok true)) - (begin (print "Tried to fly without permission!") - (ok false))))) -;; -;; Authorize a new pilot. - (ok false))))) -;; -;; Authorize a new pilot. -;; -;; here we want to ensure that this function -;; was called _directly_ by the user by -;; checking that tx-sender and contract-caller are equal. -;; if any other contract is in the call stack, contract-caller -;; would be updated to a different principal. -;; -(define-public (authorize-pilot (ship uint) (pilot principal)) - (begin - ;; sender must equal caller: an intermediate contract is - ;; not issuing this call. - (asserts! (is-eq tx-sender contract-caller) (err u1)) - ;; sender must own the rocket ship - (asserts! (is-eq (some tx-sender) - (nft-get-owner? rocket-ship ship)) (err u2)) - (let ((prev-pilots (default-to - (list) - (get pilots (map-get? allowed-pilots { rocket-ship: ship }))))) - ;; don't add a pilot already in the list - (asserts! (not (contains pilot prev-pilots)) (err u3)) - ;; append to the list, and check that it is less than - ;; the allowed maximum - (match (as-max-len? (append prev-pilots pilot) u10) - next-pilots - (ok (map-set allowed-pilots {rocket-ship: ship} {pilots: next-pilots})) - ;; too many pilots already - (err u4))))) -``` - -### Extending functionality: Multi-flyer contract - -The authorization scheme for `fly-ship` allows pilots to fly rocket-ships from other contracts. This allows other contracts to provide new functionality built around calling that function. - -For example, we can create a contract that calls `fly-ship` for multiple rocket-ships in a single transaction: - -```clarity -;; -;; rockets-multi.clar -;; - -(define-private (call-fly (ship uint)) - (unwrap! (contract-call? .rockets-base fly-ship ship) false)) -;; try to fly all the ships, returning a list of whether -;; or not we were able to fly the supplied ships -(define-public (fly-all (ships (list 10 uint))) - (ok (map call-fly ships))) -``` - -### Authorization for Contract-Owned Assets - -The check in `authorize-pilot` protects users from malicious contracts, but how would such a scheme support contract-owned assets? This is what the `as-contract` function is used for. The `as-contract` function executes the supplied closure as if the sender of the transaction was the current contract, rather than the user -- it does this by updating `tx-sender` to the current contract principal. We can use this to, for example, create a smart contract rocket-ship-line: - -```clarity -;; -;; rockets-ship-line.clar -;; - -(define-constant line-ceo 'SP19Y6GRV9X778VFS1V8WT2H502WFK33XZXADJWZ) - -(define-data-var employed-pilots (list 10 principal) (list)) - -;; This function will: -;; * check that it is called by the line-ceo -;; * check that the rocket is owned by the contract -;; * authorize each employed pilot to the ship -(define-public (add-managed-rocket (ship uint)) - (begin - ;; 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 - (asserts! (contract-call? .rockets-base is-my-ship ship) (err u2)) - ;; register all of our pilots on the ship - (add-pilots-to ship))))) - -;; add all the pilots to a ship using fold -- -;; the fold checks the return type of previous calls, -;; skipping subsequent contract-calls if one fails. -(define-private (add-pilot-via-fold (pilot principal) (prior-result (response uint uint))) - (let ((ship (try! prior-result))) - (try! (contract-call? .rockets-base authorize-pilot ship pilot)) - (ok ship))) -(define-private (add-pilots-to (ship uint)) - (fold add-pilot-via-fold (var-get employed-pilots) (ok ship))) -``` - -In order for the contract to add each pilot to a new ship, the contract must call `authorize-pilot`. However, the contract wants to perform this action on behalf of a ship the _contract_ owns, not the transaction sender. To do this, the contract uses `as-contract`. diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md b/i18n/pt/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md deleted file mode 100644 index a01e37bc04..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Resources -description: 'Resources' -sidebar_position: 8 ---- - -# External resources - - -[Clarity book](https://book.clarity-lang.org/) - -[Clarity Universe](https://stacks.org/clarity-universe) - -[Hiro Clarity tutorials](https://docs.hiro.so/tutorials) diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md b/i18n/pt/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md deleted file mode 100644 index ed65829518..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Clarity development software -description: The following tools are useful when developing Clarity smart contracts -sidebar_position: 4 ---- - -## Language Server Protocol for Clarity (including Visual Studio Code extension) - -The Language Server Protocol (LSP) defines the protocol used between an editor or IDE and a language server that provides language features like auto complete, go to definition, find all references etc. - -This makes programming in Clarity easier and much more intuitive. - -![Clarity LSP Screenshot](https://raw.githubusercontent.com/hirosystems/clarity-lsp/21b64298ca117dc41358eb9dce4605cc4a448a4c/images/screenshot.png?raw=true) - - -Clarity LSP repository is available [here](https://github.com/hirosystems/clarity-lsp). The extension for Visual Studio Code can be downloaded directly from [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=HiroSystems.clarity-lsp), but can be and older version. For a more up to date version you can also download it from [open-vsx](https://open-vsx.org/extension/hirosystems/clarity-lsp). - -## Clarity REPL - -A read—eval—print loop (REPL), also termed an interactive toplevel or language shell, is a simple, interactive computer programming environment that takes single user inputs (that is, single expressions), evaluates (executes) them, and returns the result to the user; a program written in a REPL environment is executed piecewise. - -![Clarity-repl](https://github.com/hirosystems/clarity-repl/blob/develop/docs/images/screenshot.png?raw=true) - -Instructions on how to install Clarity REPL can be found [here](https://github.com/hirosystems/clarity-repl). - -## Clarinet - -Clarinet is a Clarity runtime packaged as a command line tool, designed to facilitate smart contract understanding, development, testing and deployment. Clarinet consists of a Clarity REPL and a testing harness, which, when used together allow you to rapidly develop and test a Clarity smart contract, with the need to deploy the contract to a local devnet or testnet. - -![Clarinet](https://github.com/hirosystems/clarinet/blob/develop/docs/images/demo.gif?raw=true) - -Installation instructions, including build from source instructions can be found [here](https://github.com/hirosystems/clarinet). If you prefer you can directly download the latest compiled realease for Windows, Mac and Linux [here](https://github.com/hirosystems/clarinet/releases). - -[Clarinet 101](https://www.youtube.com/playlist?list=PL5Ujm489LoJaAz9kUJm8lYUWdGJ2AnQTb) contains multiple Clarinet video tutorials - -### Getting started with Clarinet - -You can verify you have Clarinet installed by checking its version: - -```bash -$ clarinet --version -clarinet 0.70 -``` - -More detailed information on using Clarinet is available [here](https://book.clarity-lang.org/ch07-00-using-clarinet.html). However to get you started, the following commands are important to know. - -Create a new project and enter its directory: - -```bash -clarinet new my-project && cd my-project -``` - -Create a new contract inside `my-project`: - -```bash -clarinet contract new mycoolcontract -``` - -Check the syntax of Clarity: - -```bash -clarity check -``` - -To test your contract: - -```bash -clarinet test -``` - -Enter Clarinet's console: - -```bash -clarinet console -``` diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md b/i18n/pt/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md deleted file mode 100644 index f9e1a16eb7..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Tokens -description: Learn about token support within Clarity -sidebar_position: 3 ---- - -## Introduction - -A fundamental use of blockchain technology is the representation, store, and transfer of value between users of a blockchain. Cryptocurrency is a very common use of blockchain technology, and remains one of the primary drivers of adoption of blockchain technology. Cryptocurrencies are represented by blockchain tokens: individual units of value within a given blockchain ecosystem. Blockchain tokens can extend beyond just digital currency, however, and recent developments throughout the cryptocurrency community have demonstrated potential for the use of blockchain to tokenize and represent not just money but other tangible assets. - -A blockchain token is a digital asset that can be verifiably owned by a user of a blockchain. Blockchain tokens are governed by a set of rules that are defined by either the blockchain itself (in the case of native tokens) or by a smart contract on a blockchain. Rules can vary depending on the nature and the use of the token. - -Tokens on a blockchain fall into two general categories, depending on their properties: [fungible][] or [non-fungible][]. The following sections discuss the properties of both types of tokens, and provide information about implementation of the two types of tokens on Stacks. - -## Fungible tokens - -A core property of any token on a blockchain is fungibility. A fungible token is a token that's mutually interchangable or capable of mutual substitution. In other words, one quantity or part of a fungible token can be replaced by an equal quantity or part of the same fungible token. Fungible tokens are often used to represent real-world fungible assets like currency. The STX token is an example of a fungible token. Other examples include stablecoins, tokens that represent voting rights in a DAO, or tokens that algorithmically track the price of stocks. - -Fungible tokens form one of the most important value propositions for blockchain technology, the ability to store value and exchange that value through both internal and external transactions. Because fungible tokens can be divided into smaller parts and recombined into the same value representation, they serve a great utility for transferring value between blockchain users. - -The primary fungible token on the Stacks blockchain is the native token, STX. Because the Stacks blockchain allows for the creation of \[smart contracts\]\[\], other fungible tokens can be created on the Stacks blockchain as well. [SIP-010][] specifies the standard for fungible tokens on the Stacks blockchain. This specification defines the functions and traits that a fungible token on Stacks _must_ have. This specification defines the functions and traits that a fungible token on Stacks _must_ have. - -### Understanding the fungible token standard - -The [SIP-010][] standard is an interface definition that allows Stacks applications and wallets to interact with fungible tokens in a standard way. Supporting the standard reduces complexity for token creators to get their tokens into the ecosystem. Under the [SIP-010][] standard, fungible tokens must have the following characteristics: - -- Ability to transfer a specified amount of the token to a recipient (`transfer`). The recipient is required to be a Stacks principal. -- Ability to obtain the human-readable name of the token (`get-name`). -- Ability to obtain a short name (ticker symbol) for the token (`get-symbol`). -- Ability to get the number of decimals in the token representation (`get-decimals`). This is used to construct a representation of the token that humans would be familiar dealing with. For example, the US dollar has 2 decimals, if the base unit is cents. -- Ability to get the balance of the token for a particular Stacks principal (`get-balance-of`). -- Ability to get the total supply of the token (`get-total-supply`). -- A URI to metadata associated with the token (`get-token-uri`). This can resolve to off-chain metadata about the token or contract, such as an image icon for the token or a description. - -## Non-fungible tokens (NFTs) - -Non-fungible tokens (NFTs) are a type of token that are not interchangeable. NFTs have unique traits (usually in the form of attached metadata) that restrict the abillity to replace them with identical tokens. An NFT is a token that is unique, such as a piece of art, or ownership rights to a real-world asset such as a house. - -NFTs alone don't have an inherent value, like a currency. The value of an NFT is derived from the assets that the NFT represents. The use of NFTs are myriad, including digital art, collectibles, domain names, and representation of ownership of content rights. NFTs can be used as digital certificates that track the authenticty of real world items, or digitize the ownership rights to property. - -As with fungible tokens, NFTs on the Stacks blockchain are created with smart contracts. [SIP-009][] specifies the standard for NFTs on the Stacks blockchain. This specification defines the functions and traits that an NFT _must_ have, but most NFTs have more functions or traits attached than those solely described by the specification. By complying with this standard, non-fungible tokens on Stacks can be easily represented by wallets that support Stacks. - -### Understanding the non-fungible token standard - -The [SIP-009][] standard is an interface definition that the Stacks ecosystem aligned on. With support for this standard across wallets and tools, it becomes easy to interact with NFTs. Under the [SIP-009][] standard, NFT contract must have the following characteristics: - -- Ability to obtain the last token identifier (`get-last-token-id`). This id represents the upper limit of NFTs issued by the contract. -- A URI to metadata associated with a specific token identifier. (`get-token-uri`). This URI could resolve to a JSON file with information about the creator, associated media files, descriptions, signatures, and more. -- Ability to verify the owner for a given token identifier (`get-owner`). The owner resolves to a [Stacks principal](principals). -- Ability to transfer an NFT to a recipient (`transfer`). The recipient is required to be a Stacks principal. - -## Further reading - -- [The Difference Between Fungible and Non-Fungible Tokens](https://101blockchains.com/fungible-vs-non-fungible-tokens/) -- [Explain It Like I Am 5: NFTs](https://messari.io/article/explain-it-like-i-am-5-nfts) - -[fungible]: #fungible-tokens -[non-fungible]: #non-fungible-tokens-nfts -[SIP-010]: https://github.com/stacksgov/sips/blob/main/sips/sip-010/sip-010-fungible-token-standard.md -[SIP-010]: https://github.com/hstove/sips/blob/feat/sip-10-ft/sips/sip-010/sip-010-fungible-token-standard.md -[SIP-009]: https://github.com/stacksgov/sips/blob/main/sips/sip-009/sip-009-nft-standard.md diff --git a/i18n/pt/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md b/i18n/pt/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md deleted file mode 100644 index 54f44c759f..0000000000 --- a/i18n/pt/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md +++ /dev/null @@ -1,301 +0,0 @@ ---- -title: Clarity Values -description: Learn how to deal with Clarity Values in JavaScript -sidebar_position: 2 ---- - -## Introduction - -The Clarity language makes use of a strong static 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/hirosystems/stacks.js/tree/master/packages/transactions) library makes this easy, as we will demonstrate below. - -## Clarity Types - -Please see the following page for information on [Clarity Types](../write-smart-contracts/clarity-language/language-types). - -## Constructing Clarity Values and accessing their data - -Clarity values can be constructed with functions provided by the [@stacks/transactions](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library. These functions simply output javascript objects that contain a value and a numerical representation of the Clarity type information. The Clarity types are encoded as follows: - -```typescript -export enum ClarityType { - Int = 0, - UInt = 1, - Buffer = 2, - BoolTrue = 3, - BoolFalse = 4, - PrincipalStandard = 5, - PrincipalContract = 6, - ResponseOk = 7, - ResponseErr = 8, - OptionalNone = 9, - OptionalSome = 10, - List = 11, - Tuple = 12, - StringASCII = 13, - StringUTF8 = 14, -} -``` - -`ClarityValue` objects can be serialized and included in transactions that interact with published Clarity contracts. - -Here are examples of how to construct each type of Clarity value, and how to access its data if it has any: - -### Booleans - -```typescript -const t = trueCV(); -// { type: ClarityType. BoolTrue } - -const f = falseCV(); -// { type: ClarityType. BoolFalse } -``` - -Boolean Clarity Values don't contain any underlying data. They are simply objects with `type` information. - -### Optional Values - -```typescript -const nothing: NoneCV = noneCV(); -// { type: ClarityType. OptionalNone } - -const something: SomeCV = someCV(trueCV()); -// { type: ClarityType. OptionalSome, value: { type: 4 } } -``` - -Optional Clarity Values can either be nothing (an empty type that has no data), or something (a wrapped value). - -If you are dealing with a function or contract function that returns an `OptionalCV`, you should always check what type it is before trying to access its value. - -```typescript -const maybeVal: OptionalCV = await callReadOnlyFunction(...); - -if (maybeVal.type === ClarityType. OptionalSome) { - console.log(maybeVal.value); -} else if (maybeVal.type === ClarityType. OptionalNone) { - // deal with `none` value -} -``` - -### Buffers - -```typescript -const buffer = Buffer.from('foo'); -const bufCV: BufferCV = bufferCV(buffer); -// { type: ClarityType. Buffer, buffer: } -``` - -### Integers - -Clarity supports both integers and unsigned integers. - -```typescript -const i: IntCV = intCV(-10); -// { type: ClarityType. Int, value: BN { ... } } - -const u: UIntCV = uintCV(10); -// { type: ClarityType.UInt, value: BN { ... } } -``` - -Clarity value ints store their underlying data as `BigNum` values from the [bn.js](https://github.com/indutny/bn.js/) library. - -In order to display/print Clarity (u)int values, use the `cvToString(val)` method. - -If you wish to perform arithmetic operations using Clarity (u)int values, you must use methods from the `BigNum` api on their underlying `BigNum` values, and the construct a new Clarity value out of the result. For example: - -```typescript -const x = intCV(1); -const y = intCV(2); - -x.value.add(y.value); -// 3 -``` - -### Strings - -```typescript -const ascii: StringAsciiCV = stringAsciiCV('hello world'); -// { type: ClarityType. StringASCII, data: 'hello world' } - -const utf8: StringUtf8CV = stringUtf8CV('hello 🌾'); -// { type: ClarityType. StringUTF8, data: 'hello 🌾' } -``` - -Clarity supports both ascii and utf8 strings. - -### Principals - -```typescript -const address = 'SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B'; -const contractName = 'contract-name'; - -const spCV = standardPrincipalCV(address); -// { -// type: ClarityType. PrincipalStandard -// address: { -// type: StacksMessageType. Address, -// version: AddressVersion. MainnetSingleSig, -// hash160: "SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B" -// } -// } - -const cpCV = contractPrincipalCV(address, contractName); -// { -// type: ClarityType. PrincipalContract, -// contractName: { -// type: StacksMessageType. LengthPrefixedString, -// content: 'contract-name', -// lengthPrefixBytes: 1, -// maxLengthBytes: 128, -// }, -// address: { -// type: StacksMessageType. Address, -// version: AddressVersion. MainnetSingleSig, -// hash160: "SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B" -// } -// } -``` - -Both kinds of Clarity principal values contain `type` information and an `address` object. Contract principals also contain a `contractName`. - -### Response Values - -```typescript -const errCV = responseErrorCV(trueCV()); -// { type: ResponseErr, value: { type: ClarityType. BoolTrue } } - -const okCV = responseOkCV(falseCV()); -// { type: ResponseOk, value: { type: ClarityType. BoolFalse } } -``` - -Response Clarity Values will either have the type `ClarityType. ResponseOk` or `ClarityType. ResponseErr`. They both contain a Clarity Value. Often this value will be an integer error code if the response is an `Error`. - -### Tuples - -```typescript -const tupCV = tupleCV({ - a: intCV(1), - b: trueCV(), - c: falseCV(), -}); -// { -// type: ClarityType. Tuple, -// data: { -// a: { type: ClarityType. Int, value: BN { ... } }, -// b: { type: ClarityType. BoolTrue }, -// c: { type: ClarityType. BoolFalse }, -// } -// } - -console.log(tupCV.data['b']); -// { type: ClarityType. BoolTrue } -``` - -Tuples in Clarity are typed and contain named fields. The tuple above, for example, contains three fields with the names **a**, **b** and **c**, and the types of their values are `Int`, `Boolean` and `Boolean`, respectively. - -Clarity tuples are represented in JavaScript as objects and a tuple's data can be accessed by its `data` field, where the underlying JS object is stored. - -### Lists - -```typescript -const l = listCV([trueCV(), falseCV()]); -// { type: ClarityType. List, list: [{ type: ClarityType. BoolTrue }] } - -console.log(l.list[0]); -// { type: ClarityType. BoolTrue } -``` - -Lists, in Clarity, are homogeneous, meaning they can only contain elements of a singular (Clarity) type. Make sure to avoid constructing lists that have elements of multiple types. - -A Clarity lists underlying data can be accessed via its `list` field. - -## Using Clarity Values - -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](../understand-stacks/transactions#construction). - -## Utilizing Clarity Values from Transaction Responses - -`Read-only` Clarity functions can return Clarity values as a response. These `read-only` functions can be accessed easily in JavaScript via the [`callReadOnlyFunction()`](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions#calling-read-only-contract-function) function included in `@stacks/transactions`, which returns a `ClarityValue`. - -As mentioned above, `ClarityValues` are simply javascript objects containing a value and its associated Clarity type information. These object types are defined [here](https://github.com/hirosystems/stacks.js/tree/1f2b5fd8bdf1c2b5866e8171163594d7708a8c7a/packages/transactions/src/clarity/types). - -When you are calling a `read-only` contract function, you will always know what type the function will return, since functions in Clarity are strongly typed. - -It is common for Clarity functions to return values wrapped in a `Response`, in order to indicate if there was success or an error. - -Since every `ClarityValue` has a `type` field, the type of the result of a `read-only` function call can be checked and acted upon like so: - -```typescript -const contractAddress = 'ST3KC0MTNW34S1ZXD36JYKFD3JJMWA01M55DSJ4JE'; -const contractName = 'kv-store'; -const functionName = 'get-value'; -const buffer = bufferCVFromString('foo'); -const network = new StacksTestnet(); // for mainnet, use `StacksMainnet()` -const senderAddress = 'ST2F4BK4GZH6YFBNHYDDGN4T1RKBA7DA1BJZPJEJJ'; - -const options = { - contractAddress, - contractName, - functionName, - functionArgs: [buffer], - network, - senderAddress, -}; - -// make a read-only call to a contract function that -// returns a Response -const result: ResponseCV = await callReadOnlyFunction(options); - -if (result.type === ClarityType. ResponseOk) { - console.log(cvToString(result.value)); -} else if (result.type === ClarityType. ResponseErr) { - throw new Error(`kv-store contract error: ${result.value.data}`); -} -``` - -### ClarityValues to/from Hex - -If you receive a response from a transaction in the form of a `hex` string, you can deserialize it into a Clarity value like so: - -```javascript -import { hexToCV } from '@stacks/transactions'; - -let cv = hexToCV('hex_string'); -``` - -Similarly, you can convert a Clarity value to `hex` string like so: - -```javascript -import { cvToHex, trueCV } from '@stacks/transactions'; - -let trueHex = cvToHex(trueCV()); -``` - -## Debugging Clarity Values - -Sometimes you might receive a Clarity value that you were not expecting. Logging the value to your console won't always prove to be useful, unless you have memorized the Clarity value type enum values. - -In order to figure out what kind of value you are dealing with, you can use the `cvToString()` function to convert the Clarity value to a more easily readable string. - -For example, calling `cvToString()` on a large `tuple` might yield something like: - -``` -(tuple - (a -1) - (b u1) - (c 0x74657374) - (d true) - (e (some true)) - (f none) - (g SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B) - (h SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B.test) - (i (ok true)) - (j (err false)) - (k (list true false)) - (l (tuple (a true) (b false))) - (m "hello world") - (n u"hello \u{1234}"))` -``` diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/blockchain/index.md b/i18n/ru/docusaurus-plugin-content-docs/current/blockchain/index.md deleted file mode 100644 index 13db24ec30..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/blockchain/index.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: Blockchain -description: Stacks Blockchain -sidebar_position: 6 ---- - -Below is a guide to start working locally with the Stacks Blockchain. - -Code repository is [here](https://github.com/stacks-network/stacks-blockchain). - -## Getting started with the Stacks Blockchain - -### Download and build stacks-blockchain - -The first step is to ensure that you have Rust and the support software installed. - -```bash -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -``` - -:::info -For building on Windows, follow the rustup installer instructions at https://rustup.rs/ -::: - -From there, you can clone the Stacks Blockchain repository: - -```bash -git clone --depth=1 https://github.com/stacks-network/stacks-blockchain.git - -cd stacks-blockchain -``` - -Then build the project: - -```bash -cargo build -``` - -Run the tests: - -```bash -cargo test testnet -- --test-threads=1 -``` - -### Encode and sign transactions - -Here, we have generated a keypair that will be used for signing the upcoming transactions: - -```bash -cargo run --bin blockstack-cli generate-sk --testnet - -# Output -# { -# secretKey: "b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001", -# publicKey: "02781d2d3a545afdb7f6013a8241b9e400475397516a0d0f76863c6742210539b5", -# stacksAddress: "ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH" -# } -``` - -This keypair is already registered in the `testnet-follower-conf.toml` file, so it can be used as presented here. - -We will interact with the following simple contract `kv-store`. In our examples, we will assume this contract is saved to `./kv-store.clar`: - -```scheme -(define-map store { key: (string-ascii 32) } { value: (string-ascii 32) }) - -(define-public (get-value (key (string-ascii 32))) - (match (map-get? store { key: key }) - entry (ok (get value entry)) - (err 0))) - -(define-public (set-value (key (string-ascii 32)) (value (string-ascii 32))) - (begin - (map-set store { key: key } { value: value }) - (ok true))) -``` - -We want to publish this contract on chain, then issue some transactions that interact with it by setting some keys and getting some values, so we can observe read and writes. - -Our first step is to generate and sign, using your private key, the transaction that will publish the contract `kv-store`. To do that, we will use the subcommand `blockstack-cli` that has the following usage: - -```bash -blockstack-cli (options) publish [publisher-secret-key-hex] [fee-rate] [nonce] [contract-name] [file-name.clar] -``` - -With the following arguments: - -```bash -cargo run --bin blockstack-cli publish b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 515 0 kv-store ./kv-store.clar --testnet -``` - -The `515` is the transaction fee, denominated in microSTX. Right now, the testnet requires one microSTX per byte minimum, and this transaction should be less than 515 bytes. The third argument `0` is a nonce, that must be increased monotonically with each new transaction. - -This command will output the **binary format** of the transaction. In our case, we want to pipe this output and dump it to a file that will be used later in this tutorial. - -```bash -cargo run --bin blockstack-cli publish b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 515 0 kv-store ./kv-store.clar --testnet | xxd -r -p > tx1.bin -``` - -### Run the testnet - -You can observe the state machine in action locally by running: - -```bash -cargo stacks-node start --config=./testnet/stacks-node/conf/testnet-follower-conf.toml -``` - -`testnet-follower-conf.toml` is a configuration file that you can use for setting genesis balances or configuring Event observers. You can grant an address an initial account balance by adding the following entries: - -``` -[[ustx_balance]] -address = "ST2VHM28V9E5QCRD6C73215KAPSBKQGPWTEE5CMQT" -amount = 100000000 -``` - -The `address` field is the Stacks testnet address, and the `amount` field is the number of microSTX to grant to it in the genesis block. The addresses of the private keys used in the tutorial below are already added. - -### Publish your contract - -Assuming that the testnet is running, we can publish our `kv-store` contract. - -In another terminal (or file explorer), you can move the `tx1.bin` generated earlier, to the mempool: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx1.bin http://localhost:20443/v2/transactions -``` - -In the terminal window running the testnet, you can observe the state machine's reactions. - -### Reading from / Writing to the contract - -Now that our contract has been published on chain, let's try to submit some read / write transactions. We will start by trying to read the value associated with the key `foo`. - -To do that, we will use the subcommand: - -```bash -cargo run --bin blockstack-cli contract-call --help -``` - -With the following arguments: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 1 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store get-value -e \"foo\" --testnet | xxd -r -p > tx2.bin -``` - -`contract-call` generates and signs a contract-call transaction. - -We can submit the transaction by moving it to the mempool path: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx2.bin http://localhost:20443/v2/transactions -``` - -Similarly, we can generate a transaction that would be setting the key `foo` to the value `bar`: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 2 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store set-value -e \"foo\" -e \"bar\" --testnet | xxd -r -p > tx3.bin -``` - -And submit it by moving it to the mempool path: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx3.bin http://localhost:20443/v2/transactions -``` - -Finally, we can issue a third transaction, reading the key `foo` again, for ensuring that the previous transaction has successfully updated the state machine: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 3 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store get-value -e \"foo\" --testnet | xxd -r -p > tx4.bin -``` - -And submit this last transaction by moving it to the mempool path: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx4.bin http://localhost:20443/v2/transactions -``` - -Congratulations, you can now [write your own smart contracts with Clarity](write-smart-contracts/). diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/blockchain/networks.md b/i18n/ru/docusaurus-plugin-content-docs/current/blockchain/networks.md deleted file mode 100644 index fe9725352c..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/blockchain/networks.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Stacks Blockchain Networks -description: Stacks Blockchain Networks -sidebar_position: 3 ---- - -### Stacks Blockchain Networks - -- [x] **Krypton** is a Stacks 2 testnet with a fixed, two-minute block time, called `regtest`. Regtest is generally unstable for regular use, and is reset often. See the [regtest documentation](understand-stacks/testnet) for more information on using regtest. - -- [x] **Testnet** (old Xenon) is the Stacks 2 public testnet, which runs PoX against the Bitcoin testnet. It is the full implementation of the Stacks 2 blockchain, and should be considered a stable testnet for developing Clarity smart contracts. See the [testnet documentation](understand-stacks/testnet) for more information on the public testnet. - -- [x] **Mainnet** is the fully functional Stacks 2 blockchain, see the [Stacks overview](understand-stacks/) for information on running a Stacks node, mining, stacking, and writing Clarity smart contracts. diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md b/i18n/ru/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md deleted file mode 100644 index cf4f84a2da..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Stacks Blockchain API -description: Interacting with the Stacks 2.0 Blockchain via API -sidebar_position: 4 ---- - -## Introduction - -:::tip API Documentation Official API Documentation is available [here](https://stacks-network.github.io/stacks-blockchain/). ::: - - -The Stacks 2.0 Blockchain API allows you to query the Stacks 2.0 blockchain and interact with smart contracts. It was built to maintain pageable materialized views of the Stacks 2.0 Blockchain. - -:::caution The RESTful API is developed by Hiro. Hiro also hosts a public API node for easy onboarding. Using it requires you to trust the hosted server, but provides a faster onboarding experience. You can [run your own API server](https://docs.hiro.so/get-started/running-api-node) ::: - -The RESTful JSON API can be used without any authorization. The basepath for the API is: - -```bash -# for mainnet, replace `testnet` with `mainnet` -https://stacks-node-api.testnet.stacks.co/ -``` - -:::note This documentation only covers endpoints that are exposed on a Stacks node, referred to as the RPC API. For full documentation on the RESTful API, check out the [Hiro's API reference](https://docs.hiro.so/api). ::: - -### Stacks Node RPC API - -The [stacks-node implementation](https://github.com/stacks-network/stacks-blockchain/) exposes JSON RPC endpoints. - -All `/v2/` routes a proxied to a Hiro-hosted Stacks Node. For a trustless architecture, you should make these requests to a self-hosted node. - -## Proxied Stacks Node RPC API endpoints - -The Stacks 2.0 Blockchain API is centrally hosted. However, every running Stacks node exposes an RPC API, which allows you to interact with the underlying blockchain. Instead of using a centrally hosted API, you can directly access the RPC API of a locally hosted Node. - -:::tip -The Stacks Blockchain API proxies to Node RPC endpoints -::: - -While the Node RPC API doesn't give the same functionality as the hosted Stacks 2.0 Blockchain API, you get similar functionality in a way that is scoped to that specific node. The RPC API includes the following endpoints: - -- [POST /v2/transactions](https://docs.hiro.so/api#operation/post_core_node_transactions) -- [GET /v2/contracts/interface/{contract_address}/{contract_name}](https://docs.hiro.so/api#operation/get_contract_interface) -- [POST /v2/map_entry/{contract_address}/{contract_name}/{map_name}](https://docs.hiro.so/api#operation/get_contract_data_map_entry) -- [GET /v2/contracts/source/{contract_address}/{contract_name}](https://docs.hiro.so/api#operation/get_contract_source) -- [GET /v2/accounts/{principal}](https://docs.hiro.so/api#operation/get_account_info) -- [POST /v2/contracts/call-read/{contract_address}/{contract_name}/{function_name}](https://docs.hiro.so/api#operation/call_read_only_function) -- [GET /v2/fees/transfer](https://docs.hiro.so/api#operation/get_fee_transfer) -- [GET /v2/info](https://docs.hiro.so/api#operation/get_core_api_info) - -:::caution If you run a local node, it exposes an HTTP server on port `20443`. The info endpoint would be `localhost:20443/v2/info`. ::: diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md b/i18n/ru/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md deleted file mode 100644 index 71e3542302..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Stacks Releases -description: Stacks Blockchain Releases -sidebar_position: 2 ---- - -:::info -This page needs contributions. Help us improve it. -::: - -### Stacks Blockchain Releases - -All releases are published [here](https://github.com/stacks-network/stacks-blockchain/releases). Most important ones are described below. - -### Stacks 2.1 - -Scheduled for release at the end of 2022. - -More information on [what to expect with Stacks 2.1](https://stacks.org/stacks-21-what-to-expect). - -#### Stacks 2.05 -Activated on [Bitcoin block 713000](https://explorer.stacks.co/txid/0xece8e369310b5ff9b92ef11181ae0d2457ac0c821376d4a96c4998763e22ad04?chain=mainnet). - -This breaking change enables storage cost for list to be based on actual length and change in number of indexed I/O operations. More info on this [blog post](https://www.stacks.org/stacks-2-05?ref=docs-website). - -#### Stacks 2.0 -Activated on January 14th 2021 - -This hard fork enables Stacking, Clarity smart contracts, scalable transactions, and also building directly on Bitcoin. More info [here](https://forum.stacks.org/t/path-to-mainnet-for-stx-holders-things-to-know-ahead-of-stacks-2-0/11529). - -#### Stacks Genesis -Released on 2018, October 30th UTC+6 at Bitcoin block height 547921 - -This hard fork addresses registration of digital assets with Stacks token and also distribution of Stacks token to the existing purchasers. More info [here](https://blog.blockstack.org/the-launch-of-the-stacks-genesis-block/?ref=docs-website). - diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md b/i18n/ru/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md deleted file mode 100644 index 25ec969824..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Deploy tips -description: Learn some common methods for deploying your application. ---- - -## Introduction - -Stacks applications are web applications that authenticate users with Stacks Auth and store data with Gaia. Both of these technologies can be accessed on the client side. As such, Stacks apps tend to be simple in design and operation, since in many cases, they don’t have to host anything besides the application’s assets. - -## Where to deploy your application - -Before users can interact with your application, you must deploy it on a server that is accessible over the internet. Deploying requires that you: - -- Configure or customize the files in the `public` directory. -- Build your application site for deployment. -- Copy your generated application files to your production server. - -If you first populated your application with the Stacks application generator, your application contains the starting blocks for configuring, building, and deploying your app. For example, the React template builds out a scaffolding with the following building blocks. - -| File or Directory | Description | -| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| node_modules/react-scripts | A set of scripts for that helps you kick off React projects without configuring, so you do not have to set up your project by yourself. | -| package.json | Contains a scripts section that includes a reference to the react-scripts, which are a dependency. This script creates a build directory containing your files for deployment. | -| public/favicon.ico | An example shortcut icon. | -| public/index.html | An entry page for an application. | -| public/manifest.json | A JSON file that describes your web application to the browser. | -| cors | Contains example deployment files for cross-origin request configuration. | - -If you use the generator to build JavasScript or Vue scaffolding, your project configuration files will be different. - -Regardless of which scaffolding you use, you must customize and extend this basic scaffolding as needed by your application. For example, you may want to add more properties to the `manifest.json` file. Since every application is different, Stacks Auth cannot give you specific instructions on how to do this. The steps you take are specific to your application. - -## Stacks Authentication and deployment - -When your application authenticates users with Stacks, the Stacks Wallet at on URL requests a resource (the app manifest) from your DApp. A request for a resource outside of the origin (the Stacks Wallet) 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 (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) - -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 Stacks 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`: - -```html -Access-Control-Allow-Origin: * Access-Control-Allow-Headers: "X-Requested-With, Content-Type, -Origin, Authorization, Accept, Client-Security-Token, Accept-Encoding" Access-Control-Allow-Methods: -"POST, GET, OPTIONS, DELETE, PUT" -``` - -Consult the documentation for your hosting service to learn how to configure CORS on that service. - -## Deployment and Radiks - -If you are deploying a Stacks application that uses [Radiks](https://github.com/stacks-network/radiks), your deployment includes a server and a database component. You must take this into account when deploying your application. You may want to choose a service such as [Heroku](https://www.heroku.com) or [Digital Ocean](https://www.digitalocean.com) if your app uses Radiks. diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/build-apps/index.md b/i18n/ru/docusaurus-plugin-content-docs/current/build-apps/index.md deleted file mode 100644 index 23714cba5d..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/build-apps/index.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Build apps with Stacks -description: Authenticate users, sign transactions and store data with the Stacks blockchain -sidebar_position: 3 -sidebar_label: Build apps ---- - -## Introduction - -Apps built with the Stacks blockchain give users control over their digital identities, assets, and data. - -Unlike most cloud-based apps, they are "decentralized" since they don't depend on any centralized platform, server, or database to function. Rather, they use the Stacks blockchain to authenticate users and facilitate read and write requests for them without any single point of failure or trust. - -Stacks provides three main functions for building apps: - - - -- **Authentication**: Register and sign users in with identities on the Stacks blockchain -- **Transaction signing**: Prompt users to sign and broadcast transactions to the Stacks blockchain -- **Data storage**: Save and retrieve data for users with [Gaia](../gaia) - - -All three of these integrations can be used together to create powerful new user experiences that rival or exceed those of traditional apps—all while protecting your users' digital rights. - -While integration is possible for any type of app, most of the resources available here are for web developers experienced with JavaScript. See [Hiro developer docs](https://docs.hiro.so) for more information on the available app development libraries for Stacks. - -## [References](references) - -[Authentication](references/authentication) - -[BNS](references/bns) - -[Gaia](../gaia/) - diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md b/i18n/ru/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md deleted file mode 100644 index 727b4e2163..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: NoCodeClarity -description: Launch apps for the Stacks blockchain through no code platforms like Bubble. ---- - -## Introduction - -![](https://d1muf25xaso8hp.cloudfront.net/https%3A%2F%2Fs3.amazonaws.com%2Fappforest_uf%2Ff1653407713550x759333524803365600%2FLogo%2520of%2520NoCodeClarity.png?w=179&h=84&auto=compress&dpr=1&fit=max) - -[NoCodeClarity](https://nocodeclarity.com) allows people to create applications for the Stacks blockchain without coding. - -## Stacks Plug-In on bubble - -The [Stacks-No-Code-Plugin](https://bubble.io/plugin/the-stacks-plug-in-1645467277638x949839693014368300) released in May 2022 and it can easily be installed on Bubble with a few clicks allowing users to deploy applications with no coding knowledge. [Bubble](https://bubble.io/blog/explaining-bubble-to-investors/) is the first No Code platform that the Stacks plugin launched on. More platforms are in the roadmap of NoCodeClarity, founded by Christopher Perceptions and Sergio Gongora. The Stacks plugin was created through the support of the Stacks Foundation via a grant in January 2022 and NoCodeClarity was awarded a $100,000 grant in June 2022 to expand the roadmap. - -Additional [instructions](https://s3.amazonaws.com/appforest_uf/f1654202471526x991633667675927800/Instructions%20v2.docx.pdf) are also available. Tutorials and step by step guides will be released soon. - -The Stacks-No-Code-Plugin code is [publicly available on Github](https://github.com/nocodeclarity/Stacks-No-Code-Plugin). - -![](/img/bubble-stacks-plugin.png) - -## Demo page - -A demo page is available [here](https://test-stacks-plugin.bubbleapps.io/version-test). - -## NoCodeClarity videos - -NodeCodeClarity has their own [youtube channel](https://www.youtube.com/channel/UC9Ep0VQ-GQ-yDzt-wmIElRA). - -Videos: - -* [NoCodeClarity Setup](https://www.youtube.com/watch?v=WanXlpBGl0w) -* [NoCodeClarity - Part 1 of the plugin](https://www.youtube.com/watch?v=o6d3hrzNqVI&t=248s) -* [NoCodeClarity - Part 2 of the plugin](https://www.youtube.com/watch?v=0rzMdsrRg80) -* [Sneak Peek of the No Code Stacks Wallet Template](https://www.youtube.com/watch?v=Xe6Yv0rF6XM) \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md b/i18n/ru/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md deleted file mode 100644 index 86a8568663..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Authentication -description: Register and sign in users with identities on the Stacks blockchain ---- - -## Introduction - -This guide explains how authentication is performed on the Stacks blockchain. - -Authentication provides a way for users to identify themselves to an app while retaining complete control over their credentials and personal details. It can be integrated alone or used in conjunction with [transaction signing](https://docs.hiro.so/get-started/transactions#signature-and-verification) and [data storage](https://docs.stacks.co/build-apps/references/gaia), for which it is a prerequisite. - -Users who register for your app can subsequently authenticate to any other app with support for the [Blockchain Naming System](bns) and vice versa. - -## How it works - -The authentication flow with Stacks is similar to the typical client-server flow used by centralized sign in services (for example, OAuth). However, with Stacks the authentication flow happens entirely client-side. - -An app and authenticator, such as [the Stacks Wallet](https://www.hiro.so/wallet/install-web), communicate during the authentication flow by passing back and forth two tokens. The requesting app sends the authenticator an `authRequest` token. Once a user approves authentication, the authenticator responds to the app with an `authResponse` token. - -These tokens are are based on [a JSON Web Token (JWT) standard](https://tools.ietf.org/html/rfc7519) with additional support for the `secp256k1` curve used by Bitcoin and many other cryptocurrencies. They are passed via URL query strings. - -When a user chooses to authenticate an app, it sends the `authRequest` token to the authenticator via a URL query string with an equally named parameter: - -`https://wallet.hiro.so/...?authRequest=j902120cn829n1jnvoa...` - -When the authenticator receives the request, it generates an `authResponse` token for the app using an _ephemeral transit key_ . The ephemeral transit key is just used for the particular instance of the app, in this case, to sign the `authRequest`. - -The app stores the ephemeral transit key during request generation. The public portion of the transit key is passed in the `authRequest` token. The authenticator uses the public portion of the key to encrypt an _app private key_ which is returned via the `authResponse`. - -The authenticator generates the app private key from the user's _identity address private key_ and the app's domain. The app private key serves three functions: - -1. It is used to create credentials that give the app access to a storage bucket in the user's Gaia hub -2. It is used in the end-to-end encryption of files stored for the app in the user's Gaia storage. -3. It serves as a cryptographic secret that apps can use to perform other cryptographic functions. - -Finally, the app private key is deterministic, meaning that the same private key will always be generated for a given Stacks address and domain. - -The first two of these functions are particularly relevant to [data storage with Stacks.js](https://docs.stacks.co/docs/gaia). - -## Key pairs - -Authentication with Stacks makes extensive use of public key cryptography generally and ECDSA with the `secp256k1` curve in particular. - -The following sections describe the three public-private key pairs used, including how they're generated, where they're used and to whom private keys are disclosed. - -### Transit private key - -The transit private is an ephemeral key that is used to encrypt secrets that need to be passed from the authenticator to the app during the authentication process. It is randomly generated by the app at the beginning of the authentication response. - -The public key that corresponds to the transit private key is stored in a single element array in the `public_keys` key of the authentication request token. The authenticator encrypts secret data such as the app private key using this public key and sends it back to the app when the user signs in to the app. The transit private key signs the app authentication request. - -### Identity address private key - -The identity address private key is derived from the user's keychain phrase and is the private key of the Stacks username that the user chooses to use to sign in to the app. It is a secret owned by the user and never leaves the user's instance of the authenticator. - -This private key signs the authentication response token for an app to indicate that the user approves sign in to that app. - -### App private key - -The app private key is an app-specific private key that is generated from the user's identity address private key using the `domain_name` as input. - -The app private key is securely shared with the app on each authentication, encrypted by the authenticator with the transit public key. Because the transit key is only stored on the client side, this prevents a man-in-the-middle attack where a server or internet provider could potentially snoop on the app private key. diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/build-apps/references/bns.md b/i18n/ru/docusaurus-plugin-content-docs/current/build-apps/references/bns.md deleted file mode 100644 index 32b045dc83..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/build-apps/references/bns.md +++ /dev/null @@ -1,241 +0,0 @@ ---- -title: Blockchain Naming System -description: Binds Stacks usernames to off-chain state ---- - -Blockchain Naming System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of control. - -The Stacks V1 blockchain implemented BNS through first-order name operations. In Stacks V2, BNS is instead implemented through a smart-contract loaded during the genesis block. - -Names in BNS have three properties: - -- **Names are globally unique.** The protocol does not allow name collisions, and all well-behaved nodes resolve a given name to the same state. -- **Names are human-meaningful.** Each name is chosen by its creator. -- **Names are strongly owned.** Only the name's owner can change the state it resolves to. Specifically, a name is owned by one or more ECDSA private keys. - -The Stacks blockchain insures that each node's BNS view is synchronized to all of the other nodes in the world, so queries on one node will be the same on other nodes. Stacks blockchain nodes allow a name's owner to bind up to 40Kb of off-chain state to their name, which will be replicated to all other Stacks blockchain nodes via a P2P network. - -The biggest consequence for developers is that in BNS, reading name state is fast and cheap but writing name state is slow and expensive. This is because registering and modifying names requires one or more transactions to be sent to the underlying blockchain, and BNS nodes will not process them until they are sufficiently confirmed. Users and developers need to acquire and spend the requisite cryptocurrency (STX) to send BNS transactions. - -## Motivation behind naming systems - -We rely on naming systems in everyday life, and they play a critical role in many different applications. For example, when you look up a friend on social media, you are using the platform's naming system to resolve their name to their profile. When you look up a website, you are using the Domain Name Service to resolve the hostname to its host's IP address. When you check out a Git branch, you are using your Git client to resolve the branch name to a commit hash. When you look up someone's PGP key on a keyserver, you are resolving their key ID to their public key. - -What kinds of things do we want to be true about names? In BNS, names are globally unique, names are human-meaningful, and names are strongly owned. However, if you look at these examples, you'll see that each of them only guarantees _two_ of these properties. This limits how useful they can be. - -- In DNS and social media, names are globally unique and human-readable, but not strongly owned. The system operator has the final say as to what each names resolves to. - - - **Problem**: Clients must trust the system to make the right choice in what a given name resolves to. This includes trusting that no one but the system administrators can make these changes. - -- In Git, branch names are human-meaningful and strongly owned, but not globally unique. Two different Git nodes may resolve the same branch name to different unrelated repository states. - - - **Problem**: Since names can refer to conflicting state, developers have to figure out some other mechanism to resolve ambiguities. In Git's case, the user has to manually intervene. - -- In PGP, names are key IDs. They are are globally unique and cryptographically owned, but not human-readable. PGP key IDs are derived from the keys they reference. - - **Problem**: These names are difficult for most users to remember since they do not carry semantic information relating to their use in the system. - -BNS names have all three properties, and none of these problems. This makes it a powerful tool for building all kinds of network applications. With BNS, we can do the following and more: - -- Build domain name services where hostnames can't be hijacked. -- Build social media platforms where user names can't be stolen by phishers. -- Build version control systems where repository branches do not conflict. -- Build public-key infrastructure where it's easy for users to discover and remember each other's keys. - -## Organization of BNS - -BNS names are organized into a global name hierarchy. There are three different layers in this hierarchy related to naming: - -- **Namespaces**. These are the top-level names in the hierarchy. An analogy to BNS namespaces are DNS top-level domains. Existing BNS namespaces include `.id`, `.podcast`, and `.helloworld`. All other names belong to exactly one namespace. Anyone can create a namespace, but in order for the namespace to be persisted, it must be _launched_ so that anyone can register names in it. Namespaces are not owned by their creators. - -- **BNS names**. These are names whose records are stored directly on the blockchain. The ownership and state of these names are controlled by sending blockchain transactions. Example names include `verified.podcast` and `muneeb.id`. Anyone can create a BNS name, as long as the namespace that contains it exists already. - -- **BNS subdomains**. These are names whose records are stored off-chain, but are collectively anchored to the blockchain. The ownership and state for these names lives within the P2P network data. While BNS subdomains are owned by separate private keys, a BNS name owner must broadcast their subdomain state. Example subdomains include `jude.personal.id` and `podsaveamerica.verified.podcast`. Unlike BNS namespaces and names, the state of BNS subdomains is _not_ part of the blockchain consensus rules. - -A feature comparison matrix summarizing the similarities and differences between these name objects is presented below: - -| Feature | **Namespaces** | **BNS names** | **BNS Subdomains** | -| -------------------------------------- | -------------- | ------------- | ------------------ | -| Globally unique | X | X | X | -| Human-meaningful | X | X | X | -| Owned by a private key | | X | X | -| Anyone can create | X | X | [1] | -| Owner can update | | X | [1] | -| State hosted on-chain | X | X | | -| State hosted off-chain | | X | X | -| Behavior controlled by consensus rules | X | X | | -| May have an expiration date | | X | | - -[1] Requires the cooperation of a BNS name owner to broadcast its transactions - -## Namespaces - -Namespaces are the top-level naming objects in BNS. - -They control a few properties about the names within them: - -- How expensive they are to register -- How long they last before they have to be renewed -- Who (if anyone) receives the name registration fees -- Who is allowed to seed the namespace with its initial names. - -At the time of this writing, by far the largest BNS namespace is the `.id` namespace. Names in the `.id` namespace are meant for resolving user identities. Short names in `.id` are more expensive than long names, and have to be renewed by their owners every two years. Name registration fees are not paid to anyone in particular---they are instead sent to a "black hole" where they are rendered unspendable (the intention is to discourage ID squatters). - -Unlike DNS, _anyone_ can create a namespace and set its properties. Namespaces are created on a first-come first-serve basis, and once created, they last 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 (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`). - -Namespaces can be between 1 and 19 characters long, and are composed of the characters `a-z`, `0-9`, `-`, and `_`. - -## Subdomains - -BNS names are strongly owned because the owner of its private key can generate valid transactions that update its zone file hash and owner. However, this comes at the cost of requiring a name owner to pay for the underlying transaction in the blockchain. Moreover, this approach limits the rate of BNS name registrations and operations to the underlying blockchain's transaction bandwidth. - -BNS overcomes this with subdomains. A **BNS subdomain** is a type of BNS name whose state and owner are stored outside of the blockchain, but whose existence and operation history are anchored to the blockchain. Like their on-chain counterparts, subdomains are globally unique, strongly owned, and human-readable. BNS gives them their own name state and public keys. Unlike on-chain names, subdomains can be created and managed cheaply, because they are broadcast to the BNS network in batches. A single blockchain transaction can send up to 120 subdomain operations. - -This is achieved by storing subdomain records in the BNS name zone files. An on-chain name owner broadcasts subdomain operations by encoding them as `TXT` records within a DNS zone file. To broadcast the zone file, the name owner sets the new zone file hash with a `NAME_UPDATE` transaction and replicates the zone file. This, in turn, replicates all subdomain operations it contains, and anchors the set of subdomain operations to an on-chain transaction. The BNS node's consensus rules ensure that only valid subdomain operations from _valid_ `NAME_UPDATE` transactions will ever be stored. - -For example, the name `verified.podcast` once wrote the zone file hash `247121450ca0e9af45e85a82e61cd525cd7ba023`, which is the hash of the following zone file: - -```bash -$TTL 3600 -1yeardaily TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxeWVhcmRhaWx5CiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMXllYXJkYWlseS9oZWFkLmpzb24iCg==" -2dopequeens TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAyZG9wZXF1ZWVucwokVFRMIDM2MDAKX2h0dHAuX3RjcCBVUkkgMTAgMSAiaHR0cHM6Ly9waC5kb3Rwb2RjYXN0LmNvLzJkb3BlcXVlZW5zL2hlYWQuanNvbiIK" -10happier TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxMGhhcHBpZXIKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8xMGhhcHBpZXIvaGVhZC5qc29uIgo=" -31thoughts TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzMXRob3VnaHRzCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzF0aG91Z2h0cy9oZWFkLmpzb24iCg==" -359 TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzNTkKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8zNTkvaGVhZC5qc29uIgo=" -30for30 TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzMGZvcjMwCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzBmb3IzMC9oZWFkLmpzb24iCg==" -onea TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiBvbmVhCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vb25lYS9oZWFkLmpzb24iCg==" -10minuteteacher TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxMG1pbnV0ZXRlYWNoZXIKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8xMG1pbnV0ZXRlYWNoZXIvaGVhZC5qc29uIgo=" -36questionsthepodcastmusical TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzNnF1ZXN0aW9uc3RoZXBvZGNhc3RtdXNpY2FsCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzZxdWVzdGlvbnN0aGVwb2RjYXN0bXVzaWNhbC9oZWFkLmpzb24iCg==" -_http._tcp URI 10 1 "https://dotpodcast.co/" -``` - -Each `TXT` record in this zone file encodes a subdomain-creation. For example, `1yeardaily.verified.podcast` resolves to: - -```json -{ - "address": "1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH", - "blockchain": "bitcoin", - "last_txid": "d87a22ebab3455b7399bfef8a41791935f94bc97aee55967edd5a87f22cce339", - "status": "registered_subdomain", - "zonefile_hash": "e7acc97fd42c48ed94fd4d41f674eddbee5557e3", - "zonefile_txt": "$ORIGIN 1yeardaily\n$TTL 3600\n_http._tcp URI 10 1 \"https://ph.dotpodcast.co/1yeardaily/head.json\"\n" -} -``` - -This information was extracted from the `1yeardaily` `TXT` resource record in the zone file for `verified.podcast`. - -### Subdomain Lifecycle - -Note that `1yeardaily.verified.podcast` has a different public key hash (address) than `verified.podcast`. A BNS node will only process a subsequent subdomain operation on `1yeardaily.verified.podcast` if it includes a signature from this address's private key. `verified.podcast` cannot generate updates; only the owner of `1yeardaily.verified.podcast can do so`. - -The lifecycle of a subdomain and its operations is shown in Figure 2. - -``` - subdomain subdomain subdomain - creation update transfer -+----------------+ +----------------+ +----------------+ -| cicero | | cicero | | cicero | -| owner="1Et..." | signed | owner="1Et..." | signed | owner="1cJ..." | -| zf0="7e4..." |<--------| zf0="111..." |<--------| zf0="111..." |<---- ... -| seqn=0 | | seqn=1 | | seqn=2 | -| | | sig="xxxx" | | sig="xxxx" | -+----------------+ +----------------+ +----------------+ - | | | - | off-chain | | -~ ~ ~ ~ | ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~|~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ | ~ ~ ~ ~ ~ ~ ~ ... - | on-chain | | - V V (zone file hash ) V -+----------------+ +----------------+ +----------------+ -| res_publica.id | | jude.id | | res_publica.id | -| NAME_UPDATE |<--------| NAME_UPDATE |<--------| NAME_UPDATE |<---- ... -+----------------+ +----------------+ +----------------+ - blockchain blockchain blockchain - block block block - - -Figure 2: Subdomain lifetime with respect to on-chain name operations .A new -subdomain operation will only be accepted if it has a later "sequence=" number, -and a valid signature in "sig=" over the transaction body .The "sig=" field -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." -However, any on-chain name ("jude.id" in this case) can broadcast a subdomain -update for "cicero.res_publica.id." -``` - -Subdomain operations are ordered by sequence number, starting at 0. Each new subdomain operation must include: - -- The next sequence number -- The public key that hashes to the previous subdomain transaction's address -- A signature from the corresponding private key over the entire subdomain operation. - -If two correctly signed but conflicting subdomain operations are discovered (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 subdomain's operations will be able to determine the valid sequence of state-transitions it has undergone, and determine the current zone file and public key hash for the subdomain. - -### Subdomain Creation and Management - -Unlike an on-chain name, a subdomain owner needs an on-chain name owner's help to broadcast their subdomain operations. In particular: - -- A subdomain-creation transaction can only be processed by the owner of the on-chain name that shares its suffix. For example, only the owner of `res_publica.id` can broadcast subdomain-creation transactions for subdomain names ending in `.res_publica.id`. -- A subdomain-transfer transaction can only be broadcast by the owner of the on-chain name that created it. For example, the owner of `cicero.res_publica.id` needs the owner of `res_publica.id` to broadcast a subdomain-transfer transaction to change `cicero.res_publica.id`'s public key. -- In order to send a subdomain-creation or subdomain-transfer, all of an on-chain name owner's zone files must be present in the Atlas network. This lets the BNS node prove the _absence_ of any conflicting subdomain-creation and subdomain-transfer operations when processing new zone files. -- A subdomain update transaction can be broadcast by _any_ on-chain name owner, but the subdomain owner needs to find one who will cooperate. For example, the owner of `verified.podcast` can broadcast a subdomain-update transaction created by the owner of `cicero.res_publica.id`. - -That said, to create a subdomain, the subdomain owner generates a subdomain-creation operation for their desired name and gives it to the on-chain name owner. - -Once created, a subdomain owner can use any on-chain name owner to broadcast a subdomain-update operation. To do so, they generate and sign the requisite subdomain operation and give it to an on-chain name owner, who then packages it with other subdomain operations into a DNS zone file and broadcasts it to the network. - -If the subdomain owner wants to change the address of their subdomain, they need to sign a subdomain-transfer operation and give it to the on-chain name owner who created the subdomain. They then package it into a zone file and broadcast it. - -### Subdomain Registrars - -Because subdomain names are cheap, developers may be inclined to run subdomain registrars on behalf of their applications. For example, the name `personal.id` is used to register usernames without requiring them to spend any Bitcoin. - -We supply a reference implementation of a [BNS Subdomain Registrar](https://github.com/stacks-network/subdomain-registrar) to help developers broadcast subdomain operations. Users would still own their subdomain names; the registrar simply gives developers a convenient way for them to register and manage them in the context of a particular application. - -# BNS and DID Standards - -BNS names are compliant with the emerging [Decentralized Identity Foundation](http://identity.foundation) protocol specification for decentralized identifiers (DIDs). - -Each name in BNS has an associated DID. The DID format for BNS is: - -```bash - did:stack:v0:{address}-{index} -``` - -Where: - -- `{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 `did:stack:v0:1dARRtzHPAFRNE7Yup2Md9w18XEQAtLiV-0`, because the name `personal.id` was the first-ever name created by `1dARRtzHPAFRNE7Yup2Md9w18XEQAtLiV`. - -As another example, the DID for `jude.id` is `did:stack:v0:16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg-1`. Here, the address `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` had created one earlier name in history prior to this one (which happens to be `abcdefgh123456.id`). - -The purpose of a DID is to provide an eternal identifier for a public key. The public key may change, but the DID will not. - -Stacks Blockchain implements a DID method of its own in order to be compatible with other systems that use DIDs for public key resolution. In order for a DID to be resolvable, all of the following must be true for a name: - -- The name must exist -- The name's zone file hash must be the hash of a well-formed DNS zone file -- The DNS zone file must be present in the Stacks node's data. -- The DNS zone file must contain a `URI` resource record that points to a signed JSON Web Token -- The public key that signed the JSON Web Token (and is included with it) must hash to the address that owns the name - -Not all names will have DIDs that resolve to public keys. However, names created by standard tooling will have DIDs that do. - -A RESTful API is under development. - -## DID Encoding for Subdomains - -Every name and subdomain in BNS has a DID. The encoding is slightly different 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 (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 subdomains owned by a single private key, and version byte 50 for subdomains owned by a m-of-n set of private keys. That is, subdomain DID addresses start with `S` or `M`, respectively. - -The `{index}` field for a subdomain's DID is distinct from the `{index}` field for a BNS name's DID, even if the same created both names and subdomains. For example, the name `abcdefgh123456.id` has the DID `did:stack:v0:16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg-0`, because it was the first name created by `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg`. However, `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` _also_ created `jude.statism.id` as its first subdomain name. The DID for `jude.statism.id` is `did:stack:v0:SSXMcDiCZ7yFSQSUj7mWzmDcdwYhq97p2i-0`. Note that the address `SSXMcDiCZ7yFSQSUj7mWzmDcdwYhq97p2i` encodes the same public key hash as the address `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` (the only difference between these two strings is that the first is base58check-encoded with version byte 0, and the second is encoded with version byte 63). diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/build-apps/references/references.md b/i18n/ru/docusaurus-plugin-content-docs/current/build-apps/references/references.md deleted file mode 100644 index babe5e119a..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/build-apps/references/references.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: References -sidebar_label: References ---- - -[Authentication](./authentication) - -[Blockchain Naming System](./bns) - -[Hiro example apps](https://docs.hiro.so/example-apps) \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/contribute/docs.md b/i18n/ru/docusaurus-plugin-content-docs/current/contribute/docs.md deleted file mode 100644 index 77705451b8..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/contribute/docs.md +++ /dev/null @@ -1,207 +0,0 @@ ---- -title: Contribute to docs -description: Learn how this site is built, and how you can contribute to it. ---- - -## Introduction - -Thank you for your interest in contributing and helping make these docs as good as they can be. - -This docs site is built on the open source platform [Discosaurus 2](https://docusaurus.io/) and most of its content is written in Markdown files. All of the code for this site is free and open source, located at the [GitHub repository here](https://github.com/stacks-network/docs). - -:::tip Don't know what Markdown is? Want to learn? Here is a [helpful guide](https://guides.github.com/features/mastering-markdown/). - -Don't want to learn it? No need to. Write [in plain text an issue on Github](https://github.com/stacks-network/docs/issues/new?assignees=&labels=documentation&template=add-documentation.md&title=%5BAdd+docs%5D) ::: - -:::info You need a free [Github](https://www.github.com) account to add or edit any content. ::: - -To edit any page, just click on the *Edit this page* button at the bottom of each page and submit your changes online. - -To add new content, they are two different ways to do it, the [easy way](#easy-way) and the [advanced way](#advanced-way). - -## Easy way - -[**Simply click here and enter the text of the article you wish to add.**](https://github.com/stacks-network/docs/issues/new?assignees=&labels=documentation&template=add-documentation.md&title=%5BAdd+docs%5D) - -This will open up an issue on github using our template. -## Advanced way - -For more advanced changes you can follow the next steps. - -You can also test the site locally using this method. -### Steps - -1. Fork the [docs reposiroty](https://github.com/stacks-network/docs) by clicking on the *Fork* button in the upper right of the screen. -2. Clone your fork to your local machine with this command `git clone git@github.com:/docs.git stacks_docs` -3. Enter your project folder `cd stacks_docs` -4. Create a branch `git checkout -b feat/my-feature-branch`. -5. You can optionally preview your changes in real time with: - - `npm install` (to install dependencies). - - `npx docusaurus start` to start a local copy of the site. A web browser will open at http://localhost:3000, so you can see a preview of yourhanges in real time. -6. Make the changes you wish and then commit them with this kind of message: `git commit -am "feat: some new feature or content"`. -7. Push to to GitHub with `git push --set-upstream origin feature/my-feature-branch`. -8. Visit GitHub and make your pull request. - -## Aditional information -### Running and building the site locally (optional) - -You can start the page locally with the following command. This is enough to preview your changes. -```bash -npx docusaurus start -``` - -Before running this command for the first time you will need to run `npm install` to install dependencies. - -The docs site will be accessible at this url: [`http://localhost:3000`](http://localhost:3000). - - -After you finished your changes, you can also build the entire site with the following command (not usually needed): -```bash -npm run build -``` - -:::tip `npx docusaurus start` will only load the default language (english). To test all languages you can build with `npm run build` and then preview your build with `npm run serve`. ::: - -### An alternative: Working in browser - -As an alterative to working locally, you can also use the web IDE gitpod that provides an environment to contribute directly from within your browser. - -You only need to have a github account and open [this link](https://gitpod.io/#https://github.com/stacks-network/docs). - -### Folder structure of the site - -If you are interested in only adding new documentation content to the site, the files that will be important to you are located within `./docs/*`: - -```bash -docs/ - build-apps - contribute/ - faq/ - gaia/ - nodes-and-miners/ - noteworthy-contracts/ - references/ - understand-stack/ - write-smart-contracts/ -``` - -The routing for this site is file based, meaning if you created a folder within `/docs/gaia/` named `testing` and in it a file named `test1.md`, you would be able to navigate to `http://localhost:3000/gaia/testing/test1` and you would see whatever content is in that markdown file. - -All the docs in English are stored in the folder `/docs/`. - -To add new English content simply add a markdown file (.md) into any subfolder in docs, and it will be automatically displayed in the category of that folder. - -All the docs in other languages are stored under the folder `i18n`, but these files should never be edited using GitHub as they are overwritten by Crowdin every time new translations are added. **To make changes in other languages**, you must do so using Crowdin. Please refer to [translations](translations) instead. - -### Frontmatter - -Frontmatter is the top part of any markdown document that is written in a language called [YAML](https://yaml.org/). It looks like this: - -```yaml ---- -title: This is my page title -description: A short, concise sentence describing what is on this page ---- -``` - -Frontmatter gives us the ability to define some things within a page that the site can use, such as a page title or page description. When adding any new page, please include a `title` and `description`. - - - -### Use Conventional Commits - -We use the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) as and commits naming convention. Use it while contributing, please. - -### Code blocks - -To write a code block, you need to wrap your code in ` ```language `, and end your code block with ` ``` `. Here is an example of ` ```clarity `. - -```clarity -(define-data-var counter int 0) - -(define-public (get-counter) - (ok (var-get counter))) -``` -### Admonitions - -You can use the following admonitions to highlight content. - -```md -:::note -Some **content** with _markdown_ `syntax`. -::: - -:::tip -Some **content** with _markdown_ `syntax`. -::: - -:::info -Some **content** with _markdown_ `syntax`. -::: - -:::caution -Some **content** with _markdown_ `syntax`. -::: - -:::danger -Some **content** with _markdown_ `syntax`. -::: - -:::tip My personalized title -Some **content** with _markdown_ `syntax`. -::: -``` - -Which renders: - -:::note - -Some **content** with _markdown_ `syntax`. - -::: - -:::tip - -Some **content** with _markdown_ `syntax`. - -::: - -:::info - -Some **content** with _markdown_ `syntax`. - -::: - -:::caution - -Some **content** with _markdown_ `syntax`. - -::: - -:::danger - -Some **content** with _markdown_ `syntax`. - -::: - -:::tip My personalized title - -Some **content** with _markdown_ `syntax`. - -::: \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/contribute/index.md b/i18n/ru/docusaurus-plugin-content-docs/current/contribute/index.md deleted file mode 100644 index ac81d899bd..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/contribute/index.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Contribute -description: Contribute to the Stacks ecosystem. -sidebar_position: 10 -sidebar_label: "Contribute" ---- - -You can contribute to the Stacks ecosystem in multiple ways: - - - -### Documentation - -Contribute to the Stacks Docs on this website. More info [here](docs). - -### Translations - -Help us reach more people with translations. More details [here](translations). - - - -### Articles - -Write an article or a blog post about Stacks. A good place to start is [Stacks Forum](https://forum.stacks.org). - -### Github - -If you are familiar with Github they are multiple repositories of the Stack Ecosystem that you can contribute to. - -- https://github.com/stacks-network/ diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/contribute/translations.md b/i18n/ru/docusaurus-plugin-content-docs/current/contribute/translations.md deleted file mode 100644 index bd9a452333..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/contribute/translations.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Contribute with translations -description: Want to help tranlating these docs to your local language? ---- - -## Help with translations - -Translations are managed with Crowdin. -Anybody can colaborate and no technichal skills are required, as it's all done on the browser. - -To help with translation please go to [this page](https://crowdin.com/project/docsstacksco), click any language and start translating. - -All help is appreciated. - -:::caution -Please don't add any translations to the Github repository, as the translated pages get rewritten from Crowdin. Translations need to be added on Crodin intead. -::: - -### Common issues on translations - -When translating in Crowdin, please only translate the texts and not the html code. - -If you acccidently modify the html tags you will get errors like shown below (`Seems like some formating tags are missing` or `Translation contains tag that source text doesn't have`). These errors will prevent your translation getting published until the tags are left as they were in the original text. - -![](/img/crowdin-qa-issue-formatting_tags_missing.png) ![](/img/crowdin-qa-issue-tag_source.png) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/faq/faq.md b/i18n/ru/docusaurus-plugin-content-docs/current/faq/faq.md deleted file mode 100644 index dde584e583..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/faq/faq.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: General FAQs -description: Frequently Asked Questions -sidebar_label: "FAQ" -sidebar_position: 10 ---- - -![](/img/glasses.png) - -## Why is my transfer still pending? - -Commonly it's because your fee is too low or your [nonce](#what-is-nonce) is incorrect. - -More information can be found [here](https://www.hiro.so/wallet-faq/why-is-my-stacks-transaction-pending). There are also [best practices and known issues](https://forum.stacks.org/t/transactions-in-mempool-best-practices-and-known-issues/11659) and [diagnosing pending transactions](https://forum.stacks.org/t/diagnosing-pending-transactions/11908). - -There is also this [script](https://github.com/citycoins/scripts/blob/main/getnetworkstatus.js) to look at either the first 200 transactions or all the transactions in the mempool, to then return the maximum adn average fee values. We've noticed that using 1.5-2x the average fee in the mempool will generally get things processed within 6-10 blocks even during high congestion. - -There is also this [script](https://github.com/citycoins/scripts/blob/main/gettxstatus.js) to track a pending transaction until it reaches a final status. - -## What is Nonce? - -A nonce is used to make sure that every transaction goes in right order. Nonce starts at 0, so the very first transaction from an address should set to nonce=0. You can find the nonce of your wallet address by searching the address in any [Stacks blockchain explorer](https://explorer.stacks.co/). You can also user `$ stx balance
`. - -If you have a transaction nonce that is less than your account nonce, the transaction is unmineable and will (should) disappear after 256 blocks. This does not affect future transactions and therefore can be just ignored, they are in the past. - -If you have a transaction nonce that is equal to your account nonce, then that transaction is valid and should be the next in line to be processed next. - -If you have a transaction nonce that is higher than your account nonce, then there needs to be a chain of transactions starting with your account nonce in order for it to be processed. E.g. Your account nonce is 10 but the pending transaction has a nonce of 12. It will not be mineable until a transaction with nonces 10 and 11 are processed. - -## Whats a Replace-by-fee (RBF)? - -A replace-by-fee (RBF) transaction tells the blockchain that you would like to replace one transaction with another, while specifying a fee that is higher than the original transaction fee. A transaction can be replaced with **any other transaction**, and is not limited to the same operation. - -This can be used to effectively **cancel a transaction** by replacing it with something else, like a small STX transfer to another owned address. - -This can be used to **raise the fee for a pending transaction** so it is considered by miners during periods of high congestion. This can also be used to _resubmit_ a transaction, in the sense that the RBF transaction gets a new txid and gets considered again (or faster) by miners. E.g. I submit my transaction with 1 STX fee at block 54,123. By block 54,133 I see my tx hasn’t been picked up, so I RBF with 1.1 STX. Then wait 10 blocks again, and RBF again if not received. There’s a balance between doing this too often and keeping a consistent pace, but it has been seen to help get transactions through, especially when new ones are constantly flooding in. - -The replacement transaction needs to use the same nonce as the original transaction with a fee increase of at least 0.000001 STX. E.g. Your original transaction has a fee of 0.03 STX, the new RBF transaction must have a fee of 0.030001 STX or above. - -RBF transactions process in one of two ways: - -- If miners pick up the original transaction before the RBF transaction is received, then the original transaction is processed and the replacement transaction goes into an unmineable state. It will eventually disappear and doesn’t affect future transactions. -- If miners pick up the replaced transaction then the new transaction is processed instead of the original, and the status of the original transaction is set to “droppped_replaced_by_fee”. This status is not shown on the explorer but can be seen when querying the txid. - -Submitting multiple transactions for the same action can slow things down in a few ways. - -- If the total spent in 2 or 3 transactions is more than can be spent in a single transaction, the transactions appear unmineable. -- If the fees for multiple transactions exceed the STX balance, the transactions will be unmineable. - -## What are .btc domains? - -[This forum post](https://forum.stacks.org/t/btc-domains-are-live/12065) explains all the benefits of .btc domains. They can currently be purchased in [btc.us](https://btc.us/) - -## What is the blockchain trilemma? - -## Stacks vs. Solana vs. Polygon: How Do They Compare From a Developer Perspective? - -[This blog post answers the question](https://www.hiro.so/blog/stacks-vs-solana-vs-polygon-how-do-they-compare-from-a-developer-perspective). - -## What Does Lightning’s Taro Proposal Mean for Stacks? - -[This blog post answers the question](https://www.hiro.so/blog/what-does-lightnings-taro-proposal-mean-for-stacks). - - -## Is Stacks a [PoS chain](https://en.wikipedia.org/wiki/Proof_of_stake)?[¹][] - -No. - -The act of block production requires an extrinsic expenditure — it is not tied to owning the native token, as would be required in PoS. The only way to produce blocks in the Stacks chain is to transfer Bitcoin to a predetermined randomized list of Bitcoin addresses. Moreover, the Stacks blockchain can fork, and there exists a protocol to rank forks by quality independent of the set of miners and the tokens they hold. These two properties further distinguish it from PoS chains, which cannot fork due to the inability to identify a canonical fork without trusting a 3rd party to decree a particular fork as valid. The ability to fork allows the Stacks blockchain to survive failure modes that would crash a PoS chain. - -## Is Stacks a [sidechain](https://en.bitcoin.it/wiki/Sidechain)?[¹][] - -No. - -For two key reasons. - -First, the history of all Stacks blocks produced is recorded to Bitcoin. This means that the act of producing a private Stacks fork is at least as hard as reorging the Bitcoin chain. This in turn makes it so attacks on the chain that rely on creating private forks (such as selfish mining and double-spending) are much harder to carry out profitably, since all honest participants can see the attack coming before it happens and have a chance to apply countermeasures. Sidechains offer no such security benefit. - -Second, the Stacks blockchain has its own token; it does not represent pegged Bitcoin. This means that the safety of the canonical fork of the Stacks blockchain is underpinned by its entire token economy’s value, whereas the safety of a sidechain’s canonical fork is underpinned only by whatever system-specific measures incentivize its validators to produce blocks honestly, or the Bitcoin miners’ willingness to process peg-in requests (whichever is the weaker guarantee). - - -## Is Stacks a [layer-2 system](https://academy.binance.com/en/glossary/layer-2) for Bitcoin?[¹][] - -No. - -Stacks blockchain is a layer-1 blockchain, which uses a novel and unique mining protocol called proof-of-transfer (PoX). A PoX blockchain runs in parallel to another blockchain (Bitcoin in Stacks’ case), which it uses as a reliable broadcast medium for its block headers. It's a sovereign system in its own right. The Stacks blockchain state is distinct from Bitcoin, and is wholly maintained by and for Stacks nodes. Stacks transactions are separate from Bitcoin transactions. Layer-2 systems like Lightning are designed to help scale Bitcoin payment transactions, whereas Stacks is designed to bring new use-cases to Bitcoin through smart contracts. Stacks is not designed as a Bitcoin layer-2 scalability solution. - - -## Is Stacks a [merged-mined chain](https://en.bitcoin.it/wiki/Merged_mining_specification)?[¹][] - -No. - -The only block producers on the Stacks chain are Stacks miners. Bitcoin miners do not participate in Stacks block validation, and do not claim Stacks block rewards. Moreover, Stacks is not a [blind merged-mined chain](https://github.com/bitcoin/bips/blob/master/bip-0301.mediawiki), because STX block winners are public and randomly chosen (instead of highest-bid-wins), and its tokens are minted according to a schedule that is independent of the degree of miner commitment or Bitcoin transferred (instead of minted only by one-way pegs from Bitcoin). This ensures that Stacks is able to make forward progress without opt-in from Bitcoin miners, and it ensures that Stacks miners are adequately compensated for keeping the system alive regardless of transaction volume. - -## Whats the difference between Stacks and Ethereum?[²][] -**Computation and Storage** Stacks does all computation and storage outside of the blockchain, and uses the blockchain only as a “shared source of truth” between clients. By contrast, Ethereum does all computation and most application storage in the blockchain itself. Like Ethereum, if two Stacks nodes see the same underlying blockchain, they will independently run the same computations and produce the same state. Unlike Ethereum, there is no Stacks-specific blockchain. - -**Programming Language and Tooling** Stacks’s programming model is based on running off-chain programs. These programs can be written and debugged in any language you want. By contrast, Ethereum’s programming model is based on running on-chain “smart contracts.” These are written and debugged with a whole new set of tools, like Solidity and Serpent. - -**Scalability of On-chain Computation** Stacks is designed around a “virtual chain” concept, where nodes only need to reach consensus on the shared “virtual chain” they’re interested in. Virtual chains do not interact with one another, and a single blockchain can host many virtual chains. Although Stacks’s specific virtual chain is not Turing-complete (i.e. it’s a list of instructions to build the name database), it is possible to create Turing-complete virtual chains like Ethereum. These virtual chains can live in any blockchain for which there exists a driver, and virtual chain clients only need to execute their virtual chain transactions (i.e. Stacks only processes Stacks virtual chain transactions). - -By contrast, because smart contracts run on-chain and can call one another, all Ethereum nodes need to process all smart contracts’ computations in order to reach consensus. This can get expensive as the number of running smart contracts grow, which takes the form of gas fee increases. - -**Scalability of Off-chain Computation** Stacks applications are very similar to Web applications today and almost never need to interact with the blockchain. For most Stacks applications, the blockchain is only used to authenticate the application’s code and data before the user runs it. By contrast, Ethereum applications usually require an application-specific smart contract, and must interact with the blockchain to carry out its operations. - - -[¹]: https://stacks.org/stacks-blockchain -[²]: https://forum.stacks.org/t/what-is-the-difference-between-blockstack-and-ethereum/781 diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/gaia/configuration.md b/i18n/ru/docusaurus-plugin-content-docs/current/gaia/configuration.md deleted file mode 100644 index a6a530cd70..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/gaia/configuration.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Configuration -description: Configuring Gaia Hub ---- - -## Configuration files - -The following configuration files exist in the folder `deploy/configs/gaia/`: - -``` -admin-config.json -hub-config.json -reader-config.json -``` - -## GAIA Admin Service - -You can also use the GAIA Admin Service to remotely administer it with an API Key. It will require you to install `npm` with a `apt install npm`. Once `npm` is installed you can continue with the steps in the [GAIA Admin Service](https://github.com/stacks-network/gaia/blob/master/admin/README.md). - -## Driver Selection - -The Gaia hub currently supports the following drivers: - -``` -'aws' == Amazon S3 -'azure' == Azure Blob Storage -'disk' == Local disk -'google-cloud' === Google Cloud Storage -``` - -Set the driver you wish to use in your [config.json](https://github.com/stacks-network/gaia/blob/master/hub/config.sample.json) file with the `driver` parameter. Many drivers additionally accept the `bucket` parameter, which controls the bucket name that files should be written to. - -These driver may require you to provide additional credentials for performing writes to the backends. See `config.sample.json` for fields for those credentials. In some cases, the driver can use a system configured credential for the backend (e.g., if you are logged into your AWS CLI account, and run the hub from that environment, it won't need to read credentials from your `config.json`). - -_Note:_ The disk driver requires a \*nix like filesystem interface, and will not work correctly when trying to run in a Windows environment. ::: - -## Note on SSL - -We _strongly_ recommend that you deploy your Gaia hub with SSL enabled. Otherwise, the tokens used to authenticate with the Gaia hub may be stolen by attackers, which could allow them to execute writes on your behalf. -Configuration options are available to run the hub with an `https` Node.js server. -Otherwise, a reverse proxy web server such as nginx or Apache can be used. - -## Require Correct Hub URL - -If you turn on the `requireCorrectHubUrl` option in your `config.json` file, your Gaia hub will require that authentication requests correctly include the `hubURL` they are trying to connect with. This is used to prevent a malicious gaia hub from using an authentication token for itself on other Gaia hubs. - -By default, the Gaia hub will validate that the supplied URL matches `https://${config.serverName}`, but if there are multiple valid URLs for clients to reach the hub at, you can include a list in your `config.json`: - -```javascript -{ - .... - serverName: "normalserver.com" - validHubUrls: [ "https://specialserver.com/", - "https://legacyurl.info" ] - .... -} -``` - -## The readURL parameter - -By default, the gaia hub drivers will return read URLs which point directly at the written content. For example, an S3 driver would return the URL directly to the S3 file. However, if you configure a CDN or domain to point at that same bucket, you can use the `readURL` parameter to tell the gaia hub that files can be read from the given URL. For example, the `hub.blockstack.org` Gaia Hub is configured to return a read URL that looks like `https://gaia.blockstack.org/hub/`. - -Unset this configuration parameter if you do not intend to deploy any caching. - -## Minimum Proofs Requirement - -The gaia hub can also be configured to require a minimum number of social proofs in a user's profile to accept writes from that user. This can be used as a kind of spam-control mechanism. However, we recommend for the smoothest operation of your gaia hub, to set the `proofsConfig.proofsRequired` configuration key to `0`. - -## CDN & Replicated Hubs - -- https://docs.microsoft.com/en-us/azure/storage/blobs/storage-https-custom-domain-cdn - -- The hub implementation is designed to be ran from a single Node.js instance. If the hub instance is sharded (e.g. replicated hubs via load balancing), then any given `bucket` (identified by URI segment) must be served by the same instance, At least a couple elements of the Gaia Hub depend on this: token invalidation in-memory caching, and resource endpoint 409 contention behavior. diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md b/i18n/ru/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md deleted file mode 100644 index 558cbb14f5..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Deploy Gaia Hub -description: Steps and tutorials ---- - -## Deploy your GAIA hub - -Tutorials to deploy your own GAIA hub are currently available for [Linux](./setup-linux), [MacOS](./setup-mac) and [Amazon EC2 / CloudFormation](./gaia-on-ec2). - -Regardless of what server the Gaia Hub runs on, the storage it uses can currently be deployed on multiple platforms: - -- Local disk (the server itself) -- Amazon S3 -- Azure Blob Storage -- Google Cloud - -:::tip -Support for IPFS is under development. -::: \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md b/i18n/ru/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md deleted file mode 100644 index 2067e7d57c..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Amazon EC2 -description: Use a template to deploy a Gaia hub on Amazon EC2 -tags: - - tutorial - - gaia ---- - -## Introduction - -The template provided on this page provides an easy way to deploy a Gaia hub directly to Amazon EC2. You can use this template to deploy your own Gaia hub to your Amazon Web Services (AWS) account. Amazon EC2 is an affordable and convenient cloud computing provider. The template provides a one-click deploy for Amazon EC2 with either S3 or EBS as a storage provider. - -## Prerequisites - -This procedure uses Amazon CloudFormation to configure an EC2 cloud compute provider to run the Gaia hub service with an S3 or EBS provider for file storage. You should have access to an AWS account either through your personal account or through a corporate account. This account should have permissions to create resources. - -Additionally, you must also own a domain name and be able to update the DNS records associated with that domain name. - -## Setup steps - -### Step 1 - Create Stack - -Use a link in the table to launch the [CloudFormation](https://console.aws.amazon.com/cloudformation/) template in the AWS region that you wish to deploy a Gaia hub. - -![Create stack](/img/cloudformation-create-stack.png) - -### Step 2 - Setup stack using template - -You need to configure the template with the appropiate values for your hub and domain it runs on. - -Select `Template is ready` and `Amazon S3 URL` and enter the following Amazon S3 URL: -``` -https://s3-external-1.amazonaws.com/cf-templates-vzldibfi2mw8-us-east-1/2022160J6G-cloudformation.yaml -``` - -If you prefer you can instead select `Template is ready` and `Upload a template file` to upload the template file `cloudformation.yaml`. - -The latest `cloudformation.yaml` file can be downloaded [here](https://raw.githubusercontent.com/stacks-network/gaia/master/deploy/cloudformation.yaml). On most browsers you can right-click on that page and click on `Save page as` to download the file. Alternatively, you can copy/paste the text into a text file called `cloudformation.yaml`. - -Then click `Next`. - -![Specify template](/img/cloudformation-specify-template.png) - -### Step 3 - Specify stack details - -Specify the stack details and then click `Next`: ![Specify template](/img/cloudformation-specify-stack-details.png) - -| Field | Value | Notes | -| --------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Stack name | _a unique name in your AWS account_ | e.g.: my_gaia_hub | -| DomainName | _your-domain_ | | -| EmailAddress | _your email address_ | | -| GaiaBucketName | _S3 bucket name_ | The template combines this name with the stack name to create a unique S3 bucket. The template ignores this field if GaiaStorageType is set to `disk`. | -| GaiaStorageType | `s3` or `disk` | Select the GaiaStorageType of which to use as a backend for the Gaia Hub. Selecting `s3` causes the template to create an S3 bucket based on the name given in the previous field. Selecting `disk` causes the template to attach a separate EBS volume to the EC2 instance for Hub storage. | -| InstaceType | t2.micro | Select the instance type you want. Default value is `t2.micro`. | -| KeyName | | In the KeyName drop-down, select an [EC2 KeyPair](https://console.aws.amazon.com/ec2/v2/home?region=us-east-1#KeyPairs:) to enable SSH access to the EC2 instance. You should download the `.pem` keyfile for this pair from the EC2 console. For more information see the [EC2 key pair documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html#prepare-key-pair) | -| SSHLocation | 0.0.0.0/0 | Leave the SSHLocation field with the default value of `0.0.0.0/0` to enable SSH access from any IP address. If you wish to restrict SSH access to the EC2 instance to a certain IP, you can update this field. | -| SubnetId | _subnetid_ | Select a public subnet | -| VpcId | _vpcid_ | | - -### Step 4 - Configure stack options - -Configure any stack options that fit your desired setup and click `Next`. All these fields are optional. - -![Specify template](/img/cloudformation-stack-options.png) - -### Step 5 - Review - -Review the configuration of your Gaia hub, select the checkbox to acknowledge that AWS may create IAM resources with custom names and click on `Create stack`. - -![Specify template](/img/cloudformation-iam-resources.png) - -### Step 6 - Retrieve the public IP of your Gaia hub - -Your stack can take several minutes to launch. You can monitor the Events tab of your hub to review the current progress of the launch. When the launch is complete, the Outputs tab displays information about the hub. Select the PublicIP and copy it to configure your domain name. - -Create an `A` DNS record pointing to the given IP in your domain. - -Wait a few minutes for the DNS record to propagate, and your should be able to access your Gaia hub with SSH. - -## Accessing your Gaia hub with SSH - -To SSH into your Gaia hub EC2 host directly, you must have the keyfile used in container creation. Access the host with the following command in your terminal: - -```bash -ssh -i admin@ -``` - -:::tip If you can only access SSH with the IP but not with the DNS name and you wish to do so, you can optionally activate it by following these steps: - - Open your [AWS Console](https://console.aws.amazon.com) - Click on `Service` -> VPC - Open Your VPCs - Select your VPC connected to your Gaia Hub - Click `Actions` -> `Edit DNS Hostnames` -> Change `DNS hostnames` to `Enable` -::: -## Graphical representation of the cloudformation template - -![](/img/cloudformation-gaia-template1-designer.png) \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/gaia/gaia.md b/i18n/ru/docusaurus-plugin-content-docs/current/gaia/gaia.md deleted file mode 100644 index 1070857350..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/gaia/gaia.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Gaia -description: Decentralized storage architecture for off-chain data -sidebar_position: 5 -tags: - - gaia ---- - -## Introduction - -Apps built with the Stacks blockchain store off-chain data using a storage system called Gaia. - -Whereas public transactional metadata is best stored on the Stacks blockchain, user application data can often be stored more efficiently and privately in Gaia storage. - -Storing data off of the blockchain ensures that Stacks applications can provide users with high performance and high availability for data reads and writes without introducing central trust parties. - -:::tip Latest whitepaper of GAIA (May 2022) is available [here](https://dev1-gaia-hub.s3.amazonaws.com/GAIA_Whitepaper.pdf) ::: - -## Understand Gaia in the Stacks architecture - -The following diagram depicts the Stacks architecture and Gaia's place in it: - -![Stacks Architecture](/img/architecture.png) - -Blockchains require consensus among large numbers of people, so they can be slow. Additionally, a blockchain is not designed to hold a lot of data. This means using a blockchain for every bit of data a user might write and store is expensive. For example, imagine if an application were storing every tweet in the chain. - -The Stacks blockchain addresses performance problems using a layered approach. The base layer consists of the Stacks blockchain and the Blockchain Naming System (BNS). The blockchain governs ownership of identities in the Stacks network. Identities can be names such as domain names, usernames, or application names. - -When an identity is created, its creation is recorded in the Stacks blockchain. Identities make up the primary data stored into the Stacks blockchain. These identities correspond to routing data in the OSI stack. The routing data is stored in the Atlas Peer Network, the second layer. Every core node that joins the Stacks Network is able to obtain an entire copy of this routing data. Stacks uses the routing data to associate identities (domain names, user names, and application names) with a particular storage location in the final layer, the Gaia Storage System. - -A Gaia Storage System consists of a _hub service_ and storage resource on a cloud software provider. The storage provider can be any commercial provider such as Azure, DigitalOcean, Amazon EC2, and so forth. Typically the compute resource and the storage resource reside same cloud vendor, though this is not a requirement. Gaia currently has driver support for S3, Azure Blob Storage, Google Cloud Platform and local disk, but the driver model allows for other backend support as well. - -Gaia stores data as a simple key-value store. When an identity is created, a corresponding data store is associated with that identity on Gaia. When a user logs into a dApp, the authentication process gives the application the URL of a Gaia hub, which then writes to storage on behalf of that user. - -The Stacks blockchain stores only identity data. Data created by the actions of an identity is stored in a Gaia Storage System. Each user has profile data. When a user interacts with a decentralized dApp that application stores application data on behalf of the user. Because Gaia stores user and application data off the blockchain, a Stacks DApp is typically more performant than DApps created on other blockchains. - -## User control or how is Gaia decentralized? - -A Gaia hub runs as a service which writes to data storage. The storage itself is a simple key-value store. The hub service writes to data storage by requiring a valid authentication token from a requestor. Typically, the hub service runs on a compute resource and the storage itself on separate, dedicated storage resource. Typically, both resources belong to the same cloud computing provider. - -![Gaiastorage](/img/gaia-storage.png) - -Gaia's approach to decentralization focuses on user control of data and its storage. Users can choose a Gaia hub provider. If a user can choose which Gaia hub provider to use, then that choice is all the decentralization required to enable user-controlled applications. Moreover, Gaia defines a uniform API for applications to access that data. - -The control of user data lies in the way that user data is accessed. When an application fetches a file `data.txt` for a given user `alice.id`, the lookup will follow these steps: - -1. Fetch the `zonefile` for `alice.id`. -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. Find the read-only url out of the profile's `appsMeta` section (e.g. `https://example-app.gaia.alice.org`). -6. Fetch the file from `https://example-app.gaia.alice.org/data.txt`. - -Because `alice.id` has access to her [zonefile](https://docs.stacks.co/references/bns-contract#name-update), 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. - -:::caution -Users with existing identities cannot yet migrate their data from one hub to another. -::: - -Applications writing directly on behalf of `alice.id` do not need to perform a lookup. Instead, the [Stacks authentication flow](https://stacks.js.org) provides Alice's chosen gaia hub URL to the application. This authentication flow _is also_ within Alice's control because Alice's wallet _must_ generate the authentication response. - -## Understand data storage - -A Gaia hub stores the written data _exactly_ as given. It offers minimal guarantees about the data. It does not ensure that data is validly formatted, contains valid signatures, or is encrypted. Rather, the design philosophy is that these concerns are client-side concerns. - -Client libraries (such as [`Stacks.js`](https://stacks.js.org/)) are capable of providing these guarantees. A liberal definition of the [end-to-end principle](https://en.wikipedia.org/wiki/End-to-end_principle) guides this design decision. - -When an application writes to a Gaia hub, an authentication token, key, and the data are passed to the Gaia hub. - -![Gaia writes](/img/gaia-writes.png) - -The token ensures the app has the authorization to write to the hub on the user's behalf. - -## Gaia versus other storage systems - -Here's how Gaia stacks up against other decentralized storage systems. Features that are common to all storage systems are omitted for brevity. - -| Features | [Gaia](https://github.com/stacks-network/gaia) | [Sia](https://sia.tech/) | [Storj](https://storj.io/) | [IPFS](https://ipfs.io/) | [DAT](https://datproject.org/) | [SSB](https://www.scuttlebutt.nz/) | -| ------------------------------------------ | ---------------------------------------------- | ------------------------ | -------------------------- | ------------------------ | ------------------------------ | ---------------------------------- | -| User controls where data is hosted | X | | | | | | -| Data can be viewed in a normal Web browser | X | | | X | | | -| Data is read/write | X | | | | X | X | -| Data can be deleted | X | | | | X | X | -| Data can be listed | X | X | X | | X | X | -| Deleted data space is reclaimed | X | X | X | X | | | -| Data lookups have predictable performance | X | | X | | | | -| Writes permission can be delegated | X | | | | | | -| Listing permission can be delegated | X | | | | | | -| Supports multiple backends natively | X | | X | | | | -| Data is globally addressable | X | X | X | X | X | | -| Needs a cryptocurrency to work | | X | X | | | | -| Data is content-addressed | | X | X | X | X | X | diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/gaia/setup-linux.md b/i18n/ru/docusaurus-plugin-content-docs/current/gaia/setup-linux.md deleted file mode 100644 index db427f890a..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/gaia/setup-linux.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: Linux -description: Steps to setup a GAIA hub on a Linux server (fresh install). This example is using Debian, but should work on any Linux distribution. It uses docker compose in the backgroud. -tags: - - tutorial - - gaia ---- - -This configuration will setup the following 4 docker containers: - -- Nginx with certbot on TCP ports 80 and 443. -- Gaia hub on TCP port 3000. -- Gaia admin on TCP port 8009. -- Gaia reader on TCP port 8008 - -**1. Update the system and install the dependencies and software we will use to test:** - -```bash -apt update && apt upgrade -y && apt install -y git vim gnupg jq -``` - -**2. Install [docker](https://docs.docker.com/engine/install/debian/) and [docker-compose](https://docs.docker.com/compose/cli-command/#install-on-linux)** in your OS. -For our example we install _docker_ with: - -```bash -curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg - -echo \ - "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian \ - $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null - -apt update && apt install -y docker-ce docker-ce-cli containerd.io -``` - -Install _docker-compose_ by downloading the [latest-release](https://github.com/docker/compose/releases): - -```bash -VERSION_DC=$(curl --silent https://api.github.com/repos/docker/compose/releases/latest | jq .name -r) -DESTINATION_DC=~/.docker/cli-plugins -mkdir -p ${DESTINATION_DC} -curl -SL https://github.com/docker/compose/releases/download/${VERSION_DC}/docker-compose-linux-x86_64 -o ${DESTINATION_DC}/docker-compose -chmod +x ${DESTINATION_DC}/docker-compose -``` - -**3. Clone the GAIA repository** and enter it's docker directory. - -```bash -git clone https://github.com/stacks-network/gaia.git && cd gaia/deploy/docker -``` - -**4. Copy and edit appropiate .env file**. -In the folder `./deploy/docker/` they are different sample files for different configurations like using aws, azure or disk among others. In this example we will store the data localy so we will copy the _disk_ file and update the domain and email fields. Please change `gaia.site.com` and `gaiarocks@mydomain.com` accordingly. Note you need both for the SSL certificate to be created correctly. - -```bash -export MYGAIADOMAIN=gaia.site.com -export MYGAIAEMAIL=gaiarocks@mydomain.com -cp sample-disk.env disk.env -sed -i 's/my-domain.com/'"$MYGAIADOMAIN"'/g' disk.env -sed -i 's/my-email@example.com/'"$MYGAIAEMAIL"'/g' disk.env - -``` - -**5. Start GAIA HUB service** - -To start GAIA HUB - -```bash -./gaiahub.sh start -``` - -To stop GAIA HUB - -```bash -./gaiahub.sh stop -``` - -To view GAIA HUB status - -```bash -./gaiahub.sh status -``` - -**6. Verify server works locally** with the following command: - -```bash -curl -sk http://localhost/hub_info | jq -``` - -A correct result should look similar to this: - -```bash - { - "challenge_text": "[\"gaiahub\",\"0\",\"gaia-0\",\"blockstack_storage_please_sign\"]", - "latest_auth_version": "v1", - "max_file_upload_size_megabytes": 20, - "read_url_prefix": "https://gaia.site.com/reader/" - } -``` - -**7. Test your GAIA HUB** Running `gaia_test.js` will test your GAIA Hub, by trying to connect to it, uploading a file and downloading it again. - -First install all required dependencies with: - -```bash -npm install -``` - -Then, from the root folder of the project type: - -```bash -node ./deploy/gaia_test.js https://yourgaiaurl -``` - -A correct result will be something like this: - -``` -Will run a test for the GAIA HUB: https://gaia.mydomain.com -Generating some test keys... -Private key: 5aacc60fc2a429e1f02be139f3cac82061c6a980******************** -Public key: 025691f17f2ab80dc4af363bb9c7aac59e9e1db6ae8ff668202582a3f4ec9678ff -Address: 15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS -[DEBUG] connectToGaiaHub: https://gaia.mydomain.com/hub_info -[DEBUG] uploadToGaiaHub: uploading testing.txt to https://gaia.mydomain.com -File uploaded successfully. -Upload to gaia hub thinks it can read it from: https://gaia.mydomain.com/reader/15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS/testing.txt -Hub info thinks it can read it from : https://gaia.mydomain.com/reader/15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS/testing.txt -Let's now try to fetch the uploaded file... -File fetched successfully. Contents of file: GAIA ROCKS! -``` diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/gaia/setup-mac.md b/i18n/ru/docusaurus-plugin-content-docs/current/gaia/setup-mac.md deleted file mode 100644 index 808833b212..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/gaia/setup-mac.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: MacOS -description: MacOS for local testing/development -tags: - - tutorial ---- - -The following assumes you have [Docker Installed](https://docs.docker.com/docker-for-mac/install/) - -- Recommended to also have [MacOS Homebrew](https://docs.brew.sh/Installation) installed -- Use Homebrew to install jq with `brew install jq` - -In your working directory: - -**1. Clone a copy of the [gaia repo](https://github.com/stacks-network/gaia):** - -```bash -$ git clone -b master --single-branch https://github.com/stacks-network/gaia -``` - -**2. Change your cwd:** - -```bash -$ cd gaia/deploy/docker -``` - -**3. Create a copy of sample-disk.env and fill out the values:** - -``` -$ cp sample-disk.env disk.env -# Update the DOMAIN_NAME variable to `localhost` -``` - -**4. Start the server:** - -``` -$ docker-compose -f docker-compose-base.yaml -f docker-compose-disk.yaml --env-file disk.env up -``` - -**5. Verify the server is responding locally:** - -``` -$ curl -sk https://localhost/hub_info | jq - { - "challenge_text": "[\"gaiahub\",\"0\",\"gaia-0\",\"blockstack_storage_please_sign\"]", - "latest_auth_version": "v1", - "max_file_upload_size_megabytes": 20, - "read_url_prefix": "https://localhost/reader/" - } -``` - -### Modifying the configuration for your gaia-hub - -Two methods exist: - -1. Edit the `gaia/deploy/configs/gaia/hub-config.json` using `vim` or other - -- requires a restart of the containers: `docker-compose -f docker-compose-base.yaml -f docker-compose-disk.yaml --env-file disk.env restart` - -2. Use the running `admin` container to modify any config values, and also reload the hub when complete: - -- [GitHub - Gaia Admin README.md](https://github.com/stacks-network/gaia/blob/master/admin/README.md) - -``` -$ export API_KEY="hello" -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - -H 'Content-Type: application/json' \ - -X POST \ - --data-raw '{"serverName": "myserver"}' \ - http://localhost:8009/v1/admin/config - -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - -X POST \ - http://localhost:8009/v1/admin/reload - -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - http://localhost:8009/v1/admin/config | jq -``` diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/governance/_index.md b/i18n/ru/docusaurus-plugin-content-docs/current/governance/_index.md deleted file mode 100644 index 1ecdf67871..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/governance/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Governance -description: Governance -sidebar_position: 9 ---- - -This page needs contributions. Help us write it! \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/governance/index.md b/i18n/ru/docusaurus-plugin-content-docs/current/governance/index.md deleted file mode 100644 index 91b0215b5f..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/governance/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Governance -description: Governance -sidebar_position: 9 ---- - -![](/img/stacks-governance.png) - -This page needs contributions. Help us write it! - -Governance in web3 is driven by the community. - -How can I get involved ? - -[Governance Resources website](https://resources.stacksgov.com) - -[Github - Stack Community Governance](https://github.com/stacksgov) - -:::tip Community Calls Monthly community calls are recorded and available [here](https://www.youtube.com/playlist?list=PLg717Ri_rTnwwYjQYlc7rIP6x2FaTNn7f) ::: diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/governance/sips.md b/i18n/ru/docusaurus-plugin-content-docs/current/governance/sips.md deleted file mode 100644 index 29ac1ae1ed..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/governance/sips.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: SIPs -description: SIPs -sidebar_position: 9 ---- - -## Stacks Improvement Proposals (SIPs) - -Stacks improvement proposals (SIPs) are aimed at describing the implementation of the Stacks blockchain, as well as proposing improvements. - -The SIP process [(SIP-000)](https://github.com/stacksgov/sips/blob/main/sips/sip-000/sip-000-stacks-improvement-proposal-process.md) describes how to make a SIP and get it ratified. - -They should contain concise technical specifications of features or standards and the rationale behind it. SIPs are intended to be the primary medium for proposing new features, for collecting community input on a system-wide issue, and for documenting design decisions. - -The SIPs are located in the [stacksgov/sips](https://github.com/stacksgov/sips) repository as part of the [Stacks Community Governance organization](https://github.com/stacksgov). - -Anyone in the Stacks community can submit a SIP. - -:::tip Stacks Improvement Proposals Community Calls SIP Meeting calls are recorded and available [here](https://www.youtube.com/playlist?list=PLg717Ri_rTnx5kuaWqp3cUAtwQk_yzslT) - -More details of the meetings are available [here](https://github.com/stacksgov/sips/issues/79) ::: - -## Ratified SIPSs - -- [x] [SIP 001: Burn Election](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md) -- [x] [SIP 002: Clarity, a language for predictable smart contracts](https://github.com/stacksgov/sips/blob/main/sips/sip-002/sip-002-smart-contract-language.md) -- [x] [SIP 003: Peer Network](https://github.com/stacksgov/sips/blob/main/sips/sip-003/sip-003-peer-network.md) -- [x] [SIP 004: Cryptographic Committment to Materialized Views](https://github.com/stacksgov/sips/blob/main/sips/sip-004/sip-004-materialized-view.md) -- [x] [SIP 005: Blocks, Transactions, and Accounts](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md) -- [x] [SIP 006: Clarity Execution Cost Assessment](https://github.com/stacksgov/sips/blob/main/sips/sip-006/sip-006-runtime-cost-assessment.md) -- [x] [SIP 007: Stacking Consensus](https://github.com/stacksgov/sips/blob/main/sips/sip-007/sip-007-stacking-consensus.md) -- [x] [SIP 008: Clarity Parsing and Analysis Cost Assessment](https://github.com/stacksgov/sips/blob/main/sips/sip-008/sip-008-analysis-cost-assessment.md) -- [x] [SIP 009: Standard Trait Definition for Non-Fungible Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-009/sip-009-nft-standard.md) -- [x] [SIP 010: Standard Trait Definition for Fungible Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-010/sip-010-fungible-token-standard.md) -- [x] [SIP 012: Burn Height Selection for a Network Upgrade to Introduce New Cost-Limits](https://github.com/stacksgov/sips/blob/main/sips/sip-012/sip-012-cost-limits-network-upgrade.md) -- [x] [SIP-016: Metadata for Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-016/sip-016-token-metadata.md) - -## How to Get Involved - -There are several ways you can get involved with the SIP process: - -* **Join the weekly SIP Meeting call** listed [here](https://community.stacks.org/events). - -* **SIP Editor**. SIP editors help SIP authors make sure their SIPs are well-formed and follow the right process. They help get SIPs ready for deep review by advancing it them from Draft to Accepted status. If you want to become a SIP editor, open an issue with your name and email to ask to be added to the list of SIP editors. - -* **Join a CAB** (Consideration Advisory Board). SIPs fall under the purview of one or more considerations. A full list is in [this github](https://github.com/stacksgov/sips/tree/main/considerations) directory. Currently they are: Diversity, Economics, Ethics, Governance and Technical. Members of SIP consideration advisory boards use their domain expertise to give Accepted SIPs a deep read, and give the authors any/all feedback to help make the SIP workable. If you want to join a board, reach out to the board's chairperson via the listed contact information. - -* **Steering Committee**. The Steering Committee organizes the consideration advisory boards and votes to advance Recommended SIPs to Activation-in-Progress status, and then to either Ratified or Rejected status. Once they are in the process of being activated, they use a SIP's Activation section to determine whether or not the Stacks ecosystem has ratified or rejected the SIP. Joining this committee requires the consent of the Stacks Foundation board. diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/intro.md b/i18n/ru/docusaurus-plugin-content-docs/current/intro.md deleted file mode 100644 index 84f1eaa649..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/intro.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_label: "Home" -sidebar_position: 1 ---- - -# Stacks Docs Introduction - -Welcome to the community driven official Stacks Documentation. - -Learn about Stacks mining, the STX token, and the Clarity smart contract language. - -![](/img/Bitcoinet-L_2.svg) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md b/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md deleted file mode 100644 index dd7194f504..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Stacks on DigitalOcean -description: A guide to setup Stacks on DigitalOcean -sidebar_position: 4 -tags: - - tutorial ---- - -## Introduction - -This is a step by step guide to deploy the [Stacks Blockchain on DigitalOcean](https://marketplace.digitalocean.com/apps/stacks-blockchain). Code is hosted on this [Github repository](https://github.com/stacks-network/stacks-blockchain-docker). - -## Steps - -#### Step 1 - -Go to the [Stacks Blockchain page](https://marketplace.digitalocean.com/apps/stacks-blockchain) in DigitalOcean's marketplace. Click on `Create Stacks Blockchain Droplet`. - -#### Step 2 - -Choose a plan (it will only allow you to select a plan that meets the minimum requirements) and your prefered datacenter region. ![](/img/sh_digitalocean-choose-plan.png) - -#### Step 3 - -Enter a root password or enable SSH keys if your prefer. - -![](/img/sh_digitalocean-choose-authentication.png) - -#### Step 4 - -You can leave the rest of the options as they are and click on `Create Droplet` - -#### Step 5 - -You will need to wait a few seconds for the droplet to get created. Once created click on it to see more information. - -![](/img/sh_digitalocean-creating-droplet.png) - -![](/img/sh_digitalocean-created-droplet.png) - -### Step 6 - -Congratulations! You are now running the Stacks Blockchain. You can click on `Console` for a terminal window to open or login using SSH to the public IP you've been assigned to with user `root`. - -![](/img/sh_digitalocean-console-button.png) ![](/img/sh_digitalocean-console.png) - -## Getting started after deploying Stacks Blockchain - -Once droplet is launched, initial startup can take several minutes while BNS data is imported (this is a one time operation). - -To keep track of the progress, you can `ssh root@your_droplet_public_ipv4` to the host and run: `/opt/stacks-blockchain-docker/manage.sh -n mainnet -a logs`. - -Once the stacks blockchain starts to sync with peers, application ports will open and nginx port 80 will now start proxying requests. - -Use `http://your_droplet_public_ipv4` to access the data directly, with output being similar to: - -```json -{ - "server_version": "stacks-blockchain-api v3.0.3 (master:cd0c8aef)", - "status": "ready", - "chain_tip": { - "block_height": 16220, - "block_hash": "0x3123fba9c0de6b569573494cf83c1d5d198a66bfd5f48ef97949b6bf11ba13be", - "index_block_hash": "0xeec960fbbd6186b4ccac85ce12adba72be497d881f81e077305c90955b51a6ae" - } -} -``` - -All services are managed by a [systemd unit file](https://github.com/stacksfoundation/stacks-machine-images/blob/master/files/etc/systemd/system/stacks.service) that is set to start on boot. - -Manual control is also possible via the [manage.sh script](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/manage.sh) at `/opt/stacks-blockchain-docker/manage.sh` on the host. - -Full details on how to use the manage.sh script is [available here](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/README.md#quickstart). - -## API Creation - -In addition to creating a Droplet from the Stacks Blockchain 1-Click App via the control panel, you can also use the [DigitalOcean API](https://digitalocean.com/docs/api). - -As an example, to create a 4GB Stacks Blockchain Droplet in the SFO2 region, you can use the following curl command. You’ll need to either save your [API access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/) to an environment variable or substitute it into the command below. - -```bash -curl -X POST -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer '$TOKEN'' -d \ - '{"name":"choose_a_name","region":"sfo2","size":"s-2vcpu-4gb","image":"stacksfoundation-stacksblockchain"}' \ - "https://api.digitalocean.com/v2/droplets" -``` diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md b/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md deleted file mode 100644 index b6cbb9754a..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Nodes and Miners -description: Nodes and Miners -sidebar_position: 7 ---- - -Here are all the steps to run nodes and miners, both on mainnet and testnet. - -## What's a Stacks node? - -## What's a Stacks miner? diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md b/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md deleted file mode 100644 index 40397a51e0..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Miner costs and fees -description: Miner Cost and Fee Estimation -sidebar_position: 8 ---- - -## Configuring Cost and Fee Estimation - -Fee and cost estimators can be configured via the config section `[fee_estimation]`: - -``` -[fee_estimation] -cost_estimator = naive_pessimistic -fee_estimator = fuzzed_weighted_median_fee_rate -fee_rate_fuzzer_fraction = 0.1 -fee_rate_window_size = 5 -cost_metric = proportion_dot_product -log_error = true -enabled = true -``` - -Fee and cost estimators observe transactions on the network and use the observed costs of those transactions to build estimates for viable fee rates and expected execution costs for transactions. Estimators and metrics can be selected using the configuration fields above, though the default values are the only options currently. `log_error` controls whether or not the INFO logger will display information about the cost estimator accuracy as new costs are observed. Setting `enabled = false` turns off the cost estimators. Cost estimators are **not** consensus-critical components, but rather can be used by miners to rank transactions in the mempool or client to determine appropriate fee rates for transactions before broadcasting them. - -The `fuzzed_weighted_median_fee_rate` uses a median estimate from a window of the fees paid in the last `fee_rate_window_size` blocks. Estimates are then randomly "fuzzed" using uniform random fuzz of size up to `fee_rate_fuzzer_fraction` of the base estimate. diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md b/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md deleted file mode 100644 index 061f4a2511..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md +++ /dev/null @@ -1,343 +0,0 @@ ---- -title: Mine mainnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 mainnet -sidebar_position: 5 -tags: - - tutorial ---- - -## Introduction - -Make sure you've followed the [run a node](run-a-node) procedure. Once completed it's only a few more steps to run a proof-of-burn miner on the mainnet. - -If you're interested in mining on the testnet, you can find instructions on how to do that [here](miner-testnet): - -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining): - -## Running bitcoind locally - -To participate as a miner on mainnet, you must have access to a mainnet bitcoin node. One way to accomplish this is to run bitcoind locally. [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements) - -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. - -Next, start bitcoind with the following configuration: - -```toml -server=1 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=1 -banscore=1 -bind=0.0.0.0:8333 -rpcbind=0.0.0.0:8332 -rpcport=8332 -``` - -Finally, start bitcoind as follows: - -```bash -bitcoind -conf=path/to/bitcoin.conf -``` - -It may take a few days for the node to synchronize with the Bitcoin mainnet. - -## Running a miner - -First, a keychain needs to be generated. With this keychain, we'll purchase some BTC from a crytpocurrency exchange, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. We'll use the `make_keychain` command. - -```bash -npx @stacks/cli make_keychain 2>/dev/null | json_pp > keychain.txt -``` - -After this runs, you should see some JSON in the new `keychain.txt` file that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -**Don't lose this information** - we'll need to use the `privateKey` field later on. - -The above BTC address will then need to be imported into the BTC network. - -```bash -bitcoin-cli -rpcport=8332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - - - -Once imported, we need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - - - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/mainnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `make_keychain` command. Replace the `seed` field with your private key. Save and close this configuration file. - -To run your miner, run this in the command line: - -```bash -stacks-node start --config=./testnet/stacks-node/conf/mainnet-miner-conf.toml -``` - -Your node should start. It will take some time to sync, and then your miner will be running. - -### Creating an optimized binary - -The steps above are great for trying to run a node temporarily. If you want to host a node on a server somewhere, you might want to generate an optimized binary. To do so, use the same configuration as above, but run: - -```bash -cd testnet/stacks-node -cargo build --release --bin stacks-node -``` - -The above code will compile an optimized binary. To use it, run: - -```bash -cd ../.. -./target/release/stacks-node start --config=./mainnet-miner-conf.toml -``` - -To read more about the technical details of mining on the Stacks 2.0 network, have a look at [the mining guide](../understand-stacks/mining). - -### Enable debug logging - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -STACKS_LOG_DEBUG=1 stacks-node mainnet -``` - -## Running a miner in Windows - -### Prerequisites - -Make sure are [running a node](run-a-node) and [running bitcoind locally](#running-bitcoind-locally) before starting this tutorial. - -### Generate keychain and get mainnet tokens in Windows - -To setup the miner, first we need to generate a keychain. With this keychain, we'll purchase some BTC from a crytpocurrency exchange, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. To get a keychain, the simplest way is to use the `stacks-cli`. - -Generate a keychain: - -```bash -npm install --global @stacks/cli -stx make_keychain > cli_keychain.json -type cli_keychain.json -``` - -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -The above BTC address will then need to be imported into the BTC network. - -```bash -bitcoin-cli -rpcport=8332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - -Once imported, we need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Update configuration file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/mainnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Run the miner - -To start your miner, run this in the command line: - -```bash -stacks-node start --config=testnet/stacks-node/conf/mainnet-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](/img/windows-defender.png) - -Your node should start. It will take some time to sync, and then your miner will be running. - -### Enable debug logging in Windows - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=mainnet-miner-conf.toml -``` - -## Optional: Running with Docker - -Alternatively, you can run the mainnet node with Docker. - -:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: - -### Generate keychain and get tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null -``` - -We need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Update configuration file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/mainnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Start the miner - -:::info The ENV VARS `RUST_BACKTRACE` and `STACKS_LOG_DEBUG` are optional. If removed, debug logs will be disabled ::: - -```bash -docker run -d \ - --name stacks_miner \ - --rm \ - --network host \ - -e RUST_BACKTRACE="full" \ - -e STACKS_LOG_DEBUG="1" \ - -v "$(pwd)/testnet/stacks-node/conf/mainnet-miner-conf.toml:/src/stacks-node/mainnet-miner-conf.toml" \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain:latest \ -/bin/stacks-node start --config /src/stacks-node/mainnet-miner-conf.toml -``` - -You can review the node logs with this command: - -```bash -docker logs -f stacks_miner -``` - -## Optional: Running in Kubernetes with Helm - -In addition, you're also able to run a mainnet node in a Kubernetes cluster using the [stacks-blockchain Helm chart](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). - -Ensure you have the following prerequisites installed on your machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [minikube](https://minikube.sigs.k8s.io/docs/start/) (Only needed if standing up a local Kubernetes cluster) -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [helm](https://helm.sh/docs/intro/install/) - -### Generate keychain and get some tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null -``` - -We need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Install the chart and run the miner - -To install the chart with the release name `my-release` and run the node as a miner: - -```bash -minikube start # Only run this if standing up a local Kubernetes cluster -helm repo add blockstack https://charts.blockstack.xyz -helm install my-release blockstack/stacks-blockchain \ - --set config.node.miner=true \ - --set config.node.seed="replace-with-your-privateKey-from-generate-keychain-step" \ - --set config.burnchain.mode="mainnet" -``` - -You can review the node logs with this command: - -```bash -kubectl logs -l app.kubernetes.io/name=stacks-blockchain -``` - -For more information on the Helm chart and configuration options, please refer to the [chart's homepage](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md b/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md deleted file mode 100644 index 56374190c1..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md +++ /dev/null @@ -1,336 +0,0 @@ ---- -title: Mine testnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 testnet -sidebar_position: 4 -tags: - - tutorial ---- - -## Introduction - -Make sure you've followed the [Run a node](run-a-node) procedure. Once completed it's only a few more steps to run a proof-of-burn miner on the testnet. - -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining). - -## Running bitcoind locally - -To participate as a miner on Testnet, you must have access to a testnet bitcoin node. One way to accomplish this is to run bitcoind locally. [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements) - -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. - -Next, start bitcoind with the following configuration: - -```toml -server=1 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password -testnet=1 -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=1 -banscore=1 - -[test] -bind=0.0.0.0:18333 -rpcbind=0.0.0.0:18332 -rpcport=18332 -``` - -Finally, start bitcoind as follows: - -```bash -bitcoind -conf=path/to/bitcoin.conf -``` - -It may take a few hours for the node to synchronize with the Bitcoin testnet. - -## Running a miner - -First, a keychain needs to be generated. With this keychain, we'll get some testnet BTC from a faucet, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. To get a keychain, the simplest way is to use the `stacks-cli`. - -```bash -npx @stacks/cli make_keychain -t 2>/dev/null | json_pp > keychain.txt -``` - -After this runs, you should see some JSON in the new `keychain.txt` file that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -**Don't lose this information** - we'll need to use the `privateKey` field later on. - -The above BTC address will then need to be imported into the BTC testnet network. - -```bash -bitcoin-cli -rpcport=18332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - -Once imported, we need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). You'll be sent `0.01` testnet BTC to that address. - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/testnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/testnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `make_keychain` command. Replace the `seed` field with your private key. Save and close this configuration file. - -To run your miner, run this in the command line: - -```bash -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. - -### Creating an optimized binary - -The steps above are great for trying to run a node temporarily. If you want to host a node on a server somewhere, you might want to generate an optimized binary. To do so, use the same configuration as above, but run: - -```bash -cd testnet/stacks-node -cargo build --release --bin stacks-node -``` - -The above code will compile an optimized binary. To use it, run: - -```bash -cd ../.. -./target/release/stacks-node start --config=./testnet/conf/testnet-follower-conf.toml -``` - -To read more about the technical details of mining on the Stacks 2.0 network, have a look at [the minig guide](../understand-stacks/mining): - -### Enable debug logging - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -STACKS_LOG_DEBUG=1 stacks-node testnet -``` - -## Running a miner in Windows - -### Prerequisites - -Make sure are [running a testnet node](run-a-node) before starting this tutorial. - -### Generate keychain and get testnet tokens in Windows - -To setup the miner, first, we need to generate a keychain. With this keychain, we'll get some testnet BTC from a faucet, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. We'll use the `stx make-keychain` command, and pass `-t` to indicate that we want a testnet keychain. - -Generate a keychain: - -```bash -npm install --global @stacks/cli -stx make_keychain -t > cli_keychain.json -type cli_keychain.json -``` - -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -Request BTC from faucet: - -We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). - -### Update configuration file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/testnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/testnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Run the miner - -To start your miner, run this in the command line: - -```bash -stacks-node start --config=testnet/stacks-node/conf/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](/img/windows-defender.png) - - - -Your node should start. It will take some time to sync, and then your miner will be running. - -### Enable debug logging in Windows - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=testnet-miner-conf.toml -``` - -## Optional: Running with Docker - -Alternatively, you can run the testnet node with Docker. - -:::warning Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: - -### Generate keychain and get testnet tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` - -We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). - -### Update config file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/testnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/testnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Start the miner - -:::info The ENV VARS `RUST_BACKTRACE` and `STACKS_LOG_DEBUG` are optional. If removed, debug logs will be disabled ::: - -```bash -docker run -d \ - --name stacks_miner \ - --rm \ - --network host \ - -e RUST_BACKTRACE="full" \ - -e STACKS_LOG_DEBUG="1" \ - -v "$(pwd))/testnet/stacks-node/conf/testnet-miner-conf.toml:/src/stacks-node/testnet-miner-conf.toml" \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain:latest \ -/bin/stacks-node start --config /src/stacks-node/testnet-miner-conf.toml -``` - -You can review the node logs with this command: - -```bash -docker logs -f stacks_miner -``` - -## Optional: Running in Kubernetes with Helm - -In addition, you're also able to run a testnet node in a Kubernetes cluster using the [stacks-blockchain Helm chart](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). - -Ensure you have the following prerequisites installed on your machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [minikube](https://minikube.sigs.k8s.io/docs/start/) (Only needed if standing up a local Kubernetes cluster) -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [helm](https://helm.sh/docs/intro/install/) - -### Generate keychain and get some testnet tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` - -We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). - -### Install the chart and run the miner - -To install the chart with the release name `my-release` and run the node as a miner: - -```bash -minikube start # Only run this if standing up a local Kubernetes cluster -helm repo add blockstack https://charts.blockstack.xyz -helm install my-release blockstack/stacks-blockchain \ - --set config.node.miner=true \ - --set config.node.seed="replace-with-your-privateKey-from-generate-keychain-step" -``` - -You can review the node logs with this command: - -```bash -kubectl logs -l app.kubernetes.io/name=stacks-blockchain -``` - -For more information on the Helm chart and configuration options, please refer to the [chart's homepage](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md b/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md deleted file mode 100644 index 94d938c5ca..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md +++ /dev/null @@ -1,351 +0,0 @@ ---- -title: Run a node -description: Set up and run a Stacks node -sidebar_position: 1 -tags: - - tutorial ---- - -## Stacks Blockchain with Docker - -Run your own Stacks Blockchain node easily with just few commands. - -This tutorial describes a simple and effective [quickstart](#quickstart) to run a Stacks node using public scripts hosted in [Stacks Blockchain repository](https://github.com/stacks-network/stacks-blockchain-docker). Valid for mainnet, testnet and mocknet. - -## **Quickstart** - -1. **Clone the stacks-blockchain-docker repository locally** - -```bash -git clone https://github.com/stacks-network/stacks-blockchain-docker && cd stacks-blockchain-docker -``` - -2. **Optionally, create/copy `.env` file**. If file `.env` doesn't exist when launched it will be created from `sample.env` automatically. - -```bash -cp sample.env .env -``` - -_You may also use a symlink as an alternative to copying: `ln -s sample.env .env`_ - -3. **Optionally, ensure all images are up to date** - -```bash -./manage.sh -n -a pull -``` - -4. **Start the Services** - -```bash -./manage.sh -n -a start -``` - -- With optional proxy: - -```bash -./manage.sh -n -a start -f proxy -``` - -- With optional bitcoin node: - -```bash -./manage.sh -n -a start -f bitcoin -``` - -5. **Stop the Services** - -```bash -./manage.sh -n -a stop -``` - -6. **Retrieve Service Logs** - -```bash -./manage.sh -n -a logs -``` - -- Export docker log files to `./exported-logs`: - -This will create one log file for every running service, for example: postgres.log, stacks-blockain.log, stacks-blockchain-api.log and bitcoin-core.log. -Notice that each time you run this command the log files will be overwritten. - -```bash -./manage.sh -n -a logs export -``` - -7. **Restart all services** - -```bash -./manage.sh -n -a restart -``` - -- With optional proxy: - -```bash -./manage.sh -n -a restart -f proxy -``` - -8. **Delete** all data in `./persistent-data/` and/or data of the Bitcoin blockchain. - - This data is owned by root, so you will need to run it with sudo privileges so it can delete the data. - -```bash -$ sudo ./manage.sh -n -a reset - -Please confirm what persistent data you wish to delete: - -0. Cancel -1. Delete Persistent data for Stacks testnet only and leave Bitcoin blockchain data unaffected. -2. Delete Persistent data for Stacks testnet and Bitcoin blockchain data in ./persistent-data/blockchain-bitcoin -3. Delete Persistent data for Bitcoin blockchain data in ./persistent-data/blockchain-bitcoin only. -Please note that BNS data will never get deleted. - -Type 0, 1, 2 or 3: 2 - -Ok. Delete Stacks and Bitcoin data. -[ Success ] Persistent data deleted for Bitcoin blockchain. -[ Success ] Persistent data deleted for Stacks testnet. - -``` - -9. **Download BNS data to** `./persistent-data/bns-data` - -```bash -./manage.sh bns -``` - -10. **Export stacks-blockchain-api events** (_Not applicable for mocknet_) - -```bash -./manage.sh -n -a export -# check logs for completion -./manage.sh -n -a restart -``` - -11. **Replay stacks-blockchain-api events** (_Not applicable for mocknet_) - -```bash -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart -``` - -## **Running also a bitcoin node (Optional)** - -Stacks needs to use a Bitcoin node, and by default when you run a Stacks node you will be using a public Bitcoin node, which is configured in the `.env` file. Default values is `BITCOIN_NODE=bitcoin.mainnet.stacks.org`. - -However, you can optionaly run both nodes together and configured in a way that you Stacks node will use your own Bitcoin node instead of a public one. - -If you run the script with a bitcoin node it will download and build it directly from source for increased security. This process which only needs to happen once can take up to 20-30 minutes depending on the speed of your system. Also, once the bitcoin node is up and running it will need an additional time for sync for the first time (can be hours for testnet and days for mainnet). - -### Why run Stacks node with your own Bitcoin node? - -Because running your own Bitcoin node will give you higher security and improved perfomance. - -* **Improved perfomance**: The Bitcoin node will serve you blocks faster, as well as UTXOs for your miner (if you run one). -* **Higher security**: The Bitcoin node will also have validated all bitcoin transactions the Stacks node consumes. If you don't run your own Bitcoin node, you're relying on the SPV headers to vouch for the validity of Bitcoin blocks. - -The disadvantage of running your own Bitcoin node is that you need the extra space to store the Bitcoin blockchain (about 500GB) and the initial time it will take to download this data the first time. - -### Example - -You can run easily run your Stacks node with your own Bitcoin node by adding the flag `bitcoin`. This is available only for testnet and mainnet. - -Example: `./manage.sh -n mainnet -a start -f bitcoin` or `./manage.sh -n testnet -a start -f bitcoin` - -### Bitcoin node configuration - -In the `.env` file there is the variable `BITCOIN_BLOCKCHAIN_FOLDER`. As the bitcoin blockchain can be large (over 500GB) you optionally change this variable to any location of your choosing. If you have previously used the [bitcoin core application](https://bitcoin.org/en/bitcoin-core/) and already have the bitcoin blockchain synced, you can use the same data folder and avoid redownloading the entire bitcoin blockchain. - -## **Accessing the services** - -:::tip For networks other than `mocknet`, downloading the initial headers can take several minutes. Until the headers are downloaded, the `/v2/info` endpoints won't return any data. - -Use the command `./manage.sh -n -a logs` to check the sync progress. ::: - -**stacks-blockchain**: - -- Ports `20443-20444` are exposed to `localhost` - -```bash -curl -sL localhost:20443/v2/info | jq -``` - -**stacks-blockchain-api**: - -- Port `3999` are exposed to `localhost` - -```bash -curl -sL localhost:3999/v2/info | jq -``` - -**proxy**: - -- Port `80` is exposed to `localhost` - -```bash -curl -sL localhost/v2/info | jq -curl -sL localhost/ | jq -``` - ---- - -## Upgrades - -⚠️ For upgrades to running instances of this repo, you'll need to [run the event-replay](https://github.com/hirosystems/stacks-blockchain-api#event-replay): - -```bash -./manage.sh -n -a stop -./manage.sh -n -a export -./manage.sh -n -a import -./manage.sh -n -a restart -``` - ---- - -## **Workarounds to potential issues** - -_**Port(s) already in use**_: - -- 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. `3999` and edit your `.env` file to use the new port. - -```bash -netstat -anl | grep 3999 -``` - -``` -tcp46 0 0 *.3999 *.* LISTEN -``` - -_**Containers not starting (hanging on start)**_: - -- Occasionally, docker can get **stuck** and not allow new containers to start. If this happens, simply restart your docker daemon and try again. - -_**Database Issues**_: - -- For any of the various Postgres/sync issues, it may be easier to simply remove the persistent data dir. Note that doing so will result in a longer startup time as the data is repopulated. - -```bash -./manage.sh -n -a stop -./manage.sh -n -a reset -./manage.sh -n -a start -``` - -_**API Missing Parent Block Error**_: - -- If the Stacks blockchain is no longer syncing blocks, and the API reports an error similar to this:\ - `Error processing core node block message DB does not contain a parent block at height 1970 with index_hash 0x3367f1abe0ee35b10e77fbcaa00d3ca452355478068a0662ec492bb30ee0f13e"`,\ - The API (and by extension the DB) is out of sync with the blockchain. \ - The only known method to recover is to resync from genesis (**event-replay _may_ work, but in all likelihood will restore data to the same broken state**). - -- To attempt the event-replay - -```bash -./manage.sh -n -a stop -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart -``` - -- To wipe data and re-sync from genesis - -```bash -./manage.sh -n -a stop -./manage.sh -n -a reset -./manage.sh -n -a restart -``` - - -## **Requirements:** - -- [Docker](https://docs.docker.com/get-docker/) >= `17.09` -- [docker-compose](https://github.com/docker/compose/releases/) >= `1.27.4` -- [git](https://git-scm.com/downloads) -- [jq binary](https://stedolan.github.io/jq/download/) -- [sed](https://www.gnu.org/software/sed/) -- Machine with (at a minimum): - - 4GB memory - - 1 Vcpu - - 50GB storage (600GB if you optionally also run the bitcoin mainnet node) - -:::caution MacOS with an M1 processor is NOT recommended - -The way Docker for Mac on an Arm chip is designed makes the I/O incredibly slow, and blockchains are **_very_** heavy on I/O. This only seems to affect MacOS, other Arm based systems like Raspberry Pi's seem to work fine. - -::: - - -### Install/Update docker-compose - -:::note `docker-compose` executable is required, even though recent versions of Docker contain `compose` natively ::: - -- [Install Docker-compose](https://docs.docker.com/compose/install/) -- [Docker Desktop for Mac](https://docs.docker.com/docker-for-mac/install/) -- [Docker Desktop for Windows](https://docs.docker.com/docker-for-windows/install/) -- [Docker Engine for Linux](https://docs.docker.com/engine/install/#server) - -First, check if you have `docker-compose` installed locally. - -To do that, run this command in your terminal : - -```bash -docker-compose --version -``` - -Output should look something very similar to this : - -``` -docker-compose version 1.27.4, build 40524192 -``` - -If the command is not found, or the version is < `1.27.4`, run the following to install the latest to `/usr/local/bin/docker-compose`: - -```bash -#You will need to have jq installed, or this snippet won't run. -VERSION=$(curl --silent https://api.github.com/repos/docker/compose/releases/latest | jq .name -r) -DESTINATION=/usr/local/bin/docker-compose -sudo curl -L https://github.com/docker/compose/releases/download/${VERSION}/docker-compose-$(uname -s)-$(uname -m) -o $DESTINATION -sudo chmod 755 $DESTINATION -``` - -### Security note on docker - -The Docker daemon always runs as the root user so by default you will need root privileges to interact with it. - -The script `manage.sh` uses docker, so to avoid the requirement of needing to run the script with root privileges it is prefered to be able to *manage Docker as a non-root user*, following [these simple tests](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user). - -This will avoid the need of running the script with root privileges for all operations except the removal of data. - -### Configuration files you can edit - -The following files can be modified to personalize your node configuration, but generally most of them should be left as-is. All these files will be created from the sample copy if they don't exist at runtime (for example `.env` is created from `sample.env`). However these files will never be modified by the application once created and will never be pushed back to github, so your changes will be safe. - -* `.env` -* `./conf/mainnet/Config.toml` -* `./conf/mainnet/bitcoin.conf` -* `./conf/testnet/Config.toml` -* `./conf/testnet/bitcoin.conf` - -By default: - -- BNS data is **not** enabled/imported - - To enable, uncomment `# BNS_IMPORT_DIR=/bns-data` in `./env` - - Download BNS data: `./manage.sh bns` -- Fungible token metadata is **not** enabled - - To enable, uncomment `# STACKS_API_ENABLE_FT_METADATA=1` in `./env` -- Non-Fungible token metadata is **not** enabled - - To enable, uncomment `# STACKS_API_ENABLE_NFT_METADATA=1` in `./env` -- Verbose logging is **not** enabled - - To enable, uncomment `# VERBOSE=true` in `./env` -- Bitcoin blockchain folder is configured in `BITCOIN_BLOCKCHAIN_FOLDER` in `./env` - -### Local Data Dirs - -Directories will be created on first start that will store persistent data under `./persistent-data/` - -`` can be 1 of: - -- mainnet -- testnet -- mocknet diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md b/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md deleted file mode 100644 index 09db354d0d..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md +++ /dev/null @@ -1,188 +0,0 @@ ---- -title: Running a mainnet node -description: Set up and run a mainnet node with Docker -sidebar_position: 3 -tags: - - tutorial ---- - -## Introduction - -This procedure demonstrates how to run a local mainnet node using Docker images. - -:::caution -This procedure focuses on Unix-like operating systems (Linux and MacOS). This procedure has not been tested on Windows. -::: - -## Prerequisites - -Running a node has no specialized hardware requirements. Users have been successful in running nodes on Raspberry Pi boards and other system-on-chip architectures. In order to complete this procedure, you must have the following software installed on the node host machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [curl](https://curl.se/download.html) -- [jq](https://stedolan.github.io/jq/download/) - -### Firewall configuration - -In order for the API node services to work correctly, you must configure any network firewall rules to allow traffic on the ports discussed in this section. The details of network and firewall configuration are highly specific to your machine and network, so a detailed example isn't provided. - -The following ports must open on the host machine: - -Ingress: - -- stacks-blockchain (open to `0.0.0.0/0`): - - `20443 TCP` - - `20444 TCP` - -Egress: - -- `8332` -- `8333` -- `20443-20444` - -These egress ports are for syncing stacks-blockchain and Bitcoin headers. If they're not open, the sync will fail. - -## Step 1: initial setup - -In order to run the mainnet node, you must download the Docker images and create a directory structure to hold the persistent data from the services. Download and configure the Docker images with the following commands: - -```sh -docker pull blockstack/stacks-blockchain -``` - -Create a directory structure for the service data with the following command: - -```sh -mkdir -p ./stacks-node/{persistent-data/stacks-blockchain/mainnet,config/mainnet} && cd stacks-node -``` - -## Step 2: running Stacks blockchain - -First, create the `./config/mainnet/Config.toml` file and add the following content to the file using a text editor: - -```toml -[node] -working_dir = "/root/stacks-node/data" -rpc_bind = "0.0.0.0:20443" -p2p_bind = "0.0.0.0:20444" -bootstrap_node = "02da7a464ac770ae8337a343670778b93410f2f3fef6bea98dd1c3e9224459d36b@seed-0.mainnet.stacks.co:20444,02afeae522aab5f8c99a00ddf75fbcb4a641e052dd48836408d9cf437344b63516@seed-1.mainnet.stacks.co:20444,03652212ea76be0ed4cd83a25c06e57819993029a7b9999f7d63c36340b34a4e62@seed-2.mainnet.stacks.co:20444" -wait_time_for_microblocks = 10000 - -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "bitcoin.blockstack.com" -username = "blockstack" -password = "blockstacksystem" -rpc_port = 8332 -peer_port = 8333 - -[connection_options] -read_only_call_limit_write_length = 0 -read_only_call_limit_read_length = 100000 -read_only_call_limit_write_count = 0 -read_only_call_limit_read_count = 30 -read_only_call_limit_runtime = 1000000000 -``` - -Start the `stacks-blockchain` container with the following command: - -```sh -docker run -d --rm \ - --name stacks-blockchain \ - -v $(pwd)/persistent-data/stacks-blockchain/mainnet:/root/stacks-node/data \ - -v $(pwd)/config/mainnet:/src/stacks-node \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain \ -/bin/stacks-node start --config /src/stacks-node/Config.toml -``` - -You can verify the running `stacks-blockchain` container with the command: - -```sh -docker ps --filter name=stacks-blockchain -``` - -## Step 3: verifying the services - -:::note -The initial burnchain header sync can take several minutes, until this is done the following commands will not work -::: - -To verify the `stacks-blockchain` burnchain header sync progress: - -```sh -docker logs stacks-blockchain -``` - -The output should be similar to the following: - -``` -INFO [1626290705.886954] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.2% (8000 out of 691034) -INFO [1626290748.103291] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.4% (10000 out of 691034) -INFO [1626290776.956535] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.7% (12000 out of 691034) -``` - -To verify the `stacks-blockchain` tip height is progressing use the following command: - -```sh -curl -sL localhost:20443/v2/info | jq -``` - -If the instance is running you should recieve terminal output similar to the following: - -```json -{ - "peer_version": 402653184, - "pox_consensus": "89d752034e73ed10d3b97e6bcf3cff53367b4166", - "burn_block_height": 666143, - "stable_pox_consensus": "707f26d9d0d1b4c62881a093c99f9232bc74e744", - "stable_burn_block_height": 666136, - "server_version": "stacks-node 2.0.11.1.0-rc1 (master:67dccdf, release build, linux [x86_64])", - "network_id": 1, - "parent_network_id": 3652501241, - "stacks_tip_height": 61, - "stacks_tip": "e08b2fe3dce36fd6d015c2a839c8eb0885cbe29119c1e2a581f75bc5814bce6f", - "stacks_tip_consensus_hash": "ad9f4cb6155a5b4f5dcb719d0f6bee043038bc63", - "genesis_chainstate_hash": "74237aa39aa50a83de11a4f53e9d3bb7d43461d1de9873f402e5453ae60bc59b", - "unanchored_tip": "74d172df8f8934b468c5b0af2efdefe938e9848772d69bcaeffcfe1d6c6ef041", - "unanchored_seq": 0, - "exit_at_block_height": null -} -``` - -## Stopping the mainnet node - -Use the following commands to stop the local mainnet node: - -```sh -docker stop stacks-blockchain -``` - -## Optional. Run stacks node with own bitcoin node - -It's encouraged to use your own bitcoin node when possible. - -To do this simply update the `stacks-node/config/mainnet/Config.toml` file with the details of your bitcoin node. For example: - -``` -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "localhost" -username = "rpc username" -password = "rpc password" -rpc_port = 8332 -peer_port = 8333 -``` - -The rpc configuration of your bitcoin node is out of the scope of this document, but you can find more information on how to set it up [here](https://developer.bitcoin.org/examples/intro.html). - -## Additional reading - - - -- [Running a Stacks API node](https://docs.hiro.so/get-started/running-api-node) -- [Running a Stacks testnet node](running-testnet-node) - diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md b/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md deleted file mode 100644 index da01ce2ea1..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: Running a testnet node -description: Set up and run a testnet node with Docker -sidebar_position: 2 -tags: - - tutorial ---- - -## Introduction - -This procedure demonstrates how to run a local testnet node using Docker images. - -:::caution -This procedure focuses on Unix-like operating systems (Linux and MacOS). This procedure has not been tested on Windows. -::: - -## Prerequisites - -Running a node has no specialized hardware requirements. Users have been successful in running nodes on Raspberry Pi boards and other system-on-chip architectures. In order to complete this procedure, you must have the following software installed on the node host machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [curl](https://curl.se/download.html) -- [jq](https://stedolan.github.io/jq/download/) - -### Firewall configuration - -In order for the API node services to work correctly, you must configure any network firewall rules to allow traffic on the ports discussed in this section. The details of network and firewall configuration are highly specific to your machine and network, so a detailed example isn't provided. - -The following ports must open on the host machine: - -Ingress: - -- stacks-blockchain (open to `0.0.0.0/0`): - - `20443 TCP` - - `20444 TCP` - -Egress: - -- `18332` -- `18333` -- `20443-20444` - -These egress ports are for syncing stacks-blockchain and Bitcoin headers. If they're not open, the sync will fail. - -## Step 1: initial setup - -In order to run the testnet node, you must download the Docker images and create a directory structure to hold the persistent data from the services. Download and configure the Docker images with the following commands: - -```sh -docker pull blockstack/stacks-blockchain -``` - -Create a directory structure for the service data with the following command: - -```sh -mkdir -p ./stacks-node/persistent-data/stacks-blockchain/testnet && cd stacks-node -``` - -## Step 2: running Stacks blockchain - -Start the stacks-blockchain container with the following command: - -```sh -docker run -d --rm \ - --name stacks-blockchain \ - -v $(pwd)/persistent-data/stacks-blockchain/testnet:/root/stacks-node/data \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain \ -/bin/stacks-node testnet -``` - -You can verify the running stacks-blockchain container with the command: - -```sh -docker ps --filter name=stacks-blockchain -``` - -## Step 3: verifying the services - -:::info -The initial burnchain header sync can take several minutes, until this is done the following commands will not work -::: - -To verify the stacks-blockchain burnchain header sync progress: - -```sh -docker logs stacks-blockchain -``` - -The output should be similar to the following: - -``` -INFO [1626290705.886954] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.2% (8000 out of 2034380) -INFO [1626290748.103291] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.4% (10000 out of 2034380) -INFO [1626290776.956535] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.7% (12000 out of 2034380) -``` - -To verify the stacks-blockchain tip height is progressing use the following command: - -```sh -curl -sL localhost:20443/v2/info | jq -``` - -If the instance is running you should recieve terminal output similar to the following: - -```json -{ - "peer_version": 4207599105, - "pox_consensus": "12f7fa85e5099755a00b7eaecded1aa27af61748", - "burn_block_height": 2034380, - "stable_pox_consensus": "5cc4e0403ff6a1a4bd17dae9600c7c13d0b10bdf", - "stable_burn_block_height": 2034373, - "server_version": "stacks-node 2.0.11.2.0-rc1 (develop:7b6d3ee+, release build, linux [x86_64])", - "network_id": 2147483648, - "parent_network_id": 118034699, - "stacks_tip_height": 509, - "stacks_tip": "e0ee952e9891709d196080ca638ad07e6146d4c362e6afe4bb46f42d5fe584e8", - "stacks_tip_consensus_hash": "12f7fa85e5099755a00b7eaecded1aa27af61748", - "genesis_chainstate_hash": "74237aa39aa50a83de11a4f53e9d3bb7d43461d1de9873f402e5453ae60bc59b", - "unanchored_tip": "32bc86590f11504f17904ee7f5cb05bcf71a68a35f0bb3bc2d31aca726090842", - "unanchored_seq": 0, - "exit_at_block_height": null -} -``` - -## Stopping the testnet node - -Use the following commands to stop the local testnet node: - -```sh -docker stop stacks-blockchain -``` - -## Additional reading - - - -- [Running a Stacks API node](https://docs.hiro.so/get-started/running-api-node) -- [Running a Stacks mainnet node](running-mainnet-node) - diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md b/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md deleted file mode 100644 index 40b2ef676b..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md +++ /dev/null @@ -1,501 +0,0 @@ ---- -title: Stacks Node Configuration -description: Configuration parameters and options for the stacks-node binary -sidebar_position: 6 ---- - -## Usage - -```bash -stacks-node sub-command [--subcommand-option ] -``` - -## Subcommands - -:::caution The `stacks-node` binary may have deprecated commands that are not documented on this page. Deprecated commands may be accessible until they are fully removed from the sources. ::: - -### mocknet - -Start a node based on a fast local setup emulating a burnchain. Ideal for smart contract development. - -Example: - -```bash -stacks-node mocknet -``` - -### krypton - -Start a node that will join and stream blocks from the public krypton regtest, powered by Blockstack via [Proof of Transfer](../understand-stacks#consensus-mechanism). - -Example: - -```bash -stacks-node krypton -``` - -### testnet - -Start a node that will join and stream blocks from the public testnet. - -Example: - -```bash -stacks-node testnet -``` - -### mainnet - -Start a node that joins and streams blocks from the public mainnet. - -Example: - -```bash -stacks-node mainnet -``` - -### start - -Start a node with a config of your own. Can be used for joining a network, starting a new chain, or replacing default values used by the `mocknet` or `testnet` subcommands. - -#### Arguments - -**--config**: relative or absolute path to the TOML config file. Required. - -Example: - -```bash -stacks-node start --config=/path/to/config.toml -``` - -See [Configuration File Options](#configuration-file-options) for more information. - -#### version - -Displays information about the current version and the release cycle. - -Example: - -```bash -stacks-node version -``` - -#### help - -Displays a help message. - -Example: - -```bash -stacks-node help -``` - -## Configuration File Options - -The TOML configuration file has multiple sections under which an option may be placed. - -To see a list of example configurations, [please see this page](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf). - -### Section: node - -Contains various configuration options pertaining to the stacks-node. - -Example: - -```toml -[node] -rpc_bind = "0.0.0.0:20443" -p2p_bind = "0.0.0.0:20444" -# Enter your private key here -seed = "replace-with-your-private-key" -miner = true -``` - -#### working_dir (optional) - -Absolute path to the directory which the stacks-node will use for storing various data. - -Example: - -```toml -working_dir = "/root/stacks-node" -``` - -#### rpc_bind - -Address and port stacks-node should bind to for RPC connections. - -Example: - -```toml -rpc_bind = "0.0.0.0:20443" -``` - -#### p2p_bind - -Address and port stacks-node should bind to for P2P connections. - -Example: - -```toml -p2p_bind = "0.0.0.0:20444" -``` - -#### data_url (optional) - -Address and port from which the stacks-node will be receiving incoming rpc connections. - -Example: - -```toml -data_url = "1.2.3.4:20443" -``` - -#### p2p_address (optional) - -Address and port from which the stacks-node will be receiving incoming p2p connections. - -Example: - -```toml -p2p_address = "1.2.3.4:20444" -``` - -#### bootstrap_node (optional) - -Public key, address, and port stacks-node should use to pull transaction data from when starting. - -Example: - -```toml -bootstrap_node = "047435c194e9b01b3d7f7a2802d6684a3af68d05bbf4ec8f17021980d777691f1d51651f7f1d566532c804da506c117bbf79ad62eea81213ba58f8808b4d9504ad@testnet.blockstack.org:20444" -``` - -#### wait_time_for_microblocks (optional) - -The amount of time (in milliseconds) that a node will wait before trying to mine a block, after catching up to the anchored chain tip. This gives the current leader time to broadcast microblocks that will get included in that mined block. - -Example: - -```toml -wait_time_for_microblocks = 15000 -``` - -#### seed (optional) - -The private key to use for mining. Only needed if `miner` is set to `true`. - -Example: - -```toml -seed = "replace-with-your-private-key" -``` - -#### local_peer_seed (optional) - -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. - -Example: - -```toml -local_peer_seed = "replace-with-your-private-key" -``` - -#### miner (optional) - -Determines whether the stacks-node is running a follower (`false`) or a miner (`true`). Defaults to `false` if omitted. - -Example: - -```toml -miner = true -``` - -#### mine_microblocks (optional) - -Determines whether the stacks-node will mine microblocks. Will only take effect if `miner` is set to `true`. - -Example: - -```toml -mine_microblocks = true -``` - -#### prometheus_bind (optional) - -Address and port stacks-node should open for Prometheus metrics collection. - -Example: - -```toml -prometheus_bind = "0.0.0.0:9153" -``` - -### Section: events_observer (optional) - -Contains options for watching events emitted by a local [stacks-blockchain-api](https://github.com/hirosystems/stacks-blockchain-api) service. - -:::info -This section can be repeated multiple times. -::: - -Example: - -```toml -[[events_observer]] endpoint = "address-to-my-local.stacks-node-api.com:3700" -retry_count = 255 -events_keys = ["*"] -``` - -#### endpoint - -Address and port to a stacks-node-api to watch for events. - -Example: - -```toml -endpoint = "address-to-my-local.stacks-node-api.com:3700" -``` - -#### retry_count - -Number of times to retry sending events to the endpoint before failing. - -Example: - -```toml -retry_count = 255 -``` - -#### events_keys - -Event keys for which to watch. The emitted node events can be restricted by account, function name and event type. Asterix ("\*") can be used to emit all events. - -Examples: - -```toml -events_keys = ["*"] -``` - -```toml -events_keys = [ - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.store::print", - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.contract.ft-token", - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.contract.nft-token", - "stx" -] -``` - -### Section: connection_options (optional) - -Specifies configuration options for others connecting to the stacks node. - -Example: - -```toml -[connection_options] -public_ip_address = "1.2.3.4:20444" -download_interval = 60 -walk_interval = 30 -``` - -#### public_ip_address - -The advertised public IP of this stacks-node. - -Example: - -```toml -public_ip_address = "1.2.3.4:20444" -``` - -#### download_interval - -Time (in seconds) between attempts to download blocks. - -Example: - -```toml -download_interval = 60 -``` - -#### walk_interval - -Time (in seconds) between attempts to walk the neighborhood. - -Example: - -```toml -walk_interval = 30 -``` - -#### read_only_call_limit_read_length - -Total number of bytes allowed to be read by an individual read-only function call. - -Example: - -```toml -read_only_call_limit_read_length = 100000 -``` - -#### read_only_call_limit_read_count - -Total number of independent read operations permitted for an individual read-only function call. - -Example: - -```toml -read_only_call_limit_read_count = 30 -``` - -#### read_only_call_limit_runtime - -[Runtime cost](https://github.com/stacksgov/sips/blob/2d3fd9bf8da7a04f588d90ff6252173d7609d7bf/sips/sip-006/sip-006-runtime-cost-assessment.md#introduction) limit for an individual read-only function call. - -Example: - -```toml -read_only_call_limit_runtime = 1000000000 -``` - -### Section: burnchain - -This section contains configuration options pertaining to the blockchain the stacks-node binds to on the backend for proof-of-transfer (BTC). - -Example: - -```toml -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "your.bitcoind.node.org" -rpc_port = 8332 -peer_port = 8333 -``` - -#### chain - -The blockchain stacks-node binds to on the backend for proof-of-transfer. Only value supported: `"bitcoin"`. - -Example: - -```toml -chain = "bitcoin" -``` - -#### mode - -The profile or test phase of which to run stacks-node. Valid values are `"mocknet"`, `"helium"`, `"neon"`, `"argon"`, `"krypton"`, `"xenon"`. - -Example: - -```toml -mode = "xenon" -``` - -#### peer_host - -Domain name of the host running the backend Bitcoin blockchain. It's required to either run a personal Bitcoin node locally, or to use a publicly hosted Bitcoin node. - -Example: - -```toml -peer_host = "your.bitcoind.node.org" -``` - -#### rpc_port - -peer_host's port stacks-node will connect to for RPC connections. - -Example: - -```toml -rpc_port = 8332 -``` - -#### peer_port - -peer_host's port stacks-node will connect to for P2P connections. - -Example: - -```toml -peer_port = 8333 -``` - -#### burn_fee_cap (optional) - -Maximum amount (in Satoshis) of "burn commitment" to broadcast for the next block's leader election. - -Example: - -```toml -burn_fee_cap = 30000 -``` - -#### satoshis_per_byte (optional) - -Amount (in Satoshis) per [virtual byte](https://en.bitcoin.it/wiki/Weight_units). This is used to compute the transaction fees. - -Example: - -```toml -satoshis_per_byte = 50 -``` - -So total transaction cost would be `(estimated_tx_size * satoshis_per_byte) + burn_fee_cap`. - -#### commit_anchor_block_within (optional) - -Sets the time period (in milliseconds) for commitments. Only used when `mode` is set to `"helium"`. - -Example: - -```toml -commit_anchor_block_within = 10000 -``` - -### Section: ustx_balance (testnet/regtest only) - -This section contains configuration options pertaining to the genesis block allocation for an address in micro-STX. If a user changes these values, their node may be in conflict with other nodes on the network and find themselves unable to sync with other nodes. - -:::info -This section can repeat multiple times, and thus is in double-brackets. Each section can define only one address. This section is ignored if running a node on mainnet. -::: - -Example: - -```toml -[[ustx_balance]] address = "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6" -amount = 10000000000000000 - -[[ustx_balance]] address = "ST11NJTTKGVT6D1HY4NJRVQWMQM7TVAR091EJ8P2Y" -amount = 10000000000000000 - -[[ustx_balance]] address = "ST1HB1T8WRNBYB0Y3T7WXZS38NKKPTBR3EG9EPJKR" -amount = 10000000000000000 - -[[ustx_balance]] address = "STRYYQQ9M8KAF4NS7WNZQYY59X93XEKR31JP64CP" -amount = 10000000000000000 -``` - -#### address - -Address which maintains a micro-STX balance. - -Example: - -```toml -address = "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6" -``` - -#### amount - -The balance of micro-STX given to the address at the start of the node. - -Example: - -```toml -amount = 10000000000000000 -``` diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md b/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md deleted file mode 100644 index 094e3f03a1..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Verify Miner -description: Verify node is operating as miner -sidebar_position: 7 ---- - -You can verify that your node is operating as a miner by checking its log output to verify that it was able to find its Bitcoin UTXOs: - -```bash -$ head -n 100 /path/to/your/node/logs | grep -i utxo -INFO [1630127492.031042] [testnet/stacks-node/src/run_loop/neon.rs:146] [main] Miner node: checking UTXOs at address: -INFO [1630127492.062652] [testnet/stacks-node/src/run_loop/neon.rs:164] [main] UTXOs found - will run as a Miner node -``` \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json b/i18n/ru/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json deleted file mode 100644 index f5de305558..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Noteworthy Contracts", - "position": 4, - "link": { - "type": "generated-index", - "description": "Specific deployed Clarity Contracts worth mentioning." - } -} \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md b/i18n/ru/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md deleted file mode 100644 index 99723a9ff2..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md +++ /dev/null @@ -1,362 +0,0 @@ ---- -title: BNS Contract -description: The Blockchain Naming System. ---- - -![](/img/satoshi-btc.png) - -## Introduction - -The Blockchain Naming System (BNS) is implemented as a smart contract using Clarity. - -Below is a list of public and read-only functions as well as error codes that can be returned by those methods: -* [Public functions](#public-functions) -* [Read-only functions](#read-only-functions) -* [Error codes](#error-codes) - -## Public functions - - -### name-import - -#### Input: `(buff 20), (buff 48), principal, (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-import namespace name beneficiary zonefile-hash)` -#### Description: -Imports name to a revealed namespace. Each imported name is given both an owner and some off-chain state. - -### name-preorder - -#### Input: `(buff 20), uint` -#### Output: `(response uint int)` -#### Signature: `(name-preorder hashed-salted-fqn stx-to-burn)` -#### Description: -Preorders a name by telling all BNS nodes the salted hash of the BNS name. It pays the registration fee to the namespace owner's designated address. - -### name-register - -#### Input: `(buff 20), (buff 48), (buff 20), (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-register namespace name salt zonefile-hash)` -#### Description: -Reveals the salt and the name to all BNS nodes, and assigns the name an initial public key hash and zone file hash. - -### name-renewal - -#### Input: `(buff 20), (buff 48), uint, (optional principal), (optional (buff 20))` -#### Output: `(response bool int)` -#### Signature: `(name-renewal namespace name stx-to-burn new-owner zonefile-hash)` -#### Description: -Depending in the namespace rules, a name can expire. For example, names in the .id namespace expire after 2 years. You need to send a name renewal every so often to keep your name. - -You will pay the registration cost of your name to the namespace's designated burn address when you renew it. When a name expires, it enters a \"grace period\". The period is set to 5000 blocks (a month) but can be configured for each namespace. - -It will stop resolving in the grace period, and all of the above operations will cease to be honored by the BNS consensus rules. You may, however, send a NAME_RENEWAL during this grace period to preserve your name. After the grace period, everybody can register that name again. If your name is in a namespace where names do not expire, then you never need to use this transaction. -### name-revoke - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(name-revoke namespace name)` -#### Description: -Makes a name unresolvable. The BNS consensus rules stipulate that once a name is revoked, no one can change its public key hash or its zone file hash. The name's zone file hash is set to null to prevent it from resolving. You should only do this if your private key is compromised, or if you want to render your name unusable for whatever reason. - -### name-transfer - -#### Input: `(buff 20), (buff 48), principal, (optional (buff 20))` -#### Output: `(response bool int)` -#### Signature: `(name-transfer namespace name new-owner zonefile-hash)` -#### Description: -Changes the name's public key hash. You would send a name transfer transaction if you wanted to: -* Change your private key -* Send the name to someone else or -* Update your zone file - -When transferring a name, you have the option to also clear the name's zone file hash (i.e. set it to null). This is useful for when you send the name to someone else, so the recipient's name does not resolve to your zone file. - -### name-update - -#### Input: `(buff 20), (buff 48), (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-update namespace name zonefile-hash)` -#### Description: -Changes the name's zone file hash. You would send a name update transaction if you wanted to change the name's zone file contents. For example, you would do this if you want to deploy your own Gaia hub and want other people to read from it. - -### namespace-preorder - -#### Input: `(buff 20), uint` -#### Output: `(response uint int)` -#### Signature: `(namespace-preorder hashed-salted-namespace stx-to-burn)` -#### Description: -Registers the salted hash of the namespace with BNS nodes, and burns the requisite amount of cryptocurrency. Additionally, this step proves to the BNS nodes that user has honored the BNS consensus rules by including a recent consensus hash in the transaction. Returns pre-order's expiration date (in blocks). - -### namespace-ready - -#### Input: `(buff 20)` -#### Output: `(response bool int)` -#### Signature: `(namespace-ready namespace)` -#### Description: -Launches the namespace and makes it available to the public. Once a namespace is launched, anyone can register a name in it if they pay the appropriate amount of cryptocurrency. - -### namespace-reveal - -#### Input: `(buff 20), (buff 20), uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, principal` -#### Output: `(response bool int)` -#### Signature: `(namespace-reveal namespace namespace-salt p-func-base p-func-coeff p-func-b1 p-func-b2 p-func-b3 p-func-b4 p-func-b5 p-func-b6 p-func-b7 p-func-b8 p-func-b9 p-func-b10 p-func-b11 p-func-b12 p-func-b13 p-func-b14 p-func-b15 p-func-b16 p-func-non-alpha-discount p-func-no-vowel-discount lifetime namespace-import)` -#### Description: -Reveals the salt and the namespace ID (after a namespace preorder). It reveals how long names last in this namespace before they expire or must be renewed, and it sets a price function for the namespace that determines how cheap or expensive names its will be.All of the parameters prefixed by `p` make up the `price function`. These parameters govern the pricing and lifetime of names in the namespace. - -The rules for a namespace are as follows: - -* a name can fall into one of 16 buckets, measured by length. Bucket 16 incorporates all names at least 16 characters long. - -* the pricing structure applies a multiplicative penalty for having numeric characters, or punctuation characters. - -* the price of a name in a bucket is `((coeff) * (base) ^ (bucket exponent)) / ((numeric discount multiplier) * (punctuation discount multiplier))` - -Example: - -* base = 10 -* coeff = 2 -* nonalpha discount: 10 -* no-vowel discount: 10 -* buckets 1, 2: 9 -* buckets 3, 4, 5, 6: 8 -* buckets 7, 8, 9, 10, 11, 12, 13, 14: 7 -* buckets 15, 16+: - - -## Read-only functions - -### can-name-be-registered - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(can-name-be-registered namespace name)` -#### Description: -Returns true if the provided name can be registered. - -### can-namespace-be-registered - -#### Input: `(buff 20)` -#### Output: `(response bool UnknownType)` -#### Signature: `(can-namespace-be-registered namespace)` -#### Description: -Returns true if the provided namespace is available. - -### can-receive-name - -#### Input: `principal` -#### Output: `(response bool int)` -#### Signature: `(can-receive-name owner)` -#### Description: -Returns true if the provided name can be received. That is, if it is not curretly owned, a previous lease is expired, and the name wasn't revoked. - -### get-name-price - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response uint int)` -#### Signature: `(get-name-price namespace name)` -#### Description: -Gets the price for a name. - -### get-namespace-price - -#### Input: `(buff 20)` -#### Output: `(response uint int)` -#### Signature: `(get-namespace-price namespace)` -#### Description: -Gets the price for a namespace. - -### get-namespace-properties - -#### Input: `(buff 20)` -#### Output: `(response (tuple (namespace (buff 20)) (properties (tuple (can-update-price-function bool) (launched-at (optional uint)) (lifetime uint) (namespace-import principal) (price-function (tuple (base uint) (buckets (list 16 uint)) (coeff uint) (no-vowel-discount uint) (nonalpha-discount uint))) (revealed-at uint)))) int)` -#### Signature: `(get-namespace-properties namespace)` -#### Description: -Get namespace properties. - -### is-name-lease-expired - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(is-name-lease-expired namespace name)` -#### Description: -Return true if the provided name lease is expired. - -### name-resolve - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response (tuple (lease-ending-at (optional uint)) (lease-started-at uint) (owner principal) (zonefile-hash (buff 20))) int)` -#### Signature: `(name-resolve namespace name)` -#### Description: -Get name registration details. - -### resolve-principal - -#### Input: `principal` -#### Output: `(response (tuple (name (buff 48)) (namespace (buff 20))) (tuple (code int) (name (optional (tuple (name (buff 48)) (namespace (buff 20)))))))` -#### Signature: `(resolve-principal owner)` -#### Description: -Returns the registered name that a principal owns if there is one. A principal can only own one name at a time. - -## Error codes - -### ERR_INSUFFICIENT_FUNDS -#### type: `int` -#### value: `4001` - -### ERR_NAMESPACE_ALREADY_EXISTS -#### type: `int` -#### value: `1006` - -### ERR_NAMESPACE_ALREADY_LAUNCHED -#### type: `int` -#### value: `1014` - -### ERR_NAMESPACE_BLANK -#### type: `int` -#### value: `1013` - -### ERR_NAMESPACE_CHARSET_INVALID -#### type: `int` -#### value: `1016` - -### ERR_NAMESPACE_HASH_MALFORMED -#### type: `int` -#### value: `1015` - -### ERR_NAMESPACE_NOT_FOUND -#### type: `int` -#### value: `1005` - -### ERR_NAMESPACE_NOT_LAUNCHED -#### type: `int` -#### value: `1007` - -### ERR_NAMESPACE_OPERATION_UNAUTHORIZED -#### type: `int` -#### value: `1011` - -### ERR_NAMESPACE_PREORDER_ALREADY_EXISTS -#### type: `int` -#### value: `1003` - -### ERR_NAMESPACE_PREORDER_CLAIMABILITY_EXPIRED -#### type: `int` -#### value: `1009` - -### ERR_NAMESPACE_PREORDER_EXPIRED -#### type: `int` -#### value: `1002` - -### ERR_NAMESPACE_PREORDER_LAUNCHABILITY_EXPIRED -#### type: `int` -#### value: `1010` - -### ERR_NAMESPACE_PREORDER_NOT_FOUND -#### type: `int` -#### value: `1001` - -### ERR_NAMESPACE_PRICE_FUNCTION_INVALID -#### type: `int` -#### value: `1008` - -### ERR_NAMESPACE_STX_BURNT_INSUFFICIENT -#### type: `int` -#### value: `1012` - -### ERR_NAMESPACE_UNAVAILABLE -#### type: `int` -#### value: `1004` - -### ERR_NAME_ALREADY_CLAIMED -#### type: `int` -#### value: `2011` - -### ERR_NAME_BLANK -#### type: `int` -#### value: `2010` - -### ERR_NAME_CHARSET_INVALID -#### type: `int` -#### value: `2022` - -### ERR_NAME_CLAIMABILITY_EXPIRED -#### type: `int` -#### value: `2012` - -### ERR_NAME_COULD_NOT_BE_MINTED -#### type: `int` -#### value: `2020` - -### ERR_NAME_COULD_NOT_BE_TRANSFERED -#### type: `int` -#### value: `2021` - -### ERR_NAME_EXPIRED -#### type: `int` -#### value: `2008` - -### ERR_NAME_GRACE_PERIOD -#### type: `int` -#### value: `2009` - -### ERR_NAME_HASH_MALFORMED -#### type: `int` -#### value: `2017` - -### ERR_NAME_NOT_FOUND -#### type: `int` -#### value: `2013` - -### ERR_NAME_NOT_RESOLVABLE -#### type: `int` -#### value: `2019` - -### ERR_NAME_OPERATION_UNAUTHORIZED -#### type: `int` -#### value: `2006` - -### ERR_NAME_PREORDERED_BEFORE_NAMESPACE_LAUNCH -#### type: `int` -#### value: `2018` - -### ERR_NAME_PREORDER_ALREADY_EXISTS -#### type: `int` -#### value: `2016` - -### ERR_NAME_PREORDER_EXPIRED -#### type: `int` -#### value: `2002` - -### ERR_NAME_PREORDER_FUNDS_INSUFFICIENT -#### type: `int` -#### value: `2003` - -### ERR_NAME_PREORDER_NOT_FOUND -#### type: `int` -#### value: `2001` - -### ERR_NAME_REVOKED -#### type: `int` -#### value: `2014` - -### ERR_NAME_STX_BURNT_INSUFFICIENT -#### type: `int` -#### value: `2007` - -### ERR_NAME_TRANSFER_FAILED -#### type: `int` -#### value: `2015` - -### ERR_NAME_UNAVAILABLE -#### type: `int` -#### value: `2004` - -### ERR_PANIC -#### type: `int` -#### value: `0` - -### ERR_PRINCIPAL_ALREADY_ASSOCIATED -#### type: `int` -#### value: `3001` diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md b/i18n/ru/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md deleted file mode 100644 index ce1b1ba859..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -title: Stacking Contract -description: See a detailed list of all functions and error codes of the Stacking contract. ---- - -## Introduction - -Stacking is implemented as a smart contract using Clarity. You can always find the Stacking contract identifier using the Stacks Blockchain API [`v2/pox` endpoint](https://docs.hiro.so/api#operation/get_pox_info). - -Below is a list of public and read-only functions as well as error codes that can be returned by those methods: - -* [Public functions](#public-functions) -* [Read-only functions](#read-only-functions) -* [Error codes](#error-codes) - -## Public functions - -### allow-contract-caller -#### input: `principal, (optional uint)` -#### output: `(response bool int)` -#### signature: `(allow-contract-caller caller until-burn-ht)` -#### description: -Give a contract-caller authorization to call stacking methods. Normally, stacking methods may only be invoked by _direct_ transactions (i.e., the `tx-sender` issues a direct `contract-call` to the stacking methods). - -By issuing an allowance, the tx-sender may call through the allowed contract. - -### delegate-stack-stx -#### input: `principal, uint, (tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint` -#### output: `(response (tuple (lock-amount uint) (stacker principal) (unlock-burn-height uint)) int)` -#### signature: `(delegate-stack-stx stacker amount-ustx pox-addr start-burn-ht lock-period)` -#### description: -As a delegate, stack the given principal's STX using `partial-stacked-by-cycle`. - -Once the delegate has stacked > minimum, the delegate should call `stack-aggregation-commit`. - -### delegate-stx -#### input: `uint, principal, (optional uint), (optional (tuple (hashbytes (buff 20)) (version (buff 1))))` -#### output: `(response bool int)` -#### signature: `(delegate-stx amount-ustx delegate-to until-burn-ht pox-addr)` -#### description: -Delegate to `delegate-to` the ability to stack from a given address. - -This method _does not_ lock the funds, rather, it allows the delegate to issue the stacking lock. - -The caller specifies: - -* amount-ustx: the total amount of ustx the delegate may be allowed to lock -* until-burn-ht: an optional burn height at which this delegation expiration -* pox-addr: an optional p2pkh or p2sh address to which any rewards *must* be sent - -### disallow-contract-caller -#### input: `principal` -#### output: `(response bool int)` -#### signature: `(disallow-contract-caller caller)` -#### description: -Revokes authorization from a contract to invoke stacking methods through contract-calls - -### reject-pox -#### input: -#### output: `(response bool int)` -#### signature: `(reject-pox)` -#### description: -Reject Stacking for this reward cycle. - -`tx-sender` votes all its uSTX for rejection. - -Note that unlike Stacking, rejecting PoX does not lock the tx-sender's tokens: PoX rejection acts like a coin vote. - -### revoke-delegate-stx -#### input: -#### output: `(response bool int)` -#### signature: `(revoke-delegate-stx)` -#### description: -Revoke a Stacking delegate relationship. A particular Stacker may only have one delegate, so this method does not take any parameters, and just revokes the Stacker's current delegate (if one exists). - -### stack-aggregation-commit -#### input: `(tuple (hashbytes (buff 20)) (version (buff 1))), uint` -#### output: `(response bool int)` -#### signature: `(stack-aggregation-commit pox-addr reward-cycle)` -#### description: -Commit partially stacked STX. - -This allows a stacker/delegate to lock fewer STX than the minimal threshold in multiple transactions, - -so long as: - -1. The pox-addr is the same. -2. This \"commit\" transaction is called _before_ the PoX anchor block. - -This ensures that each entry in the reward set returned to the stacks-node is greater than the threshold, - - but does not require it be all locked up within a single transaction - -### stack-stx -#### input: `uint, (tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint` -#### output: `(response (tuple (lock-amount uint) (stacker principal) (unlock-burn-height uint)) int)` -#### signature: `(stack-stx amount-ustx pox-addr start-burn-ht lock-period)` -#### description: -Lock up some uSTX for stacking! Note that the given amount here is in micro-STX (uSTX). - -The STX will be locked for the given number of reward cycles (lock-period). - -This is the self-service interface. tx-sender will be the Stacker. - -* The given stacker cannot currently be stacking. -* You will need the minimum uSTX threshold. This isn't determined until the reward cycle begins, but this method still requires stacking over the _absolute minimum_ amount, which can be obtained by calling `get-stacking-minimum`. -* The pox-addr argument must represent a valid reward address. Right now, this must be a Bitcoin p2pkh or p2sh address. It cannot be a native Segwit address, but it may be a p2wpkh-p2sh or p2wsh-p2sh address. - -The tokens will unlock and be returned to the Stacker (tx-sender) automatically. - -## Read-only functions - -### can-stack-stx -#### input: `(tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint, uint` -#### output: `(response bool int)` -#### signature: `(can-stack-stx pox-addr amount-ustx first-reward-cycle num-cycles)` -#### description: -Evaluate if a participant can stack an amount of STX for a given period. - -### get-pox-info -#### input: -#### output: `(response (tuple (current-rejection-votes uint) (first-burnchain-block-height uint) (min-amount-ustx uint) (prepare-cycle-length uint) (rejection-fraction uint) (reward-cycle-id uint) (reward-cycle-length uint) (total-liquid-supply-ustx uint)) UnknownType)` -#### signature: `(get-pox-info)` -#### description: -Returns information about PoX status. - -### get-pox-rejection -#### input: `principal, uint` -#### output: `(optional (tuple (amount uint)))` -#### signature: `(get-pox-rejection stacker reward-cycle)` -#### description: -Returns the amount of uSTX that a given principal used to reject a PoX cycle. - -### get-stacker-info -#### input: `principal` -#### output: `(optional (tuple (amount-ustx uint) (first-reward-cycle uint) (lock-period uint) (pox-addr (tuple (hashbytes (buff 20)) (version (buff 1))))))` -#### signature: `(get-stacker-info stacker)` -#### description: -Returns the _current_ stacking information for `stacker. If the information is expired, or if there's never been such a stacker, then returns none. - -### get-stacking-minimum -#### input: -#### output: `uint` -#### signature: `(get-stacking-minimum)` -#### description: -Returns the absolute minimum amount that could be validly Stacked (the threshold to Stack in a given reward cycle may be higher than this - -### get-total-ustx-stacked -#### input: `uint` -#### output: `uint` -#### signature: `(get-total-ustx-stacked reward-cycle)` -#### description: -Returns the amount of currently participating uSTX in the given cycle. - -### is-pox-active -#### input: `uint` -#### output: `bool` -#### signature: `(is-pox-active reward-cycle)` -#### description: -Returns whether or not PoX has been rejected at a given PoX cycle. -## Error codes - -### ERR_DELEGATION_EXPIRES_DURING_LOCK -#### type: `int` -#### value: `21` - -### ERR_DELEGATION_POX_ADDR_REQUIRED -#### type: `int` -#### value: `23` - -### ERR_DELEGATION_TOO_MUCH_LOCKED -#### type: `int` -#### value: `22` - -### ERR_INVALID_START_BURN_HEIGHT -#### type: `int` -#### value: `24` - -### ERR_NOT_ALLOWED -#### type: `int` -#### value: `19` - -### ERR_STACKING_ALREADY_DELEGATED -#### type: `int` -#### value: `20` - -### ERR_STACKING_ALREADY_REJECTED -#### type: `int` -#### value: `17` - -### ERR_STACKING_ALREADY_STACKED -#### type: `int` -#### value: `3` - -### ERR_STACKING_EXPIRED -#### type: `int` -#### value: `5` - -### ERR_STACKING_INSUFFICIENT_FUNDS -#### type: `int` -#### value: `1` - -### ERR_STACKING_INVALID_AMOUNT -#### type: `int` -#### value: `18` - -### ERR_STACKING_INVALID_LOCK_PERIOD -#### type: `int` -#### value: `2` - -### ERR_STACKING_INVALID_POX_ADDRESS -#### type: `int` -#### value: `13` - -### ERR_STACKING_NO_SUCH_PRINCIPAL -#### type: `int` -#### value: `4` - -### ERR_STACKING_PERMISSION_DENIED -#### type: `int` -#### value: `9` - -### ERR_STACKING_POX_ADDRESS_IN_USE -#### type: `int` -#### value: `12` - -### ERR_STACKING_STX_LOCKED -#### type: `int` -#### value: `6` - -### ERR_STACKING_THRESHOLD_NOT_MET -#### type: `int` -#### value: `11` - -### ERR_STACKING_UNREACHABLE -#### type: `int` -#### value: `255` \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md b/i18n/ru/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md deleted file mode 100644 index 5f38edfb57..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: xBTC -description: Wrapped BTC on Stacks ---- - -![](/img/xbtc-icon.webp) - -## Introduction - -[Wrapped.com](https://www.wrapped.com) has brought Bitcoin (xBTC) to the Stacks ecosystem. - -xBTC is backed 1:1 by Bitcoin and empowers developers to expand the Bitcoin DeFi ecosystem. - -The reserves are publicly visible [here](https://open.wrapped.com/reserves/). - -## Contract - -[SP3DX3H4FEYZJZ586MFBS25ZW3HZDMEW92260R2PR.Wrapped-Bitcoin](https://explorer.stacks.co/txid/SP3DX3H4FEYZJZ586MFBS25ZW3HZDMEW92260R2PR.Wrapped-Bitcoin?chain=mainnet) - -## Examples of uses - -[Friedger Mining Pool](https://pool.friedger.de/) currrently supports Stacking rewards payments in xBTC (optional). - - -## More information - -* [Blog post announcement](https://www.stacks.co/blog/tokensoft-wrapped-fundamental-bitcoin-defi-building-blocks-xbtc) by Muneeb Ali - -* Video: [Why xBTC is Important For Bitcoin to Grow](https://www.youtube.com/watch?v=xIoadrfSdi4) \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/references/_category_.json b/i18n/ru/docusaurus-plugin-content-docs/current/references/_category_.json deleted file mode 100644 index 3805ab0783..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/references/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "References", - "position": 9, - "link": { - "type": "generated-index", - "description": "Stacks references." - } -} \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/references/glossary.md b/i18n/ru/docusaurus-plugin-content-docs/current/references/glossary.md deleted file mode 100644 index f97908371a..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/references/glossary.md +++ /dev/null @@ -1,215 +0,0 @@ ---- -title: Glossary -description: A comprehensive list of terms used within the ecosystem. ---- - -A comprehensive list of terms used within the ecosystem. - -#### App Review -An incentive mechanism for application developers in the early stage (first four years) of the ecosystem and helps with bootstrapping the two-sided market. - -#### Atlas -A peer network provide a global index for discovery. - -#### Bitcoin (BTC) address -A string of letters and numbers. `3E53XjqK4Cxt71BGeP2VhpcotM8LZ853C8` Sharing this address allows anyone to send Bitcoin to the address. - -#### block -A discrete group of records written to a blockchain that can effectively be identified and referenced by the use of headers that contain a digital fingerprint of the records each block contains. - -#### blockchain -A database created and shared by the members of a peer-to-peer computer network which each member of that network can independently trust due to the rules governing the database’s creation. A blockchain can therefore be used to replace centralized databases. - -#### Blockchain Name System (BNS) -Replacement for DNS. More info [here](../noteworthy-contracts/bns-contract). - -#### Blockstack Browser -A deprecated application for accessing identity and storage. - -#### Blockstack Owner Address - -Looks like a bitcoin address but starts with `ID` for example: `ID-1J3PUxY5uDShUnHRrMyU6yKtoHEUPhKULs` - -#### Burning -Burning a token means that the token is transferred to an address that is a black hole—one that is not owned by any entity and for which guessing the applicable private key is effectively impossible based on known mathematical principles. This effectively destroys the token by making it unavailable for future use and decreases the total number of tokens available from that point forward. - -#### consensus hash -A consensus hash is a cryptographic hash that each node calculates at each block. It is derived from the accepted state transitions in the last-processed block and a geometric series of prior-calculated consensus hashes. - -#### Consensus rules -"The rules governing the creation of new valid records in a blockchain database and the mining algorithms used for this purpose. - -#### control plane -The part of a network that carries signaling traffic and is responsible for routing. Control packets originate from or are destined for a router. Functions of the control plane include system configuration and management. - -#### core node -A server that runs Stacks Blockchain services. - -#### crypto-asset -A digital asset which utilises cryptography, peer-to-peer networking and a public ledger to regulate the creation of new units, verify transactions and secure the transactions without the intervention of any middleman. - -#### cryptography -The practise and study of encryption and decryption - encoding data so that it can only be decoded by specific individuals. A system for encrypting and decrypting data is a cryptosystem. - -#### DAO -See Decentralized Autonomous Organization. - -#### decentralized application (DApp) -A DApp is a service that enables direct interaction between end users and providers (e.g. connecting buyers and sellers in some marketplace, owners and stores in file storage). A term coined by Ethereum. See their glossary: http://ethdocs.org/en/latest/glossary.html#dapp" - -#### Decentralized Autonomous Organization -A type of contract or suite of contracts on the blockchain that is intented to codify, enforce or automate the processes of an organization. - -#### digital asset -Also referred to as a crypto-asset. Any set of unique digital information—including, for example, programs, decentralized programs, isolated chunks of programming code, collections of data, e-mail or web addresses or cryptocurrency tokens—that is capable of being stored and uniquely tracked on a computer network such as the Stacks network and over which a user can maintain control through that network. - -#### digital fingerprint -A digital fingerprint is a unique number of a fixed length that can be produced by running any set of digital information through something called a cryptographic hash function. Each set of digital information (including a digital asset, and the digital record of any network operation on that digital asset) should (as a practical matter) have a unique digital fingerprint, which allows that set of digital information to be identified. However, it is almost impossible to recreate a digital asset from its digital fingerprint. The Blockstack network uses industry-standard algorithms such as SHA-256 to create digital fingerprints. - -#### digital signature -A digital signature is a sequence of digital information combining a user’s private key and any digital information that the user wishes to sign. Any other party can use the user’s paired public key to verify that the digital signature is authentic, i.e. that the public key was generated from a particular piece of digital information and the user’s private key. - -#### distributed hash tables (DHT) -A form of network used to store some content in the form of key/value pairs. ... This experimental project try to avoid keeping all the blockchain, but instead prefers to store it in a DHT. - -#### ephemeral key -A cryptographic key is called ephemeral if it is generated for each execution of a key establishment process. - -#### fork -The term fork is used to refer both to any situation where there are two or more competing versions of a blockchain on a network (a situation that may arise and resolve itself in the ordinary course of network operations due to lags in communication between core nodes) and any software update that is proposed for adoption by the core nodes of a blockchain network that may result in a persistent fork on the network, with core nodes that adopt the update recognizing one version of the blockchain and those which do not recognizing another. - -#### Gaia -Decentralized storage architecture for off-chain data. More info [here](../gaia). - -#### genesis block -The genesis block is the first block of the Stacks blockchain, which will create the initial 1.32 billion Stacks Tokens. - -#### id.blockstack -An identifier in the Blockstack, for example meepers.id.blockstack. This is your name & identity that is registered in the .id namespace on Blockstack. Your personal data and storage are built around this ID. Apps that want to access your data use your permission and identity to find it. An id is usually a shorthand for a longer, hash ID string, for example ID-1Fj9kkw15P51Fj9kkw15P5xJmyefWhLKrQMKNPREfaqsJ" - -#### identity - -A way to identify a person or an organization on the Stacks network. An identity is unique, both `meepers.id.blockstack` or `chad.id` are examples of IDs. - -#### identity management (IDM) -Identity management, also known as identity and access management is, in computer security, the security and business discipline that enables the right individuals to access the right resources at the right times and for the right reason". - -#### know your customer (KYC) -Or KYC, is a popular term used in the banking or financial field. KYC is a process where financial institutions, insurers and other companies obtain information about the identity and address of the customers as part of risk management. - -#### light clients -Clients that can independently validate the existence of transactions by downloading only block headers and not the entire blockchain. - -#### magic recovery code - -A long encrypted string, for example: `36mWivFdy0YPH2z31EflpQz/Y0UMrOrJ++lH=0EI7c3mop2JuRBm5WXxSTazJsUjOA...` Do not share the QR code that accompanied your recovery code either. This is a QR code: - -![](/img/qr-code.png) - -#### mesh network -A local network topology in which the infrastructure nodes (i.e. bridges, switches, and other infrastructure devices) connect directly, dynamically and non-hierarchically to as many other nodes as possible and cooperate with one another to efficiently route data from/to clients. - -#### mining -Mining generally refers to the process of performing certain functions for a network such as adding new records to a blockchain in exchange for mining rewards; it may also refer to other mechanisms whereby rewards (usually in the form of cryptocurrency) are provided for performing other tasks helpful to the network. - -#### mining power -A miner’s (or group of miners’) mining power is equal to the probability it will be selected to write a new block to the blockchain. Depending on the mechanism for mining, this is usually related to the overall share of computing power or cryptoassets the miner or miners possess relative to all miners for that blockchain. - -#### mining rewards -Mining rewards are newly issued tokens received by miners in exchange for adding new records to the blockchain or other activities beneficial to the network. - -#### name -An identifier or name. Names are a type of digital asset in the Stacks network. If you have signed into the Stacks Wallet, you might have created a name. If an application developer registered an application within Stacks, then they registered a name. Public Stacking pools can also have a name. - -#### network operation -A network operation is any change to the information about a digital asset (or smart contract) stored on a blockchain, including, for example, a change in the digital asset’s owner, or a change in the location at which it is stored on the network. How and when these network operations are performed for each digital asset is governed, on the Blockstack network, either by the Stacks Node software or a smart contract. - -#### NFT -Non fungible token. - -#### private key - -Private keys matches a corresponding public key. A public key also looks like a string of letters and numbers: - -![](/img/private.png) - -The exact format of the public and private key depend on the software you use to create them. - -#### proof-of-burn mining -The consensus algorithm used in the Stacks blockchain where miners destroy a proof-of-work-based cryptocurrency (currently Bitcoin) to get tokens; this enables the functionality where nodes can select between conflicting blockchain forks, as the blockchain fork with the most amount of cryptocurrency burned is considered to be the correct fork. - -#### proof-of-work -A proof-of-work system or proof-of-work mining is a mining mechanism where miners must expend computing power to solve complicated cryptographic puzzles, and prove that they have done so by writing the solution to the blockchain, in order to be allowed to add blocks to a blockchain. This is the mining system used, for example, by Bitcoin. - -#### public key -Public and private key pair comprise of two uniquely related cryptographic keys. It looks like a long random string of letters and numbers: `3048 0241 00C9 18FA CF8D EB2D EFD5 FD37 89B9 E069 EA97 FC20 …` The exact format of the public and private key depend on the software you use to create them. - -#### Public Key Infrastructure (PKI) -A system which returns a cryptographic public key associated with a name. - -#### replicated state machines (RSMs) -This is a model for reasoning about distributed computer programs -- any program (plus it's input) can be represented as a state machine, and when trying to get a distributed set of servers to agree on the output of an algorithm, you can model that process as N different state machines" - -#### Secret recovery Key, -Used to access an identity on the Stacks blockchain. A 24-word sequence of words for example: `applied binge crisp pictorial fiery` `dancing agreeable frogs light finish ping apple` - -#### seed phrase - -Used to access Stacks Wallet software. The seed phrase consists of 24 words in a sequence. Both the word *and its position the sequence* are important. Write down your seed phrase and store it in a secure location such as a safe deposit box. When you write the seed phrase down, include its position, for example,`1-frog, 2-horse, 3-building` and so on until you reach a final position `24-ocean`. -#### smart contract -A smart contract is a computer program written to a blockchain such as the Stacks blockchain by developers. This computer program defines the various network operations that can be performed on the digital assets on the blockchain, the computations that can be performed using the smart contract, along with defining various important properties of the respective digital assets like ownership rights and the cost in fuel required to register the digital assets. - -#### soft fork -A soft fork is a proposed update to the software governing the network that results in a post-update network that is compatible with the network as it existed prior to the update, because it restricts the network operations that can be performed after the update. - -#### Stacks (STX) address - - A STX address is a string of letters and numbers starting with an `SP` or `SM`, for example: `SM3KJBA4RZ7Z20KD2HBXNSXVPCR1D3CRAV6Q05MKT` If you created a software-only wallet with the Stacks Wallet software, the wallet has a single STX address which is also sometimes called the *wallet address*. You access a software wallet with a *seed phrase*. " - -#### Stacks blockchain -The Stacks blockchain is the custom blockchain being developed for use by the Stacks network that will use the Stacks token as its native currency and which will include the genesis block and subsequent blocks created by the mining activities described in the Stacks Network—Development of the Stacks network. - -#### Stacks Explorer -An application that allow you to view and search transactions in the blockchain. For example, https://explorer.stacks.co. - -#### Stacks node -A complete version of our open-source software available on Github at https://github.com/stacks-network/stacks-blockchain/ that governs the creation of the blockchain, the smart contracts that may be written to our blockchain, and other systems that make up the Stacks network, when run on the systems and devices of our users and developers. - -#### Stacks wallet -An application for accessing assets, identity and storage. Examples are the [Hiro Wallet](https://www.hiro.so/wallet), [xverse](https://www.xverse.app/) and [dcent](https://dcentwallet.com/). More information and example [here](../services-using-stacks/wallets). - -#### storage hub -A Gaia instance run by a hub provider or software. A Gaia hub stores data in a separate, addressed location. - -#### storage provider -A third-party company cloud or software provider that hosts one or more Gaia storage hubs. - -#### transaction -A transaction is a unit of work within a block. - -#### transaction fee -Fees paid by participants in a transaction to miners. - -#### two-sided market problem -Economic platforms having two distinct user groups that provide each other with network benefits. The Stacks platform is a classic two-sided market. - -#### username -A shorthand name for your id.blockstack. - -#### virtual blockchain -A layer that sits on top of a blockchain that introduces new functionality and operations without requiring changes to the underlying blockchain. - -#### wallet address -A wallet address is the form in which a public key can be presented and recorded on a blockchain. Wallet addresses are therefore used to assign the ownership of digital assets on the Blockstack network. - -#### watch-only wallet -A wallet without send and receive ability. You can view only balances and transaction history. - -#### web of trust mining -Web-of-trust mining provides incentive mechanisms for users where an initial trusted-set of unique users is curated in the genesis block and, in the future, the initial set of users can expand the web-of-trust after the network goes live. - -#### web3 -The exact definition is still under discussion, but it general refers to the 3rd generation of the web that is based on blockchain technology and incorporates decentralized and token-based economics. - -#### zone file -A Domain Name System (DNS) zone file is a text file that describes a DNS zone. A DNS zone is a subset, often a single domain, of the hierarchical domain name structure of the DNS. diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/references/nft.md b/i18n/ru/docusaurus-plugin-content-docs/current/references/nft.md deleted file mode 100644 index 033ee0a71a..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/references/nft.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: NFTs on Stacks -description: A list of sites that operate NFTs on Stacks ---- - -List of sites that operate NFTS on Stacks on alphabetical order. - -### [Byzantion](https://byzantion.xyz/) - -![website-screenshot](/img/sh_nft_byzantion.png) - -### [Gamma](https://gamma.io/) -![website-screenshot](/img/sh_nft_gamma.png) - -### [Megapont](https://www.megapont.com/) - -![website-screenshot](/img/sh_nft_megapont.png) - -### [StacksArt](https://www.stacksart.com/) - -![website-screenshot](/img/sh_nft_stacksart.png) - diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md b/i18n/ru/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md deleted file mode 100644 index dc6e507d5e..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Stacks info sites -description: A list of sites on alphabetical order that display status and stats of the Stacks network. ---- - -### [Haystack](https://haystack.tools/mempool) - -![website-screenshot](/img/sh_haystacks.png) - -### [Stacksdata](https://stacksdata.info/) - -![website-screenshot](/img/sh_stacksdata.png) - -### [Stacksonchain](https://stacksonchain.com) - -![website-screenshot](/img/sh_stacksonchain.png) - -### [Status Hiro](https://status.hiro.so/) - -![website-screenshot](/img/sh_statushiro.png) - -### [Stxstats](https://www.stxstats.co/) - -![website-screenshot](/img/sh_stxstats.png) - -### [Novuminsights](https://stacks.novuminsights.com/health) - -![website-screenshot](/img/sh_novuminsights.png) - -### [Onstacks](https://app.onstacks.com/) - -![website-screenshot](/img/sh_onstacks.png) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json b/i18n/ru/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json deleted file mode 100644 index ebd63f366c..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Services using Stacks", - "position": 8, - "link": { - "type": "generated-index", - "description": "An 'always incomplete' list of services that use Stacks." - } -} \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md b/i18n/ru/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md deleted file mode 100644 index 51defacba7..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: DeFi -description: De-Fi sites on Stacks -sidebar_position: 2 ---- - -They are multiple De-Fi sites that operate on the Stacks blockchain. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Alex - -[Alex](https://app.alexlab.co) ![](/img/sh_alex.png) - -## Arkadiko - -[Arkadiko](https://arkadiko.finance/) ![](/img/sh_arkadiko.png) - -## Catamaran Swaps - -[Catamaran Swaps](https://www.catamaranswaps.org/) allows trustless exchange of digital assets. - -![](/img/sh_catamaran.png) - -## Lnswap - -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange - -![](/img/sh_lnswap.png) - -## Neoswap - -[Neoswap](https://neoswap.party) - -![](/img/sh_neoswap.png) - -## Stackswap - -[Stackswap](https://app.stackswap.org/v2) - -![](/img/sh_stackswap.png) - diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/services-using-stacks/more.md b/i18n/ru/docusaurus-plugin-content-docs/current/services-using-stacks/more.md deleted file mode 100644 index df0b3e2254..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/services-using-stacks/more.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: More -description: More services built on Stacks. -sidebar_position: 5 ---- - -List of sites on alphabetical order added by the community. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Citycoins - -[Citycoins](https://citycoins.co) - -![](/img/sh_citycoins.png) - -## Sigle - -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. - -![](/img/sh_sigle.png) \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md b/i18n/ru/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md deleted file mode 100644 index bfa0505dc9..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: NFTs -description: NFTs on Stacks -sidebar_position: 3 ---- - -List of sites that operate NFTS on Stacks on alphabetical order. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -### [Byzantion](https://byzantion.xyz/) - -![website-screenshot](/img/sh_nft_byzantion.png) - -### [Gamma](https://gamma.io/) -![website-screenshot](/img/sh_nft_gamma.png) - -### [Megapont](https://www.megapont.com/) - -![website-screenshot](/img/sh_nft_megapont.png) - -### [StacksArt](https://www.stacksart.com/) - -![website-screenshot](/img/sh_nft_stacksart.png) - -### [Superfandom](https://superfandom.io/) - -![website-screenshot](/img/sh_superfandom.png) \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/services-using-stacks/other.md b/i18n/ru/docusaurus-plugin-content-docs/current/services-using-stacks/other.md deleted file mode 100644 index 199fc41da5..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/services-using-stacks/other.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Other Stacks sites -description: A list of sites on alphabetical order built on Stacks. -sidebar_position: 4 ---- - -List of sites on alphabetical order added by the community. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Alex -[Alex](https://app.alexlab.co) - -## Sigle - -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md b/i18n/ru/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md deleted file mode 100644 index 35ced8dac6..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Stacks info sites -description: Status and stats of the Stacks network. -sidebar_position: 1 ---- - -A list of sites on alphabetical order that display status and stats of the Stacks network. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -### [Haystack](https://haystack.tools/mempool) - -![website-screenshot](/img/sh_haystacks.png) - -### [Stacksdata](https://stacksdata.info/) - -![website-screenshot](/img/sh_stacksdata.png) - -### [Stacksonchain](https://stacksonchain.com) - -![website-screenshot](/img/sh_stacksonchain.png) - -### [Status Hiro](https://status.hiro.so/) - -![website-screenshot](/img/sh_statushiro.png) - -### [Stxstats](https://www.stxstats.co/) - -![website-screenshot](/img/sh_stxstats.png) - -### [Novuminsights](https://stacks.novuminsights.com/health) - -![website-screenshot](/img/sh_novuminsights.png) - -### [Onstacks](https://app.onstacks.com/) - -![website-screenshot](/img/sh_onstacks.png) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md b/i18n/ru/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md deleted file mode 100644 index d4b4cbf18c..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Swaps -description: A list of sites that allow Swaps -sidebar_position: 2 ---- - -They are multiple sites that allow you to make swaps using the Stacks blockchain. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Catamaran Swaps - -[Catamaran Swaps](https://www.catamaranswaps.org/) allows trustless exchange of digital assets. - -![](/img/sh_catamaran.png) - -## Lnswap - -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange - -![](/img/sh_lnswap.png) - -## Neoswap - -[Neoswap](https://neoswap.party) - -![](/img/sh_neoswap.png) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md b/i18n/ru/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md deleted file mode 100644 index e5ea6c5b45..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Wallets -description: Wallets for Stacks -sidebar_position: 4 ---- - -A list of hardware and software wallets for Stacks - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Blockchain.com - -[Blockchain.com](https://www.blockchain.com/wallet) - -![](/img/sh_blockchain.png) -## Boom - -[Boom](https://boom.money) - -![](/img/sh_boom.png) - -## Dcent wallet - -[D'CENT](https://dcentwallet.com) - -![](/img/sh_dcent.png) -## Hiro Wallet - -[Hiro Wallet](https://www.hiro.so/wallet) - -![](/img/sh_hirowallet.png) - -## Neptune - -[Neptune](https://neptunewallet.io) - -![](/img/sh_neptunewallet.png) - -## Xverse - -[Xverse](https://www.xverse.app/) - -![](/img/sh_xverse.png) - -## Wise - -[Wise](https://wiseapp.id) - -![](/img/sh_wiseapp.png) \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md b/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md deleted file mode 100644 index bd2c361985..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md +++ /dev/null @@ -1,214 +0,0 @@ ---- -title: Accounts -description: Guide to Stacks 2.0 accounts -sidebar_position: 5 ---- - -## Introduction - -Stacks 2.0 accounts are entities that own assets, like Stacks (STX) tokens. An account has an address, private key, nonce, and one or more asset balances. - -:::tip The encryption algorithm used in Stacks 2.0 is **[secp256k1](https://en.bitcoinwiki.org/wiki/Secp256k1)**. - -Additionally, [Ed25519](https://ed25519.cr.yp.to/) is also used just for the VRF (Verifiable Random Function). ::: - -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. - -:::tip -The transaction type doesn't need to be a token transfer - contract deploy and contract call transactions can change the balances of an account -::: - -## Creation - -An account is generated from a 24-word mnemonic phrase. This is often referred to as the **seed phrase**. The seed phrase provides access to Stacks 2.0 accounts. - -:::danger -If the seed phrase is lost, access to the associated account cannot be restored. No person or organization, including Blockstack, can recover a lost seed phrase. -::: - -The easiest way to generate a new Stacks 2.0 account is to use the [Stacks CLI](https://github.com/hirosystems/stacks.js/tree/master/packages/cli): - -```bash -# install CLI globally -npm install --global @stacks/cli - -# generate a new account and store details in a new file -# '-t' option makes this a testnet account -stx make_keychain -t > cli_keychain.json -``` - -`make_keychain` creates the following file: - -```js -{ - "mnemonic": "aaa bbb ccc ddd ...", - "keyInfo": { - "privateKey": "5a3f1f15245bb3fb...", - "address": "STJRM2AMVF90ER6G3RW1QTF85E3HZH37006D5ER1", - "btcAddress": "biwSd6KTEvJcyX2R8oyfgj5REuLzczMYC1", - "wif": "L4HXn7PLmzoNW...", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -| Field | Description | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `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.privateKey` | Private key for the account. Required for token transfers and often referred to as `senderKey` | -| `keyInfo.address` | Stacks address for the account | -| `keyInfo.btcAddress` | Corresponding BTC address for the account. | -| `keyInfo.wif` | Private key of the btcAddress in compressed format. | -| `keyInfo.index` | Nonce for the account, starting at 0 | - -Note that a new account automatically exists for each new private key. There is no need to manually instantiate an account on the Stacks 2.0 blockchain. - -:::tip Addresses are created by generating the [RIPEMD-160 hash](https://en.wikipedia.org/wiki/RIPEMD#RIPEMD-160_hashes) of the [SHA256](https://en.bitcoinwiki.org/wiki/SHA-256) of the public key. BTC addresses are encoded with [Base58Check](https://en.bitcoin.it/wiki/Base58Check_encoding). For Stacks addresses, [c32check](https://github.com/stacks-network/c32check) is used. Deriving an address from a public key can be done without internet access, for instance using the c32check `c32addressDecode` method. ::: - -Alternatively to the CLI creation, the [Stacks Transactions JS](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library can be used: - -```js -import { - makeRandomPrivKey, - privateKeyToString, - getAddressFromPrivateKey, - TransactionVersion, -} from '@stacks/transactions'; - -const privateKey = makeRandomPrivKey(); - -// Get public key from private -const publicKey = getPublicKey(privateKey); - -const stacksAddress = getAddressFromPrivateKey( - privateKeyToString(privateKey), - TransactionVersion.Testnet // remove for Mainnet addresses -); -``` - -A second alternative would be to use [stacks-gen](https://github.com/psq/stacks-gen). This tool will generate all the keys you need in one place, including the values needed for calling the stacking contract, and also a WIF key for use with `bitcoind`. - -#### stacks-gen prerequisite - -Install [npx](https://github.com/npm/npx) if not already installed. (npx will check whether `` exists in \$PATH, or in the local project binaries, and execute that. If `` is not found, it will be installed prior to execution). - -``` -npm install -g npx -``` - -#### stacks-gen usage - -``` -npx -q stacks-gen sk --testnet - -{ - "phrase": "guide air pet hat friend anchor harvest dog depart matter deny awkward sign almost speak short dragon rare private fame depart elevator snake chef", - "private": "0351764dc07ee1ad038ff49c0e020799f0a350dd0769017ea09460e150a6401901", - "public": "022d82baea2d041ac281bebafab11571f45db4f163a9e3f8640b1c804a4ac6f662", - "stacks": "ST16JQQNQXVNGR8RZ1D52TMH5MFHTXVPHRV6YE19C", - "stacking": "{ hashbytes: 0x4d2bdeb7eeeb0c231f0b4a2d5225a3e3aeeed1c6, version: 0x00 }", - "btc": "mnYzsxxW271GkmyMnRfiopEkaEpeqLtDy8", - "wif": "cMh9kwaCEttgTQYkyMUYQVbdm5ZarZdBHErcq7mXUChXXCo7CFEh" -} -``` - -:::tip The stacking object with hashbytes and a version represents the bitcoin address derived from the Stacks address. Read more about the [bitcoin address format](stacking#bitcoin-address). ::: - -Full documentation available at [stacks-gen](https://github.com/psq/stacks-gen). - -## Querying - -### Get Stacks (STX) balance and nonce - -STX balance and nonce can be obtained through the [`GET /v2/accounts/`](https://docs.hiro.so/api#operation/get_account_info) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/accounts/' -``` - -Sample response: - -```js -{ - "balance": "0x0000000000000000002386f26f3f40ec", - "nonce": 17 -} -``` - -:::tip -The balance string represents an unsigned 128-bit integer (big-endian) in hex encoding -::: - -### Get all token balances - -All token balances can be obtained through the [`GET /extended/v1/address//balances`](https://docs.hiro.so/api#operation/get_account_balance) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/address//balances' -``` - -Sample response: - -```js -{ - "stx": { - "balance": "0", - "total_sent": "0", - "total_received": "0" - }, - "fungible_tokens": {}, - "non_fungible_tokens": {} -} -``` - -:::tip Stacks accounts cannot hold bitcoins. The best way to obtain corresponding BTC balances is to derive the BTC address from the Stacks address (using [`c32check`](https://github.com/stacks-network/c32check#c32tob58-b58toc32)) and query the Bitcoin network. ::: - -### Get all asset events - -All asset events associated with the account can be obtained through the [`GET /extended/v1/address//assets`](https://docs.hiro.so/api#operation/get_account_balance) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/address//assets' -``` - -Sample response: - -```js -{ - "limit": 20, - "offset": 0, - "total": 0, - "results": [ - { - "event_index": 5, - "event_type": "non_fungible_token_asset", - "asset": { - "asset_event_type": "transfer", - "asset_id": "ST2W14YX9SFVDB1ZGHSH40CX1YQAP9XKRAYSSVYAG.hello_world::hello-nft", - "sender": "SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR", - "recipient": "SM2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQVX8X0G", - "value": { - "hex": "0x0100000000000000000000000000000001", - "repr": "u1" - } - } - }, - { - "event_index": 3, - "event_type": "fungible_token_asset", - "asset": { - "asset_event_type": "mint", - "asset_id": "ST2W14YX9SFVDB1ZGHSH40CX1YQAP9XKRAYSSVYAG.hello_world::novel-token-19", - "sender": "", - "recipient": "SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR", - "amount": "12" - } - } - ] -} -``` diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/index.md b/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/index.md deleted file mode 100644 index 1533219df9..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/index.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Understand Stacks -description: Learn more about the Stacks 2.0 blockchain -sidebar_position: 1 ---- - -![](/img/SBC-L-2x-10.png) -## Introduction - -Stacks 2.0 is a layer-1 blockchain that connects to Bitcoin and brings smart contracts and decentralized apps to it. Smart contracts and apps developed on the Stacks platform are natively integrated with the security, stability, and economic power of Bitcoin. - -## Capabilities - -Read more about the features provided by the Stacks 2.0 blockchain. - - - -:::tip Check out the [technical specifications](technical-specs) for a brief overview ::: - - - - -A detailed [comparison of the Stacks blockchain to other blockchain technologies][] is available at the Stacks Foundation blog. -### Consensus mechanism -![](/img/pages/stacking.svg) Stacks 2.0 implements a new mining mechanism called Proof of Transfer ("PoX"). PoX is a consensus algorithm between two blockchains. It uses an established blockchain (in this case Bitcoin) to secure a new blockchain (Stacks). - -PoX connects to Bitcoin with a 1:1 block ratio, meaning anything that happens on the Stacks blockchain can be verified on the Bitcoin Blockchain. - -Instead of burning electricity on proof of work, PoX reuses already minted bitcoins as "proof of computation" and miners represent their cost of mining in bitcoins directly. - - -[Read more about Proof of Transfer](proof-of-transfer) -### Mining - -![](/img/pages/testnet-sm.svg) Mining is required to make the network usable, trustworthy, and secure. Miners verify incoming transactions, participate in the consensus mechanism, and write new blocks to the blockchain. - -To incentivize mining, miners receive freshly minted Stacks (STX) tokens if they win the bid for becoming the leader of the next round. - -[Read more about Mining](mining) - -### Stacking - -Bitcoins used for miner bids are sent to a set of specific addresses corresponding to Stacks (STX) tokens holders that are actively participating in consensus ("Stackers"). Thus, rather than being destroyed, the bitcoins consumed in the mining process go to productive Stacks holders as a reward based on their holdings of Stacks and participation in the Stacking algorithm. - -Stackers have to lock up their Stacks (STX) tokens for a certain period of time. - -[Read more about Stacking](stacking) - -### Smart contracts - -![](/img/pages/write-smart-contracts-sm.svg) Clarity is a new language for smart contracts on the Stacks 2.0 blockchain. The Clarity smart contract language optimizes for predictability and security. - -Stacks 2.0 anchors clarity smart contracts to Bitcoin making it possible for smart contracts to operate based on actions seen on the bitcoin blockchain. - -:::note The [Clarity open-source project](https://clarity-lang.org/) is supported by Stacks and [Algorand](https://www.algorand.com/) ::: - - -Clarity is distinct from other languages designed for writing smart contracts in a few ways: - -- **Predictability**: The Clarity language uses precise and unambiguous syntax that allows developers to predict exactly how their contracts will be executed. -- **Security**: The Clarity language allows users to supply their own conditions for transactions that ensure that a contract may never unexpectedly transfer a token owned by a user. -- **No compiler**: Contracts written in Clarity are broadcasted on the Stacks blockchain exactly as they are written by developers. This ensures that the code developers wrote, analyzed, and tested, is exactly what gets executed. - -[Read more about Clarity](../write-smart-contracts/clarity-language/) - -## Guides - -Read one of our guides to understand the ins and outs of the Stacks 2.0 blockchain. - -* [Account](../understand-stacks/accounts) -* [Transactions](../understand-stacks/transactions) -* [Network](../understand-stacks/network) -* [Microblocks](../understand-stacks/microblocks) - -[comparison of the Stacks blockchain to other blockchain technologies]: https://stacks.org/stacks-blockchain diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md b/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md deleted file mode 100644 index de64c617f4..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: Microblocks -description: Guide to Stacks Microblocks -sidebar_position: 8 ---- - -## Introduction - -Microblocks are a protocol-level feature of the Stacks blockchain that solve the technical challenge of transaction latency. Because each Stacks block is anchored to a Bitcoin block through the [Proof-of-Transfer consensus mechanism](../understand-stacks/proof-of-transfer), Stacks is necessarily limited to the same block times as the Bitcoin network. Microblocks allow the Stacks blockchain to perform state transitions between anchor blocks. - -Microblocks are a powerful mechanism for developers to create performant, high quality applications on Stacks, while still inheriting the security of Bitcoin. - -## Transaction states - -The [Stacks block production model](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.) is described in SIP-001. The standard outlines the mechanism by which elected block leaders can produce blocks on the Stacks blockchain either by batching transactions or by streaming them. Microblocks are the product of the streaming model. - -If a block leader has elected to mine microblocks, the leader selects transactions from the mempool and package them into microblocks during the current epoch. Microblocks are blocks of transactions included by a miner after the previous anchor block has been mined, but before the next block is selected. Transactions included in microblocks are processed by the network: their results are known. - -Consider a transaction from the perspective of the number of block confirmations it has. A transaction included in a microblock might have the following example lifecycle: - -``` -Transaction 1 is broadcast to the mempool. It has 0 confirmations. -Transaction 1 is included in a microblock. It still has 0 confirmations, but the results of the transaction are known -Transaction 1 is included in the next anchor block. It has 1 confirmation. -The next Stacks block confirms the previous block. Transaction 1 has 2 confirmations. -The next Stacks block confirms the previous block. Transaction 1 has 3 confirmations. -... -``` - -Consider a similar transaction that is not included in a microblock: - -``` -Transaction 2 is broadcast to the mempool. It has 0 confirmations. -Transaction 2 is included in the next anchor block. It has 1 confirmation. -The next Stacks block confirms the previous block. Transaction 2 has 2 confirmations. -The next Stacks block confirms the previous block. Transaction 2 has 3 confirmations. -``` - -The lifecycles of the two transactions are similar, but the difference is pending state. Many Bitcoin wallets display 0-confirmation balances: your wallet balance with any mempool transactions already applied. This is useful because it tells you when you've sent a transaction or received one. With smart contracts, displaying pending state is not as straightforward, because smart contracts do not just transfer inputs to outputs, they may call other contracts, emit events, or perform other computations. A transaction processed in a microblock generates all that information. - -:::tip -If a transaction is dependent on a chain state that could by altered by previous transactions with serious -implications, you should carefully consider whether it should be performed using microblocks. -::: - -## Enabling microblocks - -Miners can choose to enable or disable microblocks in their mining configuration. As a best practice, miners should enable microblock mining. When an application or user submits a transaction, the transaction can include an argument that requires the transaction to be in a microblock, an anchor block, or in either. - -### Transactions - -Transactions include an option that controls if a miner should include them in microblocks or in anchor blocks. The anchor mode transaction option is an optional argument that controls whether a transaction must be included in an anchor block or a microblock, or is eligible for either. - -### Mining - -Stacks miners must enable microblocks in their miner configuration to implement the block streaming model. For more information, see [mining microblocks](../understand-stacks/mining#microblocks). - -## Developing with microblocks - -In most cases, information from transactions included in microblocks should be treated like information from any other block. Wallets and explorers should display the consequences of microblock transactions as the current state of the network. This state should be acknowledged as tentative. - -A microblock transaction can end up being reorganized in the next block rather than just being confirmed as-is. Because of this, your UI should communicate to users if the outputs of a transaction changed, or if the transaction's associated block changed. This is the same outcome as if a 1-block fork occurred. - -### Stacks.js libraries - -Stacks.js provides the [AnchorMode][] argument on transaction objects so that your application can set the microblocks preference for transactions. - -### API - -:::danger API support for microblocks is a work-in-progress. Review the [API documentation][microblocks_api] carefully to ensure that you are up-to-date on the latest implementation details for microblocks. ::: - -The Stacks Blockchain API exposes microblocks through several endpoints. Please review the [Stacks Blockchain API guide][] for more details. - -## Best practices - -Working with microblocks is a design decision that you must make for your own application. When working with microblocks, the following best practices are recommended. - -### Handling nonce - -Nonce handling with microblocks is challenging because the next account nonce must take into account any nonce values included in microblocks, which may not yet be included in an anchor block. The Stacks Blockchain API [provides an endpoint][] to retrieve the next nonce for a given principal. - -### Application design - -The state of microblock transactions should be carefully communicated to users. No transaction is final until it's included in an anchor block, and your application design should reflect this. - -The following guidelines are provided as an initial set of best practices for UI design when incorporating microblocks into your application. - -#### Explorers - -Display pending state, but warn that a transaction is still pending. Indicate visually that displayed balances depend on pending state. - -#### Wallets - -Display pending state, but warn that a transaction is still pending. Indicate visually that displayed balances depend on pending state. - -#### Exchanges - -Continue to count confirmations, microblocks should be considered pending. - -#### Applications - -Microblock communication is highly app-dependent. For some applications, displaying a pending or 0-confirmation transaction as confirmed may be fine. For example, storing data on the chain, or querying the BNS contract. For other applications, such as the transfer of real value, waiting for 3-confirmations would be prudent before displaying the state as confirmed. - -[AnchorMode]: https://stacks.js.org/enums/transactions.AnchorMode.html -[Stacks Blockchain API guide]: https://docs.hiro.so/get-started/stacks-blockchain-api#microblocks-support -[provides an endpoint]: https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling -[microblocks_api]: https://docs.hiro.so/api#tag/Microblocks diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/mining.md b/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/mining.md deleted file mode 100644 index fa1f56ed3f..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/mining.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Mining -description: A guide to mining on Stacks 2.0 -sidebar_position: 4 ---- - -## Introduction - -This guide highlights some technical details related to mining on the Stacks 2.0 network. - -For steps on how to setup your own miner please refer to [miner on tesnet](nodes-and-miners/miner-testnet.md) and [miner on mainnet](nodes-and-miners/miner-testnet.md). - -## Mining frequency - -A new Stacks block may be mined once per Bitcoin block. To be considered for mining a block, a miner must have a block commit included in a Bitcoin block. If a miner wishes to update their commitment after submission, they may use Bitcoin Replace-By-Fee. - -## Coinbase rewards - -Miners receive coinbase rewards for blocks they win. - -The reward amounts are: - -- 1000 STX per block are released in the first 4 years of mining -- 500 STX per block are released during the following 4 years -- 250 STX per block are released during the following 4 years -- 125 STX per block are released from then on indefinitely. - -These "halvings" are synchronized with Bitcoin halvings. - -![coinbase rewards](/img/pages/coinbase-rewards.png) - -## Transaction fees - -Miners receive Stacks fees for transactions mined in any block they produce. - -For transactions mined in microblocks, the miner that produces the microblock receives 40% of the fees, while the miner that confirms the microblock receives 60% of the fees. - -## Reward maturity - -Block rewards and transaction fees take 100 blocks on the Bitcoin blockchain to mature. After successfully mining a block your rewards appear in your Stacks account after ~24 hours. - -## Mining with proof-of-transfer - -Miners commit Bitcoin to **two** addresses in every leader block commit. The amount committed to each address must be the same. The addresses are chosen from the current reward set of stacking participants. Addresses are chosen using a verifiable-random-function, and determining the correct two addresses for a given block requires monitoring the Stacks chain. - -![mining with pox](/img/pages/mining-with-pox.png) - -## 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, 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. - -While there is no minimum BTC commitment enforced by the protocol, in practice, there's a floor constrained by [dust](https://unchained-capital.com/blog/dust-thermodynamics/)": basically, if the fees for a transaction exceed the value of the spent output, it's considered dust. How dust is [calculated](https://github.com/bitcoin/bitcoin/blob/master/src/policy/policy.cpp#L14) depends on a number of factors, we've found 5,500 satoshis to be good lower bound per [output](https://learnmeabitcoin.com/technical/output). Bitcoin transactions from Stacks miners contain two outputs (for Proof-of-Transfer), so a commitment of at least 11,000 satoshis / block is recommended. - -To calculate the amount of BTC to send miners should: - -- Guess the price BTC/STX for the next day (100 blocks later) -- Guess the total amount of BTCs committed by all miners - -## Microblocks - -The Stacks blockchain produces blocks at the same rate as the Bitcoin blockchain. In order to provide lower latency transactions, miners can opt to enable microblocks. Microblocks allow the current block leader to stream transactions and include their state transitions in the current epoch. - -If a block leader opts to produce microblocks, the next leader builds the chain tip off the last microblock that the current leader produces. - -The block streaming model is described in [SIP-001][]. - -[SIP-001]: https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md#operation-as-a-leader diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/network.md b/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/network.md deleted file mode 100644 index 2aa8fd4b0e..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/network.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -title: Network -description: Guide to the Stacks 2.0 network -sidebar_position: 7 ---- - -## Tokens - -Stacks (STX) tokens are the native tokens on the Stacks 2.0 blockchain. The smallest fraction is one micro-STX. 1,000,000 micro-STX make one Stacks (STX). - -STX amounts should be stored as integers (8 bytes long), and represent the amount of micro-STX. For display purposes, micro-STX are divided by 1,000,000 (decimal precision of 6). - -## 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 in bytes. The fee rate is a market determined variable. For the [testnet](testnet), it is set to 1 micro-STX. - -Fee estimates can obtained through the [`GET /v2/fees/transfer`](https://docs.hiro.so/api#operation/get_fee_transfer) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/fees/transfer' -``` - -The API will respond with the fee rate (as integer): - -```json -1 -``` - -[The Stacks Transactions JS library](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) supports fee estimation for: - -- token transfers (`estimateTransfer`) -- contract deploys (`estimateContractDeploy`) -- non read-only contract calls (`estimateContractFunctionCall`) - -:::tip For an implementation using a different language than JavaScript, please review [this reference implementation](https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/src/builders.ts#L97). ::: - -## Nonces - -Every account carries a [nonce property](https://en.wikipedia.org/wiki/Cryptographic_nonce) that indicates the number of transactions processed for the given account. Nonces are one-time codes, starting at `0` for new accounts, and incremented by 1 on every transaction. - -Nonces are added to all transactions and help identify them in order to ensure transactions are processed in order and to avoid duplicated processing. - -:::tip -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 is constructed, the most recent nonce of the account needs to fetched and set. - -:::tip The API provides an endpoint to [simplify nonce handling](https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling). ::: - -## Confirmations - -The Stacks 2.0 network is anchored onto the bitcoin network. This allows transactions on Stacks to inherit the same finality and security of the Bitcoin blockchain. - -The time to mine a block, to confirm transactions, will eventually match the expected "block time" of the bitcoin network: 10 minutes. - -:::tip Transactions can also be mined in [microblocks](microblocks), reducing the latency significantly. ::: - -The block time is hardcoded and will change throughout the implementation phases of the [testnet](testnet). The current block time can be obtained through the [`GET /extended/v1/info/network_block_times`](https://docs.hiro.so/api#operation/get_network_block_times) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/info/network_block_times' -``` - -The API will respond with the block time (in seconds): - -```js -{ - "testnet": { - "target_block_time": 120 - }, - "mainnet": { - "target_block_time": 600 - } -} -``` - -## Read-only function calls - -Smart contracts can expose public function calls. For functions that make state modifications to the blockchain, transactions need to be generated and broadcasted. - -However, for read-only function calls, transactions are **not** required. Instead, these calls can be done using the [Stacks Blockchain API](https://docs.hiro.so/get-started/stacks-blockchain-api). - -:::tip -Read-only function calls do not require transaction fees -::: - -A read-only contract call can be done using the [`POST /v2/contracts/call-read///`](https://docs.hiro.so/api#operation/call_read_only_function) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl --location --request POST 'https://stacks-node-api.testnet.stacks.co/v2/contracts/call-read///' \ ---header 'Content-Type: application/json' \ ---data-raw '{ - "sender": ".", - "arguments": [, ...] -}' -}' -}' -}' -``` - -Sample response for a successful call: - -```js -{ - "okay": true, - "result": "" -} -``` - -:::tip To set the function call arguments and read the result, [Clarity values](../write-smart-contracts/values) need to be serialized into a hexadecimal string. The [Stacks Transactions JS](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library supports these operations ::: - -## Querying - -Stacks 2.0 network details can be queried using the [Stacks Blockchain API](https://docs.hiro.so/get-started/stacks-blockchain-api). - -### Health check - -The [status checker](https://stacks-status.com/) is a service that provides a user interface to quickly review the health of the Stacks 2.0 blockchain. - -### Network info - -The network information can be obtained using the [`GET /v2/info`](https://docs.hiro.so/api#operation/get_core_api_info) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/info' -``` - -Sample response: - -```js -{ - "peer_version": 385875968, - "burn_consensus": "826401d65cf3671210a3fb135d827d549c0b4d37", - "burn_block_height": 1972, - "stable_burn_consensus": "e27ea23f199076bc41a729d76a813e125b725f64", - "stable_burn_block_height": 1971, - "server_version": "blockstack-core 0.0.1 => 23.0.0.0 (master:bdd042242+, release build, linux [x86_64]", - "network_id": 2147483648, - "parent_network_id": 3669344250, - "stacks_tip_height": 933, - "stacks_tip": "1f601823fbcc5b6b2215b2ff59d2818fba61ee4a3cea426d8bc3dbb268005d8f", - "stacks_tip_burn_block": "54c56a9685545c45accf42b5dcb2787c97eda8185a1c794daf9b5a59d4807abc", - "unanchored_tip": "71948ee211dac3b241eb65d881637f649d0d49ac08ee4a41c29217d3026d7aae", - "exit_at_block_height": 28160 -} -``` diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md b/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md deleted file mode 100644 index c933f7af68..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Proof of Transfer -description: Understand the proof-of-transfer consensus mechanism -sidebar_position: 3 ---- - -## Overview - -Consensus algorithms for blockchains require compute or financial resources to secure the blockchain. The general practice of decentralized consensus is to make it practically infeasible for any single malicious actor to have enough computing power or ownership stake to attack the network. - -Popular consensus mechanisms in modern blockchains include proof-of-work, in which nodes dedicate computing resources, and proof-of-stake, in which nodes dedicate financial resources to secure the network. - -Proof-of-burn is a novel consensus mechanism where miners compete by ‘burning’ (destroying) a proof-of-work cryptocurrency as a proxy for computing resources. - -Proof-of-transfer (PoX) is an extension of the proof-of-burn mechanism. 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. - -![PoX mechanism](/img/pox-mechanism.png) - -This allows network participants to secure the PoX cryptocurrency network and earn a reward in the base cryptocurrency. Thus, proof-of-transfer blockchains are anchored on their chosen proof-of-work chain. Stacks uses [Bitcoin](#why-bitcoin) as its anchor chain. - -![PoX participants](/img/pox-participants.png) - -## Why Bitcoin? - -There are a number of reasons that Stacks chose Bitcoin as the blockchain to power consensus. It's the oldest blockchain protocol, having launched in 2009, and has become a recognized asset outside of the cryptocurrency community. BTC has held the highest market capitalization of any cryptocurrency for the past decade. - -Bitcoin champions simplicity and stability, and has stood the test of time. Influencing or attacking the network is infeasible or impractical for any potential hackers. It's one of the only cryptocurrencies to capture public attention. Bitcoin is a household name, and is recognized as an asset by governments, large corporations, and legacy banking institutions. Lastly, Bitcoin is largely considered a reliable store of value, and provides extensive infrastructure to support the proof-of-transfer consensus mechanism. - -SIP-001 provides a full [list of reasons why Bitcoin was chosen to secure Stacks](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md). - -![btc-stacks](/img/pox-why-bitcoin.png) - -## Blocks and microblocks - -The Stacks blockchain allows for increased transaction throughput using a mechanism called microblocks. Bitcoin and Stacks progress in lockstep, and their blocks are confirmed simultaneously. On Stacks, this is referred to as an ‘anchor block’. An entire block of Stacks transactions corresponds to a single Bitcoin transaction. This significantly improves cost/byte ratio for processing Stacks transactions. Because of simultaneous block production, Bitcoin acts as a rate-limiter for creating Stacks blocks, thereby preventing denial-of-service attacks on its peer network. - -However, in between Stacks anchor blocks settling on the Bitcoin blockchain, there are also a varying number of microblocks that allow rapid settlement of Stacks transactions with a high degree of confidence. This allows Stacks transaction throughput to scale independently of Bitcoin, while still periodically establishing finality with the Bitcoin chain. The Stacks blockchain adopts a block streaming model whereby each leader can adaptively select and package transactions into their block as they arrive in the mempool. Therefore when an anchor block is confirmed, all of the transactions in the parent microblock stream are packaged and processed. This is an unprecedented method for achieving scalability without creating a totally separate protocol from Bitcoin. - -![stx-microblock](/img/stx-microblocks.png) - -## Unlocking Bitcoin capital - -Stacks also unlocks the hundreds of billions in capital in Bitcoin, and gives Bitcoiners new opportunities to use and earn BTC. Stacks is a accompaniment to the Bitcoin ecosystem, and the two networks working in tandem enables totally novel ways of using BTC. The Stacks ecosystem makes interactive cryptocurrency applications available to Bitcoin holders. Additionally, By stacking STX tokens and participating in the PoX consensus mechanism, users have the opportunity to earn BTC while securing the Stacks chain. - -![Unlocking Bitcoin](/img/pox-unlocking-btc.png) - -## Clarity and the Bitcoin state - -Clarity smart contracts also have unique visibility into the state of the Bitcoin blockchain. This means that contract logic in a Clarity file has the ability to trigger when specific Bitcoin transactions are confirmed. Clarity smart contracts have a built in Simple Payment Verification (SPV) proofs for Bitcoin that make interacting with Bitcoin’s state much simpler for developers. Additionally, Clarity contracts can fork with the original Bitcoin chain. Therefore, in an edge case where Bitcoin forks, developers wouldn’t have to worry about adjusting the deployment of their smart contracts. - -## See also - -- [Read the full PoX whitepaper](https://community.stacks.org/pox) -- [Watch Executive Chair of Hiro Muneeb Ali and Evangelist Joe Bender give an overview of Stack's breakthrough PoX mining mechanism](https://www.youtube.com/watch?v=NY_eUrIcWOY) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md b/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md deleted file mode 100644 index 5f3863e8dd..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: Stacking -description: Introduction to the reward mechanism of Proof-of-Transfer -sidebar_position: 9 ---- - -## Introduction - -Stacking rewards Stacks (STX) token holders with bitcoin for providing a valuable service to the network by locking up their tokens for a certain time. - -![](/img/stacking.png) - -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. - -:::info The Stacking consensus algorithm is implemented as a smart contract, using [Clarity](../write-smart-contracts/). [Read more about the contract](../noteworthy-contracts/stacking-contract). ::: - -## Stacking flow - -The Stacking mechanism can be presented as a flow of actions: - -![Stacking flow](/img/stacking-illustration.png) - -1. Make API calls to get details about the upcoming reward cycle -2. For a specific Stacks account, confirm eligibility -3. Confirm the BTC reward address and the lockup duration -4. The transaction is broadcasted and the STX tokens are locked. This needs to happen before the prepare phase of the next reward cycle, the last 100 Bitcoin blocks of the ongoing reward phase -5. The Stacking mechanism executes reward cycles and sends out rewards to the set BTC reward address -6. During the lockup period, details about unlocking timing, rewards and more can be obtained -7. Once the lockup period is passed, the tokens are released and accessible again -8. Display reward history, including details like earnings for previous reward cycles - -:::info Keep in mind that the target duration for a reward cycles is ~2 weeks. This duration is based on the target block time of the network (10 minutes) and can be higher at times due to [confirmation time variances](https://www.blockchain.com/charts/median-confirmation-time) of the bitcoin network. ::: - -## Stacking delegation flow - -The Stacking flow is different for delegation use cases: - -![Delegated tacking flow](/img/stacking-delegation-illustration.png) - -- Before Stacking can be initiated for a token holder, the delegator needs to be granted permission to Stack on behalf of the account owner. The permission is restricted to the maximum amount the delegator is allowed to Stack. The maximum amount is not limited by the available funds and can be set much higher. An account can only be associated with one single delegator -- The account has to define the delegation relationship. They can optionally restrict the Bitcoin reward address that must be used for payouts, and the expiration burn block height for the permission, thus limiting the time a delegator has permission to Stack -- Delegators have to lock Stacks from different accounts ("pooling phase") until they reach the minimum amount of Stacks required to participate in Stacking -- Once a delegator locks enough STX tokens, they can finalize and commit their participation in the next reward cycle -- Certain delegation relationships may allow the STX holder to receive the payout directly from the miner (step 5/6) -- The termination of the delegation relationship can either happen automatically based on set expiration rules or by actively revoking delegation rights - -## PoX mining - -PoX mining is a modification of Proof-of-Burn (PoB) mining, where instead of sending the committed Bitcoin to a burn address, it's transferred to eligible STX holders that participate in the stacking protocol. - -:::note -A PoX miner can only receive newly minted STX tokens when they transfer Bitcoin to eligible owners of STX tokens -::: - -![Mining flow](/img/pox-mining-flow.png) - -Miners run Stacks nodes with mining enabled to participate in the PoX mechanism. The node implements the PoX mechanism, which ensures proper handling and incentives through four key phases: - -- Registration: miners register for a future election by sending consensus data to the network -- Commitment: registered miners transfer Bitcoin to participate in the election. Committed BTC are sent to a set participating STX token holders -- Election: a verifiable random function chooses one miner to write a new block on the Stacks blockchain -- Assembly: the elected miner writes the new block and collects rewards in form of new STX tokens - -## Token holder eligibility - -Stacks (STX) token holders don't automatically receive stacking rewards. Instead, they must: - -- Commit to participation before a reward cycle begins -- Commit the minimum amount of STX tokens to secure a reward slot, or pool with others to reach the minimum -- Lock up STX tokens for a specified period -- Provide a supported Bitcoin address to receive rewards (native segwit is not supported) - -The following diagram describes how the minimum STX tokens per slot is determined. More information on [dynamic minimums for stacking](https://stacking.club) is available at stacking.club. - -![Dynamic minimum for individual eligibility](/img/stacking-dynamic-minimum.png) - -Token holders have a variety of providers and tools to support their participation in Stacking. The Stacks website contains a [list of stacking providers and pools](https://stacks.org/stacking#earn). - -## Stacking in the PoX consensus algorithm - -Stacking is a built-in capability of PoX and occurs through a set of actions on the Stacks blockchain. The [full proof-of-transfer implementation details](https://github.com/stacks-network/stacks-blockchain/blob/develop/sip/sip-007-stacking-consensus.md) are in SIP-007. Below is a summary of the most relevant actions of the algorithm. - -![PoX cycles](/img/pox-cycles.png) - -- Stacking happens over reward cycles with a fixed length. In each reward cycle, a set of Bitcoin addresses associated with stacking participants receive BTC rewards -- A reward cycle consists of two phases: prepare and reward -- During the prepare phase, miners decide on an anchor block and a reward set. Mining any descendant forks of the anchor block requires transferring mining funds to the appropriate reward addresses. The reward set is the set of Bitcoin addresses which are eligible to receive funds in the reward cycle -- Miners register as leader candidates for a future election by sending a key transaction that burns cryptocurrency. The transaction also registers the leader's preferred chain tip (must be a descendant of the anchor block) and commitment of funds to 2 addresses from the reward set -- Token holders register for the next rewards cycle by broadcasting a signed message that locks up associated STX tokens for a protocol-specified lockup period, specifies a Bitcoin address to receive the funds, and votes on a Stacks chain tip -- Multiple leaders can commit to the same chain tip. The leader that wins the election and the peers who also burn for that leader collectively share the reward, proportional to how much each one burned -- Token holders' locked up tokens automatically unlock as soon as the lockup period finishes - -## Bitcoin address - -:::danger You must provide a BTC address in one of two formats: - -* [Legacy (P2PKH)](https://en.bitcoin.it/wiki/Transaction#Pay-to-PubkeyHash), which starts with `1`. - -* [Segregated Witness / Segwit (P2SH)](https://en.bitcoin.it/wiki/Pay_to_script_hash), which starts with `3`. The "Native Segwit" format (which starts with `bc1`), for example, is not supported. ::: - -The Stacking contract needs a special format for the Bitcoin address (the reward address). This is required to ensure that miners are able to correctly construct the Bitcoin transaction containing the reward address. - -The address must be specified in the following format using the Clarity language: - -```clar -;; a tuple of a version and hashbytes buffer -(pox-addr (tuple (version (buff 1)) (hashbytes (buff 20)))) -``` - -The `version` buffer must represent what kind of bitcoin address is being submitted. It can be one of the following: - -```js -SerializeP2PKH = 0x00, // hash160(public-key), same as bitcoin's p2pkh -SerializeP2SH = 0x01, // hash160(multisig-redeem-script), same as bitcoin's multisig p2sh -SerializeP2WPKH = 0x02, // hash160(segwit-program-00(p2pkh)), same as bitcoin's p2sh-p2wpkh -SerializeP2WSH = 0x03, // hash160(segwit-program-00(public-keys)), same as bitcoin's p2sh-p2wsh -``` - -The `hashbytes` are the 20 hash bytes of the bitcoin address. You can obtain that from a bitcoin library, for instance using [`bitcoinjs-lib`](https://github.com/bitcoinjs/bitcoinjs-lib): - -```js -const btc = require('bitcoinjs-lib'); -console.log( - '0x' + btc.address.fromBase58Check('1C56LYirKa3PFXFsvhSESgDy2acEHVAEt6').hash.toString('hex') -); -``` - -## Choosing the right Stacking strategy - -[Here](https://blog.stacks.co/stacking-strategy) is an interesting article that may help you choose the right Stacking stategy. - - -## Where to Stacks? - -You can Stack on your own, on a pool or on an exchange: -### Stacking on your own - -Stacking on your own is non-custodial. - -Stacking on your own requires a protocol minimum (amount changes but about 100,000 STX). - -[Hiro Wallet](https://www.hiro.so/wallet) allows stacking on your own. - -### Stacking on a pool - -Stacking on a pool allows Stacking without the requirement of the protocol minumum. - -Some available pools are: - -| Pool | Type | Pays rewards in | Fee | Minimum amount | -| --------------------------------------------------- | ------------- |:---------------:| --- |:--------------:| -| [Friedger's Pool](https://pool.friedger.de/) | Non custodial | STX or xBTC | No | 40 STX | -| [Planbetter](https://planbetter.org/) | Non custodial | BTC | 5% | 200 STX | -| [Stacked](https://staking.staked.us/stacks-staking) | Non custodial | BTC | | 100,000 STX | -| [Xverse](https://www.xverse.app/) | Non custodial | BTC | No | 100 STX | - -### Stacking on an exchange - -Stacking on an exchange is custodial, meaning you are trusting the exchange with your Stacks. - -Several exchanges allow Stacking directly on their sites. Examples are [Okcoin](https://www.okcoin.com) and [Binance](https://www.binance.com/en/staking) - -## Stacking statistics - -You can view all sorts of Stacking data and statistics on [Stacking Club](https://stacking.club) \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md b/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md deleted file mode 100644 index d942d6af8f..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Stacks Blockchain API -description: Interacting with the Stacks 2.0 Blockchain via API ---- - -## Temporal page because of a Crowdin bug \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md b/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md deleted file mode 100644 index e370129d1d..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Technical Specifications -description: Summary of technical specifications of Stacks 2.0 -sidebar_position: 10 ---- - -## Consensus - -- Proof of Transfer (PoX) as described in [SIP-007](https://github.com/stacksgov/sips/blob/main/sips/sip-007/sip-007-stacking-consensus.md) -- Network will transition to Proof of Burn (PoB) as described in [SIP-001](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md) after 10 years. [Learn more about Proof-of-Burn in SIP-001](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md). -- Threat model - - 51% of malicious Stacks mining power can perform a double-spend attack - - 51% of malicious Bitcoin mining power can reorg the Stacks chain -- Different actors and their roles - - Stacks Miners package transactions into blocks, mine them through a Bitcoin transaction, propagate them, and if they win the block race, append microblocks to their winning block until the next block is mined. The next block confirms the microblock stream. - - Stacks Holders may alter the calculation of block limits (subject to a miner veto) and may vote to disable Proof-of-Transfer rewards for a reward cycle. -- Transactions are considered final when the corresponding "block commit" transaction on Bitcoin is finalized. Typically this can by 3-6 confirmations. -- For more details, see [Proof of Transfer](proof-of-transfer). - -## Proof of Transfer Mining - -- Coinbase reward schedule: - - 1000 STX/block for first 4 years - - 500 STX/block for following 4 years - - 250 STX/block for subsequent 4 years - - 125 STX/block in perpetuity after that -- Coinbase rewards accumulate for "missed sortitions": If a Bitcoin block has no sortition (at height N), then any Stacks block mined in a subsequent sortition that builds off of any Stacks chain tip that existed at the penultimate sortition (at height N-1) may claim its coinbase. This encourages miners to keep mining even if Bitcoin fees are high. -- Initial mining bonus: This is a special case of the above to incentivize early miners. Coinbase for all burnchain blocks between the first burn block height (to be chosen by independent miners as part of the Stacks 2.0 launch) and the first sortition winner accumulate and are distributed to miners over a fixed window (to be determined). For instance, say burn block height is 10,000 and first sortition is at block 10500 and distribution window is 100 blocks, then coinbase for the first 500 blocks (10,500 - 10,000) will be distributed evenly to miners who win sortition over the subsequent 100 blocks. -- 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 at least 11,000 satoshis (5,500 sats / [UTXO output](https://learnmeabitcoin.com/technical/utxo)); 2 outputs / block) to avoid "dust." -- For more details, see [Mining](mining). - -## Stacking - -- Stacking works in 2 phases - 1. Prepare phase: In this phase an "anchor block" is chosen. The qualifying set of addresses ("reward set") is determined based on the snapshot of the chain at the anchor block. Length of prepare phase is 100 blocks. Stacking commitments need to be confirmed before this phase starts - 2. Reward phase: In this phase miner BTC commitments are distributed amongst the reward set. Reward cycle length is 2000 BTC blocks (~2 weeks). -- 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/stacksgov/sips/blob/main/sips/sip-007/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.stacks.co/references/stacking-contract#delegate-stx). -- Only two types of BTC reward addresses are supported: [Legacy (P2PKH)](https://en.bitcoin.it/wiki/Transaction#Pay-to-PubkeyHash) or [Segregated Witness / Segwit (P2SH)](https://en.bitcoin.it/wiki/Pay_to_script_hash). Native Segwit is not supported. -- Further reading: [Stacking](stacking) - -## Accounts and Addresses - -- Transactions in the Stacks blockchain originate from, are paid for by, and execute under the authority of accounts -- An account is fully specified by its address + nonce + assets -- 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 (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](accounts) - -## Transactions - -- Transaction 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 - 2. _paying account_ is the account that is billed by the leader for the cost of validating and executing the transaction - 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 -- Transactions can be batched or streamed into blocks. The behavior can be controlled by the anchor mode of a transaction. With streaming ([microblocks](microblocks)), a faster confirmation time is possible. -- 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. -- Mempool limit for concurrent pending transactions is 25 per account -- Pending mempool transactions will be garbage-collected [256 blocks after receipt](https://github.com/stacks-network/stacks-blockchain/blob/master/src/core/mempool.rs#L62). With 10 minutes target block time, this would equal ~42 hours -- [Learn more about transaction encoding in SIP-005](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md#transaction-encoding) -- [Transaction signing and verification are described in SIP-005](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md#transaction-signing-and-verifying) -- All transactions impacting account balance are atomic, a transfer operation can not increment one account’s balance without decrementing another’s. However, transactions that perform multiple account actions (for example, transferring from multiple accounts) may partially complete. -- Transactions can include a memo string (max 34 bytes) - -## See also - -- [Read the full Stacks 2.0: Apps and Smart Contracts for Bitcoin whitepaper](https://cloudflare-ipfs.com/ipfs/QmaGgiVHymeDjAc3aF1AwyhiFFwN97pme5m536cHT4FsAW). - -- [Watch Aaron Blankstein video on Stacks whitepater v2](https://www.youtube.com/watch?v=Wd-Bfe8Sn-Y). \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md b/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md deleted file mode 100644 index 59934a5bde..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Testnet -description: Test your smart contracts and apps -sidebar_position: 2 ---- - -## About testnet - -The testnet is a separate blockchain from the Stacks mainnet analogous to a staging environment. It's a network used by developers to test their apps, smart contracts, or changes to the protocol in a production-like environment. It produces blocks at roughly the same rate as mainnet; about 1 block every 10 minutes on average. The Stacks testnet is rarely reset. - -### Faucet - -The testnet faucet provides you with free Stacks Token (STX) to test with. These are not the same as STX on mainnet and have no value. You can get STX from the faucet on the [Stacks Explorer Sandbox](https://explorer.stacks.co/sandbox/faucet?chain=testnet), or using the [API](https://docs.hiro.so/api#tag/Faucets). - -To get STX tokens from within the Explorer Sandbox, navigate to the "Faucet" tab on the left and click "Request STX" button. - -![](/img/stx_faucet.png) - -You can also try out [Stacking](stacking) by clicking on `I want to stack`. - -:::note -The Explorer Sandbox requires you to login with a Stacks wallet -::: - -### Testnet API - -The hosted Stacks Blockchain API for the testnet is available at this base URL: - -```shell -https://stacks-node-api.testnet.stacks.co/ -``` - -![](/img/api_testnet_status.png) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md b/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md deleted file mode 100644 index 2ff6072384..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Transactions -description: Guide to Stacks 2.0 transactions -sidebar_position: 6 ---- - -## Introduction - -Transactions are the fundamental unit of execution in the Stacks blockchain. Each transaction is originated from a [Stacks 2.0 account](accounts), and is retained in the Stacks blockchain history for eternity. This guide helps you understand Stacks 2.0 transactions. - -## Lifecycle - -Transactions go through phases before being finally confirmed, and available for all, on the Stacks 2.0 network. - -![Transaction lifecycle](/img/tx-lifecycle.png) - -- **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/en/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. - -:::note A transaction can have one of three states once it is registered: `pending`, `success`, or `failed`. ::: - -## Types - -The Stacks 2.0 supports a set of different transaction types: - -| **Type** | **Value** | **Description** | -| ----------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Coinbase | `coinbase` | The first transaction in a new block (an entity holding several transactions). Used to register for block rewards. These are not manually generated and broadcasted like other types of transactions. | -| Token transfer | `token_transfer` | Asset transfer from a sender to a recipient | -| Contract deploy | `smart_contract` | Contract instantiation | -| Contract call | `contract_call` | Contract call for a public, non read-only function | -| Poison Microblock | `poison_microblock` | Punish leaders who intentionally equivocate about the microblocks they package | - -A sample of each transaction type can be found in the [Stacks Blockchain API response definition for transactions](https://docs.hiro.so/api#operation/get_transaction_by_id). - -:::caution Read-only contract call calls do **not** require transactions. Read more about it in the [network guide](network#read-only-function-calls). ::: diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md b/i18n/ru/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md deleted file mode 100644 index fd45c80583..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Clarity Language -description: Overview of the Clarity language constructs -sidebar_label: Clarity Language -tags: - - clarity ---- - -## Clarity Type System - -The Clarity language uses a strong static type system. Function arguments and database schemas require specified types, and use of types is checked during contract launch. The type system does _not_ have a universal super type. - -## Public Functions - -Functions specified via `define-public` statements are _public_ functions and these are the only types of functions which may be called directly through signed blockchain transactions. In addition to being callable directly from a transaction (see the Stacks wire formats for more details on Stacks transactions), public functions may be called by other smart contracts. - -Public functions _must_ return a `(response ...)` type. This is used by Clarity to determine whether or not to materialize any changes from the execution of the function. If a function returns an `(err ...)` type, any mutations on the blockchain state from executing the function (and any function that it called during execution) will be aborted. - -In addition to functions defined via `define-public`, contracts may expose read-only functions. These functions, defined via `define-read-only`, are callable by other smart contracts, and may be queryable via public blockchain explorers. These functions _may not_ mutate any blockchain state. Unlike normal public functions, read-only functions may return any type. - -## Contract Calls - -A smart contract may call functions from other smart contracts using a `(contract-call?)` function. - -This function returns a response type result -- the return value of the called smart contract function. - -We distinguish 2 different types of `contract-call?`: - -### Static dispatch - -The callee is a known, invariant contract available on-chain when the caller contract is deployed. In this case, the callee's principal is provided as the first argument, followed by the name of the method and its arguments: - -```clarity -(contract-call? - .registrar - register-name - name-to-register) -``` - -### Dynamic dispatch - -The callee is passed as an argument, and typed as a trait reference (``). - -```clarity -(define-public (swap (token-a ) - (amount-a uint) - (owner-a principal) - (token-b ) - (amount-b uint) - (owner-b principal))) - (begin - (unwrap! (contract-call? token-a transfer-from? owner-a owner-b amount-a)) - (unwrap! (contract-call? token-b transfer-from? owner-b owner-a amount-b)))) -``` - -Traits can either be locally defined: - -```clarity -(define-trait can-transfer-tokens ( - (transfer-from? (principal principal uint) (response uint))) -``` - -Or imported from an existing contract: - -```clarity -(use-trait can-transfer-tokens - .contract-defining-trait.can-transfer-tokens) -``` - -Looking at trait conformance, callee contracts have two different paths. They can either be "compatible" with a trait by defining methods matching some of the methods defined in a trait, or explicitly declare conformance using the `impl-trait` statement: - -```clarity -(impl-trait .contract-defining-trait.can-transfer-tokens) -``` - -Explicit conformance should be prefered when adequate. It acts as a safeguard by helping the static analysis system to detect deviations in method signatures before contract deployment. - -The following limitations are imposed on contract calls: - -1. On static dispatches, callee smart contracts _must_ exist at the time of creation. -2. No cycles may exist in the call graph of a smart contract. This prevents recursion (and re-entrancy bugs). Such structures can be detected with static analysis of the call graph, and will be rejected by the network. -3. `contract-call?` are for inter-contract calls only. Attempts to execute when the caller is also the callee will abort the transaction. diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md b/i18n/ru/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md deleted file mode 100644 index a6011cca8b..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md +++ /dev/null @@ -1,1388 +0,0 @@ ---- -title: Functions -description: See a detailed list of all functions for the Clarity language. -tags: - - clarity ---- - -## Functions - -Detailed list of all functions for the Clarity language. - -### + (add) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(+ i1 i2...)` -#### description: -Adds a variable number of integer inputs and returns the result. In the event of an _overflow_, throws a runtime error. -#### example: -```clarity -(+ 1 2 3) ;; Returns 6 -(+ 2 3) ;; Returns 5 -(+ 1 2 3 4) ;; Returns 10 -(+ 9 -3) ;; Returns 6 -(+ -3 -2) ;; Returns -5 -``` - -### - (subtract) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(- i1 i2...)` -#### description: -Subtracts a variable number of integer inputs and returns the result. In the event of an _underflow_, throws a runtime error. -#### example: -```clarity -(- 2 1 1) ;; Returns 0 -(- 0 3) ;; Returns -3 -(- 5 -3) ;; Returns 8 -(- -4 -5) ;; Returns 1 -``` - -### * (multiply) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(* i1 i2...)` -#### description: -Multiplies a variable number of integer inputs and returns the result. In the event of an _overflow_, throws a runtime error. -#### example: -```clarity -(* 2 3) ;; Returns 6 -(* 5 2) ;; Returns 10 -(* 2 2 2) ;; Returns 8 -(* 3 -2) ;; Returns -6 -(* -1 -2) ;; Returns 2 -``` - -### / (divide) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(/ i1 i2...)` -#### description: -Divides a variable number of integer inputs and returns the _integer part_ of the result. In the event of _division by zero_, throws a runtime error. - -#### example: -```clarity -(/ 2 3) ;; Returns 0 -(/ 5 2) ;; Returns 2 -(/ 4 2 2) ;; Returns 1 -(/ -10 2) ;; Returns -5 -(/ -8 -2) ;; Returns 4 -(/ -9 4) ;; Returns -2 -``` - -### >= (greater than or equal) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(>= i1 i2)` -#### description: -Compares two integers, returning `true` if `i1` is greater than or equal to `i2` and `false` otherwise. -#### example: -```clarity -(>= 1 1) ;; Returns true -(>= 5 2) ;; Returns true -``` - -### <= (less than or equal) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(<= i1 i2)` -#### description: -Compares two integers, returning true if `i1` is less than or equal to `i2` and `false` otherwise. -#### example: -```clarity -(<= 1 1) ;; Returns true -(<= 5 2) ;; Returns false -``` - -### < (less than) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(< i1 i2)` -#### description: -Compares two integers, returning `true` if `i1` is less than `i2` and `false` otherwise. -#### example: -```clarity -(< 1 2) ;; Returns true -(< 5 2) ;; Returns false -``` - -### > (greater than) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(> i1 i2)` -#### description: -Compares two integers, returning `true` if `i1` is greater than `i2` and false otherwise. -#### example: -```clarity -(> 1 2) ;; Returns false -(> 5 2) ;; Returns true -``` - -### to-int -#### input: `uint` -#### output: `int` -#### signature: `(to-int u)` -#### description: -Tries to convert the `uint` argument to an `int`. Will cause a runtime error and abort if the supplied argument is >= `pow(2, 127)`` -#### example: -```clarity -(to-int u238) ;; Returns 238 -``` - -### to-uint -#### input: `int` -#### output: `uint` -#### signature: `(to-uint i)` -#### description: -Tries to convert the `int` argument to a `uint`. Will cause a runtime error and abort if the supplied argument is negative. -#### example: -```clarity -(to-uint 238) ;; Returns u238 -``` - -### mod -#### input: `int, int | uint, uint` -#### output: `int | uint` -#### signature: `(mod i1 i2)` -#### description: -Returns the integer remainder from integer dividing `i1` by `i2`. In the event of a division by zero, throws a runtime error. -#### example: -```clarity -(mod 2 3) ;; Returns 2 -(mod 5 2) ;; Returns 1 -(mod 7 1) ;; Returns 0 -``` - -### pow -#### input: `int, int | uint, uint` -#### output: `int | uint` -#### signature: `(pow i1 i2)` -#### description: -Returns the result of raising `i1` to the power of `i2`. In the event of an _overflow_, throws a runtime error. -#### example: -```clarity -(pow 2 3) ;; Returns 8 -(pow 2 2) ;; Returns 4 -(pow 7 1) ;; Returns 7 -``` - -### sqrti -#### input: `int | uint` -#### output: `int | uint` -#### signature: `(sqrti n)` -#### description: -Returns the largest integer that is less than or equal to the square root of `n`. Fails on a negative numbers. -#### example: -```clarity -(sqrti u11) ;; Returns u3 -(sqrti 1000000) ;; Returns 1000 -(sqrti u1) ;; Returns u1 -(sqrti 0) ;; Returns 0 -``` - -### log2 -#### input: `int | uint` -#### output: `int | uint` -#### signature: `(log2 n)` -#### description: -Returns the _integer part_ of the power to which the number 2 must be raised to obtain the value `n`. Fails on zero or a negative number. -#### example: -```clarity -(log2 u8) ;; Returns u3 -(log2 8) ;; Returns 3 -(log2 u1) ;; Returns u0 -(log2 1000) ;; Returns 9 -``` - -### xor -#### input: `int, int | uint, uint` -#### output: `int | uint` -#### signature: `(xor i1 i2)` -#### description: -Returns the result of bitwise exclusive or'ing `i1` with `i2`. -#### example: -```clarity -(xor 1 2) ;; Returns 3 -(xor 120 280) ;; Returns 352 -``` - -### and -#### input: `bool, ...` -#### output: `bool` -#### signature: `(and b1 b2 ...)` -#### description: -Returns `true` if all boolean inputs are `true`. Importantly, the supplied arguments are evaluated in-order and lazily. Lazy evaluation means that if one of the arguments returns `false`, the function short-circuits, and no subsequent arguments are evaluated. -#### example: -```clarity -(and true false) ;; Returns false -(and (is-eq (+ 1 2) 1) (is-eq 4 4)) ;; Returns false -(and (is-eq (+ 1 2) 3) (is-eq 4 4)) ;; Returns true -``` - -### or -#### input: `bool, ...` -#### output: `bool` -#### signature: `(or b1 b2 ...)` -#### description: -Returns `true` if any boolean inputs are `true`. Importantly, the supplied arguments are evaluated in-order and lazily. Importantly, the supplied arguments are evaluated in-order and lazily. -#### example: -```clarity -(or true false) ;; Returns true -(or (is-eq (+ 1 2) 1) (is-eq 4 4)) ;; Returns true -(or (is-eq (+ 1 2) 1) (is-eq 3 4)) ;; Returns false -(or (is-eq (+ 1 2) 3) (is-eq 4 4)) ;; Returns true -``` - -### not -#### input: `bool` -#### output: `bool` -#### signature: `(not b1)` -#### description: -Returns the inverse of the boolean input. -#### example: -```clarity -(not true) ;; Returns false -(not (is-eq 1 2)) ;; Returns true -``` - -### is-eq -#### input: `A, A, ...` -#### output: `bool` -#### signature: `(is-eq v1 v2...)` -#### description: -Compares the inputted values, returning `true` if they are all equal. Note that _unlike_ the `(and ...)` function, `(is-eq ...)` will _not_ short-circuit. All values supplied to is-eq _must_ be the same type. -#### example: -```clarity -(is-eq 1 1) ;; Returns true -(is-eq true false) ;; Returns false -(is-eq \"abc\" 234 234) ;; Throws type error -``` - -### if -#### input: `bool, A, A` -#### output: `A` -#### signature: `(if bool1 expr1 expr2)` -#### description: -The `if` function admits a boolean argument and two expressions which must return the same type. In the case that the boolean input is `true`, the `if` function evaluates and returns `expr1`. If the boolean input is `false`, the `if` function evaluates and returns `expr2`. -#### example: -```clarity -(if true 1 2) ;; Returns 1 -(if (> 1 2) 1 2) ;; Returns 2 -``` - -### let -#### input: `((name1 AnyType) (name2 AnyType) ...), AnyType, ... A` -#### output: `A` -#### signature: `(let ((name1 expr1) (name2 expr2) ...) expr-body1 expr-body2 ... expr-body-last)` -#### description: -The `let` function accepts a list of `variable name` and `expression` pairs, evaluating each expression and _binding_ it to the corresponding variable name. `let` bindings are sequential: when a `let` binding is evaluated, it may refer to prior binding. The _context_ created by this set of bindings is used for evaluating its body expressions. The let expression returns the value of the last such body expression. Note: intermediary statements returning a response type must be checked` -#### example: -```clarity -(let ((a 2) (b (+ 5 6 7))) (print a) (print b) (+ a b)) ;; Returns 20 -(let ((a 5) (c (+ a 1)) (d (+ c 1)) (b (+ a c d))) (print a) (print b) (+ a b)) ;; Returns 23 -``` - -### map -#### input: `Function(A, B, ..., N) -> X, sequence_A, sequence_B, ..., sequence_N` -#### output: `(list X)` -#### signature: `(map func sequence_A sequence_B ... sequence_N)` -#### description: -Also, note that, no matter what kind of sequences the inputs are, the output is always a list. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. The `map` function applies the function `func` to each corresponding element of the input sequences, and outputs a _list_ of the same type containing the outputs from those function applications. -#### example: -```clarity -(map not (list true false true false)) ;; Returns (false true false true) -(map + (list 1 2 3) (list 1 2 3) (list 1 2 3)) ;; Returns (3 6 9) -(define-private (a-or-b (char (string-utf8 1))) (if (is-eq char u\"a\") u\"a\" u\"b\")) -(map a-or-b u\"aca\") ;; Returns (u\"a\" u\"b\" u\"a\") -(define-private (zero-or-one (char (buff 1))) (if (is-eq char 0x00) 0x00 0x01)) -(map zero-or-one 0x000102) ;; Returns (0x00 0x01 0x01) -``` - -### fold -#### input: `Function(A, B) -> B, sequence_A, B` -#### output: `B` -#### signature: `(fold func sequence_A initial_B)` -#### description: -The `fold` function condenses `sequence_A` into a value of type `B` by recursively applies the function `func` to each element of the input sequence _and_ the output of a previous application of `func`. - -`fold` uses `initial_B` in the initial application of `func`, along with the first element of `sequence_A`. The resulting value of type `B` is used for the next application of `func`, along with the next element of `sequence_A` and so on. `fold` returns the last value of type `B` returned by these successive applications `func`. - -Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. - -#### example: -```clarity -(fold * (list 2 2 2) 1) ;; Returns 8 -(fold * (list 2 2 2) 0) ;; Returns 0 -;; calculates (- 11 (- 7 (- 3 2))) -(fold - (list 3 7 11) 2) ;; Returns 5 -(define-private (concat-string (a (string-ascii 20)) (b (string-ascii 20))) (unwrap-panic (as-max-len? (concat a b) u20))) -(fold concat-string \"cdef\" \"ab\") ;; Returns \"fedcab\" -(fold concat-string (list \"cd\" \"ef\") \"ab\") ;; Returns \"efcdab\" -(define-private (concat-buff (a (buff 20)) (b (buff 20))) (unwrap-panic (as-max-len? (concat a b) u20))) -(fold concat-buff 0x03040506 0x0102) ;; Returns 0x060504030102 -``` - -### append -#### input: `list A, A` -#### output: `list` -#### signature: `(append (list 1 2 3 4) 5)` -#### description: -The `append` function takes a list and another value with the same entry type, and outputs a list of the same type with max_len += 1. -#### example: -```clarity -(append (list 1 2 3 4) 5) ;; Returns (1 2 3 4 5) -``` - -### concat -#### input: `sequence_A, sequence_A` -#### output: `sequence_A` -#### signature: `(concat sequence1 sequence2)` -#### description: -The `func` argument must be a literal function name. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. - -#### example: -```clarity -(concat (list 1 2) (list 3 4)) ;; Returns (1 2 3 4) -(concat \"hello \" \"world\") ;; Returns \"hello world\" -(concat 0x0102 0x0304) ;; Returns 0x01020304 -``` - -### as-max-len? -#### input: `sequence_A, uint` -#### output: `sequence_A` -#### signature: `(as-max-len? sequence max_length)` -#### description: -The `as-max-len?` function takes a sequence argument and a uint-valued, literal length argument. The function returns an optional type. If the input sequence length is less than or equal to the supplied max_length, this returns `(some sequence)`, otherwise it returns `none`. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. ` -#### example: -```clarity -(as-max-len? (list 2 2 2) u3) ;; Returns (some (2 2 2)) -(as-max-len? (list 1 2 3) u2) ;; Returns none -(as-max-len? \"hello\" u10) ;; Returns (some \"hello\") -(as-max-len? 0x010203 u10) ;; Returns (some 0x010203) -``` - -### len -#### input: `sequence_A` -#### output: `uint` -#### signature: `(len sequence)` -#### description: -The `len` function returns the length of a given sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. ` -#### example: -```clarity -(len \"blockstack\") ;; Returns u10 -(len (list 1 2 3 4 5)) ;; Returns u5 -(len 0x010203) ;; Returns u3 -``` - -### element-at -#### input: `sequence_A, uint` -#### output: `(optional A)` -#### signature: `(element-at sequence index)` -#### description: -The `element-at` function returns the element at `index` in the provided sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. ` -#### example: -```clarity -(element-at \"blockstack\" u5) ;; Returns (some \"s\") -(element-at (list 1 2 3 4 5) u5) ;; Returns none -(element-at (list 1 2 3 4 5) (+ u1 u2)) ;; Returns (some 4) -(element-at \"abcd\" u1) ;; Returns (some \"b\") -(element-at 0xfb01 u1) ;; Returns (some 0x01) -``` - -### index-of -#### input: `sequence_A, A` -#### output: `(optional uint)` -#### signature: `(index-of sequence item)` -#### description: -The `index-of` function returns the first index at which `item` can be found, using `is-eq` checks, in the provided sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. If the target item is not found in the sequence (or if an empty string or buffer is supplied), this function returns `none`. -#### example: -```clarity -(index-of \"blockstack\" \"b\") ;; Returns (some u0) -(index-of \"blockstack\" \"k\") ;; Returns (some u4) -(index-of \"blockstack\" \"\") ;; Returns none -(index-of (list 1 2 3 4 5) 6) ;; Returns none -(index-of 0xfb01 0x01) ;; Returns (some u1) -``` - -### list -#### input: `A, ...` -#### output: `(list A)` -#### signature: `(list expr1 expr2 expr3 ...)` -#### description: -The `list` function constructs a list composed of the inputted values. Each supplied value must be of the same type. -#### example: -```clarity -(list (+ 1 2) 4 5) ;; Returns (3 4 5) -``` - -### var-get -#### input: `VarName` -#### output: `A` -#### signature: `(var-get var-name)` -#### description: -The `var-get` function looks up and returns an entry from a contract's data map. The value is looked up using `var-name`. -#### example: -```clarity -(define-data-var cursor int 6) -(var-get cursor) ;; Returns 6 -``` - -### var-set -#### input: `VarName, AnyType` -#### output: `bool` -#### signature: `(var-set var-name expr1)` -#### description: -The `var-set` function sets the value associated with the input variable to the inputted value. The function always returns `true`. -#### example: -```clarity -(define-data-var cursor int 6) -(var-get cursor) ;; Returns 6 -(var-set cursor (+ (var-get cursor) 1)) ;; Returns true -(var-get cursor) ;; Returns 7 -``` - -### map-get? -#### input: `MapName, tuple` -#### output: `(optional (tuple))` -#### signature: `(map-get? map-name key-tuple)` -#### description: -The `map-get?` function looks up and returns an entry from a contract's data map. The value is looked up using `key-tuple`. If there is no value associated with that key in the data map, the function returns a `none` option. Otherwise, it returns `(some value)`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(map-get? names-map (tuple (name \"blockstack\"))) ;; Returns (some (tuple (id 1337))) -(map-get? names-map { name: \"blockstack\" }) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-set -#### input: `MapName, tuple_A, tuple_B` -#### output: `bool` -#### signature: `(map-set map-name key-tuple value-tuple)` -#### description: -The `map-set` function sets the value associated with the input key to the inputted value. This function performs a _blind_ update; whether or not a value is already associated with the key, the function overwrites that existing association. - -Note: the `value-tuple` requires 1 additional byte for storage in the materialized blockchain state, and therefore the maximum size of a value that may be inserted into a map is MAX_CLARITY_VALUE - 1. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-set names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-insert -#### input: `MapName, tuple_A, tuple_B` -#### output: `bool` -#### signature: `(map-insert map-name key-tuple value-tuple)` -#### description: -The `map-insert` function sets the value associated with the input key to the inputted value if and only if there is not already a value associated with the key in the map. If an insert occurs, the function returns `true`. If a value already existed for this key in the data map, the function returns `false`. - -Note: the `value-tuple` requires 1 additional byte for storage in the materialized blockchain state, and therefore the maximum size of a value that may be inserted into a map is MAX_CLARITY_VALUE - 1. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns false -(map-insert names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-delete -#### input: `MapName, tuple` -#### output: `bool` -#### signature: `(map-delete map-name key-tuple)` -#### description: -The `map-delete` function removes the value associated with the input key for the given map. If an item exists and is removed, the function returns `true`. If a value did not exist for this key in the data map, the function returns `false`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-delete names-map { name: \"blockstack\" }) ;; Returns true -(map-delete names-map { name: \"blockstack\" }) ;; Returns false -(map-delete names-map (tuple (name \"blockstack\"))) ;; Same command, using a shorthand for constructing the tuple -``` - -### tuple -#### input: `(key-name A), (key-name-2 B), ...` -#### output: `(tuple (key-name A) (key-name-2 B) ...)` -#### signature: `(tuple (key0 expr0) (key1 expr1) ...)` -#### description: -The `tuple` special form constructs a typed tuple from the supplied key and expression pairs. A `get` function can use typed tuples as input to select specific values from a given tuple. Key names may not appear multiple times in the same tuple definition. Supplied expressions are evaluated and associated with the expressions' paired key name. - -There is a shorthand using curly brackets of the form {key0: expr0, key1: expr, ...}` -#### example: -```clarity -(tuple (name \"blockstack\") (id 1337)) ;; using tuple -{name: \"blockstack\", id: 1337} ;; using curly brackets -``` - -### get -#### input: `KeyName, (tuple) | (optional (tuple))` -#### output: `A` -#### signature: `(get key-name tuple)` -#### description: -The `get` function fetches the value associated with a given key from the supplied typed tuple. If an `Optional` value is supplied as the inputted tuple, `get` returns an `Optional` type of the specified key in the tuple. If the supplied option is a `(none)` option, get returns `(none)`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(get id (tuple (name \"blockstack\") (id 1337))) ;; Returns 1337 -(get id (map-get? names-map (tuple (name \"blockstack\")))) ;; Returns (some 1337) -(get id (map-get? names-map (tuple (name \"non-existent\")))) ;; Returns none -``` - -### merge -#### input: `tuple, tuple` -#### output: `tuple` -#### signature: `(merge tuple { key1: val1 })` -#### description: -The `merge` function returns a new tuple with the combined fields, without mutating the supplied tuples. -#### example: -```clarity -(define-map users { id: int } { name: (string-ascii 12), address: (optional principal) }) -(map-insert users { id: 1337 } { name: \"john\", address: none }) ;; Returns true -(let ((user (unwrap-panic (map-get? users { id: 1337 })))) -(merge user { address: (some 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) })) ;; Returns (tuple (address (some SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF)) (name \"john\")) -``` - -### begin -#### input: `AnyType, ... A` -#### output: `A` -#### signature: `(begin expr1 expr2 expr3 ... expr-last)` -#### description: -The `begin` function evaluates each of its input expressions, returning the return value of the last such expression. Note: intermediary statements returning a response type must be checked. -#### example: -```clarity -(begin (+ 1 2) 4 5) ;; Returns 5 -``` - -### hash160 -#### input: `buff|uint|int` -#### output: `(buff 20)` -#### signature: `(hash160 value)` -#### description: -The `hash160` function computes `RIPEMD160(SHA256(x))` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(hash160 0) ;; Returns 0xe4352f72356db555721651aa612e00379167b30f -``` - -### sha256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(sha256 value)` -#### description: -The `sha256` function computes `SHA256(x)` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(sha256 0) ;; Returns 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb -``` - -### sha512 -#### input: `buff|uint|int` -#### output: `(buff 64)` -#### signature: `(sha512 value)` -#### description: -The `sha512` function computes `SHA512(x)` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(sha512 1) ;; Returns 0x6fcee9a7b7a7b821d241c03c82377928bc6882e7a08c78a4221199bfa220cdc55212273018ee613317c8293bb8d1ce08d1e017508e94e06ab85a734c99c7cc34 -``` - -### sha512/256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(sha512/256 value)` -#### description: -The `sha512/256` function computes `SHA512/256(x)` (the SHA512 algorithm with the 512/256 initialization vector, truncated to 256 bits) of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(sha512/256 1) ;; Returns 0x515a7e92e7c60522db968d81ff70b80818fc17aeabbec36baf0dda2812e94a86 -``` - -### keccak256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(keccak256 value)` -#### description: -The `keccak256` function computes `KECCAK256(value)` of the inputted value. Note that this differs from the `NIST SHA-3` (that is, FIPS 202) standard. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(keccak256 0) ;; Returns 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4 -``` - -### secp256k1-recover? -#### input: `(buff 32), (buff 65)` -#### output: `(response (buff 33) uint)` -#### signature: `(secp256k1-recover? message-hash signature)` -#### description: -The `secp256k1-recover?` function recovers the public key used to sign the message which sha256 is `message-hash` with the provided `signature`. If the signature does not match, it will return the error code `(err u1).`. If the signature is invalid, it will return the error code `(err u2).`. The signature includes 64 bytes plus an additional recovery id (00..03) for a total of 65 bytes. -#### example: -```clarity -(secp256k1-recover? 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a1301) - ;; Returns (ok 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) - ``` - -### secp256k1-verify -#### input: `(buff 32), (buff 64) | (buff 65), (buff 33)` -#### output: `bool` -#### signature: `(secp256k1-verify message-hash signature public-key)` -#### description: -The `secp256k1-verify` function verifies that the provided signature of the message-hash was signed with the private key that generated the public key. The `message-hash` is the `sha256` of the message. The signature includes 64 bytes plus an optional additional recovery id (00..03) for a total of 64 or 65 bytes. -#### example: -```clarity -(secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a1301 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns true -(secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a13 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns true -(secp256k1-verify 0x0000000000000000000000000000000000000000000000000000000000000000 - 0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns false - ``` - -### print -#### input: `A` -#### output: `A` -#### signature: `(print expr)` -#### description: -The `print` function evaluates and returns its input expression. On Stacks Core nodes configured for development (as opposed to production mining nodes), this function prints the resulting value to `STDOUT` (standard output). -#### example: -```clarity -(print (+ 1 2 3)) ;; Returns 6 -``` - -### contract-call? -#### input: `ContractName, PublicFunctionName, Arg0, ...` -#### output: `(response A B)` -#### signature: `(contract-call? .contract-name function-name arg0 arg1 ...)` -#### description: -The `contract-call?` function executes the given public function of the given contract. You _may not_ use this function to call a public function defined in the current contract. If the public function returns _err_, any database changes resulting from calling `contract-call?` are aborted. If the function returns _ok_, database changes occurred. -#### example: -```clarity - -;; instantiate the sample-contracts/tokens.clar contract first! -(as-contract (contract-call? .tokens mint! u19)) ;; Returns (ok u19) -``` - -### as-contract -#### input: `A` -#### output: `A` -#### signature: `(as-contract expr)` -#### description: -The `as-contract` function switches the current context's `tx-sender` value to the _contract's_ principal and executes `expr` with that context. It returns the resulting value of `expr`. -#### example: -```clarity -(as-contract tx-sender) ;; Returns S1G2081040G2081040G2081040G208105NK8PE5.docs-test -``` - -### contract-of -#### input: `Trait` -#### output: `principal` -#### signature: `(contract-of .contract-name)` -#### description: -The `contract-of` function returns the principal of the contract implementing the trait. -#### example: -```clarity -(use-trait token-a-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) -(define-public (forward-get-balance (user principal) (contract )) - (begin - (ok (contract-of contract)))) ;; returns the principal of the contract implementing -``` - -### principal-of? -#### input: `(buff 33)` -#### output: `(response principal uint)` -#### signature: `(principal-of? public-key)` -#### description: -The `principal-of?` function returns the principal derived from the provided public key. If the `public-key` is invalid, it will return the error code `(err u1).`. ` -#### example: -```clarity -(principal-of? 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns (ok ST1AW6EKPGT61SQ9FNVDS17RKNWT8ZP582VF9HSCP) -``` - -### at-block -#### input: `(buff 32), A` -#### output: `A` -#### signature: `(at-block id-block-hash expr)` -#### description: -The `at-block` function evaluates the expression `expr` _as if_ it were evaluated at the end of the block indicated by the _block-hash_ argument. The `expr` closure must be read-only. - -This hash uniquely identifies Stacks blocks and is unique across Stacks forks. Note: The block identifying hash must be a hash returned by the `id-header-hash` block information property. While the hash returned by `header-hash` is unique within the context of a single fork, it is not unique across Stacks forks. - -The function returns the result of evaluating `expr`. - -#### example: -```clarity -(define-data-var data int 1) -(at-block 0x0000000000000000000000000000000000000000000000000000000000000000 block-height) ;; Returns u0 -(at-block (get-block-info? id-header-hash 0) (var-get data)) ;; Throws NoSuchDataVariable because `data` wasn't initialized at block height 0 -``` - -### get-block-info? -#### input: `BlockInfoPropertyName, BlockHeightInt` -#### output: `(optional buff) | (optional uint)` -#### signature: `(get-block-info? prop-name block-height-expr)` -#### description: -The `get-block-info?` function fetches data for a block of the given block height. The value and type returned are determined by the specified `BlockInfoPropertyName`. If the provided `BlockHeightInt` does not correspond to an existing block prior to the current block, the function returns `none`. The currently available property names are `time`, `header-hash`, `burnchain-header-hash`, `id-header-hash`, `miner-address`, and `vrf-seed`. - -This is a Unix epoch timestamp in seconds which roughly corresponds to when the block was mined. The `time` property returns an integer value of the block header time field. **Warning**: this does not increase monotonically with each block and block times are accurate only to within two hours. See [BIP113](https://github.com/bitcoin/bips/blob/master/bip-0113.mediawiki) for more information. - -The `header-hash`, `burnchain-header-hash`, `id-header-hash`, and `vrf-seed` properties return a 32-byte buffer. - -The `miner-address` property returns a `principal` corresponding to the miner of the given block. - -The `id-header-hash` is the block identifier value that must be used as input to the `at-block` function. - -#### example: -```clarity -(get-block-info? time u0) ;; Returns (some u1557860301) -(get-block-info? header-hash u0) ;; Returns (some 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb) -(get-block-info? vrf-seed u0) ;; Returns (some 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4) -``` - -### err -#### input: `A` -#### output: `(response A B)` -#### signature: `(err value)` -#### description: -The `err` function constructs a response type from the input value. Use `err` for creating return values in public functions. An _err_ value indicates that any database changes during the processing of the function should be rolled back. -#### example: -```clarity -(err true) ;; Returns (err true) -``` - -### ok -#### input: `A` -#### output: `(response A B)` -#### signature: `(ok value)` -#### description: -The `ok` function constructs a response type from the input value. Use `ok` for creating return values in public functions. An _ok_ value indicates that any database changes during the processing of the function should materialize. -#### example: -```clarity -(ok 1) ;; Returns (ok 1) -``` - -### some -#### input: `A` -#### output: `(optional A)` -#### signature: `(some value)` -#### description: -The `some` function constructs a `optional` type from the input value. -#### example: -```clarity -(some 1) ;; Returns (some 1) -(is-none (some 2)) ;; Returns false -``` - -### default-to -#### input: `A, (optional A)` -#### output: `A` -#### signature: `(default-to default-value option-value)` -#### description: -The `default-to` function attempts to 'unpack' the second argument: if the argument is a `(some ...)` option, it returns the inner value of the option. If the second argument is a `(none)` value, `default-to` it returns the value of `default-value`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(default-to 0 (get id (map-get? names-map (tuple (name \"blockstack\"))))) ;; Returns 1337 -(default-to 0 (get id (map-get? names-map (tuple (name \"non-existant\"))))) ;; Returns 0 -``` - -### asserts! -#### input: `bool, C` -#### output: `bool` -#### signature: `(asserts! bool-expr thrown-value)` -#### description: -The `asserts!` function admits a boolean argument and asserts its evaluation: if bool-expr is `true`, `asserts!` returns `true` and proceeds in the program execution. If the supplied argument is returning a false value, `asserts!` _returns_ `thrown-value` and exits the current control-flow. -#### example: -```clarity -(asserts! (is-eq 1 1) (err 1)) ;; Returns true -``` - -### unwrap! -#### input: `(optional A) | (response A B), C` -#### output: `A` -#### signature: `(unwrap! option-input thrown-value)` -#### description: -The `unwrap!` function attempts to 'unpack' the first argument: if the argument is an option type, and the argument is a `(some ...)` option, `unwrap!` returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, `unwrap!` returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `(none)` value, `unwrap!` _returns_ `thrown-value` from the current function and exits the current control-flow. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(define-private (get-name-or-err (name (string-ascii 12))) - (let ((raw-name (unwrap! (define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(define-private (get-name-or-err (name (string-ascii 12))) - (let ((raw-name (unwrap! names-map { name: name }) (err 1)))) - (ok raw-name))) - -(get-name-or-err \"blockstack\") ;; Returns (ok (tuple (id 1337))) -(get-name-or-err \"non-existant\") ;; Returns (err 1) -``` - -### unwrap-err! -#### input: `(response A B), C` -#### output: `B` -#### signature: `(unwrap-err! response-input thrown-value)` -#### description: -The `unwrap-err!` function attempts to 'unpack' the first argument: if the argument is an `(err ...)` response, `unwrap-err!` returns the inner value of the `err`. If the supplied argument is an `(ok ...)` value, `unwrap-err!` _returns_ `thrown-value` from the current function and exits the current control-flow. -#### example: -```clarity -(unwrap-err! (err 1) false) ;; Returns 1 -``` - -### unwrap-panic -#### input: `(optional A) | (response A B)` -#### output: `A` -#### signature: `(unwrap-panic option-input)` -#### description: -The `unwrap` function attempts to 'unpack' its argument: if the argument is an option type, and the argument is a `(some ...)` option, this function returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, it returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `(none)` value, `unwrap` throws a runtime error, aborting any further processing of the current transaction. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(unwrap-panic (map-get? names-map { name: \"blockstack\" })) ;; Returns (tuple (id 1337)) -(unwrap-panic (map-get? names-map { name: \"non-existant\" })) ;; Throws a runtime exception -``` - -### unwrap-err-panic -#### input: `(response A B)` -#### output: `B` -#### signature: `(unwrap-err-panic response-input)` -#### description: -The `unwrap-err` function attempts to 'unpack' the first argument: if the argument is an `(err ...)` response, `unwrap` returns the inner value of the `err`. If the supplied argument is an `(ok ...)` value, `unwrap-err` throws a runtime error, aborting any further processing of the current transaction. -#### example: -```clarity -(unwrap-err-panic (err 1)) ;; Returns 1 -(unwrap-err-panic (ok 1)) ;; Throws a runtime exception -``` - -### match -#### input: `(optional A) name expression expression | (response A B) name expression name expression` -#### output: `C` -#### signature: `(match opt-input some-binding-name some-branch none-branch) | -(match-resp input ok-binding-name ok-branch err-binding-name err-branch)` -#### description: -The `match` function is used to test and destructure optional and response types. - -If the `input` is an optional, it tests whether the provided `input` is a `some` or `none` option, and evaluates `some-branch` or `none-branch` in each respective case. - -Within the `some-branch`, the _contained value_ of the `input` argument is bound to the provided `some-binding-name` name. - -Only _one_ of the branches will be evaluated (similar to `if` statements). - -If the `input` is a response, it tests whether the provided `input` is an `ok` or `err` response type, and evaluates `ok-branch` or `err-branch` in each respective case. - -Within the `ok-branch`, the _contained ok value_ of the `input` argument is bound to the provided `ok-binding-name` name. - -Within the `err-branch`, the _contained err value_ of the `input` argument is bound to the provided `err-binding-name` name. - -Only _one_ of the branches will be evaluated (similar to `if` statements). - -Note: Type checking requires that the type of both the ok and err parts of the response object be determinable. For situations in which one of the parts of a response is untyped, you should use `unwrap-panic` or `unwrap-err-panic` instead of `match`. -#### example: -```clarity - -(define-private (add-10 (x (optional int))) - (match x - value (+ 10 value) - 10)) -(add-10 (some 5)) ;; Returns 15 -(add-10 none) ;; Returns 10 - -(define-private (add-or-pass-err (x (response int (string-ascii 10))) (to-add int)) - (match x - value (ok (+ to-add value)) - err-value (err err-value))) -(add-or-pass-err (ok 5) 20) ;; Returns (ok 25) -(add-or-pass-err (err \"ERROR\") 20) ;; Returns (err \"ERROR\") -``` - -### try! -#### input: `(optional A) | (response A B)` -#### output: `A` -#### signature: `(try! option-input)` -#### description: -The `try!` function attempts to 'unpack' the first argument: if the argument is an option type, and the argument is a `(some ...)` option, `try!` returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, `try!` returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `none` value, `try!` _returns_ either `none` or the `(err ...)` value from the current function and exits the current control-flow. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(try! (define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(define-private (get-name-or-err (name (string-ascii 12))) - (let ((raw-name (unwrap! names-map { name: \"blockstack\" })) ;; Returns (tuple (id 1337)) -(define-private (checked-even (x int)) - (if (is-eq (mod x 2) 0) - (ok x) - (err false))) -(define-private (double-if-even (x int)) - (ok (* 2 (try! (checked-even x))))) -(double-if-even 10) ;; Returns (ok 20) -(double-if-even 3) ;; Returns (err false) -``` - -### is-ok -#### input: `(response A B)` -#### output: `bool` -#### signature: `(is-ok value)` -#### description: -`is-ok` tests a supplied response value, returning `true` if the response was `ok`, and `false` if it was an `err`. -#### example: -```clarity -(is-ok (ok 1)) ;; Returns true -(is-ok (err 1)) ;; Returns false -``` - -### is-none -#### input: `(optional A)` -#### output: `bool` -#### signature: `(is-none value)` -#### description: -`is-none` tests a supplied option value, returning `true` if the option value is `(none)`, and `false` if it is a `(some ...)`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(is-none (get id (map-get? names-map { name: \"blockstack\" }))) ;; Returns false -(is-none (get id (map-get? names-map { name: \"non-existant\" }))) ;; Returns true -``` - -### is-err -#### input: `(response A B)` -#### output: `bool` -#### signature: `(is-err value)` -#### description: -`is-err` tests a supplied response value, returning `true` if the response was an `err`, and `false` if it was an `ok`. -#### example: -```clarity -(is-err (ok 1)) ;; Returns false -(is-err (err 1)) ;; Returns true -``` - -### is-some -#### input: `(optional A)` -#### output: `bool` -#### signature: `(is-some value)` -#### description: -`is-some` tests a supplied option value, returning `true` if the option value is `(some ...)`, and `false` if it is a `none`. -#### example: -```clarity - -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(is-some (get id (map-get? names-map { name: \"blockstack\" }))) ;; Returns true -(is-some (get id (map-get? names-map { name: \"non-existant\" }))) ;; Returns false -``` - -### filter -#### input: `Function(A) -> bool, sequence_A` -#### output: `sequence_A` -#### signature: `(filter func sequence)` -#### description: -The `filter` function applies the input function `func` to each element of the input sequence, and returns the same sequence with any elements removed for which `func` returned `false`. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. ` -#### example: -```clarity - -(filter not (list true false true false)) ;; Returns (false false) -(define-private (is-a (char (string-utf8 1))) (is-eq char u\"a\")) -(filter is-a u\"acabd\") ;; Returns u\"aa\" -(define-private (is-zero (char (buff 1))) (is-eq char 0x00)) -(filter is-zero 0x00010002) ;; Returns 0x0000 -``` - -### ft-get-balance -#### input: `TokenName, principal` -#### output: `uint` -#### signature: `(ft-get-balance token-name principal)` -#### description: -`ft-get-balance` returns `token-name` balance of the principal `principal`. The token type must have been defined using `define-fungible-token`. -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-get-balance stackaroo 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns u100 -``` - -### nft-get-owner? -#### input: `AssetName, A` -#### output: `(optional principal)` -#### signature: `(nft-get-owner? asset-class asset-identifier)` -#### description: -`nft-get-owner?` returns the owner of an asset, identified by `asset-identifier`, or `none` if the asset does not exist. The asset type must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) -(nft-get-owner? stackaroo \"Roo\") ;; Returns (some SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) -(nft-get-owner? stackaroo \"Too\") ;; Returns none -``` - -### ft-transfer? -#### input: `TokenName, uint, principal, principal` -#### output: `(response bool uint)` -#### signature: `(ft-transfer? token-name amount sender recipient)` -#### description: -`ft-transfer?` is used to increase the token balance for the `recipient` principal for a token type defined using `define-fungible-token` by debiting the `sender` principal. In contrast to `stx-transfer?`, any user can transfer the assets. When used, relevant guards need to be added. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- amount to send is non-positive ` -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-transfer? stackaroo u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(ft-transfer? stackaroo u60 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u1) -``` - -### nft-transfer? -#### input: `AssetName, A, principal, principal` -#### output: `(response bool uint)` -#### signature: `(nft-transfer? asset-class asset-identifier sender recipient)` -#### description: -`nft-transfer?` is used to change the owner of an asset identified by `asset-identifier` from `sender` to `recipient`. The `asset-class` must have been defined by `define-non-fungible-token` and `asset-identifier` must be of the type specified in that definition. In contrast to `stx-transfer?`, any user can transfer the asset. When used, relevant guards need to be added. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not own the asset `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- asset identified by asset-identifier does not exist ` -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(nft-transfer? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(nft-transfer? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u1) -(nft-transfer? stackaroo \"Stacka\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u3) -``` - -### nft-mint? -#### input: `AssetName, A, principal` -#### output: `(response bool uint)` -#### signature: `(nft-mint? asset-class asset-identifier recipient)` -#### description: -`nft-mint?` is used to instantiate an asset and set that asset's owner to the `recipient` principal. The asset must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. - -If an asset identified by `asset-identifier` _already exists_, this function will return an error with the following error code: - -`(err u1)` - -Otherwise, on successfuly mint, it returns `(ok true)`. ` -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### ft-mint? -#### input: `TokenName, uint, principal` -#### output: `(response bool uint)` -#### signature: `(ft-mint? token-name amount recipient)` -#### description: -`ft-mint?` is used to increase the token balance for the `recipient` principal for a token type defined using `define-fungible-token`. The increased token balance is _not_ transfered from another principal, but rather minted. - -If a non-positive amount is provided to mint, this function returns `(err 1)`. Otherwise, on successfuly mint, it returns `(ok true)`. ` -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### ft-get-supply -#### input: `TokenName` -#### output: `uint` -#### signature: `(ft-get-supply token-name)` -#### description: -`ft-get-balance` returns `token-name` circulating supply. The token type must have been defined using `define-fungible-token`. -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-get-supply stackaroo) ;; Returns u100 -``` - -### ft-burn? -#### input: `TokenName, uint, principal` -#### output: `(response bool uint)` -#### signature: `(ft-burn? token-name amount sender)` -#### description: -`ft-burn?` is used to decrease the token balance for the `sender` principal for a token type defined using `define-fungible-token`. The decreased token balance is _not_ transfered to another principal, but rather destroyed, reducing the circulating supply. - -If a non-positive amount is provided to burn, this function returns `(err 1)`. Otherwise, on successfuly burn, it returns `(ok true)`. - -#### example: -```clarity - -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(ft-burn? stackaroo u50 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### nft-burn? -#### input: `AssetName, A, principal` -#### output: `(response bool uint)` -#### signature: `(nft-burn? asset-class asset-identifier recipient)` -#### description: -`nft-burn?` is used to burn an asset and remove that asset's owner from the `recipient` principal. The asset must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. - -If an asset identified by `asset-identifier` _doesn't exist_, this function will return an error with the following error code: - -`(err u1)` - -Otherwise, on successfuly burn, it returns `(ok true)`. ` -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(nft-burn? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### stx-get-balance -#### input: `principal` -#### output: `uint` -#### signature: `(stx-get-balance owner)` -#### description: -`stx-get-balance` is used to query the STX balance of the `owner` principal. - -This function returns the STX balance of the `owner` principal. In the event that the `owner` principal isn't materialized, it returns 0. - -#### example: -```clarity -(stx-get-balance 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns u0 -(stx-get-balance (as-contract tx-sender)) ;; Returns u1000 -``` - -### stx-transfer? -#### input: `uint, principal, principal` -#### output: `(response bool uint)` -#### signature: `(stx-transfer? amount sender recipient)` -#### description: -`stx-transfer?` is used to increase the STX balance for the `recipient` principal by debiting the `sender` principal. The `sender` principal _must_ be equal to the current context's `tx-sender`. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- amount to send is non-positive `(err u4)` -- the `sender` principal is not the current `tx-sender` - -#### example: -```clarity - -(as-contract - (stx-transfer? u60 tx-sender 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (ok true) -(as-contract - (stx-transfer? u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR tx-sender)) ;; Returns (err u4) -``` - -### stx-burn? -#### input: `uint, principal` -#### output: `(response bool uint)` -#### signature: `(stx-burn? amount sender)` -#### description: -`stx-burn?` debits the `sender` principal's STX holdings by `amount`, destroying the STX. The `sender` principal _must_ be equal to the current context's `tx-sender`. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u3)` -- amount to send is non-positive `(err u4)` -- the `sender` principal is not the current `tx-sender` - -#### example: -```clarity -(as-contract - (stx-burn? u60 tx-sender)) ;; Returns (ok true) -(as-contract - (stx-burn? u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (err u4) -``` - -### define-constant -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-constant name expression)` -#### description: -`define-constant` is used to define a private constant value in a smart contract. The expression passed into the definition is evaluated at contract launch, in the order that it is supplied in the contract. This can lead to undefined function or undefined variable errors in the event that a function or variable used in the expression has not been defined before the constant. - -Like other kinds of definition statements, `define-constant` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -#### example: -```clarity - -(define-constant four (+ 2 2)) -(+ 4 four) ;; Returns 8 -``` - -### define-private -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-private (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### description: -`define-private` is used to define _private_ functions for a smart contract. Private functions may not be called from other smart contracts, nor may they be invoked directly by users. Instead, these functions may only be invoked by other functions defined in the same smart contract. - -Like other kinds of definition statements, `define-private` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Private functions may return any type. -#### example: -```clarity -(define-private (max-of (i1 int) (i2 int)) - (if (> i1 i2) - i1 - i2)) -(max-of 4 6) ;; Returns 6 -``` - -### define-public -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-public (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### description: -`define-public` is used to define a _public_ function and transaction for a smart contract. Public functions are callable from other smart contracts and may be invoked directly by users by submitting a transaction to the Stacks blockchain. - -Like other kinds of definition statements, `define-public` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Public functions _must_ return a ResponseType (using either `ok` or `err`). Any datamap modifications performed by a public function is aborted if the function returns an `err` type. Public functions may be invoked by other contracts via `contract-call?`. -#### example: -```clarity -(define-public (hello-world (input int)) - (begin (print (+ 2 input)) - (ok input))) -``` - -### define-read-only -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-read-only (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### description: -`define-read-only` is used to define a _public read-only_ function for a smart contract. Such functions are callable from other smart contracts. - -Like other kinds of definition statements, `define-read-only` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Read-only functions may return any type. However, read-only functions may not perform any datamap modifications, or call any functions which perform such modifications. This is enforced both during type checks and during the execution of the function. Public read-only functions may be invoked by other contracts via `contract-call?`. -#### example: -```clarity -(define-read-only (just-return-one-hundred) - (* 10 10)) - ``` - -### define-map -#### input: `MapName, TypeDefinition, TypeDefinition` -#### output: `Not Applicable` -#### signature: `(define-map map-name key-type value-type)` -#### description: -`define-map` is used to define a new datamap for use in a smart contract. Such maps are only modifiable by the current smart contract. - -Maps are defined with a key type and value type, often these types are tuple types. - -Like other kinds of definition statements, `define-map` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). -#### example: -```clarity -(define-map squares { x: int } { square: int }) -(define-private (add-entry (x int)) - (map-insert squares { x: 2 } { square: (* x x) })) -(add-entry 1) -(add-entry 2) -(add-entry 3) -(add-entry 4) -(add-entry 5) -``` - -### define-data-var -#### input: `VarName, TypeDefinition, Value` -#### output: `Not Applicable` -#### signature: `(define-data-var var-name type value)` -#### description: -`define-data-var` is used to define a new persisted variable for use in a smart contract. Such variable are only modifiable by the current smart contract. - -Persisted variable are defined with a type and a value. - -Like other kinds of definition statements, `define-data-var` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). -#### example: -```clarity -(define-data-var size int 0) -(define-private (set-size (value int)) - (var-set size value)) -(set-size 1) -(set-size 2) -``` - -### define-fungible-token -#### input: `TokenName, ` -#### output: `Not Applicable` -#### signature: `(define-fungible-token token-name )` -#### description: -`define-fungible-token` is used to define a new fungible token class for use in the current contract. - -The second argument, if supplied, defines the total supply of the fungible token. This ensures that all calls to the `ft-mint?` function will never be able to create more than `total-supply` tokens. If any such call were to increase the total supply of tokens passed that amount, that invocation of `ft-mint?` will result in a runtime error and abort. - -Like other kinds of definition statements, `define-fungible-token` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Tokens defined using `define-fungible-token` may be used in `ft-transfer?`, `ft-mint?`, and `ft-get-balance` functions` -#### example: -```clarity -(define-fungible-token stacks) -(define-fungible-token limited-supply-stacks u100) -``` - -### define-non-fungible-token -#### input: `AssetName, TypeSignature` -#### output: `Not Applicable` -#### signature: `(define-non-fungible-token asset-name asset-identifier-type)` -#### description: -`define-non-fungible-token` is used to define a new non-fungible token class for use in the current contract. Individual assets are identified by their asset identifier, which must be of the type `asset-identifier-type`. Asset identifiers are _unique_ identifiers. - -Like other kinds of definition statements, `define-non-fungible-token` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Assets defined using `define-non-fungible-token` may be used in `nft-transfer?`, `nft-mint?`, and `nft-get-owner?` functions` -#### example: -```clarity -(define-non-fungible-token names (buff 50)) -``` - -### define-trait -#### input: `VarName, [MethodSignature]` -#### output: `Not Applicable` -#### signature: `(define-trait trait-name ((func1-name (arg1-type arg2-type ...) (return-type))))` -#### description: -`define-trait` is used to define a new trait definition for use in a smart contract. Other contracts can implement a given trait and then have their contract identifier being passed as function arguments in order to be called dynamically with `contract-call?`. - -Traits are defined with a name, and a list functions defined with a name, a list of argument types, and return type. - -Like other kinds of definition statements, `define-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -#### example: -```clarity -(define-trait token-trait - ((transfer? (principal principal uint) (response uint uint)) - (get-balance (principal) (response uint uint)))) -``` - -### use-trait -#### input: `VarName, TraitIdentifier` -#### output: `Not Applicable` -#### signature: `(use-trait trait-alias trait-identifier)` -#### description: -`use-trait` is used to bring a trait, defined in another contract, to the current contract. Subsequent references to an imported trait are signaled with the syntax ``. - -Traits import are defined with a name, used as an alias, and a trait identifier. Trait identifiers can either be using the sugared syntax (.token-a.token-trait), or be fully qualified ('SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait). - -Like other kinds of definition statements, `use-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put such a statement in the middle of a function body). -#### example: -```clarity -(use-trait token-a-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) -(define-public (forward-get-balance (user principal) (contract )) - (begin - (ok 1))) -``` - -### impl-trait -#### input: `TraitIdentifier` -#### output: `Not Applicable` -#### signature: `(impl-trait trait-identifier)` -#### description: -`impl-trait` can be use for asserting that a contract is fully implementing a given trait. Additional checks are being performed when the contract is being published, rejecting the deployment if the contract is violating the trait specification. - -Trait identifiers can either be using the sugared syntax (.token-a.token-trait), or be fully qualified ('SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait). - -Like other kinds of definition statements, `impl-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put such a statement in the middle of a function body). - -#### example: -```clarity -(impl-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) (define-public (get-balance (account principal)) (ok u0)) (define-public (transfer? (from principal) (to principal) (amount uint)) - (ok u0)) -``` \ No newline at end of file diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md b/i18n/ru/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md deleted file mode 100644 index fd62451198..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Keywords -description: See a detailed list of all keywords for the Clarity language. -tags: - - clarity ---- - -![](/img/keywords.jpg) -## Keyword reference - -Detailed list of all keywords for the Clarity language. - - -### contract-caller -#### output: `principal` -#### description: -Returns the caller of the current contract context. If this contract is the first one called by a signed transaction, the caller will be equal to the signing principal. If `contract-call?` was used to invoke a function from a new contract, `contract-caller` changes to the _calling_ contract's principal. If `as-contract` is used to change the `tx-sender` context, `contract-caller` _also_ changes to the same contract principal. -#### example: -```clarity -(print contract-caller) ;; Will print out a Stacks address of the transaction sender -``` - -### tx-sender -#### output: `principal` -#### description: -Returns the original sender of the current transaction, or if `as-contract` was called to modify the sending context, it returns that contract principal. -#### example: -```clarity -(print tx-sender) ;; Will print out a Stacks address of the transaction sender -``` - -### block-height -#### output: `uint` -#### description: -Returns the current block height of the Stacks blockchain as an uint -#### example: -```clarity -(> block-height 1000) ;; returns true if the current block-height has passed 1000 blocks. -``` - -### burn-block-height -#### output: `uint` -#### description: -Returns the current block height of the underlying burn blockchain as a uint -#### example: -```clarity -(> burn-block-height 1000) ;; returns true if the current height of the underlying burn blockchain has passed 1000 blocks. -``` - -### none -#### output: `(optional ?)` -#### description: -Represents the _none_ option indicating no value for a given optional (analogous to a null value). -#### example: -```clarity -(define-public (only-if-positive (a int)) - (if (> a 0) - (some a) - none)) -(only-if-positive 4) ;; Returns (some 4) -(only-if-positive (- 3)) ;; Returns none -``` - -### true -#### output: `bool` -#### description: -Boolean true constant. -#### example: -```clarity -(and true false) ;; Evaluates to false -(or false true) ;; Evaluates to true -``` - -### false -#### output: `bool` -#### description: -Boolean false constant. -#### example: -```clarity -(and true false) ;; Evaluates to false -(or false true) ;; Evaluates to true -``` - -### stx-liquid-supply -#### output: `uint` -#### description: -Returns the total number of micro-STX (uSTX) that are liquid in the system as of this block. -#### example: -```clarity -(print stx-liquid-supply) ;; Will print out the total number of liquid uSTX -``` - -### is-in-regtest -#### output: `bool` -#### description: -Returns whether or not the code is running in a regression test -#### example: -```clarity -(print is-in-regtest) ;; Will print 'true' if the code is running in a regression test -``` - diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md b/i18n/ru/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md deleted file mode 100644 index d22f991413..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Types -description: See a detailed list of all types for the Clarity language. -tags: - - clarity ---- - -## Clarity Type System - -The type system contains the following types: - -| Types | Notes | -| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `int` | signed 128-bit integer | -| `uint` | unsigned 128-bit integer | -| `bool` | boolean value (`true` or `false`) | -| `principal` | object representing a principal (whether a contract principal or standard principal) | -| `(buff max-len)` | byte buffer of 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` (u"A smiley face emoji \u{1F600} as a utf8 string") | -| `(list max-len entry-type)` | list of maximum length `max-len`, with entries of type `entry-type` | -| `{label-0: value-type-0, label-1: value-type-1, ...}` | tuple, group of data values with named fields | -| `(optional some-type)` | an option type for objects that can either be `(some value)` or `none` | -| `(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. | diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md b/i18n/ru/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md deleted file mode 100644 index e75e1d69b9..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Clarity overview -description: Overview and guides for getting started with Clarity -sidebar_label: Write smart contracts -sidebar_position: 2 ---- - -## Introduction - -Clarity is a **decidable** smart contract language that optimizes for predictability and security, designed for the Stacks blockchain. Smart contracts allow developers to encode essential business logic on a blockchain. - -## Smart contracts - -Smart contracts encode and enforce rules for modifying a particular set of data that is shared among people and entities who don't necessarily trust each other. For example, a smart contract can hold funds in escrow until multiple parties agree to release them, create its own ledger and keep track of its own novel tokens (fungible or non-fungible), and even help make supply chains more transparent. - -A smart contract execution can result in new transactions being written to the blockchain. Because smart contracts are programs that exist in a blockchain, anyone can query them, and anyone can submit transactions to execute them. - -Apps can take advantage of smart contracts to manage a global state that is visible to the public. Anyone can audit the blockchain to independently verify that an app's global shared state has been managed correctly according to the smart contract's rules. - -There is a [Clarity Visual Studio Code plugin][] available for syntax assistance and debugging. - -## Use cases - -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 (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 - -## Language design - -Clarity differs from most other smart contract languages in two essential ways: - -- The language is interpreted and broadcast on the blockchain as is (not compiled) -- The language is decidable (not Turing complete) - -Using an interpreted language ensures that the executed code is human-readable and auditable. A decidable language like Clarity makes it possible to determine precisely which code is executed, for any function. - -A Clarity smart contract consists of two parts, a data space and a set of functions. Only the associated smart contract may modify its corresponding data space on the blockchain. Functions may be private and thus callable only from within the smart contract, or public and thus callable from other contracts. Users call smart contracts' public functions by broadcasting a transaction on the blockchain which invokes the public function. Contracts can also call public functions from other smart contracts. - -Note some of the key Clarity language rules and limitations. - -- The only primitive types are booleans, integers, buffers, and principals. -- Recursion is illegal and there are no anonymous functions. -- Looping is only performed via `map`, `filter`, or `fold`. -- There is support for lists, however, the only variable length lists in the language appear as function inputs; there is no support for list operations like append or join. -- Variables are immutable. - -## Explore more - -For language details and references, see the following: - -- [Clarity language overview](./clarity-language/) -- [Understating Principals](principals) -- [Clarity Values](values) - -[Clarity Visual Studio Code plugin]: https://marketplace.visualstudio.com/items?itemName=HiroSystems.clarity-lsp diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md b/i18n/ru/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md deleted file mode 100644 index 2482d174a7..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md +++ /dev/null @@ -1,240 +0,0 @@ ---- -title: Principals -description: 'Clarity: Understanding Principals' -sidebar_position: 1 ---- - -## Introduction - -_Principals_ are a Clarity native type that represents an entity that can have a token balance. This section discusses principals and how they are used in the Clarity. - -## Principals and tx-sender - -Assets in the smart contracting language and blockchain are "owned" by objects of the principal type, meaning that any object of the principal type may own an asset. For the case of public-key hash and multi-signature Stacks addresses, a given principal can operate on their assets by issuing a signed transaction on the blockchain. _Smart contracts_ may also be principals (represented by the smart contract's identifier), however, there is no private key associated with the smart contract, and it cannot broadcast a signed transaction on the blockchain. - -A Clarity contract can use a globally defined `tx-sender` variable to obtain the current principal. The following example defines a transaction type that transfers `amount` microSTX from the sender to a recipient if amount is a multiple of 10, otherwise returning a 400 error code. - -```clarity -(define-public (transfer-to-recipient! (recipient principal) (amount uint)) - (if (is-eq (mod amount 10) 0) - (stx-transfer? amount tx-sender recipient) - (err u400))) -``` - -Clarity provides an additional variable to help smart contracts authenticate a transaction sender. The keyword `contract-caller` returns the principal that _called_ the current contract. If an inter-contract call occurred, `contract-caller` returns the last contract in the stack of callers. For example, suppose there are three contracts A, B, and C, each with an `invoke` function such that `A::invoke` calls `B::invoke` and `B::invoke` calls `C::invoke`. - -When a user Bob issues a transaction that calls `A::invoke`, the value of `contract-caller` in each successive invoke function's body would change: - -```clarity -in A::invoke, contract-caller = Bob -in B::invoke, contract-caller = A -in C::invoke, contract-caller = B -``` - -This allows contracts to make assertions and perform authorization checks using not only the `tx-sender` (which in this example, would always be "Bob"), but also using the `contract-caller`. This could be used to ensure that a particular function is only ever called directly and never called via an inter-contract call (by asserting that `tx-sender` and `contract-caller` are equal). We provide an example of a two different types of authorization checks in the rocket ship example below. - -## Smart contracts as principals - -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, for example: - -```clarity -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-name -``` - -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 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 qualified identifier for the contracts would be: - -```clarity -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-A -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-B -``` - -But, in the contract source code, if the developer wishes to call a function from `contract-A` in `contract-B`, they can write - -```clarity -(contract-call? .contract-A public-function-foo) -``` - -This allows the smart contract developer to modularize their applications across multiple smart contracts _without_ knowing the publishing key a priori. - -In order for a smart contract to operate on assets it owns, smart contracts may use the special `(as-contract ...)` function. This function executes the expression (passed as an argument) with the `tx-sender` set to the contract's principal, rather than the current sender. The `as-contract` function returns the value of the provided expression. - -For example, a smart contract that implements something like a "token faucet" could be implemented as so: - -```clarity -(define-map claimed-before - ((sender principal)) - ((claimed bool))) - -(define-constant err-already-claimed u1) -(define-constant err-faucet-empty u2) -(define-constant stx-amount u1) - -(define-public (claim-from-faucet) - (let ((requester tx-sender)) ;; set a local variable requester = tx-sender - (asserts! (is-none (map-get? claimed-before {sender: requester})) (err err-already-claimed)) - (unwrap! (as-contract (stx-transfer? stx-amount tx-sender requester)) (err err-faucet-empty)) - (map-set claimed-before {sender: requester} {claimed: true}) - (ok stx-amount))) -``` - -In this example, the public function `claim-from-faucet`: - -- Checks if the sender has claimed from the faucet before. -- Assigns the tx sender to a `requester` variable. -- Adds an entry to the tracking map. -- Uses `as-contract` to send 1 microstack - -Unlike other principals, there is no private key associated with a smart contract. As it lacks a private key, a Clarity smart contract cannot broadcast a signed transaction on the blockchain. - -## Example: Authorization checks - -The interactions between `tx-sender`, `contract-caller` and `as-contract` are subtle, but are important when performing authorization checks in a contract. In this example contract, we'll show two different kinds of authorization checks a contract may wish to perform, and then walk through how different ways in which contract functions may be called will pass or fail those checks. - -This contract defines a "rocket-ship" non-fungible-token that a principal may own and manage the authorized pilots. Pilots are principals that are allowed to "fly" the rocket ship. - -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. -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 be called _directly_ by the ship's owner, rather than through a inter-contract-call. - -The second type of check is more restrictive than the first check, and is helpful for guarding very sensitive routines --- it protects users from unknowingly calling a function on a malicious contract that subsequently tries to call sensitive functions on another contract. - -```clarity -;; -;; rockets-base.clar -;; - -(define-non-fungible-token rocket-ship uint) - -;; a map from rocket ships to their allowed -;; pilots -(define-map allowed-pilots - ((rocket-ship uint)) ((pilots (list 10 principal)))) - -;; implementing a contains function via fold -(define-private (contains-check - (y principal) - (to-check { p: principal, result: bool })) - (if (get result to-check) - to-check - { p: (get p to-check), - result: (is-eq (get p to-check) y) })) - -(define-private (contains (x principal) (find-in (list 10 principal))) - (get result (fold contains-check find-in - { p: x, result: false }))) - -(define-read-only (is-my-ship (ship uint)) - (is-eq (some tx-sender) (nft-get-owner? rocket-ship ship))) - -;; this function will print a message -;; (and emit an event) if the tx-sender was -;; an authorized flyer. -;; -;; here we use tx-sender, because we want -;; to allow the user to let other contracts -;; fly the ship on behalf of users - -(define-public (fly-ship (ship uint)) - (let ((pilots (default-to - (list) - (get pilots (map-get? allowed-pilots { rocket-ship: ship }))))) - (if (contains tx-sender pilots) - (begin (print "Flew the rocket-ship!") - (ok true)) - (begin (print "Tried to fly without permission!") - (ok false))))) -;; -;; Authorize a new pilot. - (ok true)) - (begin (print "Tried to fly without permission!") - (ok false))))) -;; -;; Authorize a new pilot. - (ok false))))) -;; -;; Authorize a new pilot. -;; -;; here we want to ensure that this function -;; was called _directly_ by the user by -;; checking that tx-sender and contract-caller are equal. -;; if any other contract is in the call stack, contract-caller -;; would be updated to a different principal. -;; -(define-public (authorize-pilot (ship uint) (pilot principal)) - (begin - ;; sender must equal caller: an intermediate contract is - ;; not issuing this call. - (asserts! (asserts! (is-eq tx-sender contract-caller) (err u1)) - ;; sender must own the rocket ship - (asserts! (is-eq (some tx-sender) - (nft-get-owner? rocket-ship ship)) (err u2)) - (let ((prev-pilots (default-to - (list) - (get pilots (map-get? allowed-pilots { rocket-ship: ship }))))) - ;; don't add a pilot already in the list - (asserts! (not (contains pilot prev-pilots)) (err u3)) - ;; append to the list, and check that it is less than - ;; the allowed maximum - (match (as-max-len? -``` - -### Extending functionality: Multi-flyer contract - -The authorization scheme for `fly-ship` allows pilots to fly rocket-ships from other contracts. This allows other contracts to provide new functionality built around calling that function. - -For example, we can create a contract that calls `fly-ship` for multiple rocket-ships in a single transaction: - -```clarity -;; -;; rockets-multi.clar -;; - -(define-private (call-fly (ship uint)) - (unwrap! (contract-call? .rockets-base fly-ship ship) false)) -;; try to fly all the ships, returning a list of whether -;; or not we were able to fly the supplied ships -(define-public (fly-all (ships (list 10 uint))) - (ok (map call-fly ships))) -``` - -### Authorization for Contract-Owned Assets - -The check in `authorize-pilot` protects users from malicious contracts, but how would such a scheme support contract-owned assets? This is what the `as-contract` function is used for. The `as-contract` function executes the supplied closure as if the sender of the transaction was the current contract, rather than the user -- it does this by updating `tx-sender` to the current contract principal. We can use this to, for example, create a smart contract rocket-ship-line: - -```clarity -;; -;; rockets-ship-line.clar -;; - -(define-constant line-ceo 'SP19Y6GRV9X778VFS1V8WT2H502WFK33XZXADJWZ) - -(define-data-var employed-pilots (list 10 principal) (list)) - -;; This function will: -;; * check that it is called by the line-ceo -;; * check that the rocket is owned by the contract -;; * authorize each employed pilot to the ship -(define-public (add-managed-rocket (ship uint)) - (begin - ;; 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 - (asserts! (contract-call? .rockets-base is-my-ship ship) (err u2)) - ;; register all of our pilots on the ship - (add-pilots-to ship))))) - -;; add all the pilots to a ship using fold -- -;; the fold checks the return type of previous calls, -;; skipping subsequent contract-calls if one fails. -(define-private (add-pilot-via-fold (pilot principal) (prior-result (response uint uint))) - (let ((ship (try! prior-result))) - (try! (contract-call? .rockets-base authorize-pilot ship pilot)) - (ok ship))) -(define-private (add-pilots-to (ship uint)) - (fold add-pilot-via-fold (var-get employed-pilots) (ok ship))) -``` - -In order for the contract to add each pilot to a new ship, the contract must call `authorize-pilot`. However, the contract wants to perform this action on behalf of a ship the _contract_ owns, not the transaction sender. To do this, the contract uses `as-contract`. diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md b/i18n/ru/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md deleted file mode 100644 index a01e37bc04..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Resources -description: 'Resources' -sidebar_position: 8 ---- - -# External resources - - -[Clarity book](https://book.clarity-lang.org/) - -[Clarity Universe](https://stacks.org/clarity-universe) - -[Hiro Clarity tutorials](https://docs.hiro.so/tutorials) diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md b/i18n/ru/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md deleted file mode 100644 index ed65829518..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Clarity development software -description: The following tools are useful when developing Clarity smart contracts -sidebar_position: 4 ---- - -## Language Server Protocol for Clarity (including Visual Studio Code extension) - -The Language Server Protocol (LSP) defines the protocol used between an editor or IDE and a language server that provides language features like auto complete, go to definition, find all references etc. - -This makes programming in Clarity easier and much more intuitive. - -![Clarity LSP Screenshot](https://raw.githubusercontent.com/hirosystems/clarity-lsp/21b64298ca117dc41358eb9dce4605cc4a448a4c/images/screenshot.png?raw=true) - - -Clarity LSP repository is available [here](https://github.com/hirosystems/clarity-lsp). The extension for Visual Studio Code can be downloaded directly from [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=HiroSystems.clarity-lsp), but can be and older version. For a more up to date version you can also download it from [open-vsx](https://open-vsx.org/extension/hirosystems/clarity-lsp). - -## Clarity REPL - -A read—eval—print loop (REPL), also termed an interactive toplevel or language shell, is a simple, interactive computer programming environment that takes single user inputs (that is, single expressions), evaluates (executes) them, and returns the result to the user; a program written in a REPL environment is executed piecewise. - -![Clarity-repl](https://github.com/hirosystems/clarity-repl/blob/develop/docs/images/screenshot.png?raw=true) - -Instructions on how to install Clarity REPL can be found [here](https://github.com/hirosystems/clarity-repl). - -## Clarinet - -Clarinet is a Clarity runtime packaged as a command line tool, designed to facilitate smart contract understanding, development, testing and deployment. Clarinet consists of a Clarity REPL and a testing harness, which, when used together allow you to rapidly develop and test a Clarity smart contract, with the need to deploy the contract to a local devnet or testnet. - -![Clarinet](https://github.com/hirosystems/clarinet/blob/develop/docs/images/demo.gif?raw=true) - -Installation instructions, including build from source instructions can be found [here](https://github.com/hirosystems/clarinet). If you prefer you can directly download the latest compiled realease for Windows, Mac and Linux [here](https://github.com/hirosystems/clarinet/releases). - -[Clarinet 101](https://www.youtube.com/playlist?list=PL5Ujm489LoJaAz9kUJm8lYUWdGJ2AnQTb) contains multiple Clarinet video tutorials - -### Getting started with Clarinet - -You can verify you have Clarinet installed by checking its version: - -```bash -$ clarinet --version -clarinet 0.70 -``` - -More detailed information on using Clarinet is available [here](https://book.clarity-lang.org/ch07-00-using-clarinet.html). However to get you started, the following commands are important to know. - -Create a new project and enter its directory: - -```bash -clarinet new my-project && cd my-project -``` - -Create a new contract inside `my-project`: - -```bash -clarinet contract new mycoolcontract -``` - -Check the syntax of Clarity: - -```bash -clarity check -``` - -To test your contract: - -```bash -clarinet test -``` - -Enter Clarinet's console: - -```bash -clarinet console -``` diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md b/i18n/ru/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md deleted file mode 100644 index 2754709092..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Tokens -description: Learn about token support within Clarity -sidebar_position: 3 ---- - -## Introduction - -A fundamental use of blockchain technology is the representation, store, and transfer of value between users of a blockchain. Cryptocurrency is a very common use of blockchain technology, and remains one of the primary drivers of adoption of blockchain technology. Cryptocurrencies are represented by blockchain tokens: individual units of value within a given blockchain ecosystem. Blockchain tokens can extend beyond just digital currency, however, and recent developments throughout the cryptocurrency community have demonstrated potential for the use of blockchain to tokenize and represent not just money but other tangible assets. - -A blockchain token is a digital asset that can be verifiably owned by a user of a blockchain. Blockchain tokens are governed by a set of rules that are defined by either the blockchain itself (in the case of native tokens) or by a smart contract on a blockchain. Rules can vary depending on the nature and the use of the token. - -Tokens on a blockchain fall into two general categories, depending on their properties: [fungible][] or [non-fungible][]. The following sections discuss the properties of both types of tokens, and provide information about implementation of the two types of tokens on Stacks. - -## Fungible tokens - -A core property of any token on a blockchain is fungibility. A fungible token is a token that's mutually interchangable or capable of mutual substitution. In other words, one quantity or part of a fungible token can be replaced by an equal quantity or part of the same fungible token. Fungible tokens are often used to represent real-world fungible assets like currency. The STX token is an example of a fungible token. Other examples include stablecoins, tokens that represent voting rights in a DAO, or tokens that algorithmically track the price of stocks. - -Fungible tokens form one of the most important value propositions for blockchain technology, the ability to store value and exchange that value through both internal and external transactions. Because fungible tokens can be divided into smaller parts and recombined into the same value representation, they serve a great utility for transferring value between blockchain users. - -The primary fungible token on the Stacks blockchain is the native token, STX. Because the Stacks blockchain allows for the creation of \[smart contracts\]\[\], other fungible tokens can be created on the Stacks blockchain as well. [SIP-010][] specifies the standard for fungible tokens on the Stacks blockchain. This specification defines the functions and traits that a fungible token on Stacks _must_ have. This specification defines the functions and traits that a fungible token on Stacks _must_ have. - -### Understanding the fungible token standard - -The [SIP-010][] standard is an interface definition that allows Stacks applications and wallets to interact with fungible tokens in a standard way. Supporting the standard reduces complexity for token creators to get their tokens into the ecosystem. Under the [SIP-010][] standard, fungible tokens must have the following characteristics: - -- Ability to transfer a specified amount of the token to a recipient (`transfer`). The recipient is required to be a Stacks principal. -- Ability to obtain the human-readable name of the token (`get-name`). -- Ability to obtain a short name (ticker symbol) for the token (`get-symbol`). -- Ability to get the number of decimals in the token representation (`get-decimals`). This is used to construct a representation of the token that humans would be familiar dealing with. For example, the US dollar has 2 decimals, if the base unit is cents. -- Ability to get the balance of the token for a particular Stacks principal (`get-balance-of`). -- Ability to get the total supply of the token (`get-total-supply`). -- A URI to metadata associated with the token (`get-token-uri`). This can resolve to off-chain metadata about the token or contract, such as an image icon for the token or a description. - -## Non-fungible tokens (NFTs) - -Non-fungible tokens (NFTs) are a type of token that are not interchangeable. NFTs have unique traits (usually in the form of attached metadata) that restrict the abillity to replace them with identical tokens. An NFT is a token that is unique, such as a piece of art, or ownership rights to a real-world asset such as a house. - -NFTs alone don't have an inherent value, like a currency. The value of an NFT is derived from the assets that the NFT represents. The use of NFTs are myriad, including digital art, collectibles, domain names, and representation of ownership of content rights. NFTs can be used as digital certificates that track the authenticty of real world items, or digitize the ownership rights to property. - -As with fungible tokens, NFTs on the Stacks blockchain are created with smart contracts. [SIP-009][] specifies the standard for NFTs on the Stacks blockchain. This specification defines the functions and traits that an NFT _must_ have, but most NFTs have more functions or traits attached than those solely described by the specification. By complying with this standard, non-fungible tokens on Stacks can be easily represented by wallets that support Stacks. - -### Understanding the non-fungible token standard - -The [SIP-009][] standard is an interface definition that the Stacks ecosystem aligned on. With support for this standard across wallets and tools, it becomes easy to interact with NFTs. Under the [SIP-009][] standard, NFT contract must have the following characteristics: - -- Ability to obtain the last token identifier (`get-last-token-id`). This id represents the upper limit of NFTs issued by the contract. -- A URI to metadata associated with a specific token identifier. (`get-token-uri`). This URI could resolve to a JSON file with information about the creator, associated media files, descriptions, signatures, and more. -- Ability to verify the owner for a given token identifier (`get-owner`). The owner resolves to a [Stacks principal](principals). -- Ability to transfer an NFT to a recipient (`transfer`). The recipient is required to be a Stacks principal. - -## Further reading - -- [The Difference Between Fungible and Non-Fungible Tokens](https://101blockchains.com/fungible-vs-non-fungible-tokens/) -- [Explain It Like I Am 5: NFTs](https://messari.io/article/explain-it-like-i-am-5-nfts) - -[fungible]: #fungible-tokens -[non-fungible]: #non-fungible-tokens-nfts -[SIP-010]: https://github.com/hstove/sips/blob/feat/sip-10-ft/sips/sip-010/sip-010-fungible-token-standard.md -[SIP-009]: https://github.com/stacksgov/sips/blob/main/sips/sip-009/sip-009-nft-standard.md diff --git a/i18n/ru/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md b/i18n/ru/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md deleted file mode 100644 index fc4765aa0c..0000000000 --- a/i18n/ru/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md +++ /dev/null @@ -1,301 +0,0 @@ ---- -title: Clarity Values -description: Learn how to deal with Clarity Values in JavaScript -sidebar_position: 2 ---- - -## Introduction - -The Clarity language makes use of a strong static 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/hirosystems/stacks.js/tree/master/packages/transactions) library makes this easy, as we will demonstrate below. - -## Clarity Types - -Please see the following page for information on [Clarity Types](../write-smart-contracts/clarity-language/language-types). - -## Constructing Clarity Values and accessing their data - -Clarity values can be constructed with functions provided by the [@stacks/transactions](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library. These functions simply output javascript objects that contain a value and a numerical representation of the Clarity type information. The Clarity types are encoded as follows: - -```typescript -export enum ClarityType { - Int = 0, - UInt = 1, - Buffer = 2, - BoolTrue = 3, - BoolFalse = 4, - PrincipalStandard = 5, - PrincipalContract = 6, - ResponseOk = 7, - ResponseErr = 8, - OptionalNone = 9, - OptionalSome = 10, - List = 11, - Tuple = 12, - StringASCII = 13, - StringUTF8 = 14, -} -``` - -`ClarityValue` objects can be serialized and included in transactions that interact with published Clarity contracts. - -Here are examples of how to construct each type of Clarity value, and how to access its data if it has any: - -### Booleans - -```typescript -const t = trueCV(); -// { type: ClarityType.BoolTrue } - -const f = falseCV(); -// { type: ClarityType.BoolFalse } -``` - -Boolean Clarity Values don't contain any underlying data. They are simply objects with `type` information. - -### Optional Values - -```typescript -const nothing: NoneCV = noneCV(); -// { type: ClarityType.OptionalNone } - -const something: SomeCV = someCV(trueCV()); -// { type: ClarityType.OptionalSome, value: { type: 4 } } -``` - -Optional Clarity Values can either be nothing (an empty type that has no data), or something (a wrapped value). - -If you are dealing with a function or contract function that returns an `OptionalCV`, you should always check what type it is before trying to access its value. - -```typescript -const maybeVal: OptionalCV = await callReadOnlyFunction(...); - -if (maybeVal.type === ClarityType.OptionalSome) { - console.log(maybeVal.value); -} else if (maybeVal.type === ClarityType.OptionalNone) { - // deal with `none` value -} -``` - -### Buffers - -```typescript -const buffer = Buffer.from('foo'); -const bufCV: BufferCV = bufferCV(buffer); -// { type: ClarityType.Buffer, buffer: } -``` - -### Integers - -Clarity supports both integers and unsigned integers. - -```typescript -const i: IntCV = intCV(-10); -// { type: ClarityType.Int, value: BN { ... } } - -const u: UIntCV = uintCV(10); -// { type: ClarityType.UInt, value: BN { ... } } -``` - -Clarity value ints store their underlying data as `BigNum` values from the [bn.js](https://github.com/indutny/bn.js/) library. - -In order to display/print Clarity (u)int values, use the `cvToString(val)` method. - -If you wish to perform arithmetic operations using Clarity (u)int values, you must use methods from the `BigNum` api on their underlying `BigNum` values, and the construct a new Clarity value out of the result. For example: - -```typescript -const x = intCV(1); -const y = intCV(2); - -x.value.add(y.value); -// 3 -``` - -### Strings - -```typescript -const ascii: StringAsciiCV = stringAsciiCV('hello world'); -// { type: ClarityType.StringASCII, data: 'hello world' } - -const utf8: StringUtf8CV = stringUtf8CV('hello 🌾'); -// { type: ClarityType.StringUTF8, data: 'hello 🌾' } -``` - -Clarity supports both ascii and utf8 strings. - -### Principals - -```typescript -const address = 'SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B'; -const contractName = 'contract-name'; - -const spCV = standardPrincipalCV(address); -// { -// type: ClarityType.PrincipalStandard -// address: { -// type: StacksMessageType.Address, -// version: AddressVersion.MainnetSingleSig, -// hash160: "SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B" -// } -// } - -const cpCV = contractPrincipalCV(address, contractName); -// { -// type: ClarityType.PrincipalContract, -// contractName: { -// type: StacksMessageType.LengthPrefixedString, -// content: 'contract-name', -// lengthPrefixBytes: 1, -// maxLengthBytes: 128, -// }, -// address: { -// type: StacksMessageType.Address, -// version: AddressVersion.MainnetSingleSig, -// hash160: "SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B" -// } -// } -``` - -Both kinds of Clarity principal values contain `type` information and an `address` object. Contract principals also contain a `contractName`. - -### Response Values - -```typescript -const errCV = responseErrorCV(trueCV()); -// { type: ResponseErr, value: { type: ClarityType.BoolTrue } } - -const okCV = responseOkCV(falseCV()); -// { type: ResponseOk, value: { type: ClarityType.BoolFalse } } -``` - -Response Clarity Values will either have the type `ClarityType.ResponseOk` or `ClarityType.ResponseErr`. They both contain a Clarity Value. Often this value will be an integer error code if the response is an `Error`. - -### Tuples - -```typescript -const tupCV = tupleCV({ - a: intCV(1), - b: trueCV(), - c: falseCV(), -}); -// { -// type: ClarityType.Tuple, -// data: { -// a: { type: ClarityType.Int, value: BN { ... } }, -// b: { type: ClarityType.BoolTrue }, -// c: { type: ClarityType.BoolFalse }, -// } -// } - -console.log(tupCV.data['b']); -// { type: ClarityType.BoolTrue } -``` - -Tuples in Clarity are typed and contain named fields. The tuple above, for example, contains three fields with the names **a**, **b** and **c**, and the types of their values are `Int`, `Boolean` and `Boolean`, respectively. - -Clarity tuples are represented in JavaScript as objects and a tuple's data can be accessed by its `data` field, where the underlying JS object is stored. - -### Lists - -```typescript -const l = listCV([trueCV(), falseCV()]); -// { type: ClarityType.List, list: [{ type: ClarityType.BoolTrue }] } - -console.log(l.list[0]); -// { type: ClarityType.BoolTrue } -``` - -Lists, in Clarity, are homogeneous, meaning they can only contain elements of a singular (Clarity) type. Make sure to avoid constructing lists that have elements of multiple types. - -A Clarity lists underlying data can be accessed via its `list` field. - -## Using Clarity Values - -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](../understand-stacks/transactions#construction). - -## Utilizing Clarity Values from Transaction Responses - -`Read-only` Clarity functions can return Clarity values as a response. These `read-only` functions can be accessed easily in JavaScript via the [`callReadOnlyFunction()`](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions#calling-read-only-contract-function) function included in `@stacks/transactions`, which returns a `ClarityValue`. - -As mentioned above, `ClarityValues` are simply javascript objects containing a value and its associated Clarity type information. These object types are defined [here](https://github.com/hirosystems/stacks.js/tree/1f2b5fd8bdf1c2b5866e8171163594d7708a8c7a/packages/transactions/src/clarity/types). - -When you are calling a `read-only` contract function, you will always know what type the function will return, since functions in Clarity are strongly typed. - -It is common for Clarity functions to return values wrapped in a `Response`, in order to indicate if there was success or an error. - -Since every `ClarityValue` has a `type` field, the type of the result of a `read-only` function call can be checked and acted upon like so: - -```typescript -const contractAddress = 'ST3KC0MTNW34S1ZXD36JYKFD3JJMWA01M55DSJ4JE'; -const contractName = 'kv-store'; -const functionName = 'get-value'; -const buffer = bufferCVFromString('foo'); -const network = new StacksTestnet(); // for mainnet, use `StacksMainnet()` -const senderAddress = 'ST2F4BK4GZH6YFBNHYDDGN4T1RKBA7DA1BJZPJEJJ'; - -const options = { - contractAddress, - contractName, - functionName, - functionArgs: [buffer], - network, - senderAddress, -}; - -// make a read-only call to a contract function that -// returns a Response -const result: ResponseCV = await callReadOnlyFunction(options); - -if (result.type === ClarityType.ResponseOk) { - console.log(cvToString(result.value)); -} else if (result.type === ClarityType.ResponseErr) { - throw new Error(`kv-store contract error: ${result.value.data}`); -} -``` - -### ClarityValues to/from Hex - -If you receive a response from a transaction in the form of a `hex` string, you can deserialize it into a Clarity value like so: - -```javascript -import { hexToCV } from '@stacks/transactions'; - -let cv = hexToCV('hex_string'); -``` - -Similarly, you can convert a Clarity value to `hex` string like so: - -```javascript -import { cvToHex, trueCV } from '@stacks/transactions'; - -let trueHex = cvToHex(trueCV()); -``` - -## Debugging Clarity Values - -Sometimes you might receive a Clarity value that you were not expecting. Logging the value to your console won't always prove to be useful, unless you have memorized the Clarity value type enum values. - -In order to figure out what kind of value you are dealing with, you can use the `cvToString()` function to convert the Clarity value to a more easily readable string. - -For example, calling `cvToString()` on a large `tuple` might yield something like: - -``` -(tuple - (a -1) - (b u1) - (c 0x74657374) - (d true) - (e (some true)) - (f none) - (g SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B) - (h SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B.test) - (i (ok true)) - (j (err false)) - (k (list true false)) - (l (tuple (a true) (b false))) - (m "hello world") - (n u"hello \u{1234}"))` -``` diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/blockchain/index.md b/i18n/tr/docusaurus-plugin-content-docs/current/blockchain/index.md deleted file mode 100644 index 13db24ec30..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/blockchain/index.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: Blockchain -description: Stacks Blockchain -sidebar_position: 6 ---- - -Below is a guide to start working locally with the Stacks Blockchain. - -Code repository is [here](https://github.com/stacks-network/stacks-blockchain). - -## Getting started with the Stacks Blockchain - -### Download and build stacks-blockchain - -The first step is to ensure that you have Rust and the support software installed. - -```bash -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -``` - -:::info -For building on Windows, follow the rustup installer instructions at https://rustup.rs/ -::: - -From there, you can clone the Stacks Blockchain repository: - -```bash -git clone --depth=1 https://github.com/stacks-network/stacks-blockchain.git - -cd stacks-blockchain -``` - -Then build the project: - -```bash -cargo build -``` - -Run the tests: - -```bash -cargo test testnet -- --test-threads=1 -``` - -### Encode and sign transactions - -Here, we have generated a keypair that will be used for signing the upcoming transactions: - -```bash -cargo run --bin blockstack-cli generate-sk --testnet - -# Output -# { -# secretKey: "b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001", -# publicKey: "02781d2d3a545afdb7f6013a8241b9e400475397516a0d0f76863c6742210539b5", -# stacksAddress: "ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH" -# } -``` - -This keypair is already registered in the `testnet-follower-conf.toml` file, so it can be used as presented here. - -We will interact with the following simple contract `kv-store`. In our examples, we will assume this contract is saved to `./kv-store.clar`: - -```scheme -(define-map store { key: (string-ascii 32) } { value: (string-ascii 32) }) - -(define-public (get-value (key (string-ascii 32))) - (match (map-get? store { key: key }) - entry (ok (get value entry)) - (err 0))) - -(define-public (set-value (key (string-ascii 32)) (value (string-ascii 32))) - (begin - (map-set store { key: key } { value: value }) - (ok true))) -``` - -We want to publish this contract on chain, then issue some transactions that interact with it by setting some keys and getting some values, so we can observe read and writes. - -Our first step is to generate and sign, using your private key, the transaction that will publish the contract `kv-store`. To do that, we will use the subcommand `blockstack-cli` that has the following usage: - -```bash -blockstack-cli (options) publish [publisher-secret-key-hex] [fee-rate] [nonce] [contract-name] [file-name.clar] -``` - -With the following arguments: - -```bash -cargo run --bin blockstack-cli publish b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 515 0 kv-store ./kv-store.clar --testnet -``` - -The `515` is the transaction fee, denominated in microSTX. Right now, the testnet requires one microSTX per byte minimum, and this transaction should be less than 515 bytes. The third argument `0` is a nonce, that must be increased monotonically with each new transaction. - -This command will output the **binary format** of the transaction. In our case, we want to pipe this output and dump it to a file that will be used later in this tutorial. - -```bash -cargo run --bin blockstack-cli publish b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 515 0 kv-store ./kv-store.clar --testnet | xxd -r -p > tx1.bin -``` - -### Run the testnet - -You can observe the state machine in action locally by running: - -```bash -cargo stacks-node start --config=./testnet/stacks-node/conf/testnet-follower-conf.toml -``` - -`testnet-follower-conf.toml` is a configuration file that you can use for setting genesis balances or configuring Event observers. You can grant an address an initial account balance by adding the following entries: - -``` -[[ustx_balance]] -address = "ST2VHM28V9E5QCRD6C73215KAPSBKQGPWTEE5CMQT" -amount = 100000000 -``` - -The `address` field is the Stacks testnet address, and the `amount` field is the number of microSTX to grant to it in the genesis block. The addresses of the private keys used in the tutorial below are already added. - -### Publish your contract - -Assuming that the testnet is running, we can publish our `kv-store` contract. - -In another terminal (or file explorer), you can move the `tx1.bin` generated earlier, to the mempool: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx1.bin http://localhost:20443/v2/transactions -``` - -In the terminal window running the testnet, you can observe the state machine's reactions. - -### Reading from / Writing to the contract - -Now that our contract has been published on chain, let's try to submit some read / write transactions. We will start by trying to read the value associated with the key `foo`. - -To do that, we will use the subcommand: - -```bash -cargo run --bin blockstack-cli contract-call --help -``` - -With the following arguments: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 1 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store get-value -e \"foo\" --testnet | xxd -r -p > tx2.bin -``` - -`contract-call` generates and signs a contract-call transaction. - -We can submit the transaction by moving it to the mempool path: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx2.bin http://localhost:20443/v2/transactions -``` - -Similarly, we can generate a transaction that would be setting the key `foo` to the value `bar`: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 2 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store set-value -e \"foo\" -e \"bar\" --testnet | xxd -r -p > tx3.bin -``` - -And submit it by moving it to the mempool path: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx3.bin http://localhost:20443/v2/transactions -``` - -Finally, we can issue a third transaction, reading the key `foo` again, for ensuring that the previous transaction has successfully updated the state machine: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 3 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store get-value -e \"foo\" --testnet | xxd -r -p > tx4.bin -``` - -And submit this last transaction by moving it to the mempool path: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx4.bin http://localhost:20443/v2/transactions -``` - -Congratulations, you can now [write your own smart contracts with Clarity](write-smart-contracts/). diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/blockchain/networks.md b/i18n/tr/docusaurus-plugin-content-docs/current/blockchain/networks.md deleted file mode 100644 index fe9725352c..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/blockchain/networks.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Stacks Blockchain Networks -description: Stacks Blockchain Networks -sidebar_position: 3 ---- - -### Stacks Blockchain Networks - -- [x] **Krypton** is a Stacks 2 testnet with a fixed, two-minute block time, called `regtest`. Regtest is generally unstable for regular use, and is reset often. See the [regtest documentation](understand-stacks/testnet) for more information on using regtest. - -- [x] **Testnet** (old Xenon) is the Stacks 2 public testnet, which runs PoX against the Bitcoin testnet. It is the full implementation of the Stacks 2 blockchain, and should be considered a stable testnet for developing Clarity smart contracts. See the [testnet documentation](understand-stacks/testnet) for more information on the public testnet. - -- [x] **Mainnet** is the fully functional Stacks 2 blockchain, see the [Stacks overview](understand-stacks/) for information on running a Stacks node, mining, stacking, and writing Clarity smart contracts. diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md b/i18n/tr/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md deleted file mode 100644 index cf4f84a2da..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Stacks Blockchain API -description: Interacting with the Stacks 2.0 Blockchain via API -sidebar_position: 4 ---- - -## Introduction - -:::tip API Documentation Official API Documentation is available [here](https://stacks-network.github.io/stacks-blockchain/). ::: - - -The Stacks 2.0 Blockchain API allows you to query the Stacks 2.0 blockchain and interact with smart contracts. It was built to maintain pageable materialized views of the Stacks 2.0 Blockchain. - -:::caution The RESTful API is developed by Hiro. Hiro also hosts a public API node for easy onboarding. Using it requires you to trust the hosted server, but provides a faster onboarding experience. You can [run your own API server](https://docs.hiro.so/get-started/running-api-node) ::: - -The RESTful JSON API can be used without any authorization. The basepath for the API is: - -```bash -# for mainnet, replace `testnet` with `mainnet` -https://stacks-node-api.testnet.stacks.co/ -``` - -:::note This documentation only covers endpoints that are exposed on a Stacks node, referred to as the RPC API. For full documentation on the RESTful API, check out the [Hiro's API reference](https://docs.hiro.so/api). ::: - -### Stacks Node RPC API - -The [stacks-node implementation](https://github.com/stacks-network/stacks-blockchain/) exposes JSON RPC endpoints. - -All `/v2/` routes a proxied to a Hiro-hosted Stacks Node. For a trustless architecture, you should make these requests to a self-hosted node. - -## Proxied Stacks Node RPC API endpoints - -The Stacks 2.0 Blockchain API is centrally hosted. However, every running Stacks node exposes an RPC API, which allows you to interact with the underlying blockchain. Instead of using a centrally hosted API, you can directly access the RPC API of a locally hosted Node. - -:::tip -The Stacks Blockchain API proxies to Node RPC endpoints -::: - -While the Node RPC API doesn't give the same functionality as the hosted Stacks 2.0 Blockchain API, you get similar functionality in a way that is scoped to that specific node. The RPC API includes the following endpoints: - -- [POST /v2/transactions](https://docs.hiro.so/api#operation/post_core_node_transactions) -- [GET /v2/contracts/interface/{contract_address}/{contract_name}](https://docs.hiro.so/api#operation/get_contract_interface) -- [POST /v2/map_entry/{contract_address}/{contract_name}/{map_name}](https://docs.hiro.so/api#operation/get_contract_data_map_entry) -- [GET /v2/contracts/source/{contract_address}/{contract_name}](https://docs.hiro.so/api#operation/get_contract_source) -- [GET /v2/accounts/{principal}](https://docs.hiro.so/api#operation/get_account_info) -- [POST /v2/contracts/call-read/{contract_address}/{contract_name}/{function_name}](https://docs.hiro.so/api#operation/call_read_only_function) -- [GET /v2/fees/transfer](https://docs.hiro.so/api#operation/get_fee_transfer) -- [GET /v2/info](https://docs.hiro.so/api#operation/get_core_api_info) - -:::caution If you run a local node, it exposes an HTTP server on port `20443`. The info endpoint would be `localhost:20443/v2/info`. ::: diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md b/i18n/tr/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md deleted file mode 100644 index 71e3542302..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Stacks Releases -description: Stacks Blockchain Releases -sidebar_position: 2 ---- - -:::info -This page needs contributions. Help us improve it. -::: - -### Stacks Blockchain Releases - -All releases are published [here](https://github.com/stacks-network/stacks-blockchain/releases). Most important ones are described below. - -### Stacks 2.1 - -Scheduled for release at the end of 2022. - -More information on [what to expect with Stacks 2.1](https://stacks.org/stacks-21-what-to-expect). - -#### Stacks 2.05 -Activated on [Bitcoin block 713000](https://explorer.stacks.co/txid/0xece8e369310b5ff9b92ef11181ae0d2457ac0c821376d4a96c4998763e22ad04?chain=mainnet). - -This breaking change enables storage cost for list to be based on actual length and change in number of indexed I/O operations. More info on this [blog post](https://www.stacks.org/stacks-2-05?ref=docs-website). - -#### Stacks 2.0 -Activated on January 14th 2021 - -This hard fork enables Stacking, Clarity smart contracts, scalable transactions, and also building directly on Bitcoin. More info [here](https://forum.stacks.org/t/path-to-mainnet-for-stx-holders-things-to-know-ahead-of-stacks-2-0/11529). - -#### Stacks Genesis -Released on 2018, October 30th UTC+6 at Bitcoin block height 547921 - -This hard fork addresses registration of digital assets with Stacks token and also distribution of Stacks token to the existing purchasers. More info [here](https://blog.blockstack.org/the-launch-of-the-stacks-genesis-block/?ref=docs-website). - diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md b/i18n/tr/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md deleted file mode 100644 index 25ec969824..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Deploy tips -description: Learn some common methods for deploying your application. ---- - -## Introduction - -Stacks applications are web applications that authenticate users with Stacks Auth and store data with Gaia. Both of these technologies can be accessed on the client side. As such, Stacks apps tend to be simple in design and operation, since in many cases, they don’t have to host anything besides the application’s assets. - -## Where to deploy your application - -Before users can interact with your application, you must deploy it on a server that is accessible over the internet. Deploying requires that you: - -- Configure or customize the files in the `public` directory. -- Build your application site for deployment. -- Copy your generated application files to your production server. - -If you first populated your application with the Stacks application generator, your application contains the starting blocks for configuring, building, and deploying your app. For example, the React template builds out a scaffolding with the following building blocks. - -| File or Directory | Description | -| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| node_modules/react-scripts | A set of scripts for that helps you kick off React projects without configuring, so you do not have to set up your project by yourself. | -| package.json | Contains a scripts section that includes a reference to the react-scripts, which are a dependency. This script creates a build directory containing your files for deployment. | -| public/favicon.ico | An example shortcut icon. | -| public/index.html | An entry page for an application. | -| public/manifest.json | A JSON file that describes your web application to the browser. | -| cors | Contains example deployment files for cross-origin request configuration. | - -If you use the generator to build JavasScript or Vue scaffolding, your project configuration files will be different. - -Regardless of which scaffolding you use, you must customize and extend this basic scaffolding as needed by your application. For example, you may want to add more properties to the `manifest.json` file. Since every application is different, Stacks Auth cannot give you specific instructions on how to do this. The steps you take are specific to your application. - -## Stacks Authentication and deployment - -When your application authenticates users with Stacks, the Stacks Wallet at on URL requests a resource (the app manifest) from your DApp. A request for a resource outside of the origin (the Stacks Wallet) 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 (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) - -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 Stacks 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`: - -```html -Access-Control-Allow-Origin: * Access-Control-Allow-Headers: "X-Requested-With, Content-Type, -Origin, Authorization, Accept, Client-Security-Token, Accept-Encoding" Access-Control-Allow-Methods: -"POST, GET, OPTIONS, DELETE, PUT" -``` - -Consult the documentation for your hosting service to learn how to configure CORS on that service. - -## Deployment and Radiks - -If you are deploying a Stacks application that uses [Radiks](https://github.com/stacks-network/radiks), your deployment includes a server and a database component. You must take this into account when deploying your application. You may want to choose a service such as [Heroku](https://www.heroku.com) or [Digital Ocean](https://www.digitalocean.com) if your app uses Radiks. diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/build-apps/index.md b/i18n/tr/docusaurus-plugin-content-docs/current/build-apps/index.md deleted file mode 100644 index 23714cba5d..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/build-apps/index.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Build apps with Stacks -description: Authenticate users, sign transactions and store data with the Stacks blockchain -sidebar_position: 3 -sidebar_label: Build apps ---- - -## Introduction - -Apps built with the Stacks blockchain give users control over their digital identities, assets, and data. - -Unlike most cloud-based apps, they are "decentralized" since they don't depend on any centralized platform, server, or database to function. Rather, they use the Stacks blockchain to authenticate users and facilitate read and write requests for them without any single point of failure or trust. - -Stacks provides three main functions for building apps: - - - -- **Authentication**: Register and sign users in with identities on the Stacks blockchain -- **Transaction signing**: Prompt users to sign and broadcast transactions to the Stacks blockchain -- **Data storage**: Save and retrieve data for users with [Gaia](../gaia) - - -All three of these integrations can be used together to create powerful new user experiences that rival or exceed those of traditional apps—all while protecting your users' digital rights. - -While integration is possible for any type of app, most of the resources available here are for web developers experienced with JavaScript. See [Hiro developer docs](https://docs.hiro.so) for more information on the available app development libraries for Stacks. - -## [References](references) - -[Authentication](references/authentication) - -[BNS](references/bns) - -[Gaia](../gaia/) - diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md b/i18n/tr/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md deleted file mode 100644 index 727b4e2163..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: NoCodeClarity -description: Launch apps for the Stacks blockchain through no code platforms like Bubble. ---- - -## Introduction - -![](https://d1muf25xaso8hp.cloudfront.net/https%3A%2F%2Fs3.amazonaws.com%2Fappforest_uf%2Ff1653407713550x759333524803365600%2FLogo%2520of%2520NoCodeClarity.png?w=179&h=84&auto=compress&dpr=1&fit=max) - -[NoCodeClarity](https://nocodeclarity.com) allows people to create applications for the Stacks blockchain without coding. - -## Stacks Plug-In on bubble - -The [Stacks-No-Code-Plugin](https://bubble.io/plugin/the-stacks-plug-in-1645467277638x949839693014368300) released in May 2022 and it can easily be installed on Bubble with a few clicks allowing users to deploy applications with no coding knowledge. [Bubble](https://bubble.io/blog/explaining-bubble-to-investors/) is the first No Code platform that the Stacks plugin launched on. More platforms are in the roadmap of NoCodeClarity, founded by Christopher Perceptions and Sergio Gongora. The Stacks plugin was created through the support of the Stacks Foundation via a grant in January 2022 and NoCodeClarity was awarded a $100,000 grant in June 2022 to expand the roadmap. - -Additional [instructions](https://s3.amazonaws.com/appforest_uf/f1654202471526x991633667675927800/Instructions%20v2.docx.pdf) are also available. Tutorials and step by step guides will be released soon. - -The Stacks-No-Code-Plugin code is [publicly available on Github](https://github.com/nocodeclarity/Stacks-No-Code-Plugin). - -![](/img/bubble-stacks-plugin.png) - -## Demo page - -A demo page is available [here](https://test-stacks-plugin.bubbleapps.io/version-test). - -## NoCodeClarity videos - -NodeCodeClarity has their own [youtube channel](https://www.youtube.com/channel/UC9Ep0VQ-GQ-yDzt-wmIElRA). - -Videos: - -* [NoCodeClarity Setup](https://www.youtube.com/watch?v=WanXlpBGl0w) -* [NoCodeClarity - Part 1 of the plugin](https://www.youtube.com/watch?v=o6d3hrzNqVI&t=248s) -* [NoCodeClarity - Part 2 of the plugin](https://www.youtube.com/watch?v=0rzMdsrRg80) -* [Sneak Peek of the No Code Stacks Wallet Template](https://www.youtube.com/watch?v=Xe6Yv0rF6XM) \ No newline at end of file diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md b/i18n/tr/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md deleted file mode 100644 index 86a8568663..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Authentication -description: Register and sign in users with identities on the Stacks blockchain ---- - -## Introduction - -This guide explains how authentication is performed on the Stacks blockchain. - -Authentication provides a way for users to identify themselves to an app while retaining complete control over their credentials and personal details. It can be integrated alone or used in conjunction with [transaction signing](https://docs.hiro.so/get-started/transactions#signature-and-verification) and [data storage](https://docs.stacks.co/build-apps/references/gaia), for which it is a prerequisite. - -Users who register for your app can subsequently authenticate to any other app with support for the [Blockchain Naming System](bns) and vice versa. - -## How it works - -The authentication flow with Stacks is similar to the typical client-server flow used by centralized sign in services (for example, OAuth). However, with Stacks the authentication flow happens entirely client-side. - -An app and authenticator, such as [the Stacks Wallet](https://www.hiro.so/wallet/install-web), communicate during the authentication flow by passing back and forth two tokens. The requesting app sends the authenticator an `authRequest` token. Once a user approves authentication, the authenticator responds to the app with an `authResponse` token. - -These tokens are are based on [a JSON Web Token (JWT) standard](https://tools.ietf.org/html/rfc7519) with additional support for the `secp256k1` curve used by Bitcoin and many other cryptocurrencies. They are passed via URL query strings. - -When a user chooses to authenticate an app, it sends the `authRequest` token to the authenticator via a URL query string with an equally named parameter: - -`https://wallet.hiro.so/...?authRequest=j902120cn829n1jnvoa...` - -When the authenticator receives the request, it generates an `authResponse` token for the app using an _ephemeral transit key_ . The ephemeral transit key is just used for the particular instance of the app, in this case, to sign the `authRequest`. - -The app stores the ephemeral transit key during request generation. The public portion of the transit key is passed in the `authRequest` token. The authenticator uses the public portion of the key to encrypt an _app private key_ which is returned via the `authResponse`. - -The authenticator generates the app private key from the user's _identity address private key_ and the app's domain. The app private key serves three functions: - -1. It is used to create credentials that give the app access to a storage bucket in the user's Gaia hub -2. It is used in the end-to-end encryption of files stored for the app in the user's Gaia storage. -3. It serves as a cryptographic secret that apps can use to perform other cryptographic functions. - -Finally, the app private key is deterministic, meaning that the same private key will always be generated for a given Stacks address and domain. - -The first two of these functions are particularly relevant to [data storage with Stacks.js](https://docs.stacks.co/docs/gaia). - -## Key pairs - -Authentication with Stacks makes extensive use of public key cryptography generally and ECDSA with the `secp256k1` curve in particular. - -The following sections describe the three public-private key pairs used, including how they're generated, where they're used and to whom private keys are disclosed. - -### Transit private key - -The transit private is an ephemeral key that is used to encrypt secrets that need to be passed from the authenticator to the app during the authentication process. It is randomly generated by the app at the beginning of the authentication response. - -The public key that corresponds to the transit private key is stored in a single element array in the `public_keys` key of the authentication request token. The authenticator encrypts secret data such as the app private key using this public key and sends it back to the app when the user signs in to the app. The transit private key signs the app authentication request. - -### Identity address private key - -The identity address private key is derived from the user's keychain phrase and is the private key of the Stacks username that the user chooses to use to sign in to the app. It is a secret owned by the user and never leaves the user's instance of the authenticator. - -This private key signs the authentication response token for an app to indicate that the user approves sign in to that app. - -### App private key - -The app private key is an app-specific private key that is generated from the user's identity address private key using the `domain_name` as input. - -The app private key is securely shared with the app on each authentication, encrypted by the authenticator with the transit public key. Because the transit key is only stored on the client side, this prevents a man-in-the-middle attack where a server or internet provider could potentially snoop on the app private key. diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/build-apps/references/bns.md b/i18n/tr/docusaurus-plugin-content-docs/current/build-apps/references/bns.md deleted file mode 100644 index 32b045dc83..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/build-apps/references/bns.md +++ /dev/null @@ -1,241 +0,0 @@ ---- -title: Blockchain Naming System -description: Binds Stacks usernames to off-chain state ---- - -Blockchain Naming System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of control. - -The Stacks V1 blockchain implemented BNS through first-order name operations. In Stacks V2, BNS is instead implemented through a smart-contract loaded during the genesis block. - -Names in BNS have three properties: - -- **Names are globally unique.** The protocol does not allow name collisions, and all well-behaved nodes resolve a given name to the same state. -- **Names are human-meaningful.** Each name is chosen by its creator. -- **Names are strongly owned.** Only the name's owner can change the state it resolves to. Specifically, a name is owned by one or more ECDSA private keys. - -The Stacks blockchain insures that each node's BNS view is synchronized to all of the other nodes in the world, so queries on one node will be the same on other nodes. Stacks blockchain nodes allow a name's owner to bind up to 40Kb of off-chain state to their name, which will be replicated to all other Stacks blockchain nodes via a P2P network. - -The biggest consequence for developers is that in BNS, reading name state is fast and cheap but writing name state is slow and expensive. This is because registering and modifying names requires one or more transactions to be sent to the underlying blockchain, and BNS nodes will not process them until they are sufficiently confirmed. Users and developers need to acquire and spend the requisite cryptocurrency (STX) to send BNS transactions. - -## Motivation behind naming systems - -We rely on naming systems in everyday life, and they play a critical role in many different applications. For example, when you look up a friend on social media, you are using the platform's naming system to resolve their name to their profile. When you look up a website, you are using the Domain Name Service to resolve the hostname to its host's IP address. When you check out a Git branch, you are using your Git client to resolve the branch name to a commit hash. When you look up someone's PGP key on a keyserver, you are resolving their key ID to their public key. - -What kinds of things do we want to be true about names? In BNS, names are globally unique, names are human-meaningful, and names are strongly owned. However, if you look at these examples, you'll see that each of them only guarantees _two_ of these properties. This limits how useful they can be. - -- In DNS and social media, names are globally unique and human-readable, but not strongly owned. The system operator has the final say as to what each names resolves to. - - - **Problem**: Clients must trust the system to make the right choice in what a given name resolves to. This includes trusting that no one but the system administrators can make these changes. - -- In Git, branch names are human-meaningful and strongly owned, but not globally unique. Two different Git nodes may resolve the same branch name to different unrelated repository states. - - - **Problem**: Since names can refer to conflicting state, developers have to figure out some other mechanism to resolve ambiguities. In Git's case, the user has to manually intervene. - -- In PGP, names are key IDs. They are are globally unique and cryptographically owned, but not human-readable. PGP key IDs are derived from the keys they reference. - - **Problem**: These names are difficult for most users to remember since they do not carry semantic information relating to their use in the system. - -BNS names have all three properties, and none of these problems. This makes it a powerful tool for building all kinds of network applications. With BNS, we can do the following and more: - -- Build domain name services where hostnames can't be hijacked. -- Build social media platforms where user names can't be stolen by phishers. -- Build version control systems where repository branches do not conflict. -- Build public-key infrastructure where it's easy for users to discover and remember each other's keys. - -## Organization of BNS - -BNS names are organized into a global name hierarchy. There are three different layers in this hierarchy related to naming: - -- **Namespaces**. These are the top-level names in the hierarchy. An analogy to BNS namespaces are DNS top-level domains. Existing BNS namespaces include `.id`, `.podcast`, and `.helloworld`. All other names belong to exactly one namespace. Anyone can create a namespace, but in order for the namespace to be persisted, it must be _launched_ so that anyone can register names in it. Namespaces are not owned by their creators. - -- **BNS names**. These are names whose records are stored directly on the blockchain. The ownership and state of these names are controlled by sending blockchain transactions. Example names include `verified.podcast` and `muneeb.id`. Anyone can create a BNS name, as long as the namespace that contains it exists already. - -- **BNS subdomains**. These are names whose records are stored off-chain, but are collectively anchored to the blockchain. The ownership and state for these names lives within the P2P network data. While BNS subdomains are owned by separate private keys, a BNS name owner must broadcast their subdomain state. Example subdomains include `jude.personal.id` and `podsaveamerica.verified.podcast`. Unlike BNS namespaces and names, the state of BNS subdomains is _not_ part of the blockchain consensus rules. - -A feature comparison matrix summarizing the similarities and differences between these name objects is presented below: - -| Feature | **Namespaces** | **BNS names** | **BNS Subdomains** | -| -------------------------------------- | -------------- | ------------- | ------------------ | -| Globally unique | X | X | X | -| Human-meaningful | X | X | X | -| Owned by a private key | | X | X | -| Anyone can create | X | X | [1] | -| Owner can update | | X | [1] | -| State hosted on-chain | X | X | | -| State hosted off-chain | | X | X | -| Behavior controlled by consensus rules | X | X | | -| May have an expiration date | | X | | - -[1] Requires the cooperation of a BNS name owner to broadcast its transactions - -## Namespaces - -Namespaces are the top-level naming objects in BNS. - -They control a few properties about the names within them: - -- How expensive they are to register -- How long they last before they have to be renewed -- Who (if anyone) receives the name registration fees -- Who is allowed to seed the namespace with its initial names. - -At the time of this writing, by far the largest BNS namespace is the `.id` namespace. Names in the `.id` namespace are meant for resolving user identities. Short names in `.id` are more expensive than long names, and have to be renewed by their owners every two years. Name registration fees are not paid to anyone in particular---they are instead sent to a "black hole" where they are rendered unspendable (the intention is to discourage ID squatters). - -Unlike DNS, _anyone_ can create a namespace and set its properties. Namespaces are created on a first-come first-serve basis, and once created, they last 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 (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`). - -Namespaces can be between 1 and 19 characters long, and are composed of the characters `a-z`, `0-9`, `-`, and `_`. - -## Subdomains - -BNS names are strongly owned because the owner of its private key can generate valid transactions that update its zone file hash and owner. However, this comes at the cost of requiring a name owner to pay for the underlying transaction in the blockchain. Moreover, this approach limits the rate of BNS name registrations and operations to the underlying blockchain's transaction bandwidth. - -BNS overcomes this with subdomains. A **BNS subdomain** is a type of BNS name whose state and owner are stored outside of the blockchain, but whose existence and operation history are anchored to the blockchain. Like their on-chain counterparts, subdomains are globally unique, strongly owned, and human-readable. BNS gives them their own name state and public keys. Unlike on-chain names, subdomains can be created and managed cheaply, because they are broadcast to the BNS network in batches. A single blockchain transaction can send up to 120 subdomain operations. - -This is achieved by storing subdomain records in the BNS name zone files. An on-chain name owner broadcasts subdomain operations by encoding them as `TXT` records within a DNS zone file. To broadcast the zone file, the name owner sets the new zone file hash with a `NAME_UPDATE` transaction and replicates the zone file. This, in turn, replicates all subdomain operations it contains, and anchors the set of subdomain operations to an on-chain transaction. The BNS node's consensus rules ensure that only valid subdomain operations from _valid_ `NAME_UPDATE` transactions will ever be stored. - -For example, the name `verified.podcast` once wrote the zone file hash `247121450ca0e9af45e85a82e61cd525cd7ba023`, which is the hash of the following zone file: - -```bash -$TTL 3600 -1yeardaily TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxeWVhcmRhaWx5CiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMXllYXJkYWlseS9oZWFkLmpzb24iCg==" -2dopequeens TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAyZG9wZXF1ZWVucwokVFRMIDM2MDAKX2h0dHAuX3RjcCBVUkkgMTAgMSAiaHR0cHM6Ly9waC5kb3Rwb2RjYXN0LmNvLzJkb3BlcXVlZW5zL2hlYWQuanNvbiIK" -10happier TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxMGhhcHBpZXIKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8xMGhhcHBpZXIvaGVhZC5qc29uIgo=" -31thoughts TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzMXRob3VnaHRzCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzF0aG91Z2h0cy9oZWFkLmpzb24iCg==" -359 TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzNTkKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8zNTkvaGVhZC5qc29uIgo=" -30for30 TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzMGZvcjMwCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzBmb3IzMC9oZWFkLmpzb24iCg==" -onea TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiBvbmVhCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vb25lYS9oZWFkLmpzb24iCg==" -10minuteteacher TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxMG1pbnV0ZXRlYWNoZXIKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8xMG1pbnV0ZXRlYWNoZXIvaGVhZC5qc29uIgo=" -36questionsthepodcastmusical TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzNnF1ZXN0aW9uc3RoZXBvZGNhc3RtdXNpY2FsCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzZxdWVzdGlvbnN0aGVwb2RjYXN0bXVzaWNhbC9oZWFkLmpzb24iCg==" -_http._tcp URI 10 1 "https://dotpodcast.co/" -``` - -Each `TXT` record in this zone file encodes a subdomain-creation. For example, `1yeardaily.verified.podcast` resolves to: - -```json -{ - "address": "1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH", - "blockchain": "bitcoin", - "last_txid": "d87a22ebab3455b7399bfef8a41791935f94bc97aee55967edd5a87f22cce339", - "status": "registered_subdomain", - "zonefile_hash": "e7acc97fd42c48ed94fd4d41f674eddbee5557e3", - "zonefile_txt": "$ORIGIN 1yeardaily\n$TTL 3600\n_http._tcp URI 10 1 \"https://ph.dotpodcast.co/1yeardaily/head.json\"\n" -} -``` - -This information was extracted from the `1yeardaily` `TXT` resource record in the zone file for `verified.podcast`. - -### Subdomain Lifecycle - -Note that `1yeardaily.verified.podcast` has a different public key hash (address) than `verified.podcast`. A BNS node will only process a subsequent subdomain operation on `1yeardaily.verified.podcast` if it includes a signature from this address's private key. `verified.podcast` cannot generate updates; only the owner of `1yeardaily.verified.podcast can do so`. - -The lifecycle of a subdomain and its operations is shown in Figure 2. - -``` - subdomain subdomain subdomain - creation update transfer -+----------------+ +----------------+ +----------------+ -| cicero | | cicero | | cicero | -| owner="1Et..." | signed | owner="1Et..." | signed | owner="1cJ..." | -| zf0="7e4..." |<--------| zf0="111..." |<--------| zf0="111..." |<---- ... -| seqn=0 | | seqn=1 | | seqn=2 | -| | | sig="xxxx" | | sig="xxxx" | -+----------------+ +----------------+ +----------------+ - | | | - | off-chain | | -~ ~ ~ ~ | ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~|~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ | ~ ~ ~ ~ ~ ~ ~ ... - | on-chain | | - V V (zone file hash ) V -+----------------+ +----------------+ +----------------+ -| res_publica.id | | jude.id | | res_publica.id | -| NAME_UPDATE |<--------| NAME_UPDATE |<--------| NAME_UPDATE |<---- ... -+----------------+ +----------------+ +----------------+ - blockchain blockchain blockchain - block block block - - -Figure 2: Subdomain lifetime with respect to on-chain name operations .A new -subdomain operation will only be accepted if it has a later "sequence=" number, -and a valid signature in "sig=" over the transaction body .The "sig=" field -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." -However, any on-chain name ("jude.id" in this case) can broadcast a subdomain -update for "cicero.res_publica.id." -``` - -Subdomain operations are ordered by sequence number, starting at 0. Each new subdomain operation must include: - -- The next sequence number -- The public key that hashes to the previous subdomain transaction's address -- A signature from the corresponding private key over the entire subdomain operation. - -If two correctly signed but conflicting subdomain operations are discovered (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 subdomain's operations will be able to determine the valid sequence of state-transitions it has undergone, and determine the current zone file and public key hash for the subdomain. - -### Subdomain Creation and Management - -Unlike an on-chain name, a subdomain owner needs an on-chain name owner's help to broadcast their subdomain operations. In particular: - -- A subdomain-creation transaction can only be processed by the owner of the on-chain name that shares its suffix. For example, only the owner of `res_publica.id` can broadcast subdomain-creation transactions for subdomain names ending in `.res_publica.id`. -- A subdomain-transfer transaction can only be broadcast by the owner of the on-chain name that created it. For example, the owner of `cicero.res_publica.id` needs the owner of `res_publica.id` to broadcast a subdomain-transfer transaction to change `cicero.res_publica.id`'s public key. -- In order to send a subdomain-creation or subdomain-transfer, all of an on-chain name owner's zone files must be present in the Atlas network. This lets the BNS node prove the _absence_ of any conflicting subdomain-creation and subdomain-transfer operations when processing new zone files. -- A subdomain update transaction can be broadcast by _any_ on-chain name owner, but the subdomain owner needs to find one who will cooperate. For example, the owner of `verified.podcast` can broadcast a subdomain-update transaction created by the owner of `cicero.res_publica.id`. - -That said, to create a subdomain, the subdomain owner generates a subdomain-creation operation for their desired name and gives it to the on-chain name owner. - -Once created, a subdomain owner can use any on-chain name owner to broadcast a subdomain-update operation. To do so, they generate and sign the requisite subdomain operation and give it to an on-chain name owner, who then packages it with other subdomain operations into a DNS zone file and broadcasts it to the network. - -If the subdomain owner wants to change the address of their subdomain, they need to sign a subdomain-transfer operation and give it to the on-chain name owner who created the subdomain. They then package it into a zone file and broadcast it. - -### Subdomain Registrars - -Because subdomain names are cheap, developers may be inclined to run subdomain registrars on behalf of their applications. For example, the name `personal.id` is used to register usernames without requiring them to spend any Bitcoin. - -We supply a reference implementation of a [BNS Subdomain Registrar](https://github.com/stacks-network/subdomain-registrar) to help developers broadcast subdomain operations. Users would still own their subdomain names; the registrar simply gives developers a convenient way for them to register and manage them in the context of a particular application. - -# BNS and DID Standards - -BNS names are compliant with the emerging [Decentralized Identity Foundation](http://identity.foundation) protocol specification for decentralized identifiers (DIDs). - -Each name in BNS has an associated DID. The DID format for BNS is: - -```bash - did:stack:v0:{address}-{index} -``` - -Where: - -- `{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 `did:stack:v0:1dARRtzHPAFRNE7Yup2Md9w18XEQAtLiV-0`, because the name `personal.id` was the first-ever name created by `1dARRtzHPAFRNE7Yup2Md9w18XEQAtLiV`. - -As another example, the DID for `jude.id` is `did:stack:v0:16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg-1`. Here, the address `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` had created one earlier name in history prior to this one (which happens to be `abcdefgh123456.id`). - -The purpose of a DID is to provide an eternal identifier for a public key. The public key may change, but the DID will not. - -Stacks Blockchain implements a DID method of its own in order to be compatible with other systems that use DIDs for public key resolution. In order for a DID to be resolvable, all of the following must be true for a name: - -- The name must exist -- The name's zone file hash must be the hash of a well-formed DNS zone file -- The DNS zone file must be present in the Stacks node's data. -- The DNS zone file must contain a `URI` resource record that points to a signed JSON Web Token -- The public key that signed the JSON Web Token (and is included with it) must hash to the address that owns the name - -Not all names will have DIDs that resolve to public keys. However, names created by standard tooling will have DIDs that do. - -A RESTful API is under development. - -## DID Encoding for Subdomains - -Every name and subdomain in BNS has a DID. The encoding is slightly different 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 (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 subdomains owned by a single private key, and version byte 50 for subdomains owned by a m-of-n set of private keys. That is, subdomain DID addresses start with `S` or `M`, respectively. - -The `{index}` field for a subdomain's DID is distinct from the `{index}` field for a BNS name's DID, even if the same created both names and subdomains. For example, the name `abcdefgh123456.id` has the DID `did:stack:v0:16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg-0`, because it was the first name created by `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg`. However, `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` _also_ created `jude.statism.id` as its first subdomain name. The DID for `jude.statism.id` is `did:stack:v0:SSXMcDiCZ7yFSQSUj7mWzmDcdwYhq97p2i-0`. Note that the address `SSXMcDiCZ7yFSQSUj7mWzmDcdwYhq97p2i` encodes the same public key hash as the address `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` (the only difference between these two strings is that the first is base58check-encoded with version byte 0, and the second is encoded with version byte 63). diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/build-apps/references/references.md b/i18n/tr/docusaurus-plugin-content-docs/current/build-apps/references/references.md deleted file mode 100644 index babe5e119a..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/build-apps/references/references.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: References -sidebar_label: References ---- - -[Authentication](./authentication) - -[Blockchain Naming System](./bns) - -[Hiro example apps](https://docs.hiro.so/example-apps) \ No newline at end of file diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/contribute/docs.md b/i18n/tr/docusaurus-plugin-content-docs/current/contribute/docs.md deleted file mode 100644 index 77705451b8..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/contribute/docs.md +++ /dev/null @@ -1,207 +0,0 @@ ---- -title: Contribute to docs -description: Learn how this site is built, and how you can contribute to it. ---- - -## Introduction - -Thank you for your interest in contributing and helping make these docs as good as they can be. - -This docs site is built on the open source platform [Discosaurus 2](https://docusaurus.io/) and most of its content is written in Markdown files. All of the code for this site is free and open source, located at the [GitHub repository here](https://github.com/stacks-network/docs). - -:::tip Don't know what Markdown is? Want to learn? Here is a [helpful guide](https://guides.github.com/features/mastering-markdown/). - -Don't want to learn it? No need to. Write [in plain text an issue on Github](https://github.com/stacks-network/docs/issues/new?assignees=&labels=documentation&template=add-documentation.md&title=%5BAdd+docs%5D) ::: - -:::info You need a free [Github](https://www.github.com) account to add or edit any content. ::: - -To edit any page, just click on the *Edit this page* button at the bottom of each page and submit your changes online. - -To add new content, they are two different ways to do it, the [easy way](#easy-way) and the [advanced way](#advanced-way). - -## Easy way - -[**Simply click here and enter the text of the article you wish to add.**](https://github.com/stacks-network/docs/issues/new?assignees=&labels=documentation&template=add-documentation.md&title=%5BAdd+docs%5D) - -This will open up an issue on github using our template. -## Advanced way - -For more advanced changes you can follow the next steps. - -You can also test the site locally using this method. -### Steps - -1. Fork the [docs reposiroty](https://github.com/stacks-network/docs) by clicking on the *Fork* button in the upper right of the screen. -2. Clone your fork to your local machine with this command `git clone git@github.com:/docs.git stacks_docs` -3. Enter your project folder `cd stacks_docs` -4. Create a branch `git checkout -b feat/my-feature-branch`. -5. You can optionally preview your changes in real time with: - - `npm install` (to install dependencies). - - `npx docusaurus start` to start a local copy of the site. A web browser will open at http://localhost:3000, so you can see a preview of yourhanges in real time. -6. Make the changes you wish and then commit them with this kind of message: `git commit -am "feat: some new feature or content"`. -7. Push to to GitHub with `git push --set-upstream origin feature/my-feature-branch`. -8. Visit GitHub and make your pull request. - -## Aditional information -### Running and building the site locally (optional) - -You can start the page locally with the following command. This is enough to preview your changes. -```bash -npx docusaurus start -``` - -Before running this command for the first time you will need to run `npm install` to install dependencies. - -The docs site will be accessible at this url: [`http://localhost:3000`](http://localhost:3000). - - -After you finished your changes, you can also build the entire site with the following command (not usually needed): -```bash -npm run build -``` - -:::tip `npx docusaurus start` will only load the default language (english). To test all languages you can build with `npm run build` and then preview your build with `npm run serve`. ::: - -### An alternative: Working in browser - -As an alterative to working locally, you can also use the web IDE gitpod that provides an environment to contribute directly from within your browser. - -You only need to have a github account and open [this link](https://gitpod.io/#https://github.com/stacks-network/docs). - -### Folder structure of the site - -If you are interested in only adding new documentation content to the site, the files that will be important to you are located within `./docs/*`: - -```bash -docs/ - build-apps - contribute/ - faq/ - gaia/ - nodes-and-miners/ - noteworthy-contracts/ - references/ - understand-stack/ - write-smart-contracts/ -``` - -The routing for this site is file based, meaning if you created a folder within `/docs/gaia/` named `testing` and in it a file named `test1.md`, you would be able to navigate to `http://localhost:3000/gaia/testing/test1` and you would see whatever content is in that markdown file. - -All the docs in English are stored in the folder `/docs/`. - -To add new English content simply add a markdown file (.md) into any subfolder in docs, and it will be automatically displayed in the category of that folder. - -All the docs in other languages are stored under the folder `i18n`, but these files should never be edited using GitHub as they are overwritten by Crowdin every time new translations are added. **To make changes in other languages**, you must do so using Crowdin. Please refer to [translations](translations) instead. - -### Frontmatter - -Frontmatter is the top part of any markdown document that is written in a language called [YAML](https://yaml.org/). It looks like this: - -```yaml ---- -title: This is my page title -description: A short, concise sentence describing what is on this page ---- -``` - -Frontmatter gives us the ability to define some things within a page that the site can use, such as a page title or page description. When adding any new page, please include a `title` and `description`. - - - -### Use Conventional Commits - -We use the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) as and commits naming convention. Use it while contributing, please. - -### Code blocks - -To write a code block, you need to wrap your code in ` ```language `, and end your code block with ` ``` `. Here is an example of ` ```clarity `. - -```clarity -(define-data-var counter int 0) - -(define-public (get-counter) - (ok (var-get counter))) -``` -### Admonitions - -You can use the following admonitions to highlight content. - -```md -:::note -Some **content** with _markdown_ `syntax`. -::: - -:::tip -Some **content** with _markdown_ `syntax`. -::: - -:::info -Some **content** with _markdown_ `syntax`. -::: - -:::caution -Some **content** with _markdown_ `syntax`. -::: - -:::danger -Some **content** with _markdown_ `syntax`. -::: - -:::tip My personalized title -Some **content** with _markdown_ `syntax`. -::: -``` - -Which renders: - -:::note - -Some **content** with _markdown_ `syntax`. - -::: - -:::tip - -Some **content** with _markdown_ `syntax`. - -::: - -:::info - -Some **content** with _markdown_ `syntax`. - -::: - -:::caution - -Some **content** with _markdown_ `syntax`. - -::: - -:::danger - -Some **content** with _markdown_ `syntax`. - -::: - -:::tip My personalized title - -Some **content** with _markdown_ `syntax`. - -::: \ No newline at end of file diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/contribute/index.md b/i18n/tr/docusaurus-plugin-content-docs/current/contribute/index.md deleted file mode 100644 index ac81d899bd..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/contribute/index.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Contribute -description: Contribute to the Stacks ecosystem. -sidebar_position: 10 -sidebar_label: "Contribute" ---- - -You can contribute to the Stacks ecosystem in multiple ways: - - - -### Documentation - -Contribute to the Stacks Docs on this website. More info [here](docs). - -### Translations - -Help us reach more people with translations. More details [here](translations). - - - -### Articles - -Write an article or a blog post about Stacks. A good place to start is [Stacks Forum](https://forum.stacks.org). - -### Github - -If you are familiar with Github they are multiple repositories of the Stack Ecosystem that you can contribute to. - -- https://github.com/stacks-network/ diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/contribute/translations.md b/i18n/tr/docusaurus-plugin-content-docs/current/contribute/translations.md deleted file mode 100644 index bd9a452333..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/contribute/translations.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Contribute with translations -description: Want to help tranlating these docs to your local language? ---- - -## Help with translations - -Translations are managed with Crowdin. -Anybody can colaborate and no technichal skills are required, as it's all done on the browser. - -To help with translation please go to [this page](https://crowdin.com/project/docsstacksco), click any language and start translating. - -All help is appreciated. - -:::caution -Please don't add any translations to the Github repository, as the translated pages get rewritten from Crowdin. Translations need to be added on Crodin intead. -::: - -### Common issues on translations - -When translating in Crowdin, please only translate the texts and not the html code. - -If you acccidently modify the html tags you will get errors like shown below (`Seems like some formating tags are missing` or `Translation contains tag that source text doesn't have`). These errors will prevent your translation getting published until the tags are left as they were in the original text. - -![](/img/crowdin-qa-issue-formatting_tags_missing.png) ![](/img/crowdin-qa-issue-tag_source.png) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/faq/faq.md b/i18n/tr/docusaurus-plugin-content-docs/current/faq/faq.md deleted file mode 100644 index dde584e583..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/faq/faq.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: General FAQs -description: Frequently Asked Questions -sidebar_label: "FAQ" -sidebar_position: 10 ---- - -![](/img/glasses.png) - -## Why is my transfer still pending? - -Commonly it's because your fee is too low or your [nonce](#what-is-nonce) is incorrect. - -More information can be found [here](https://www.hiro.so/wallet-faq/why-is-my-stacks-transaction-pending). There are also [best practices and known issues](https://forum.stacks.org/t/transactions-in-mempool-best-practices-and-known-issues/11659) and [diagnosing pending transactions](https://forum.stacks.org/t/diagnosing-pending-transactions/11908). - -There is also this [script](https://github.com/citycoins/scripts/blob/main/getnetworkstatus.js) to look at either the first 200 transactions or all the transactions in the mempool, to then return the maximum adn average fee values. We've noticed that using 1.5-2x the average fee in the mempool will generally get things processed within 6-10 blocks even during high congestion. - -There is also this [script](https://github.com/citycoins/scripts/blob/main/gettxstatus.js) to track a pending transaction until it reaches a final status. - -## What is Nonce? - -A nonce is used to make sure that every transaction goes in right order. Nonce starts at 0, so the very first transaction from an address should set to nonce=0. You can find the nonce of your wallet address by searching the address in any [Stacks blockchain explorer](https://explorer.stacks.co/). You can also user `$ stx balance
`. - -If you have a transaction nonce that is less than your account nonce, the transaction is unmineable and will (should) disappear after 256 blocks. This does not affect future transactions and therefore can be just ignored, they are in the past. - -If you have a transaction nonce that is equal to your account nonce, then that transaction is valid and should be the next in line to be processed next. - -If you have a transaction nonce that is higher than your account nonce, then there needs to be a chain of transactions starting with your account nonce in order for it to be processed. E.g. Your account nonce is 10 but the pending transaction has a nonce of 12. It will not be mineable until a transaction with nonces 10 and 11 are processed. - -## Whats a Replace-by-fee (RBF)? - -A replace-by-fee (RBF) transaction tells the blockchain that you would like to replace one transaction with another, while specifying a fee that is higher than the original transaction fee. A transaction can be replaced with **any other transaction**, and is not limited to the same operation. - -This can be used to effectively **cancel a transaction** by replacing it with something else, like a small STX transfer to another owned address. - -This can be used to **raise the fee for a pending transaction** so it is considered by miners during periods of high congestion. This can also be used to _resubmit_ a transaction, in the sense that the RBF transaction gets a new txid and gets considered again (or faster) by miners. E.g. I submit my transaction with 1 STX fee at block 54,123. By block 54,133 I see my tx hasn’t been picked up, so I RBF with 1.1 STX. Then wait 10 blocks again, and RBF again if not received. There’s a balance between doing this too often and keeping a consistent pace, but it has been seen to help get transactions through, especially when new ones are constantly flooding in. - -The replacement transaction needs to use the same nonce as the original transaction with a fee increase of at least 0.000001 STX. E.g. Your original transaction has a fee of 0.03 STX, the new RBF transaction must have a fee of 0.030001 STX or above. - -RBF transactions process in one of two ways: - -- If miners pick up the original transaction before the RBF transaction is received, then the original transaction is processed and the replacement transaction goes into an unmineable state. It will eventually disappear and doesn’t affect future transactions. -- If miners pick up the replaced transaction then the new transaction is processed instead of the original, and the status of the original transaction is set to “droppped_replaced_by_fee”. This status is not shown on the explorer but can be seen when querying the txid. - -Submitting multiple transactions for the same action can slow things down in a few ways. - -- If the total spent in 2 or 3 transactions is more than can be spent in a single transaction, the transactions appear unmineable. -- If the fees for multiple transactions exceed the STX balance, the transactions will be unmineable. - -## What are .btc domains? - -[This forum post](https://forum.stacks.org/t/btc-domains-are-live/12065) explains all the benefits of .btc domains. They can currently be purchased in [btc.us](https://btc.us/) - -## What is the blockchain trilemma? - -## Stacks vs. Solana vs. Polygon: How Do They Compare From a Developer Perspective? - -[This blog post answers the question](https://www.hiro.so/blog/stacks-vs-solana-vs-polygon-how-do-they-compare-from-a-developer-perspective). - -## What Does Lightning’s Taro Proposal Mean for Stacks? - -[This blog post answers the question](https://www.hiro.so/blog/what-does-lightnings-taro-proposal-mean-for-stacks). - - -## Is Stacks a [PoS chain](https://en.wikipedia.org/wiki/Proof_of_stake)?[¹][] - -No. - -The act of block production requires an extrinsic expenditure — it is not tied to owning the native token, as would be required in PoS. The only way to produce blocks in the Stacks chain is to transfer Bitcoin to a predetermined randomized list of Bitcoin addresses. Moreover, the Stacks blockchain can fork, and there exists a protocol to rank forks by quality independent of the set of miners and the tokens they hold. These two properties further distinguish it from PoS chains, which cannot fork due to the inability to identify a canonical fork without trusting a 3rd party to decree a particular fork as valid. The ability to fork allows the Stacks blockchain to survive failure modes that would crash a PoS chain. - -## Is Stacks a [sidechain](https://en.bitcoin.it/wiki/Sidechain)?[¹][] - -No. - -For two key reasons. - -First, the history of all Stacks blocks produced is recorded to Bitcoin. This means that the act of producing a private Stacks fork is at least as hard as reorging the Bitcoin chain. This in turn makes it so attacks on the chain that rely on creating private forks (such as selfish mining and double-spending) are much harder to carry out profitably, since all honest participants can see the attack coming before it happens and have a chance to apply countermeasures. Sidechains offer no such security benefit. - -Second, the Stacks blockchain has its own token; it does not represent pegged Bitcoin. This means that the safety of the canonical fork of the Stacks blockchain is underpinned by its entire token economy’s value, whereas the safety of a sidechain’s canonical fork is underpinned only by whatever system-specific measures incentivize its validators to produce blocks honestly, or the Bitcoin miners’ willingness to process peg-in requests (whichever is the weaker guarantee). - - -## Is Stacks a [layer-2 system](https://academy.binance.com/en/glossary/layer-2) for Bitcoin?[¹][] - -No. - -Stacks blockchain is a layer-1 blockchain, which uses a novel and unique mining protocol called proof-of-transfer (PoX). A PoX blockchain runs in parallel to another blockchain (Bitcoin in Stacks’ case), which it uses as a reliable broadcast medium for its block headers. It's a sovereign system in its own right. The Stacks blockchain state is distinct from Bitcoin, and is wholly maintained by and for Stacks nodes. Stacks transactions are separate from Bitcoin transactions. Layer-2 systems like Lightning are designed to help scale Bitcoin payment transactions, whereas Stacks is designed to bring new use-cases to Bitcoin through smart contracts. Stacks is not designed as a Bitcoin layer-2 scalability solution. - - -## Is Stacks a [merged-mined chain](https://en.bitcoin.it/wiki/Merged_mining_specification)?[¹][] - -No. - -The only block producers on the Stacks chain are Stacks miners. Bitcoin miners do not participate in Stacks block validation, and do not claim Stacks block rewards. Moreover, Stacks is not a [blind merged-mined chain](https://github.com/bitcoin/bips/blob/master/bip-0301.mediawiki), because STX block winners are public and randomly chosen (instead of highest-bid-wins), and its tokens are minted according to a schedule that is independent of the degree of miner commitment or Bitcoin transferred (instead of minted only by one-way pegs from Bitcoin). This ensures that Stacks is able to make forward progress without opt-in from Bitcoin miners, and it ensures that Stacks miners are adequately compensated for keeping the system alive regardless of transaction volume. - -## Whats the difference between Stacks and Ethereum?[²][] -**Computation and Storage** Stacks does all computation and storage outside of the blockchain, and uses the blockchain only as a “shared source of truth” between clients. By contrast, Ethereum does all computation and most application storage in the blockchain itself. Like Ethereum, if two Stacks nodes see the same underlying blockchain, they will independently run the same computations and produce the same state. Unlike Ethereum, there is no Stacks-specific blockchain. - -**Programming Language and Tooling** Stacks’s programming model is based on running off-chain programs. These programs can be written and debugged in any language you want. By contrast, Ethereum’s programming model is based on running on-chain “smart contracts.” These are written and debugged with a whole new set of tools, like Solidity and Serpent. - -**Scalability of On-chain Computation** Stacks is designed around a “virtual chain” concept, where nodes only need to reach consensus on the shared “virtual chain” they’re interested in. Virtual chains do not interact with one another, and a single blockchain can host many virtual chains. Although Stacks’s specific virtual chain is not Turing-complete (i.e. it’s a list of instructions to build the name database), it is possible to create Turing-complete virtual chains like Ethereum. These virtual chains can live in any blockchain for which there exists a driver, and virtual chain clients only need to execute their virtual chain transactions (i.e. Stacks only processes Stacks virtual chain transactions). - -By contrast, because smart contracts run on-chain and can call one another, all Ethereum nodes need to process all smart contracts’ computations in order to reach consensus. This can get expensive as the number of running smart contracts grow, which takes the form of gas fee increases. - -**Scalability of Off-chain Computation** Stacks applications are very similar to Web applications today and almost never need to interact with the blockchain. For most Stacks applications, the blockchain is only used to authenticate the application’s code and data before the user runs it. By contrast, Ethereum applications usually require an application-specific smart contract, and must interact with the blockchain to carry out its operations. - - -[¹]: https://stacks.org/stacks-blockchain -[²]: https://forum.stacks.org/t/what-is-the-difference-between-blockstack-and-ethereum/781 diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/gaia/configuration.md b/i18n/tr/docusaurus-plugin-content-docs/current/gaia/configuration.md deleted file mode 100644 index a6a530cd70..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/gaia/configuration.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Configuration -description: Configuring Gaia Hub ---- - -## Configuration files - -The following configuration files exist in the folder `deploy/configs/gaia/`: - -``` -admin-config.json -hub-config.json -reader-config.json -``` - -## GAIA Admin Service - -You can also use the GAIA Admin Service to remotely administer it with an API Key. It will require you to install `npm` with a `apt install npm`. Once `npm` is installed you can continue with the steps in the [GAIA Admin Service](https://github.com/stacks-network/gaia/blob/master/admin/README.md). - -## Driver Selection - -The Gaia hub currently supports the following drivers: - -``` -'aws' == Amazon S3 -'azure' == Azure Blob Storage -'disk' == Local disk -'google-cloud' === Google Cloud Storage -``` - -Set the driver you wish to use in your [config.json](https://github.com/stacks-network/gaia/blob/master/hub/config.sample.json) file with the `driver` parameter. Many drivers additionally accept the `bucket` parameter, which controls the bucket name that files should be written to. - -These driver may require you to provide additional credentials for performing writes to the backends. See `config.sample.json` for fields for those credentials. In some cases, the driver can use a system configured credential for the backend (e.g., if you are logged into your AWS CLI account, and run the hub from that environment, it won't need to read credentials from your `config.json`). - -_Note:_ The disk driver requires a \*nix like filesystem interface, and will not work correctly when trying to run in a Windows environment. ::: - -## Note on SSL - -We _strongly_ recommend that you deploy your Gaia hub with SSL enabled. Otherwise, the tokens used to authenticate with the Gaia hub may be stolen by attackers, which could allow them to execute writes on your behalf. -Configuration options are available to run the hub with an `https` Node.js server. -Otherwise, a reverse proxy web server such as nginx or Apache can be used. - -## Require Correct Hub URL - -If you turn on the `requireCorrectHubUrl` option in your `config.json` file, your Gaia hub will require that authentication requests correctly include the `hubURL` they are trying to connect with. This is used to prevent a malicious gaia hub from using an authentication token for itself on other Gaia hubs. - -By default, the Gaia hub will validate that the supplied URL matches `https://${config.serverName}`, but if there are multiple valid URLs for clients to reach the hub at, you can include a list in your `config.json`: - -```javascript -{ - .... - serverName: "normalserver.com" - validHubUrls: [ "https://specialserver.com/", - "https://legacyurl.info" ] - .... -} -``` - -## The readURL parameter - -By default, the gaia hub drivers will return read URLs which point directly at the written content. For example, an S3 driver would return the URL directly to the S3 file. However, if you configure a CDN or domain to point at that same bucket, you can use the `readURL` parameter to tell the gaia hub that files can be read from the given URL. For example, the `hub.blockstack.org` Gaia Hub is configured to return a read URL that looks like `https://gaia.blockstack.org/hub/`. - -Unset this configuration parameter if you do not intend to deploy any caching. - -## Minimum Proofs Requirement - -The gaia hub can also be configured to require a minimum number of social proofs in a user's profile to accept writes from that user. This can be used as a kind of spam-control mechanism. However, we recommend for the smoothest operation of your gaia hub, to set the `proofsConfig.proofsRequired` configuration key to `0`. - -## CDN & Replicated Hubs - -- https://docs.microsoft.com/en-us/azure/storage/blobs/storage-https-custom-domain-cdn - -- The hub implementation is designed to be ran from a single Node.js instance. If the hub instance is sharded (e.g. replicated hubs via load balancing), then any given `bucket` (identified by URI segment) must be served by the same instance, At least a couple elements of the Gaia Hub depend on this: token invalidation in-memory caching, and resource endpoint 409 contention behavior. diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md b/i18n/tr/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md deleted file mode 100644 index 558cbb14f5..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Deploy Gaia Hub -description: Steps and tutorials ---- - -## Deploy your GAIA hub - -Tutorials to deploy your own GAIA hub are currently available for [Linux](./setup-linux), [MacOS](./setup-mac) and [Amazon EC2 / CloudFormation](./gaia-on-ec2). - -Regardless of what server the Gaia Hub runs on, the storage it uses can currently be deployed on multiple platforms: - -- Local disk (the server itself) -- Amazon S3 -- Azure Blob Storage -- Google Cloud - -:::tip -Support for IPFS is under development. -::: \ No newline at end of file diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md b/i18n/tr/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md deleted file mode 100644 index 2067e7d57c..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Amazon EC2 -description: Use a template to deploy a Gaia hub on Amazon EC2 -tags: - - tutorial - - gaia ---- - -## Introduction - -The template provided on this page provides an easy way to deploy a Gaia hub directly to Amazon EC2. You can use this template to deploy your own Gaia hub to your Amazon Web Services (AWS) account. Amazon EC2 is an affordable and convenient cloud computing provider. The template provides a one-click deploy for Amazon EC2 with either S3 or EBS as a storage provider. - -## Prerequisites - -This procedure uses Amazon CloudFormation to configure an EC2 cloud compute provider to run the Gaia hub service with an S3 or EBS provider for file storage. You should have access to an AWS account either through your personal account or through a corporate account. This account should have permissions to create resources. - -Additionally, you must also own a domain name and be able to update the DNS records associated with that domain name. - -## Setup steps - -### Step 1 - Create Stack - -Use a link in the table to launch the [CloudFormation](https://console.aws.amazon.com/cloudformation/) template in the AWS region that you wish to deploy a Gaia hub. - -![Create stack](/img/cloudformation-create-stack.png) - -### Step 2 - Setup stack using template - -You need to configure the template with the appropiate values for your hub and domain it runs on. - -Select `Template is ready` and `Amazon S3 URL` and enter the following Amazon S3 URL: -``` -https://s3-external-1.amazonaws.com/cf-templates-vzldibfi2mw8-us-east-1/2022160J6G-cloudformation.yaml -``` - -If you prefer you can instead select `Template is ready` and `Upload a template file` to upload the template file `cloudformation.yaml`. - -The latest `cloudformation.yaml` file can be downloaded [here](https://raw.githubusercontent.com/stacks-network/gaia/master/deploy/cloudformation.yaml). On most browsers you can right-click on that page and click on `Save page as` to download the file. Alternatively, you can copy/paste the text into a text file called `cloudformation.yaml`. - -Then click `Next`. - -![Specify template](/img/cloudformation-specify-template.png) - -### Step 3 - Specify stack details - -Specify the stack details and then click `Next`: ![Specify template](/img/cloudformation-specify-stack-details.png) - -| Field | Value | Notes | -| --------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Stack name | _a unique name in your AWS account_ | e.g.: my_gaia_hub | -| DomainName | _your-domain_ | | -| EmailAddress | _your email address_ | | -| GaiaBucketName | _S3 bucket name_ | The template combines this name with the stack name to create a unique S3 bucket. The template ignores this field if GaiaStorageType is set to `disk`. | -| GaiaStorageType | `s3` or `disk` | Select the GaiaStorageType of which to use as a backend for the Gaia Hub. Selecting `s3` causes the template to create an S3 bucket based on the name given in the previous field. Selecting `disk` causes the template to attach a separate EBS volume to the EC2 instance for Hub storage. | -| InstaceType | t2.micro | Select the instance type you want. Default value is `t2.micro`. | -| KeyName | | In the KeyName drop-down, select an [EC2 KeyPair](https://console.aws.amazon.com/ec2/v2/home?region=us-east-1#KeyPairs:) to enable SSH access to the EC2 instance. You should download the `.pem` keyfile for this pair from the EC2 console. For more information see the [EC2 key pair documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html#prepare-key-pair) | -| SSHLocation | 0.0.0.0/0 | Leave the SSHLocation field with the default value of `0.0.0.0/0` to enable SSH access from any IP address. If you wish to restrict SSH access to the EC2 instance to a certain IP, you can update this field. | -| SubnetId | _subnetid_ | Select a public subnet | -| VpcId | _vpcid_ | | - -### Step 4 - Configure stack options - -Configure any stack options that fit your desired setup and click `Next`. All these fields are optional. - -![Specify template](/img/cloudformation-stack-options.png) - -### Step 5 - Review - -Review the configuration of your Gaia hub, select the checkbox to acknowledge that AWS may create IAM resources with custom names and click on `Create stack`. - -![Specify template](/img/cloudformation-iam-resources.png) - -### Step 6 - Retrieve the public IP of your Gaia hub - -Your stack can take several minutes to launch. You can monitor the Events tab of your hub to review the current progress of the launch. When the launch is complete, the Outputs tab displays information about the hub. Select the PublicIP and copy it to configure your domain name. - -Create an `A` DNS record pointing to the given IP in your domain. - -Wait a few minutes for the DNS record to propagate, and your should be able to access your Gaia hub with SSH. - -## Accessing your Gaia hub with SSH - -To SSH into your Gaia hub EC2 host directly, you must have the keyfile used in container creation. Access the host with the following command in your terminal: - -```bash -ssh -i admin@ -``` - -:::tip If you can only access SSH with the IP but not with the DNS name and you wish to do so, you can optionally activate it by following these steps: - - Open your [AWS Console](https://console.aws.amazon.com) - Click on `Service` -> VPC - Open Your VPCs - Select your VPC connected to your Gaia Hub - Click `Actions` -> `Edit DNS Hostnames` -> Change `DNS hostnames` to `Enable` -::: -## Graphical representation of the cloudformation template - -![](/img/cloudformation-gaia-template1-designer.png) \ No newline at end of file diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/gaia/gaia.md b/i18n/tr/docusaurus-plugin-content-docs/current/gaia/gaia.md deleted file mode 100644 index 1070857350..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/gaia/gaia.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Gaia -description: Decentralized storage architecture for off-chain data -sidebar_position: 5 -tags: - - gaia ---- - -## Introduction - -Apps built with the Stacks blockchain store off-chain data using a storage system called Gaia. - -Whereas public transactional metadata is best stored on the Stacks blockchain, user application data can often be stored more efficiently and privately in Gaia storage. - -Storing data off of the blockchain ensures that Stacks applications can provide users with high performance and high availability for data reads and writes without introducing central trust parties. - -:::tip Latest whitepaper of GAIA (May 2022) is available [here](https://dev1-gaia-hub.s3.amazonaws.com/GAIA_Whitepaper.pdf) ::: - -## Understand Gaia in the Stacks architecture - -The following diagram depicts the Stacks architecture and Gaia's place in it: - -![Stacks Architecture](/img/architecture.png) - -Blockchains require consensus among large numbers of people, so they can be slow. Additionally, a blockchain is not designed to hold a lot of data. This means using a blockchain for every bit of data a user might write and store is expensive. For example, imagine if an application were storing every tweet in the chain. - -The Stacks blockchain addresses performance problems using a layered approach. The base layer consists of the Stacks blockchain and the Blockchain Naming System (BNS). The blockchain governs ownership of identities in the Stacks network. Identities can be names such as domain names, usernames, or application names. - -When an identity is created, its creation is recorded in the Stacks blockchain. Identities make up the primary data stored into the Stacks blockchain. These identities correspond to routing data in the OSI stack. The routing data is stored in the Atlas Peer Network, the second layer. Every core node that joins the Stacks Network is able to obtain an entire copy of this routing data. Stacks uses the routing data to associate identities (domain names, user names, and application names) with a particular storage location in the final layer, the Gaia Storage System. - -A Gaia Storage System consists of a _hub service_ and storage resource on a cloud software provider. The storage provider can be any commercial provider such as Azure, DigitalOcean, Amazon EC2, and so forth. Typically the compute resource and the storage resource reside same cloud vendor, though this is not a requirement. Gaia currently has driver support for S3, Azure Blob Storage, Google Cloud Platform and local disk, but the driver model allows for other backend support as well. - -Gaia stores data as a simple key-value store. When an identity is created, a corresponding data store is associated with that identity on Gaia. When a user logs into a dApp, the authentication process gives the application the URL of a Gaia hub, which then writes to storage on behalf of that user. - -The Stacks blockchain stores only identity data. Data created by the actions of an identity is stored in a Gaia Storage System. Each user has profile data. When a user interacts with a decentralized dApp that application stores application data on behalf of the user. Because Gaia stores user and application data off the blockchain, a Stacks DApp is typically more performant than DApps created on other blockchains. - -## User control or how is Gaia decentralized? - -A Gaia hub runs as a service which writes to data storage. The storage itself is a simple key-value store. The hub service writes to data storage by requiring a valid authentication token from a requestor. Typically, the hub service runs on a compute resource and the storage itself on separate, dedicated storage resource. Typically, both resources belong to the same cloud computing provider. - -![Gaiastorage](/img/gaia-storage.png) - -Gaia's approach to decentralization focuses on user control of data and its storage. Users can choose a Gaia hub provider. If a user can choose which Gaia hub provider to use, then that choice is all the decentralization required to enable user-controlled applications. Moreover, Gaia defines a uniform API for applications to access that data. - -The control of user data lies in the way that user data is accessed. When an application fetches a file `data.txt` for a given user `alice.id`, the lookup will follow these steps: - -1. Fetch the `zonefile` for `alice.id`. -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. Find the read-only url out of the profile's `appsMeta` section (e.g. `https://example-app.gaia.alice.org`). -6. Fetch the file from `https://example-app.gaia.alice.org/data.txt`. - -Because `alice.id` has access to her [zonefile](https://docs.stacks.co/references/bns-contract#name-update), 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. - -:::caution -Users with existing identities cannot yet migrate their data from one hub to another. -::: - -Applications writing directly on behalf of `alice.id` do not need to perform a lookup. Instead, the [Stacks authentication flow](https://stacks.js.org) provides Alice's chosen gaia hub URL to the application. This authentication flow _is also_ within Alice's control because Alice's wallet _must_ generate the authentication response. - -## Understand data storage - -A Gaia hub stores the written data _exactly_ as given. It offers minimal guarantees about the data. It does not ensure that data is validly formatted, contains valid signatures, or is encrypted. Rather, the design philosophy is that these concerns are client-side concerns. - -Client libraries (such as [`Stacks.js`](https://stacks.js.org/)) are capable of providing these guarantees. A liberal definition of the [end-to-end principle](https://en.wikipedia.org/wiki/End-to-end_principle) guides this design decision. - -When an application writes to a Gaia hub, an authentication token, key, and the data are passed to the Gaia hub. - -![Gaia writes](/img/gaia-writes.png) - -The token ensures the app has the authorization to write to the hub on the user's behalf. - -## Gaia versus other storage systems - -Here's how Gaia stacks up against other decentralized storage systems. Features that are common to all storage systems are omitted for brevity. - -| Features | [Gaia](https://github.com/stacks-network/gaia) | [Sia](https://sia.tech/) | [Storj](https://storj.io/) | [IPFS](https://ipfs.io/) | [DAT](https://datproject.org/) | [SSB](https://www.scuttlebutt.nz/) | -| ------------------------------------------ | ---------------------------------------------- | ------------------------ | -------------------------- | ------------------------ | ------------------------------ | ---------------------------------- | -| User controls where data is hosted | X | | | | | | -| Data can be viewed in a normal Web browser | X | | | X | | | -| Data is read/write | X | | | | X | X | -| Data can be deleted | X | | | | X | X | -| Data can be listed | X | X | X | | X | X | -| Deleted data space is reclaimed | X | X | X | X | | | -| Data lookups have predictable performance | X | | X | | | | -| Writes permission can be delegated | X | | | | | | -| Listing permission can be delegated | X | | | | | | -| Supports multiple backends natively | X | | X | | | | -| Data is globally addressable | X | X | X | X | X | | -| Needs a cryptocurrency to work | | X | X | | | | -| Data is content-addressed | | X | X | X | X | X | diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/gaia/setup-linux.md b/i18n/tr/docusaurus-plugin-content-docs/current/gaia/setup-linux.md deleted file mode 100644 index db427f890a..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/gaia/setup-linux.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: Linux -description: Steps to setup a GAIA hub on a Linux server (fresh install). This example is using Debian, but should work on any Linux distribution. It uses docker compose in the backgroud. -tags: - - tutorial - - gaia ---- - -This configuration will setup the following 4 docker containers: - -- Nginx with certbot on TCP ports 80 and 443. -- Gaia hub on TCP port 3000. -- Gaia admin on TCP port 8009. -- Gaia reader on TCP port 8008 - -**1. Update the system and install the dependencies and software we will use to test:** - -```bash -apt update && apt upgrade -y && apt install -y git vim gnupg jq -``` - -**2. Install [docker](https://docs.docker.com/engine/install/debian/) and [docker-compose](https://docs.docker.com/compose/cli-command/#install-on-linux)** in your OS. -For our example we install _docker_ with: - -```bash -curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg - -echo \ - "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian \ - $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null - -apt update && apt install -y docker-ce docker-ce-cli containerd.io -``` - -Install _docker-compose_ by downloading the [latest-release](https://github.com/docker/compose/releases): - -```bash -VERSION_DC=$(curl --silent https://api.github.com/repos/docker/compose/releases/latest | jq .name -r) -DESTINATION_DC=~/.docker/cli-plugins -mkdir -p ${DESTINATION_DC} -curl -SL https://github.com/docker/compose/releases/download/${VERSION_DC}/docker-compose-linux-x86_64 -o ${DESTINATION_DC}/docker-compose -chmod +x ${DESTINATION_DC}/docker-compose -``` - -**3. Clone the GAIA repository** and enter it's docker directory. - -```bash -git clone https://github.com/stacks-network/gaia.git && cd gaia/deploy/docker -``` - -**4. Copy and edit appropiate .env file**. -In the folder `./deploy/docker/` they are different sample files for different configurations like using aws, azure or disk among others. In this example we will store the data localy so we will copy the _disk_ file and update the domain and email fields. Please change `gaia.site.com` and `gaiarocks@mydomain.com` accordingly. Note you need both for the SSL certificate to be created correctly. - -```bash -export MYGAIADOMAIN=gaia.site.com -export MYGAIAEMAIL=gaiarocks@mydomain.com -cp sample-disk.env disk.env -sed -i 's/my-domain.com/'"$MYGAIADOMAIN"'/g' disk.env -sed -i 's/my-email@example.com/'"$MYGAIAEMAIL"'/g' disk.env - -``` - -**5. Start GAIA HUB service** - -To start GAIA HUB - -```bash -./gaiahub.sh start -``` - -To stop GAIA HUB - -```bash -./gaiahub.sh stop -``` - -To view GAIA HUB status - -```bash -./gaiahub.sh status -``` - -**6. Verify server works locally** with the following command: - -```bash -curl -sk http://localhost/hub_info | jq -``` - -A correct result should look similar to this: - -```bash - { - "challenge_text": "[\"gaiahub\",\"0\",\"gaia-0\",\"blockstack_storage_please_sign\"]", - "latest_auth_version": "v1", - "max_file_upload_size_megabytes": 20, - "read_url_prefix": "https://gaia.site.com/reader/" - } -``` - -**7. Test your GAIA HUB** Running `gaia_test.js` will test your GAIA Hub, by trying to connect to it, uploading a file and downloading it again. - -First install all required dependencies with: - -```bash -npm install -``` - -Then, from the root folder of the project type: - -```bash -node ./deploy/gaia_test.js https://yourgaiaurl -``` - -A correct result will be something like this: - -``` -Will run a test for the GAIA HUB: https://gaia.mydomain.com -Generating some test keys... -Private key: 5aacc60fc2a429e1f02be139f3cac82061c6a980******************** -Public key: 025691f17f2ab80dc4af363bb9c7aac59e9e1db6ae8ff668202582a3f4ec9678ff -Address: 15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS -[DEBUG] connectToGaiaHub: https://gaia.mydomain.com/hub_info -[DEBUG] uploadToGaiaHub: uploading testing.txt to https://gaia.mydomain.com -File uploaded successfully. -Upload to gaia hub thinks it can read it from: https://gaia.mydomain.com/reader/15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS/testing.txt -Hub info thinks it can read it from : https://gaia.mydomain.com/reader/15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS/testing.txt -Let's now try to fetch the uploaded file... -File fetched successfully. Contents of file: GAIA ROCKS! -``` diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/gaia/setup-mac.md b/i18n/tr/docusaurus-plugin-content-docs/current/gaia/setup-mac.md deleted file mode 100644 index 808833b212..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/gaia/setup-mac.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: MacOS -description: MacOS for local testing/development -tags: - - tutorial ---- - -The following assumes you have [Docker Installed](https://docs.docker.com/docker-for-mac/install/) - -- Recommended to also have [MacOS Homebrew](https://docs.brew.sh/Installation) installed -- Use Homebrew to install jq with `brew install jq` - -In your working directory: - -**1. Clone a copy of the [gaia repo](https://github.com/stacks-network/gaia):** - -```bash -$ git clone -b master --single-branch https://github.com/stacks-network/gaia -``` - -**2. Change your cwd:** - -```bash -$ cd gaia/deploy/docker -``` - -**3. Create a copy of sample-disk.env and fill out the values:** - -``` -$ cp sample-disk.env disk.env -# Update the DOMAIN_NAME variable to `localhost` -``` - -**4. Start the server:** - -``` -$ docker-compose -f docker-compose-base.yaml -f docker-compose-disk.yaml --env-file disk.env up -``` - -**5. Verify the server is responding locally:** - -``` -$ curl -sk https://localhost/hub_info | jq - { - "challenge_text": "[\"gaiahub\",\"0\",\"gaia-0\",\"blockstack_storage_please_sign\"]", - "latest_auth_version": "v1", - "max_file_upload_size_megabytes": 20, - "read_url_prefix": "https://localhost/reader/" - } -``` - -### Modifying the configuration for your gaia-hub - -Two methods exist: - -1. Edit the `gaia/deploy/configs/gaia/hub-config.json` using `vim` or other - -- requires a restart of the containers: `docker-compose -f docker-compose-base.yaml -f docker-compose-disk.yaml --env-file disk.env restart` - -2. Use the running `admin` container to modify any config values, and also reload the hub when complete: - -- [GitHub - Gaia Admin README.md](https://github.com/stacks-network/gaia/blob/master/admin/README.md) - -``` -$ export API_KEY="hello" -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - -H 'Content-Type: application/json' \ - -X POST \ - --data-raw '{"serverName": "myserver"}' \ - http://localhost:8009/v1/admin/config - -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - -X POST \ - http://localhost:8009/v1/admin/reload - -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - http://localhost:8009/v1/admin/config | jq -``` diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/governance/_index.md b/i18n/tr/docusaurus-plugin-content-docs/current/governance/_index.md deleted file mode 100644 index 1ecdf67871..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/governance/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Governance -description: Governance -sidebar_position: 9 ---- - -This page needs contributions. Help us write it! \ No newline at end of file diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/governance/index.md b/i18n/tr/docusaurus-plugin-content-docs/current/governance/index.md deleted file mode 100644 index 91b0215b5f..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/governance/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Governance -description: Governance -sidebar_position: 9 ---- - -![](/img/stacks-governance.png) - -This page needs contributions. Help us write it! - -Governance in web3 is driven by the community. - -How can I get involved ? - -[Governance Resources website](https://resources.stacksgov.com) - -[Github - Stack Community Governance](https://github.com/stacksgov) - -:::tip Community Calls Monthly community calls are recorded and available [here](https://www.youtube.com/playlist?list=PLg717Ri_rTnwwYjQYlc7rIP6x2FaTNn7f) ::: diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/governance/sips.md b/i18n/tr/docusaurus-plugin-content-docs/current/governance/sips.md deleted file mode 100644 index 29ac1ae1ed..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/governance/sips.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: SIPs -description: SIPs -sidebar_position: 9 ---- - -## Stacks Improvement Proposals (SIPs) - -Stacks improvement proposals (SIPs) are aimed at describing the implementation of the Stacks blockchain, as well as proposing improvements. - -The SIP process [(SIP-000)](https://github.com/stacksgov/sips/blob/main/sips/sip-000/sip-000-stacks-improvement-proposal-process.md) describes how to make a SIP and get it ratified. - -They should contain concise technical specifications of features or standards and the rationale behind it. SIPs are intended to be the primary medium for proposing new features, for collecting community input on a system-wide issue, and for documenting design decisions. - -The SIPs are located in the [stacksgov/sips](https://github.com/stacksgov/sips) repository as part of the [Stacks Community Governance organization](https://github.com/stacksgov). - -Anyone in the Stacks community can submit a SIP. - -:::tip Stacks Improvement Proposals Community Calls SIP Meeting calls are recorded and available [here](https://www.youtube.com/playlist?list=PLg717Ri_rTnx5kuaWqp3cUAtwQk_yzslT) - -More details of the meetings are available [here](https://github.com/stacksgov/sips/issues/79) ::: - -## Ratified SIPSs - -- [x] [SIP 001: Burn Election](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md) -- [x] [SIP 002: Clarity, a language for predictable smart contracts](https://github.com/stacksgov/sips/blob/main/sips/sip-002/sip-002-smart-contract-language.md) -- [x] [SIP 003: Peer Network](https://github.com/stacksgov/sips/blob/main/sips/sip-003/sip-003-peer-network.md) -- [x] [SIP 004: Cryptographic Committment to Materialized Views](https://github.com/stacksgov/sips/blob/main/sips/sip-004/sip-004-materialized-view.md) -- [x] [SIP 005: Blocks, Transactions, and Accounts](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md) -- [x] [SIP 006: Clarity Execution Cost Assessment](https://github.com/stacksgov/sips/blob/main/sips/sip-006/sip-006-runtime-cost-assessment.md) -- [x] [SIP 007: Stacking Consensus](https://github.com/stacksgov/sips/blob/main/sips/sip-007/sip-007-stacking-consensus.md) -- [x] [SIP 008: Clarity Parsing and Analysis Cost Assessment](https://github.com/stacksgov/sips/blob/main/sips/sip-008/sip-008-analysis-cost-assessment.md) -- [x] [SIP 009: Standard Trait Definition for Non-Fungible Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-009/sip-009-nft-standard.md) -- [x] [SIP 010: Standard Trait Definition for Fungible Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-010/sip-010-fungible-token-standard.md) -- [x] [SIP 012: Burn Height Selection for a Network Upgrade to Introduce New Cost-Limits](https://github.com/stacksgov/sips/blob/main/sips/sip-012/sip-012-cost-limits-network-upgrade.md) -- [x] [SIP-016: Metadata for Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-016/sip-016-token-metadata.md) - -## How to Get Involved - -There are several ways you can get involved with the SIP process: - -* **Join the weekly SIP Meeting call** listed [here](https://community.stacks.org/events). - -* **SIP Editor**. SIP editors help SIP authors make sure their SIPs are well-formed and follow the right process. They help get SIPs ready for deep review by advancing it them from Draft to Accepted status. If you want to become a SIP editor, open an issue with your name and email to ask to be added to the list of SIP editors. - -* **Join a CAB** (Consideration Advisory Board). SIPs fall under the purview of one or more considerations. A full list is in [this github](https://github.com/stacksgov/sips/tree/main/considerations) directory. Currently they are: Diversity, Economics, Ethics, Governance and Technical. Members of SIP consideration advisory boards use their domain expertise to give Accepted SIPs a deep read, and give the authors any/all feedback to help make the SIP workable. If you want to join a board, reach out to the board's chairperson via the listed contact information. - -* **Steering Committee**. The Steering Committee organizes the consideration advisory boards and votes to advance Recommended SIPs to Activation-in-Progress status, and then to either Ratified or Rejected status. Once they are in the process of being activated, they use a SIP's Activation section to determine whether or not the Stacks ecosystem has ratified or rejected the SIP. Joining this committee requires the consent of the Stacks Foundation board. diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/intro.md b/i18n/tr/docusaurus-plugin-content-docs/current/intro.md deleted file mode 100644 index ea521dd1f5..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/intro.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_label: "Ana sayfa" -sidebar_position: 1 ---- - -# Stacks Dokümanları Tanıtımı - -Topluluk odaklı resmi Stacks Dokümantasyonuna hoş geldiniz. - -Stacks madenciliği, STX token ve Clarity akıllı sözleşme dili hakkında bilgi edinin. - -![](/img/Bitcoinet-L_2.svg) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md b/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md deleted file mode 100644 index dd7194f504..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Stacks on DigitalOcean -description: A guide to setup Stacks on DigitalOcean -sidebar_position: 4 -tags: - - tutorial ---- - -## Introduction - -This is a step by step guide to deploy the [Stacks Blockchain on DigitalOcean](https://marketplace.digitalocean.com/apps/stacks-blockchain). Code is hosted on this [Github repository](https://github.com/stacks-network/stacks-blockchain-docker). - -## Steps - -#### Step 1 - -Go to the [Stacks Blockchain page](https://marketplace.digitalocean.com/apps/stacks-blockchain) in DigitalOcean's marketplace. Click on `Create Stacks Blockchain Droplet`. - -#### Step 2 - -Choose a plan (it will only allow you to select a plan that meets the minimum requirements) and your prefered datacenter region. ![](/img/sh_digitalocean-choose-plan.png) - -#### Step 3 - -Enter a root password or enable SSH keys if your prefer. - -![](/img/sh_digitalocean-choose-authentication.png) - -#### Step 4 - -You can leave the rest of the options as they are and click on `Create Droplet` - -#### Step 5 - -You will need to wait a few seconds for the droplet to get created. Once created click on it to see more information. - -![](/img/sh_digitalocean-creating-droplet.png) - -![](/img/sh_digitalocean-created-droplet.png) - -### Step 6 - -Congratulations! You are now running the Stacks Blockchain. You can click on `Console` for a terminal window to open or login using SSH to the public IP you've been assigned to with user `root`. - -![](/img/sh_digitalocean-console-button.png) ![](/img/sh_digitalocean-console.png) - -## Getting started after deploying Stacks Blockchain - -Once droplet is launched, initial startup can take several minutes while BNS data is imported (this is a one time operation). - -To keep track of the progress, you can `ssh root@your_droplet_public_ipv4` to the host and run: `/opt/stacks-blockchain-docker/manage.sh -n mainnet -a logs`. - -Once the stacks blockchain starts to sync with peers, application ports will open and nginx port 80 will now start proxying requests. - -Use `http://your_droplet_public_ipv4` to access the data directly, with output being similar to: - -```json -{ - "server_version": "stacks-blockchain-api v3.0.3 (master:cd0c8aef)", - "status": "ready", - "chain_tip": { - "block_height": 16220, - "block_hash": "0x3123fba9c0de6b569573494cf83c1d5d198a66bfd5f48ef97949b6bf11ba13be", - "index_block_hash": "0xeec960fbbd6186b4ccac85ce12adba72be497d881f81e077305c90955b51a6ae" - } -} -``` - -All services are managed by a [systemd unit file](https://github.com/stacksfoundation/stacks-machine-images/blob/master/files/etc/systemd/system/stacks.service) that is set to start on boot. - -Manual control is also possible via the [manage.sh script](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/manage.sh) at `/opt/stacks-blockchain-docker/manage.sh` on the host. - -Full details on how to use the manage.sh script is [available here](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/README.md#quickstart). - -## API Creation - -In addition to creating a Droplet from the Stacks Blockchain 1-Click App via the control panel, you can also use the [DigitalOcean API](https://digitalocean.com/docs/api). - -As an example, to create a 4GB Stacks Blockchain Droplet in the SFO2 region, you can use the following curl command. You’ll need to either save your [API access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/) to an environment variable or substitute it into the command below. - -```bash -curl -X POST -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer '$TOKEN'' -d \ - '{"name":"choose_a_name","region":"sfo2","size":"s-2vcpu-4gb","image":"stacksfoundation-stacksblockchain"}' \ - "https://api.digitalocean.com/v2/droplets" -``` diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md b/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md deleted file mode 100644 index b6cbb9754a..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Nodes and Miners -description: Nodes and Miners -sidebar_position: 7 ---- - -Here are all the steps to run nodes and miners, both on mainnet and testnet. - -## What's a Stacks node? - -## What's a Stacks miner? diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md b/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md deleted file mode 100644 index 40397a51e0..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Miner costs and fees -description: Miner Cost and Fee Estimation -sidebar_position: 8 ---- - -## Configuring Cost and Fee Estimation - -Fee and cost estimators can be configured via the config section `[fee_estimation]`: - -``` -[fee_estimation] -cost_estimator = naive_pessimistic -fee_estimator = fuzzed_weighted_median_fee_rate -fee_rate_fuzzer_fraction = 0.1 -fee_rate_window_size = 5 -cost_metric = proportion_dot_product -log_error = true -enabled = true -``` - -Fee and cost estimators observe transactions on the network and use the observed costs of those transactions to build estimates for viable fee rates and expected execution costs for transactions. Estimators and metrics can be selected using the configuration fields above, though the default values are the only options currently. `log_error` controls whether or not the INFO logger will display information about the cost estimator accuracy as new costs are observed. Setting `enabled = false` turns off the cost estimators. Cost estimators are **not** consensus-critical components, but rather can be used by miners to rank transactions in the mempool or client to determine appropriate fee rates for transactions before broadcasting them. - -The `fuzzed_weighted_median_fee_rate` uses a median estimate from a window of the fees paid in the last `fee_rate_window_size` blocks. Estimates are then randomly "fuzzed" using uniform random fuzz of size up to `fee_rate_fuzzer_fraction` of the base estimate. diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md b/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md deleted file mode 100644 index 061f4a2511..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md +++ /dev/null @@ -1,343 +0,0 @@ ---- -title: Mine mainnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 mainnet -sidebar_position: 5 -tags: - - tutorial ---- - -## Introduction - -Make sure you've followed the [run a node](run-a-node) procedure. Once completed it's only a few more steps to run a proof-of-burn miner on the mainnet. - -If you're interested in mining on the testnet, you can find instructions on how to do that [here](miner-testnet): - -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining): - -## Running bitcoind locally - -To participate as a miner on mainnet, you must have access to a mainnet bitcoin node. One way to accomplish this is to run bitcoind locally. [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements) - -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. - -Next, start bitcoind with the following configuration: - -```toml -server=1 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=1 -banscore=1 -bind=0.0.0.0:8333 -rpcbind=0.0.0.0:8332 -rpcport=8332 -``` - -Finally, start bitcoind as follows: - -```bash -bitcoind -conf=path/to/bitcoin.conf -``` - -It may take a few days for the node to synchronize with the Bitcoin mainnet. - -## Running a miner - -First, a keychain needs to be generated. With this keychain, we'll purchase some BTC from a crytpocurrency exchange, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. We'll use the `make_keychain` command. - -```bash -npx @stacks/cli make_keychain 2>/dev/null | json_pp > keychain.txt -``` - -After this runs, you should see some JSON in the new `keychain.txt` file that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -**Don't lose this information** - we'll need to use the `privateKey` field later on. - -The above BTC address will then need to be imported into the BTC network. - -```bash -bitcoin-cli -rpcport=8332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - - - -Once imported, we need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - - - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/mainnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `make_keychain` command. Replace the `seed` field with your private key. Save and close this configuration file. - -To run your miner, run this in the command line: - -```bash -stacks-node start --config=./testnet/stacks-node/conf/mainnet-miner-conf.toml -``` - -Your node should start. It will take some time to sync, and then your miner will be running. - -### Creating an optimized binary - -The steps above are great for trying to run a node temporarily. If you want to host a node on a server somewhere, you might want to generate an optimized binary. To do so, use the same configuration as above, but run: - -```bash -cd testnet/stacks-node -cargo build --release --bin stacks-node -``` - -The above code will compile an optimized binary. To use it, run: - -```bash -cd ../.. -./target/release/stacks-node start --config=./mainnet-miner-conf.toml -``` - -To read more about the technical details of mining on the Stacks 2.0 network, have a look at [the mining guide](../understand-stacks/mining). - -### Enable debug logging - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -STACKS_LOG_DEBUG=1 stacks-node mainnet -``` - -## Running a miner in Windows - -### Prerequisites - -Make sure are [running a node](run-a-node) and [running bitcoind locally](#running-bitcoind-locally) before starting this tutorial. - -### Generate keychain and get mainnet tokens in Windows - -To setup the miner, first we need to generate a keychain. With this keychain, we'll purchase some BTC from a crytpocurrency exchange, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. To get a keychain, the simplest way is to use the `stacks-cli`. - -Generate a keychain: - -```bash -npm install --global @stacks/cli -stx make_keychain > cli_keychain.json -type cli_keychain.json -``` - -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -The above BTC address will then need to be imported into the BTC network. - -```bash -bitcoin-cli -rpcport=8332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - -Once imported, we need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Update configuration file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/mainnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Run the miner - -To start your miner, run this in the command line: - -```bash -stacks-node start --config=testnet/stacks-node/conf/mainnet-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](/img/windows-defender.png) - -Your node should start. It will take some time to sync, and then your miner will be running. - -### Enable debug logging in Windows - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=mainnet-miner-conf.toml -``` - -## Optional: Running with Docker - -Alternatively, you can run the mainnet node with Docker. - -:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: - -### Generate keychain and get tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null -``` - -We need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Update configuration file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/mainnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Start the miner - -:::info The ENV VARS `RUST_BACKTRACE` and `STACKS_LOG_DEBUG` are optional. If removed, debug logs will be disabled ::: - -```bash -docker run -d \ - --name stacks_miner \ - --rm \ - --network host \ - -e RUST_BACKTRACE="full" \ - -e STACKS_LOG_DEBUG="1" \ - -v "$(pwd)/testnet/stacks-node/conf/mainnet-miner-conf.toml:/src/stacks-node/mainnet-miner-conf.toml" \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain:latest \ -/bin/stacks-node start --config /src/stacks-node/mainnet-miner-conf.toml -``` - -You can review the node logs with this command: - -```bash -docker logs -f stacks_miner -``` - -## Optional: Running in Kubernetes with Helm - -In addition, you're also able to run a mainnet node in a Kubernetes cluster using the [stacks-blockchain Helm chart](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). - -Ensure you have the following prerequisites installed on your machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [minikube](https://minikube.sigs.k8s.io/docs/start/) (Only needed if standing up a local Kubernetes cluster) -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [helm](https://helm.sh/docs/intro/install/) - -### Generate keychain and get some tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null -``` - -We need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Install the chart and run the miner - -To install the chart with the release name `my-release` and run the node as a miner: - -```bash -minikube start # Only run this if standing up a local Kubernetes cluster -helm repo add blockstack https://charts.blockstack.xyz -helm install my-release blockstack/stacks-blockchain \ - --set config.node.miner=true \ - --set config.node.seed="replace-with-your-privateKey-from-generate-keychain-step" \ - --set config.burnchain.mode="mainnet" -``` - -You can review the node logs with this command: - -```bash -kubectl logs -l app.kubernetes.io/name=stacks-blockchain -``` - -For more information on the Helm chart and configuration options, please refer to the [chart's homepage](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md b/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md deleted file mode 100644 index 56374190c1..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md +++ /dev/null @@ -1,336 +0,0 @@ ---- -title: Mine testnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 testnet -sidebar_position: 4 -tags: - - tutorial ---- - -## Introduction - -Make sure you've followed the [Run a node](run-a-node) procedure. Once completed it's only a few more steps to run a proof-of-burn miner on the testnet. - -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining). - -## Running bitcoind locally - -To participate as a miner on Testnet, you must have access to a testnet bitcoin node. One way to accomplish this is to run bitcoind locally. [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements) - -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. - -Next, start bitcoind with the following configuration: - -```toml -server=1 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password -testnet=1 -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=1 -banscore=1 - -[test] -bind=0.0.0.0:18333 -rpcbind=0.0.0.0:18332 -rpcport=18332 -``` - -Finally, start bitcoind as follows: - -```bash -bitcoind -conf=path/to/bitcoin.conf -``` - -It may take a few hours for the node to synchronize with the Bitcoin testnet. - -## Running a miner - -First, a keychain needs to be generated. With this keychain, we'll get some testnet BTC from a faucet, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. To get a keychain, the simplest way is to use the `stacks-cli`. - -```bash -npx @stacks/cli make_keychain -t 2>/dev/null | json_pp > keychain.txt -``` - -After this runs, you should see some JSON in the new `keychain.txt` file that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -**Don't lose this information** - we'll need to use the `privateKey` field later on. - -The above BTC address will then need to be imported into the BTC testnet network. - -```bash -bitcoin-cli -rpcport=18332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - -Once imported, we need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). You'll be sent `0.01` testnet BTC to that address. - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/testnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/testnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `make_keychain` command. Replace the `seed` field with your private key. Save and close this configuration file. - -To run your miner, run this in the command line: - -```bash -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. - -### Creating an optimized binary - -The steps above are great for trying to run a node temporarily. If you want to host a node on a server somewhere, you might want to generate an optimized binary. To do so, use the same configuration as above, but run: - -```bash -cd testnet/stacks-node -cargo build --release --bin stacks-node -``` - -The above code will compile an optimized binary. To use it, run: - -```bash -cd ../.. -./target/release/stacks-node start --config=./testnet/conf/testnet-follower-conf.toml -``` - -To read more about the technical details of mining on the Stacks 2.0 network, have a look at [the minig guide](../understand-stacks/mining): - -### Enable debug logging - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -STACKS_LOG_DEBUG=1 stacks-node testnet -``` - -## Running a miner in Windows - -### Prerequisites - -Make sure are [running a testnet node](run-a-node) before starting this tutorial. - -### Generate keychain and get testnet tokens in Windows - -To setup the miner, first, we need to generate a keychain. With this keychain, we'll get some testnet BTC from a faucet, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. We'll use the `stx make-keychain` command, and pass `-t` to indicate that we want a testnet keychain. - -Generate a keychain: - -```bash -npm install --global @stacks/cli -stx make_keychain -t > cli_keychain.json -type cli_keychain.json -``` - -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -Request BTC from faucet: - -We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). - -### Update configuration file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/testnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/testnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Run the miner - -To start your miner, run this in the command line: - -```bash -stacks-node start --config=testnet/stacks-node/conf/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](/img/windows-defender.png) - - - -Your node should start. It will take some time to sync, and then your miner will be running. - -### Enable debug logging in Windows - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=testnet-miner-conf.toml -``` - -## Optional: Running with Docker - -Alternatively, you can run the testnet node with Docker. - -:::warning Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: - -### Generate keychain and get testnet tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` - -We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). - -### Update config file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/testnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/testnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Start the miner - -:::info The ENV VARS `RUST_BACKTRACE` and `STACKS_LOG_DEBUG` are optional. If removed, debug logs will be disabled ::: - -```bash -docker run -d \ - --name stacks_miner \ - --rm \ - --network host \ - -e RUST_BACKTRACE="full" \ - -e STACKS_LOG_DEBUG="1" \ - -v "$(pwd))/testnet/stacks-node/conf/testnet-miner-conf.toml:/src/stacks-node/testnet-miner-conf.toml" \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain:latest \ -/bin/stacks-node start --config /src/stacks-node/testnet-miner-conf.toml -``` - -You can review the node logs with this command: - -```bash -docker logs -f stacks_miner -``` - -## Optional: Running in Kubernetes with Helm - -In addition, you're also able to run a testnet node in a Kubernetes cluster using the [stacks-blockchain Helm chart](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). - -Ensure you have the following prerequisites installed on your machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [minikube](https://minikube.sigs.k8s.io/docs/start/) (Only needed if standing up a local Kubernetes cluster) -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [helm](https://helm.sh/docs/intro/install/) - -### Generate keychain and get some testnet tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` - -We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). - -### Install the chart and run the miner - -To install the chart with the release name `my-release` and run the node as a miner: - -```bash -minikube start # Only run this if standing up a local Kubernetes cluster -helm repo add blockstack https://charts.blockstack.xyz -helm install my-release blockstack/stacks-blockchain \ - --set config.node.miner=true \ - --set config.node.seed="replace-with-your-privateKey-from-generate-keychain-step" -``` - -You can review the node logs with this command: - -```bash -kubectl logs -l app.kubernetes.io/name=stacks-blockchain -``` - -For more information on the Helm chart and configuration options, please refer to the [chart's homepage](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md b/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md deleted file mode 100644 index 94d938c5ca..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md +++ /dev/null @@ -1,351 +0,0 @@ ---- -title: Run a node -description: Set up and run a Stacks node -sidebar_position: 1 -tags: - - tutorial ---- - -## Stacks Blockchain with Docker - -Run your own Stacks Blockchain node easily with just few commands. - -This tutorial describes a simple and effective [quickstart](#quickstart) to run a Stacks node using public scripts hosted in [Stacks Blockchain repository](https://github.com/stacks-network/stacks-blockchain-docker). Valid for mainnet, testnet and mocknet. - -## **Quickstart** - -1. **Clone the stacks-blockchain-docker repository locally** - -```bash -git clone https://github.com/stacks-network/stacks-blockchain-docker && cd stacks-blockchain-docker -``` - -2. **Optionally, create/copy `.env` file**. If file `.env` doesn't exist when launched it will be created from `sample.env` automatically. - -```bash -cp sample.env .env -``` - -_You may also use a symlink as an alternative to copying: `ln -s sample.env .env`_ - -3. **Optionally, ensure all images are up to date** - -```bash -./manage.sh -n -a pull -``` - -4. **Start the Services** - -```bash -./manage.sh -n -a start -``` - -- With optional proxy: - -```bash -./manage.sh -n -a start -f proxy -``` - -- With optional bitcoin node: - -```bash -./manage.sh -n -a start -f bitcoin -``` - -5. **Stop the Services** - -```bash -./manage.sh -n -a stop -``` - -6. **Retrieve Service Logs** - -```bash -./manage.sh -n -a logs -``` - -- Export docker log files to `./exported-logs`: - -This will create one log file for every running service, for example: postgres.log, stacks-blockain.log, stacks-blockchain-api.log and bitcoin-core.log. -Notice that each time you run this command the log files will be overwritten. - -```bash -./manage.sh -n -a logs export -``` - -7. **Restart all services** - -```bash -./manage.sh -n -a restart -``` - -- With optional proxy: - -```bash -./manage.sh -n -a restart -f proxy -``` - -8. **Delete** all data in `./persistent-data/` and/or data of the Bitcoin blockchain. - - This data is owned by root, so you will need to run it with sudo privileges so it can delete the data. - -```bash -$ sudo ./manage.sh -n -a reset - -Please confirm what persistent data you wish to delete: - -0. Cancel -1. Delete Persistent data for Stacks testnet only and leave Bitcoin blockchain data unaffected. -2. Delete Persistent data for Stacks testnet and Bitcoin blockchain data in ./persistent-data/blockchain-bitcoin -3. Delete Persistent data for Bitcoin blockchain data in ./persistent-data/blockchain-bitcoin only. -Please note that BNS data will never get deleted. - -Type 0, 1, 2 or 3: 2 - -Ok. Delete Stacks and Bitcoin data. -[ Success ] Persistent data deleted for Bitcoin blockchain. -[ Success ] Persistent data deleted for Stacks testnet. - -``` - -9. **Download BNS data to** `./persistent-data/bns-data` - -```bash -./manage.sh bns -``` - -10. **Export stacks-blockchain-api events** (_Not applicable for mocknet_) - -```bash -./manage.sh -n -a export -# check logs for completion -./manage.sh -n -a restart -``` - -11. **Replay stacks-blockchain-api events** (_Not applicable for mocknet_) - -```bash -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart -``` - -## **Running also a bitcoin node (Optional)** - -Stacks needs to use a Bitcoin node, and by default when you run a Stacks node you will be using a public Bitcoin node, which is configured in the `.env` file. Default values is `BITCOIN_NODE=bitcoin.mainnet.stacks.org`. - -However, you can optionaly run both nodes together and configured in a way that you Stacks node will use your own Bitcoin node instead of a public one. - -If you run the script with a bitcoin node it will download and build it directly from source for increased security. This process which only needs to happen once can take up to 20-30 minutes depending on the speed of your system. Also, once the bitcoin node is up and running it will need an additional time for sync for the first time (can be hours for testnet and days for mainnet). - -### Why run Stacks node with your own Bitcoin node? - -Because running your own Bitcoin node will give you higher security and improved perfomance. - -* **Improved perfomance**: The Bitcoin node will serve you blocks faster, as well as UTXOs for your miner (if you run one). -* **Higher security**: The Bitcoin node will also have validated all bitcoin transactions the Stacks node consumes. If you don't run your own Bitcoin node, you're relying on the SPV headers to vouch for the validity of Bitcoin blocks. - -The disadvantage of running your own Bitcoin node is that you need the extra space to store the Bitcoin blockchain (about 500GB) and the initial time it will take to download this data the first time. - -### Example - -You can run easily run your Stacks node with your own Bitcoin node by adding the flag `bitcoin`. This is available only for testnet and mainnet. - -Example: `./manage.sh -n mainnet -a start -f bitcoin` or `./manage.sh -n testnet -a start -f bitcoin` - -### Bitcoin node configuration - -In the `.env` file there is the variable `BITCOIN_BLOCKCHAIN_FOLDER`. As the bitcoin blockchain can be large (over 500GB) you optionally change this variable to any location of your choosing. If you have previously used the [bitcoin core application](https://bitcoin.org/en/bitcoin-core/) and already have the bitcoin blockchain synced, you can use the same data folder and avoid redownloading the entire bitcoin blockchain. - -## **Accessing the services** - -:::tip For networks other than `mocknet`, downloading the initial headers can take several minutes. Until the headers are downloaded, the `/v2/info` endpoints won't return any data. - -Use the command `./manage.sh -n -a logs` to check the sync progress. ::: - -**stacks-blockchain**: - -- Ports `20443-20444` are exposed to `localhost` - -```bash -curl -sL localhost:20443/v2/info | jq -``` - -**stacks-blockchain-api**: - -- Port `3999` are exposed to `localhost` - -```bash -curl -sL localhost:3999/v2/info | jq -``` - -**proxy**: - -- Port `80` is exposed to `localhost` - -```bash -curl -sL localhost/v2/info | jq -curl -sL localhost/ | jq -``` - ---- - -## Upgrades - -⚠️ For upgrades to running instances of this repo, you'll need to [run the event-replay](https://github.com/hirosystems/stacks-blockchain-api#event-replay): - -```bash -./manage.sh -n -a stop -./manage.sh -n -a export -./manage.sh -n -a import -./manage.sh -n -a restart -``` - ---- - -## **Workarounds to potential issues** - -_**Port(s) already in use**_: - -- 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. `3999` and edit your `.env` file to use the new port. - -```bash -netstat -anl | grep 3999 -``` - -``` -tcp46 0 0 *.3999 *.* LISTEN -``` - -_**Containers not starting (hanging on start)**_: - -- Occasionally, docker can get **stuck** and not allow new containers to start. If this happens, simply restart your docker daemon and try again. - -_**Database Issues**_: - -- For any of the various Postgres/sync issues, it may be easier to simply remove the persistent data dir. Note that doing so will result in a longer startup time as the data is repopulated. - -```bash -./manage.sh -n -a stop -./manage.sh -n -a reset -./manage.sh -n -a start -``` - -_**API Missing Parent Block Error**_: - -- If the Stacks blockchain is no longer syncing blocks, and the API reports an error similar to this:\ - `Error processing core node block message DB does not contain a parent block at height 1970 with index_hash 0x3367f1abe0ee35b10e77fbcaa00d3ca452355478068a0662ec492bb30ee0f13e"`,\ - The API (and by extension the DB) is out of sync with the blockchain. \ - The only known method to recover is to resync from genesis (**event-replay _may_ work, but in all likelihood will restore data to the same broken state**). - -- To attempt the event-replay - -```bash -./manage.sh -n -a stop -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart -``` - -- To wipe data and re-sync from genesis - -```bash -./manage.sh -n -a stop -./manage.sh -n -a reset -./manage.sh -n -a restart -``` - - -## **Requirements:** - -- [Docker](https://docs.docker.com/get-docker/) >= `17.09` -- [docker-compose](https://github.com/docker/compose/releases/) >= `1.27.4` -- [git](https://git-scm.com/downloads) -- [jq binary](https://stedolan.github.io/jq/download/) -- [sed](https://www.gnu.org/software/sed/) -- Machine with (at a minimum): - - 4GB memory - - 1 Vcpu - - 50GB storage (600GB if you optionally also run the bitcoin mainnet node) - -:::caution MacOS with an M1 processor is NOT recommended - -The way Docker for Mac on an Arm chip is designed makes the I/O incredibly slow, and blockchains are **_very_** heavy on I/O. This only seems to affect MacOS, other Arm based systems like Raspberry Pi's seem to work fine. - -::: - - -### Install/Update docker-compose - -:::note `docker-compose` executable is required, even though recent versions of Docker contain `compose` natively ::: - -- [Install Docker-compose](https://docs.docker.com/compose/install/) -- [Docker Desktop for Mac](https://docs.docker.com/docker-for-mac/install/) -- [Docker Desktop for Windows](https://docs.docker.com/docker-for-windows/install/) -- [Docker Engine for Linux](https://docs.docker.com/engine/install/#server) - -First, check if you have `docker-compose` installed locally. - -To do that, run this command in your terminal : - -```bash -docker-compose --version -``` - -Output should look something very similar to this : - -``` -docker-compose version 1.27.4, build 40524192 -``` - -If the command is not found, or the version is < `1.27.4`, run the following to install the latest to `/usr/local/bin/docker-compose`: - -```bash -#You will need to have jq installed, or this snippet won't run. -VERSION=$(curl --silent https://api.github.com/repos/docker/compose/releases/latest | jq .name -r) -DESTINATION=/usr/local/bin/docker-compose -sudo curl -L https://github.com/docker/compose/releases/download/${VERSION}/docker-compose-$(uname -s)-$(uname -m) -o $DESTINATION -sudo chmod 755 $DESTINATION -``` - -### Security note on docker - -The Docker daemon always runs as the root user so by default you will need root privileges to interact with it. - -The script `manage.sh` uses docker, so to avoid the requirement of needing to run the script with root privileges it is prefered to be able to *manage Docker as a non-root user*, following [these simple tests](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user). - -This will avoid the need of running the script with root privileges for all operations except the removal of data. - -### Configuration files you can edit - -The following files can be modified to personalize your node configuration, but generally most of them should be left as-is. All these files will be created from the sample copy if they don't exist at runtime (for example `.env` is created from `sample.env`). However these files will never be modified by the application once created and will never be pushed back to github, so your changes will be safe. - -* `.env` -* `./conf/mainnet/Config.toml` -* `./conf/mainnet/bitcoin.conf` -* `./conf/testnet/Config.toml` -* `./conf/testnet/bitcoin.conf` - -By default: - -- BNS data is **not** enabled/imported - - To enable, uncomment `# BNS_IMPORT_DIR=/bns-data` in `./env` - - Download BNS data: `./manage.sh bns` -- Fungible token metadata is **not** enabled - - To enable, uncomment `# STACKS_API_ENABLE_FT_METADATA=1` in `./env` -- Non-Fungible token metadata is **not** enabled - - To enable, uncomment `# STACKS_API_ENABLE_NFT_METADATA=1` in `./env` -- Verbose logging is **not** enabled - - To enable, uncomment `# VERBOSE=true` in `./env` -- Bitcoin blockchain folder is configured in `BITCOIN_BLOCKCHAIN_FOLDER` in `./env` - -### Local Data Dirs - -Directories will be created on first start that will store persistent data under `./persistent-data/` - -`` can be 1 of: - -- mainnet -- testnet -- mocknet diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md b/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md deleted file mode 100644 index 09db354d0d..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md +++ /dev/null @@ -1,188 +0,0 @@ ---- -title: Running a mainnet node -description: Set up and run a mainnet node with Docker -sidebar_position: 3 -tags: - - tutorial ---- - -## Introduction - -This procedure demonstrates how to run a local mainnet node using Docker images. - -:::caution -This procedure focuses on Unix-like operating systems (Linux and MacOS). This procedure has not been tested on Windows. -::: - -## Prerequisites - -Running a node has no specialized hardware requirements. Users have been successful in running nodes on Raspberry Pi boards and other system-on-chip architectures. In order to complete this procedure, you must have the following software installed on the node host machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [curl](https://curl.se/download.html) -- [jq](https://stedolan.github.io/jq/download/) - -### Firewall configuration - -In order for the API node services to work correctly, you must configure any network firewall rules to allow traffic on the ports discussed in this section. The details of network and firewall configuration are highly specific to your machine and network, so a detailed example isn't provided. - -The following ports must open on the host machine: - -Ingress: - -- stacks-blockchain (open to `0.0.0.0/0`): - - `20443 TCP` - - `20444 TCP` - -Egress: - -- `8332` -- `8333` -- `20443-20444` - -These egress ports are for syncing stacks-blockchain and Bitcoin headers. If they're not open, the sync will fail. - -## Step 1: initial setup - -In order to run the mainnet node, you must download the Docker images and create a directory structure to hold the persistent data from the services. Download and configure the Docker images with the following commands: - -```sh -docker pull blockstack/stacks-blockchain -``` - -Create a directory structure for the service data with the following command: - -```sh -mkdir -p ./stacks-node/{persistent-data/stacks-blockchain/mainnet,config/mainnet} && cd stacks-node -``` - -## Step 2: running Stacks blockchain - -First, create the `./config/mainnet/Config.toml` file and add the following content to the file using a text editor: - -```toml -[node] -working_dir = "/root/stacks-node/data" -rpc_bind = "0.0.0.0:20443" -p2p_bind = "0.0.0.0:20444" -bootstrap_node = "02da7a464ac770ae8337a343670778b93410f2f3fef6bea98dd1c3e9224459d36b@seed-0.mainnet.stacks.co:20444,02afeae522aab5f8c99a00ddf75fbcb4a641e052dd48836408d9cf437344b63516@seed-1.mainnet.stacks.co:20444,03652212ea76be0ed4cd83a25c06e57819993029a7b9999f7d63c36340b34a4e62@seed-2.mainnet.stacks.co:20444" -wait_time_for_microblocks = 10000 - -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "bitcoin.blockstack.com" -username = "blockstack" -password = "blockstacksystem" -rpc_port = 8332 -peer_port = 8333 - -[connection_options] -read_only_call_limit_write_length = 0 -read_only_call_limit_read_length = 100000 -read_only_call_limit_write_count = 0 -read_only_call_limit_read_count = 30 -read_only_call_limit_runtime = 1000000000 -``` - -Start the `stacks-blockchain` container with the following command: - -```sh -docker run -d --rm \ - --name stacks-blockchain \ - -v $(pwd)/persistent-data/stacks-blockchain/mainnet:/root/stacks-node/data \ - -v $(pwd)/config/mainnet:/src/stacks-node \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain \ -/bin/stacks-node start --config /src/stacks-node/Config.toml -``` - -You can verify the running `stacks-blockchain` container with the command: - -```sh -docker ps --filter name=stacks-blockchain -``` - -## Step 3: verifying the services - -:::note -The initial burnchain header sync can take several minutes, until this is done the following commands will not work -::: - -To verify the `stacks-blockchain` burnchain header sync progress: - -```sh -docker logs stacks-blockchain -``` - -The output should be similar to the following: - -``` -INFO [1626290705.886954] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.2% (8000 out of 691034) -INFO [1626290748.103291] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.4% (10000 out of 691034) -INFO [1626290776.956535] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.7% (12000 out of 691034) -``` - -To verify the `stacks-blockchain` tip height is progressing use the following command: - -```sh -curl -sL localhost:20443/v2/info | jq -``` - -If the instance is running you should recieve terminal output similar to the following: - -```json -{ - "peer_version": 402653184, - "pox_consensus": "89d752034e73ed10d3b97e6bcf3cff53367b4166", - "burn_block_height": 666143, - "stable_pox_consensus": "707f26d9d0d1b4c62881a093c99f9232bc74e744", - "stable_burn_block_height": 666136, - "server_version": "stacks-node 2.0.11.1.0-rc1 (master:67dccdf, release build, linux [x86_64])", - "network_id": 1, - "parent_network_id": 3652501241, - "stacks_tip_height": 61, - "stacks_tip": "e08b2fe3dce36fd6d015c2a839c8eb0885cbe29119c1e2a581f75bc5814bce6f", - "stacks_tip_consensus_hash": "ad9f4cb6155a5b4f5dcb719d0f6bee043038bc63", - "genesis_chainstate_hash": "74237aa39aa50a83de11a4f53e9d3bb7d43461d1de9873f402e5453ae60bc59b", - "unanchored_tip": "74d172df8f8934b468c5b0af2efdefe938e9848772d69bcaeffcfe1d6c6ef041", - "unanchored_seq": 0, - "exit_at_block_height": null -} -``` - -## Stopping the mainnet node - -Use the following commands to stop the local mainnet node: - -```sh -docker stop stacks-blockchain -``` - -## Optional. Run stacks node with own bitcoin node - -It's encouraged to use your own bitcoin node when possible. - -To do this simply update the `stacks-node/config/mainnet/Config.toml` file with the details of your bitcoin node. For example: - -``` -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "localhost" -username = "rpc username" -password = "rpc password" -rpc_port = 8332 -peer_port = 8333 -``` - -The rpc configuration of your bitcoin node is out of the scope of this document, but you can find more information on how to set it up [here](https://developer.bitcoin.org/examples/intro.html). - -## Additional reading - - - -- [Running a Stacks API node](https://docs.hiro.so/get-started/running-api-node) -- [Running a Stacks testnet node](running-testnet-node) - diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md b/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md deleted file mode 100644 index da01ce2ea1..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: Running a testnet node -description: Set up and run a testnet node with Docker -sidebar_position: 2 -tags: - - tutorial ---- - -## Introduction - -This procedure demonstrates how to run a local testnet node using Docker images. - -:::caution -This procedure focuses on Unix-like operating systems (Linux and MacOS). This procedure has not been tested on Windows. -::: - -## Prerequisites - -Running a node has no specialized hardware requirements. Users have been successful in running nodes on Raspberry Pi boards and other system-on-chip architectures. In order to complete this procedure, you must have the following software installed on the node host machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [curl](https://curl.se/download.html) -- [jq](https://stedolan.github.io/jq/download/) - -### Firewall configuration - -In order for the API node services to work correctly, you must configure any network firewall rules to allow traffic on the ports discussed in this section. The details of network and firewall configuration are highly specific to your machine and network, so a detailed example isn't provided. - -The following ports must open on the host machine: - -Ingress: - -- stacks-blockchain (open to `0.0.0.0/0`): - - `20443 TCP` - - `20444 TCP` - -Egress: - -- `18332` -- `18333` -- `20443-20444` - -These egress ports are for syncing stacks-blockchain and Bitcoin headers. If they're not open, the sync will fail. - -## Step 1: initial setup - -In order to run the testnet node, you must download the Docker images and create a directory structure to hold the persistent data from the services. Download and configure the Docker images with the following commands: - -```sh -docker pull blockstack/stacks-blockchain -``` - -Create a directory structure for the service data with the following command: - -```sh -mkdir -p ./stacks-node/persistent-data/stacks-blockchain/testnet && cd stacks-node -``` - -## Step 2: running Stacks blockchain - -Start the stacks-blockchain container with the following command: - -```sh -docker run -d --rm \ - --name stacks-blockchain \ - -v $(pwd)/persistent-data/stacks-blockchain/testnet:/root/stacks-node/data \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain \ -/bin/stacks-node testnet -``` - -You can verify the running stacks-blockchain container with the command: - -```sh -docker ps --filter name=stacks-blockchain -``` - -## Step 3: verifying the services - -:::info -The initial burnchain header sync can take several minutes, until this is done the following commands will not work -::: - -To verify the stacks-blockchain burnchain header sync progress: - -```sh -docker logs stacks-blockchain -``` - -The output should be similar to the following: - -``` -INFO [1626290705.886954] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.2% (8000 out of 2034380) -INFO [1626290748.103291] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.4% (10000 out of 2034380) -INFO [1626290776.956535] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.7% (12000 out of 2034380) -``` - -To verify the stacks-blockchain tip height is progressing use the following command: - -```sh -curl -sL localhost:20443/v2/info | jq -``` - -If the instance is running you should recieve terminal output similar to the following: - -```json -{ - "peer_version": 4207599105, - "pox_consensus": "12f7fa85e5099755a00b7eaecded1aa27af61748", - "burn_block_height": 2034380, - "stable_pox_consensus": "5cc4e0403ff6a1a4bd17dae9600c7c13d0b10bdf", - "stable_burn_block_height": 2034373, - "server_version": "stacks-node 2.0.11.2.0-rc1 (develop:7b6d3ee+, release build, linux [x86_64])", - "network_id": 2147483648, - "parent_network_id": 118034699, - "stacks_tip_height": 509, - "stacks_tip": "e0ee952e9891709d196080ca638ad07e6146d4c362e6afe4bb46f42d5fe584e8", - "stacks_tip_consensus_hash": "12f7fa85e5099755a00b7eaecded1aa27af61748", - "genesis_chainstate_hash": "74237aa39aa50a83de11a4f53e9d3bb7d43461d1de9873f402e5453ae60bc59b", - "unanchored_tip": "32bc86590f11504f17904ee7f5cb05bcf71a68a35f0bb3bc2d31aca726090842", - "unanchored_seq": 0, - "exit_at_block_height": null -} -``` - -## Stopping the testnet node - -Use the following commands to stop the local testnet node: - -```sh -docker stop stacks-blockchain -``` - -## Additional reading - - - -- [Running a Stacks API node](https://docs.hiro.so/get-started/running-api-node) -- [Running a Stacks mainnet node](running-mainnet-node) - diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md b/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md deleted file mode 100644 index 89af343dc6..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md +++ /dev/null @@ -1,506 +0,0 @@ ---- -title: Stacks Node Configuration -description: Configuration parameters and options for the stacks-node binary -sidebar_position: 6 ---- - -## Usage - -```bash -stacks-node sub-command [--subcommand-option ] -``` - -## Subcommands - -:::caution The `stacks-node` binary may have deprecated commands that are not documented on this page. Deprecated commands may be accessible until they are fully removed from the sources. ::: - -### mocknet - -Start a node based on a fast local setup emulating a burnchain. Ideal for smart contract development. - -Example: - -```bash -stacks-node mocknet -``` - -### krypton - -Start a node that will join and stream blocks from the public krypton regtest, powered by Blockstack via [Proof of Transfer](../understand-stacks#consensus-mechanism). - -Example: - -```bash -stacks-node krypton -``` - -### testnet - -Start a node that will join and stream blocks from the public testnet. - -Example: - -```bash -stacks-node testnet -``` - -### mainnet - -Start a node that joins and streams blocks from the public mainnet. - -Example: - -```bash -stacks-node mainnet -``` - -### start - -Start a node with a config of your own. Can be used for joining a network, starting a new chain, or replacing default values used by the `mocknet` or `testnet` subcommands. - -#### Arguments - -**--config**: relative or absolute path to the TOML config file. Required. - -Example: - -```bash -stacks-node start --config=/path/to/config.toml -``` - -See [Configuration File Options](#configuration-file-options) for more information. - -#### version - -Displays information about the current version and the release cycle. - -Example: - -```bash -stacks-node version -``` - -#### help - -Displays a help message. - -Example: - -```bash -stacks-node help -``` - -## Configuration File Options - -The TOML configuration file has multiple sections under which an option may be placed. - -To see a list of example configurations, [please see this page](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf). - -### Section: node - -Contains various configuration options pertaining to the stacks-node. - -Example: - -```toml -[node] -rpc_bind = "0.0.0.0:20443" -p2p_bind = "0.0.0.0:20444" -# Enter your private key here -seed = "replace-with-your-private-key" -miner = true -``` - -#### working_dir (optional) - -Absolute path to the directory which the stacks-node will use for storing various data. - -Example: - -```toml -working_dir = "/root/stacks-node" -``` - -#### rpc_bind - -Address and port stacks-node should bind to for RPC connections. - -Example: - -```toml -rpc_bind = "0.0.0.0:20443" -``` - -#### p2p_bind - -Address and port stacks-node should bind to for P2P connections. - -Example: - -```toml -p2p_bind = "0.0.0.0:20444" -``` - -#### data_url (optional) - -Address and port from which the stacks-node will be receiving incoming rpc connections. - -Example: - -```toml -data_url = "1.2.3.4:20443" -``` - -#### p2p_address (optional) - -Address and port from which the stacks-node will be receiving incoming p2p connections. - -Example: - -```toml -p2p_address = "1.2.3.4:20444" -``` - -#### bootstrap_node (optional) - -Public key, address, and port stacks-node should use to pull transaction data from when starting. - -Example: - -```toml -bootstrap_node = "047435c194e9b01b3d7f7a2802d6684a3af68d05bbf4ec8f17021980d777691f1d51651f7f1d566532c804da506c117bbf79ad62eea81213ba58f8808b4d9504ad@testnet.blockstack.org:20444" -``` - -#### wait_time_for_microblocks (optional) - -The amount of time (in milliseconds) that a node will wait before trying to mine a block, after catching up to the anchored chain tip. This gives the current leader time to broadcast microblocks that will get included in that mined block. - -Example: - -```toml -wait_time_for_microblocks = 15000 -``` - -#### seed (optional) - -The private key to use for mining. Only needed if `miner` is set to `true`. - -Example: - -```toml -seed = "replace-with-your-private-key" -``` - -#### local_peer_seed (optional) - -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. - -Example: - -```toml -local_peer_seed = "replace-with-your-private-key" -``` - -#### miner (optional) - -Determines whether the stacks-node is running a follower (`false`) or a miner (`true`). Defaults to `false` if omitted. - -Example: - -```toml -miner = true -``` - -#### mine_microblocks (optional) - -Determines whether the stacks-node will mine microblocks. Will only take effect if `miner` is set to `true`. - -Example: - -```toml -mine_microblocks = true -``` - -#### prometheus_bind (optional) - -Address and port stacks-node should open for Prometheus metrics collection. - -Example: - -```toml -prometheus_bind = "0.0.0.0:9153" -``` - -### Section: events_observer (optional) - -Contains options for watching events emitted by a local [stacks-blockchain-api](https://github.com/hirosystems/stacks-blockchain-api) service. - -:::info -This section can be repeated multiple times. -::: - -Example: - -```toml -[[events_observer]] -endpoint = "address-to-my-local.stacks-node-api.com:3700" -retry_count = 255 -events_keys = ["*"] -``` - -#### endpoint - -Address and port to a stacks-node-api to watch for events. - -Example: - -```toml -endpoint = "address-to-my-local.stacks-node-api.com:3700" -``` - -#### retry_count - -Number of times to retry sending events to the endpoint before failing. - -Example: - -```toml -retry_count = 255 -``` - -#### events_keys - -Event keys for which to watch. The emitted node events can be restricted by account, function name and event type. Asterix ("\*") can be used to emit all events. - -Examples: - -```toml -events_keys = ["*"] -``` - -```toml -events_keys = [ - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.store::print", - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.contract.ft-token", - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.contract.nft-token", - "stx" -] -``` - -### Section: connection_options (optional) - -Specifies configuration options for others connecting to the stacks node. - -Example: - -```toml -[connection_options] -public_ip_address = "1.2.3.4:20444" -download_interval = 60 -walk_interval = 30 -``` - -#### public_ip_address - -The advertised public IP of this stacks-node. - -Example: - -```toml -public_ip_address = "1.2.3.4:20444" -``` - -#### download_interval - -Time (in seconds) between attempts to download blocks. - -Example: - -```toml -download_interval = 60 -``` - -#### walk_interval - -Time (in seconds) between attempts to walk the neighborhood. - -Example: - -```toml -walk_interval = 30 -``` - -#### read_only_call_limit_read_length - -Total number of bytes allowed to be read by an individual read-only function call. - -Example: - -```toml -read_only_call_limit_read_length = 100000 -``` - -#### read_only_call_limit_read_count - -Total number of independent read operations permitted for an individual read-only function call. - -Example: - -```toml -read_only_call_limit_read_count = 30 -``` - -#### read_only_call_limit_runtime - -[Runtime cost](https://github.com/stacksgov/sips/blob/2d3fd9bf8da7a04f588d90ff6252173d7609d7bf/sips/sip-006/sip-006-runtime-cost-assessment.md#introduction) limit for an individual read-only function call. - -Example: - -```toml -read_only_call_limit_runtime = 1000000000 -``` - -### Section: burnchain - -This section contains configuration options pertaining to the blockchain the stacks-node binds to on the backend for proof-of-transfer (BTC). - -Example: - -```toml -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "your.bitcoind.node.org" -rpc_port = 8332 -peer_port = 8333 -``` - -#### chain - -The blockchain stacks-node binds to on the backend for proof-of-transfer. Only value supported: `"bitcoin"`. - -Example: - -```toml -chain = "bitcoin" -``` - -#### mode - -The profile or test phase of which to run stacks-node. Valid values are `"mocknet"`, `"helium"`, `"neon"`, `"argon"`, `"krypton"`, `"xenon"`. - -Example: - -```toml -mode = "xenon" -``` - -#### peer_host - -Domain name of the host running the backend Bitcoin blockchain. It's required to either run a personal Bitcoin node locally, or to use a publicly hosted Bitcoin node. - -Example: - -```toml -peer_host = "your.bitcoind.node.org" -``` - -#### rpc_port - -peer_host's port stacks-node will connect to for RPC connections. - -Example: - -```toml -rpc_port = 8332 -``` - -#### peer_port - -peer_host's port stacks-node will connect to for P2P connections. - -Example: - -```toml -peer_port = 8333 -``` - -#### burn_fee_cap (optional) - -Maximum amount (in Satoshis) of "burn commitment" to broadcast for the next block's leader election. - -Example: - -```toml -burn_fee_cap = 30000 -``` - -#### satoshis_per_byte (optional) - -Amount (in Satoshis) per [virtual byte](https://en.bitcoin.it/wiki/Weight_units). This is used to compute the transaction fees. - -Example: - -```toml -satoshis_per_byte = 50 -``` - -So total transaction cost would be `(estimated_tx_size * satoshis_per_byte) + burn_fee_cap`. - -#### commit_anchor_block_within (optional) - -Sets the time period (in milliseconds) for commitments. Only used when `mode` is set to `"helium"`. - -Example: - -```toml -commit_anchor_block_within = 10000 -``` - -### Section: ustx_balance (testnet/regtest only) - -This section contains configuration options pertaining to the genesis block allocation for an address in micro-STX. If a user changes these values, their node may be in conflict with other nodes on the network and find themselves unable to sync with other nodes. - -:::info -This section can repeat multiple times, and thus is in double-brackets. Each section can define only one address. This section is ignored if running a node on mainnet. -::: - -Example: - -```toml -[[ustx_balance]] -address = "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6" -amount = 10000000000000000 - -[[ustx_balance]] -address = "ST11NJTTKGVT6D1HY4NJRVQWMQM7TVAR091EJ8P2Y" -amount = 10000000000000000 - -[[ustx_balance]] -address = "ST1HB1T8WRNBYB0Y3T7WXZS38NKKPTBR3EG9EPJKR" -amount = 10000000000000000 - -[[ustx_balance]] -address = "STRYYQQ9M8KAF4NS7WNZQYY59X93XEKR31JP64CP" -amount = 10000000000000000 -``` - -#### address - -Address which maintains a micro-STX balance. - -Example: - -```toml -address = "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6" -``` - -#### amount - -The balance of micro-STX given to the address at the start of the node. - -Example: - -```toml -amount = 10000000000000000 -``` diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md b/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md deleted file mode 100644 index 094e3f03a1..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Verify Miner -description: Verify node is operating as miner -sidebar_position: 7 ---- - -You can verify that your node is operating as a miner by checking its log output to verify that it was able to find its Bitcoin UTXOs: - -```bash -$ head -n 100 /path/to/your/node/logs | grep -i utxo -INFO [1630127492.031042] [testnet/stacks-node/src/run_loop/neon.rs:146] [main] Miner node: checking UTXOs at address: -INFO [1630127492.062652] [testnet/stacks-node/src/run_loop/neon.rs:164] [main] UTXOs found - will run as a Miner node -``` \ No newline at end of file diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json b/i18n/tr/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json deleted file mode 100644 index f5de305558..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Noteworthy Contracts", - "position": 4, - "link": { - "type": "generated-index", - "description": "Specific deployed Clarity Contracts worth mentioning." - } -} \ No newline at end of file diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md b/i18n/tr/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md deleted file mode 100644 index 99723a9ff2..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md +++ /dev/null @@ -1,362 +0,0 @@ ---- -title: BNS Contract -description: The Blockchain Naming System. ---- - -![](/img/satoshi-btc.png) - -## Introduction - -The Blockchain Naming System (BNS) is implemented as a smart contract using Clarity. - -Below is a list of public and read-only functions as well as error codes that can be returned by those methods: -* [Public functions](#public-functions) -* [Read-only functions](#read-only-functions) -* [Error codes](#error-codes) - -## Public functions - - -### name-import - -#### Input: `(buff 20), (buff 48), principal, (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-import namespace name beneficiary zonefile-hash)` -#### Description: -Imports name to a revealed namespace. Each imported name is given both an owner and some off-chain state. - -### name-preorder - -#### Input: `(buff 20), uint` -#### Output: `(response uint int)` -#### Signature: `(name-preorder hashed-salted-fqn stx-to-burn)` -#### Description: -Preorders a name by telling all BNS nodes the salted hash of the BNS name. It pays the registration fee to the namespace owner's designated address. - -### name-register - -#### Input: `(buff 20), (buff 48), (buff 20), (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-register namespace name salt zonefile-hash)` -#### Description: -Reveals the salt and the name to all BNS nodes, and assigns the name an initial public key hash and zone file hash. - -### name-renewal - -#### Input: `(buff 20), (buff 48), uint, (optional principal), (optional (buff 20))` -#### Output: `(response bool int)` -#### Signature: `(name-renewal namespace name stx-to-burn new-owner zonefile-hash)` -#### Description: -Depending in the namespace rules, a name can expire. For example, names in the .id namespace expire after 2 years. You need to send a name renewal every so often to keep your name. - -You will pay the registration cost of your name to the namespace's designated burn address when you renew it. When a name expires, it enters a \"grace period\". The period is set to 5000 blocks (a month) but can be configured for each namespace. - -It will stop resolving in the grace period, and all of the above operations will cease to be honored by the BNS consensus rules. You may, however, send a NAME_RENEWAL during this grace period to preserve your name. After the grace period, everybody can register that name again. If your name is in a namespace where names do not expire, then you never need to use this transaction. -### name-revoke - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(name-revoke namespace name)` -#### Description: -Makes a name unresolvable. The BNS consensus rules stipulate that once a name is revoked, no one can change its public key hash or its zone file hash. The name's zone file hash is set to null to prevent it from resolving. You should only do this if your private key is compromised, or if you want to render your name unusable for whatever reason. - -### name-transfer - -#### Input: `(buff 20), (buff 48), principal, (optional (buff 20))` -#### Output: `(response bool int)` -#### Signature: `(name-transfer namespace name new-owner zonefile-hash)` -#### Description: -Changes the name's public key hash. You would send a name transfer transaction if you wanted to: -* Change your private key -* Send the name to someone else or -* Update your zone file - -When transferring a name, you have the option to also clear the name's zone file hash (i.e. set it to null). This is useful for when you send the name to someone else, so the recipient's name does not resolve to your zone file. - -### name-update - -#### Input: `(buff 20), (buff 48), (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-update namespace name zonefile-hash)` -#### Description: -Changes the name's zone file hash. You would send a name update transaction if you wanted to change the name's zone file contents. For example, you would do this if you want to deploy your own Gaia hub and want other people to read from it. - -### namespace-preorder - -#### Input: `(buff 20), uint` -#### Output: `(response uint int)` -#### Signature: `(namespace-preorder hashed-salted-namespace stx-to-burn)` -#### Description: -Registers the salted hash of the namespace with BNS nodes, and burns the requisite amount of cryptocurrency. Additionally, this step proves to the BNS nodes that user has honored the BNS consensus rules by including a recent consensus hash in the transaction. Returns pre-order's expiration date (in blocks). - -### namespace-ready - -#### Input: `(buff 20)` -#### Output: `(response bool int)` -#### Signature: `(namespace-ready namespace)` -#### Description: -Launches the namespace and makes it available to the public. Once a namespace is launched, anyone can register a name in it if they pay the appropriate amount of cryptocurrency. - -### namespace-reveal - -#### Input: `(buff 20), (buff 20), uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, principal` -#### Output: `(response bool int)` -#### Signature: `(namespace-reveal namespace namespace-salt p-func-base p-func-coeff p-func-b1 p-func-b2 p-func-b3 p-func-b4 p-func-b5 p-func-b6 p-func-b7 p-func-b8 p-func-b9 p-func-b10 p-func-b11 p-func-b12 p-func-b13 p-func-b14 p-func-b15 p-func-b16 p-func-non-alpha-discount p-func-no-vowel-discount lifetime namespace-import)` -#### Description: -Reveals the salt and the namespace ID (after a namespace preorder). It reveals how long names last in this namespace before they expire or must be renewed, and it sets a price function for the namespace that determines how cheap or expensive names its will be.All of the parameters prefixed by `p` make up the `price function`. These parameters govern the pricing and lifetime of names in the namespace. - -The rules for a namespace are as follows: - -* a name can fall into one of 16 buckets, measured by length. Bucket 16 incorporates all names at least 16 characters long. - -* the pricing structure applies a multiplicative penalty for having numeric characters, or punctuation characters. - -* the price of a name in a bucket is `((coeff) * (base) ^ (bucket exponent)) / ((numeric discount multiplier) * (punctuation discount multiplier))` - -Example: - -* base = 10 -* coeff = 2 -* nonalpha discount: 10 -* no-vowel discount: 10 -* buckets 1, 2: 9 -* buckets 3, 4, 5, 6: 8 -* buckets 7, 8, 9, 10, 11, 12, 13, 14: 7 -* buckets 15, 16+: - - -## Read-only functions - -### can-name-be-registered - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(can-name-be-registered namespace name)` -#### Description: -Returns true if the provided name can be registered. - -### can-namespace-be-registered - -#### Input: `(buff 20)` -#### Output: `(response bool UnknownType)` -#### Signature: `(can-namespace-be-registered namespace)` -#### Description: -Returns true if the provided namespace is available. - -### can-receive-name - -#### Input: `principal` -#### Output: `(response bool int)` -#### Signature: `(can-receive-name owner)` -#### Description: -Returns true if the provided name can be received. That is, if it is not curretly owned, a previous lease is expired, and the name wasn't revoked. - -### get-name-price - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response uint int)` -#### Signature: `(get-name-price namespace name)` -#### Description: -Gets the price for a name. - -### get-namespace-price - -#### Input: `(buff 20)` -#### Output: `(response uint int)` -#### Signature: `(get-namespace-price namespace)` -#### Description: -Gets the price for a namespace. - -### get-namespace-properties - -#### Input: `(buff 20)` -#### Output: `(response (tuple (namespace (buff 20)) (properties (tuple (can-update-price-function bool) (launched-at (optional uint)) (lifetime uint) (namespace-import principal) (price-function (tuple (base uint) (buckets (list 16 uint)) (coeff uint) (no-vowel-discount uint) (nonalpha-discount uint))) (revealed-at uint)))) int)` -#### Signature: `(get-namespace-properties namespace)` -#### Description: -Get namespace properties. - -### is-name-lease-expired - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(is-name-lease-expired namespace name)` -#### Description: -Return true if the provided name lease is expired. - -### name-resolve - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response (tuple (lease-ending-at (optional uint)) (lease-started-at uint) (owner principal) (zonefile-hash (buff 20))) int)` -#### Signature: `(name-resolve namespace name)` -#### Description: -Get name registration details. - -### resolve-principal - -#### Input: `principal` -#### Output: `(response (tuple (name (buff 48)) (namespace (buff 20))) (tuple (code int) (name (optional (tuple (name (buff 48)) (namespace (buff 20)))))))` -#### Signature: `(resolve-principal owner)` -#### Description: -Returns the registered name that a principal owns if there is one. A principal can only own one name at a time. - -## Error codes - -### ERR_INSUFFICIENT_FUNDS -#### type: `int` -#### value: `4001` - -### ERR_NAMESPACE_ALREADY_EXISTS -#### type: `int` -#### value: `1006` - -### ERR_NAMESPACE_ALREADY_LAUNCHED -#### type: `int` -#### value: `1014` - -### ERR_NAMESPACE_BLANK -#### type: `int` -#### value: `1013` - -### ERR_NAMESPACE_CHARSET_INVALID -#### type: `int` -#### value: `1016` - -### ERR_NAMESPACE_HASH_MALFORMED -#### type: `int` -#### value: `1015` - -### ERR_NAMESPACE_NOT_FOUND -#### type: `int` -#### value: `1005` - -### ERR_NAMESPACE_NOT_LAUNCHED -#### type: `int` -#### value: `1007` - -### ERR_NAMESPACE_OPERATION_UNAUTHORIZED -#### type: `int` -#### value: `1011` - -### ERR_NAMESPACE_PREORDER_ALREADY_EXISTS -#### type: `int` -#### value: `1003` - -### ERR_NAMESPACE_PREORDER_CLAIMABILITY_EXPIRED -#### type: `int` -#### value: `1009` - -### ERR_NAMESPACE_PREORDER_EXPIRED -#### type: `int` -#### value: `1002` - -### ERR_NAMESPACE_PREORDER_LAUNCHABILITY_EXPIRED -#### type: `int` -#### value: `1010` - -### ERR_NAMESPACE_PREORDER_NOT_FOUND -#### type: `int` -#### value: `1001` - -### ERR_NAMESPACE_PRICE_FUNCTION_INVALID -#### type: `int` -#### value: `1008` - -### ERR_NAMESPACE_STX_BURNT_INSUFFICIENT -#### type: `int` -#### value: `1012` - -### ERR_NAMESPACE_UNAVAILABLE -#### type: `int` -#### value: `1004` - -### ERR_NAME_ALREADY_CLAIMED -#### type: `int` -#### value: `2011` - -### ERR_NAME_BLANK -#### type: `int` -#### value: `2010` - -### ERR_NAME_CHARSET_INVALID -#### type: `int` -#### value: `2022` - -### ERR_NAME_CLAIMABILITY_EXPIRED -#### type: `int` -#### value: `2012` - -### ERR_NAME_COULD_NOT_BE_MINTED -#### type: `int` -#### value: `2020` - -### ERR_NAME_COULD_NOT_BE_TRANSFERED -#### type: `int` -#### value: `2021` - -### ERR_NAME_EXPIRED -#### type: `int` -#### value: `2008` - -### ERR_NAME_GRACE_PERIOD -#### type: `int` -#### value: `2009` - -### ERR_NAME_HASH_MALFORMED -#### type: `int` -#### value: `2017` - -### ERR_NAME_NOT_FOUND -#### type: `int` -#### value: `2013` - -### ERR_NAME_NOT_RESOLVABLE -#### type: `int` -#### value: `2019` - -### ERR_NAME_OPERATION_UNAUTHORIZED -#### type: `int` -#### value: `2006` - -### ERR_NAME_PREORDERED_BEFORE_NAMESPACE_LAUNCH -#### type: `int` -#### value: `2018` - -### ERR_NAME_PREORDER_ALREADY_EXISTS -#### type: `int` -#### value: `2016` - -### ERR_NAME_PREORDER_EXPIRED -#### type: `int` -#### value: `2002` - -### ERR_NAME_PREORDER_FUNDS_INSUFFICIENT -#### type: `int` -#### value: `2003` - -### ERR_NAME_PREORDER_NOT_FOUND -#### type: `int` -#### value: `2001` - -### ERR_NAME_REVOKED -#### type: `int` -#### value: `2014` - -### ERR_NAME_STX_BURNT_INSUFFICIENT -#### type: `int` -#### value: `2007` - -### ERR_NAME_TRANSFER_FAILED -#### type: `int` -#### value: `2015` - -### ERR_NAME_UNAVAILABLE -#### type: `int` -#### value: `2004` - -### ERR_PANIC -#### type: `int` -#### value: `0` - -### ERR_PRINCIPAL_ALREADY_ASSOCIATED -#### type: `int` -#### value: `3001` diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md b/i18n/tr/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md deleted file mode 100644 index ce1b1ba859..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -title: Stacking Contract -description: See a detailed list of all functions and error codes of the Stacking contract. ---- - -## Introduction - -Stacking is implemented as a smart contract using Clarity. You can always find the Stacking contract identifier using the Stacks Blockchain API [`v2/pox` endpoint](https://docs.hiro.so/api#operation/get_pox_info). - -Below is a list of public and read-only functions as well as error codes that can be returned by those methods: - -* [Public functions](#public-functions) -* [Read-only functions](#read-only-functions) -* [Error codes](#error-codes) - -## Public functions - -### allow-contract-caller -#### input: `principal, (optional uint)` -#### output: `(response bool int)` -#### signature: `(allow-contract-caller caller until-burn-ht)` -#### description: -Give a contract-caller authorization to call stacking methods. Normally, stacking methods may only be invoked by _direct_ transactions (i.e., the `tx-sender` issues a direct `contract-call` to the stacking methods). - -By issuing an allowance, the tx-sender may call through the allowed contract. - -### delegate-stack-stx -#### input: `principal, uint, (tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint` -#### output: `(response (tuple (lock-amount uint) (stacker principal) (unlock-burn-height uint)) int)` -#### signature: `(delegate-stack-stx stacker amount-ustx pox-addr start-burn-ht lock-period)` -#### description: -As a delegate, stack the given principal's STX using `partial-stacked-by-cycle`. - -Once the delegate has stacked > minimum, the delegate should call `stack-aggregation-commit`. - -### delegate-stx -#### input: `uint, principal, (optional uint), (optional (tuple (hashbytes (buff 20)) (version (buff 1))))` -#### output: `(response bool int)` -#### signature: `(delegate-stx amount-ustx delegate-to until-burn-ht pox-addr)` -#### description: -Delegate to `delegate-to` the ability to stack from a given address. - -This method _does not_ lock the funds, rather, it allows the delegate to issue the stacking lock. - -The caller specifies: - -* amount-ustx: the total amount of ustx the delegate may be allowed to lock -* until-burn-ht: an optional burn height at which this delegation expiration -* pox-addr: an optional p2pkh or p2sh address to which any rewards *must* be sent - -### disallow-contract-caller -#### input: `principal` -#### output: `(response bool int)` -#### signature: `(disallow-contract-caller caller)` -#### description: -Revokes authorization from a contract to invoke stacking methods through contract-calls - -### reject-pox -#### input: -#### output: `(response bool int)` -#### signature: `(reject-pox)` -#### description: -Reject Stacking for this reward cycle. - -`tx-sender` votes all its uSTX for rejection. - -Note that unlike Stacking, rejecting PoX does not lock the tx-sender's tokens: PoX rejection acts like a coin vote. - -### revoke-delegate-stx -#### input: -#### output: `(response bool int)` -#### signature: `(revoke-delegate-stx)` -#### description: -Revoke a Stacking delegate relationship. A particular Stacker may only have one delegate, so this method does not take any parameters, and just revokes the Stacker's current delegate (if one exists). - -### stack-aggregation-commit -#### input: `(tuple (hashbytes (buff 20)) (version (buff 1))), uint` -#### output: `(response bool int)` -#### signature: `(stack-aggregation-commit pox-addr reward-cycle)` -#### description: -Commit partially stacked STX. - -This allows a stacker/delegate to lock fewer STX than the minimal threshold in multiple transactions, - -so long as: - -1. The pox-addr is the same. -2. This \"commit\" transaction is called _before_ the PoX anchor block. - -This ensures that each entry in the reward set returned to the stacks-node is greater than the threshold, - - but does not require it be all locked up within a single transaction - -### stack-stx -#### input: `uint, (tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint` -#### output: `(response (tuple (lock-amount uint) (stacker principal) (unlock-burn-height uint)) int)` -#### signature: `(stack-stx amount-ustx pox-addr start-burn-ht lock-period)` -#### description: -Lock up some uSTX for stacking! Note that the given amount here is in micro-STX (uSTX). - -The STX will be locked for the given number of reward cycles (lock-period). - -This is the self-service interface. tx-sender will be the Stacker. - -* The given stacker cannot currently be stacking. -* You will need the minimum uSTX threshold. This isn't determined until the reward cycle begins, but this method still requires stacking over the _absolute minimum_ amount, which can be obtained by calling `get-stacking-minimum`. -* The pox-addr argument must represent a valid reward address. Right now, this must be a Bitcoin p2pkh or p2sh address. It cannot be a native Segwit address, but it may be a p2wpkh-p2sh or p2wsh-p2sh address. - -The tokens will unlock and be returned to the Stacker (tx-sender) automatically. - -## Read-only functions - -### can-stack-stx -#### input: `(tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint, uint` -#### output: `(response bool int)` -#### signature: `(can-stack-stx pox-addr amount-ustx first-reward-cycle num-cycles)` -#### description: -Evaluate if a participant can stack an amount of STX for a given period. - -### get-pox-info -#### input: -#### output: `(response (tuple (current-rejection-votes uint) (first-burnchain-block-height uint) (min-amount-ustx uint) (prepare-cycle-length uint) (rejection-fraction uint) (reward-cycle-id uint) (reward-cycle-length uint) (total-liquid-supply-ustx uint)) UnknownType)` -#### signature: `(get-pox-info)` -#### description: -Returns information about PoX status. - -### get-pox-rejection -#### input: `principal, uint` -#### output: `(optional (tuple (amount uint)))` -#### signature: `(get-pox-rejection stacker reward-cycle)` -#### description: -Returns the amount of uSTX that a given principal used to reject a PoX cycle. - -### get-stacker-info -#### input: `principal` -#### output: `(optional (tuple (amount-ustx uint) (first-reward-cycle uint) (lock-period uint) (pox-addr (tuple (hashbytes (buff 20)) (version (buff 1))))))` -#### signature: `(get-stacker-info stacker)` -#### description: -Returns the _current_ stacking information for `stacker. If the information is expired, or if there's never been such a stacker, then returns none. - -### get-stacking-minimum -#### input: -#### output: `uint` -#### signature: `(get-stacking-minimum)` -#### description: -Returns the absolute minimum amount that could be validly Stacked (the threshold to Stack in a given reward cycle may be higher than this - -### get-total-ustx-stacked -#### input: `uint` -#### output: `uint` -#### signature: `(get-total-ustx-stacked reward-cycle)` -#### description: -Returns the amount of currently participating uSTX in the given cycle. - -### is-pox-active -#### input: `uint` -#### output: `bool` -#### signature: `(is-pox-active reward-cycle)` -#### description: -Returns whether or not PoX has been rejected at a given PoX cycle. -## Error codes - -### ERR_DELEGATION_EXPIRES_DURING_LOCK -#### type: `int` -#### value: `21` - -### ERR_DELEGATION_POX_ADDR_REQUIRED -#### type: `int` -#### value: `23` - -### ERR_DELEGATION_TOO_MUCH_LOCKED -#### type: `int` -#### value: `22` - -### ERR_INVALID_START_BURN_HEIGHT -#### type: `int` -#### value: `24` - -### ERR_NOT_ALLOWED -#### type: `int` -#### value: `19` - -### ERR_STACKING_ALREADY_DELEGATED -#### type: `int` -#### value: `20` - -### ERR_STACKING_ALREADY_REJECTED -#### type: `int` -#### value: `17` - -### ERR_STACKING_ALREADY_STACKED -#### type: `int` -#### value: `3` - -### ERR_STACKING_EXPIRED -#### type: `int` -#### value: `5` - -### ERR_STACKING_INSUFFICIENT_FUNDS -#### type: `int` -#### value: `1` - -### ERR_STACKING_INVALID_AMOUNT -#### type: `int` -#### value: `18` - -### ERR_STACKING_INVALID_LOCK_PERIOD -#### type: `int` -#### value: `2` - -### ERR_STACKING_INVALID_POX_ADDRESS -#### type: `int` -#### value: `13` - -### ERR_STACKING_NO_SUCH_PRINCIPAL -#### type: `int` -#### value: `4` - -### ERR_STACKING_PERMISSION_DENIED -#### type: `int` -#### value: `9` - -### ERR_STACKING_POX_ADDRESS_IN_USE -#### type: `int` -#### value: `12` - -### ERR_STACKING_STX_LOCKED -#### type: `int` -#### value: `6` - -### ERR_STACKING_THRESHOLD_NOT_MET -#### type: `int` -#### value: `11` - -### ERR_STACKING_UNREACHABLE -#### type: `int` -#### value: `255` \ No newline at end of file diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md b/i18n/tr/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md deleted file mode 100644 index 5f38edfb57..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: xBTC -description: Wrapped BTC on Stacks ---- - -![](/img/xbtc-icon.webp) - -## Introduction - -[Wrapped.com](https://www.wrapped.com) has brought Bitcoin (xBTC) to the Stacks ecosystem. - -xBTC is backed 1:1 by Bitcoin and empowers developers to expand the Bitcoin DeFi ecosystem. - -The reserves are publicly visible [here](https://open.wrapped.com/reserves/). - -## Contract - -[SP3DX3H4FEYZJZ586MFBS25ZW3HZDMEW92260R2PR.Wrapped-Bitcoin](https://explorer.stacks.co/txid/SP3DX3H4FEYZJZ586MFBS25ZW3HZDMEW92260R2PR.Wrapped-Bitcoin?chain=mainnet) - -## Examples of uses - -[Friedger Mining Pool](https://pool.friedger.de/) currrently supports Stacking rewards payments in xBTC (optional). - - -## More information - -* [Blog post announcement](https://www.stacks.co/blog/tokensoft-wrapped-fundamental-bitcoin-defi-building-blocks-xbtc) by Muneeb Ali - -* Video: [Why xBTC is Important For Bitcoin to Grow](https://www.youtube.com/watch?v=xIoadrfSdi4) \ No newline at end of file diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/references/_category_.json b/i18n/tr/docusaurus-plugin-content-docs/current/references/_category_.json deleted file mode 100644 index 3805ab0783..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/references/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "References", - "position": 9, - "link": { - "type": "generated-index", - "description": "Stacks references." - } -} \ No newline at end of file diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/references/glossary.md b/i18n/tr/docusaurus-plugin-content-docs/current/references/glossary.md deleted file mode 100644 index f97908371a..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/references/glossary.md +++ /dev/null @@ -1,215 +0,0 @@ ---- -title: Glossary -description: A comprehensive list of terms used within the ecosystem. ---- - -A comprehensive list of terms used within the ecosystem. - -#### App Review -An incentive mechanism for application developers in the early stage (first four years) of the ecosystem and helps with bootstrapping the two-sided market. - -#### Atlas -A peer network provide a global index for discovery. - -#### Bitcoin (BTC) address -A string of letters and numbers. `3E53XjqK4Cxt71BGeP2VhpcotM8LZ853C8` Sharing this address allows anyone to send Bitcoin to the address. - -#### block -A discrete group of records written to a blockchain that can effectively be identified and referenced by the use of headers that contain a digital fingerprint of the records each block contains. - -#### blockchain -A database created and shared by the members of a peer-to-peer computer network which each member of that network can independently trust due to the rules governing the database’s creation. A blockchain can therefore be used to replace centralized databases. - -#### Blockchain Name System (BNS) -Replacement for DNS. More info [here](../noteworthy-contracts/bns-contract). - -#### Blockstack Browser -A deprecated application for accessing identity and storage. - -#### Blockstack Owner Address - -Looks like a bitcoin address but starts with `ID` for example: `ID-1J3PUxY5uDShUnHRrMyU6yKtoHEUPhKULs` - -#### Burning -Burning a token means that the token is transferred to an address that is a black hole—one that is not owned by any entity and for which guessing the applicable private key is effectively impossible based on known mathematical principles. This effectively destroys the token by making it unavailable for future use and decreases the total number of tokens available from that point forward. - -#### consensus hash -A consensus hash is a cryptographic hash that each node calculates at each block. It is derived from the accepted state transitions in the last-processed block and a geometric series of prior-calculated consensus hashes. - -#### Consensus rules -"The rules governing the creation of new valid records in a blockchain database and the mining algorithms used for this purpose. - -#### control plane -The part of a network that carries signaling traffic and is responsible for routing. Control packets originate from or are destined for a router. Functions of the control plane include system configuration and management. - -#### core node -A server that runs Stacks Blockchain services. - -#### crypto-asset -A digital asset which utilises cryptography, peer-to-peer networking and a public ledger to regulate the creation of new units, verify transactions and secure the transactions without the intervention of any middleman. - -#### cryptography -The practise and study of encryption and decryption - encoding data so that it can only be decoded by specific individuals. A system for encrypting and decrypting data is a cryptosystem. - -#### DAO -See Decentralized Autonomous Organization. - -#### decentralized application (DApp) -A DApp is a service that enables direct interaction between end users and providers (e.g. connecting buyers and sellers in some marketplace, owners and stores in file storage). A term coined by Ethereum. See their glossary: http://ethdocs.org/en/latest/glossary.html#dapp" - -#### Decentralized Autonomous Organization -A type of contract or suite of contracts on the blockchain that is intented to codify, enforce or automate the processes of an organization. - -#### digital asset -Also referred to as a crypto-asset. Any set of unique digital information—including, for example, programs, decentralized programs, isolated chunks of programming code, collections of data, e-mail or web addresses or cryptocurrency tokens—that is capable of being stored and uniquely tracked on a computer network such as the Stacks network and over which a user can maintain control through that network. - -#### digital fingerprint -A digital fingerprint is a unique number of a fixed length that can be produced by running any set of digital information through something called a cryptographic hash function. Each set of digital information (including a digital asset, and the digital record of any network operation on that digital asset) should (as a practical matter) have a unique digital fingerprint, which allows that set of digital information to be identified. However, it is almost impossible to recreate a digital asset from its digital fingerprint. The Blockstack network uses industry-standard algorithms such as SHA-256 to create digital fingerprints. - -#### digital signature -A digital signature is a sequence of digital information combining a user’s private key and any digital information that the user wishes to sign. Any other party can use the user’s paired public key to verify that the digital signature is authentic, i.e. that the public key was generated from a particular piece of digital information and the user’s private key. - -#### distributed hash tables (DHT) -A form of network used to store some content in the form of key/value pairs. ... This experimental project try to avoid keeping all the blockchain, but instead prefers to store it in a DHT. - -#### ephemeral key -A cryptographic key is called ephemeral if it is generated for each execution of a key establishment process. - -#### fork -The term fork is used to refer both to any situation where there are two or more competing versions of a blockchain on a network (a situation that may arise and resolve itself in the ordinary course of network operations due to lags in communication between core nodes) and any software update that is proposed for adoption by the core nodes of a blockchain network that may result in a persistent fork on the network, with core nodes that adopt the update recognizing one version of the blockchain and those which do not recognizing another. - -#### Gaia -Decentralized storage architecture for off-chain data. More info [here](../gaia). - -#### genesis block -The genesis block is the first block of the Stacks blockchain, which will create the initial 1.32 billion Stacks Tokens. - -#### id.blockstack -An identifier in the Blockstack, for example meepers.id.blockstack. This is your name & identity that is registered in the .id namespace on Blockstack. Your personal data and storage are built around this ID. Apps that want to access your data use your permission and identity to find it. An id is usually a shorthand for a longer, hash ID string, for example ID-1Fj9kkw15P51Fj9kkw15P5xJmyefWhLKrQMKNPREfaqsJ" - -#### identity - -A way to identify a person or an organization on the Stacks network. An identity is unique, both `meepers.id.blockstack` or `chad.id` are examples of IDs. - -#### identity management (IDM) -Identity management, also known as identity and access management is, in computer security, the security and business discipline that enables the right individuals to access the right resources at the right times and for the right reason". - -#### know your customer (KYC) -Or KYC, is a popular term used in the banking or financial field. KYC is a process where financial institutions, insurers and other companies obtain information about the identity and address of the customers as part of risk management. - -#### light clients -Clients that can independently validate the existence of transactions by downloading only block headers and not the entire blockchain. - -#### magic recovery code - -A long encrypted string, for example: `36mWivFdy0YPH2z31EflpQz/Y0UMrOrJ++lH=0EI7c3mop2JuRBm5WXxSTazJsUjOA...` Do not share the QR code that accompanied your recovery code either. This is a QR code: - -![](/img/qr-code.png) - -#### mesh network -A local network topology in which the infrastructure nodes (i.e. bridges, switches, and other infrastructure devices) connect directly, dynamically and non-hierarchically to as many other nodes as possible and cooperate with one another to efficiently route data from/to clients. - -#### mining -Mining generally refers to the process of performing certain functions for a network such as adding new records to a blockchain in exchange for mining rewards; it may also refer to other mechanisms whereby rewards (usually in the form of cryptocurrency) are provided for performing other tasks helpful to the network. - -#### mining power -A miner’s (or group of miners’) mining power is equal to the probability it will be selected to write a new block to the blockchain. Depending on the mechanism for mining, this is usually related to the overall share of computing power or cryptoassets the miner or miners possess relative to all miners for that blockchain. - -#### mining rewards -Mining rewards are newly issued tokens received by miners in exchange for adding new records to the blockchain or other activities beneficial to the network. - -#### name -An identifier or name. Names are a type of digital asset in the Stacks network. If you have signed into the Stacks Wallet, you might have created a name. If an application developer registered an application within Stacks, then they registered a name. Public Stacking pools can also have a name. - -#### network operation -A network operation is any change to the information about a digital asset (or smart contract) stored on a blockchain, including, for example, a change in the digital asset’s owner, or a change in the location at which it is stored on the network. How and when these network operations are performed for each digital asset is governed, on the Blockstack network, either by the Stacks Node software or a smart contract. - -#### NFT -Non fungible token. - -#### private key - -Private keys matches a corresponding public key. A public key also looks like a string of letters and numbers: - -![](/img/private.png) - -The exact format of the public and private key depend on the software you use to create them. - -#### proof-of-burn mining -The consensus algorithm used in the Stacks blockchain where miners destroy a proof-of-work-based cryptocurrency (currently Bitcoin) to get tokens; this enables the functionality where nodes can select between conflicting blockchain forks, as the blockchain fork with the most amount of cryptocurrency burned is considered to be the correct fork. - -#### proof-of-work -A proof-of-work system or proof-of-work mining is a mining mechanism where miners must expend computing power to solve complicated cryptographic puzzles, and prove that they have done so by writing the solution to the blockchain, in order to be allowed to add blocks to a blockchain. This is the mining system used, for example, by Bitcoin. - -#### public key -Public and private key pair comprise of two uniquely related cryptographic keys. It looks like a long random string of letters and numbers: `3048 0241 00C9 18FA CF8D EB2D EFD5 FD37 89B9 E069 EA97 FC20 …` The exact format of the public and private key depend on the software you use to create them. - -#### Public Key Infrastructure (PKI) -A system which returns a cryptographic public key associated with a name. - -#### replicated state machines (RSMs) -This is a model for reasoning about distributed computer programs -- any program (plus it's input) can be represented as a state machine, and when trying to get a distributed set of servers to agree on the output of an algorithm, you can model that process as N different state machines" - -#### Secret recovery Key, -Used to access an identity on the Stacks blockchain. A 24-word sequence of words for example: `applied binge crisp pictorial fiery` `dancing agreeable frogs light finish ping apple` - -#### seed phrase - -Used to access Stacks Wallet software. The seed phrase consists of 24 words in a sequence. Both the word *and its position the sequence* are important. Write down your seed phrase and store it in a secure location such as a safe deposit box. When you write the seed phrase down, include its position, for example,`1-frog, 2-horse, 3-building` and so on until you reach a final position `24-ocean`. -#### smart contract -A smart contract is a computer program written to a blockchain such as the Stacks blockchain by developers. This computer program defines the various network operations that can be performed on the digital assets on the blockchain, the computations that can be performed using the smart contract, along with defining various important properties of the respective digital assets like ownership rights and the cost in fuel required to register the digital assets. - -#### soft fork -A soft fork is a proposed update to the software governing the network that results in a post-update network that is compatible with the network as it existed prior to the update, because it restricts the network operations that can be performed after the update. - -#### Stacks (STX) address - - A STX address is a string of letters and numbers starting with an `SP` or `SM`, for example: `SM3KJBA4RZ7Z20KD2HBXNSXVPCR1D3CRAV6Q05MKT` If you created a software-only wallet with the Stacks Wallet software, the wallet has a single STX address which is also sometimes called the *wallet address*. You access a software wallet with a *seed phrase*. " - -#### Stacks blockchain -The Stacks blockchain is the custom blockchain being developed for use by the Stacks network that will use the Stacks token as its native currency and which will include the genesis block and subsequent blocks created by the mining activities described in the Stacks Network—Development of the Stacks network. - -#### Stacks Explorer -An application that allow you to view and search transactions in the blockchain. For example, https://explorer.stacks.co. - -#### Stacks node -A complete version of our open-source software available on Github at https://github.com/stacks-network/stacks-blockchain/ that governs the creation of the blockchain, the smart contracts that may be written to our blockchain, and other systems that make up the Stacks network, when run on the systems and devices of our users and developers. - -#### Stacks wallet -An application for accessing assets, identity and storage. Examples are the [Hiro Wallet](https://www.hiro.so/wallet), [xverse](https://www.xverse.app/) and [dcent](https://dcentwallet.com/). More information and example [here](../services-using-stacks/wallets). - -#### storage hub -A Gaia instance run by a hub provider or software. A Gaia hub stores data in a separate, addressed location. - -#### storage provider -A third-party company cloud or software provider that hosts one or more Gaia storage hubs. - -#### transaction -A transaction is a unit of work within a block. - -#### transaction fee -Fees paid by participants in a transaction to miners. - -#### two-sided market problem -Economic platforms having two distinct user groups that provide each other with network benefits. The Stacks platform is a classic two-sided market. - -#### username -A shorthand name for your id.blockstack. - -#### virtual blockchain -A layer that sits on top of a blockchain that introduces new functionality and operations without requiring changes to the underlying blockchain. - -#### wallet address -A wallet address is the form in which a public key can be presented and recorded on a blockchain. Wallet addresses are therefore used to assign the ownership of digital assets on the Blockstack network. - -#### watch-only wallet -A wallet without send and receive ability. You can view only balances and transaction history. - -#### web of trust mining -Web-of-trust mining provides incentive mechanisms for users where an initial trusted-set of unique users is curated in the genesis block and, in the future, the initial set of users can expand the web-of-trust after the network goes live. - -#### web3 -The exact definition is still under discussion, but it general refers to the 3rd generation of the web that is based on blockchain technology and incorporates decentralized and token-based economics. - -#### zone file -A Domain Name System (DNS) zone file is a text file that describes a DNS zone. A DNS zone is a subset, often a single domain, of the hierarchical domain name structure of the DNS. diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/references/nft.md b/i18n/tr/docusaurus-plugin-content-docs/current/references/nft.md deleted file mode 100644 index 033ee0a71a..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/references/nft.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: NFTs on Stacks -description: A list of sites that operate NFTs on Stacks ---- - -List of sites that operate NFTS on Stacks on alphabetical order. - -### [Byzantion](https://byzantion.xyz/) - -![website-screenshot](/img/sh_nft_byzantion.png) - -### [Gamma](https://gamma.io/) -![website-screenshot](/img/sh_nft_gamma.png) - -### [Megapont](https://www.megapont.com/) - -![website-screenshot](/img/sh_nft_megapont.png) - -### [StacksArt](https://www.stacksart.com/) - -![website-screenshot](/img/sh_nft_stacksart.png) - diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md b/i18n/tr/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md deleted file mode 100644 index dc6e507d5e..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Stacks info sites -description: A list of sites on alphabetical order that display status and stats of the Stacks network. ---- - -### [Haystack](https://haystack.tools/mempool) - -![website-screenshot](/img/sh_haystacks.png) - -### [Stacksdata](https://stacksdata.info/) - -![website-screenshot](/img/sh_stacksdata.png) - -### [Stacksonchain](https://stacksonchain.com) - -![website-screenshot](/img/sh_stacksonchain.png) - -### [Status Hiro](https://status.hiro.so/) - -![website-screenshot](/img/sh_statushiro.png) - -### [Stxstats](https://www.stxstats.co/) - -![website-screenshot](/img/sh_stxstats.png) - -### [Novuminsights](https://stacks.novuminsights.com/health) - -![website-screenshot](/img/sh_novuminsights.png) - -### [Onstacks](https://app.onstacks.com/) - -![website-screenshot](/img/sh_onstacks.png) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json b/i18n/tr/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json deleted file mode 100644 index ebd63f366c..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Services using Stacks", - "position": 8, - "link": { - "type": "generated-index", - "description": "An 'always incomplete' list of services that use Stacks." - } -} \ No newline at end of file diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md b/i18n/tr/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md deleted file mode 100644 index 51defacba7..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: DeFi -description: De-Fi sites on Stacks -sidebar_position: 2 ---- - -They are multiple De-Fi sites that operate on the Stacks blockchain. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Alex - -[Alex](https://app.alexlab.co) ![](/img/sh_alex.png) - -## Arkadiko - -[Arkadiko](https://arkadiko.finance/) ![](/img/sh_arkadiko.png) - -## Catamaran Swaps - -[Catamaran Swaps](https://www.catamaranswaps.org/) allows trustless exchange of digital assets. - -![](/img/sh_catamaran.png) - -## Lnswap - -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange - -![](/img/sh_lnswap.png) - -## Neoswap - -[Neoswap](https://neoswap.party) - -![](/img/sh_neoswap.png) - -## Stackswap - -[Stackswap](https://app.stackswap.org/v2) - -![](/img/sh_stackswap.png) - diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/services-using-stacks/more.md b/i18n/tr/docusaurus-plugin-content-docs/current/services-using-stacks/more.md deleted file mode 100644 index df0b3e2254..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/services-using-stacks/more.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: More -description: More services built on Stacks. -sidebar_position: 5 ---- - -List of sites on alphabetical order added by the community. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Citycoins - -[Citycoins](https://citycoins.co) - -![](/img/sh_citycoins.png) - -## Sigle - -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. - -![](/img/sh_sigle.png) \ No newline at end of file diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md b/i18n/tr/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md deleted file mode 100644 index bfa0505dc9..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: NFTs -description: NFTs on Stacks -sidebar_position: 3 ---- - -List of sites that operate NFTS on Stacks on alphabetical order. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -### [Byzantion](https://byzantion.xyz/) - -![website-screenshot](/img/sh_nft_byzantion.png) - -### [Gamma](https://gamma.io/) -![website-screenshot](/img/sh_nft_gamma.png) - -### [Megapont](https://www.megapont.com/) - -![website-screenshot](/img/sh_nft_megapont.png) - -### [StacksArt](https://www.stacksart.com/) - -![website-screenshot](/img/sh_nft_stacksart.png) - -### [Superfandom](https://superfandom.io/) - -![website-screenshot](/img/sh_superfandom.png) \ No newline at end of file diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/services-using-stacks/other.md b/i18n/tr/docusaurus-plugin-content-docs/current/services-using-stacks/other.md deleted file mode 100644 index 199fc41da5..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/services-using-stacks/other.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Other Stacks sites -description: A list of sites on alphabetical order built on Stacks. -sidebar_position: 4 ---- - -List of sites on alphabetical order added by the community. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Alex -[Alex](https://app.alexlab.co) - -## Sigle - -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. \ No newline at end of file diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md b/i18n/tr/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md deleted file mode 100644 index 35ced8dac6..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Stacks info sites -description: Status and stats of the Stacks network. -sidebar_position: 1 ---- - -A list of sites on alphabetical order that display status and stats of the Stacks network. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -### [Haystack](https://haystack.tools/mempool) - -![website-screenshot](/img/sh_haystacks.png) - -### [Stacksdata](https://stacksdata.info/) - -![website-screenshot](/img/sh_stacksdata.png) - -### [Stacksonchain](https://stacksonchain.com) - -![website-screenshot](/img/sh_stacksonchain.png) - -### [Status Hiro](https://status.hiro.so/) - -![website-screenshot](/img/sh_statushiro.png) - -### [Stxstats](https://www.stxstats.co/) - -![website-screenshot](/img/sh_stxstats.png) - -### [Novuminsights](https://stacks.novuminsights.com/health) - -![website-screenshot](/img/sh_novuminsights.png) - -### [Onstacks](https://app.onstacks.com/) - -![website-screenshot](/img/sh_onstacks.png) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md b/i18n/tr/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md deleted file mode 100644 index d4b4cbf18c..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Swaps -description: A list of sites that allow Swaps -sidebar_position: 2 ---- - -They are multiple sites that allow you to make swaps using the Stacks blockchain. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Catamaran Swaps - -[Catamaran Swaps](https://www.catamaranswaps.org/) allows trustless exchange of digital assets. - -![](/img/sh_catamaran.png) - -## Lnswap - -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange - -![](/img/sh_lnswap.png) - -## Neoswap - -[Neoswap](https://neoswap.party) - -![](/img/sh_neoswap.png) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md b/i18n/tr/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md deleted file mode 100644 index e5ea6c5b45..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Wallets -description: Wallets for Stacks -sidebar_position: 4 ---- - -A list of hardware and software wallets for Stacks - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Blockchain.com - -[Blockchain.com](https://www.blockchain.com/wallet) - -![](/img/sh_blockchain.png) -## Boom - -[Boom](https://boom.money) - -![](/img/sh_boom.png) - -## Dcent wallet - -[D'CENT](https://dcentwallet.com) - -![](/img/sh_dcent.png) -## Hiro Wallet - -[Hiro Wallet](https://www.hiro.so/wallet) - -![](/img/sh_hirowallet.png) - -## Neptune - -[Neptune](https://neptunewallet.io) - -![](/img/sh_neptunewallet.png) - -## Xverse - -[Xverse](https://www.xverse.app/) - -![](/img/sh_xverse.png) - -## Wise - -[Wise](https://wiseapp.id) - -![](/img/sh_wiseapp.png) \ No newline at end of file diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md b/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md deleted file mode 100644 index bd2c361985..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md +++ /dev/null @@ -1,214 +0,0 @@ ---- -title: Accounts -description: Guide to Stacks 2.0 accounts -sidebar_position: 5 ---- - -## Introduction - -Stacks 2.0 accounts are entities that own assets, like Stacks (STX) tokens. An account has an address, private key, nonce, and one or more asset balances. - -:::tip The encryption algorithm used in Stacks 2.0 is **[secp256k1](https://en.bitcoinwiki.org/wiki/Secp256k1)**. - -Additionally, [Ed25519](https://ed25519.cr.yp.to/) is also used just for the VRF (Verifiable Random Function). ::: - -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. - -:::tip -The transaction type doesn't need to be a token transfer - contract deploy and contract call transactions can change the balances of an account -::: - -## Creation - -An account is generated from a 24-word mnemonic phrase. This is often referred to as the **seed phrase**. The seed phrase provides access to Stacks 2.0 accounts. - -:::danger -If the seed phrase is lost, access to the associated account cannot be restored. No person or organization, including Blockstack, can recover a lost seed phrase. -::: - -The easiest way to generate a new Stacks 2.0 account is to use the [Stacks CLI](https://github.com/hirosystems/stacks.js/tree/master/packages/cli): - -```bash -# install CLI globally -npm install --global @stacks/cli - -# generate a new account and store details in a new file -# '-t' option makes this a testnet account -stx make_keychain -t > cli_keychain.json -``` - -`make_keychain` creates the following file: - -```js -{ - "mnemonic": "aaa bbb ccc ddd ...", - "keyInfo": { - "privateKey": "5a3f1f15245bb3fb...", - "address": "STJRM2AMVF90ER6G3RW1QTF85E3HZH37006D5ER1", - "btcAddress": "biwSd6KTEvJcyX2R8oyfgj5REuLzczMYC1", - "wif": "L4HXn7PLmzoNW...", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -| Field | Description | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `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.privateKey` | Private key for the account. Required for token transfers and often referred to as `senderKey` | -| `keyInfo.address` | Stacks address for the account | -| `keyInfo.btcAddress` | Corresponding BTC address for the account. | -| `keyInfo.wif` | Private key of the btcAddress in compressed format. | -| `keyInfo.index` | Nonce for the account, starting at 0 | - -Note that a new account automatically exists for each new private key. There is no need to manually instantiate an account on the Stacks 2.0 blockchain. - -:::tip Addresses are created by generating the [RIPEMD-160 hash](https://en.wikipedia.org/wiki/RIPEMD#RIPEMD-160_hashes) of the [SHA256](https://en.bitcoinwiki.org/wiki/SHA-256) of the public key. BTC addresses are encoded with [Base58Check](https://en.bitcoin.it/wiki/Base58Check_encoding). For Stacks addresses, [c32check](https://github.com/stacks-network/c32check) is used. Deriving an address from a public key can be done without internet access, for instance using the c32check `c32addressDecode` method. ::: - -Alternatively to the CLI creation, the [Stacks Transactions JS](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library can be used: - -```js -import { - makeRandomPrivKey, - privateKeyToString, - getAddressFromPrivateKey, - TransactionVersion, -} from '@stacks/transactions'; - -const privateKey = makeRandomPrivKey(); - -// Get public key from private -const publicKey = getPublicKey(privateKey); - -const stacksAddress = getAddressFromPrivateKey( - privateKeyToString(privateKey), - TransactionVersion.Testnet // remove for Mainnet addresses -); -``` - -A second alternative would be to use [stacks-gen](https://github.com/psq/stacks-gen). This tool will generate all the keys you need in one place, including the values needed for calling the stacking contract, and also a WIF key for use with `bitcoind`. - -#### stacks-gen prerequisite - -Install [npx](https://github.com/npm/npx) if not already installed. (npx will check whether `` exists in \$PATH, or in the local project binaries, and execute that. If `` is not found, it will be installed prior to execution). - -``` -npm install -g npx -``` - -#### stacks-gen usage - -``` -npx -q stacks-gen sk --testnet - -{ - "phrase": "guide air pet hat friend anchor harvest dog depart matter deny awkward sign almost speak short dragon rare private fame depart elevator snake chef", - "private": "0351764dc07ee1ad038ff49c0e020799f0a350dd0769017ea09460e150a6401901", - "public": "022d82baea2d041ac281bebafab11571f45db4f163a9e3f8640b1c804a4ac6f662", - "stacks": "ST16JQQNQXVNGR8RZ1D52TMH5MFHTXVPHRV6YE19C", - "stacking": "{ hashbytes: 0x4d2bdeb7eeeb0c231f0b4a2d5225a3e3aeeed1c6, version: 0x00 }", - "btc": "mnYzsxxW271GkmyMnRfiopEkaEpeqLtDy8", - "wif": "cMh9kwaCEttgTQYkyMUYQVbdm5ZarZdBHErcq7mXUChXXCo7CFEh" -} -``` - -:::tip The stacking object with hashbytes and a version represents the bitcoin address derived from the Stacks address. Read more about the [bitcoin address format](stacking#bitcoin-address). ::: - -Full documentation available at [stacks-gen](https://github.com/psq/stacks-gen). - -## Querying - -### Get Stacks (STX) balance and nonce - -STX balance and nonce can be obtained through the [`GET /v2/accounts/`](https://docs.hiro.so/api#operation/get_account_info) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/accounts/' -``` - -Sample response: - -```js -{ - "balance": "0x0000000000000000002386f26f3f40ec", - "nonce": 17 -} -``` - -:::tip -The balance string represents an unsigned 128-bit integer (big-endian) in hex encoding -::: - -### Get all token balances - -All token balances can be obtained through the [`GET /extended/v1/address//balances`](https://docs.hiro.so/api#operation/get_account_balance) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/address//balances' -``` - -Sample response: - -```js -{ - "stx": { - "balance": "0", - "total_sent": "0", - "total_received": "0" - }, - "fungible_tokens": {}, - "non_fungible_tokens": {} -} -``` - -:::tip Stacks accounts cannot hold bitcoins. The best way to obtain corresponding BTC balances is to derive the BTC address from the Stacks address (using [`c32check`](https://github.com/stacks-network/c32check#c32tob58-b58toc32)) and query the Bitcoin network. ::: - -### Get all asset events - -All asset events associated with the account can be obtained through the [`GET /extended/v1/address//assets`](https://docs.hiro.so/api#operation/get_account_balance) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/address//assets' -``` - -Sample response: - -```js -{ - "limit": 20, - "offset": 0, - "total": 0, - "results": [ - { - "event_index": 5, - "event_type": "non_fungible_token_asset", - "asset": { - "asset_event_type": "transfer", - "asset_id": "ST2W14YX9SFVDB1ZGHSH40CX1YQAP9XKRAYSSVYAG.hello_world::hello-nft", - "sender": "SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR", - "recipient": "SM2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQVX8X0G", - "value": { - "hex": "0x0100000000000000000000000000000001", - "repr": "u1" - } - } - }, - { - "event_index": 3, - "event_type": "fungible_token_asset", - "asset": { - "asset_event_type": "mint", - "asset_id": "ST2W14YX9SFVDB1ZGHSH40CX1YQAP9XKRAYSSVYAG.hello_world::novel-token-19", - "sender": "", - "recipient": "SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR", - "amount": "12" - } - } - ] -} -``` diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/index.md b/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/index.md deleted file mode 100644 index 1533219df9..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/index.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Understand Stacks -description: Learn more about the Stacks 2.0 blockchain -sidebar_position: 1 ---- - -![](/img/SBC-L-2x-10.png) -## Introduction - -Stacks 2.0 is a layer-1 blockchain that connects to Bitcoin and brings smart contracts and decentralized apps to it. Smart contracts and apps developed on the Stacks platform are natively integrated with the security, stability, and economic power of Bitcoin. - -## Capabilities - -Read more about the features provided by the Stacks 2.0 blockchain. - - - -:::tip Check out the [technical specifications](technical-specs) for a brief overview ::: - - - - -A detailed [comparison of the Stacks blockchain to other blockchain technologies][] is available at the Stacks Foundation blog. -### Consensus mechanism -![](/img/pages/stacking.svg) Stacks 2.0 implements a new mining mechanism called Proof of Transfer ("PoX"). PoX is a consensus algorithm between two blockchains. It uses an established blockchain (in this case Bitcoin) to secure a new blockchain (Stacks). - -PoX connects to Bitcoin with a 1:1 block ratio, meaning anything that happens on the Stacks blockchain can be verified on the Bitcoin Blockchain. - -Instead of burning electricity on proof of work, PoX reuses already minted bitcoins as "proof of computation" and miners represent their cost of mining in bitcoins directly. - - -[Read more about Proof of Transfer](proof-of-transfer) -### Mining - -![](/img/pages/testnet-sm.svg) Mining is required to make the network usable, trustworthy, and secure. Miners verify incoming transactions, participate in the consensus mechanism, and write new blocks to the blockchain. - -To incentivize mining, miners receive freshly minted Stacks (STX) tokens if they win the bid for becoming the leader of the next round. - -[Read more about Mining](mining) - -### Stacking - -Bitcoins used for miner bids are sent to a set of specific addresses corresponding to Stacks (STX) tokens holders that are actively participating in consensus ("Stackers"). Thus, rather than being destroyed, the bitcoins consumed in the mining process go to productive Stacks holders as a reward based on their holdings of Stacks and participation in the Stacking algorithm. - -Stackers have to lock up their Stacks (STX) tokens for a certain period of time. - -[Read more about Stacking](stacking) - -### Smart contracts - -![](/img/pages/write-smart-contracts-sm.svg) Clarity is a new language for smart contracts on the Stacks 2.0 blockchain. The Clarity smart contract language optimizes for predictability and security. - -Stacks 2.0 anchors clarity smart contracts to Bitcoin making it possible for smart contracts to operate based on actions seen on the bitcoin blockchain. - -:::note The [Clarity open-source project](https://clarity-lang.org/) is supported by Stacks and [Algorand](https://www.algorand.com/) ::: - - -Clarity is distinct from other languages designed for writing smart contracts in a few ways: - -- **Predictability**: The Clarity language uses precise and unambiguous syntax that allows developers to predict exactly how their contracts will be executed. -- **Security**: The Clarity language allows users to supply their own conditions for transactions that ensure that a contract may never unexpectedly transfer a token owned by a user. -- **No compiler**: Contracts written in Clarity are broadcasted on the Stacks blockchain exactly as they are written by developers. This ensures that the code developers wrote, analyzed, and tested, is exactly what gets executed. - -[Read more about Clarity](../write-smart-contracts/clarity-language/) - -## Guides - -Read one of our guides to understand the ins and outs of the Stacks 2.0 blockchain. - -* [Account](../understand-stacks/accounts) -* [Transactions](../understand-stacks/transactions) -* [Network](../understand-stacks/network) -* [Microblocks](../understand-stacks/microblocks) - -[comparison of the Stacks blockchain to other blockchain technologies]: https://stacks.org/stacks-blockchain diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md b/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md deleted file mode 100644 index de64c617f4..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: Microblocks -description: Guide to Stacks Microblocks -sidebar_position: 8 ---- - -## Introduction - -Microblocks are a protocol-level feature of the Stacks blockchain that solve the technical challenge of transaction latency. Because each Stacks block is anchored to a Bitcoin block through the [Proof-of-Transfer consensus mechanism](../understand-stacks/proof-of-transfer), Stacks is necessarily limited to the same block times as the Bitcoin network. Microblocks allow the Stacks blockchain to perform state transitions between anchor blocks. - -Microblocks are a powerful mechanism for developers to create performant, high quality applications on Stacks, while still inheriting the security of Bitcoin. - -## Transaction states - -The [Stacks block production model](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.) is described in SIP-001. The standard outlines the mechanism by which elected block leaders can produce blocks on the Stacks blockchain either by batching transactions or by streaming them. Microblocks are the product of the streaming model. - -If a block leader has elected to mine microblocks, the leader selects transactions from the mempool and package them into microblocks during the current epoch. Microblocks are blocks of transactions included by a miner after the previous anchor block has been mined, but before the next block is selected. Transactions included in microblocks are processed by the network: their results are known. - -Consider a transaction from the perspective of the number of block confirmations it has. A transaction included in a microblock might have the following example lifecycle: - -``` -Transaction 1 is broadcast to the mempool. It has 0 confirmations. -Transaction 1 is included in a microblock. It still has 0 confirmations, but the results of the transaction are known -Transaction 1 is included in the next anchor block. It has 1 confirmation. -The next Stacks block confirms the previous block. Transaction 1 has 2 confirmations. -The next Stacks block confirms the previous block. Transaction 1 has 3 confirmations. -... -``` - -Consider a similar transaction that is not included in a microblock: - -``` -Transaction 2 is broadcast to the mempool. It has 0 confirmations. -Transaction 2 is included in the next anchor block. It has 1 confirmation. -The next Stacks block confirms the previous block. Transaction 2 has 2 confirmations. -The next Stacks block confirms the previous block. Transaction 2 has 3 confirmations. -``` - -The lifecycles of the two transactions are similar, but the difference is pending state. Many Bitcoin wallets display 0-confirmation balances: your wallet balance with any mempool transactions already applied. This is useful because it tells you when you've sent a transaction or received one. With smart contracts, displaying pending state is not as straightforward, because smart contracts do not just transfer inputs to outputs, they may call other contracts, emit events, or perform other computations. A transaction processed in a microblock generates all that information. - -:::tip -If a transaction is dependent on a chain state that could by altered by previous transactions with serious -implications, you should carefully consider whether it should be performed using microblocks. -::: - -## Enabling microblocks - -Miners can choose to enable or disable microblocks in their mining configuration. As a best practice, miners should enable microblock mining. When an application or user submits a transaction, the transaction can include an argument that requires the transaction to be in a microblock, an anchor block, or in either. - -### Transactions - -Transactions include an option that controls if a miner should include them in microblocks or in anchor blocks. The anchor mode transaction option is an optional argument that controls whether a transaction must be included in an anchor block or a microblock, or is eligible for either. - -### Mining - -Stacks miners must enable microblocks in their miner configuration to implement the block streaming model. For more information, see [mining microblocks](../understand-stacks/mining#microblocks). - -## Developing with microblocks - -In most cases, information from transactions included in microblocks should be treated like information from any other block. Wallets and explorers should display the consequences of microblock transactions as the current state of the network. This state should be acknowledged as tentative. - -A microblock transaction can end up being reorganized in the next block rather than just being confirmed as-is. Because of this, your UI should communicate to users if the outputs of a transaction changed, or if the transaction's associated block changed. This is the same outcome as if a 1-block fork occurred. - -### Stacks.js libraries - -Stacks.js provides the [AnchorMode][] argument on transaction objects so that your application can set the microblocks preference for transactions. - -### API - -:::danger API support for microblocks is a work-in-progress. Review the [API documentation][microblocks_api] carefully to ensure that you are up-to-date on the latest implementation details for microblocks. ::: - -The Stacks Blockchain API exposes microblocks through several endpoints. Please review the [Stacks Blockchain API guide][] for more details. - -## Best practices - -Working with microblocks is a design decision that you must make for your own application. When working with microblocks, the following best practices are recommended. - -### Handling nonce - -Nonce handling with microblocks is challenging because the next account nonce must take into account any nonce values included in microblocks, which may not yet be included in an anchor block. The Stacks Blockchain API [provides an endpoint][] to retrieve the next nonce for a given principal. - -### Application design - -The state of microblock transactions should be carefully communicated to users. No transaction is final until it's included in an anchor block, and your application design should reflect this. - -The following guidelines are provided as an initial set of best practices for UI design when incorporating microblocks into your application. - -#### Explorers - -Display pending state, but warn that a transaction is still pending. Indicate visually that displayed balances depend on pending state. - -#### Wallets - -Display pending state, but warn that a transaction is still pending. Indicate visually that displayed balances depend on pending state. - -#### Exchanges - -Continue to count confirmations, microblocks should be considered pending. - -#### Applications - -Microblock communication is highly app-dependent. For some applications, displaying a pending or 0-confirmation transaction as confirmed may be fine. For example, storing data on the chain, or querying the BNS contract. For other applications, such as the transfer of real value, waiting for 3-confirmations would be prudent before displaying the state as confirmed. - -[AnchorMode]: https://stacks.js.org/enums/transactions.AnchorMode.html -[Stacks Blockchain API guide]: https://docs.hiro.so/get-started/stacks-blockchain-api#microblocks-support -[provides an endpoint]: https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling -[microblocks_api]: https://docs.hiro.so/api#tag/Microblocks diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/mining.md b/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/mining.md deleted file mode 100644 index fa1f56ed3f..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/mining.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Mining -description: A guide to mining on Stacks 2.0 -sidebar_position: 4 ---- - -## Introduction - -This guide highlights some technical details related to mining on the Stacks 2.0 network. - -For steps on how to setup your own miner please refer to [miner on tesnet](nodes-and-miners/miner-testnet.md) and [miner on mainnet](nodes-and-miners/miner-testnet.md). - -## Mining frequency - -A new Stacks block may be mined once per Bitcoin block. To be considered for mining a block, a miner must have a block commit included in a Bitcoin block. If a miner wishes to update their commitment after submission, they may use Bitcoin Replace-By-Fee. - -## Coinbase rewards - -Miners receive coinbase rewards for blocks they win. - -The reward amounts are: - -- 1000 STX per block are released in the first 4 years of mining -- 500 STX per block are released during the following 4 years -- 250 STX per block are released during the following 4 years -- 125 STX per block are released from then on indefinitely. - -These "halvings" are synchronized with Bitcoin halvings. - -![coinbase rewards](/img/pages/coinbase-rewards.png) - -## Transaction fees - -Miners receive Stacks fees for transactions mined in any block they produce. - -For transactions mined in microblocks, the miner that produces the microblock receives 40% of the fees, while the miner that confirms the microblock receives 60% of the fees. - -## Reward maturity - -Block rewards and transaction fees take 100 blocks on the Bitcoin blockchain to mature. After successfully mining a block your rewards appear in your Stacks account after ~24 hours. - -## Mining with proof-of-transfer - -Miners commit Bitcoin to **two** addresses in every leader block commit. The amount committed to each address must be the same. The addresses are chosen from the current reward set of stacking participants. Addresses are chosen using a verifiable-random-function, and determining the correct two addresses for a given block requires monitoring the Stacks chain. - -![mining with pox](/img/pages/mining-with-pox.png) - -## 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, 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. - -While there is no minimum BTC commitment enforced by the protocol, in practice, there's a floor constrained by [dust](https://unchained-capital.com/blog/dust-thermodynamics/)": basically, if the fees for a transaction exceed the value of the spent output, it's considered dust. How dust is [calculated](https://github.com/bitcoin/bitcoin/blob/master/src/policy/policy.cpp#L14) depends on a number of factors, we've found 5,500 satoshis to be good lower bound per [output](https://learnmeabitcoin.com/technical/output). Bitcoin transactions from Stacks miners contain two outputs (for Proof-of-Transfer), so a commitment of at least 11,000 satoshis / block is recommended. - -To calculate the amount of BTC to send miners should: - -- Guess the price BTC/STX for the next day (100 blocks later) -- Guess the total amount of BTCs committed by all miners - -## Microblocks - -The Stacks blockchain produces blocks at the same rate as the Bitcoin blockchain. In order to provide lower latency transactions, miners can opt to enable microblocks. Microblocks allow the current block leader to stream transactions and include their state transitions in the current epoch. - -If a block leader opts to produce microblocks, the next leader builds the chain tip off the last microblock that the current leader produces. - -The block streaming model is described in [SIP-001][]. - -[SIP-001]: https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md#operation-as-a-leader diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/network.md b/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/network.md deleted file mode 100644 index 6efcc385ec..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/network.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: Network -description: Guide to the Stacks 2.0 network -sidebar_position: 7 ---- - -## Tokens - -Stacks (STX) tokens are the native tokens on the Stacks 2.0 blockchain. The smallest fraction is one micro-STX. 1,000,000 micro-STX make one Stacks (STX). - -STX amounts should be stored as integers (8 bytes long), and represent the amount of micro-STX. For display purposes, micro-STX are divided by 1,000,000 (decimal precision of 6). - -## 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 in bytes. The fee rate is a market determined variable. For the [testnet](testnet), it is set to 1 micro-STX. - -Fee estimates can obtained through the [`GET /v2/fees/transfer`](https://docs.hiro.so/api#operation/get_fee_transfer) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/fees/transfer' -``` - -The API will respond with the fee rate (as integer): - -```json -1 -``` - -[The Stacks Transactions JS library](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) supports fee estimation for: - -- token transfers (`estimateTransfer`) -- contract deploys (`estimateContractDeploy`) -- non read-only contract calls (`estimateContractFunctionCall`) - -:::tip For an implementation using a different language than JavaScript, please review [this reference implementation](https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/src/builders.ts#L97). ::: - -## Nonces - -Every account carries a [nonce property](https://en.wikipedia.org/wiki/Cryptographic_nonce) that indicates the number of transactions processed for the given account. Nonces are one-time codes, starting at `0` for new accounts, and incremented by 1 on every transaction. - -Nonces are added to all transactions and help identify them in order to ensure transactions are processed in order and to avoid duplicated processing. - -:::tip -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 is constructed, the most recent nonce of the account needs to fetched and set. - -:::tip The API provides an endpoint to [simplify nonce handling](https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling). ::: - -## Confirmations - -The Stacks 2.0 network is anchored onto the bitcoin network. This allows transactions on Stacks to inherit the same finality and security of the Bitcoin blockchain. - -The time to mine a block, to confirm transactions, will eventually match the expected "block time" of the bitcoin network: 10 minutes. - -:::tip Transactions can also be mined in [microblocks](microblocks), reducing the latency significantly. ::: - -The block time is hardcoded and will change throughout the implementation phases of the [testnet](testnet). The current block time can be obtained through the [`GET /extended/v1/info/network_block_times`](https://docs.hiro.so/api#operation/get_network_block_times) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/info/network_block_times' -``` - -The API will respond with the block time (in seconds): - -```js -{ - "testnet": { - "target_block_time": 120 - }, - "mainnet": { - "target_block_time": 600 - } -} -``` - -## Read-only function calls - -Smart contracts can expose public function calls. For functions that make state modifications to the blockchain, transactions need to be generated and broadcasted. - -However, for read-only function calls, transactions are **not** required. Instead, these calls can be done using the [Stacks Blockchain API](https://docs.hiro.so/get-started/stacks-blockchain-api). - -:::tip -Read-only function calls do not require transaction fees -::: - -A read-only contract call can be done using the [`POST /v2/contracts/call-read///`](https://docs.hiro.so/api#operation/call_read_only_function) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl --location --request POST 'https://stacks-node-api.testnet.stacks.co/v2/contracts/call-read///' \ ---header 'Content-Type: application/json' \ ---data-raw '{ - "sender": ".", - "arguments": [, ...] -}' -``` - -Sample response for a successful call: - -```js -{ - "okay": true, - "result": "" -} -``` - -:::tip To set the function call arguments and read the result, [Clarity values](../write-smart-contracts/values) need to be serialized into a hexadecimal string. The [Stacks Transactions JS](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library supports these operations ::: - -## Querying - -Stacks 2.0 network details can be queried using the [Stacks Blockchain API](https://docs.hiro.so/get-started/stacks-blockchain-api). - -### Health check - -The [status checker](https://stacks-status.com/) is a service that provides a user interface to quickly review the health of the Stacks 2.0 blockchain. - -### Network info - -The network information can be obtained using the [`GET /v2/info`](https://docs.hiro.so/api#operation/get_core_api_info) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/info' -``` - -Sample response: - -```js -{ - "peer_version": 385875968, - "burn_consensus": "826401d65cf3671210a3fb135d827d549c0b4d37", - "burn_block_height": 1972, - "stable_burn_consensus": "e27ea23f199076bc41a729d76a813e125b725f64", - "stable_burn_block_height": 1971, - "server_version": "blockstack-core 0.0.1 => 23.0.0.0 (master:bdd042242+, release build, linux [x86_64]", - "network_id": 2147483648, - "parent_network_id": 3669344250, - "stacks_tip_height": 933, - "stacks_tip": "1f601823fbcc5b6b2215b2ff59d2818fba61ee4a3cea426d8bc3dbb268005d8f", - "stacks_tip_burn_block": "54c56a9685545c45accf42b5dcb2787c97eda8185a1c794daf9b5a59d4807abc", - "unanchored_tip": "71948ee211dac3b241eb65d881637f649d0d49ac08ee4a41c29217d3026d7aae", - "exit_at_block_height": 28160 -} -``` diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md b/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md deleted file mode 100644 index c933f7af68..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Proof of Transfer -description: Understand the proof-of-transfer consensus mechanism -sidebar_position: 3 ---- - -## Overview - -Consensus algorithms for blockchains require compute or financial resources to secure the blockchain. The general practice of decentralized consensus is to make it practically infeasible for any single malicious actor to have enough computing power or ownership stake to attack the network. - -Popular consensus mechanisms in modern blockchains include proof-of-work, in which nodes dedicate computing resources, and proof-of-stake, in which nodes dedicate financial resources to secure the network. - -Proof-of-burn is a novel consensus mechanism where miners compete by ‘burning’ (destroying) a proof-of-work cryptocurrency as a proxy for computing resources. - -Proof-of-transfer (PoX) is an extension of the proof-of-burn mechanism. 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. - -![PoX mechanism](/img/pox-mechanism.png) - -This allows network participants to secure the PoX cryptocurrency network and earn a reward in the base cryptocurrency. Thus, proof-of-transfer blockchains are anchored on their chosen proof-of-work chain. Stacks uses [Bitcoin](#why-bitcoin) as its anchor chain. - -![PoX participants](/img/pox-participants.png) - -## Why Bitcoin? - -There are a number of reasons that Stacks chose Bitcoin as the blockchain to power consensus. It's the oldest blockchain protocol, having launched in 2009, and has become a recognized asset outside of the cryptocurrency community. BTC has held the highest market capitalization of any cryptocurrency for the past decade. - -Bitcoin champions simplicity and stability, and has stood the test of time. Influencing or attacking the network is infeasible or impractical for any potential hackers. It's one of the only cryptocurrencies to capture public attention. Bitcoin is a household name, and is recognized as an asset by governments, large corporations, and legacy banking institutions. Lastly, Bitcoin is largely considered a reliable store of value, and provides extensive infrastructure to support the proof-of-transfer consensus mechanism. - -SIP-001 provides a full [list of reasons why Bitcoin was chosen to secure Stacks](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md). - -![btc-stacks](/img/pox-why-bitcoin.png) - -## Blocks and microblocks - -The Stacks blockchain allows for increased transaction throughput using a mechanism called microblocks. Bitcoin and Stacks progress in lockstep, and their blocks are confirmed simultaneously. On Stacks, this is referred to as an ‘anchor block’. An entire block of Stacks transactions corresponds to a single Bitcoin transaction. This significantly improves cost/byte ratio for processing Stacks transactions. Because of simultaneous block production, Bitcoin acts as a rate-limiter for creating Stacks blocks, thereby preventing denial-of-service attacks on its peer network. - -However, in between Stacks anchor blocks settling on the Bitcoin blockchain, there are also a varying number of microblocks that allow rapid settlement of Stacks transactions with a high degree of confidence. This allows Stacks transaction throughput to scale independently of Bitcoin, while still periodically establishing finality with the Bitcoin chain. The Stacks blockchain adopts a block streaming model whereby each leader can adaptively select and package transactions into their block as they arrive in the mempool. Therefore when an anchor block is confirmed, all of the transactions in the parent microblock stream are packaged and processed. This is an unprecedented method for achieving scalability without creating a totally separate protocol from Bitcoin. - -![stx-microblock](/img/stx-microblocks.png) - -## Unlocking Bitcoin capital - -Stacks also unlocks the hundreds of billions in capital in Bitcoin, and gives Bitcoiners new opportunities to use and earn BTC. Stacks is a accompaniment to the Bitcoin ecosystem, and the two networks working in tandem enables totally novel ways of using BTC. The Stacks ecosystem makes interactive cryptocurrency applications available to Bitcoin holders. Additionally, By stacking STX tokens and participating in the PoX consensus mechanism, users have the opportunity to earn BTC while securing the Stacks chain. - -![Unlocking Bitcoin](/img/pox-unlocking-btc.png) - -## Clarity and the Bitcoin state - -Clarity smart contracts also have unique visibility into the state of the Bitcoin blockchain. This means that contract logic in a Clarity file has the ability to trigger when specific Bitcoin transactions are confirmed. Clarity smart contracts have a built in Simple Payment Verification (SPV) proofs for Bitcoin that make interacting with Bitcoin’s state much simpler for developers. Additionally, Clarity contracts can fork with the original Bitcoin chain. Therefore, in an edge case where Bitcoin forks, developers wouldn’t have to worry about adjusting the deployment of their smart contracts. - -## See also - -- [Read the full PoX whitepaper](https://community.stacks.org/pox) -- [Watch Executive Chair of Hiro Muneeb Ali and Evangelist Joe Bender give an overview of Stack's breakthrough PoX mining mechanism](https://www.youtube.com/watch?v=NY_eUrIcWOY) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md b/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md deleted file mode 100644 index 5f3863e8dd..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: Stacking -description: Introduction to the reward mechanism of Proof-of-Transfer -sidebar_position: 9 ---- - -## Introduction - -Stacking rewards Stacks (STX) token holders with bitcoin for providing a valuable service to the network by locking up their tokens for a certain time. - -![](/img/stacking.png) - -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. - -:::info The Stacking consensus algorithm is implemented as a smart contract, using [Clarity](../write-smart-contracts/). [Read more about the contract](../noteworthy-contracts/stacking-contract). ::: - -## Stacking flow - -The Stacking mechanism can be presented as a flow of actions: - -![Stacking flow](/img/stacking-illustration.png) - -1. Make API calls to get details about the upcoming reward cycle -2. For a specific Stacks account, confirm eligibility -3. Confirm the BTC reward address and the lockup duration -4. The transaction is broadcasted and the STX tokens are locked. This needs to happen before the prepare phase of the next reward cycle, the last 100 Bitcoin blocks of the ongoing reward phase -5. The Stacking mechanism executes reward cycles and sends out rewards to the set BTC reward address -6. During the lockup period, details about unlocking timing, rewards and more can be obtained -7. Once the lockup period is passed, the tokens are released and accessible again -8. Display reward history, including details like earnings for previous reward cycles - -:::info Keep in mind that the target duration for a reward cycles is ~2 weeks. This duration is based on the target block time of the network (10 minutes) and can be higher at times due to [confirmation time variances](https://www.blockchain.com/charts/median-confirmation-time) of the bitcoin network. ::: - -## Stacking delegation flow - -The Stacking flow is different for delegation use cases: - -![Delegated tacking flow](/img/stacking-delegation-illustration.png) - -- Before Stacking can be initiated for a token holder, the delegator needs to be granted permission to Stack on behalf of the account owner. The permission is restricted to the maximum amount the delegator is allowed to Stack. The maximum amount is not limited by the available funds and can be set much higher. An account can only be associated with one single delegator -- The account has to define the delegation relationship. They can optionally restrict the Bitcoin reward address that must be used for payouts, and the expiration burn block height for the permission, thus limiting the time a delegator has permission to Stack -- Delegators have to lock Stacks from different accounts ("pooling phase") until they reach the minimum amount of Stacks required to participate in Stacking -- Once a delegator locks enough STX tokens, they can finalize and commit their participation in the next reward cycle -- Certain delegation relationships may allow the STX holder to receive the payout directly from the miner (step 5/6) -- The termination of the delegation relationship can either happen automatically based on set expiration rules or by actively revoking delegation rights - -## PoX mining - -PoX mining is a modification of Proof-of-Burn (PoB) mining, where instead of sending the committed Bitcoin to a burn address, it's transferred to eligible STX holders that participate in the stacking protocol. - -:::note -A PoX miner can only receive newly minted STX tokens when they transfer Bitcoin to eligible owners of STX tokens -::: - -![Mining flow](/img/pox-mining-flow.png) - -Miners run Stacks nodes with mining enabled to participate in the PoX mechanism. The node implements the PoX mechanism, which ensures proper handling and incentives through four key phases: - -- Registration: miners register for a future election by sending consensus data to the network -- Commitment: registered miners transfer Bitcoin to participate in the election. Committed BTC are sent to a set participating STX token holders -- Election: a verifiable random function chooses one miner to write a new block on the Stacks blockchain -- Assembly: the elected miner writes the new block and collects rewards in form of new STX tokens - -## Token holder eligibility - -Stacks (STX) token holders don't automatically receive stacking rewards. Instead, they must: - -- Commit to participation before a reward cycle begins -- Commit the minimum amount of STX tokens to secure a reward slot, or pool with others to reach the minimum -- Lock up STX tokens for a specified period -- Provide a supported Bitcoin address to receive rewards (native segwit is not supported) - -The following diagram describes how the minimum STX tokens per slot is determined. More information on [dynamic minimums for stacking](https://stacking.club) is available at stacking.club. - -![Dynamic minimum for individual eligibility](/img/stacking-dynamic-minimum.png) - -Token holders have a variety of providers and tools to support their participation in Stacking. The Stacks website contains a [list of stacking providers and pools](https://stacks.org/stacking#earn). - -## Stacking in the PoX consensus algorithm - -Stacking is a built-in capability of PoX and occurs through a set of actions on the Stacks blockchain. The [full proof-of-transfer implementation details](https://github.com/stacks-network/stacks-blockchain/blob/develop/sip/sip-007-stacking-consensus.md) are in SIP-007. Below is a summary of the most relevant actions of the algorithm. - -![PoX cycles](/img/pox-cycles.png) - -- Stacking happens over reward cycles with a fixed length. In each reward cycle, a set of Bitcoin addresses associated with stacking participants receive BTC rewards -- A reward cycle consists of two phases: prepare and reward -- During the prepare phase, miners decide on an anchor block and a reward set. Mining any descendant forks of the anchor block requires transferring mining funds to the appropriate reward addresses. The reward set is the set of Bitcoin addresses which are eligible to receive funds in the reward cycle -- Miners register as leader candidates for a future election by sending a key transaction that burns cryptocurrency. The transaction also registers the leader's preferred chain tip (must be a descendant of the anchor block) and commitment of funds to 2 addresses from the reward set -- Token holders register for the next rewards cycle by broadcasting a signed message that locks up associated STX tokens for a protocol-specified lockup period, specifies a Bitcoin address to receive the funds, and votes on a Stacks chain tip -- Multiple leaders can commit to the same chain tip. The leader that wins the election and the peers who also burn for that leader collectively share the reward, proportional to how much each one burned -- Token holders' locked up tokens automatically unlock as soon as the lockup period finishes - -## Bitcoin address - -:::danger You must provide a BTC address in one of two formats: - -* [Legacy (P2PKH)](https://en.bitcoin.it/wiki/Transaction#Pay-to-PubkeyHash), which starts with `1`. - -* [Segregated Witness / Segwit (P2SH)](https://en.bitcoin.it/wiki/Pay_to_script_hash), which starts with `3`. The "Native Segwit" format (which starts with `bc1`), for example, is not supported. ::: - -The Stacking contract needs a special format for the Bitcoin address (the reward address). This is required to ensure that miners are able to correctly construct the Bitcoin transaction containing the reward address. - -The address must be specified in the following format using the Clarity language: - -```clar -;; a tuple of a version and hashbytes buffer -(pox-addr (tuple (version (buff 1)) (hashbytes (buff 20)))) -``` - -The `version` buffer must represent what kind of bitcoin address is being submitted. It can be one of the following: - -```js -SerializeP2PKH = 0x00, // hash160(public-key), same as bitcoin's p2pkh -SerializeP2SH = 0x01, // hash160(multisig-redeem-script), same as bitcoin's multisig p2sh -SerializeP2WPKH = 0x02, // hash160(segwit-program-00(p2pkh)), same as bitcoin's p2sh-p2wpkh -SerializeP2WSH = 0x03, // hash160(segwit-program-00(public-keys)), same as bitcoin's p2sh-p2wsh -``` - -The `hashbytes` are the 20 hash bytes of the bitcoin address. You can obtain that from a bitcoin library, for instance using [`bitcoinjs-lib`](https://github.com/bitcoinjs/bitcoinjs-lib): - -```js -const btc = require('bitcoinjs-lib'); -console.log( - '0x' + btc.address.fromBase58Check('1C56LYirKa3PFXFsvhSESgDy2acEHVAEt6').hash.toString('hex') -); -``` - -## Choosing the right Stacking strategy - -[Here](https://blog.stacks.co/stacking-strategy) is an interesting article that may help you choose the right Stacking stategy. - - -## Where to Stacks? - -You can Stack on your own, on a pool or on an exchange: -### Stacking on your own - -Stacking on your own is non-custodial. - -Stacking on your own requires a protocol minimum (amount changes but about 100,000 STX). - -[Hiro Wallet](https://www.hiro.so/wallet) allows stacking on your own. - -### Stacking on a pool - -Stacking on a pool allows Stacking without the requirement of the protocol minumum. - -Some available pools are: - -| Pool | Type | Pays rewards in | Fee | Minimum amount | -| --------------------------------------------------- | ------------- |:---------------:| --- |:--------------:| -| [Friedger's Pool](https://pool.friedger.de/) | Non custodial | STX or xBTC | No | 40 STX | -| [Planbetter](https://planbetter.org/) | Non custodial | BTC | 5% | 200 STX | -| [Stacked](https://staking.staked.us/stacks-staking) | Non custodial | BTC | | 100,000 STX | -| [Xverse](https://www.xverse.app/) | Non custodial | BTC | No | 100 STX | - -### Stacking on an exchange - -Stacking on an exchange is custodial, meaning you are trusting the exchange with your Stacks. - -Several exchanges allow Stacking directly on their sites. Examples are [Okcoin](https://www.okcoin.com) and [Binance](https://www.binance.com/en/staking) - -## Stacking statistics - -You can view all sorts of Stacking data and statistics on [Stacking Club](https://stacking.club) \ No newline at end of file diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md b/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md deleted file mode 100644 index d942d6af8f..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Stacks Blockchain API -description: Interacting with the Stacks 2.0 Blockchain via API ---- - -## Temporal page because of a Crowdin bug \ No newline at end of file diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md b/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md deleted file mode 100644 index e370129d1d..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Technical Specifications -description: Summary of technical specifications of Stacks 2.0 -sidebar_position: 10 ---- - -## Consensus - -- Proof of Transfer (PoX) as described in [SIP-007](https://github.com/stacksgov/sips/blob/main/sips/sip-007/sip-007-stacking-consensus.md) -- Network will transition to Proof of Burn (PoB) as described in [SIP-001](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md) after 10 years. [Learn more about Proof-of-Burn in SIP-001](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md). -- Threat model - - 51% of malicious Stacks mining power can perform a double-spend attack - - 51% of malicious Bitcoin mining power can reorg the Stacks chain -- Different actors and their roles - - Stacks Miners package transactions into blocks, mine them through a Bitcoin transaction, propagate them, and if they win the block race, append microblocks to their winning block until the next block is mined. The next block confirms the microblock stream. - - Stacks Holders may alter the calculation of block limits (subject to a miner veto) and may vote to disable Proof-of-Transfer rewards for a reward cycle. -- Transactions are considered final when the corresponding "block commit" transaction on Bitcoin is finalized. Typically this can by 3-6 confirmations. -- For more details, see [Proof of Transfer](proof-of-transfer). - -## Proof of Transfer Mining - -- Coinbase reward schedule: - - 1000 STX/block for first 4 years - - 500 STX/block for following 4 years - - 250 STX/block for subsequent 4 years - - 125 STX/block in perpetuity after that -- Coinbase rewards accumulate for "missed sortitions": If a Bitcoin block has no sortition (at height N), then any Stacks block mined in a subsequent sortition that builds off of any Stacks chain tip that existed at the penultimate sortition (at height N-1) may claim its coinbase. This encourages miners to keep mining even if Bitcoin fees are high. -- Initial mining bonus: This is a special case of the above to incentivize early miners. Coinbase for all burnchain blocks between the first burn block height (to be chosen by independent miners as part of the Stacks 2.0 launch) and the first sortition winner accumulate and are distributed to miners over a fixed window (to be determined). For instance, say burn block height is 10,000 and first sortition is at block 10500 and distribution window is 100 blocks, then coinbase for the first 500 blocks (10,500 - 10,000) will be distributed evenly to miners who win sortition over the subsequent 100 blocks. -- 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 at least 11,000 satoshis (5,500 sats / [UTXO output](https://learnmeabitcoin.com/technical/utxo)); 2 outputs / block) to avoid "dust." -- For more details, see [Mining](mining). - -## Stacking - -- Stacking works in 2 phases - 1. Prepare phase: In this phase an "anchor block" is chosen. The qualifying set of addresses ("reward set") is determined based on the snapshot of the chain at the anchor block. Length of prepare phase is 100 blocks. Stacking commitments need to be confirmed before this phase starts - 2. Reward phase: In this phase miner BTC commitments are distributed amongst the reward set. Reward cycle length is 2000 BTC blocks (~2 weeks). -- 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/stacksgov/sips/blob/main/sips/sip-007/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.stacks.co/references/stacking-contract#delegate-stx). -- Only two types of BTC reward addresses are supported: [Legacy (P2PKH)](https://en.bitcoin.it/wiki/Transaction#Pay-to-PubkeyHash) or [Segregated Witness / Segwit (P2SH)](https://en.bitcoin.it/wiki/Pay_to_script_hash). Native Segwit is not supported. -- Further reading: [Stacking](stacking) - -## Accounts and Addresses - -- Transactions in the Stacks blockchain originate from, are paid for by, and execute under the authority of accounts -- An account is fully specified by its address + nonce + assets -- 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 (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](accounts) - -## Transactions - -- Transaction 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 - 2. _paying account_ is the account that is billed by the leader for the cost of validating and executing the transaction - 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 -- Transactions can be batched or streamed into blocks. The behavior can be controlled by the anchor mode of a transaction. With streaming ([microblocks](microblocks)), a faster confirmation time is possible. -- 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. -- Mempool limit for concurrent pending transactions is 25 per account -- Pending mempool transactions will be garbage-collected [256 blocks after receipt](https://github.com/stacks-network/stacks-blockchain/blob/master/src/core/mempool.rs#L62). With 10 minutes target block time, this would equal ~42 hours -- [Learn more about transaction encoding in SIP-005](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md#transaction-encoding) -- [Transaction signing and verification are described in SIP-005](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md#transaction-signing-and-verifying) -- All transactions impacting account balance are atomic, a transfer operation can not increment one account’s balance without decrementing another’s. However, transactions that perform multiple account actions (for example, transferring from multiple accounts) may partially complete. -- Transactions can include a memo string (max 34 bytes) - -## See also - -- [Read the full Stacks 2.0: Apps and Smart Contracts for Bitcoin whitepaper](https://cloudflare-ipfs.com/ipfs/QmaGgiVHymeDjAc3aF1AwyhiFFwN97pme5m536cHT4FsAW). - -- [Watch Aaron Blankstein video on Stacks whitepater v2](https://www.youtube.com/watch?v=Wd-Bfe8Sn-Y). \ No newline at end of file diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md b/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md deleted file mode 100644 index 59934a5bde..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Testnet -description: Test your smart contracts and apps -sidebar_position: 2 ---- - -## About testnet - -The testnet is a separate blockchain from the Stacks mainnet analogous to a staging environment. It's a network used by developers to test their apps, smart contracts, or changes to the protocol in a production-like environment. It produces blocks at roughly the same rate as mainnet; about 1 block every 10 minutes on average. The Stacks testnet is rarely reset. - -### Faucet - -The testnet faucet provides you with free Stacks Token (STX) to test with. These are not the same as STX on mainnet and have no value. You can get STX from the faucet on the [Stacks Explorer Sandbox](https://explorer.stacks.co/sandbox/faucet?chain=testnet), or using the [API](https://docs.hiro.so/api#tag/Faucets). - -To get STX tokens from within the Explorer Sandbox, navigate to the "Faucet" tab on the left and click "Request STX" button. - -![](/img/stx_faucet.png) - -You can also try out [Stacking](stacking) by clicking on `I want to stack`. - -:::note -The Explorer Sandbox requires you to login with a Stacks wallet -::: - -### Testnet API - -The hosted Stacks Blockchain API for the testnet is available at this base URL: - -```shell -https://stacks-node-api.testnet.stacks.co/ -``` - -![](/img/api_testnet_status.png) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md b/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md deleted file mode 100644 index 2ff6072384..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Transactions -description: Guide to Stacks 2.0 transactions -sidebar_position: 6 ---- - -## Introduction - -Transactions are the fundamental unit of execution in the Stacks blockchain. Each transaction is originated from a [Stacks 2.0 account](accounts), and is retained in the Stacks blockchain history for eternity. This guide helps you understand Stacks 2.0 transactions. - -## Lifecycle - -Transactions go through phases before being finally confirmed, and available for all, on the Stacks 2.0 network. - -![Transaction lifecycle](/img/tx-lifecycle.png) - -- **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/en/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. - -:::note A transaction can have one of three states once it is registered: `pending`, `success`, or `failed`. ::: - -## Types - -The Stacks 2.0 supports a set of different transaction types: - -| **Type** | **Value** | **Description** | -| ----------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Coinbase | `coinbase` | The first transaction in a new block (an entity holding several transactions). Used to register for block rewards. These are not manually generated and broadcasted like other types of transactions. | -| Token transfer | `token_transfer` | Asset transfer from a sender to a recipient | -| Contract deploy | `smart_contract` | Contract instantiation | -| Contract call | `contract_call` | Contract call for a public, non read-only function | -| Poison Microblock | `poison_microblock` | Punish leaders who intentionally equivocate about the microblocks they package | - -A sample of each transaction type can be found in the [Stacks Blockchain API response definition for transactions](https://docs.hiro.so/api#operation/get_transaction_by_id). - -:::caution Read-only contract call calls do **not** require transactions. Read more about it in the [network guide](network#read-only-function-calls). ::: diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md b/i18n/tr/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md deleted file mode 100644 index fd45c80583..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Clarity Language -description: Overview of the Clarity language constructs -sidebar_label: Clarity Language -tags: - - clarity ---- - -## Clarity Type System - -The Clarity language uses a strong static type system. Function arguments and database schemas require specified types, and use of types is checked during contract launch. The type system does _not_ have a universal super type. - -## Public Functions - -Functions specified via `define-public` statements are _public_ functions and these are the only types of functions which may be called directly through signed blockchain transactions. In addition to being callable directly from a transaction (see the Stacks wire formats for more details on Stacks transactions), public functions may be called by other smart contracts. - -Public functions _must_ return a `(response ...)` type. This is used by Clarity to determine whether or not to materialize any changes from the execution of the function. If a function returns an `(err ...)` type, any mutations on the blockchain state from executing the function (and any function that it called during execution) will be aborted. - -In addition to functions defined via `define-public`, contracts may expose read-only functions. These functions, defined via `define-read-only`, are callable by other smart contracts, and may be queryable via public blockchain explorers. These functions _may not_ mutate any blockchain state. Unlike normal public functions, read-only functions may return any type. - -## Contract Calls - -A smart contract may call functions from other smart contracts using a `(contract-call?)` function. - -This function returns a response type result -- the return value of the called smart contract function. - -We distinguish 2 different types of `contract-call?`: - -### Static dispatch - -The callee is a known, invariant contract available on-chain when the caller contract is deployed. In this case, the callee's principal is provided as the first argument, followed by the name of the method and its arguments: - -```clarity -(contract-call? - .registrar - register-name - name-to-register) -``` - -### Dynamic dispatch - -The callee is passed as an argument, and typed as a trait reference (``). - -```clarity -(define-public (swap (token-a ) - (amount-a uint) - (owner-a principal) - (token-b ) - (amount-b uint) - (owner-b principal))) - (begin - (unwrap! (contract-call? token-a transfer-from? owner-a owner-b amount-a)) - (unwrap! (contract-call? token-b transfer-from? owner-b owner-a amount-b)))) -``` - -Traits can either be locally defined: - -```clarity -(define-trait can-transfer-tokens ( - (transfer-from? (principal principal uint) (response uint))) -``` - -Or imported from an existing contract: - -```clarity -(use-trait can-transfer-tokens - .contract-defining-trait.can-transfer-tokens) -``` - -Looking at trait conformance, callee contracts have two different paths. They can either be "compatible" with a trait by defining methods matching some of the methods defined in a trait, or explicitly declare conformance using the `impl-trait` statement: - -```clarity -(impl-trait .contract-defining-trait.can-transfer-tokens) -``` - -Explicit conformance should be prefered when adequate. It acts as a safeguard by helping the static analysis system to detect deviations in method signatures before contract deployment. - -The following limitations are imposed on contract calls: - -1. On static dispatches, callee smart contracts _must_ exist at the time of creation. -2. No cycles may exist in the call graph of a smart contract. This prevents recursion (and re-entrancy bugs). Such structures can be detected with static analysis of the call graph, and will be rejected by the network. -3. `contract-call?` are for inter-contract calls only. Attempts to execute when the caller is also the callee will abort the transaction. diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md b/i18n/tr/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md deleted file mode 100644 index a6011cca8b..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md +++ /dev/null @@ -1,1388 +0,0 @@ ---- -title: Functions -description: See a detailed list of all functions for the Clarity language. -tags: - - clarity ---- - -## Functions - -Detailed list of all functions for the Clarity language. - -### + (add) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(+ i1 i2...)` -#### description: -Adds a variable number of integer inputs and returns the result. In the event of an _overflow_, throws a runtime error. -#### example: -```clarity -(+ 1 2 3) ;; Returns 6 -(+ 2 3) ;; Returns 5 -(+ 1 2 3 4) ;; Returns 10 -(+ 9 -3) ;; Returns 6 -(+ -3 -2) ;; Returns -5 -``` - -### - (subtract) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(- i1 i2...)` -#### description: -Subtracts a variable number of integer inputs and returns the result. In the event of an _underflow_, throws a runtime error. -#### example: -```clarity -(- 2 1 1) ;; Returns 0 -(- 0 3) ;; Returns -3 -(- 5 -3) ;; Returns 8 -(- -4 -5) ;; Returns 1 -``` - -### * (multiply) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(* i1 i2...)` -#### description: -Multiplies a variable number of integer inputs and returns the result. In the event of an _overflow_, throws a runtime error. -#### example: -```clarity -(* 2 3) ;; Returns 6 -(* 5 2) ;; Returns 10 -(* 2 2 2) ;; Returns 8 -(* 3 -2) ;; Returns -6 -(* -1 -2) ;; Returns 2 -``` - -### / (divide) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(/ i1 i2...)` -#### description: -Divides a variable number of integer inputs and returns the _integer part_ of the result. In the event of _division by zero_, throws a runtime error. - -#### example: -```clarity -(/ 2 3) ;; Returns 0 -(/ 5 2) ;; Returns 2 -(/ 4 2 2) ;; Returns 1 -(/ -10 2) ;; Returns -5 -(/ -8 -2) ;; Returns 4 -(/ -9 4) ;; Returns -2 -``` - -### >= (greater than or equal) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(>= i1 i2)` -#### description: -Compares two integers, returning `true` if `i1` is greater than or equal to `i2` and `false` otherwise. -#### example: -```clarity -(>= 1 1) ;; Returns true -(>= 5 2) ;; Returns true -``` - -### <= (less than or equal) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(<= i1 i2)` -#### description: -Compares two integers, returning true if `i1` is less than or equal to `i2` and `false` otherwise. -#### example: -```clarity -(<= 1 1) ;; Returns true -(<= 5 2) ;; Returns false -``` - -### < (less than) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(< i1 i2)` -#### description: -Compares two integers, returning `true` if `i1` is less than `i2` and `false` otherwise. -#### example: -```clarity -(< 1 2) ;; Returns true -(< 5 2) ;; Returns false -``` - -### > (greater than) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(> i1 i2)` -#### description: -Compares two integers, returning `true` if `i1` is greater than `i2` and false otherwise. -#### example: -```clarity -(> 1 2) ;; Returns false -(> 5 2) ;; Returns true -``` - -### to-int -#### input: `uint` -#### output: `int` -#### signature: `(to-int u)` -#### description: -Tries to convert the `uint` argument to an `int`. Will cause a runtime error and abort if the supplied argument is >= `pow(2, 127)`` -#### example: -```clarity -(to-int u238) ;; Returns 238 -``` - -### to-uint -#### input: `int` -#### output: `uint` -#### signature: `(to-uint i)` -#### description: -Tries to convert the `int` argument to a `uint`. Will cause a runtime error and abort if the supplied argument is negative. -#### example: -```clarity -(to-uint 238) ;; Returns u238 -``` - -### mod -#### input: `int, int | uint, uint` -#### output: `int | uint` -#### signature: `(mod i1 i2)` -#### description: -Returns the integer remainder from integer dividing `i1` by `i2`. In the event of a division by zero, throws a runtime error. -#### example: -```clarity -(mod 2 3) ;; Returns 2 -(mod 5 2) ;; Returns 1 -(mod 7 1) ;; Returns 0 -``` - -### pow -#### input: `int, int | uint, uint` -#### output: `int | uint` -#### signature: `(pow i1 i2)` -#### description: -Returns the result of raising `i1` to the power of `i2`. In the event of an _overflow_, throws a runtime error. -#### example: -```clarity -(pow 2 3) ;; Returns 8 -(pow 2 2) ;; Returns 4 -(pow 7 1) ;; Returns 7 -``` - -### sqrti -#### input: `int | uint` -#### output: `int | uint` -#### signature: `(sqrti n)` -#### description: -Returns the largest integer that is less than or equal to the square root of `n`. Fails on a negative numbers. -#### example: -```clarity -(sqrti u11) ;; Returns u3 -(sqrti 1000000) ;; Returns 1000 -(sqrti u1) ;; Returns u1 -(sqrti 0) ;; Returns 0 -``` - -### log2 -#### input: `int | uint` -#### output: `int | uint` -#### signature: `(log2 n)` -#### description: -Returns the _integer part_ of the power to which the number 2 must be raised to obtain the value `n`. Fails on zero or a negative number. -#### example: -```clarity -(log2 u8) ;; Returns u3 -(log2 8) ;; Returns 3 -(log2 u1) ;; Returns u0 -(log2 1000) ;; Returns 9 -``` - -### xor -#### input: `int, int | uint, uint` -#### output: `int | uint` -#### signature: `(xor i1 i2)` -#### description: -Returns the result of bitwise exclusive or'ing `i1` with `i2`. -#### example: -```clarity -(xor 1 2) ;; Returns 3 -(xor 120 280) ;; Returns 352 -``` - -### and -#### input: `bool, ...` -#### output: `bool` -#### signature: `(and b1 b2 ...)` -#### description: -Returns `true` if all boolean inputs are `true`. Importantly, the supplied arguments are evaluated in-order and lazily. Lazy evaluation means that if one of the arguments returns `false`, the function short-circuits, and no subsequent arguments are evaluated. -#### example: -```clarity -(and true false) ;; Returns false -(and (is-eq (+ 1 2) 1) (is-eq 4 4)) ;; Returns false -(and (is-eq (+ 1 2) 3) (is-eq 4 4)) ;; Returns true -``` - -### or -#### input: `bool, ...` -#### output: `bool` -#### signature: `(or b1 b2 ...)` -#### description: -Returns `true` if any boolean inputs are `true`. Importantly, the supplied arguments are evaluated in-order and lazily. Importantly, the supplied arguments are evaluated in-order and lazily. -#### example: -```clarity -(or true false) ;; Returns true -(or (is-eq (+ 1 2) 1) (is-eq 4 4)) ;; Returns true -(or (is-eq (+ 1 2) 1) (is-eq 3 4)) ;; Returns false -(or (is-eq (+ 1 2) 3) (is-eq 4 4)) ;; Returns true -``` - -### not -#### input: `bool` -#### output: `bool` -#### signature: `(not b1)` -#### description: -Returns the inverse of the boolean input. -#### example: -```clarity -(not true) ;; Returns false -(not (is-eq 1 2)) ;; Returns true -``` - -### is-eq -#### input: `A, A, ...` -#### output: `bool` -#### signature: `(is-eq v1 v2...)` -#### description: -Compares the inputted values, returning `true` if they are all equal. Note that _unlike_ the `(and ...)` function, `(is-eq ...)` will _not_ short-circuit. All values supplied to is-eq _must_ be the same type. -#### example: -```clarity -(is-eq 1 1) ;; Returns true -(is-eq true false) ;; Returns false -(is-eq \"abc\" 234 234) ;; Throws type error -``` - -### if -#### input: `bool, A, A` -#### output: `A` -#### signature: `(if bool1 expr1 expr2)` -#### description: -The `if` function admits a boolean argument and two expressions which must return the same type. In the case that the boolean input is `true`, the `if` function evaluates and returns `expr1`. If the boolean input is `false`, the `if` function evaluates and returns `expr2`. -#### example: -```clarity -(if true 1 2) ;; Returns 1 -(if (> 1 2) 1 2) ;; Returns 2 -``` - -### let -#### input: `((name1 AnyType) (name2 AnyType) ...), AnyType, ... A` -#### output: `A` -#### signature: `(let ((name1 expr1) (name2 expr2) ...) expr-body1 expr-body2 ... expr-body-last)` -#### description: -The `let` function accepts a list of `variable name` and `expression` pairs, evaluating each expression and _binding_ it to the corresponding variable name. `let` bindings are sequential: when a `let` binding is evaluated, it may refer to prior binding. The _context_ created by this set of bindings is used for evaluating its body expressions. The let expression returns the value of the last such body expression. Note: intermediary statements returning a response type must be checked` -#### example: -```clarity -(let ((a 2) (b (+ 5 6 7))) (print a) (print b) (+ a b)) ;; Returns 20 -(let ((a 5) (c (+ a 1)) (d (+ c 1)) (b (+ a c d))) (print a) (print b) (+ a b)) ;; Returns 23 -``` - -### map -#### input: `Function(A, B, ..., N) -> X, sequence_A, sequence_B, ..., sequence_N` -#### output: `(list X)` -#### signature: `(map func sequence_A sequence_B ... sequence_N)` -#### description: -Also, note that, no matter what kind of sequences the inputs are, the output is always a list. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. The `map` function applies the function `func` to each corresponding element of the input sequences, and outputs a _list_ of the same type containing the outputs from those function applications. -#### example: -```clarity -(map not (list true false true false)) ;; Returns (false true false true) -(map + (list 1 2 3) (list 1 2 3) (list 1 2 3)) ;; Returns (3 6 9) -(define-private (a-or-b (char (string-utf8 1))) (if (is-eq char u\"a\") u\"a\" u\"b\")) -(map a-or-b u\"aca\") ;; Returns (u\"a\" u\"b\" u\"a\") -(define-private (zero-or-one (char (buff 1))) (if (is-eq char 0x00) 0x00 0x01)) -(map zero-or-one 0x000102) ;; Returns (0x00 0x01 0x01) -``` - -### fold -#### input: `Function(A, B) -> B, sequence_A, B` -#### output: `B` -#### signature: `(fold func sequence_A initial_B)` -#### description: -The `fold` function condenses `sequence_A` into a value of type `B` by recursively applies the function `func` to each element of the input sequence _and_ the output of a previous application of `func`. - -`fold` uses `initial_B` in the initial application of `func`, along with the first element of `sequence_A`. The resulting value of type `B` is used for the next application of `func`, along with the next element of `sequence_A` and so on. `fold` returns the last value of type `B` returned by these successive applications `func`. - -Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. - -#### example: -```clarity -(fold * (list 2 2 2) 1) ;; Returns 8 -(fold * (list 2 2 2) 0) ;; Returns 0 -;; calculates (- 11 (- 7 (- 3 2))) -(fold - (list 3 7 11) 2) ;; Returns 5 -(define-private (concat-string (a (string-ascii 20)) (b (string-ascii 20))) (unwrap-panic (as-max-len? (concat a b) u20))) -(fold concat-string \"cdef\" \"ab\") ;; Returns \"fedcab\" -(fold concat-string (list \"cd\" \"ef\") \"ab\") ;; Returns \"efcdab\" -(define-private (concat-buff (a (buff 20)) (b (buff 20))) (unwrap-panic (as-max-len? (concat a b) u20))) -(fold concat-buff 0x03040506 0x0102) ;; Returns 0x060504030102 -``` - -### append -#### input: `list A, A` -#### output: `list` -#### signature: `(append (list 1 2 3 4) 5)` -#### description: -The `append` function takes a list and another value with the same entry type, and outputs a list of the same type with max_len += 1. -#### example: -```clarity -(append (list 1 2 3 4) 5) ;; Returns (1 2 3 4 5) -``` - -### concat -#### input: `sequence_A, sequence_A` -#### output: `sequence_A` -#### signature: `(concat sequence1 sequence2)` -#### description: -The `func` argument must be a literal function name. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. - -#### example: -```clarity -(concat (list 1 2) (list 3 4)) ;; Returns (1 2 3 4) -(concat \"hello \" \"world\") ;; Returns \"hello world\" -(concat 0x0102 0x0304) ;; Returns 0x01020304 -``` - -### as-max-len? -#### input: `sequence_A, uint` -#### output: `sequence_A` -#### signature: `(as-max-len? sequence max_length)` -#### description: -The `as-max-len?` function takes a sequence argument and a uint-valued, literal length argument. The function returns an optional type. If the input sequence length is less than or equal to the supplied max_length, this returns `(some sequence)`, otherwise it returns `none`. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. ` -#### example: -```clarity -(as-max-len? (list 2 2 2) u3) ;; Returns (some (2 2 2)) -(as-max-len? (list 1 2 3) u2) ;; Returns none -(as-max-len? \"hello\" u10) ;; Returns (some \"hello\") -(as-max-len? 0x010203 u10) ;; Returns (some 0x010203) -``` - -### len -#### input: `sequence_A` -#### output: `uint` -#### signature: `(len sequence)` -#### description: -The `len` function returns the length of a given sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. ` -#### example: -```clarity -(len \"blockstack\") ;; Returns u10 -(len (list 1 2 3 4 5)) ;; Returns u5 -(len 0x010203) ;; Returns u3 -``` - -### element-at -#### input: `sequence_A, uint` -#### output: `(optional A)` -#### signature: `(element-at sequence index)` -#### description: -The `element-at` function returns the element at `index` in the provided sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. ` -#### example: -```clarity -(element-at \"blockstack\" u5) ;; Returns (some \"s\") -(element-at (list 1 2 3 4 5) u5) ;; Returns none -(element-at (list 1 2 3 4 5) (+ u1 u2)) ;; Returns (some 4) -(element-at \"abcd\" u1) ;; Returns (some \"b\") -(element-at 0xfb01 u1) ;; Returns (some 0x01) -``` - -### index-of -#### input: `sequence_A, A` -#### output: `(optional uint)` -#### signature: `(index-of sequence item)` -#### description: -The `index-of` function returns the first index at which `item` can be found, using `is-eq` checks, in the provided sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. If the target item is not found in the sequence (or if an empty string or buffer is supplied), this function returns `none`. -#### example: -```clarity -(index-of \"blockstack\" \"b\") ;; Returns (some u0) -(index-of \"blockstack\" \"k\") ;; Returns (some u4) -(index-of \"blockstack\" \"\") ;; Returns none -(index-of (list 1 2 3 4 5) 6) ;; Returns none -(index-of 0xfb01 0x01) ;; Returns (some u1) -``` - -### list -#### input: `A, ...` -#### output: `(list A)` -#### signature: `(list expr1 expr2 expr3 ...)` -#### description: -The `list` function constructs a list composed of the inputted values. Each supplied value must be of the same type. -#### example: -```clarity -(list (+ 1 2) 4 5) ;; Returns (3 4 5) -``` - -### var-get -#### input: `VarName` -#### output: `A` -#### signature: `(var-get var-name)` -#### description: -The `var-get` function looks up and returns an entry from a contract's data map. The value is looked up using `var-name`. -#### example: -```clarity -(define-data-var cursor int 6) -(var-get cursor) ;; Returns 6 -``` - -### var-set -#### input: `VarName, AnyType` -#### output: `bool` -#### signature: `(var-set var-name expr1)` -#### description: -The `var-set` function sets the value associated with the input variable to the inputted value. The function always returns `true`. -#### example: -```clarity -(define-data-var cursor int 6) -(var-get cursor) ;; Returns 6 -(var-set cursor (+ (var-get cursor) 1)) ;; Returns true -(var-get cursor) ;; Returns 7 -``` - -### map-get? -#### input: `MapName, tuple` -#### output: `(optional (tuple))` -#### signature: `(map-get? map-name key-tuple)` -#### description: -The `map-get?` function looks up and returns an entry from a contract's data map. The value is looked up using `key-tuple`. If there is no value associated with that key in the data map, the function returns a `none` option. Otherwise, it returns `(some value)`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(map-get? names-map (tuple (name \"blockstack\"))) ;; Returns (some (tuple (id 1337))) -(map-get? names-map { name: \"blockstack\" }) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-set -#### input: `MapName, tuple_A, tuple_B` -#### output: `bool` -#### signature: `(map-set map-name key-tuple value-tuple)` -#### description: -The `map-set` function sets the value associated with the input key to the inputted value. This function performs a _blind_ update; whether or not a value is already associated with the key, the function overwrites that existing association. - -Note: the `value-tuple` requires 1 additional byte for storage in the materialized blockchain state, and therefore the maximum size of a value that may be inserted into a map is MAX_CLARITY_VALUE - 1. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-set names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-insert -#### input: `MapName, tuple_A, tuple_B` -#### output: `bool` -#### signature: `(map-insert map-name key-tuple value-tuple)` -#### description: -The `map-insert` function sets the value associated with the input key to the inputted value if and only if there is not already a value associated with the key in the map. If an insert occurs, the function returns `true`. If a value already existed for this key in the data map, the function returns `false`. - -Note: the `value-tuple` requires 1 additional byte for storage in the materialized blockchain state, and therefore the maximum size of a value that may be inserted into a map is MAX_CLARITY_VALUE - 1. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns false -(map-insert names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-delete -#### input: `MapName, tuple` -#### output: `bool` -#### signature: `(map-delete map-name key-tuple)` -#### description: -The `map-delete` function removes the value associated with the input key for the given map. If an item exists and is removed, the function returns `true`. If a value did not exist for this key in the data map, the function returns `false`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-delete names-map { name: \"blockstack\" }) ;; Returns true -(map-delete names-map { name: \"blockstack\" }) ;; Returns false -(map-delete names-map (tuple (name \"blockstack\"))) ;; Same command, using a shorthand for constructing the tuple -``` - -### tuple -#### input: `(key-name A), (key-name-2 B), ...` -#### output: `(tuple (key-name A) (key-name-2 B) ...)` -#### signature: `(tuple (key0 expr0) (key1 expr1) ...)` -#### description: -The `tuple` special form constructs a typed tuple from the supplied key and expression pairs. A `get` function can use typed tuples as input to select specific values from a given tuple. Key names may not appear multiple times in the same tuple definition. Supplied expressions are evaluated and associated with the expressions' paired key name. - -There is a shorthand using curly brackets of the form {key0: expr0, key1: expr, ...}` -#### example: -```clarity -(tuple (name \"blockstack\") (id 1337)) ;; using tuple -{name: \"blockstack\", id: 1337} ;; using curly brackets -``` - -### get -#### input: `KeyName, (tuple) | (optional (tuple))` -#### output: `A` -#### signature: `(get key-name tuple)` -#### description: -The `get` function fetches the value associated with a given key from the supplied typed tuple. If an `Optional` value is supplied as the inputted tuple, `get` returns an `Optional` type of the specified key in the tuple. If the supplied option is a `(none)` option, get returns `(none)`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(get id (tuple (name \"blockstack\") (id 1337))) ;; Returns 1337 -(get id (map-get? names-map (tuple (name \"blockstack\")))) ;; Returns (some 1337) -(get id (map-get? names-map (tuple (name \"non-existent\")))) ;; Returns none -``` - -### merge -#### input: `tuple, tuple` -#### output: `tuple` -#### signature: `(merge tuple { key1: val1 })` -#### description: -The `merge` function returns a new tuple with the combined fields, without mutating the supplied tuples. -#### example: -```clarity -(define-map users { id: int } { name: (string-ascii 12), address: (optional principal) }) -(map-insert users { id: 1337 } { name: \"john\", address: none }) ;; Returns true -(let ((user (unwrap-panic (map-get? users { id: 1337 })))) -(merge user { address: (some 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) })) ;; Returns (tuple (address (some SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF)) (name \"john\")) -``` - -### begin -#### input: `AnyType, ... A` -#### output: `A` -#### signature: `(begin expr1 expr2 expr3 ... expr-last)` -#### description: -The `begin` function evaluates each of its input expressions, returning the return value of the last such expression. Note: intermediary statements returning a response type must be checked. -#### example: -```clarity -(begin (+ 1 2) 4 5) ;; Returns 5 -``` - -### hash160 -#### input: `buff|uint|int` -#### output: `(buff 20)` -#### signature: `(hash160 value)` -#### description: -The `hash160` function computes `RIPEMD160(SHA256(x))` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(hash160 0) ;; Returns 0xe4352f72356db555721651aa612e00379167b30f -``` - -### sha256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(sha256 value)` -#### description: -The `sha256` function computes `SHA256(x)` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(sha256 0) ;; Returns 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb -``` - -### sha512 -#### input: `buff|uint|int` -#### output: `(buff 64)` -#### signature: `(sha512 value)` -#### description: -The `sha512` function computes `SHA512(x)` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(sha512 1) ;; Returns 0x6fcee9a7b7a7b821d241c03c82377928bc6882e7a08c78a4221199bfa220cdc55212273018ee613317c8293bb8d1ce08d1e017508e94e06ab85a734c99c7cc34 -``` - -### sha512/256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(sha512/256 value)` -#### description: -The `sha512/256` function computes `SHA512/256(x)` (the SHA512 algorithm with the 512/256 initialization vector, truncated to 256 bits) of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(sha512/256 1) ;; Returns 0x515a7e92e7c60522db968d81ff70b80818fc17aeabbec36baf0dda2812e94a86 -``` - -### keccak256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(keccak256 value)` -#### description: -The `keccak256` function computes `KECCAK256(value)` of the inputted value. Note that this differs from the `NIST SHA-3` (that is, FIPS 202) standard. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(keccak256 0) ;; Returns 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4 -``` - -### secp256k1-recover? -#### input: `(buff 32), (buff 65)` -#### output: `(response (buff 33) uint)` -#### signature: `(secp256k1-recover? message-hash signature)` -#### description: -The `secp256k1-recover?` function recovers the public key used to sign the message which sha256 is `message-hash` with the provided `signature`. If the signature does not match, it will return the error code `(err u1).`. If the signature is invalid, it will return the error code `(err u2).`. The signature includes 64 bytes plus an additional recovery id (00..03) for a total of 65 bytes. -#### example: -```clarity -(secp256k1-recover? 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a1301) - ;; Returns (ok 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) - ``` - -### secp256k1-verify -#### input: `(buff 32), (buff 64) | (buff 65), (buff 33)` -#### output: `bool` -#### signature: `(secp256k1-verify message-hash signature public-key)` -#### description: -The `secp256k1-verify` function verifies that the provided signature of the message-hash was signed with the private key that generated the public key. The `message-hash` is the `sha256` of the message. The signature includes 64 bytes plus an optional additional recovery id (00..03) for a total of 64 or 65 bytes. -#### example: -```clarity -(secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a1301 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns true -(secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a13 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns true -(secp256k1-verify 0x0000000000000000000000000000000000000000000000000000000000000000 - 0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns false - ``` - -### print -#### input: `A` -#### output: `A` -#### signature: `(print expr)` -#### description: -The `print` function evaluates and returns its input expression. On Stacks Core nodes configured for development (as opposed to production mining nodes), this function prints the resulting value to `STDOUT` (standard output). -#### example: -```clarity -(print (+ 1 2 3)) ;; Returns 6 -``` - -### contract-call? -#### input: `ContractName, PublicFunctionName, Arg0, ...` -#### output: `(response A B)` -#### signature: `(contract-call? .contract-name function-name arg0 arg1 ...)` -#### description: -The `contract-call?` function executes the given public function of the given contract. You _may not_ use this function to call a public function defined in the current contract. If the public function returns _err_, any database changes resulting from calling `contract-call?` are aborted. If the function returns _ok_, database changes occurred. -#### example: -```clarity - -;; instantiate the sample-contracts/tokens.clar contract first! -(as-contract (contract-call? .tokens mint! u19)) ;; Returns (ok u19) -``` - -### as-contract -#### input: `A` -#### output: `A` -#### signature: `(as-contract expr)` -#### description: -The `as-contract` function switches the current context's `tx-sender` value to the _contract's_ principal and executes `expr` with that context. It returns the resulting value of `expr`. -#### example: -```clarity -(as-contract tx-sender) ;; Returns S1G2081040G2081040G2081040G208105NK8PE5.docs-test -``` - -### contract-of -#### input: `Trait` -#### output: `principal` -#### signature: `(contract-of .contract-name)` -#### description: -The `contract-of` function returns the principal of the contract implementing the trait. -#### example: -```clarity -(use-trait token-a-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) -(define-public (forward-get-balance (user principal) (contract )) - (begin - (ok (contract-of contract)))) ;; returns the principal of the contract implementing -``` - -### principal-of? -#### input: `(buff 33)` -#### output: `(response principal uint)` -#### signature: `(principal-of? public-key)` -#### description: -The `principal-of?` function returns the principal derived from the provided public key. If the `public-key` is invalid, it will return the error code `(err u1).`. ` -#### example: -```clarity -(principal-of? 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns (ok ST1AW6EKPGT61SQ9FNVDS17RKNWT8ZP582VF9HSCP) -``` - -### at-block -#### input: `(buff 32), A` -#### output: `A` -#### signature: `(at-block id-block-hash expr)` -#### description: -The `at-block` function evaluates the expression `expr` _as if_ it were evaluated at the end of the block indicated by the _block-hash_ argument. The `expr` closure must be read-only. - -This hash uniquely identifies Stacks blocks and is unique across Stacks forks. Note: The block identifying hash must be a hash returned by the `id-header-hash` block information property. While the hash returned by `header-hash` is unique within the context of a single fork, it is not unique across Stacks forks. - -The function returns the result of evaluating `expr`. - -#### example: -```clarity -(define-data-var data int 1) -(at-block 0x0000000000000000000000000000000000000000000000000000000000000000 block-height) ;; Returns u0 -(at-block (get-block-info? id-header-hash 0) (var-get data)) ;; Throws NoSuchDataVariable because `data` wasn't initialized at block height 0 -``` - -### get-block-info? -#### input: `BlockInfoPropertyName, BlockHeightInt` -#### output: `(optional buff) | (optional uint)` -#### signature: `(get-block-info? prop-name block-height-expr)` -#### description: -The `get-block-info?` function fetches data for a block of the given block height. The value and type returned are determined by the specified `BlockInfoPropertyName`. If the provided `BlockHeightInt` does not correspond to an existing block prior to the current block, the function returns `none`. The currently available property names are `time`, `header-hash`, `burnchain-header-hash`, `id-header-hash`, `miner-address`, and `vrf-seed`. - -This is a Unix epoch timestamp in seconds which roughly corresponds to when the block was mined. The `time` property returns an integer value of the block header time field. **Warning**: this does not increase monotonically with each block and block times are accurate only to within two hours. See [BIP113](https://github.com/bitcoin/bips/blob/master/bip-0113.mediawiki) for more information. - -The `header-hash`, `burnchain-header-hash`, `id-header-hash`, and `vrf-seed` properties return a 32-byte buffer. - -The `miner-address` property returns a `principal` corresponding to the miner of the given block. - -The `id-header-hash` is the block identifier value that must be used as input to the `at-block` function. - -#### example: -```clarity -(get-block-info? time u0) ;; Returns (some u1557860301) -(get-block-info? header-hash u0) ;; Returns (some 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb) -(get-block-info? vrf-seed u0) ;; Returns (some 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4) -``` - -### err -#### input: `A` -#### output: `(response A B)` -#### signature: `(err value)` -#### description: -The `err` function constructs a response type from the input value. Use `err` for creating return values in public functions. An _err_ value indicates that any database changes during the processing of the function should be rolled back. -#### example: -```clarity -(err true) ;; Returns (err true) -``` - -### ok -#### input: `A` -#### output: `(response A B)` -#### signature: `(ok value)` -#### description: -The `ok` function constructs a response type from the input value. Use `ok` for creating return values in public functions. An _ok_ value indicates that any database changes during the processing of the function should materialize. -#### example: -```clarity -(ok 1) ;; Returns (ok 1) -``` - -### some -#### input: `A` -#### output: `(optional A)` -#### signature: `(some value)` -#### description: -The `some` function constructs a `optional` type from the input value. -#### example: -```clarity -(some 1) ;; Returns (some 1) -(is-none (some 2)) ;; Returns false -``` - -### default-to -#### input: `A, (optional A)` -#### output: `A` -#### signature: `(default-to default-value option-value)` -#### description: -The `default-to` function attempts to 'unpack' the second argument: if the argument is a `(some ...)` option, it returns the inner value of the option. If the second argument is a `(none)` value, `default-to` it returns the value of `default-value`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(default-to 0 (get id (map-get? names-map (tuple (name \"blockstack\"))))) ;; Returns 1337 -(default-to 0 (get id (map-get? names-map (tuple (name \"non-existant\"))))) ;; Returns 0 -``` - -### asserts! -#### input: `bool, C` -#### output: `bool` -#### signature: `(asserts! bool-expr thrown-value)` -#### description: -The `asserts!` function admits a boolean argument and asserts its evaluation: if bool-expr is `true`, `asserts!` returns `true` and proceeds in the program execution. If the supplied argument is returning a false value, `asserts!` _returns_ `thrown-value` and exits the current control-flow. -#### example: -```clarity -(asserts! (is-eq 1 1) (err 1)) ;; Returns true -``` - -### unwrap! -#### input: `(optional A) | (response A B), C` -#### output: `A` -#### signature: `(unwrap! option-input thrown-value)` -#### description: -The `unwrap!` function attempts to 'unpack' the first argument: if the argument is an option type, and the argument is a `(some ...)` option, `unwrap!` returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, `unwrap!` returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `(none)` value, `unwrap!` _returns_ `thrown-value` from the current function and exits the current control-flow. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(define-private (get-name-or-err (name (string-ascii 12))) - (let ((raw-name (unwrap! (define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(define-private (get-name-or-err (name (string-ascii 12))) - (let ((raw-name (unwrap! names-map { name: name }) (err 1)))) - (ok raw-name))) - -(get-name-or-err \"blockstack\") ;; Returns (ok (tuple (id 1337))) -(get-name-or-err \"non-existant\") ;; Returns (err 1) -``` - -### unwrap-err! -#### input: `(response A B), C` -#### output: `B` -#### signature: `(unwrap-err! response-input thrown-value)` -#### description: -The `unwrap-err!` function attempts to 'unpack' the first argument: if the argument is an `(err ...)` response, `unwrap-err!` returns the inner value of the `err`. If the supplied argument is an `(ok ...)` value, `unwrap-err!` _returns_ `thrown-value` from the current function and exits the current control-flow. -#### example: -```clarity -(unwrap-err! (err 1) false) ;; Returns 1 -``` - -### unwrap-panic -#### input: `(optional A) | (response A B)` -#### output: `A` -#### signature: `(unwrap-panic option-input)` -#### description: -The `unwrap` function attempts to 'unpack' its argument: if the argument is an option type, and the argument is a `(some ...)` option, this function returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, it returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `(none)` value, `unwrap` throws a runtime error, aborting any further processing of the current transaction. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(unwrap-panic (map-get? names-map { name: \"blockstack\" })) ;; Returns (tuple (id 1337)) -(unwrap-panic (map-get? names-map { name: \"non-existant\" })) ;; Throws a runtime exception -``` - -### unwrap-err-panic -#### input: `(response A B)` -#### output: `B` -#### signature: `(unwrap-err-panic response-input)` -#### description: -The `unwrap-err` function attempts to 'unpack' the first argument: if the argument is an `(err ...)` response, `unwrap` returns the inner value of the `err`. If the supplied argument is an `(ok ...)` value, `unwrap-err` throws a runtime error, aborting any further processing of the current transaction. -#### example: -```clarity -(unwrap-err-panic (err 1)) ;; Returns 1 -(unwrap-err-panic (ok 1)) ;; Throws a runtime exception -``` - -### match -#### input: `(optional A) name expression expression | (response A B) name expression name expression` -#### output: `C` -#### signature: `(match opt-input some-binding-name some-branch none-branch) | -(match-resp input ok-binding-name ok-branch err-binding-name err-branch)` -#### description: -The `match` function is used to test and destructure optional and response types. - -If the `input` is an optional, it tests whether the provided `input` is a `some` or `none` option, and evaluates `some-branch` or `none-branch` in each respective case. - -Within the `some-branch`, the _contained value_ of the `input` argument is bound to the provided `some-binding-name` name. - -Only _one_ of the branches will be evaluated (similar to `if` statements). - -If the `input` is a response, it tests whether the provided `input` is an `ok` or `err` response type, and evaluates `ok-branch` or `err-branch` in each respective case. - -Within the `ok-branch`, the _contained ok value_ of the `input` argument is bound to the provided `ok-binding-name` name. - -Within the `err-branch`, the _contained err value_ of the `input` argument is bound to the provided `err-binding-name` name. - -Only _one_ of the branches will be evaluated (similar to `if` statements). - -Note: Type checking requires that the type of both the ok and err parts of the response object be determinable. For situations in which one of the parts of a response is untyped, you should use `unwrap-panic` or `unwrap-err-panic` instead of `match`. -#### example: -```clarity - -(define-private (add-10 (x (optional int))) - (match x - value (+ 10 value) - 10)) -(add-10 (some 5)) ;; Returns 15 -(add-10 none) ;; Returns 10 - -(define-private (add-or-pass-err (x (response int (string-ascii 10))) (to-add int)) - (match x - value (ok (+ to-add value)) - err-value (err err-value))) -(add-or-pass-err (ok 5) 20) ;; Returns (ok 25) -(add-or-pass-err (err \"ERROR\") 20) ;; Returns (err \"ERROR\") -``` - -### try! -#### input: `(optional A) | (response A B)` -#### output: `A` -#### signature: `(try! option-input)` -#### description: -The `try!` function attempts to 'unpack' the first argument: if the argument is an option type, and the argument is a `(some ...)` option, `try!` returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, `try!` returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `none` value, `try!` _returns_ either `none` or the `(err ...)` value from the current function and exits the current control-flow. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(try! (define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(define-private (get-name-or-err (name (string-ascii 12))) - (let ((raw-name (unwrap! names-map { name: \"blockstack\" })) ;; Returns (tuple (id 1337)) -(define-private (checked-even (x int)) - (if (is-eq (mod x 2) 0) - (ok x) - (err false))) -(define-private (double-if-even (x int)) - (ok (* 2 (try! (checked-even x))))) -(double-if-even 10) ;; Returns (ok 20) -(double-if-even 3) ;; Returns (err false) -``` - -### is-ok -#### input: `(response A B)` -#### output: `bool` -#### signature: `(is-ok value)` -#### description: -`is-ok` tests a supplied response value, returning `true` if the response was `ok`, and `false` if it was an `err`. -#### example: -```clarity -(is-ok (ok 1)) ;; Returns true -(is-ok (err 1)) ;; Returns false -``` - -### is-none -#### input: `(optional A)` -#### output: `bool` -#### signature: `(is-none value)` -#### description: -`is-none` tests a supplied option value, returning `true` if the option value is `(none)`, and `false` if it is a `(some ...)`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(is-none (get id (map-get? names-map { name: \"blockstack\" }))) ;; Returns false -(is-none (get id (map-get? names-map { name: \"non-existant\" }))) ;; Returns true -``` - -### is-err -#### input: `(response A B)` -#### output: `bool` -#### signature: `(is-err value)` -#### description: -`is-err` tests a supplied response value, returning `true` if the response was an `err`, and `false` if it was an `ok`. -#### example: -```clarity -(is-err (ok 1)) ;; Returns false -(is-err (err 1)) ;; Returns true -``` - -### is-some -#### input: `(optional A)` -#### output: `bool` -#### signature: `(is-some value)` -#### description: -`is-some` tests a supplied option value, returning `true` if the option value is `(some ...)`, and `false` if it is a `none`. -#### example: -```clarity - -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(is-some (get id (map-get? names-map { name: \"blockstack\" }))) ;; Returns true -(is-some (get id (map-get? names-map { name: \"non-existant\" }))) ;; Returns false -``` - -### filter -#### input: `Function(A) -> bool, sequence_A` -#### output: `sequence_A` -#### signature: `(filter func sequence)` -#### description: -The `filter` function applies the input function `func` to each element of the input sequence, and returns the same sequence with any elements removed for which `func` returned `false`. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. ` -#### example: -```clarity - -(filter not (list true false true false)) ;; Returns (false false) -(define-private (is-a (char (string-utf8 1))) (is-eq char u\"a\")) -(filter is-a u\"acabd\") ;; Returns u\"aa\" -(define-private (is-zero (char (buff 1))) (is-eq char 0x00)) -(filter is-zero 0x00010002) ;; Returns 0x0000 -``` - -### ft-get-balance -#### input: `TokenName, principal` -#### output: `uint` -#### signature: `(ft-get-balance token-name principal)` -#### description: -`ft-get-balance` returns `token-name` balance of the principal `principal`. The token type must have been defined using `define-fungible-token`. -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-get-balance stackaroo 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns u100 -``` - -### nft-get-owner? -#### input: `AssetName, A` -#### output: `(optional principal)` -#### signature: `(nft-get-owner? asset-class asset-identifier)` -#### description: -`nft-get-owner?` returns the owner of an asset, identified by `asset-identifier`, or `none` if the asset does not exist. The asset type must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) -(nft-get-owner? stackaroo \"Roo\") ;; Returns (some SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) -(nft-get-owner? stackaroo \"Too\") ;; Returns none -``` - -### ft-transfer? -#### input: `TokenName, uint, principal, principal` -#### output: `(response bool uint)` -#### signature: `(ft-transfer? token-name amount sender recipient)` -#### description: -`ft-transfer?` is used to increase the token balance for the `recipient` principal for a token type defined using `define-fungible-token` by debiting the `sender` principal. In contrast to `stx-transfer?`, any user can transfer the assets. When used, relevant guards need to be added. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- amount to send is non-positive ` -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-transfer? stackaroo u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(ft-transfer? stackaroo u60 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u1) -``` - -### nft-transfer? -#### input: `AssetName, A, principal, principal` -#### output: `(response bool uint)` -#### signature: `(nft-transfer? asset-class asset-identifier sender recipient)` -#### description: -`nft-transfer?` is used to change the owner of an asset identified by `asset-identifier` from `sender` to `recipient`. The `asset-class` must have been defined by `define-non-fungible-token` and `asset-identifier` must be of the type specified in that definition. In contrast to `stx-transfer?`, any user can transfer the asset. When used, relevant guards need to be added. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not own the asset `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- asset identified by asset-identifier does not exist ` -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(nft-transfer? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(nft-transfer? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u1) -(nft-transfer? stackaroo \"Stacka\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u3) -``` - -### nft-mint? -#### input: `AssetName, A, principal` -#### output: `(response bool uint)` -#### signature: `(nft-mint? asset-class asset-identifier recipient)` -#### description: -`nft-mint?` is used to instantiate an asset and set that asset's owner to the `recipient` principal. The asset must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. - -If an asset identified by `asset-identifier` _already exists_, this function will return an error with the following error code: - -`(err u1)` - -Otherwise, on successfuly mint, it returns `(ok true)`. ` -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### ft-mint? -#### input: `TokenName, uint, principal` -#### output: `(response bool uint)` -#### signature: `(ft-mint? token-name amount recipient)` -#### description: -`ft-mint?` is used to increase the token balance for the `recipient` principal for a token type defined using `define-fungible-token`. The increased token balance is _not_ transfered from another principal, but rather minted. - -If a non-positive amount is provided to mint, this function returns `(err 1)`. Otherwise, on successfuly mint, it returns `(ok true)`. ` -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### ft-get-supply -#### input: `TokenName` -#### output: `uint` -#### signature: `(ft-get-supply token-name)` -#### description: -`ft-get-balance` returns `token-name` circulating supply. The token type must have been defined using `define-fungible-token`. -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-get-supply stackaroo) ;; Returns u100 -``` - -### ft-burn? -#### input: `TokenName, uint, principal` -#### output: `(response bool uint)` -#### signature: `(ft-burn? token-name amount sender)` -#### description: -`ft-burn?` is used to decrease the token balance for the `sender` principal for a token type defined using `define-fungible-token`. The decreased token balance is _not_ transfered to another principal, but rather destroyed, reducing the circulating supply. - -If a non-positive amount is provided to burn, this function returns `(err 1)`. Otherwise, on successfuly burn, it returns `(ok true)`. - -#### example: -```clarity - -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(ft-burn? stackaroo u50 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### nft-burn? -#### input: `AssetName, A, principal` -#### output: `(response bool uint)` -#### signature: `(nft-burn? asset-class asset-identifier recipient)` -#### description: -`nft-burn?` is used to burn an asset and remove that asset's owner from the `recipient` principal. The asset must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. - -If an asset identified by `asset-identifier` _doesn't exist_, this function will return an error with the following error code: - -`(err u1)` - -Otherwise, on successfuly burn, it returns `(ok true)`. ` -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(nft-burn? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### stx-get-balance -#### input: `principal` -#### output: `uint` -#### signature: `(stx-get-balance owner)` -#### description: -`stx-get-balance` is used to query the STX balance of the `owner` principal. - -This function returns the STX balance of the `owner` principal. In the event that the `owner` principal isn't materialized, it returns 0. - -#### example: -```clarity -(stx-get-balance 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns u0 -(stx-get-balance (as-contract tx-sender)) ;; Returns u1000 -``` - -### stx-transfer? -#### input: `uint, principal, principal` -#### output: `(response bool uint)` -#### signature: `(stx-transfer? amount sender recipient)` -#### description: -`stx-transfer?` is used to increase the STX balance for the `recipient` principal by debiting the `sender` principal. The `sender` principal _must_ be equal to the current context's `tx-sender`. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- amount to send is non-positive `(err u4)` -- the `sender` principal is not the current `tx-sender` - -#### example: -```clarity - -(as-contract - (stx-transfer? u60 tx-sender 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (ok true) -(as-contract - (stx-transfer? u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR tx-sender)) ;; Returns (err u4) -``` - -### stx-burn? -#### input: `uint, principal` -#### output: `(response bool uint)` -#### signature: `(stx-burn? amount sender)` -#### description: -`stx-burn?` debits the `sender` principal's STX holdings by `amount`, destroying the STX. The `sender` principal _must_ be equal to the current context's `tx-sender`. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u3)` -- amount to send is non-positive `(err u4)` -- the `sender` principal is not the current `tx-sender` - -#### example: -```clarity -(as-contract - (stx-burn? u60 tx-sender)) ;; Returns (ok true) -(as-contract - (stx-burn? u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (err u4) -``` - -### define-constant -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-constant name expression)` -#### description: -`define-constant` is used to define a private constant value in a smart contract. The expression passed into the definition is evaluated at contract launch, in the order that it is supplied in the contract. This can lead to undefined function or undefined variable errors in the event that a function or variable used in the expression has not been defined before the constant. - -Like other kinds of definition statements, `define-constant` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -#### example: -```clarity - -(define-constant four (+ 2 2)) -(+ 4 four) ;; Returns 8 -``` - -### define-private -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-private (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### description: -`define-private` is used to define _private_ functions for a smart contract. Private functions may not be called from other smart contracts, nor may they be invoked directly by users. Instead, these functions may only be invoked by other functions defined in the same smart contract. - -Like other kinds of definition statements, `define-private` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Private functions may return any type. -#### example: -```clarity -(define-private (max-of (i1 int) (i2 int)) - (if (> i1 i2) - i1 - i2)) -(max-of 4 6) ;; Returns 6 -``` - -### define-public -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-public (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### description: -`define-public` is used to define a _public_ function and transaction for a smart contract. Public functions are callable from other smart contracts and may be invoked directly by users by submitting a transaction to the Stacks blockchain. - -Like other kinds of definition statements, `define-public` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Public functions _must_ return a ResponseType (using either `ok` or `err`). Any datamap modifications performed by a public function is aborted if the function returns an `err` type. Public functions may be invoked by other contracts via `contract-call?`. -#### example: -```clarity -(define-public (hello-world (input int)) - (begin (print (+ 2 input)) - (ok input))) -``` - -### define-read-only -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-read-only (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### description: -`define-read-only` is used to define a _public read-only_ function for a smart contract. Such functions are callable from other smart contracts. - -Like other kinds of definition statements, `define-read-only` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Read-only functions may return any type. However, read-only functions may not perform any datamap modifications, or call any functions which perform such modifications. This is enforced both during type checks and during the execution of the function. Public read-only functions may be invoked by other contracts via `contract-call?`. -#### example: -```clarity -(define-read-only (just-return-one-hundred) - (* 10 10)) - ``` - -### define-map -#### input: `MapName, TypeDefinition, TypeDefinition` -#### output: `Not Applicable` -#### signature: `(define-map map-name key-type value-type)` -#### description: -`define-map` is used to define a new datamap for use in a smart contract. Such maps are only modifiable by the current smart contract. - -Maps are defined with a key type and value type, often these types are tuple types. - -Like other kinds of definition statements, `define-map` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). -#### example: -```clarity -(define-map squares { x: int } { square: int }) -(define-private (add-entry (x int)) - (map-insert squares { x: 2 } { square: (* x x) })) -(add-entry 1) -(add-entry 2) -(add-entry 3) -(add-entry 4) -(add-entry 5) -``` - -### define-data-var -#### input: `VarName, TypeDefinition, Value` -#### output: `Not Applicable` -#### signature: `(define-data-var var-name type value)` -#### description: -`define-data-var` is used to define a new persisted variable for use in a smart contract. Such variable are only modifiable by the current smart contract. - -Persisted variable are defined with a type and a value. - -Like other kinds of definition statements, `define-data-var` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). -#### example: -```clarity -(define-data-var size int 0) -(define-private (set-size (value int)) - (var-set size value)) -(set-size 1) -(set-size 2) -``` - -### define-fungible-token -#### input: `TokenName, ` -#### output: `Not Applicable` -#### signature: `(define-fungible-token token-name )` -#### description: -`define-fungible-token` is used to define a new fungible token class for use in the current contract. - -The second argument, if supplied, defines the total supply of the fungible token. This ensures that all calls to the `ft-mint?` function will never be able to create more than `total-supply` tokens. If any such call were to increase the total supply of tokens passed that amount, that invocation of `ft-mint?` will result in a runtime error and abort. - -Like other kinds of definition statements, `define-fungible-token` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Tokens defined using `define-fungible-token` may be used in `ft-transfer?`, `ft-mint?`, and `ft-get-balance` functions` -#### example: -```clarity -(define-fungible-token stacks) -(define-fungible-token limited-supply-stacks u100) -``` - -### define-non-fungible-token -#### input: `AssetName, TypeSignature` -#### output: `Not Applicable` -#### signature: `(define-non-fungible-token asset-name asset-identifier-type)` -#### description: -`define-non-fungible-token` is used to define a new non-fungible token class for use in the current contract. Individual assets are identified by their asset identifier, which must be of the type `asset-identifier-type`. Asset identifiers are _unique_ identifiers. - -Like other kinds of definition statements, `define-non-fungible-token` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Assets defined using `define-non-fungible-token` may be used in `nft-transfer?`, `nft-mint?`, and `nft-get-owner?` functions` -#### example: -```clarity -(define-non-fungible-token names (buff 50)) -``` - -### define-trait -#### input: `VarName, [MethodSignature]` -#### output: `Not Applicable` -#### signature: `(define-trait trait-name ((func1-name (arg1-type arg2-type ...) (return-type))))` -#### description: -`define-trait` is used to define a new trait definition for use in a smart contract. Other contracts can implement a given trait and then have their contract identifier being passed as function arguments in order to be called dynamically with `contract-call?`. - -Traits are defined with a name, and a list functions defined with a name, a list of argument types, and return type. - -Like other kinds of definition statements, `define-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -#### example: -```clarity -(define-trait token-trait - ((transfer? (principal principal uint) (response uint uint)) - (get-balance (principal) (response uint uint)))) -``` - -### use-trait -#### input: `VarName, TraitIdentifier` -#### output: `Not Applicable` -#### signature: `(use-trait trait-alias trait-identifier)` -#### description: -`use-trait` is used to bring a trait, defined in another contract, to the current contract. Subsequent references to an imported trait are signaled with the syntax ``. - -Traits import are defined with a name, used as an alias, and a trait identifier. Trait identifiers can either be using the sugared syntax (.token-a.token-trait), or be fully qualified ('SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait). - -Like other kinds of definition statements, `use-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put such a statement in the middle of a function body). -#### example: -```clarity -(use-trait token-a-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) -(define-public (forward-get-balance (user principal) (contract )) - (begin - (ok 1))) -``` - -### impl-trait -#### input: `TraitIdentifier` -#### output: `Not Applicable` -#### signature: `(impl-trait trait-identifier)` -#### description: -`impl-trait` can be use for asserting that a contract is fully implementing a given trait. Additional checks are being performed when the contract is being published, rejecting the deployment if the contract is violating the trait specification. - -Trait identifiers can either be using the sugared syntax (.token-a.token-trait), or be fully qualified ('SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait). - -Like other kinds of definition statements, `impl-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put such a statement in the middle of a function body). - -#### example: -```clarity -(impl-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) (define-public (get-balance (account principal)) (ok u0)) (define-public (transfer? (from principal) (to principal) (amount uint)) - (ok u0)) -``` \ No newline at end of file diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md b/i18n/tr/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md deleted file mode 100644 index fd62451198..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Keywords -description: See a detailed list of all keywords for the Clarity language. -tags: - - clarity ---- - -![](/img/keywords.jpg) -## Keyword reference - -Detailed list of all keywords for the Clarity language. - - -### contract-caller -#### output: `principal` -#### description: -Returns the caller of the current contract context. If this contract is the first one called by a signed transaction, the caller will be equal to the signing principal. If `contract-call?` was used to invoke a function from a new contract, `contract-caller` changes to the _calling_ contract's principal. If `as-contract` is used to change the `tx-sender` context, `contract-caller` _also_ changes to the same contract principal. -#### example: -```clarity -(print contract-caller) ;; Will print out a Stacks address of the transaction sender -``` - -### tx-sender -#### output: `principal` -#### description: -Returns the original sender of the current transaction, or if `as-contract` was called to modify the sending context, it returns that contract principal. -#### example: -```clarity -(print tx-sender) ;; Will print out a Stacks address of the transaction sender -``` - -### block-height -#### output: `uint` -#### description: -Returns the current block height of the Stacks blockchain as an uint -#### example: -```clarity -(> block-height 1000) ;; returns true if the current block-height has passed 1000 blocks. -``` - -### burn-block-height -#### output: `uint` -#### description: -Returns the current block height of the underlying burn blockchain as a uint -#### example: -```clarity -(> burn-block-height 1000) ;; returns true if the current height of the underlying burn blockchain has passed 1000 blocks. -``` - -### none -#### output: `(optional ?)` -#### description: -Represents the _none_ option indicating no value for a given optional (analogous to a null value). -#### example: -```clarity -(define-public (only-if-positive (a int)) - (if (> a 0) - (some a) - none)) -(only-if-positive 4) ;; Returns (some 4) -(only-if-positive (- 3)) ;; Returns none -``` - -### true -#### output: `bool` -#### description: -Boolean true constant. -#### example: -```clarity -(and true false) ;; Evaluates to false -(or false true) ;; Evaluates to true -``` - -### false -#### output: `bool` -#### description: -Boolean false constant. -#### example: -```clarity -(and true false) ;; Evaluates to false -(or false true) ;; Evaluates to true -``` - -### stx-liquid-supply -#### output: `uint` -#### description: -Returns the total number of micro-STX (uSTX) that are liquid in the system as of this block. -#### example: -```clarity -(print stx-liquid-supply) ;; Will print out the total number of liquid uSTX -``` - -### is-in-regtest -#### output: `bool` -#### description: -Returns whether or not the code is running in a regression test -#### example: -```clarity -(print is-in-regtest) ;; Will print 'true' if the code is running in a regression test -``` - diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md b/i18n/tr/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md deleted file mode 100644 index d22f991413..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Types -description: See a detailed list of all types for the Clarity language. -tags: - - clarity ---- - -## Clarity Type System - -The type system contains the following types: - -| Types | Notes | -| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `int` | signed 128-bit integer | -| `uint` | unsigned 128-bit integer | -| `bool` | boolean value (`true` or `false`) | -| `principal` | object representing a principal (whether a contract principal or standard principal) | -| `(buff max-len)` | byte buffer of 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` (u"A smiley face emoji \u{1F600} as a utf8 string") | -| `(list max-len entry-type)` | list of maximum length `max-len`, with entries of type `entry-type` | -| `{label-0: value-type-0, label-1: value-type-1, ...}` | tuple, group of data values with named fields | -| `(optional some-type)` | an option type for objects that can either be `(some value)` or `none` | -| `(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. | diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md b/i18n/tr/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md deleted file mode 100644 index e75e1d69b9..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Clarity overview -description: Overview and guides for getting started with Clarity -sidebar_label: Write smart contracts -sidebar_position: 2 ---- - -## Introduction - -Clarity is a **decidable** smart contract language that optimizes for predictability and security, designed for the Stacks blockchain. Smart contracts allow developers to encode essential business logic on a blockchain. - -## Smart contracts - -Smart contracts encode and enforce rules for modifying a particular set of data that is shared among people and entities who don't necessarily trust each other. For example, a smart contract can hold funds in escrow until multiple parties agree to release them, create its own ledger and keep track of its own novel tokens (fungible or non-fungible), and even help make supply chains more transparent. - -A smart contract execution can result in new transactions being written to the blockchain. Because smart contracts are programs that exist in a blockchain, anyone can query them, and anyone can submit transactions to execute them. - -Apps can take advantage of smart contracts to manage a global state that is visible to the public. Anyone can audit the blockchain to independently verify that an app's global shared state has been managed correctly according to the smart contract's rules. - -There is a [Clarity Visual Studio Code plugin][] available for syntax assistance and debugging. - -## Use cases - -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 (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 - -## Language design - -Clarity differs from most other smart contract languages in two essential ways: - -- The language is interpreted and broadcast on the blockchain as is (not compiled) -- The language is decidable (not Turing complete) - -Using an interpreted language ensures that the executed code is human-readable and auditable. A decidable language like Clarity makes it possible to determine precisely which code is executed, for any function. - -A Clarity smart contract consists of two parts, a data space and a set of functions. Only the associated smart contract may modify its corresponding data space on the blockchain. Functions may be private and thus callable only from within the smart contract, or public and thus callable from other contracts. Users call smart contracts' public functions by broadcasting a transaction on the blockchain which invokes the public function. Contracts can also call public functions from other smart contracts. - -Note some of the key Clarity language rules and limitations. - -- The only primitive types are booleans, integers, buffers, and principals. -- Recursion is illegal and there are no anonymous functions. -- Looping is only performed via `map`, `filter`, or `fold`. -- There is support for lists, however, the only variable length lists in the language appear as function inputs; there is no support for list operations like append or join. -- Variables are immutable. - -## Explore more - -For language details and references, see the following: - -- [Clarity language overview](./clarity-language/) -- [Understating Principals](principals) -- [Clarity Values](values) - -[Clarity Visual Studio Code plugin]: https://marketplace.visualstudio.com/items?itemName=HiroSystems.clarity-lsp diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md b/i18n/tr/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md deleted file mode 100644 index 912ea694a6..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md +++ /dev/null @@ -1,232 +0,0 @@ ---- -title: Principals -description: 'Clarity: Understanding Principals' -sidebar_position: 1 ---- - -## Introduction - -_Principals_ are a Clarity native type that represents an entity that can have a token balance. This section discusses principals and how they are used in the Clarity. - -## Principals and tx-sender - -Assets in the smart contracting language and blockchain are "owned" by objects of the principal type, meaning that any object of the principal type may own an asset. For the case of public-key hash and multi-signature Stacks addresses, a given principal can operate on their assets by issuing a signed transaction on the blockchain. _Smart contracts_ may also be principals (represented by the smart contract's identifier), however, there is no private key associated with the smart contract, and it cannot broadcast a signed transaction on the blockchain. - -A Clarity contract can use a globally defined `tx-sender` variable to obtain the current principal. The following example defines a transaction type that transfers `amount` microSTX from the sender to a recipient if amount is a multiple of 10, otherwise returning a 400 error code. - -```clarity -(define-public (transfer-to-recipient! (recipient principal) (amount uint)) - (if (is-eq (mod amount 10) 0) - (stx-transfer? amount tx-sender recipient) - (err u400))) -``` - -Clarity provides an additional variable to help smart contracts authenticate a transaction sender. The keyword `contract-caller` returns the principal that _called_ the current contract. If an inter-contract call occurred, `contract-caller` returns the last contract in the stack of callers. For example, suppose there are three contracts A, B, and C, each with an `invoke` function such that `A::invoke` calls `B::invoke` and `B::invoke` calls `C::invoke`. - -When a user Bob issues a transaction that calls `A::invoke`, the value of `contract-caller` in each successive invoke function's body would change: - -```clarity -in A::invoke, contract-caller = Bob -in B::invoke, contract-caller = A -in C::invoke, contract-caller = B -``` - -This allows contracts to make assertions and perform authorization checks using not only the `tx-sender` (which in this example, would always be "Bob"), but also using the `contract-caller`. This could be used to ensure that a particular function is only ever called directly and never called via an inter-contract call (by asserting that `tx-sender` and `contract-caller` are equal). We provide an example of a two different types of authorization checks in the rocket ship example below. - -## Smart contracts as principals - -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, for example: - -```clarity -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-name -``` - -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 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 qualified identifier for the contracts would be: - -```clarity -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-A -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-B -``` - -But, in the contract source code, if the developer wishes to call a function from `contract-A` in `contract-B`, they can write - -```clarity -(contract-call? .contract-A public-function-foo) -``` - -This allows the smart contract developer to modularize their applications across multiple smart contracts _without_ knowing the publishing key a priori. - -In order for a smart contract to operate on assets it owns, smart contracts may use the special `(as-contract ...)` function. This function executes the expression (passed as an argument) with the `tx-sender` set to the contract's principal, rather than the current sender. The `as-contract` function returns the value of the provided expression. - -For example, a smart contract that implements something like a "token faucet" could be implemented as so: - -```clarity -(define-map claimed-before - ((sender principal)) - ((claimed bool))) - -(define-constant err-already-claimed u1) -(define-constant err-faucet-empty u2) -(define-constant stx-amount u1) - -(define-public (claim-from-faucet) - (let ((requester tx-sender)) ;; set a local variable requester = tx-sender - (asserts! (is-none (map-get? claimed-before {sender: requester})) (err err-already-claimed)) - (unwrap! (as-contract (stx-transfer? stx-amount tx-sender requester)) (err err-faucet-empty)) - (map-set claimed-before {sender: requester} {claimed: true}) - (ok stx-amount))) -``` - -In this example, the public function `claim-from-faucet`: - -- Checks if the sender has claimed from the faucet before. -- Assigns the tx sender to a `requester` variable. -- Adds an entry to the tracking map. -- Uses `as-contract` to send 1 microstack - -Unlike other principals, there is no private key associated with a smart contract. As it lacks a private key, a Clarity smart contract cannot broadcast a signed transaction on the blockchain. - -## Example: Authorization checks - -The interactions between `tx-sender`, `contract-caller` and `as-contract` are subtle, but are important when performing authorization checks in a contract. In this example contract, we'll show two different kinds of authorization checks a contract may wish to perform, and then walk through how different ways in which contract functions may be called will pass or fail those checks. - -This contract defines a "rocket-ship" non-fungible-token that a principal may own and manage the authorized pilots. Pilots are principals that are allowed to "fly" the rocket ship. - -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. -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 be called _directly_ by the ship's owner, rather than through a inter-contract-call. - -The second type of check is more restrictive than the first check, and is helpful for guarding very sensitive routines --- it protects users from unknowingly calling a function on a malicious contract that subsequently tries to call sensitive functions on another contract. - -```clarity -;; -;; rockets-base.clar -;; - -(define-non-fungible-token rocket-ship uint) - -;; a map from rocket ships to their allowed -;; pilots -(define-map allowed-pilots - ((rocket-ship uint)) ((pilots (list 10 principal)))) - -;; implementing a contains function via fold -(define-private (contains-check - (y principal) - (to-check { p: principal, result: bool })) - (if (get result to-check) - to-check - { p: (get p to-check), - result: (is-eq (get p to-check) y) })) - -(define-private (contains (x principal) (find-in (list 10 principal))) - (get result (fold contains-check find-in - { p: x, result: false }))) - -(define-read-only (is-my-ship (ship uint)) - (is-eq (some tx-sender) (nft-get-owner? rocket-ship ship))) - -;; this function will print a message -;; (and emit an event) if the tx-sender was -;; an authorized flyer. -;; -;; here we use tx-sender, because we want -;; to allow the user to let other contracts -;; fly the ship on behalf of users - -(define-public (fly-ship (ship uint)) - (let ((pilots (default-to - (list) - (get pilots (map-get? allowed-pilots { rocket-ship: ship }))))) - (if (contains tx-sender pilots) - (begin (print "Flew the rocket-ship!") - (ok true)) - (begin (print "Tried to fly without permission!") - (ok false))))) -;; -;; Authorize a new pilot. -;; -;; here we want to ensure that this function -;; was called _directly_ by the user by -;; checking that tx-sender and contract-caller are equal. -;; if any other contract is in the call stack, contract-caller -;; would be updated to a different principal. -;; -(define-public (authorize-pilot (ship uint) (pilot principal)) - (begin - ;; sender must equal caller: an intermediate contract is - ;; not issuing this call. - (asserts! (asserts! (is-eq tx-sender contract-caller) (err u1)) - ;; sender must own the rocket ship - (asserts! (is-eq (some tx-sender) - (nft-get-owner? rocket-ship ship)) (err u2)) - (let ((prev-pilots (default-to - (list) - (get pilots (map-get? allowed-pilots { rocket-ship: ship }))))) - ;; don't add a pilot already in the list - (asserts! (not (contains pilot prev-pilots)) (err u3)) - ;; append to the list, and check that it is less than - ;; the allowed maximum - (match (as-max-len? -``` - -### Extending functionality: Multi-flyer contract - -The authorization scheme for `fly-ship` allows pilots to fly rocket-ships from other contracts. This allows other contracts to provide new functionality built around calling that function. - -For example, we can create a contract that calls `fly-ship` for multiple rocket-ships in a single transaction: - -```clarity -;; -;; rockets-multi.clar -;; - -(define-private (call-fly (ship uint)) - (unwrap! (contract-call? .rockets-base fly-ship ship) false)) -;; try to fly all the ships, returning a list of whether -;; or not we were able to fly the supplied ships -(define-public (fly-all (ships (list 10 uint))) - (ok (map call-fly ships))) -``` - -### Authorization for Contract-Owned Assets - -The check in `authorize-pilot` protects users from malicious contracts, but how would such a scheme support contract-owned assets? This is what the `as-contract` function is used for. The `as-contract` function executes the supplied closure as if the sender of the transaction was the current contract, rather than the user -- it does this by updating `tx-sender` to the current contract principal. We can use this to, for example, create a smart contract rocket-ship-line: - -```clarity -;; -;; rockets-ship-line.clar -;; - -(define-constant line-ceo 'SP19Y6GRV9X778VFS1V8WT2H502WFK33XZXADJWZ) - -(define-data-var employed-pilots (list 10 principal) (list)) - -;; This function will: -;; * check that it is called by the line-ceo -;; * check that the rocket is owned by the contract -;; * authorize each employed pilot to the ship -(define-public (add-managed-rocket (ship uint)) - (begin - ;; 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 - (asserts! (contract-call? .rockets-base is-my-ship ship) (err u2)) - ;; register all of our pilots on the ship - (add-pilots-to ship))))) - -;; add all the pilots to a ship using fold -- -;; the fold checks the return type of previous calls, -;; skipping subsequent contract-calls if one fails. -(define-private (add-pilot-via-fold (pilot principal) (prior-result (response uint uint))) - (let ((ship (try! prior-result))) - (try! (contract-call? .rockets-base authorize-pilot ship pilot)) - (ok ship))) -(define-private (add-pilots-to (ship uint)) - (fold add-pilot-via-fold (var-get employed-pilots) (ok ship))) -``` - -In order for the contract to add each pilot to a new ship, the contract must call `authorize-pilot`. However, the contract wants to perform this action on behalf of a ship the _contract_ owns, not the transaction sender. To do this, the contract uses `as-contract`. diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md b/i18n/tr/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md deleted file mode 100644 index a01e37bc04..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Resources -description: 'Resources' -sidebar_position: 8 ---- - -# External resources - - -[Clarity book](https://book.clarity-lang.org/) - -[Clarity Universe](https://stacks.org/clarity-universe) - -[Hiro Clarity tutorials](https://docs.hiro.so/tutorials) diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md b/i18n/tr/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md deleted file mode 100644 index ed65829518..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Clarity development software -description: The following tools are useful when developing Clarity smart contracts -sidebar_position: 4 ---- - -## Language Server Protocol for Clarity (including Visual Studio Code extension) - -The Language Server Protocol (LSP) defines the protocol used between an editor or IDE and a language server that provides language features like auto complete, go to definition, find all references etc. - -This makes programming in Clarity easier and much more intuitive. - -![Clarity LSP Screenshot](https://raw.githubusercontent.com/hirosystems/clarity-lsp/21b64298ca117dc41358eb9dce4605cc4a448a4c/images/screenshot.png?raw=true) - - -Clarity LSP repository is available [here](https://github.com/hirosystems/clarity-lsp). The extension for Visual Studio Code can be downloaded directly from [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=HiroSystems.clarity-lsp), but can be and older version. For a more up to date version you can also download it from [open-vsx](https://open-vsx.org/extension/hirosystems/clarity-lsp). - -## Clarity REPL - -A read—eval—print loop (REPL), also termed an interactive toplevel or language shell, is a simple, interactive computer programming environment that takes single user inputs (that is, single expressions), evaluates (executes) them, and returns the result to the user; a program written in a REPL environment is executed piecewise. - -![Clarity-repl](https://github.com/hirosystems/clarity-repl/blob/develop/docs/images/screenshot.png?raw=true) - -Instructions on how to install Clarity REPL can be found [here](https://github.com/hirosystems/clarity-repl). - -## Clarinet - -Clarinet is a Clarity runtime packaged as a command line tool, designed to facilitate smart contract understanding, development, testing and deployment. Clarinet consists of a Clarity REPL and a testing harness, which, when used together allow you to rapidly develop and test a Clarity smart contract, with the need to deploy the contract to a local devnet or testnet. - -![Clarinet](https://github.com/hirosystems/clarinet/blob/develop/docs/images/demo.gif?raw=true) - -Installation instructions, including build from source instructions can be found [here](https://github.com/hirosystems/clarinet). If you prefer you can directly download the latest compiled realease for Windows, Mac and Linux [here](https://github.com/hirosystems/clarinet/releases). - -[Clarinet 101](https://www.youtube.com/playlist?list=PL5Ujm489LoJaAz9kUJm8lYUWdGJ2AnQTb) contains multiple Clarinet video tutorials - -### Getting started with Clarinet - -You can verify you have Clarinet installed by checking its version: - -```bash -$ clarinet --version -clarinet 0.70 -``` - -More detailed information on using Clarinet is available [here](https://book.clarity-lang.org/ch07-00-using-clarinet.html). However to get you started, the following commands are important to know. - -Create a new project and enter its directory: - -```bash -clarinet new my-project && cd my-project -``` - -Create a new contract inside `my-project`: - -```bash -clarinet contract new mycoolcontract -``` - -Check the syntax of Clarity: - -```bash -clarity check -``` - -To test your contract: - -```bash -clarinet test -``` - -Enter Clarinet's console: - -```bash -clarinet console -``` diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md b/i18n/tr/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md deleted file mode 100644 index 2754709092..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Tokens -description: Learn about token support within Clarity -sidebar_position: 3 ---- - -## Introduction - -A fundamental use of blockchain technology is the representation, store, and transfer of value between users of a blockchain. Cryptocurrency is a very common use of blockchain technology, and remains one of the primary drivers of adoption of blockchain technology. Cryptocurrencies are represented by blockchain tokens: individual units of value within a given blockchain ecosystem. Blockchain tokens can extend beyond just digital currency, however, and recent developments throughout the cryptocurrency community have demonstrated potential for the use of blockchain to tokenize and represent not just money but other tangible assets. - -A blockchain token is a digital asset that can be verifiably owned by a user of a blockchain. Blockchain tokens are governed by a set of rules that are defined by either the blockchain itself (in the case of native tokens) or by a smart contract on a blockchain. Rules can vary depending on the nature and the use of the token. - -Tokens on a blockchain fall into two general categories, depending on their properties: [fungible][] or [non-fungible][]. The following sections discuss the properties of both types of tokens, and provide information about implementation of the two types of tokens on Stacks. - -## Fungible tokens - -A core property of any token on a blockchain is fungibility. A fungible token is a token that's mutually interchangable or capable of mutual substitution. In other words, one quantity or part of a fungible token can be replaced by an equal quantity or part of the same fungible token. Fungible tokens are often used to represent real-world fungible assets like currency. The STX token is an example of a fungible token. Other examples include stablecoins, tokens that represent voting rights in a DAO, or tokens that algorithmically track the price of stocks. - -Fungible tokens form one of the most important value propositions for blockchain technology, the ability to store value and exchange that value through both internal and external transactions. Because fungible tokens can be divided into smaller parts and recombined into the same value representation, they serve a great utility for transferring value between blockchain users. - -The primary fungible token on the Stacks blockchain is the native token, STX. Because the Stacks blockchain allows for the creation of \[smart contracts\]\[\], other fungible tokens can be created on the Stacks blockchain as well. [SIP-010][] specifies the standard for fungible tokens on the Stacks blockchain. This specification defines the functions and traits that a fungible token on Stacks _must_ have. This specification defines the functions and traits that a fungible token on Stacks _must_ have. - -### Understanding the fungible token standard - -The [SIP-010][] standard is an interface definition that allows Stacks applications and wallets to interact with fungible tokens in a standard way. Supporting the standard reduces complexity for token creators to get their tokens into the ecosystem. Under the [SIP-010][] standard, fungible tokens must have the following characteristics: - -- Ability to transfer a specified amount of the token to a recipient (`transfer`). The recipient is required to be a Stacks principal. -- Ability to obtain the human-readable name of the token (`get-name`). -- Ability to obtain a short name (ticker symbol) for the token (`get-symbol`). -- Ability to get the number of decimals in the token representation (`get-decimals`). This is used to construct a representation of the token that humans would be familiar dealing with. For example, the US dollar has 2 decimals, if the base unit is cents. -- Ability to get the balance of the token for a particular Stacks principal (`get-balance-of`). -- Ability to get the total supply of the token (`get-total-supply`). -- A URI to metadata associated with the token (`get-token-uri`). This can resolve to off-chain metadata about the token or contract, such as an image icon for the token or a description. - -## Non-fungible tokens (NFTs) - -Non-fungible tokens (NFTs) are a type of token that are not interchangeable. NFTs have unique traits (usually in the form of attached metadata) that restrict the abillity to replace them with identical tokens. An NFT is a token that is unique, such as a piece of art, or ownership rights to a real-world asset such as a house. - -NFTs alone don't have an inherent value, like a currency. The value of an NFT is derived from the assets that the NFT represents. The use of NFTs are myriad, including digital art, collectibles, domain names, and representation of ownership of content rights. NFTs can be used as digital certificates that track the authenticty of real world items, or digitize the ownership rights to property. - -As with fungible tokens, NFTs on the Stacks blockchain are created with smart contracts. [SIP-009][] specifies the standard for NFTs on the Stacks blockchain. This specification defines the functions and traits that an NFT _must_ have, but most NFTs have more functions or traits attached than those solely described by the specification. By complying with this standard, non-fungible tokens on Stacks can be easily represented by wallets that support Stacks. - -### Understanding the non-fungible token standard - -The [SIP-009][] standard is an interface definition that the Stacks ecosystem aligned on. With support for this standard across wallets and tools, it becomes easy to interact with NFTs. Under the [SIP-009][] standard, NFT contract must have the following characteristics: - -- Ability to obtain the last token identifier (`get-last-token-id`). This id represents the upper limit of NFTs issued by the contract. -- A URI to metadata associated with a specific token identifier. (`get-token-uri`). This URI could resolve to a JSON file with information about the creator, associated media files, descriptions, signatures, and more. -- Ability to verify the owner for a given token identifier (`get-owner`). The owner resolves to a [Stacks principal](principals). -- Ability to transfer an NFT to a recipient (`transfer`). The recipient is required to be a Stacks principal. - -## Further reading - -- [The Difference Between Fungible and Non-Fungible Tokens](https://101blockchains.com/fungible-vs-non-fungible-tokens/) -- [Explain It Like I Am 5: NFTs](https://messari.io/article/explain-it-like-i-am-5-nfts) - -[fungible]: #fungible-tokens -[non-fungible]: #non-fungible-tokens-nfts -[SIP-010]: https://github.com/hstove/sips/blob/feat/sip-10-ft/sips/sip-010/sip-010-fungible-token-standard.md -[SIP-009]: https://github.com/stacksgov/sips/blob/main/sips/sip-009/sip-009-nft-standard.md diff --git a/i18n/tr/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md b/i18n/tr/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md deleted file mode 100644 index fc4765aa0c..0000000000 --- a/i18n/tr/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md +++ /dev/null @@ -1,301 +0,0 @@ ---- -title: Clarity Values -description: Learn how to deal with Clarity Values in JavaScript -sidebar_position: 2 ---- - -## Introduction - -The Clarity language makes use of a strong static 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/hirosystems/stacks.js/tree/master/packages/transactions) library makes this easy, as we will demonstrate below. - -## Clarity Types - -Please see the following page for information on [Clarity Types](../write-smart-contracts/clarity-language/language-types). - -## Constructing Clarity Values and accessing their data - -Clarity values can be constructed with functions provided by the [@stacks/transactions](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library. These functions simply output javascript objects that contain a value and a numerical representation of the Clarity type information. The Clarity types are encoded as follows: - -```typescript -export enum ClarityType { - Int = 0, - UInt = 1, - Buffer = 2, - BoolTrue = 3, - BoolFalse = 4, - PrincipalStandard = 5, - PrincipalContract = 6, - ResponseOk = 7, - ResponseErr = 8, - OptionalNone = 9, - OptionalSome = 10, - List = 11, - Tuple = 12, - StringASCII = 13, - StringUTF8 = 14, -} -``` - -`ClarityValue` objects can be serialized and included in transactions that interact with published Clarity contracts. - -Here are examples of how to construct each type of Clarity value, and how to access its data if it has any: - -### Booleans - -```typescript -const t = trueCV(); -// { type: ClarityType.BoolTrue } - -const f = falseCV(); -// { type: ClarityType.BoolFalse } -``` - -Boolean Clarity Values don't contain any underlying data. They are simply objects with `type` information. - -### Optional Values - -```typescript -const nothing: NoneCV = noneCV(); -// { type: ClarityType.OptionalNone } - -const something: SomeCV = someCV(trueCV()); -// { type: ClarityType.OptionalSome, value: { type: 4 } } -``` - -Optional Clarity Values can either be nothing (an empty type that has no data), or something (a wrapped value). - -If you are dealing with a function or contract function that returns an `OptionalCV`, you should always check what type it is before trying to access its value. - -```typescript -const maybeVal: OptionalCV = await callReadOnlyFunction(...); - -if (maybeVal.type === ClarityType.OptionalSome) { - console.log(maybeVal.value); -} else if (maybeVal.type === ClarityType.OptionalNone) { - // deal with `none` value -} -``` - -### Buffers - -```typescript -const buffer = Buffer.from('foo'); -const bufCV: BufferCV = bufferCV(buffer); -// { type: ClarityType.Buffer, buffer: } -``` - -### Integers - -Clarity supports both integers and unsigned integers. - -```typescript -const i: IntCV = intCV(-10); -// { type: ClarityType.Int, value: BN { ... } } - -const u: UIntCV = uintCV(10); -// { type: ClarityType.UInt, value: BN { ... } } -``` - -Clarity value ints store their underlying data as `BigNum` values from the [bn.js](https://github.com/indutny/bn.js/) library. - -In order to display/print Clarity (u)int values, use the `cvToString(val)` method. - -If you wish to perform arithmetic operations using Clarity (u)int values, you must use methods from the `BigNum` api on their underlying `BigNum` values, and the construct a new Clarity value out of the result. For example: - -```typescript -const x = intCV(1); -const y = intCV(2); - -x.value.add(y.value); -// 3 -``` - -### Strings - -```typescript -const ascii: StringAsciiCV = stringAsciiCV('hello world'); -// { type: ClarityType.StringASCII, data: 'hello world' } - -const utf8: StringUtf8CV = stringUtf8CV('hello 🌾'); -// { type: ClarityType.StringUTF8, data: 'hello 🌾' } -``` - -Clarity supports both ascii and utf8 strings. - -### Principals - -```typescript -const address = 'SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B'; -const contractName = 'contract-name'; - -const spCV = standardPrincipalCV(address); -// { -// type: ClarityType.PrincipalStandard -// address: { -// type: StacksMessageType.Address, -// version: AddressVersion.MainnetSingleSig, -// hash160: "SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B" -// } -// } - -const cpCV = contractPrincipalCV(address, contractName); -// { -// type: ClarityType.PrincipalContract, -// contractName: { -// type: StacksMessageType.LengthPrefixedString, -// content: 'contract-name', -// lengthPrefixBytes: 1, -// maxLengthBytes: 128, -// }, -// address: { -// type: StacksMessageType.Address, -// version: AddressVersion.MainnetSingleSig, -// hash160: "SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B" -// } -// } -``` - -Both kinds of Clarity principal values contain `type` information and an `address` object. Contract principals also contain a `contractName`. - -### Response Values - -```typescript -const errCV = responseErrorCV(trueCV()); -// { type: ResponseErr, value: { type: ClarityType.BoolTrue } } - -const okCV = responseOkCV(falseCV()); -// { type: ResponseOk, value: { type: ClarityType.BoolFalse } } -``` - -Response Clarity Values will either have the type `ClarityType.ResponseOk` or `ClarityType.ResponseErr`. They both contain a Clarity Value. Often this value will be an integer error code if the response is an `Error`. - -### Tuples - -```typescript -const tupCV = tupleCV({ - a: intCV(1), - b: trueCV(), - c: falseCV(), -}); -// { -// type: ClarityType.Tuple, -// data: { -// a: { type: ClarityType.Int, value: BN { ... } }, -// b: { type: ClarityType.BoolTrue }, -// c: { type: ClarityType.BoolFalse }, -// } -// } - -console.log(tupCV.data['b']); -// { type: ClarityType.BoolTrue } -``` - -Tuples in Clarity are typed and contain named fields. The tuple above, for example, contains three fields with the names **a**, **b** and **c**, and the types of their values are `Int`, `Boolean` and `Boolean`, respectively. - -Clarity tuples are represented in JavaScript as objects and a tuple's data can be accessed by its `data` field, where the underlying JS object is stored. - -### Lists - -```typescript -const l = listCV([trueCV(), falseCV()]); -// { type: ClarityType.List, list: [{ type: ClarityType.BoolTrue }] } - -console.log(l.list[0]); -// { type: ClarityType.BoolTrue } -``` - -Lists, in Clarity, are homogeneous, meaning they can only contain elements of a singular (Clarity) type. Make sure to avoid constructing lists that have elements of multiple types. - -A Clarity lists underlying data can be accessed via its `list` field. - -## Using Clarity Values - -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](../understand-stacks/transactions#construction). - -## Utilizing Clarity Values from Transaction Responses - -`Read-only` Clarity functions can return Clarity values as a response. These `read-only` functions can be accessed easily in JavaScript via the [`callReadOnlyFunction()`](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions#calling-read-only-contract-function) function included in `@stacks/transactions`, which returns a `ClarityValue`. - -As mentioned above, `ClarityValues` are simply javascript objects containing a value and its associated Clarity type information. These object types are defined [here](https://github.com/hirosystems/stacks.js/tree/1f2b5fd8bdf1c2b5866e8171163594d7708a8c7a/packages/transactions/src/clarity/types). - -When you are calling a `read-only` contract function, you will always know what type the function will return, since functions in Clarity are strongly typed. - -It is common for Clarity functions to return values wrapped in a `Response`, in order to indicate if there was success or an error. - -Since every `ClarityValue` has a `type` field, the type of the result of a `read-only` function call can be checked and acted upon like so: - -```typescript -const contractAddress = 'ST3KC0MTNW34S1ZXD36JYKFD3JJMWA01M55DSJ4JE'; -const contractName = 'kv-store'; -const functionName = 'get-value'; -const buffer = bufferCVFromString('foo'); -const network = new StacksTestnet(); // for mainnet, use `StacksMainnet()` -const senderAddress = 'ST2F4BK4GZH6YFBNHYDDGN4T1RKBA7DA1BJZPJEJJ'; - -const options = { - contractAddress, - contractName, - functionName, - functionArgs: [buffer], - network, - senderAddress, -}; - -// make a read-only call to a contract function that -// returns a Response -const result: ResponseCV = await callReadOnlyFunction(options); - -if (result.type === ClarityType.ResponseOk) { - console.log(cvToString(result.value)); -} else if (result.type === ClarityType.ResponseErr) { - throw new Error(`kv-store contract error: ${result.value.data}`); -} -``` - -### ClarityValues to/from Hex - -If you receive a response from a transaction in the form of a `hex` string, you can deserialize it into a Clarity value like so: - -```javascript -import { hexToCV } from '@stacks/transactions'; - -let cv = hexToCV('hex_string'); -``` - -Similarly, you can convert a Clarity value to `hex` string like so: - -```javascript -import { cvToHex, trueCV } from '@stacks/transactions'; - -let trueHex = cvToHex(trueCV()); -``` - -## Debugging Clarity Values - -Sometimes you might receive a Clarity value that you were not expecting. Logging the value to your console won't always prove to be useful, unless you have memorized the Clarity value type enum values. - -In order to figure out what kind of value you are dealing with, you can use the `cvToString()` function to convert the Clarity value to a more easily readable string. - -For example, calling `cvToString()` on a large `tuple` might yield something like: - -``` -(tuple - (a -1) - (b u1) - (c 0x74657374) - (d true) - (e (some true)) - (f none) - (g SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B) - (h SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B.test) - (i (ok true)) - (j (err false)) - (k (list true false)) - (l (tuple (a true) (b false))) - (m "hello world") - (n u"hello \u{1234}"))` -``` diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/blockchain/index.md b/i18n/vi/docusaurus-plugin-content-docs/current/blockchain/index.md deleted file mode 100644 index 13db24ec30..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/blockchain/index.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: Blockchain -description: Stacks Blockchain -sidebar_position: 6 ---- - -Below is a guide to start working locally with the Stacks Blockchain. - -Code repository is [here](https://github.com/stacks-network/stacks-blockchain). - -## Getting started with the Stacks Blockchain - -### Download and build stacks-blockchain - -The first step is to ensure that you have Rust and the support software installed. - -```bash -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -``` - -:::info -For building on Windows, follow the rustup installer instructions at https://rustup.rs/ -::: - -From there, you can clone the Stacks Blockchain repository: - -```bash -git clone --depth=1 https://github.com/stacks-network/stacks-blockchain.git - -cd stacks-blockchain -``` - -Then build the project: - -```bash -cargo build -``` - -Run the tests: - -```bash -cargo test testnet -- --test-threads=1 -``` - -### Encode and sign transactions - -Here, we have generated a keypair that will be used for signing the upcoming transactions: - -```bash -cargo run --bin blockstack-cli generate-sk --testnet - -# Output -# { -# secretKey: "b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001", -# publicKey: "02781d2d3a545afdb7f6013a8241b9e400475397516a0d0f76863c6742210539b5", -# stacksAddress: "ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH" -# } -``` - -This keypair is already registered in the `testnet-follower-conf.toml` file, so it can be used as presented here. - -We will interact with the following simple contract `kv-store`. In our examples, we will assume this contract is saved to `./kv-store.clar`: - -```scheme -(define-map store { key: (string-ascii 32) } { value: (string-ascii 32) }) - -(define-public (get-value (key (string-ascii 32))) - (match (map-get? store { key: key }) - entry (ok (get value entry)) - (err 0))) - -(define-public (set-value (key (string-ascii 32)) (value (string-ascii 32))) - (begin - (map-set store { key: key } { value: value }) - (ok true))) -``` - -We want to publish this contract on chain, then issue some transactions that interact with it by setting some keys and getting some values, so we can observe read and writes. - -Our first step is to generate and sign, using your private key, the transaction that will publish the contract `kv-store`. To do that, we will use the subcommand `blockstack-cli` that has the following usage: - -```bash -blockstack-cli (options) publish [publisher-secret-key-hex] [fee-rate] [nonce] [contract-name] [file-name.clar] -``` - -With the following arguments: - -```bash -cargo run --bin blockstack-cli publish b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 515 0 kv-store ./kv-store.clar --testnet -``` - -The `515` is the transaction fee, denominated in microSTX. Right now, the testnet requires one microSTX per byte minimum, and this transaction should be less than 515 bytes. The third argument `0` is a nonce, that must be increased monotonically with each new transaction. - -This command will output the **binary format** of the transaction. In our case, we want to pipe this output and dump it to a file that will be used later in this tutorial. - -```bash -cargo run --bin blockstack-cli publish b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 515 0 kv-store ./kv-store.clar --testnet | xxd -r -p > tx1.bin -``` - -### Run the testnet - -You can observe the state machine in action locally by running: - -```bash -cargo stacks-node start --config=./testnet/stacks-node/conf/testnet-follower-conf.toml -``` - -`testnet-follower-conf.toml` is a configuration file that you can use for setting genesis balances or configuring Event observers. You can grant an address an initial account balance by adding the following entries: - -``` -[[ustx_balance]] -address = "ST2VHM28V9E5QCRD6C73215KAPSBKQGPWTEE5CMQT" -amount = 100000000 -``` - -The `address` field is the Stacks testnet address, and the `amount` field is the number of microSTX to grant to it in the genesis block. The addresses of the private keys used in the tutorial below are already added. - -### Publish your contract - -Assuming that the testnet is running, we can publish our `kv-store` contract. - -In another terminal (or file explorer), you can move the `tx1.bin` generated earlier, to the mempool: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx1.bin http://localhost:20443/v2/transactions -``` - -In the terminal window running the testnet, you can observe the state machine's reactions. - -### Reading from / Writing to the contract - -Now that our contract has been published on chain, let's try to submit some read / write transactions. We will start by trying to read the value associated with the key `foo`. - -To do that, we will use the subcommand: - -```bash -cargo run --bin blockstack-cli contract-call --help -``` - -With the following arguments: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 1 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store get-value -e \"foo\" --testnet | xxd -r -p > tx2.bin -``` - -`contract-call` generates and signs a contract-call transaction. - -We can submit the transaction by moving it to the mempool path: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx2.bin http://localhost:20443/v2/transactions -``` - -Similarly, we can generate a transaction that would be setting the key `foo` to the value `bar`: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 2 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store set-value -e \"foo\" -e \"bar\" --testnet | xxd -r -p > tx3.bin -``` - -And submit it by moving it to the mempool path: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx3.bin http://localhost:20443/v2/transactions -``` - -Finally, we can issue a third transaction, reading the key `foo` again, for ensuring that the previous transaction has successfully updated the state machine: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 3 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store get-value -e \"foo\" --testnet | xxd -r -p > tx4.bin -``` - -And submit this last transaction by moving it to the mempool path: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx4.bin http://localhost:20443/v2/transactions -``` - -Congratulations, you can now [write your own smart contracts with Clarity](write-smart-contracts/). diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/blockchain/networks.md b/i18n/vi/docusaurus-plugin-content-docs/current/blockchain/networks.md deleted file mode 100644 index fe9725352c..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/blockchain/networks.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Stacks Blockchain Networks -description: Stacks Blockchain Networks -sidebar_position: 3 ---- - -### Stacks Blockchain Networks - -- [x] **Krypton** is a Stacks 2 testnet with a fixed, two-minute block time, called `regtest`. Regtest is generally unstable for regular use, and is reset often. See the [regtest documentation](understand-stacks/testnet) for more information on using regtest. - -- [x] **Testnet** (old Xenon) is the Stacks 2 public testnet, which runs PoX against the Bitcoin testnet. It is the full implementation of the Stacks 2 blockchain, and should be considered a stable testnet for developing Clarity smart contracts. See the [testnet documentation](understand-stacks/testnet) for more information on the public testnet. - -- [x] **Mainnet** is the fully functional Stacks 2 blockchain, see the [Stacks overview](understand-stacks/) for information on running a Stacks node, mining, stacking, and writing Clarity smart contracts. diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md b/i18n/vi/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md deleted file mode 100644 index cf4f84a2da..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Stacks Blockchain API -description: Interacting with the Stacks 2.0 Blockchain via API -sidebar_position: 4 ---- - -## Introduction - -:::tip API Documentation Official API Documentation is available [here](https://stacks-network.github.io/stacks-blockchain/). ::: - - -The Stacks 2.0 Blockchain API allows you to query the Stacks 2.0 blockchain and interact with smart contracts. It was built to maintain pageable materialized views of the Stacks 2.0 Blockchain. - -:::caution The RESTful API is developed by Hiro. Hiro also hosts a public API node for easy onboarding. Using it requires you to trust the hosted server, but provides a faster onboarding experience. You can [run your own API server](https://docs.hiro.so/get-started/running-api-node) ::: - -The RESTful JSON API can be used without any authorization. The basepath for the API is: - -```bash -# for mainnet, replace `testnet` with `mainnet` -https://stacks-node-api.testnet.stacks.co/ -``` - -:::note This documentation only covers endpoints that are exposed on a Stacks node, referred to as the RPC API. For full documentation on the RESTful API, check out the [Hiro's API reference](https://docs.hiro.so/api). ::: - -### Stacks Node RPC API - -The [stacks-node implementation](https://github.com/stacks-network/stacks-blockchain/) exposes JSON RPC endpoints. - -All `/v2/` routes a proxied to a Hiro-hosted Stacks Node. For a trustless architecture, you should make these requests to a self-hosted node. - -## Proxied Stacks Node RPC API endpoints - -The Stacks 2.0 Blockchain API is centrally hosted. However, every running Stacks node exposes an RPC API, which allows you to interact with the underlying blockchain. Instead of using a centrally hosted API, you can directly access the RPC API of a locally hosted Node. - -:::tip -The Stacks Blockchain API proxies to Node RPC endpoints -::: - -While the Node RPC API doesn't give the same functionality as the hosted Stacks 2.0 Blockchain API, you get similar functionality in a way that is scoped to that specific node. The RPC API includes the following endpoints: - -- [POST /v2/transactions](https://docs.hiro.so/api#operation/post_core_node_transactions) -- [GET /v2/contracts/interface/{contract_address}/{contract_name}](https://docs.hiro.so/api#operation/get_contract_interface) -- [POST /v2/map_entry/{contract_address}/{contract_name}/{map_name}](https://docs.hiro.so/api#operation/get_contract_data_map_entry) -- [GET /v2/contracts/source/{contract_address}/{contract_name}](https://docs.hiro.so/api#operation/get_contract_source) -- [GET /v2/accounts/{principal}](https://docs.hiro.so/api#operation/get_account_info) -- [POST /v2/contracts/call-read/{contract_address}/{contract_name}/{function_name}](https://docs.hiro.so/api#operation/call_read_only_function) -- [GET /v2/fees/transfer](https://docs.hiro.so/api#operation/get_fee_transfer) -- [GET /v2/info](https://docs.hiro.so/api#operation/get_core_api_info) - -:::caution If you run a local node, it exposes an HTTP server on port `20443`. The info endpoint would be `localhost:20443/v2/info`. ::: diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md b/i18n/vi/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md deleted file mode 100644 index 71e3542302..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Stacks Releases -description: Stacks Blockchain Releases -sidebar_position: 2 ---- - -:::info -This page needs contributions. Help us improve it. -::: - -### Stacks Blockchain Releases - -All releases are published [here](https://github.com/stacks-network/stacks-blockchain/releases). Most important ones are described below. - -### Stacks 2.1 - -Scheduled for release at the end of 2022. - -More information on [what to expect with Stacks 2.1](https://stacks.org/stacks-21-what-to-expect). - -#### Stacks 2.05 -Activated on [Bitcoin block 713000](https://explorer.stacks.co/txid/0xece8e369310b5ff9b92ef11181ae0d2457ac0c821376d4a96c4998763e22ad04?chain=mainnet). - -This breaking change enables storage cost for list to be based on actual length and change in number of indexed I/O operations. More info on this [blog post](https://www.stacks.org/stacks-2-05?ref=docs-website). - -#### Stacks 2.0 -Activated on January 14th 2021 - -This hard fork enables Stacking, Clarity smart contracts, scalable transactions, and also building directly on Bitcoin. More info [here](https://forum.stacks.org/t/path-to-mainnet-for-stx-holders-things-to-know-ahead-of-stacks-2-0/11529). - -#### Stacks Genesis -Released on 2018, October 30th UTC+6 at Bitcoin block height 547921 - -This hard fork addresses registration of digital assets with Stacks token and also distribution of Stacks token to the existing purchasers. More info [here](https://blog.blockstack.org/the-launch-of-the-stacks-genesis-block/?ref=docs-website). - diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md b/i18n/vi/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md deleted file mode 100644 index 25ec969824..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Deploy tips -description: Learn some common methods for deploying your application. ---- - -## Introduction - -Stacks applications are web applications that authenticate users with Stacks Auth and store data with Gaia. Both of these technologies can be accessed on the client side. As such, Stacks apps tend to be simple in design and operation, since in many cases, they don’t have to host anything besides the application’s assets. - -## Where to deploy your application - -Before users can interact with your application, you must deploy it on a server that is accessible over the internet. Deploying requires that you: - -- Configure or customize the files in the `public` directory. -- Build your application site for deployment. -- Copy your generated application files to your production server. - -If you first populated your application with the Stacks application generator, your application contains the starting blocks for configuring, building, and deploying your app. For example, the React template builds out a scaffolding with the following building blocks. - -| File or Directory | Description | -| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| node_modules/react-scripts | A set of scripts for that helps you kick off React projects without configuring, so you do not have to set up your project by yourself. | -| package.json | Contains a scripts section that includes a reference to the react-scripts, which are a dependency. This script creates a build directory containing your files for deployment. | -| public/favicon.ico | An example shortcut icon. | -| public/index.html | An entry page for an application. | -| public/manifest.json | A JSON file that describes your web application to the browser. | -| cors | Contains example deployment files for cross-origin request configuration. | - -If you use the generator to build JavasScript or Vue scaffolding, your project configuration files will be different. - -Regardless of which scaffolding you use, you must customize and extend this basic scaffolding as needed by your application. For example, you may want to add more properties to the `manifest.json` file. Since every application is different, Stacks Auth cannot give you specific instructions on how to do this. The steps you take are specific to your application. - -## Stacks Authentication and deployment - -When your application authenticates users with Stacks, the Stacks Wallet at on URL requests a resource (the app manifest) from your DApp. A request for a resource outside of the origin (the Stacks Wallet) 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 (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) - -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 Stacks 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`: - -```html -Access-Control-Allow-Origin: * Access-Control-Allow-Headers: "X-Requested-With, Content-Type, -Origin, Authorization, Accept, Client-Security-Token, Accept-Encoding" Access-Control-Allow-Methods: -"POST, GET, OPTIONS, DELETE, PUT" -``` - -Consult the documentation for your hosting service to learn how to configure CORS on that service. - -## Deployment and Radiks - -If you are deploying a Stacks application that uses [Radiks](https://github.com/stacks-network/radiks), your deployment includes a server and a database component. You must take this into account when deploying your application. You may want to choose a service such as [Heroku](https://www.heroku.com) or [Digital Ocean](https://www.digitalocean.com) if your app uses Radiks. diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/build-apps/index.md b/i18n/vi/docusaurus-plugin-content-docs/current/build-apps/index.md deleted file mode 100644 index 23714cba5d..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/build-apps/index.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Build apps with Stacks -description: Authenticate users, sign transactions and store data with the Stacks blockchain -sidebar_position: 3 -sidebar_label: Build apps ---- - -## Introduction - -Apps built with the Stacks blockchain give users control over their digital identities, assets, and data. - -Unlike most cloud-based apps, they are "decentralized" since they don't depend on any centralized platform, server, or database to function. Rather, they use the Stacks blockchain to authenticate users and facilitate read and write requests for them without any single point of failure or trust. - -Stacks provides three main functions for building apps: - - - -- **Authentication**: Register and sign users in with identities on the Stacks blockchain -- **Transaction signing**: Prompt users to sign and broadcast transactions to the Stacks blockchain -- **Data storage**: Save and retrieve data for users with [Gaia](../gaia) - - -All three of these integrations can be used together to create powerful new user experiences that rival or exceed those of traditional apps—all while protecting your users' digital rights. - -While integration is possible for any type of app, most of the resources available here are for web developers experienced with JavaScript. See [Hiro developer docs](https://docs.hiro.so) for more information on the available app development libraries for Stacks. - -## [References](references) - -[Authentication](references/authentication) - -[BNS](references/bns) - -[Gaia](../gaia/) - diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md b/i18n/vi/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md deleted file mode 100644 index 727b4e2163..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: NoCodeClarity -description: Launch apps for the Stacks blockchain through no code platforms like Bubble. ---- - -## Introduction - -![](https://d1muf25xaso8hp.cloudfront.net/https%3A%2F%2Fs3.amazonaws.com%2Fappforest_uf%2Ff1653407713550x759333524803365600%2FLogo%2520of%2520NoCodeClarity.png?w=179&h=84&auto=compress&dpr=1&fit=max) - -[NoCodeClarity](https://nocodeclarity.com) allows people to create applications for the Stacks blockchain without coding. - -## Stacks Plug-In on bubble - -The [Stacks-No-Code-Plugin](https://bubble.io/plugin/the-stacks-plug-in-1645467277638x949839693014368300) released in May 2022 and it can easily be installed on Bubble with a few clicks allowing users to deploy applications with no coding knowledge. [Bubble](https://bubble.io/blog/explaining-bubble-to-investors/) is the first No Code platform that the Stacks plugin launched on. More platforms are in the roadmap of NoCodeClarity, founded by Christopher Perceptions and Sergio Gongora. The Stacks plugin was created through the support of the Stacks Foundation via a grant in January 2022 and NoCodeClarity was awarded a $100,000 grant in June 2022 to expand the roadmap. - -Additional [instructions](https://s3.amazonaws.com/appforest_uf/f1654202471526x991633667675927800/Instructions%20v2.docx.pdf) are also available. Tutorials and step by step guides will be released soon. - -The Stacks-No-Code-Plugin code is [publicly available on Github](https://github.com/nocodeclarity/Stacks-No-Code-Plugin). - -![](/img/bubble-stacks-plugin.png) - -## Demo page - -A demo page is available [here](https://test-stacks-plugin.bubbleapps.io/version-test). - -## NoCodeClarity videos - -NodeCodeClarity has their own [youtube channel](https://www.youtube.com/channel/UC9Ep0VQ-GQ-yDzt-wmIElRA). - -Videos: - -* [NoCodeClarity Setup](https://www.youtube.com/watch?v=WanXlpBGl0w) -* [NoCodeClarity - Part 1 of the plugin](https://www.youtube.com/watch?v=o6d3hrzNqVI&t=248s) -* [NoCodeClarity - Part 2 of the plugin](https://www.youtube.com/watch?v=0rzMdsrRg80) -* [Sneak Peek of the No Code Stacks Wallet Template](https://www.youtube.com/watch?v=Xe6Yv0rF6XM) \ No newline at end of file diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md b/i18n/vi/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md deleted file mode 100644 index c856cec484..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Authentication -description: Register and sign in users with identities on the Stacks blockchain ---- - -## Introduction - -This guide explains how authentication is performed on the Stacks blockchain. - -Authentication provides a way for users to identify themselves to an app while retaining complete control over their credentials and personal details. It can be integrated alone or used in conjunction with [transaction signing](https://docs.hiro.so/get-started/transactions#signature-and-verification) and [data storage](https://docs.stacks.co/gaia/overview), for which it is a prerequisite. - -Users who register for your app can subsequently authenticate to any other app with support for the [Blockchain Naming System](bns) and vice versa. - -## How it works - -The authentication flow with Stacks is similar to the typical client-server flow used by centralized sign in services (for example, OAuth). However, with Stacks the authentication flow happens entirely client-side. - -An app and authenticator, such as [the Stacks Wallet](https://www.hiro.so/wallet/install-web), communicate during the authentication flow by passing back and forth two tokens. The requesting app sends the authenticator an `authRequest` token. Once a user approves authentication, the authenticator responds to the app with an `authResponse` token. - -These tokens are are based on [a JSON Web Token (JWT) standard](https://tools.ietf.org/html/rfc7519) with additional support for the `secp256k1` curve used by Bitcoin and many other cryptocurrencies. They are passed via URL query strings. - -When a user chooses to authenticate an app, it sends the `authRequest` token to the authenticator via a URL query string with an equally named parameter: - -`https://wallet.hiro.so/...?authRequest=j902120cn829n1jnvoa...` - -When the authenticator receives the request, it generates an `authResponse` token for the app using an _ephemeral transit key_ . The ephemeral transit key is just used for the particular instance of the app, in this case, to sign the `authRequest`. - -The app stores the ephemeral transit key during request generation. The public portion of the transit key is passed in the `authRequest` token. The authenticator uses the public portion of the key to encrypt an _app private key_ which is returned via the `authResponse`. - -The authenticator generates the app private key from the user's _identity address private key_ and the app's domain. The app private key serves three functions: - -1. It is used to create credentials that give the app access to a storage bucket in the user's Gaia hub -2. It is used in the end-to-end encryption of files stored for the app in the user's Gaia storage. -3. It serves as a cryptographic secret that apps can use to perform other cryptographic functions. - -Finally, the app private key is deterministic, meaning that the same private key will always be generated for a given Stacks address and domain. - -The first two of these functions are particularly relevant to [data storage with Stacks.js](https://docs.stacks.co/docs/gaia). - -## Key pairs - -Authentication with Stacks makes extensive use of public key cryptography generally and ECDSA with the `secp256k1` curve in particular. - -The following sections describe the three public-private key pairs used, including how they're generated, where they're used and to whom private keys are disclosed. - -### Transit private key - -The transit private is an ephemeral key that is used to encrypt secrets that need to be passed from the authenticator to the app during the authentication process. It is randomly generated by the app at the beginning of the authentication response. - -The public key that corresponds to the transit private key is stored in a single element array in the `public_keys` key of the authentication request token. The authenticator encrypts secret data such as the app private key using this public key and sends it back to the app when the user signs in to the app. The transit private key signs the app authentication request. - -### Identity address private key - -The identity address private key is derived from the user's keychain phrase and is the private key of the Stacks username that the user chooses to use to sign in to the app. It is a secret owned by the user and never leaves the user's instance of the authenticator. - -This private key signs the authentication response token for an app to indicate that the user approves sign in to that app. - -### App private key - -The app private key is an app-specific private key that is generated from the user's identity address private key using the `domain_name` as input. - -The app private key is securely shared with the app on each authentication, encrypted by the authenticator with the transit public key. Because the transit key is only stored on the client side, this prevents a man-in-the-middle attack where a server or internet provider could potentially snoop on the app private key. diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/build-apps/references/bns.md b/i18n/vi/docusaurus-plugin-content-docs/current/build-apps/references/bns.md deleted file mode 100644 index 32b045dc83..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/build-apps/references/bns.md +++ /dev/null @@ -1,241 +0,0 @@ ---- -title: Blockchain Naming System -description: Binds Stacks usernames to off-chain state ---- - -Blockchain Naming System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of control. - -The Stacks V1 blockchain implemented BNS through first-order name operations. In Stacks V2, BNS is instead implemented through a smart-contract loaded during the genesis block. - -Names in BNS have three properties: - -- **Names are globally unique.** The protocol does not allow name collisions, and all well-behaved nodes resolve a given name to the same state. -- **Names are human-meaningful.** Each name is chosen by its creator. -- **Names are strongly owned.** Only the name's owner can change the state it resolves to. Specifically, a name is owned by one or more ECDSA private keys. - -The Stacks blockchain insures that each node's BNS view is synchronized to all of the other nodes in the world, so queries on one node will be the same on other nodes. Stacks blockchain nodes allow a name's owner to bind up to 40Kb of off-chain state to their name, which will be replicated to all other Stacks blockchain nodes via a P2P network. - -The biggest consequence for developers is that in BNS, reading name state is fast and cheap but writing name state is slow and expensive. This is because registering and modifying names requires one or more transactions to be sent to the underlying blockchain, and BNS nodes will not process them until they are sufficiently confirmed. Users and developers need to acquire and spend the requisite cryptocurrency (STX) to send BNS transactions. - -## Motivation behind naming systems - -We rely on naming systems in everyday life, and they play a critical role in many different applications. For example, when you look up a friend on social media, you are using the platform's naming system to resolve their name to their profile. When you look up a website, you are using the Domain Name Service to resolve the hostname to its host's IP address. When you check out a Git branch, you are using your Git client to resolve the branch name to a commit hash. When you look up someone's PGP key on a keyserver, you are resolving their key ID to their public key. - -What kinds of things do we want to be true about names? In BNS, names are globally unique, names are human-meaningful, and names are strongly owned. However, if you look at these examples, you'll see that each of them only guarantees _two_ of these properties. This limits how useful they can be. - -- In DNS and social media, names are globally unique and human-readable, but not strongly owned. The system operator has the final say as to what each names resolves to. - - - **Problem**: Clients must trust the system to make the right choice in what a given name resolves to. This includes trusting that no one but the system administrators can make these changes. - -- In Git, branch names are human-meaningful and strongly owned, but not globally unique. Two different Git nodes may resolve the same branch name to different unrelated repository states. - - - **Problem**: Since names can refer to conflicting state, developers have to figure out some other mechanism to resolve ambiguities. In Git's case, the user has to manually intervene. - -- In PGP, names are key IDs. They are are globally unique and cryptographically owned, but not human-readable. PGP key IDs are derived from the keys they reference. - - **Problem**: These names are difficult for most users to remember since they do not carry semantic information relating to their use in the system. - -BNS names have all three properties, and none of these problems. This makes it a powerful tool for building all kinds of network applications. With BNS, we can do the following and more: - -- Build domain name services where hostnames can't be hijacked. -- Build social media platforms where user names can't be stolen by phishers. -- Build version control systems where repository branches do not conflict. -- Build public-key infrastructure where it's easy for users to discover and remember each other's keys. - -## Organization of BNS - -BNS names are organized into a global name hierarchy. There are three different layers in this hierarchy related to naming: - -- **Namespaces**. These are the top-level names in the hierarchy. An analogy to BNS namespaces are DNS top-level domains. Existing BNS namespaces include `.id`, `.podcast`, and `.helloworld`. All other names belong to exactly one namespace. Anyone can create a namespace, but in order for the namespace to be persisted, it must be _launched_ so that anyone can register names in it. Namespaces are not owned by their creators. - -- **BNS names**. These are names whose records are stored directly on the blockchain. The ownership and state of these names are controlled by sending blockchain transactions. Example names include `verified.podcast` and `muneeb.id`. Anyone can create a BNS name, as long as the namespace that contains it exists already. - -- **BNS subdomains**. These are names whose records are stored off-chain, but are collectively anchored to the blockchain. The ownership and state for these names lives within the P2P network data. While BNS subdomains are owned by separate private keys, a BNS name owner must broadcast their subdomain state. Example subdomains include `jude.personal.id` and `podsaveamerica.verified.podcast`. Unlike BNS namespaces and names, the state of BNS subdomains is _not_ part of the blockchain consensus rules. - -A feature comparison matrix summarizing the similarities and differences between these name objects is presented below: - -| Feature | **Namespaces** | **BNS names** | **BNS Subdomains** | -| -------------------------------------- | -------------- | ------------- | ------------------ | -| Globally unique | X | X | X | -| Human-meaningful | X | X | X | -| Owned by a private key | | X | X | -| Anyone can create | X | X | [1] | -| Owner can update | | X | [1] | -| State hosted on-chain | X | X | | -| State hosted off-chain | | X | X | -| Behavior controlled by consensus rules | X | X | | -| May have an expiration date | | X | | - -[1] Requires the cooperation of a BNS name owner to broadcast its transactions - -## Namespaces - -Namespaces are the top-level naming objects in BNS. - -They control a few properties about the names within them: - -- How expensive they are to register -- How long they last before they have to be renewed -- Who (if anyone) receives the name registration fees -- Who is allowed to seed the namespace with its initial names. - -At the time of this writing, by far the largest BNS namespace is the `.id` namespace. Names in the `.id` namespace are meant for resolving user identities. Short names in `.id` are more expensive than long names, and have to be renewed by their owners every two years. Name registration fees are not paid to anyone in particular---they are instead sent to a "black hole" where they are rendered unspendable (the intention is to discourage ID squatters). - -Unlike DNS, _anyone_ can create a namespace and set its properties. Namespaces are created on a first-come first-serve basis, and once created, they last 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 (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`). - -Namespaces can be between 1 and 19 characters long, and are composed of the characters `a-z`, `0-9`, `-`, and `_`. - -## Subdomains - -BNS names are strongly owned because the owner of its private key can generate valid transactions that update its zone file hash and owner. However, this comes at the cost of requiring a name owner to pay for the underlying transaction in the blockchain. Moreover, this approach limits the rate of BNS name registrations and operations to the underlying blockchain's transaction bandwidth. - -BNS overcomes this with subdomains. A **BNS subdomain** is a type of BNS name whose state and owner are stored outside of the blockchain, but whose existence and operation history are anchored to the blockchain. Like their on-chain counterparts, subdomains are globally unique, strongly owned, and human-readable. BNS gives them their own name state and public keys. Unlike on-chain names, subdomains can be created and managed cheaply, because they are broadcast to the BNS network in batches. A single blockchain transaction can send up to 120 subdomain operations. - -This is achieved by storing subdomain records in the BNS name zone files. An on-chain name owner broadcasts subdomain operations by encoding them as `TXT` records within a DNS zone file. To broadcast the zone file, the name owner sets the new zone file hash with a `NAME_UPDATE` transaction and replicates the zone file. This, in turn, replicates all subdomain operations it contains, and anchors the set of subdomain operations to an on-chain transaction. The BNS node's consensus rules ensure that only valid subdomain operations from _valid_ `NAME_UPDATE` transactions will ever be stored. - -For example, the name `verified.podcast` once wrote the zone file hash `247121450ca0e9af45e85a82e61cd525cd7ba023`, which is the hash of the following zone file: - -```bash -$TTL 3600 -1yeardaily TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxeWVhcmRhaWx5CiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMXllYXJkYWlseS9oZWFkLmpzb24iCg==" -2dopequeens TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAyZG9wZXF1ZWVucwokVFRMIDM2MDAKX2h0dHAuX3RjcCBVUkkgMTAgMSAiaHR0cHM6Ly9waC5kb3Rwb2RjYXN0LmNvLzJkb3BlcXVlZW5zL2hlYWQuanNvbiIK" -10happier TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxMGhhcHBpZXIKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8xMGhhcHBpZXIvaGVhZC5qc29uIgo=" -31thoughts TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzMXRob3VnaHRzCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzF0aG91Z2h0cy9oZWFkLmpzb24iCg==" -359 TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzNTkKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8zNTkvaGVhZC5qc29uIgo=" -30for30 TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzMGZvcjMwCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzBmb3IzMC9oZWFkLmpzb24iCg==" -onea TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiBvbmVhCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vb25lYS9oZWFkLmpzb24iCg==" -10minuteteacher TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxMG1pbnV0ZXRlYWNoZXIKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8xMG1pbnV0ZXRlYWNoZXIvaGVhZC5qc29uIgo=" -36questionsthepodcastmusical TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzNnF1ZXN0aW9uc3RoZXBvZGNhc3RtdXNpY2FsCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzZxdWVzdGlvbnN0aGVwb2RjYXN0bXVzaWNhbC9oZWFkLmpzb24iCg==" -_http._tcp URI 10 1 "https://dotpodcast.co/" -``` - -Each `TXT` record in this zone file encodes a subdomain-creation. For example, `1yeardaily.verified.podcast` resolves to: - -```json -{ - "address": "1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH", - "blockchain": "bitcoin", - "last_txid": "d87a22ebab3455b7399bfef8a41791935f94bc97aee55967edd5a87f22cce339", - "status": "registered_subdomain", - "zonefile_hash": "e7acc97fd42c48ed94fd4d41f674eddbee5557e3", - "zonefile_txt": "$ORIGIN 1yeardaily\n$TTL 3600\n_http._tcp URI 10 1 \"https://ph.dotpodcast.co/1yeardaily/head.json\"\n" -} -``` - -This information was extracted from the `1yeardaily` `TXT` resource record in the zone file for `verified.podcast`. - -### Subdomain Lifecycle - -Note that `1yeardaily.verified.podcast` has a different public key hash (address) than `verified.podcast`. A BNS node will only process a subsequent subdomain operation on `1yeardaily.verified.podcast` if it includes a signature from this address's private key. `verified.podcast` cannot generate updates; only the owner of `1yeardaily.verified.podcast can do so`. - -The lifecycle of a subdomain and its operations is shown in Figure 2. - -``` - subdomain subdomain subdomain - creation update transfer -+----------------+ +----------------+ +----------------+ -| cicero | | cicero | | cicero | -| owner="1Et..." | signed | owner="1Et..." | signed | owner="1cJ..." | -| zf0="7e4..." |<--------| zf0="111..." |<--------| zf0="111..." |<---- ... -| seqn=0 | | seqn=1 | | seqn=2 | -| | | sig="xxxx" | | sig="xxxx" | -+----------------+ +----------------+ +----------------+ - | | | - | off-chain | | -~ ~ ~ ~ | ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~|~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ | ~ ~ ~ ~ ~ ~ ~ ... - | on-chain | | - V V (zone file hash ) V -+----------------+ +----------------+ +----------------+ -| res_publica.id | | jude.id | | res_publica.id | -| NAME_UPDATE |<--------| NAME_UPDATE |<--------| NAME_UPDATE |<---- ... -+----------------+ +----------------+ +----------------+ - blockchain blockchain blockchain - block block block - - -Figure 2: Subdomain lifetime with respect to on-chain name operations .A new -subdomain operation will only be accepted if it has a later "sequence=" number, -and a valid signature in "sig=" over the transaction body .The "sig=" field -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." -However, any on-chain name ("jude.id" in this case) can broadcast a subdomain -update for "cicero.res_publica.id." -``` - -Subdomain operations are ordered by sequence number, starting at 0. Each new subdomain operation must include: - -- The next sequence number -- The public key that hashes to the previous subdomain transaction's address -- A signature from the corresponding private key over the entire subdomain operation. - -If two correctly signed but conflicting subdomain operations are discovered (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 subdomain's operations will be able to determine the valid sequence of state-transitions it has undergone, and determine the current zone file and public key hash for the subdomain. - -### Subdomain Creation and Management - -Unlike an on-chain name, a subdomain owner needs an on-chain name owner's help to broadcast their subdomain operations. In particular: - -- A subdomain-creation transaction can only be processed by the owner of the on-chain name that shares its suffix. For example, only the owner of `res_publica.id` can broadcast subdomain-creation transactions for subdomain names ending in `.res_publica.id`. -- A subdomain-transfer transaction can only be broadcast by the owner of the on-chain name that created it. For example, the owner of `cicero.res_publica.id` needs the owner of `res_publica.id` to broadcast a subdomain-transfer transaction to change `cicero.res_publica.id`'s public key. -- In order to send a subdomain-creation or subdomain-transfer, all of an on-chain name owner's zone files must be present in the Atlas network. This lets the BNS node prove the _absence_ of any conflicting subdomain-creation and subdomain-transfer operations when processing new zone files. -- A subdomain update transaction can be broadcast by _any_ on-chain name owner, but the subdomain owner needs to find one who will cooperate. For example, the owner of `verified.podcast` can broadcast a subdomain-update transaction created by the owner of `cicero.res_publica.id`. - -That said, to create a subdomain, the subdomain owner generates a subdomain-creation operation for their desired name and gives it to the on-chain name owner. - -Once created, a subdomain owner can use any on-chain name owner to broadcast a subdomain-update operation. To do so, they generate and sign the requisite subdomain operation and give it to an on-chain name owner, who then packages it with other subdomain operations into a DNS zone file and broadcasts it to the network. - -If the subdomain owner wants to change the address of their subdomain, they need to sign a subdomain-transfer operation and give it to the on-chain name owner who created the subdomain. They then package it into a zone file and broadcast it. - -### Subdomain Registrars - -Because subdomain names are cheap, developers may be inclined to run subdomain registrars on behalf of their applications. For example, the name `personal.id` is used to register usernames without requiring them to spend any Bitcoin. - -We supply a reference implementation of a [BNS Subdomain Registrar](https://github.com/stacks-network/subdomain-registrar) to help developers broadcast subdomain operations. Users would still own their subdomain names; the registrar simply gives developers a convenient way for them to register and manage them in the context of a particular application. - -# BNS and DID Standards - -BNS names are compliant with the emerging [Decentralized Identity Foundation](http://identity.foundation) protocol specification for decentralized identifiers (DIDs). - -Each name in BNS has an associated DID. The DID format for BNS is: - -```bash - did:stack:v0:{address}-{index} -``` - -Where: - -- `{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 `did:stack:v0:1dARRtzHPAFRNE7Yup2Md9w18XEQAtLiV-0`, because the name `personal.id` was the first-ever name created by `1dARRtzHPAFRNE7Yup2Md9w18XEQAtLiV`. - -As another example, the DID for `jude.id` is `did:stack:v0:16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg-1`. Here, the address `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` had created one earlier name in history prior to this one (which happens to be `abcdefgh123456.id`). - -The purpose of a DID is to provide an eternal identifier for a public key. The public key may change, but the DID will not. - -Stacks Blockchain implements a DID method of its own in order to be compatible with other systems that use DIDs for public key resolution. In order for a DID to be resolvable, all of the following must be true for a name: - -- The name must exist -- The name's zone file hash must be the hash of a well-formed DNS zone file -- The DNS zone file must be present in the Stacks node's data. -- The DNS zone file must contain a `URI` resource record that points to a signed JSON Web Token -- The public key that signed the JSON Web Token (and is included with it) must hash to the address that owns the name - -Not all names will have DIDs that resolve to public keys. However, names created by standard tooling will have DIDs that do. - -A RESTful API is under development. - -## DID Encoding for Subdomains - -Every name and subdomain in BNS has a DID. The encoding is slightly different 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 (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 subdomains owned by a single private key, and version byte 50 for subdomains owned by a m-of-n set of private keys. That is, subdomain DID addresses start with `S` or `M`, respectively. - -The `{index}` field for a subdomain's DID is distinct from the `{index}` field for a BNS name's DID, even if the same created both names and subdomains. For example, the name `abcdefgh123456.id` has the DID `did:stack:v0:16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg-0`, because it was the first name created by `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg`. However, `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` _also_ created `jude.statism.id` as its first subdomain name. The DID for `jude.statism.id` is `did:stack:v0:SSXMcDiCZ7yFSQSUj7mWzmDcdwYhq97p2i-0`. Note that the address `SSXMcDiCZ7yFSQSUj7mWzmDcdwYhq97p2i` encodes the same public key hash as the address `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` (the only difference between these two strings is that the first is base58check-encoded with version byte 0, and the second is encoded with version byte 63). diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/build-apps/references/references.md b/i18n/vi/docusaurus-plugin-content-docs/current/build-apps/references/references.md deleted file mode 100644 index babe5e119a..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/build-apps/references/references.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: References -sidebar_label: References ---- - -[Authentication](./authentication) - -[Blockchain Naming System](./bns) - -[Hiro example apps](https://docs.hiro.so/example-apps) \ No newline at end of file diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/contribute/docs.md b/i18n/vi/docusaurus-plugin-content-docs/current/contribute/docs.md deleted file mode 100644 index 77705451b8..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/contribute/docs.md +++ /dev/null @@ -1,207 +0,0 @@ ---- -title: Contribute to docs -description: Learn how this site is built, and how you can contribute to it. ---- - -## Introduction - -Thank you for your interest in contributing and helping make these docs as good as they can be. - -This docs site is built on the open source platform [Discosaurus 2](https://docusaurus.io/) and most of its content is written in Markdown files. All of the code for this site is free and open source, located at the [GitHub repository here](https://github.com/stacks-network/docs). - -:::tip Don't know what Markdown is? Want to learn? Here is a [helpful guide](https://guides.github.com/features/mastering-markdown/). - -Don't want to learn it? No need to. Write [in plain text an issue on Github](https://github.com/stacks-network/docs/issues/new?assignees=&labels=documentation&template=add-documentation.md&title=%5BAdd+docs%5D) ::: - -:::info You need a free [Github](https://www.github.com) account to add or edit any content. ::: - -To edit any page, just click on the *Edit this page* button at the bottom of each page and submit your changes online. - -To add new content, they are two different ways to do it, the [easy way](#easy-way) and the [advanced way](#advanced-way). - -## Easy way - -[**Simply click here and enter the text of the article you wish to add.**](https://github.com/stacks-network/docs/issues/new?assignees=&labels=documentation&template=add-documentation.md&title=%5BAdd+docs%5D) - -This will open up an issue on github using our template. -## Advanced way - -For more advanced changes you can follow the next steps. - -You can also test the site locally using this method. -### Steps - -1. Fork the [docs reposiroty](https://github.com/stacks-network/docs) by clicking on the *Fork* button in the upper right of the screen. -2. Clone your fork to your local machine with this command `git clone git@github.com:/docs.git stacks_docs` -3. Enter your project folder `cd stacks_docs` -4. Create a branch `git checkout -b feat/my-feature-branch`. -5. You can optionally preview your changes in real time with: - - `npm install` (to install dependencies). - - `npx docusaurus start` to start a local copy of the site. A web browser will open at http://localhost:3000, so you can see a preview of yourhanges in real time. -6. Make the changes you wish and then commit them with this kind of message: `git commit -am "feat: some new feature or content"`. -7. Push to to GitHub with `git push --set-upstream origin feature/my-feature-branch`. -8. Visit GitHub and make your pull request. - -## Aditional information -### Running and building the site locally (optional) - -You can start the page locally with the following command. This is enough to preview your changes. -```bash -npx docusaurus start -``` - -Before running this command for the first time you will need to run `npm install` to install dependencies. - -The docs site will be accessible at this url: [`http://localhost:3000`](http://localhost:3000). - - -After you finished your changes, you can also build the entire site with the following command (not usually needed): -```bash -npm run build -``` - -:::tip `npx docusaurus start` will only load the default language (english). To test all languages you can build with `npm run build` and then preview your build with `npm run serve`. ::: - -### An alternative: Working in browser - -As an alterative to working locally, you can also use the web IDE gitpod that provides an environment to contribute directly from within your browser. - -You only need to have a github account and open [this link](https://gitpod.io/#https://github.com/stacks-network/docs). - -### Folder structure of the site - -If you are interested in only adding new documentation content to the site, the files that will be important to you are located within `./docs/*`: - -```bash -docs/ - build-apps - contribute/ - faq/ - gaia/ - nodes-and-miners/ - noteworthy-contracts/ - references/ - understand-stack/ - write-smart-contracts/ -``` - -The routing for this site is file based, meaning if you created a folder within `/docs/gaia/` named `testing` and in it a file named `test1.md`, you would be able to navigate to `http://localhost:3000/gaia/testing/test1` and you would see whatever content is in that markdown file. - -All the docs in English are stored in the folder `/docs/`. - -To add new English content simply add a markdown file (.md) into any subfolder in docs, and it will be automatically displayed in the category of that folder. - -All the docs in other languages are stored under the folder `i18n`, but these files should never be edited using GitHub as they are overwritten by Crowdin every time new translations are added. **To make changes in other languages**, you must do so using Crowdin. Please refer to [translations](translations) instead. - -### Frontmatter - -Frontmatter is the top part of any markdown document that is written in a language called [YAML](https://yaml.org/). It looks like this: - -```yaml ---- -title: This is my page title -description: A short, concise sentence describing what is on this page ---- -``` - -Frontmatter gives us the ability to define some things within a page that the site can use, such as a page title or page description. When adding any new page, please include a `title` and `description`. - - - -### Use Conventional Commits - -We use the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) as and commits naming convention. Use it while contributing, please. - -### Code blocks - -To write a code block, you need to wrap your code in ` ```language `, and end your code block with ` ``` `. Here is an example of ` ```clarity `. - -```clarity -(define-data-var counter int 0) - -(define-public (get-counter) - (ok (var-get counter))) -``` -### Admonitions - -You can use the following admonitions to highlight content. - -```md -:::note -Some **content** with _markdown_ `syntax`. -::: - -:::tip -Some **content** with _markdown_ `syntax`. -::: - -:::info -Some **content** with _markdown_ `syntax`. -::: - -:::caution -Some **content** with _markdown_ `syntax`. -::: - -:::danger -Some **content** with _markdown_ `syntax`. -::: - -:::tip My personalized title -Some **content** with _markdown_ `syntax`. -::: -``` - -Which renders: - -:::note - -Some **content** with _markdown_ `syntax`. - -::: - -:::tip - -Some **content** with _markdown_ `syntax`. - -::: - -:::info - -Some **content** with _markdown_ `syntax`. - -::: - -:::caution - -Some **content** with _markdown_ `syntax`. - -::: - -:::danger - -Some **content** with _markdown_ `syntax`. - -::: - -:::tip My personalized title - -Some **content** with _markdown_ `syntax`. - -::: \ No newline at end of file diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/contribute/index.md b/i18n/vi/docusaurus-plugin-content-docs/current/contribute/index.md deleted file mode 100644 index ac81d899bd..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/contribute/index.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Contribute -description: Contribute to the Stacks ecosystem. -sidebar_position: 10 -sidebar_label: "Contribute" ---- - -You can contribute to the Stacks ecosystem in multiple ways: - - - -### Documentation - -Contribute to the Stacks Docs on this website. More info [here](docs). - -### Translations - -Help us reach more people with translations. More details [here](translations). - - - -### Articles - -Write an article or a blog post about Stacks. A good place to start is [Stacks Forum](https://forum.stacks.org). - -### Github - -If you are familiar with Github they are multiple repositories of the Stack Ecosystem that you can contribute to. - -- https://github.com/stacks-network/ diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/contribute/translations.md b/i18n/vi/docusaurus-plugin-content-docs/current/contribute/translations.md deleted file mode 100644 index bd9a452333..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/contribute/translations.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Contribute with translations -description: Want to help tranlating these docs to your local language? ---- - -## Help with translations - -Translations are managed with Crowdin. -Anybody can colaborate and no technichal skills are required, as it's all done on the browser. - -To help with translation please go to [this page](https://crowdin.com/project/docsstacksco), click any language and start translating. - -All help is appreciated. - -:::caution -Please don't add any translations to the Github repository, as the translated pages get rewritten from Crowdin. Translations need to be added on Crodin intead. -::: - -### Common issues on translations - -When translating in Crowdin, please only translate the texts and not the html code. - -If you acccidently modify the html tags you will get errors like shown below (`Seems like some formating tags are missing` or `Translation contains tag that source text doesn't have`). These errors will prevent your translation getting published until the tags are left as they were in the original text. - -![](/img/crowdin-qa-issue-formatting_tags_missing.png) ![](/img/crowdin-qa-issue-tag_source.png) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/faq/faq.md b/i18n/vi/docusaurus-plugin-content-docs/current/faq/faq.md deleted file mode 100644 index dde584e583..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/faq/faq.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: General FAQs -description: Frequently Asked Questions -sidebar_label: "FAQ" -sidebar_position: 10 ---- - -![](/img/glasses.png) - -## Why is my transfer still pending? - -Commonly it's because your fee is too low or your [nonce](#what-is-nonce) is incorrect. - -More information can be found [here](https://www.hiro.so/wallet-faq/why-is-my-stacks-transaction-pending). There are also [best practices and known issues](https://forum.stacks.org/t/transactions-in-mempool-best-practices-and-known-issues/11659) and [diagnosing pending transactions](https://forum.stacks.org/t/diagnosing-pending-transactions/11908). - -There is also this [script](https://github.com/citycoins/scripts/blob/main/getnetworkstatus.js) to look at either the first 200 transactions or all the transactions in the mempool, to then return the maximum adn average fee values. We've noticed that using 1.5-2x the average fee in the mempool will generally get things processed within 6-10 blocks even during high congestion. - -There is also this [script](https://github.com/citycoins/scripts/blob/main/gettxstatus.js) to track a pending transaction until it reaches a final status. - -## What is Nonce? - -A nonce is used to make sure that every transaction goes in right order. Nonce starts at 0, so the very first transaction from an address should set to nonce=0. You can find the nonce of your wallet address by searching the address in any [Stacks blockchain explorer](https://explorer.stacks.co/). You can also user `$ stx balance
`. - -If you have a transaction nonce that is less than your account nonce, the transaction is unmineable and will (should) disappear after 256 blocks. This does not affect future transactions and therefore can be just ignored, they are in the past. - -If you have a transaction nonce that is equal to your account nonce, then that transaction is valid and should be the next in line to be processed next. - -If you have a transaction nonce that is higher than your account nonce, then there needs to be a chain of transactions starting with your account nonce in order for it to be processed. E.g. Your account nonce is 10 but the pending transaction has a nonce of 12. It will not be mineable until a transaction with nonces 10 and 11 are processed. - -## Whats a Replace-by-fee (RBF)? - -A replace-by-fee (RBF) transaction tells the blockchain that you would like to replace one transaction with another, while specifying a fee that is higher than the original transaction fee. A transaction can be replaced with **any other transaction**, and is not limited to the same operation. - -This can be used to effectively **cancel a transaction** by replacing it with something else, like a small STX transfer to another owned address. - -This can be used to **raise the fee for a pending transaction** so it is considered by miners during periods of high congestion. This can also be used to _resubmit_ a transaction, in the sense that the RBF transaction gets a new txid and gets considered again (or faster) by miners. E.g. I submit my transaction with 1 STX fee at block 54,123. By block 54,133 I see my tx hasn’t been picked up, so I RBF with 1.1 STX. Then wait 10 blocks again, and RBF again if not received. There’s a balance between doing this too often and keeping a consistent pace, but it has been seen to help get transactions through, especially when new ones are constantly flooding in. - -The replacement transaction needs to use the same nonce as the original transaction with a fee increase of at least 0.000001 STX. E.g. Your original transaction has a fee of 0.03 STX, the new RBF transaction must have a fee of 0.030001 STX or above. - -RBF transactions process in one of two ways: - -- If miners pick up the original transaction before the RBF transaction is received, then the original transaction is processed and the replacement transaction goes into an unmineable state. It will eventually disappear and doesn’t affect future transactions. -- If miners pick up the replaced transaction then the new transaction is processed instead of the original, and the status of the original transaction is set to “droppped_replaced_by_fee”. This status is not shown on the explorer but can be seen when querying the txid. - -Submitting multiple transactions for the same action can slow things down in a few ways. - -- If the total spent in 2 or 3 transactions is more than can be spent in a single transaction, the transactions appear unmineable. -- If the fees for multiple transactions exceed the STX balance, the transactions will be unmineable. - -## What are .btc domains? - -[This forum post](https://forum.stacks.org/t/btc-domains-are-live/12065) explains all the benefits of .btc domains. They can currently be purchased in [btc.us](https://btc.us/) - -## What is the blockchain trilemma? - -## Stacks vs. Solana vs. Polygon: How Do They Compare From a Developer Perspective? - -[This blog post answers the question](https://www.hiro.so/blog/stacks-vs-solana-vs-polygon-how-do-they-compare-from-a-developer-perspective). - -## What Does Lightning’s Taro Proposal Mean for Stacks? - -[This blog post answers the question](https://www.hiro.so/blog/what-does-lightnings-taro-proposal-mean-for-stacks). - - -## Is Stacks a [PoS chain](https://en.wikipedia.org/wiki/Proof_of_stake)?[¹][] - -No. - -The act of block production requires an extrinsic expenditure — it is not tied to owning the native token, as would be required in PoS. The only way to produce blocks in the Stacks chain is to transfer Bitcoin to a predetermined randomized list of Bitcoin addresses. Moreover, the Stacks blockchain can fork, and there exists a protocol to rank forks by quality independent of the set of miners and the tokens they hold. These two properties further distinguish it from PoS chains, which cannot fork due to the inability to identify a canonical fork without trusting a 3rd party to decree a particular fork as valid. The ability to fork allows the Stacks blockchain to survive failure modes that would crash a PoS chain. - -## Is Stacks a [sidechain](https://en.bitcoin.it/wiki/Sidechain)?[¹][] - -No. - -For two key reasons. - -First, the history of all Stacks blocks produced is recorded to Bitcoin. This means that the act of producing a private Stacks fork is at least as hard as reorging the Bitcoin chain. This in turn makes it so attacks on the chain that rely on creating private forks (such as selfish mining and double-spending) are much harder to carry out profitably, since all honest participants can see the attack coming before it happens and have a chance to apply countermeasures. Sidechains offer no such security benefit. - -Second, the Stacks blockchain has its own token; it does not represent pegged Bitcoin. This means that the safety of the canonical fork of the Stacks blockchain is underpinned by its entire token economy’s value, whereas the safety of a sidechain’s canonical fork is underpinned only by whatever system-specific measures incentivize its validators to produce blocks honestly, or the Bitcoin miners’ willingness to process peg-in requests (whichever is the weaker guarantee). - - -## Is Stacks a [layer-2 system](https://academy.binance.com/en/glossary/layer-2) for Bitcoin?[¹][] - -No. - -Stacks blockchain is a layer-1 blockchain, which uses a novel and unique mining protocol called proof-of-transfer (PoX). A PoX blockchain runs in parallel to another blockchain (Bitcoin in Stacks’ case), which it uses as a reliable broadcast medium for its block headers. It's a sovereign system in its own right. The Stacks blockchain state is distinct from Bitcoin, and is wholly maintained by and for Stacks nodes. Stacks transactions are separate from Bitcoin transactions. Layer-2 systems like Lightning are designed to help scale Bitcoin payment transactions, whereas Stacks is designed to bring new use-cases to Bitcoin through smart contracts. Stacks is not designed as a Bitcoin layer-2 scalability solution. - - -## Is Stacks a [merged-mined chain](https://en.bitcoin.it/wiki/Merged_mining_specification)?[¹][] - -No. - -The only block producers on the Stacks chain are Stacks miners. Bitcoin miners do not participate in Stacks block validation, and do not claim Stacks block rewards. Moreover, Stacks is not a [blind merged-mined chain](https://github.com/bitcoin/bips/blob/master/bip-0301.mediawiki), because STX block winners are public and randomly chosen (instead of highest-bid-wins), and its tokens are minted according to a schedule that is independent of the degree of miner commitment or Bitcoin transferred (instead of minted only by one-way pegs from Bitcoin). This ensures that Stacks is able to make forward progress without opt-in from Bitcoin miners, and it ensures that Stacks miners are adequately compensated for keeping the system alive regardless of transaction volume. - -## Whats the difference between Stacks and Ethereum?[²][] -**Computation and Storage** Stacks does all computation and storage outside of the blockchain, and uses the blockchain only as a “shared source of truth” between clients. By contrast, Ethereum does all computation and most application storage in the blockchain itself. Like Ethereum, if two Stacks nodes see the same underlying blockchain, they will independently run the same computations and produce the same state. Unlike Ethereum, there is no Stacks-specific blockchain. - -**Programming Language and Tooling** Stacks’s programming model is based on running off-chain programs. These programs can be written and debugged in any language you want. By contrast, Ethereum’s programming model is based on running on-chain “smart contracts.” These are written and debugged with a whole new set of tools, like Solidity and Serpent. - -**Scalability of On-chain Computation** Stacks is designed around a “virtual chain” concept, where nodes only need to reach consensus on the shared “virtual chain” they’re interested in. Virtual chains do not interact with one another, and a single blockchain can host many virtual chains. Although Stacks’s specific virtual chain is not Turing-complete (i.e. it’s a list of instructions to build the name database), it is possible to create Turing-complete virtual chains like Ethereum. These virtual chains can live in any blockchain for which there exists a driver, and virtual chain clients only need to execute their virtual chain transactions (i.e. Stacks only processes Stacks virtual chain transactions). - -By contrast, because smart contracts run on-chain and can call one another, all Ethereum nodes need to process all smart contracts’ computations in order to reach consensus. This can get expensive as the number of running smart contracts grow, which takes the form of gas fee increases. - -**Scalability of Off-chain Computation** Stacks applications are very similar to Web applications today and almost never need to interact with the blockchain. For most Stacks applications, the blockchain is only used to authenticate the application’s code and data before the user runs it. By contrast, Ethereum applications usually require an application-specific smart contract, and must interact with the blockchain to carry out its operations. - - -[¹]: https://stacks.org/stacks-blockchain -[²]: https://forum.stacks.org/t/what-is-the-difference-between-blockstack-and-ethereum/781 diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/gaia/configuration.md b/i18n/vi/docusaurus-plugin-content-docs/current/gaia/configuration.md deleted file mode 100644 index 9fa365d7bf..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/gaia/configuration.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Configuration -description: Configuring Gaia Hub ---- - -## Configuration files - -The following configuration files exist in the folder `deploy/configs/gaia/`: - -``` -admin-config.json -hub-config.json -reader-config.json -``` - -## GAIA Admin Service - -You can also use the GAIA Admin Service to remotely administer it with an API Key. It will require you to install `npm` with a `apt install npm`. Once `npm` is installed you can continue with the steps in the [GAIA Admin Service](https://github.com/stacks-network/gaia/blob/master/admin/README.md). - -## Driver Selection - -The Gaia hub currently supports the following drivers: - -``` -'aws' == Amazon S3 -'azure' == Azure Blob Storage -'disk' == Local disk -'google-cloud' === Google Cloud Storage -``` - -Set the driver you wish to use in your [config.json](https://github.com/stacks-network/gaia/blob/master/hub/config.sample.json) file with the `driver` parameter. Many drivers additionally accept the `bucket` parameter, which controls the bucket name that files should be written to. - -These driver may require you to provide additional credentials for performing writes to the backends. See `config.sample.json` for fields for those credentials. In some cases, the driver can use a system configured credential for the backend (e.g., if you are logged into your AWS CLI account, and run the hub from that environment, it won't need to read credentials from your `config.json`). - -:::caution -The disk driver requires a \*nix like filesystem interface, and will not work correctly when trying to run in a Windows environment. -::: - -## Note on SSL - -We _strongly_ recommend that you deploy your Gaia hub with SSL enabled. Otherwise, the tokens used to authenticate with the Gaia hub may be stolen by attackers, which could allow them to execute writes on your behalf. -Configuration options are available to run the hub with an `https` Node.js server. -Otherwise, a reverse proxy web server such as nginx or Apache can be used. - -## Require Correct Hub URL - -If you turn on the `requireCorrectHubUrl` option in your `config.json` file, your Gaia hub will require that authentication requests correctly include the `hubURL` they are trying to connect with. This is used to prevent a malicious gaia hub from using an authentication token for itself on other Gaia hubs. - -By default, the Gaia hub will validate that the supplied URL matches `https://${config.serverName}`, but if there are multiple valid URLs for clients to reach the hub at, you can include a list in your `config.json`: - -```javascript -{ - .... - serverName: "normalserver.com" - validHubUrls: [ "https://specialserver.com/", - "https://legacyurl.info" ] - .... -} -``` - -## The readURL parameter - -By default, the gaia hub drivers will return read URLs which point directly at the written content. For example, an S3 driver would return the URL directly to the S3 file. However, if you configure a CDN or domain to point at that same bucket, you can use the `readURL` parameter to tell the gaia hub that files can be read from the given URL. For example, the `hub.blockstack.org` Gaia Hub is configured to return a read URL that looks like `https://gaia.blockstack.org/hub/`. - -Unset this configuration parameter if you do not intend to deploy any caching. - -## Minimum Proofs Requirement - -The gaia hub can also be configured to require a minimum number of social proofs in a user's profile to accept writes from that user. This can be used as a kind of spam-control mechanism. However, we recommend for the smoothest operation of your gaia hub, to set the `proofsConfig.proofsRequired` configuration key to `0`. - -## CDN & Replicated Hubs - -- https://docs.microsoft.com/en-us/azure/storage/blobs/storage-https-custom-domain-cdn - -- The hub implementation is designed to be ran from a single Node.js instance. If the hub instance is sharded (e.g. replicated hubs via load balancing), then any given `bucket` (identified by URI segment) must be served by the same instance, At least a couple elements of the Gaia Hub depend on this: token invalidation in-memory caching, and resource endpoint 409 contention behavior. diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md b/i18n/vi/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md deleted file mode 100644 index 558cbb14f5..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Deploy Gaia Hub -description: Steps and tutorials ---- - -## Deploy your GAIA hub - -Tutorials to deploy your own GAIA hub are currently available for [Linux](./setup-linux), [MacOS](./setup-mac) and [Amazon EC2 / CloudFormation](./gaia-on-ec2). - -Regardless of what server the Gaia Hub runs on, the storage it uses can currently be deployed on multiple platforms: - -- Local disk (the server itself) -- Amazon S3 -- Azure Blob Storage -- Google Cloud - -:::tip -Support for IPFS is under development. -::: \ No newline at end of file diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md b/i18n/vi/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md deleted file mode 100644 index 2067e7d57c..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Amazon EC2 -description: Use a template to deploy a Gaia hub on Amazon EC2 -tags: - - tutorial - - gaia ---- - -## Introduction - -The template provided on this page provides an easy way to deploy a Gaia hub directly to Amazon EC2. You can use this template to deploy your own Gaia hub to your Amazon Web Services (AWS) account. Amazon EC2 is an affordable and convenient cloud computing provider. The template provides a one-click deploy for Amazon EC2 with either S3 or EBS as a storage provider. - -## Prerequisites - -This procedure uses Amazon CloudFormation to configure an EC2 cloud compute provider to run the Gaia hub service with an S3 or EBS provider for file storage. You should have access to an AWS account either through your personal account or through a corporate account. This account should have permissions to create resources. - -Additionally, you must also own a domain name and be able to update the DNS records associated with that domain name. - -## Setup steps - -### Step 1 - Create Stack - -Use a link in the table to launch the [CloudFormation](https://console.aws.amazon.com/cloudformation/) template in the AWS region that you wish to deploy a Gaia hub. - -![Create stack](/img/cloudformation-create-stack.png) - -### Step 2 - Setup stack using template - -You need to configure the template with the appropiate values for your hub and domain it runs on. - -Select `Template is ready` and `Amazon S3 URL` and enter the following Amazon S3 URL: -``` -https://s3-external-1.amazonaws.com/cf-templates-vzldibfi2mw8-us-east-1/2022160J6G-cloudformation.yaml -``` - -If you prefer you can instead select `Template is ready` and `Upload a template file` to upload the template file `cloudformation.yaml`. - -The latest `cloudformation.yaml` file can be downloaded [here](https://raw.githubusercontent.com/stacks-network/gaia/master/deploy/cloudformation.yaml). On most browsers you can right-click on that page and click on `Save page as` to download the file. Alternatively, you can copy/paste the text into a text file called `cloudformation.yaml`. - -Then click `Next`. - -![Specify template](/img/cloudformation-specify-template.png) - -### Step 3 - Specify stack details - -Specify the stack details and then click `Next`: ![Specify template](/img/cloudformation-specify-stack-details.png) - -| Field | Value | Notes | -| --------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Stack name | _a unique name in your AWS account_ | e.g.: my_gaia_hub | -| DomainName | _your-domain_ | | -| EmailAddress | _your email address_ | | -| GaiaBucketName | _S3 bucket name_ | The template combines this name with the stack name to create a unique S3 bucket. The template ignores this field if GaiaStorageType is set to `disk`. | -| GaiaStorageType | `s3` or `disk` | Select the GaiaStorageType of which to use as a backend for the Gaia Hub. Selecting `s3` causes the template to create an S3 bucket based on the name given in the previous field. Selecting `disk` causes the template to attach a separate EBS volume to the EC2 instance for Hub storage. | -| InstaceType | t2.micro | Select the instance type you want. Default value is `t2.micro`. | -| KeyName | | In the KeyName drop-down, select an [EC2 KeyPair](https://console.aws.amazon.com/ec2/v2/home?region=us-east-1#KeyPairs:) to enable SSH access to the EC2 instance. You should download the `.pem` keyfile for this pair from the EC2 console. For more information see the [EC2 key pair documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html#prepare-key-pair) | -| SSHLocation | 0.0.0.0/0 | Leave the SSHLocation field with the default value of `0.0.0.0/0` to enable SSH access from any IP address. If you wish to restrict SSH access to the EC2 instance to a certain IP, you can update this field. | -| SubnetId | _subnetid_ | Select a public subnet | -| VpcId | _vpcid_ | | - -### Step 4 - Configure stack options - -Configure any stack options that fit your desired setup and click `Next`. All these fields are optional. - -![Specify template](/img/cloudformation-stack-options.png) - -### Step 5 - Review - -Review the configuration of your Gaia hub, select the checkbox to acknowledge that AWS may create IAM resources with custom names and click on `Create stack`. - -![Specify template](/img/cloudformation-iam-resources.png) - -### Step 6 - Retrieve the public IP of your Gaia hub - -Your stack can take several minutes to launch. You can monitor the Events tab of your hub to review the current progress of the launch. When the launch is complete, the Outputs tab displays information about the hub. Select the PublicIP and copy it to configure your domain name. - -Create an `A` DNS record pointing to the given IP in your domain. - -Wait a few minutes for the DNS record to propagate, and your should be able to access your Gaia hub with SSH. - -## Accessing your Gaia hub with SSH - -To SSH into your Gaia hub EC2 host directly, you must have the keyfile used in container creation. Access the host with the following command in your terminal: - -```bash -ssh -i admin@ -``` - -:::tip If you can only access SSH with the IP but not with the DNS name and you wish to do so, you can optionally activate it by following these steps: - - Open your [AWS Console](https://console.aws.amazon.com) - Click on `Service` -> VPC - Open Your VPCs - Select your VPC connected to your Gaia Hub - Click `Actions` -> `Edit DNS Hostnames` -> Change `DNS hostnames` to `Enable` -::: -## Graphical representation of the cloudformation template - -![](/img/cloudformation-gaia-template1-designer.png) \ No newline at end of file diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/gaia/gaia.md b/i18n/vi/docusaurus-plugin-content-docs/current/gaia/gaia.md deleted file mode 100644 index 1070857350..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/gaia/gaia.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Gaia -description: Decentralized storage architecture for off-chain data -sidebar_position: 5 -tags: - - gaia ---- - -## Introduction - -Apps built with the Stacks blockchain store off-chain data using a storage system called Gaia. - -Whereas public transactional metadata is best stored on the Stacks blockchain, user application data can often be stored more efficiently and privately in Gaia storage. - -Storing data off of the blockchain ensures that Stacks applications can provide users with high performance and high availability for data reads and writes without introducing central trust parties. - -:::tip Latest whitepaper of GAIA (May 2022) is available [here](https://dev1-gaia-hub.s3.amazonaws.com/GAIA_Whitepaper.pdf) ::: - -## Understand Gaia in the Stacks architecture - -The following diagram depicts the Stacks architecture and Gaia's place in it: - -![Stacks Architecture](/img/architecture.png) - -Blockchains require consensus among large numbers of people, so they can be slow. Additionally, a blockchain is not designed to hold a lot of data. This means using a blockchain for every bit of data a user might write and store is expensive. For example, imagine if an application were storing every tweet in the chain. - -The Stacks blockchain addresses performance problems using a layered approach. The base layer consists of the Stacks blockchain and the Blockchain Naming System (BNS). The blockchain governs ownership of identities in the Stacks network. Identities can be names such as domain names, usernames, or application names. - -When an identity is created, its creation is recorded in the Stacks blockchain. Identities make up the primary data stored into the Stacks blockchain. These identities correspond to routing data in the OSI stack. The routing data is stored in the Atlas Peer Network, the second layer. Every core node that joins the Stacks Network is able to obtain an entire copy of this routing data. Stacks uses the routing data to associate identities (domain names, user names, and application names) with a particular storage location in the final layer, the Gaia Storage System. - -A Gaia Storage System consists of a _hub service_ and storage resource on a cloud software provider. The storage provider can be any commercial provider such as Azure, DigitalOcean, Amazon EC2, and so forth. Typically the compute resource and the storage resource reside same cloud vendor, though this is not a requirement. Gaia currently has driver support for S3, Azure Blob Storage, Google Cloud Platform and local disk, but the driver model allows for other backend support as well. - -Gaia stores data as a simple key-value store. When an identity is created, a corresponding data store is associated with that identity on Gaia. When a user logs into a dApp, the authentication process gives the application the URL of a Gaia hub, which then writes to storage on behalf of that user. - -The Stacks blockchain stores only identity data. Data created by the actions of an identity is stored in a Gaia Storage System. Each user has profile data. When a user interacts with a decentralized dApp that application stores application data on behalf of the user. Because Gaia stores user and application data off the blockchain, a Stacks DApp is typically more performant than DApps created on other blockchains. - -## User control or how is Gaia decentralized? - -A Gaia hub runs as a service which writes to data storage. The storage itself is a simple key-value store. The hub service writes to data storage by requiring a valid authentication token from a requestor. Typically, the hub service runs on a compute resource and the storage itself on separate, dedicated storage resource. Typically, both resources belong to the same cloud computing provider. - -![Gaiastorage](/img/gaia-storage.png) - -Gaia's approach to decentralization focuses on user control of data and its storage. Users can choose a Gaia hub provider. If a user can choose which Gaia hub provider to use, then that choice is all the decentralization required to enable user-controlled applications. Moreover, Gaia defines a uniform API for applications to access that data. - -The control of user data lies in the way that user data is accessed. When an application fetches a file `data.txt` for a given user `alice.id`, the lookup will follow these steps: - -1. Fetch the `zonefile` for `alice.id`. -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. Find the read-only url out of the profile's `appsMeta` section (e.g. `https://example-app.gaia.alice.org`). -6. Fetch the file from `https://example-app.gaia.alice.org/data.txt`. - -Because `alice.id` has access to her [zonefile](https://docs.stacks.co/references/bns-contract#name-update), 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. - -:::caution -Users with existing identities cannot yet migrate their data from one hub to another. -::: - -Applications writing directly on behalf of `alice.id` do not need to perform a lookup. Instead, the [Stacks authentication flow](https://stacks.js.org) provides Alice's chosen gaia hub URL to the application. This authentication flow _is also_ within Alice's control because Alice's wallet _must_ generate the authentication response. - -## Understand data storage - -A Gaia hub stores the written data _exactly_ as given. It offers minimal guarantees about the data. It does not ensure that data is validly formatted, contains valid signatures, or is encrypted. Rather, the design philosophy is that these concerns are client-side concerns. - -Client libraries (such as [`Stacks.js`](https://stacks.js.org/)) are capable of providing these guarantees. A liberal definition of the [end-to-end principle](https://en.wikipedia.org/wiki/End-to-end_principle) guides this design decision. - -When an application writes to a Gaia hub, an authentication token, key, and the data are passed to the Gaia hub. - -![Gaia writes](/img/gaia-writes.png) - -The token ensures the app has the authorization to write to the hub on the user's behalf. - -## Gaia versus other storage systems - -Here's how Gaia stacks up against other decentralized storage systems. Features that are common to all storage systems are omitted for brevity. - -| Features | [Gaia](https://github.com/stacks-network/gaia) | [Sia](https://sia.tech/) | [Storj](https://storj.io/) | [IPFS](https://ipfs.io/) | [DAT](https://datproject.org/) | [SSB](https://www.scuttlebutt.nz/) | -| ------------------------------------------ | ---------------------------------------------- | ------------------------ | -------------------------- | ------------------------ | ------------------------------ | ---------------------------------- | -| User controls where data is hosted | X | | | | | | -| Data can be viewed in a normal Web browser | X | | | X | | | -| Data is read/write | X | | | | X | X | -| Data can be deleted | X | | | | X | X | -| Data can be listed | X | X | X | | X | X | -| Deleted data space is reclaimed | X | X | X | X | | | -| Data lookups have predictable performance | X | | X | | | | -| Writes permission can be delegated | X | | | | | | -| Listing permission can be delegated | X | | | | | | -| Supports multiple backends natively | X | | X | | | | -| Data is globally addressable | X | X | X | X | X | | -| Needs a cryptocurrency to work | | X | X | | | | -| Data is content-addressed | | X | X | X | X | X | diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/gaia/setup-linux.md b/i18n/vi/docusaurus-plugin-content-docs/current/gaia/setup-linux.md deleted file mode 100644 index db427f890a..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/gaia/setup-linux.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: Linux -description: Steps to setup a GAIA hub on a Linux server (fresh install). This example is using Debian, but should work on any Linux distribution. It uses docker compose in the backgroud. -tags: - - tutorial - - gaia ---- - -This configuration will setup the following 4 docker containers: - -- Nginx with certbot on TCP ports 80 and 443. -- Gaia hub on TCP port 3000. -- Gaia admin on TCP port 8009. -- Gaia reader on TCP port 8008 - -**1. Update the system and install the dependencies and software we will use to test:** - -```bash -apt update && apt upgrade -y && apt install -y git vim gnupg jq -``` - -**2. Install [docker](https://docs.docker.com/engine/install/debian/) and [docker-compose](https://docs.docker.com/compose/cli-command/#install-on-linux)** in your OS. -For our example we install _docker_ with: - -```bash -curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg - -echo \ - "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian \ - $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null - -apt update && apt install -y docker-ce docker-ce-cli containerd.io -``` - -Install _docker-compose_ by downloading the [latest-release](https://github.com/docker/compose/releases): - -```bash -VERSION_DC=$(curl --silent https://api.github.com/repos/docker/compose/releases/latest | jq .name -r) -DESTINATION_DC=~/.docker/cli-plugins -mkdir -p ${DESTINATION_DC} -curl -SL https://github.com/docker/compose/releases/download/${VERSION_DC}/docker-compose-linux-x86_64 -o ${DESTINATION_DC}/docker-compose -chmod +x ${DESTINATION_DC}/docker-compose -``` - -**3. Clone the GAIA repository** and enter it's docker directory. - -```bash -git clone https://github.com/stacks-network/gaia.git && cd gaia/deploy/docker -``` - -**4. Copy and edit appropiate .env file**. -In the folder `./deploy/docker/` they are different sample files for different configurations like using aws, azure or disk among others. In this example we will store the data localy so we will copy the _disk_ file and update the domain and email fields. Please change `gaia.site.com` and `gaiarocks@mydomain.com` accordingly. Note you need both for the SSL certificate to be created correctly. - -```bash -export MYGAIADOMAIN=gaia.site.com -export MYGAIAEMAIL=gaiarocks@mydomain.com -cp sample-disk.env disk.env -sed -i 's/my-domain.com/'"$MYGAIADOMAIN"'/g' disk.env -sed -i 's/my-email@example.com/'"$MYGAIAEMAIL"'/g' disk.env - -``` - -**5. Start GAIA HUB service** - -To start GAIA HUB - -```bash -./gaiahub.sh start -``` - -To stop GAIA HUB - -```bash -./gaiahub.sh stop -``` - -To view GAIA HUB status - -```bash -./gaiahub.sh status -``` - -**6. Verify server works locally** with the following command: - -```bash -curl -sk http://localhost/hub_info | jq -``` - -A correct result should look similar to this: - -```bash - { - "challenge_text": "[\"gaiahub\",\"0\",\"gaia-0\",\"blockstack_storage_please_sign\"]", - "latest_auth_version": "v1", - "max_file_upload_size_megabytes": 20, - "read_url_prefix": "https://gaia.site.com/reader/" - } -``` - -**7. Test your GAIA HUB** Running `gaia_test.js` will test your GAIA Hub, by trying to connect to it, uploading a file and downloading it again. - -First install all required dependencies with: - -```bash -npm install -``` - -Then, from the root folder of the project type: - -```bash -node ./deploy/gaia_test.js https://yourgaiaurl -``` - -A correct result will be something like this: - -``` -Will run a test for the GAIA HUB: https://gaia.mydomain.com -Generating some test keys... -Private key: 5aacc60fc2a429e1f02be139f3cac82061c6a980******************** -Public key: 025691f17f2ab80dc4af363bb9c7aac59e9e1db6ae8ff668202582a3f4ec9678ff -Address: 15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS -[DEBUG] connectToGaiaHub: https://gaia.mydomain.com/hub_info -[DEBUG] uploadToGaiaHub: uploading testing.txt to https://gaia.mydomain.com -File uploaded successfully. -Upload to gaia hub thinks it can read it from: https://gaia.mydomain.com/reader/15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS/testing.txt -Hub info thinks it can read it from : https://gaia.mydomain.com/reader/15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS/testing.txt -Let's now try to fetch the uploaded file... -File fetched successfully. Contents of file: GAIA ROCKS! -``` diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/gaia/setup-mac.md b/i18n/vi/docusaurus-plugin-content-docs/current/gaia/setup-mac.md deleted file mode 100644 index 808833b212..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/gaia/setup-mac.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: MacOS -description: MacOS for local testing/development -tags: - - tutorial ---- - -The following assumes you have [Docker Installed](https://docs.docker.com/docker-for-mac/install/) - -- Recommended to also have [MacOS Homebrew](https://docs.brew.sh/Installation) installed -- Use Homebrew to install jq with `brew install jq` - -In your working directory: - -**1. Clone a copy of the [gaia repo](https://github.com/stacks-network/gaia):** - -```bash -$ git clone -b master --single-branch https://github.com/stacks-network/gaia -``` - -**2. Change your cwd:** - -```bash -$ cd gaia/deploy/docker -``` - -**3. Create a copy of sample-disk.env and fill out the values:** - -``` -$ cp sample-disk.env disk.env -# Update the DOMAIN_NAME variable to `localhost` -``` - -**4. Start the server:** - -``` -$ docker-compose -f docker-compose-base.yaml -f docker-compose-disk.yaml --env-file disk.env up -``` - -**5. Verify the server is responding locally:** - -``` -$ curl -sk https://localhost/hub_info | jq - { - "challenge_text": "[\"gaiahub\",\"0\",\"gaia-0\",\"blockstack_storage_please_sign\"]", - "latest_auth_version": "v1", - "max_file_upload_size_megabytes": 20, - "read_url_prefix": "https://localhost/reader/" - } -``` - -### Modifying the configuration for your gaia-hub - -Two methods exist: - -1. Edit the `gaia/deploy/configs/gaia/hub-config.json` using `vim` or other - -- requires a restart of the containers: `docker-compose -f docker-compose-base.yaml -f docker-compose-disk.yaml --env-file disk.env restart` - -2. Use the running `admin` container to modify any config values, and also reload the hub when complete: - -- [GitHub - Gaia Admin README.md](https://github.com/stacks-network/gaia/blob/master/admin/README.md) - -``` -$ export API_KEY="hello" -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - -H 'Content-Type: application/json' \ - -X POST \ - --data-raw '{"serverName": "myserver"}' \ - http://localhost:8009/v1/admin/config - -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - -X POST \ - http://localhost:8009/v1/admin/reload - -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - http://localhost:8009/v1/admin/config | jq -``` diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/governance/_index.md b/i18n/vi/docusaurus-plugin-content-docs/current/governance/_index.md deleted file mode 100644 index 1ecdf67871..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/governance/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Governance -description: Governance -sidebar_position: 9 ---- - -This page needs contributions. Help us write it! \ No newline at end of file diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/governance/index.md b/i18n/vi/docusaurus-plugin-content-docs/current/governance/index.md deleted file mode 100644 index 91b0215b5f..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/governance/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Governance -description: Governance -sidebar_position: 9 ---- - -![](/img/stacks-governance.png) - -This page needs contributions. Help us write it! - -Governance in web3 is driven by the community. - -How can I get involved ? - -[Governance Resources website](https://resources.stacksgov.com) - -[Github - Stack Community Governance](https://github.com/stacksgov) - -:::tip Community Calls Monthly community calls are recorded and available [here](https://www.youtube.com/playlist?list=PLg717Ri_rTnwwYjQYlc7rIP6x2FaTNn7f) ::: diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/governance/sips.md b/i18n/vi/docusaurus-plugin-content-docs/current/governance/sips.md deleted file mode 100644 index 29ac1ae1ed..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/governance/sips.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: SIPs -description: SIPs -sidebar_position: 9 ---- - -## Stacks Improvement Proposals (SIPs) - -Stacks improvement proposals (SIPs) are aimed at describing the implementation of the Stacks blockchain, as well as proposing improvements. - -The SIP process [(SIP-000)](https://github.com/stacksgov/sips/blob/main/sips/sip-000/sip-000-stacks-improvement-proposal-process.md) describes how to make a SIP and get it ratified. - -They should contain concise technical specifications of features or standards and the rationale behind it. SIPs are intended to be the primary medium for proposing new features, for collecting community input on a system-wide issue, and for documenting design decisions. - -The SIPs are located in the [stacksgov/sips](https://github.com/stacksgov/sips) repository as part of the [Stacks Community Governance organization](https://github.com/stacksgov). - -Anyone in the Stacks community can submit a SIP. - -:::tip Stacks Improvement Proposals Community Calls SIP Meeting calls are recorded and available [here](https://www.youtube.com/playlist?list=PLg717Ri_rTnx5kuaWqp3cUAtwQk_yzslT) - -More details of the meetings are available [here](https://github.com/stacksgov/sips/issues/79) ::: - -## Ratified SIPSs - -- [x] [SIP 001: Burn Election](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md) -- [x] [SIP 002: Clarity, a language for predictable smart contracts](https://github.com/stacksgov/sips/blob/main/sips/sip-002/sip-002-smart-contract-language.md) -- [x] [SIP 003: Peer Network](https://github.com/stacksgov/sips/blob/main/sips/sip-003/sip-003-peer-network.md) -- [x] [SIP 004: Cryptographic Committment to Materialized Views](https://github.com/stacksgov/sips/blob/main/sips/sip-004/sip-004-materialized-view.md) -- [x] [SIP 005: Blocks, Transactions, and Accounts](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md) -- [x] [SIP 006: Clarity Execution Cost Assessment](https://github.com/stacksgov/sips/blob/main/sips/sip-006/sip-006-runtime-cost-assessment.md) -- [x] [SIP 007: Stacking Consensus](https://github.com/stacksgov/sips/blob/main/sips/sip-007/sip-007-stacking-consensus.md) -- [x] [SIP 008: Clarity Parsing and Analysis Cost Assessment](https://github.com/stacksgov/sips/blob/main/sips/sip-008/sip-008-analysis-cost-assessment.md) -- [x] [SIP 009: Standard Trait Definition for Non-Fungible Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-009/sip-009-nft-standard.md) -- [x] [SIP 010: Standard Trait Definition for Fungible Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-010/sip-010-fungible-token-standard.md) -- [x] [SIP 012: Burn Height Selection for a Network Upgrade to Introduce New Cost-Limits](https://github.com/stacksgov/sips/blob/main/sips/sip-012/sip-012-cost-limits-network-upgrade.md) -- [x] [SIP-016: Metadata for Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-016/sip-016-token-metadata.md) - -## How to Get Involved - -There are several ways you can get involved with the SIP process: - -* **Join the weekly SIP Meeting call** listed [here](https://community.stacks.org/events). - -* **SIP Editor**. SIP editors help SIP authors make sure their SIPs are well-formed and follow the right process. They help get SIPs ready for deep review by advancing it them from Draft to Accepted status. If you want to become a SIP editor, open an issue with your name and email to ask to be added to the list of SIP editors. - -* **Join a CAB** (Consideration Advisory Board). SIPs fall under the purview of one or more considerations. A full list is in [this github](https://github.com/stacksgov/sips/tree/main/considerations) directory. Currently they are: Diversity, Economics, Ethics, Governance and Technical. Members of SIP consideration advisory boards use their domain expertise to give Accepted SIPs a deep read, and give the authors any/all feedback to help make the SIP workable. If you want to join a board, reach out to the board's chairperson via the listed contact information. - -* **Steering Committee**. The Steering Committee organizes the consideration advisory boards and votes to advance Recommended SIPs to Activation-in-Progress status, and then to either Ratified or Rejected status. Once they are in the process of being activated, they use a SIP's Activation section to determine whether or not the Stacks ecosystem has ratified or rejected the SIP. Joining this committee requires the consent of the Stacks Foundation board. diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/intro.md b/i18n/vi/docusaurus-plugin-content-docs/current/intro.md deleted file mode 100644 index 84f1eaa649..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/intro.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_label: "Home" -sidebar_position: 1 ---- - -# Stacks Docs Introduction - -Welcome to the community driven official Stacks Documentation. - -Learn about Stacks mining, the STX token, and the Clarity smart contract language. - -![](/img/Bitcoinet-L_2.svg) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md b/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md deleted file mode 100644 index dd7194f504..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: Stacks on DigitalOcean -description: A guide to setup Stacks on DigitalOcean -sidebar_position: 4 -tags: - - tutorial ---- - -## Introduction - -This is a step by step guide to deploy the [Stacks Blockchain on DigitalOcean](https://marketplace.digitalocean.com/apps/stacks-blockchain). Code is hosted on this [Github repository](https://github.com/stacks-network/stacks-blockchain-docker). - -## Steps - -#### Step 1 - -Go to the [Stacks Blockchain page](https://marketplace.digitalocean.com/apps/stacks-blockchain) in DigitalOcean's marketplace. Click on `Create Stacks Blockchain Droplet`. - -#### Step 2 - -Choose a plan (it will only allow you to select a plan that meets the minimum requirements) and your prefered datacenter region. ![](/img/sh_digitalocean-choose-plan.png) - -#### Step 3 - -Enter a root password or enable SSH keys if your prefer. - -![](/img/sh_digitalocean-choose-authentication.png) - -#### Step 4 - -You can leave the rest of the options as they are and click on `Create Droplet` - -#### Step 5 - -You will need to wait a few seconds for the droplet to get created. Once created click on it to see more information. - -![](/img/sh_digitalocean-creating-droplet.png) - -![](/img/sh_digitalocean-created-droplet.png) - -### Step 6 - -Congratulations! You are now running the Stacks Blockchain. You can click on `Console` for a terminal window to open or login using SSH to the public IP you've been assigned to with user `root`. - -![](/img/sh_digitalocean-console-button.png) ![](/img/sh_digitalocean-console.png) - -## Getting started after deploying Stacks Blockchain - -Once droplet is launched, initial startup can take several minutes while BNS data is imported (this is a one time operation). - -To keep track of the progress, you can `ssh root@your_droplet_public_ipv4` to the host and run: `/opt/stacks-blockchain-docker/manage.sh -n mainnet -a logs`. - -Once the stacks blockchain starts to sync with peers, application ports will open and nginx port 80 will now start proxying requests. - -Use `http://your_droplet_public_ipv4` to access the data directly, with output being similar to: - -```json -{ - "server_version": "stacks-blockchain-api v3.0.3 (master:cd0c8aef)", - "status": "ready", - "chain_tip": { - "block_height": 16220, - "block_hash": "0x3123fba9c0de6b569573494cf83c1d5d198a66bfd5f48ef97949b6bf11ba13be", - "index_block_hash": "0xeec960fbbd6186b4ccac85ce12adba72be497d881f81e077305c90955b51a6ae" - } -} -``` - -All services are managed by a [systemd unit file](https://github.com/stacksfoundation/stacks-machine-images/blob/master/files/etc/systemd/system/stacks.service) that is set to start on boot. - -Manual control is also possible via the [manage.sh script](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/manage.sh) at `/opt/stacks-blockchain-docker/manage.sh` on the host. - -Full details on how to use the manage.sh script is [available here](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/README.md#quickstart). - -## API Creation - -In addition to creating a Droplet from the Stacks Blockchain 1-Click App via the control panel, you can also use the [DigitalOcean API](https://digitalocean.com/docs/api). - -As an example, to create a 4GB Stacks Blockchain Droplet in the SFO2 region, you can use the following curl command. You’ll need to either save your [API access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/) to an environment variable or substitute it into the command below. - -```bash -curl -X POST -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer '$TOKEN'' -d \ - '{"name":"choose_a_name","region":"sfo2","size":"s-2vcpu-4gb","image":"stacksfoundation-stacksblockchain"}' \ - "https://api.digitalocean.com/v2/droplets" -``` diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md b/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md deleted file mode 100644 index b6cbb9754a..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Nodes and Miners -description: Nodes and Miners -sidebar_position: 7 ---- - -Here are all the steps to run nodes and miners, both on mainnet and testnet. - -## What's a Stacks node? - -## What's a Stacks miner? diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md b/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md deleted file mode 100644 index 40397a51e0..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Miner costs and fees -description: Miner Cost and Fee Estimation -sidebar_position: 8 ---- - -## Configuring Cost and Fee Estimation - -Fee and cost estimators can be configured via the config section `[fee_estimation]`: - -``` -[fee_estimation] -cost_estimator = naive_pessimistic -fee_estimator = fuzzed_weighted_median_fee_rate -fee_rate_fuzzer_fraction = 0.1 -fee_rate_window_size = 5 -cost_metric = proportion_dot_product -log_error = true -enabled = true -``` - -Fee and cost estimators observe transactions on the network and use the observed costs of those transactions to build estimates for viable fee rates and expected execution costs for transactions. Estimators and metrics can be selected using the configuration fields above, though the default values are the only options currently. `log_error` controls whether or not the INFO logger will display information about the cost estimator accuracy as new costs are observed. Setting `enabled = false` turns off the cost estimators. Cost estimators are **not** consensus-critical components, but rather can be used by miners to rank transactions in the mempool or client to determine appropriate fee rates for transactions before broadcasting them. - -The `fuzzed_weighted_median_fee_rate` uses a median estimate from a window of the fees paid in the last `fee_rate_window_size` blocks. Estimates are then randomly "fuzzed" using uniform random fuzz of size up to `fee_rate_fuzzer_fraction` of the base estimate. diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md b/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md deleted file mode 100644 index 468a01df66..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md +++ /dev/null @@ -1,343 +0,0 @@ ---- -title: Mine mainnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 mainnet -sidebar_position: 5 -tags: - - tutorial ---- - -## Introduction - -Make sure you've followed the [run a node](run-a-node) procedure. Once completed it's only a few more steps to run a proof-of-burn miner on the mainnet. - -If you're interested in mining on the testnet, you can find instructions on how to do that [here](miner-testnet): - -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining): - -## Running bitcoind locally - -To participate as a miner on mainnet, you must have access to a mainnet bitcoin node. One way to accomplish this is to run bitcoind locally. [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements) - -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. - -Next, start bitcoind with the following configuration: - -```toml -server=1 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=1 -banscore=1 -bind=0.0.0.0:8333 -rpcbind=0.0.0.0:8332 -rpcport=8332 -``` - -Finally, start bitcoind as follows: - -```bash -bitcoind -conf=path/to/bitcoin.conf -``` - -It may take a few days for the node to synchronize with the Bitcoin mainnet. - -## Running a miner - -First, a keychain needs to be generated. With this keychain, we'll purchase some BTC from a crytpocurrency exchange, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. We'll use the `make_keychain` command. - -```bash -npx @stacks/cli make_keychain 2>/dev/null | json_pp > keychain.txt -``` - -After this runs, you should see some JSON in the new `keychain.txt` file that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -**Don't lose this information** - we'll need to use the `privateKey` field later on. - -The above BTC address will then need to be imported into the BTC network. - -```bash -bitcoin-cli -rpcport=8332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - - - -Once imported, we need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - - - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/mainnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `make_keychain` command. Replace the `seed` field with your private key. Save and close this configuration file. - -To run your miner, run this in the command line: - -```bash -stacks-node start --config=./testnet/stacks-node/conf/mainnet-miner-conf.toml -``` - -Your node should start. It will take some time to sync, and then your miner will be running. - -### Creating an optimized binary - -The steps above are great for trying to run a node temporarily. If you want to host a node on a server somewhere, you might want to generate an optimized binary. To do so, use the same configuration as above, but run: - -```bash -cd testnet/stacks-node -cargo build --release --bin stacks-node -``` - -The above code will compile an optimized binary. To use it, run: - -```bash -cd ../.. -./target/release/stacks-node start --config=./mainnet-miner-conf.toml -``` - -To read more about the technical details of mining on the Stacks 2.0 network, have a look at [the mining guide](../understand-stacks/mining). - -### Enable debug logging - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -STACKS_LOG_DEBUG=1 stacks-node mainnet -``` - -## Running a miner in Windows - -### Prerequisites - -Make sure are [running a node](run-a-node) and [running bitcoind locally](#running-bitcoind-locally) before starting this tutorial. - -### Generate keychain and get mainnet tokens in Windows - -To setup the miner, first we need to generate a keychain. With this keychain, we'll purchase some BTC from a crytpocurrency exchange, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. We'll use the `stx make-keychain` command. - -Generate a keychain: - -```bash -npm install --global @stacks/cli -stx make_keychain > cli_keychain.json -type cli_keychain.json -``` - -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -The above BTC address will then need to be imported into the BTC network. - -```bash -bitcoin-cli -rpcport=8332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - -Once imported, we need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Update configuration file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/mainnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Run the miner - -To start your miner, run this in the command line: - -```bash -stacks-node start --config=testnet/stacks-node/conf/mainnet-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](/img/windows-defender.png) - -Your node should start. It will take some time to sync, and then your miner will be running. - -### Enable debug logging in Windows - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=mainnet-miner-conf.toml -``` - -## Optional: Running with Docker - -Alternatively, you can run the mainnet node with Docker. - -:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: - -### Generate keychain and get tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null -``` - -We need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Update configuration file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/mainnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Start the miner - -:::info The ENV VARS `RUST_BACKTRACE` and `STACKS_LOG_DEBUG` are optional. If removed, debug logs will be disabled ::: - -```bash -docker run -d \ - --name stacks_miner \ - --rm \ - --network host \ - -e RUST_BACKTRACE="full" \ - -e STACKS_LOG_DEBUG="1" \ - -v "$(pwd)/testnet/stacks-node/conf/mainnet-miner-conf.toml:/src/stacks-node/mainnet-miner-conf.toml" \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain:latest \ -/bin/stacks-node start --config /src/stacks-node/mainnet-miner-conf.toml -``` - -You can review the node logs with this command: - -```bash -docker logs -f stacks_miner -``` - -## Optional: Running in Kubernetes with Helm - -In addition, you're also able to run a mainnet node in a Kubernetes cluster using the [stacks-blockchain Helm chart](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). - -Ensure you have the following prerequisites installed on your machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [minikube](https://minikube.sigs.k8s.io/docs/start/) (Only needed if standing up a local Kubernetes cluster) -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [helm](https://helm.sh/docs/intro/install/) - -### Generate keychain and get some tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null -``` - -We need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Install the chart and run the miner - -To install the chart with the release name `my-release` and run the node as a miner: - -```bash -minikube start # Only run this if standing up a local Kubernetes cluster -helm repo add blockstack https://charts.blockstack.xyz -helm install my-release blockstack/stacks-blockchain \ - --set config.node.miner=true \ - --set config.node.seed="replace-with-your-privateKey-from-generate-keychain-step" \ - --set config.burnchain.mode="mainnet" -``` - -You can review the node logs with this command: - -```bash -kubectl logs -l app.kubernetes.io/name=stacks-blockchain -``` - -For more information on the Helm chart and configuration options, please refer to the [chart's homepage](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md b/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md deleted file mode 100644 index b572df3ba2..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md +++ /dev/null @@ -1,336 +0,0 @@ ---- -title: Mine testnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 testnet -sidebar_position: 4 -tags: - - tutorial ---- - -## Introduction - -Make sure you've followed the [Run a node](run-a-node) procedure. Once completed it's only a few more steps to run a proof-of-burn miner on the testnet. - -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining). - -## Running bitcoind locally - -To participate as a miner on Testnet, you must have access to a testnet bitcoin node. One way to accomplish this is to run bitcoind locally. [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements) - -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. - -Next, start bitcoind with the following configuration: - -```toml -server=1 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password -testnet=1 -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=1 -banscore=1 - -[test] -bind=0.0.0.0:18333 -rpcbind=0.0.0.0:18332 -rpcport=18332 -``` - -Finally, start bitcoind as follows: - -```bash -bitcoind -conf=path/to/bitcoin.conf -``` - -It may take a few hours for the node to synchronize with the Bitcoin testnet. - -## Running a miner - -First, a keychain needs to be generated. With this keychain, we'll get some testnet BTC from a faucet, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. We'll use the `make_keychain` command, and pass `-t` to indicate that we want a testnet keychain. - -```bash -npx @stacks/cli make_keychain -t 2>/dev/null | json_pp > keychain.txt -``` - -After this runs, you should see some JSON in the new `keychain.txt` file that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -**Don't lose this information** - we'll need to use the `privateKey` field later on. - -The above BTC address will then need to be imported into the BTC testnet network. - -```bash -bitcoin-cli -rpcport=18332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - -Once imported, we need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). You'll be sent `0.01` testnet BTC to that address. - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/testnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/testnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `make_keychain` command. Replace the `seed` field with your private key. Save and close this configuration file. - -To run your miner, run this in the command line: - -```bash -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. - -### Creating an optimized binary - -The steps above are great for trying to run a node temporarily. If you want to host a node on a server somewhere, you might want to generate an optimized binary. To do so, use the same configuration as above, but run: - -```bash -cd testnet/stacks-node -cargo build --release --bin stacks-node -``` - -The above code will compile an optimized binary. To use it, run: - -```bash -cd ../.. -./target/release/stacks-node start --config=./testnet/conf/testnet-follower-conf.toml -``` - -To read more about the technical details of mining on the Stacks 2.0 network, have a look at [the minig guide](../understand-stacks/mining): - -### Enable debug logging - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -STACKS_LOG_DEBUG=1 stacks-node testnet -``` - -## Running a miner in Windows - -### Prerequisites - -Make sure are [running a testnet node](run-a-node) before starting this tutorial. - -### Generate keychain and get testnet tokens in Windows - -To setup the miner, first, we need to generate a keychain. With this keychain, we'll get some testnet BTC from a faucet, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. We'll use the `stx make-keychain` command, and pass `-t` to indicate that we want a testnet keychain. - -Generate a keychain: - -```bash -npm install --global @stacks/cli -stx make_keychain -t > cli_keychain.json -type cli_keychain.json -``` - -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -Request BTC from faucet: - -We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). You'll be sent 0.01 testnet BTC to that address. - -### Update configuration file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/testnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/testnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Run the miner - -To start your miner, run this in the command line: - -```bash -stacks-node start --config=testnet/stacks-node/conf/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](/img/windows-defender.png) - - - -Your node should start. It will take some time to sync, and then your miner will be running. - -### Enable debug logging in Windows - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: - -```bash -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=testnet-miner-conf.toml -``` - -## Optional: Running with Docker - -Alternatively, you can run the testnet node with Docker. - -:::warning Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: - -### Generate keychain and get testnet tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` - -We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). You'll be sent 0.01 testnet BTC to that address. - -### Update config file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/testnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/testnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. - -### Start the miner - -:::info The ENV VARS `RUST_BACKTRACE` and `STACKS_LOG_DEBUG` are optional. If removed, debug logs will be disabled ::: - -```bash -docker run -d \ - --name stacks_miner \ - --rm \ - --network host \ - -e RUST_BACKTRACE="full" \ - -e STACKS_LOG_DEBUG="1" \ - -v "$(pwd))/testnet/stacks-node/conf/testnet-miner-conf.toml:/src/stacks-node/testnet-miner-conf.toml" \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain:latest \ -/bin/stacks-node start --config /src/stacks-node/testnet-miner-conf.toml -``` - -You can review the node logs with this command: - -```bash -docker logs -f stacks_miner -``` - -## Optional: Running in Kubernetes with Helm - -In addition, you're also able to run a testnet node in a Kubernetes cluster using the [stacks-blockchain Helm chart](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). - -Ensure you have the following prerequisites installed on your machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [minikube](https://minikube.sigs.k8s.io/docs/start/) (Only needed if standing up a local Kubernetes cluster) -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [helm](https://helm.sh/docs/intro/install/) - -### Generate keychain and get some testnet tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` - -We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). You'll be sent 0.01 testnet BTC to that address. - -### Install the chart and run the miner - -To install the chart with the release name `my-release` and run the node as a miner: - -```bash -minikube start # Only run this if standing up a local Kubernetes cluster -helm repo add blockstack https://charts.blockstack.xyz -helm install my-release blockstack/stacks-blockchain \ - --set config.node.miner=true \ - --set config.node.seed="replace-with-your-privateKey-from-generate-keychain-step" -``` - -You can review the node logs with this command: - -```bash -kubectl logs -l app.kubernetes.io/name=stacks-blockchain -``` - -For more information on the Helm chart and configuration options, please refer to the [chart's homepage](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md b/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md deleted file mode 100644 index 94d938c5ca..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md +++ /dev/null @@ -1,351 +0,0 @@ ---- -title: Run a node -description: Set up and run a Stacks node -sidebar_position: 1 -tags: - - tutorial ---- - -## Stacks Blockchain with Docker - -Run your own Stacks Blockchain node easily with just few commands. - -This tutorial describes a simple and effective [quickstart](#quickstart) to run a Stacks node using public scripts hosted in [Stacks Blockchain repository](https://github.com/stacks-network/stacks-blockchain-docker). Valid for mainnet, testnet and mocknet. - -## **Quickstart** - -1. **Clone the stacks-blockchain-docker repository locally** - -```bash -git clone https://github.com/stacks-network/stacks-blockchain-docker && cd stacks-blockchain-docker -``` - -2. **Optionally, create/copy `.env` file**. If file `.env` doesn't exist when launched it will be created from `sample.env` automatically. - -```bash -cp sample.env .env -``` - -_You may also use a symlink as an alternative to copying: `ln -s sample.env .env`_ - -3. **Optionally, ensure all images are up to date** - -```bash -./manage.sh -n -a pull -``` - -4. **Start the Services** - -```bash -./manage.sh -n -a start -``` - -- With optional proxy: - -```bash -./manage.sh -n -a start -f proxy -``` - -- With optional bitcoin node: - -```bash -./manage.sh -n -a start -f bitcoin -``` - -5. **Stop the Services** - -```bash -./manage.sh -n -a stop -``` - -6. **Retrieve Service Logs** - -```bash -./manage.sh -n -a logs -``` - -- Export docker log files to `./exported-logs`: - -This will create one log file for every running service, for example: postgres.log, stacks-blockain.log, stacks-blockchain-api.log and bitcoin-core.log. -Notice that each time you run this command the log files will be overwritten. - -```bash -./manage.sh -n -a logs export -``` - -7. **Restart all services** - -```bash -./manage.sh -n -a restart -``` - -- With optional proxy: - -```bash -./manage.sh -n -a restart -f proxy -``` - -8. **Delete** all data in `./persistent-data/` and/or data of the Bitcoin blockchain. - - This data is owned by root, so you will need to run it with sudo privileges so it can delete the data. - -```bash -$ sudo ./manage.sh -n -a reset - -Please confirm what persistent data you wish to delete: - -0. Cancel -1. Delete Persistent data for Stacks testnet only and leave Bitcoin blockchain data unaffected. -2. Delete Persistent data for Stacks testnet and Bitcoin blockchain data in ./persistent-data/blockchain-bitcoin -3. Delete Persistent data for Bitcoin blockchain data in ./persistent-data/blockchain-bitcoin only. -Please note that BNS data will never get deleted. - -Type 0, 1, 2 or 3: 2 - -Ok. Delete Stacks and Bitcoin data. -[ Success ] Persistent data deleted for Bitcoin blockchain. -[ Success ] Persistent data deleted for Stacks testnet. - -``` - -9. **Download BNS data to** `./persistent-data/bns-data` - -```bash -./manage.sh bns -``` - -10. **Export stacks-blockchain-api events** (_Not applicable for mocknet_) - -```bash -./manage.sh -n -a export -# check logs for completion -./manage.sh -n -a restart -``` - -11. **Replay stacks-blockchain-api events** (_Not applicable for mocknet_) - -```bash -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart -``` - -## **Running also a bitcoin node (Optional)** - -Stacks needs to use a Bitcoin node, and by default when you run a Stacks node you will be using a public Bitcoin node, which is configured in the `.env` file. Default values is `BITCOIN_NODE=bitcoin.mainnet.stacks.org`. - -However, you can optionaly run both nodes together and configured in a way that you Stacks node will use your own Bitcoin node instead of a public one. - -If you run the script with a bitcoin node it will download and build it directly from source for increased security. This process which only needs to happen once can take up to 20-30 minutes depending on the speed of your system. Also, once the bitcoin node is up and running it will need an additional time for sync for the first time (can be hours for testnet and days for mainnet). - -### Why run Stacks node with your own Bitcoin node? - -Because running your own Bitcoin node will give you higher security and improved perfomance. - -* **Improved perfomance**: The Bitcoin node will serve you blocks faster, as well as UTXOs for your miner (if you run one). -* **Higher security**: The Bitcoin node will also have validated all bitcoin transactions the Stacks node consumes. If you don't run your own Bitcoin node, you're relying on the SPV headers to vouch for the validity of Bitcoin blocks. - -The disadvantage of running your own Bitcoin node is that you need the extra space to store the Bitcoin blockchain (about 500GB) and the initial time it will take to download this data the first time. - -### Example - -You can run easily run your Stacks node with your own Bitcoin node by adding the flag `bitcoin`. This is available only for testnet and mainnet. - -Example: `./manage.sh -n mainnet -a start -f bitcoin` or `./manage.sh -n testnet -a start -f bitcoin` - -### Bitcoin node configuration - -In the `.env` file there is the variable `BITCOIN_BLOCKCHAIN_FOLDER`. As the bitcoin blockchain can be large (over 500GB) you optionally change this variable to any location of your choosing. If you have previously used the [bitcoin core application](https://bitcoin.org/en/bitcoin-core/) and already have the bitcoin blockchain synced, you can use the same data folder and avoid redownloading the entire bitcoin blockchain. - -## **Accessing the services** - -:::tip For networks other than `mocknet`, downloading the initial headers can take several minutes. Until the headers are downloaded, the `/v2/info` endpoints won't return any data. - -Use the command `./manage.sh -n -a logs` to check the sync progress. ::: - -**stacks-blockchain**: - -- Ports `20443-20444` are exposed to `localhost` - -```bash -curl -sL localhost:20443/v2/info | jq -``` - -**stacks-blockchain-api**: - -- Port `3999` are exposed to `localhost` - -```bash -curl -sL localhost:3999/v2/info | jq -``` - -**proxy**: - -- Port `80` is exposed to `localhost` - -```bash -curl -sL localhost/v2/info | jq -curl -sL localhost/ | jq -``` - ---- - -## Upgrades - -⚠️ For upgrades to running instances of this repo, you'll need to [run the event-replay](https://github.com/hirosystems/stacks-blockchain-api#event-replay): - -```bash -./manage.sh -n -a stop -./manage.sh -n -a export -./manage.sh -n -a import -./manage.sh -n -a restart -``` - ---- - -## **Workarounds to potential issues** - -_**Port(s) already in use**_: - -- 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. `3999` and edit your `.env` file to use the new port. - -```bash -netstat -anl | grep 3999 -``` - -``` -tcp46 0 0 *.3999 *.* LISTEN -``` - -_**Containers not starting (hanging on start)**_: - -- Occasionally, docker can get **stuck** and not allow new containers to start. If this happens, simply restart your docker daemon and try again. - -_**Database Issues**_: - -- For any of the various Postgres/sync issues, it may be easier to simply remove the persistent data dir. Note that doing so will result in a longer startup time as the data is repopulated. - -```bash -./manage.sh -n -a stop -./manage.sh -n -a reset -./manage.sh -n -a start -``` - -_**API Missing Parent Block Error**_: - -- If the Stacks blockchain is no longer syncing blocks, and the API reports an error similar to this:\ - `Error processing core node block message DB does not contain a parent block at height 1970 with index_hash 0x3367f1abe0ee35b10e77fbcaa00d3ca452355478068a0662ec492bb30ee0f13e"`,\ - The API (and by extension the DB) is out of sync with the blockchain. \ - The only known method to recover is to resync from genesis (**event-replay _may_ work, but in all likelihood will restore data to the same broken state**). - -- To attempt the event-replay - -```bash -./manage.sh -n -a stop -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart -``` - -- To wipe data and re-sync from genesis - -```bash -./manage.sh -n -a stop -./manage.sh -n -a reset -./manage.sh -n -a restart -``` - - -## **Requirements:** - -- [Docker](https://docs.docker.com/get-docker/) >= `17.09` -- [docker-compose](https://github.com/docker/compose/releases/) >= `1.27.4` -- [git](https://git-scm.com/downloads) -- [jq binary](https://stedolan.github.io/jq/download/) -- [sed](https://www.gnu.org/software/sed/) -- Machine with (at a minimum): - - 4GB memory - - 1 Vcpu - - 50GB storage (600GB if you optionally also run the bitcoin mainnet node) - -:::caution MacOS with an M1 processor is NOT recommended - -The way Docker for Mac on an Arm chip is designed makes the I/O incredibly slow, and blockchains are **_very_** heavy on I/O. This only seems to affect MacOS, other Arm based systems like Raspberry Pi's seem to work fine. - -::: - - -### Install/Update docker-compose - -:::note `docker-compose` executable is required, even though recent versions of Docker contain `compose` natively ::: - -- [Install Docker-compose](https://docs.docker.com/compose/install/) -- [Docker Desktop for Mac](https://docs.docker.com/docker-for-mac/install/) -- [Docker Desktop for Windows](https://docs.docker.com/docker-for-windows/install/) -- [Docker Engine for Linux](https://docs.docker.com/engine/install/#server) - -First, check if you have `docker-compose` installed locally. - -To do that, run this command in your terminal : - -```bash -docker-compose --version -``` - -Output should look something very similar to this : - -``` -docker-compose version 1.27.4, build 40524192 -``` - -If the command is not found, or the version is < `1.27.4`, run the following to install the latest to `/usr/local/bin/docker-compose`: - -```bash -#You will need to have jq installed, or this snippet won't run. -VERSION=$(curl --silent https://api.github.com/repos/docker/compose/releases/latest | jq .name -r) -DESTINATION=/usr/local/bin/docker-compose -sudo curl -L https://github.com/docker/compose/releases/download/${VERSION}/docker-compose-$(uname -s)-$(uname -m) -o $DESTINATION -sudo chmod 755 $DESTINATION -``` - -### Security note on docker - -The Docker daemon always runs as the root user so by default you will need root privileges to interact with it. - -The script `manage.sh` uses docker, so to avoid the requirement of needing to run the script with root privileges it is prefered to be able to *manage Docker as a non-root user*, following [these simple tests](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user). - -This will avoid the need of running the script with root privileges for all operations except the removal of data. - -### Configuration files you can edit - -The following files can be modified to personalize your node configuration, but generally most of them should be left as-is. All these files will be created from the sample copy if they don't exist at runtime (for example `.env` is created from `sample.env`). However these files will never be modified by the application once created and will never be pushed back to github, so your changes will be safe. - -* `.env` -* `./conf/mainnet/Config.toml` -* `./conf/mainnet/bitcoin.conf` -* `./conf/testnet/Config.toml` -* `./conf/testnet/bitcoin.conf` - -By default: - -- BNS data is **not** enabled/imported - - To enable, uncomment `# BNS_IMPORT_DIR=/bns-data` in `./env` - - Download BNS data: `./manage.sh bns` -- Fungible token metadata is **not** enabled - - To enable, uncomment `# STACKS_API_ENABLE_FT_METADATA=1` in `./env` -- Non-Fungible token metadata is **not** enabled - - To enable, uncomment `# STACKS_API_ENABLE_NFT_METADATA=1` in `./env` -- Verbose logging is **not** enabled - - To enable, uncomment `# VERBOSE=true` in `./env` -- Bitcoin blockchain folder is configured in `BITCOIN_BLOCKCHAIN_FOLDER` in `./env` - -### Local Data Dirs - -Directories will be created on first start that will store persistent data under `./persistent-data/` - -`` can be 1 of: - -- mainnet -- testnet -- mocknet diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md b/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md deleted file mode 100644 index 09db354d0d..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md +++ /dev/null @@ -1,188 +0,0 @@ ---- -title: Running a mainnet node -description: Set up and run a mainnet node with Docker -sidebar_position: 3 -tags: - - tutorial ---- - -## Introduction - -This procedure demonstrates how to run a local mainnet node using Docker images. - -:::caution -This procedure focuses on Unix-like operating systems (Linux and MacOS). This procedure has not been tested on Windows. -::: - -## Prerequisites - -Running a node has no specialized hardware requirements. Users have been successful in running nodes on Raspberry Pi boards and other system-on-chip architectures. In order to complete this procedure, you must have the following software installed on the node host machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [curl](https://curl.se/download.html) -- [jq](https://stedolan.github.io/jq/download/) - -### Firewall configuration - -In order for the API node services to work correctly, you must configure any network firewall rules to allow traffic on the ports discussed in this section. The details of network and firewall configuration are highly specific to your machine and network, so a detailed example isn't provided. - -The following ports must open on the host machine: - -Ingress: - -- stacks-blockchain (open to `0.0.0.0/0`): - - `20443 TCP` - - `20444 TCP` - -Egress: - -- `8332` -- `8333` -- `20443-20444` - -These egress ports are for syncing stacks-blockchain and Bitcoin headers. If they're not open, the sync will fail. - -## Step 1: initial setup - -In order to run the mainnet node, you must download the Docker images and create a directory structure to hold the persistent data from the services. Download and configure the Docker images with the following commands: - -```sh -docker pull blockstack/stacks-blockchain -``` - -Create a directory structure for the service data with the following command: - -```sh -mkdir -p ./stacks-node/{persistent-data/stacks-blockchain/mainnet,config/mainnet} && cd stacks-node -``` - -## Step 2: running Stacks blockchain - -First, create the `./config/mainnet/Config.toml` file and add the following content to the file using a text editor: - -```toml -[node] -working_dir = "/root/stacks-node/data" -rpc_bind = "0.0.0.0:20443" -p2p_bind = "0.0.0.0:20444" -bootstrap_node = "02da7a464ac770ae8337a343670778b93410f2f3fef6bea98dd1c3e9224459d36b@seed-0.mainnet.stacks.co:20444,02afeae522aab5f8c99a00ddf75fbcb4a641e052dd48836408d9cf437344b63516@seed-1.mainnet.stacks.co:20444,03652212ea76be0ed4cd83a25c06e57819993029a7b9999f7d63c36340b34a4e62@seed-2.mainnet.stacks.co:20444" -wait_time_for_microblocks = 10000 - -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "bitcoin.blockstack.com" -username = "blockstack" -password = "blockstacksystem" -rpc_port = 8332 -peer_port = 8333 - -[connection_options] -read_only_call_limit_write_length = 0 -read_only_call_limit_read_length = 100000 -read_only_call_limit_write_count = 0 -read_only_call_limit_read_count = 30 -read_only_call_limit_runtime = 1000000000 -``` - -Start the `stacks-blockchain` container with the following command: - -```sh -docker run -d --rm \ - --name stacks-blockchain \ - -v $(pwd)/persistent-data/stacks-blockchain/mainnet:/root/stacks-node/data \ - -v $(pwd)/config/mainnet:/src/stacks-node \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain \ -/bin/stacks-node start --config /src/stacks-node/Config.toml -``` - -You can verify the running `stacks-blockchain` container with the command: - -```sh -docker ps --filter name=stacks-blockchain -``` - -## Step 3: verifying the services - -:::note -The initial burnchain header sync can take several minutes, until this is done the following commands will not work -::: - -To verify the `stacks-blockchain` burnchain header sync progress: - -```sh -docker logs stacks-blockchain -``` - -The output should be similar to the following: - -``` -INFO [1626290705.886954] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.2% (8000 out of 691034) -INFO [1626290748.103291] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.4% (10000 out of 691034) -INFO [1626290776.956535] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.7% (12000 out of 691034) -``` - -To verify the `stacks-blockchain` tip height is progressing use the following command: - -```sh -curl -sL localhost:20443/v2/info | jq -``` - -If the instance is running you should recieve terminal output similar to the following: - -```json -{ - "peer_version": 402653184, - "pox_consensus": "89d752034e73ed10d3b97e6bcf3cff53367b4166", - "burn_block_height": 666143, - "stable_pox_consensus": "707f26d9d0d1b4c62881a093c99f9232bc74e744", - "stable_burn_block_height": 666136, - "server_version": "stacks-node 2.0.11.1.0-rc1 (master:67dccdf, release build, linux [x86_64])", - "network_id": 1, - "parent_network_id": 3652501241, - "stacks_tip_height": 61, - "stacks_tip": "e08b2fe3dce36fd6d015c2a839c8eb0885cbe29119c1e2a581f75bc5814bce6f", - "stacks_tip_consensus_hash": "ad9f4cb6155a5b4f5dcb719d0f6bee043038bc63", - "genesis_chainstate_hash": "74237aa39aa50a83de11a4f53e9d3bb7d43461d1de9873f402e5453ae60bc59b", - "unanchored_tip": "74d172df8f8934b468c5b0af2efdefe938e9848772d69bcaeffcfe1d6c6ef041", - "unanchored_seq": 0, - "exit_at_block_height": null -} -``` - -## Stopping the mainnet node - -Use the following commands to stop the local mainnet node: - -```sh -docker stop stacks-blockchain -``` - -## Optional. Run stacks node with own bitcoin node - -It's encouraged to use your own bitcoin node when possible. - -To do this simply update the `stacks-node/config/mainnet/Config.toml` file with the details of your bitcoin node. For example: - -``` -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "localhost" -username = "rpc username" -password = "rpc password" -rpc_port = 8332 -peer_port = 8333 -``` - -The rpc configuration of your bitcoin node is out of the scope of this document, but you can find more information on how to set it up [here](https://developer.bitcoin.org/examples/intro.html). - -## Additional reading - - - -- [Running a Stacks API node](https://docs.hiro.so/get-started/running-api-node) -- [Running a Stacks testnet node](running-testnet-node) - diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md b/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md deleted file mode 100644 index da01ce2ea1..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: Running a testnet node -description: Set up and run a testnet node with Docker -sidebar_position: 2 -tags: - - tutorial ---- - -## Introduction - -This procedure demonstrates how to run a local testnet node using Docker images. - -:::caution -This procedure focuses on Unix-like operating systems (Linux and MacOS). This procedure has not been tested on Windows. -::: - -## Prerequisites - -Running a node has no specialized hardware requirements. Users have been successful in running nodes on Raspberry Pi boards and other system-on-chip architectures. In order to complete this procedure, you must have the following software installed on the node host machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [curl](https://curl.se/download.html) -- [jq](https://stedolan.github.io/jq/download/) - -### Firewall configuration - -In order for the API node services to work correctly, you must configure any network firewall rules to allow traffic on the ports discussed in this section. The details of network and firewall configuration are highly specific to your machine and network, so a detailed example isn't provided. - -The following ports must open on the host machine: - -Ingress: - -- stacks-blockchain (open to `0.0.0.0/0`): - - `20443 TCP` - - `20444 TCP` - -Egress: - -- `18332` -- `18333` -- `20443-20444` - -These egress ports are for syncing stacks-blockchain and Bitcoin headers. If they're not open, the sync will fail. - -## Step 1: initial setup - -In order to run the testnet node, you must download the Docker images and create a directory structure to hold the persistent data from the services. Download and configure the Docker images with the following commands: - -```sh -docker pull blockstack/stacks-blockchain -``` - -Create a directory structure for the service data with the following command: - -```sh -mkdir -p ./stacks-node/persistent-data/stacks-blockchain/testnet && cd stacks-node -``` - -## Step 2: running Stacks blockchain - -Start the stacks-blockchain container with the following command: - -```sh -docker run -d --rm \ - --name stacks-blockchain \ - -v $(pwd)/persistent-data/stacks-blockchain/testnet:/root/stacks-node/data \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain \ -/bin/stacks-node testnet -``` - -You can verify the running stacks-blockchain container with the command: - -```sh -docker ps --filter name=stacks-blockchain -``` - -## Step 3: verifying the services - -:::info -The initial burnchain header sync can take several minutes, until this is done the following commands will not work -::: - -To verify the stacks-blockchain burnchain header sync progress: - -```sh -docker logs stacks-blockchain -``` - -The output should be similar to the following: - -``` -INFO [1626290705.886954] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.2% (8000 out of 2034380) -INFO [1626290748.103291] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.4% (10000 out of 2034380) -INFO [1626290776.956535] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.7% (12000 out of 2034380) -``` - -To verify the stacks-blockchain tip height is progressing use the following command: - -```sh -curl -sL localhost:20443/v2/info | jq -``` - -If the instance is running you should recieve terminal output similar to the following: - -```json -{ - "peer_version": 4207599105, - "pox_consensus": "12f7fa85e5099755a00b7eaecded1aa27af61748", - "burn_block_height": 2034380, - "stable_pox_consensus": "5cc4e0403ff6a1a4bd17dae9600c7c13d0b10bdf", - "stable_burn_block_height": 2034373, - "server_version": "stacks-node 2.0.11.2.0-rc1 (develop:7b6d3ee+, release build, linux [x86_64])", - "network_id": 2147483648, - "parent_network_id": 118034699, - "stacks_tip_height": 509, - "stacks_tip": "e0ee952e9891709d196080ca638ad07e6146d4c362e6afe4bb46f42d5fe584e8", - "stacks_tip_consensus_hash": "12f7fa85e5099755a00b7eaecded1aa27af61748", - "genesis_chainstate_hash": "74237aa39aa50a83de11a4f53e9d3bb7d43461d1de9873f402e5453ae60bc59b", - "unanchored_tip": "32bc86590f11504f17904ee7f5cb05bcf71a68a35f0bb3bc2d31aca726090842", - "unanchored_seq": 0, - "exit_at_block_height": null -} -``` - -## Stopping the testnet node - -Use the following commands to stop the local testnet node: - -```sh -docker stop stacks-blockchain -``` - -## Additional reading - - - -- [Running a Stacks API node](https://docs.hiro.so/get-started/running-api-node) -- [Running a Stacks mainnet node](running-mainnet-node) - diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md b/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md deleted file mode 100644 index 89af343dc6..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md +++ /dev/null @@ -1,506 +0,0 @@ ---- -title: Stacks Node Configuration -description: Configuration parameters and options for the stacks-node binary -sidebar_position: 6 ---- - -## Usage - -```bash -stacks-node sub-command [--subcommand-option ] -``` - -## Subcommands - -:::caution The `stacks-node` binary may have deprecated commands that are not documented on this page. Deprecated commands may be accessible until they are fully removed from the sources. ::: - -### mocknet - -Start a node based on a fast local setup emulating a burnchain. Ideal for smart contract development. - -Example: - -```bash -stacks-node mocknet -``` - -### krypton - -Start a node that will join and stream blocks from the public krypton regtest, powered by Blockstack via [Proof of Transfer](../understand-stacks#consensus-mechanism). - -Example: - -```bash -stacks-node krypton -``` - -### testnet - -Start a node that will join and stream blocks from the public testnet. - -Example: - -```bash -stacks-node testnet -``` - -### mainnet - -Start a node that joins and streams blocks from the public mainnet. - -Example: - -```bash -stacks-node mainnet -``` - -### start - -Start a node with a config of your own. Can be used for joining a network, starting a new chain, or replacing default values used by the `mocknet` or `testnet` subcommands. - -#### Arguments - -**--config**: relative or absolute path to the TOML config file. Required. - -Example: - -```bash -stacks-node start --config=/path/to/config.toml -``` - -See [Configuration File Options](#configuration-file-options) for more information. - -#### version - -Displays information about the current version and the release cycle. - -Example: - -```bash -stacks-node version -``` - -#### help - -Displays a help message. - -Example: - -```bash -stacks-node help -``` - -## Configuration File Options - -The TOML configuration file has multiple sections under which an option may be placed. - -To see a list of example configurations, [please see this page](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf). - -### Section: node - -Contains various configuration options pertaining to the stacks-node. - -Example: - -```toml -[node] -rpc_bind = "0.0.0.0:20443" -p2p_bind = "0.0.0.0:20444" -# Enter your private key here -seed = "replace-with-your-private-key" -miner = true -``` - -#### working_dir (optional) - -Absolute path to the directory which the stacks-node will use for storing various data. - -Example: - -```toml -working_dir = "/root/stacks-node" -``` - -#### rpc_bind - -Address and port stacks-node should bind to for RPC connections. - -Example: - -```toml -rpc_bind = "0.0.0.0:20443" -``` - -#### p2p_bind - -Address and port stacks-node should bind to for P2P connections. - -Example: - -```toml -p2p_bind = "0.0.0.0:20444" -``` - -#### data_url (optional) - -Address and port from which the stacks-node will be receiving incoming rpc connections. - -Example: - -```toml -data_url = "1.2.3.4:20443" -``` - -#### p2p_address (optional) - -Address and port from which the stacks-node will be receiving incoming p2p connections. - -Example: - -```toml -p2p_address = "1.2.3.4:20444" -``` - -#### bootstrap_node (optional) - -Public key, address, and port stacks-node should use to pull transaction data from when starting. - -Example: - -```toml -bootstrap_node = "047435c194e9b01b3d7f7a2802d6684a3af68d05bbf4ec8f17021980d777691f1d51651f7f1d566532c804da506c117bbf79ad62eea81213ba58f8808b4d9504ad@testnet.blockstack.org:20444" -``` - -#### wait_time_for_microblocks (optional) - -The amount of time (in milliseconds) that a node will wait before trying to mine a block, after catching up to the anchored chain tip. This gives the current leader time to broadcast microblocks that will get included in that mined block. - -Example: - -```toml -wait_time_for_microblocks = 15000 -``` - -#### seed (optional) - -The private key to use for mining. Only needed if `miner` is set to `true`. - -Example: - -```toml -seed = "replace-with-your-private-key" -``` - -#### local_peer_seed (optional) - -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. - -Example: - -```toml -local_peer_seed = "replace-with-your-private-key" -``` - -#### miner (optional) - -Determines whether the stacks-node is running a follower (`false`) or a miner (`true`). Defaults to `false` if omitted. - -Example: - -```toml -miner = true -``` - -#### mine_microblocks (optional) - -Determines whether the stacks-node will mine microblocks. Will only take effect if `miner` is set to `true`. - -Example: - -```toml -mine_microblocks = true -``` - -#### prometheus_bind (optional) - -Address and port stacks-node should open for Prometheus metrics collection. - -Example: - -```toml -prometheus_bind = "0.0.0.0:9153" -``` - -### Section: events_observer (optional) - -Contains options for watching events emitted by a local [stacks-blockchain-api](https://github.com/hirosystems/stacks-blockchain-api) service. - -:::info -This section can be repeated multiple times. -::: - -Example: - -```toml -[[events_observer]] -endpoint = "address-to-my-local.stacks-node-api.com:3700" -retry_count = 255 -events_keys = ["*"] -``` - -#### endpoint - -Address and port to a stacks-node-api to watch for events. - -Example: - -```toml -endpoint = "address-to-my-local.stacks-node-api.com:3700" -``` - -#### retry_count - -Number of times to retry sending events to the endpoint before failing. - -Example: - -```toml -retry_count = 255 -``` - -#### events_keys - -Event keys for which to watch. The emitted node events can be restricted by account, function name and event type. Asterix ("\*") can be used to emit all events. - -Examples: - -```toml -events_keys = ["*"] -``` - -```toml -events_keys = [ - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.store::print", - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.contract.ft-token", - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.contract.nft-token", - "stx" -] -``` - -### Section: connection_options (optional) - -Specifies configuration options for others connecting to the stacks node. - -Example: - -```toml -[connection_options] -public_ip_address = "1.2.3.4:20444" -download_interval = 60 -walk_interval = 30 -``` - -#### public_ip_address - -The advertised public IP of this stacks-node. - -Example: - -```toml -public_ip_address = "1.2.3.4:20444" -``` - -#### download_interval - -Time (in seconds) between attempts to download blocks. - -Example: - -```toml -download_interval = 60 -``` - -#### walk_interval - -Time (in seconds) between attempts to walk the neighborhood. - -Example: - -```toml -walk_interval = 30 -``` - -#### read_only_call_limit_read_length - -Total number of bytes allowed to be read by an individual read-only function call. - -Example: - -```toml -read_only_call_limit_read_length = 100000 -``` - -#### read_only_call_limit_read_count - -Total number of independent read operations permitted for an individual read-only function call. - -Example: - -```toml -read_only_call_limit_read_count = 30 -``` - -#### read_only_call_limit_runtime - -[Runtime cost](https://github.com/stacksgov/sips/blob/2d3fd9bf8da7a04f588d90ff6252173d7609d7bf/sips/sip-006/sip-006-runtime-cost-assessment.md#introduction) limit for an individual read-only function call. - -Example: - -```toml -read_only_call_limit_runtime = 1000000000 -``` - -### Section: burnchain - -This section contains configuration options pertaining to the blockchain the stacks-node binds to on the backend for proof-of-transfer (BTC). - -Example: - -```toml -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "your.bitcoind.node.org" -rpc_port = 8332 -peer_port = 8333 -``` - -#### chain - -The blockchain stacks-node binds to on the backend for proof-of-transfer. Only value supported: `"bitcoin"`. - -Example: - -```toml -chain = "bitcoin" -``` - -#### mode - -The profile or test phase of which to run stacks-node. Valid values are `"mocknet"`, `"helium"`, `"neon"`, `"argon"`, `"krypton"`, `"xenon"`. - -Example: - -```toml -mode = "xenon" -``` - -#### peer_host - -Domain name of the host running the backend Bitcoin blockchain. It's required to either run a personal Bitcoin node locally, or to use a publicly hosted Bitcoin node. - -Example: - -```toml -peer_host = "your.bitcoind.node.org" -``` - -#### rpc_port - -peer_host's port stacks-node will connect to for RPC connections. - -Example: - -```toml -rpc_port = 8332 -``` - -#### peer_port - -peer_host's port stacks-node will connect to for P2P connections. - -Example: - -```toml -peer_port = 8333 -``` - -#### burn_fee_cap (optional) - -Maximum amount (in Satoshis) of "burn commitment" to broadcast for the next block's leader election. - -Example: - -```toml -burn_fee_cap = 30000 -``` - -#### satoshis_per_byte (optional) - -Amount (in Satoshis) per [virtual byte](https://en.bitcoin.it/wiki/Weight_units). This is used to compute the transaction fees. - -Example: - -```toml -satoshis_per_byte = 50 -``` - -So total transaction cost would be `(estimated_tx_size * satoshis_per_byte) + burn_fee_cap`. - -#### commit_anchor_block_within (optional) - -Sets the time period (in milliseconds) for commitments. Only used when `mode` is set to `"helium"`. - -Example: - -```toml -commit_anchor_block_within = 10000 -``` - -### Section: ustx_balance (testnet/regtest only) - -This section contains configuration options pertaining to the genesis block allocation for an address in micro-STX. If a user changes these values, their node may be in conflict with other nodes on the network and find themselves unable to sync with other nodes. - -:::info -This section can repeat multiple times, and thus is in double-brackets. Each section can define only one address. This section is ignored if running a node on mainnet. -::: - -Example: - -```toml -[[ustx_balance]] -address = "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6" -amount = 10000000000000000 - -[[ustx_balance]] -address = "ST11NJTTKGVT6D1HY4NJRVQWMQM7TVAR091EJ8P2Y" -amount = 10000000000000000 - -[[ustx_balance]] -address = "ST1HB1T8WRNBYB0Y3T7WXZS38NKKPTBR3EG9EPJKR" -amount = 10000000000000000 - -[[ustx_balance]] -address = "STRYYQQ9M8KAF4NS7WNZQYY59X93XEKR31JP64CP" -amount = 10000000000000000 -``` - -#### address - -Address which maintains a micro-STX balance. - -Example: - -```toml -address = "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6" -``` - -#### amount - -The balance of micro-STX given to the address at the start of the node. - -Example: - -```toml -amount = 10000000000000000 -``` diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md b/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md deleted file mode 100644 index 094e3f03a1..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Verify Miner -description: Verify node is operating as miner -sidebar_position: 7 ---- - -You can verify that your node is operating as a miner by checking its log output to verify that it was able to find its Bitcoin UTXOs: - -```bash -$ head -n 100 /path/to/your/node/logs | grep -i utxo -INFO [1630127492.031042] [testnet/stacks-node/src/run_loop/neon.rs:146] [main] Miner node: checking UTXOs at address: -INFO [1630127492.062652] [testnet/stacks-node/src/run_loop/neon.rs:164] [main] UTXOs found - will run as a Miner node -``` \ No newline at end of file diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json b/i18n/vi/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json deleted file mode 100644 index f5de305558..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Noteworthy Contracts", - "position": 4, - "link": { - "type": "generated-index", - "description": "Specific deployed Clarity Contracts worth mentioning." - } -} \ No newline at end of file diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md b/i18n/vi/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md deleted file mode 100644 index 99723a9ff2..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md +++ /dev/null @@ -1,362 +0,0 @@ ---- -title: BNS Contract -description: The Blockchain Naming System. ---- - -![](/img/satoshi-btc.png) - -## Introduction - -The Blockchain Naming System (BNS) is implemented as a smart contract using Clarity. - -Below is a list of public and read-only functions as well as error codes that can be returned by those methods: -* [Public functions](#public-functions) -* [Read-only functions](#read-only-functions) -* [Error codes](#error-codes) - -## Public functions - - -### name-import - -#### Input: `(buff 20), (buff 48), principal, (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-import namespace name beneficiary zonefile-hash)` -#### Description: -Imports name to a revealed namespace. Each imported name is given both an owner and some off-chain state. - -### name-preorder - -#### Input: `(buff 20), uint` -#### Output: `(response uint int)` -#### Signature: `(name-preorder hashed-salted-fqn stx-to-burn)` -#### Description: -Preorders a name by telling all BNS nodes the salted hash of the BNS name. It pays the registration fee to the namespace owner's designated address. - -### name-register - -#### Input: `(buff 20), (buff 48), (buff 20), (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-register namespace name salt zonefile-hash)` -#### Description: -Reveals the salt and the name to all BNS nodes, and assigns the name an initial public key hash and zone file hash. - -### name-renewal - -#### Input: `(buff 20), (buff 48), uint, (optional principal), (optional (buff 20))` -#### Output: `(response bool int)` -#### Signature: `(name-renewal namespace name stx-to-burn new-owner zonefile-hash)` -#### Description: -Depending in the namespace rules, a name can expire. For example, names in the .id namespace expire after 2 years. You need to send a name renewal every so often to keep your name. - -You will pay the registration cost of your name to the namespace's designated burn address when you renew it. When a name expires, it enters a \"grace period\". The period is set to 5000 blocks (a month) but can be configured for each namespace. - -It will stop resolving in the grace period, and all of the above operations will cease to be honored by the BNS consensus rules. You may, however, send a NAME_RENEWAL during this grace period to preserve your name. After the grace period, everybody can register that name again. If your name is in a namespace where names do not expire, then you never need to use this transaction. -### name-revoke - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(name-revoke namespace name)` -#### Description: -Makes a name unresolvable. The BNS consensus rules stipulate that once a name is revoked, no one can change its public key hash or its zone file hash. The name's zone file hash is set to null to prevent it from resolving. You should only do this if your private key is compromised, or if you want to render your name unusable for whatever reason. - -### name-transfer - -#### Input: `(buff 20), (buff 48), principal, (optional (buff 20))` -#### Output: `(response bool int)` -#### Signature: `(name-transfer namespace name new-owner zonefile-hash)` -#### Description: -Changes the name's public key hash. You would send a name transfer transaction if you wanted to: -* Change your private key -* Send the name to someone else or -* Update your zone file - -When transferring a name, you have the option to also clear the name's zone file hash (i.e. set it to null). This is useful for when you send the name to someone else, so the recipient's name does not resolve to your zone file. - -### name-update - -#### Input: `(buff 20), (buff 48), (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-update namespace name zonefile-hash)` -#### Description: -Changes the name's zone file hash. You would send a name update transaction if you wanted to change the name's zone file contents. For example, you would do this if you want to deploy your own Gaia hub and want other people to read from it. - -### namespace-preorder - -#### Input: `(buff 20), uint` -#### Output: `(response uint int)` -#### Signature: `(namespace-preorder hashed-salted-namespace stx-to-burn)` -#### Description: -Registers the salted hash of the namespace with BNS nodes, and burns the requisite amount of cryptocurrency. Additionally, this step proves to the BNS nodes that user has honored the BNS consensus rules by including a recent consensus hash in the transaction. Returns pre-order's expiration date (in blocks). - -### namespace-ready - -#### Input: `(buff 20)` -#### Output: `(response bool int)` -#### Signature: `(namespace-ready namespace)` -#### Description: -Launches the namespace and makes it available to the public. Once a namespace is launched, anyone can register a name in it if they pay the appropriate amount of cryptocurrency. - -### namespace-reveal - -#### Input: `(buff 20), (buff 20), uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, principal` -#### Output: `(response bool int)` -#### Signature: `(namespace-reveal namespace namespace-salt p-func-base p-func-coeff p-func-b1 p-func-b2 p-func-b3 p-func-b4 p-func-b5 p-func-b6 p-func-b7 p-func-b8 p-func-b9 p-func-b10 p-func-b11 p-func-b12 p-func-b13 p-func-b14 p-func-b15 p-func-b16 p-func-non-alpha-discount p-func-no-vowel-discount lifetime namespace-import)` -#### Description: -Reveals the salt and the namespace ID (after a namespace preorder). It reveals how long names last in this namespace before they expire or must be renewed, and it sets a price function for the namespace that determines how cheap or expensive names its will be.All of the parameters prefixed by `p` make up the `price function`. These parameters govern the pricing and lifetime of names in the namespace. - -The rules for a namespace are as follows: - -* a name can fall into one of 16 buckets, measured by length. Bucket 16 incorporates all names at least 16 characters long. - -* the pricing structure applies a multiplicative penalty for having numeric characters, or punctuation characters. - -* the price of a name in a bucket is `((coeff) * (base) ^ (bucket exponent)) / ((numeric discount multiplier) * (punctuation discount multiplier))` - -Example: - -* base = 10 -* coeff = 2 -* nonalpha discount: 10 -* no-vowel discount: 10 -* buckets 1, 2: 9 -* buckets 3, 4, 5, 6: 8 -* buckets 7, 8, 9, 10, 11, 12, 13, 14: 7 -* buckets 15, 16+: - - -## Read-only functions - -### can-name-be-registered - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(can-name-be-registered namespace name)` -#### Description: -Returns true if the provided name can be registered. - -### can-namespace-be-registered - -#### Input: `(buff 20)` -#### Output: `(response bool UnknownType)` -#### Signature: `(can-namespace-be-registered namespace)` -#### Description: -Returns true if the provided namespace is available. - -### can-receive-name - -#### Input: `principal` -#### Output: `(response bool int)` -#### Signature: `(can-receive-name owner)` -#### Description: -Returns true if the provided name can be received. That is, if it is not curretly owned, a previous lease is expired, and the name wasn't revoked. - -### get-name-price - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response uint int)` -#### Signature: `(get-name-price namespace name)` -#### Description: -Gets the price for a name. - -### get-namespace-price - -#### Input: `(buff 20)` -#### Output: `(response uint int)` -#### Signature: `(get-namespace-price namespace)` -#### Description: -Gets the price for a namespace. - -### get-namespace-properties - -#### Input: `(buff 20)` -#### Output: `(response (tuple (namespace (buff 20)) (properties (tuple (can-update-price-function bool) (launched-at (optional uint)) (lifetime uint) (namespace-import principal) (price-function (tuple (base uint) (buckets (list 16 uint)) (coeff uint) (no-vowel-discount uint) (nonalpha-discount uint))) (revealed-at uint)))) int)` -#### Signature: `(get-namespace-properties namespace)` -#### Description: -Get namespace properties. - -### is-name-lease-expired - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(is-name-lease-expired namespace name)` -#### Description: -Return true if the provided name lease is expired. - -### name-resolve - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response (tuple (lease-ending-at (optional uint)) (lease-started-at uint) (owner principal) (zonefile-hash (buff 20))) int)` -#### Signature: `(name-resolve namespace name)` -#### Description: -Get name registration details. - -### resolve-principal - -#### Input: `principal` -#### Output: `(response (tuple (name (buff 48)) (namespace (buff 20))) (tuple (code int) (name (optional (tuple (name (buff 48)) (namespace (buff 20)))))))` -#### Signature: `(resolve-principal owner)` -#### Description: -Returns the registered name that a principal owns if there is one. A principal can only own one name at a time. - -## Error codes - -### ERR_INSUFFICIENT_FUNDS -#### type: `int` -#### value: `4001` - -### ERR_NAMESPACE_ALREADY_EXISTS -#### type: `int` -#### value: `1006` - -### ERR_NAMESPACE_ALREADY_LAUNCHED -#### type: `int` -#### value: `1014` - -### ERR_NAMESPACE_BLANK -#### type: `int` -#### value: `1013` - -### ERR_NAMESPACE_CHARSET_INVALID -#### type: `int` -#### value: `1016` - -### ERR_NAMESPACE_HASH_MALFORMED -#### type: `int` -#### value: `1015` - -### ERR_NAMESPACE_NOT_FOUND -#### type: `int` -#### value: `1005` - -### ERR_NAMESPACE_NOT_LAUNCHED -#### type: `int` -#### value: `1007` - -### ERR_NAMESPACE_OPERATION_UNAUTHORIZED -#### type: `int` -#### value: `1011` - -### ERR_NAMESPACE_PREORDER_ALREADY_EXISTS -#### type: `int` -#### value: `1003` - -### ERR_NAMESPACE_PREORDER_CLAIMABILITY_EXPIRED -#### type: `int` -#### value: `1009` - -### ERR_NAMESPACE_PREORDER_EXPIRED -#### type: `int` -#### value: `1002` - -### ERR_NAMESPACE_PREORDER_LAUNCHABILITY_EXPIRED -#### type: `int` -#### value: `1010` - -### ERR_NAMESPACE_PREORDER_NOT_FOUND -#### type: `int` -#### value: `1001` - -### ERR_NAMESPACE_PRICE_FUNCTION_INVALID -#### type: `int` -#### value: `1008` - -### ERR_NAMESPACE_STX_BURNT_INSUFFICIENT -#### type: `int` -#### value: `1012` - -### ERR_NAMESPACE_UNAVAILABLE -#### type: `int` -#### value: `1004` - -### ERR_NAME_ALREADY_CLAIMED -#### type: `int` -#### value: `2011` - -### ERR_NAME_BLANK -#### type: `int` -#### value: `2010` - -### ERR_NAME_CHARSET_INVALID -#### type: `int` -#### value: `2022` - -### ERR_NAME_CLAIMABILITY_EXPIRED -#### type: `int` -#### value: `2012` - -### ERR_NAME_COULD_NOT_BE_MINTED -#### type: `int` -#### value: `2020` - -### ERR_NAME_COULD_NOT_BE_TRANSFERED -#### type: `int` -#### value: `2021` - -### ERR_NAME_EXPIRED -#### type: `int` -#### value: `2008` - -### ERR_NAME_GRACE_PERIOD -#### type: `int` -#### value: `2009` - -### ERR_NAME_HASH_MALFORMED -#### type: `int` -#### value: `2017` - -### ERR_NAME_NOT_FOUND -#### type: `int` -#### value: `2013` - -### ERR_NAME_NOT_RESOLVABLE -#### type: `int` -#### value: `2019` - -### ERR_NAME_OPERATION_UNAUTHORIZED -#### type: `int` -#### value: `2006` - -### ERR_NAME_PREORDERED_BEFORE_NAMESPACE_LAUNCH -#### type: `int` -#### value: `2018` - -### ERR_NAME_PREORDER_ALREADY_EXISTS -#### type: `int` -#### value: `2016` - -### ERR_NAME_PREORDER_EXPIRED -#### type: `int` -#### value: `2002` - -### ERR_NAME_PREORDER_FUNDS_INSUFFICIENT -#### type: `int` -#### value: `2003` - -### ERR_NAME_PREORDER_NOT_FOUND -#### type: `int` -#### value: `2001` - -### ERR_NAME_REVOKED -#### type: `int` -#### value: `2014` - -### ERR_NAME_STX_BURNT_INSUFFICIENT -#### type: `int` -#### value: `2007` - -### ERR_NAME_TRANSFER_FAILED -#### type: `int` -#### value: `2015` - -### ERR_NAME_UNAVAILABLE -#### type: `int` -#### value: `2004` - -### ERR_PANIC -#### type: `int` -#### value: `0` - -### ERR_PRINCIPAL_ALREADY_ASSOCIATED -#### type: `int` -#### value: `3001` diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md b/i18n/vi/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md deleted file mode 100644 index ce1b1ba859..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -title: Stacking Contract -description: See a detailed list of all functions and error codes of the Stacking contract. ---- - -## Introduction - -Stacking is implemented as a smart contract using Clarity. You can always find the Stacking contract identifier using the Stacks Blockchain API [`v2/pox` endpoint](https://docs.hiro.so/api#operation/get_pox_info). - -Below is a list of public and read-only functions as well as error codes that can be returned by those methods: - -* [Public functions](#public-functions) -* [Read-only functions](#read-only-functions) -* [Error codes](#error-codes) - -## Public functions - -### allow-contract-caller -#### input: `principal, (optional uint)` -#### output: `(response bool int)` -#### signature: `(allow-contract-caller caller until-burn-ht)` -#### description: -Give a contract-caller authorization to call stacking methods. Normally, stacking methods may only be invoked by _direct_ transactions (i.e., the `tx-sender` issues a direct `contract-call` to the stacking methods). - -By issuing an allowance, the tx-sender may call through the allowed contract. - -### delegate-stack-stx -#### input: `principal, uint, (tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint` -#### output: `(response (tuple (lock-amount uint) (stacker principal) (unlock-burn-height uint)) int)` -#### signature: `(delegate-stack-stx stacker amount-ustx pox-addr start-burn-ht lock-period)` -#### description: -As a delegate, stack the given principal's STX using `partial-stacked-by-cycle`. - -Once the delegate has stacked > minimum, the delegate should call `stack-aggregation-commit`. - -### delegate-stx -#### input: `uint, principal, (optional uint), (optional (tuple (hashbytes (buff 20)) (version (buff 1))))` -#### output: `(response bool int)` -#### signature: `(delegate-stx amount-ustx delegate-to until-burn-ht pox-addr)` -#### description: -Delegate to `delegate-to` the ability to stack from a given address. - -This method _does not_ lock the funds, rather, it allows the delegate to issue the stacking lock. - -The caller specifies: - -* amount-ustx: the total amount of ustx the delegate may be allowed to lock -* until-burn-ht: an optional burn height at which this delegation expiration -* pox-addr: an optional p2pkh or p2sh address to which any rewards *must* be sent - -### disallow-contract-caller -#### input: `principal` -#### output: `(response bool int)` -#### signature: `(disallow-contract-caller caller)` -#### description: -Revokes authorization from a contract to invoke stacking methods through contract-calls - -### reject-pox -#### input: -#### output: `(response bool int)` -#### signature: `(reject-pox)` -#### description: -Reject Stacking for this reward cycle. - -`tx-sender` votes all its uSTX for rejection. - -Note that unlike Stacking, rejecting PoX does not lock the tx-sender's tokens: PoX rejection acts like a coin vote. - -### revoke-delegate-stx -#### input: -#### output: `(response bool int)` -#### signature: `(revoke-delegate-stx)` -#### description: -Revoke a Stacking delegate relationship. A particular Stacker may only have one delegate, so this method does not take any parameters, and just revokes the Stacker's current delegate (if one exists). - -### stack-aggregation-commit -#### input: `(tuple (hashbytes (buff 20)) (version (buff 1))), uint` -#### output: `(response bool int)` -#### signature: `(stack-aggregation-commit pox-addr reward-cycle)` -#### description: -Commit partially stacked STX. - -This allows a stacker/delegate to lock fewer STX than the minimal threshold in multiple transactions, - -so long as: - -1. The pox-addr is the same. -2. This \"commit\" transaction is called _before_ the PoX anchor block. - -This ensures that each entry in the reward set returned to the stacks-node is greater than the threshold, - - but does not require it be all locked up within a single transaction - -### stack-stx -#### input: `uint, (tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint` -#### output: `(response (tuple (lock-amount uint) (stacker principal) (unlock-burn-height uint)) int)` -#### signature: `(stack-stx amount-ustx pox-addr start-burn-ht lock-period)` -#### description: -Lock up some uSTX for stacking! Note that the given amount here is in micro-STX (uSTX). - -The STX will be locked for the given number of reward cycles (lock-period). - -This is the self-service interface. tx-sender will be the Stacker. - -* The given stacker cannot currently be stacking. -* You will need the minimum uSTX threshold. This isn't determined until the reward cycle begins, but this method still requires stacking over the _absolute minimum_ amount, which can be obtained by calling `get-stacking-minimum`. -* The pox-addr argument must represent a valid reward address. Right now, this must be a Bitcoin p2pkh or p2sh address. It cannot be a native Segwit address, but it may be a p2wpkh-p2sh or p2wsh-p2sh address. - -The tokens will unlock and be returned to the Stacker (tx-sender) automatically. - -## Read-only functions - -### can-stack-stx -#### input: `(tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint, uint` -#### output: `(response bool int)` -#### signature: `(can-stack-stx pox-addr amount-ustx first-reward-cycle num-cycles)` -#### description: -Evaluate if a participant can stack an amount of STX for a given period. - -### get-pox-info -#### input: -#### output: `(response (tuple (current-rejection-votes uint) (first-burnchain-block-height uint) (min-amount-ustx uint) (prepare-cycle-length uint) (rejection-fraction uint) (reward-cycle-id uint) (reward-cycle-length uint) (total-liquid-supply-ustx uint)) UnknownType)` -#### signature: `(get-pox-info)` -#### description: -Returns information about PoX status. - -### get-pox-rejection -#### input: `principal, uint` -#### output: `(optional (tuple (amount uint)))` -#### signature: `(get-pox-rejection stacker reward-cycle)` -#### description: -Returns the amount of uSTX that a given principal used to reject a PoX cycle. - -### get-stacker-info -#### input: `principal` -#### output: `(optional (tuple (amount-ustx uint) (first-reward-cycle uint) (lock-period uint) (pox-addr (tuple (hashbytes (buff 20)) (version (buff 1))))))` -#### signature: `(get-stacker-info stacker)` -#### description: -Returns the _current_ stacking information for `stacker. If the information is expired, or if there's never been such a stacker, then returns none. - -### get-stacking-minimum -#### input: -#### output: `uint` -#### signature: `(get-stacking-minimum)` -#### description: -Returns the absolute minimum amount that could be validly Stacked (the threshold to Stack in a given reward cycle may be higher than this - -### get-total-ustx-stacked -#### input: `uint` -#### output: `uint` -#### signature: `(get-total-ustx-stacked reward-cycle)` -#### description: -Returns the amount of currently participating uSTX in the given cycle. - -### is-pox-active -#### input: `uint` -#### output: `bool` -#### signature: `(is-pox-active reward-cycle)` -#### description: -Returns whether or not PoX has been rejected at a given PoX cycle. -## Error codes - -### ERR_DELEGATION_EXPIRES_DURING_LOCK -#### type: `int` -#### value: `21` - -### ERR_DELEGATION_POX_ADDR_REQUIRED -#### type: `int` -#### value: `23` - -### ERR_DELEGATION_TOO_MUCH_LOCKED -#### type: `int` -#### value: `22` - -### ERR_INVALID_START_BURN_HEIGHT -#### type: `int` -#### value: `24` - -### ERR_NOT_ALLOWED -#### type: `int` -#### value: `19` - -### ERR_STACKING_ALREADY_DELEGATED -#### type: `int` -#### value: `20` - -### ERR_STACKING_ALREADY_REJECTED -#### type: `int` -#### value: `17` - -### ERR_STACKING_ALREADY_STACKED -#### type: `int` -#### value: `3` - -### ERR_STACKING_EXPIRED -#### type: `int` -#### value: `5` - -### ERR_STACKING_INSUFFICIENT_FUNDS -#### type: `int` -#### value: `1` - -### ERR_STACKING_INVALID_AMOUNT -#### type: `int` -#### value: `18` - -### ERR_STACKING_INVALID_LOCK_PERIOD -#### type: `int` -#### value: `2` - -### ERR_STACKING_INVALID_POX_ADDRESS -#### type: `int` -#### value: `13` - -### ERR_STACKING_NO_SUCH_PRINCIPAL -#### type: `int` -#### value: `4` - -### ERR_STACKING_PERMISSION_DENIED -#### type: `int` -#### value: `9` - -### ERR_STACKING_POX_ADDRESS_IN_USE -#### type: `int` -#### value: `12` - -### ERR_STACKING_STX_LOCKED -#### type: `int` -#### value: `6` - -### ERR_STACKING_THRESHOLD_NOT_MET -#### type: `int` -#### value: `11` - -### ERR_STACKING_UNREACHABLE -#### type: `int` -#### value: `255` \ No newline at end of file diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md b/i18n/vi/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md deleted file mode 100644 index 5f38edfb57..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: xBTC -description: Wrapped BTC on Stacks ---- - -![](/img/xbtc-icon.webp) - -## Introduction - -[Wrapped.com](https://www.wrapped.com) has brought Bitcoin (xBTC) to the Stacks ecosystem. - -xBTC is backed 1:1 by Bitcoin and empowers developers to expand the Bitcoin DeFi ecosystem. - -The reserves are publicly visible [here](https://open.wrapped.com/reserves/). - -## Contract - -[SP3DX3H4FEYZJZ586MFBS25ZW3HZDMEW92260R2PR.Wrapped-Bitcoin](https://explorer.stacks.co/txid/SP3DX3H4FEYZJZ586MFBS25ZW3HZDMEW92260R2PR.Wrapped-Bitcoin?chain=mainnet) - -## Examples of uses - -[Friedger Mining Pool](https://pool.friedger.de/) currrently supports Stacking rewards payments in xBTC (optional). - - -## More information - -* [Blog post announcement](https://www.stacks.co/blog/tokensoft-wrapped-fundamental-bitcoin-defi-building-blocks-xbtc) by Muneeb Ali - -* Video: [Why xBTC is Important For Bitcoin to Grow](https://www.youtube.com/watch?v=xIoadrfSdi4) \ No newline at end of file diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/references/_category_.json b/i18n/vi/docusaurus-plugin-content-docs/current/references/_category_.json deleted file mode 100644 index 3805ab0783..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/references/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "References", - "position": 9, - "link": { - "type": "generated-index", - "description": "Stacks references." - } -} \ No newline at end of file diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/references/glossary.md b/i18n/vi/docusaurus-plugin-content-docs/current/references/glossary.md deleted file mode 100644 index 1027a52c96..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/references/glossary.md +++ /dev/null @@ -1,215 +0,0 @@ ---- -title: Glossary -description: A comprehensive list of terms used within the ecosystem. ---- - -A comprehensive list of terms used within the ecosystem. - -#### App Review -An incentive mechanism for application developers in the early stage (first four years) of the ecosystem and helps with bootstrapping the two-sided market. - -#### Atlas -A peer network provide a global index for discovery. - -#### Bitcoin (BTC) address -A string of letters and numbers. `3E53XjqK4Cxt71BGeP2VhpcotM8LZ853C8` Sharing this address allows anyone to send Bitcoin to the address. - -#### block -A discrete group of records written to a blockchain that can effectively be identified and referenced by the use of headers that contain a digital fingerprint of the records each block contains. - -#### blockchain -A database created and shared by the members of a peer-to-peer computer network which each member of that network can independently trust due to the rules governing the database’s creation. A blockchain can therefore be used to replace centralized databases. - -#### Blockchain Name System (BNS) -Replacement for DNS. More info [here](../noteworthy-contracts/bns-contract). - -#### Blockstack Browser -A deprecated application for accessing identity and storage. - -#### Blockstack Owner Address - -Looks like a bitcoin address but starts with `ID` for example: `ID-1J3PUxY5uDShUnHRrMyU6yKtoHEUPhKULs` - -#### Burning -Burning a token means that the token is transferred to an address that is a black hole—one that is not owned by any entity and for which guessing the applicable private key is effectively impossible based on known mathematical principles. This effectively destroys the token by making it unavailable for future use and decreases the total number of tokens available from that point forward. - -#### consensus hash -A consensus hash is a cryptographic hash that each node calculates at each block. It is derived from the accepted state transitions in the last-processed block and a geometric series of prior-calculated consensus hashes. - -#### Consensus rules -"The rules governing the creation of new valid records in a blockchain database and the mining algorithms used for this purpose. - -#### control plane -The part of a network that carries signaling traffic and is responsible for routing. Control packets originate from or are destined for a router. Functions of the control plane include system configuration and management. - -#### core node -A server that runs Stacks Blockchain services. - -#### crypto-asset -A digital asset which utilises cryptography, peer-to-peer networking and a public ledger to regulate the creation of new units, verify transactions and secure the transactions without the intervention of any middleman. - -#### cryptography -The practise and study of encryption and decryption - encoding data so that it can only be decoded by specific individuals. A system for encrypting and decrypting data is a cryptosystem. - -#### DAO -See Decentralized Autonomous Organization. - -#### decentralized application (DApp) -A DApp is a service that enables direct interaction between end users and providers (e.g. connecting buyers and sellers in some marketplace, owners and stores in file storage). A term coined by Ethereum. See their glossary: http://ethdocs.org/en/latest/glossary.html#dapp" - -#### Decentralized Autonomous Organization -A type of contract or suite of contracts on the blockchain that is intented to codify, enforce or automate the processes of an organization. - -#### digital asset -Also referred to as a crypto-asset. Any set of unique digital information—including, for example, programs, decentralized programs, isolated chunks of programming code, collections of data, e-mail or web addresses or cryptocurrency tokens—that is capable of being stored and uniquely tracked on a computer network such as the Stacks network and over which a user can maintain control through that network. - -#### digital fingerprint -A digital fingerprint is a unique number of a fixed length that can be produced by running any set of digital information through something called a cryptographic hash function. Each set of digital information (including a digital asset, and the digital record of any network operation on that digital asset) should (as a practical matter) have a unique digital fingerprint, which allows that set of digital information to be identified. However, it is almost impossible to recreate a digital asset from its digital fingerprint. The Blockstack network uses industry-standard algorithms such as SHA-256 to create digital fingerprints. - -#### digital signature -A digital signature is a sequence of digital information combining a user’s private key and any digital information that the user wishes to sign. Any other party can use the user’s paired public key to verify that the digital signature is authentic, i.e. that the public key was generated from a particular piece of digital information and the user’s private key. - -#### distributed hash tables (DHT) -A form of network used to store some content in the form of key/value pairs. ... This experimental project try to avoid keeping all the blockchain, but instead prefers to store it in a DHT. - -#### ephemeral key -A cryptographic key is called ephemeral if it is generated for each execution of a key establishment process. - -#### fork -The term fork is used to refer both to any situation where there are two or more competing versions of a blockchain on a network (a situation that may arise and resolve itself in the ordinary course of network operations due to lags in communication between core nodes) and any software update that is proposed for adoption by the core nodes of a blockchain network that may result in a persistent fork on the network, with core nodes that adopt the update recognizing one version of the blockchain and those which do not recognizing another. - -#### Gaia -Decentralized storage architecture for off-chain data. More info [here](../gaia). - -#### genesis block -The genesis block is the first block of the Stacks blockchain, which will create the initial 1.32 billion Stacks Tokens. - -#### id.blockstack -An identifier in the Blockstack, for example meepers.id.blockstack. This is your name & identity that is registered in the .id namespace on Blockstack. Your personal data and storage are built around this ID. Apps that want to access your data use your permission and identity to find it. An id is usually a shorthand for a longer, hash ID string, for example ID-1Fj9kkw15P51Fj9kkw15P5xJmyefWhLKrQMKNPREfaqsJ" - -#### identity - -A way to identify a person or an organization on the Stacks network. An identity is unique, both `meepers.id.blockstack` or `chad.id` are examples of IDs. - -#### identity management (IDM) -Identity management, also known as identity and access management is, in computer security, the security and business discipline that enables the right individuals to access the right resources at the right times and for the right reason". - -#### know your customer (KYC) -Or KYC, is a popular term used in the banking or financial field. KYC is a process where financial institutions, insurers and other companies obtain information about the identity and address of the customers as part of risk management. - -#### light clients -Clients that can independently validate the existence of transactions by downloading only block headers and not the entire blockchain. - -#### magic recovery code - -A long encrypted string, for example: `36mWivFdy0YPH2z31EflpQz/Y0UMrOrJ++lH=0EI7c3mop2JuRBm5WXxSTazJsUjOA...` Do not share the QR code that accompanied your recovery code either. This is a QR code: - -![](/img/qr-code.png) - -#### mesh network -A local network topology in which the infrastructure nodes (i.e. bridges, switches, and other infrastructure devices) connect directly, dynamically and non-hierarchically to as many other nodes as possible and cooperate with one another to efficiently route data from/to clients. - -#### mining -Mining generally refers to the process of performing certain functions for a network such as adding new records to a blockchain in exchange for mining rewards; it may also refer to other mechanisms whereby rewards (usually in the form of cryptocurrency) are provided for performing other tasks helpful to the network. - -#### mining power -A miner’s (or group of miners’) mining power is equal to the probability it will be selected to write a new block to the blockchain. Depending on the mechanism for mining, this is usually related to the overall share of computing power or cryptoassets the miner or miners possess relative to all miners for that blockchain. - -#### mining rewards -Mining rewards are newly issued tokens received by miners in exchange for adding new records to the blockchain or other activities beneficial to the network. - -#### name -An identifier or name. Names are a type of digital asset in the Stacks network. If you have signed into the Stacks Wallet, you might have created a name. If an application developer registered an application within Stacks, then they registered a name. Public Stacking pools can also have a name. - -#### network operation -A network operation is any change to the information about a digital asset (or smart contract) stored on a blockchain, including, for example, a change in the digital asset’s owner, or a change in the location at which it is stored on the network. How and when these network operations are performed for each digital asset is governed, on the Blockstack network, either by the Stacks Node software or a smart contract. - -#### NFT -Non fungible token. - -#### private key - -Private keys matches a corresponding public key. A public key also looks like a string of letters and numbers: - -![](/img/private.png) - -The exact format of the public and private key depend on the software you use to create them. - -#### proof-of-burn mining -The consensus algorithm used in the Stacks blockchain where miners destroy a proof-of-work-based cryptocurrency (currently Bitcoin) to get tokens; this enables the functionality where nodes can select between conflicting blockchain forks, as the blockchain fork with the most amount of cryptocurrency burned is considered to be the correct fork. - -#### proof-of-work -A proof-of-work system or proof-of-work mining is a mining mechanism where miners must expend computing power to solve complicated cryptographic puzzles, and prove that they have done so by writing the solution to the blockchain, in order to be allowed to add blocks to a blockchain. This is the mining system used, for example, by Bitcoin. - -#### public key -Public and private key pair comprise of two uniquely related cryptographic keys. It looks like a long random string of letters and numbers: `3048 0241 00C9 18FA CF8D EB2D EFD5 FD37 89B9 E069 EA97 FC20 …` The exact format of the public and private key depend on the software you use to create them. - -#### Public Key Infrastructure (PKI) -A system which returns a cryptographic public key associated with a name. - -#### replicated state machines (RSMs) -This is a model for reasoning about distributed computer programs -- any program (plus it's input) can be represented as a state machine, and when trying to get a distributed set of servers to agree on the output of an algorithm, you can model that process as N different state machines" - -#### Secret recovery Key, -Used to access an identity on the Stacks blockchain. A 24-word sequence of words for example: `applied binge crisp pictorial fiery` `dancing agreeable frogs light finish ping apple` - -#### seed phrase - -Used to access Stacks Wallet software. The seed phrase consists of 24 words in a sequence. Both the word *and its position the sequence* are important. Write down your seed phrase and store it in a secure location such as a safe deposit box. When you write the seed phrase down, include its position, for example,`1-frog, 2-horse, 3-building` and so on until you reach a final position `24-ocean`. -#### smart contract -A smart contract is a computer program written to a blockchain such as the Stacks blockchain by developers. This computer program defines the various network operations that can be performed on the digital assets on the blockchain, the computations that can be performed using the smart contract, along with defining various important properties of the respective digital assets like ownership rights and the cost in fuel required to register the digital assets. - -#### soft fork -A soft fork is a proposed update to the software governing the network that results in a post-update network that is compatible with the network as it existed prior to the update, because it restricts the network operations that can be performed after the update. - -#### Stacks (STX) address - - A STX address is a string of letters and numbers starting with an `SP` or `SM`, for example: `SM3KJBA4RZ7Z20KD2HBXNSXVPCR1D3CRAV6Q05MKT` If you created a software-only wallet with the Stacks Wallet software, the wallet has a single STX address which is also sometimes called the *wallet address*. You access a software wallet with a *seed phrase*. " - -#### Stacks blockchain -The Stacks blockchain is the custom blockchain being developed for use by the Stacks network that will use the Stacks token as its native currency and which will include the genesis block and subsequent blocks created by the mining activities described in the Stacks Network—Development of the Stacks network. - -#### Stacks Explorer -An application that allow you to view and search transactions in the blockchain. For example, https://explorer.stacks.co. - -#### Stacks node -A complete version of our open-source software available on Github at https://github.com/stacks-network/stacks-blockchain/ that governs the creation of the blockchain, the smart contracts that may be written to our blockchain, and other systems that make up the Stacks network, when run on the systems and devices of our users and developers. - -#### Stacks wallet -An application for accessing assets, identity and storage. More information and example [here](../services-using-stacks/wallets). Examples are the [Hiro Wallet](https://www.hiro.so/wallet), [xverse](https://www.xverse.app/) and [dcent](https://dcentwallet.com/). - -#### storage hub -A Gaia instance run by a hub provider or software. A Gaia hub stores data in a separate, addressed location. - -#### storage provider -A third-party company cloud or software provider that hosts one or more Gaia storage hubs. - -#### transaction -A transaction is a unit of work within a block. - -#### transaction fee -Fees paid by participants in a transaction to miners. - -#### two-sided market problem -Economic platforms having two distinct user groups that provide each other with network benefits. The Stacks platform is a classic two-sided market. - -#### username -A shorthand name for your id.blockstack. - -#### virtual blockchain -A layer that sits on top of a blockchain that introduces new functionality and operations without requiring changes to the underlying blockchain. - -#### wallet address -A wallet address is the form in which a public key can be presented and recorded on a blockchain. Wallet addresses are therefore used to assign the ownership of digital assets on the Blockstack network. - -#### watch-only wallet -A wallet without send and receive ability. You can view only balances and transaction history. - -#### web of trust mining -Web-of-trust mining provides incentive mechanisms for users where an initial trusted-set of unique users is curated in the genesis block and, in the future, the initial set of users can expand the web-of-trust after the network goes live. - -#### web3 -The exact definition is still under discussion, but it general refers to the 3rd generation of the web that is based on blockchain technology and incorporates decentralized and token-based economics. - -#### zone file -A Domain Name System (DNS) zone file is a text file that describes a DNS zone. A DNS zone is a subset, often a single domain, of the hierarchical domain name structure of the DNS. diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/references/nft.md b/i18n/vi/docusaurus-plugin-content-docs/current/references/nft.md deleted file mode 100644 index 033ee0a71a..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/references/nft.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: NFTs on Stacks -description: A list of sites that operate NFTs on Stacks ---- - -List of sites that operate NFTS on Stacks on alphabetical order. - -### [Byzantion](https://byzantion.xyz/) - -![website-screenshot](/img/sh_nft_byzantion.png) - -### [Gamma](https://gamma.io/) -![website-screenshot](/img/sh_nft_gamma.png) - -### [Megapont](https://www.megapont.com/) - -![website-screenshot](/img/sh_nft_megapont.png) - -### [StacksArt](https://www.stacksart.com/) - -![website-screenshot](/img/sh_nft_stacksart.png) - diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md b/i18n/vi/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md deleted file mode 100644 index dc6e507d5e..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Stacks info sites -description: A list of sites on alphabetical order that display status and stats of the Stacks network. ---- - -### [Haystack](https://haystack.tools/mempool) - -![website-screenshot](/img/sh_haystacks.png) - -### [Stacksdata](https://stacksdata.info/) - -![website-screenshot](/img/sh_stacksdata.png) - -### [Stacksonchain](https://stacksonchain.com) - -![website-screenshot](/img/sh_stacksonchain.png) - -### [Status Hiro](https://status.hiro.so/) - -![website-screenshot](/img/sh_statushiro.png) - -### [Stxstats](https://www.stxstats.co/) - -![website-screenshot](/img/sh_stxstats.png) - -### [Novuminsights](https://stacks.novuminsights.com/health) - -![website-screenshot](/img/sh_novuminsights.png) - -### [Onstacks](https://app.onstacks.com/) - -![website-screenshot](/img/sh_onstacks.png) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json b/i18n/vi/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json deleted file mode 100644 index ebd63f366c..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Services using Stacks", - "position": 8, - "link": { - "type": "generated-index", - "description": "An 'always incomplete' list of services that use Stacks." - } -} \ No newline at end of file diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md b/i18n/vi/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md deleted file mode 100644 index 51defacba7..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: DeFi -description: De-Fi sites on Stacks -sidebar_position: 2 ---- - -They are multiple De-Fi sites that operate on the Stacks blockchain. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Alex - -[Alex](https://app.alexlab.co) ![](/img/sh_alex.png) - -## Arkadiko - -[Arkadiko](https://arkadiko.finance/) ![](/img/sh_arkadiko.png) - -## Catamaran Swaps - -[Catamaran Swaps](https://www.catamaranswaps.org/) allows trustless exchange of digital assets. - -![](/img/sh_catamaran.png) - -## Lnswap - -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange - -![](/img/sh_lnswap.png) - -## Neoswap - -[Neoswap](https://neoswap.party) - -![](/img/sh_neoswap.png) - -## Stackswap - -[Stackswap](https://app.stackswap.org/v2) - -![](/img/sh_stackswap.png) - diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/services-using-stacks/more.md b/i18n/vi/docusaurus-plugin-content-docs/current/services-using-stacks/more.md deleted file mode 100644 index df0b3e2254..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/services-using-stacks/more.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: More -description: More services built on Stacks. -sidebar_position: 5 ---- - -List of sites on alphabetical order added by the community. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Citycoins - -[Citycoins](https://citycoins.co) - -![](/img/sh_citycoins.png) - -## Sigle - -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. - -![](/img/sh_sigle.png) \ No newline at end of file diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md b/i18n/vi/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md deleted file mode 100644 index bfa0505dc9..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: NFTs -description: NFTs on Stacks -sidebar_position: 3 ---- - -List of sites that operate NFTS on Stacks on alphabetical order. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -### [Byzantion](https://byzantion.xyz/) - -![website-screenshot](/img/sh_nft_byzantion.png) - -### [Gamma](https://gamma.io/) -![website-screenshot](/img/sh_nft_gamma.png) - -### [Megapont](https://www.megapont.com/) - -![website-screenshot](/img/sh_nft_megapont.png) - -### [StacksArt](https://www.stacksart.com/) - -![website-screenshot](/img/sh_nft_stacksart.png) - -### [Superfandom](https://superfandom.io/) - -![website-screenshot](/img/sh_superfandom.png) \ No newline at end of file diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/services-using-stacks/other.md b/i18n/vi/docusaurus-plugin-content-docs/current/services-using-stacks/other.md deleted file mode 100644 index 199fc41da5..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/services-using-stacks/other.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Other Stacks sites -description: A list of sites on alphabetical order built on Stacks. -sidebar_position: 4 ---- - -List of sites on alphabetical order added by the community. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Alex -[Alex](https://app.alexlab.co) - -## Sigle - -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. \ No newline at end of file diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md b/i18n/vi/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md deleted file mode 100644 index 35ced8dac6..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Stacks info sites -description: Status and stats of the Stacks network. -sidebar_position: 1 ---- - -A list of sites on alphabetical order that display status and stats of the Stacks network. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -### [Haystack](https://haystack.tools/mempool) - -![website-screenshot](/img/sh_haystacks.png) - -### [Stacksdata](https://stacksdata.info/) - -![website-screenshot](/img/sh_stacksdata.png) - -### [Stacksonchain](https://stacksonchain.com) - -![website-screenshot](/img/sh_stacksonchain.png) - -### [Status Hiro](https://status.hiro.so/) - -![website-screenshot](/img/sh_statushiro.png) - -### [Stxstats](https://www.stxstats.co/) - -![website-screenshot](/img/sh_stxstats.png) - -### [Novuminsights](https://stacks.novuminsights.com/health) - -![website-screenshot](/img/sh_novuminsights.png) - -### [Onstacks](https://app.onstacks.com/) - -![website-screenshot](/img/sh_onstacks.png) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md b/i18n/vi/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md deleted file mode 100644 index d4b4cbf18c..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Swaps -description: A list of sites that allow Swaps -sidebar_position: 2 ---- - -They are multiple sites that allow you to make swaps using the Stacks blockchain. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Catamaran Swaps - -[Catamaran Swaps](https://www.catamaranswaps.org/) allows trustless exchange of digital assets. - -![](/img/sh_catamaran.png) - -## Lnswap - -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange - -![](/img/sh_lnswap.png) - -## Neoswap - -[Neoswap](https://neoswap.party) - -![](/img/sh_neoswap.png) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md b/i18n/vi/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md deleted file mode 100644 index e5ea6c5b45..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Wallets -description: Wallets for Stacks -sidebar_position: 4 ---- - -A list of hardware and software wallets for Stacks - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Blockchain.com - -[Blockchain.com](https://www.blockchain.com/wallet) - -![](/img/sh_blockchain.png) -## Boom - -[Boom](https://boom.money) - -![](/img/sh_boom.png) - -## Dcent wallet - -[D'CENT](https://dcentwallet.com) - -![](/img/sh_dcent.png) -## Hiro Wallet - -[Hiro Wallet](https://www.hiro.so/wallet) - -![](/img/sh_hirowallet.png) - -## Neptune - -[Neptune](https://neptunewallet.io) - -![](/img/sh_neptunewallet.png) - -## Xverse - -[Xverse](https://www.xverse.app/) - -![](/img/sh_xverse.png) - -## Wise - -[Wise](https://wiseapp.id) - -![](/img/sh_wiseapp.png) \ No newline at end of file diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md b/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md deleted file mode 100644 index 087280516a..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md +++ /dev/null @@ -1,215 +0,0 @@ ---- -title: Accounts -description: Guide to Stacks 2.0 accounts -sidebar_position: 5 ---- - -## Introduction - -Stacks 2.0 accounts are entities that own assets, like Stacks (STX) tokens. An account has an address, private key, nonce, and one or more asset balances. - -:::tip The encryption algorithm used in Stacks 2.0 is **[secp256k1](https://en.bitcoinwiki.org/wiki/Secp256k1)**. - -Additionally, [Ed25519](https://ed25519.cr.yp.to/) is also used just for the VRF (Verifiable Random Function). ::: - -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. - -:::tip -The transaction type doesn't need to be a token transfer - contract deploy and contract call transactions can change the balances of an account -::: - -## Creation - -An account is generated from a 24-word mnemonic phrase. This is often referred to as the **seed phrase**. The seed phrase provides access to Stacks 2.0 accounts. - -:::danger -If the seed phrase is lost, access to the associated account cannot be restored. No person or organization, including Blockstack, can recover a lost seed phrase. -::: - -The easiest way to generate a new Stacks 2.0 account is to use the [Stacks CLI](https://github.com/hirosystems/stacks.js/tree/master/packages/cli): - -```bash -# install CLI globally -npm install --global @stacks/cli - -# generate a new account and store details in a new file -# '-t' option makes this a testnet account -stx make_keychain -t > cli_keychain.json -``` - -`make_keychain` creates the following file: - -```js -{ - "mnemonic": "aaa bbb ccc ddd ...", - "keyInfo": { - "privateKey": "5a3f1f15245bb3fb...", - "address": "STJRM2AMVF90ER6G3RW1QTF85E3HZH37006D5ER1", - "btcAddress": "biwSd6KTEvJcyX2R8oyfgj5REuLzczMYC1", - "wif": "L4HXn7PLmzoNW...", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -| Field | Description | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `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.privateKey` | Private key for the account. Required for token transfers and often referred to as `senderKey` | -| `keyInfo.address` | Stacks address for the account | -| `keyInfo.btcAddress` | Corresponding BTC address for the account. | -| `keyInfo.wif` | Private key of the btcAddress in compressed format. | -| `keyInfo.index` | Nonce for the account, starting at 0 | - -Note that a new account automatically exists for each new private key. There is no need to manually instantiate an account on the Stacks 2.0 blockchain. - -:::tip Addresses are created by generating the [RIPEMD-160 hash](https://en.wikipedia.org/wiki/RIPEMD#RIPEMD-160_hashes) of the [SHA256](https://en.bitcoinwiki.org/wiki/SHA-256) of the public key. BTC addresses are encoded with [Base58Check](https://en.bitcoin.it/wiki/Base58Check_encoding). For Stacks addresses, [c32check](https://github.com/stacks-network/c32check) is used. Deriving an address from a public key can be done without internet access, for instance using the c32check `c32addressDecode` method. ::: - -Alternatively to the CLI creation, the [Stacks Transactions JS](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library can be used: - -```js -import { - makeRandomPrivKey, - privateKeyToString, - getAddressFromPrivateKey, - TransactionVersion, - getPublicKey, -} from '@stacks/transactions'; - -const privateKey = makeRandomPrivKey(); - -// Get public key from private -const publicKey = getPublicKey(privateKey); - -const stacksAddress = getAddressFromPrivateKey( - privateKeyToString(privateKey), - TransactionVersion.Testnet // remove for Mainnet addresses -); -``` - -A second alternative would be to use [stacks-gen](https://github.com/psq/stacks-gen). This tool will generate all the keys you need in one place, including the values needed for calling the stacking contract, and also a WIF key for use with `bitcoind`. - -#### stacks-gen prerequisite - -Install [npx](https://github.com/npm/npx) if not already installed. (npx will check whether `` exists in \$PATH, or in the local project binaries, and execute that. If `` is not found, it will be installed prior to execution). - -``` -npm install -g npx -``` - -#### stacks-gen usage - -``` -npx -q stacks-gen sk --testnet - -{ - "phrase": "guide air pet hat friend anchor harvest dog depart matter deny awkward sign almost speak short dragon rare private fame depart elevator snake chef", - "private": "0351764dc07ee1ad038ff49c0e020799f0a350dd0769017ea09460e150a6401901", - "public": "022d82baea2d041ac281bebafab11571f45db4f163a9e3f8640b1c804a4ac6f662", - "stacks": "ST16JQQNQXVNGR8RZ1D52TMH5MFHTXVPHRV6YE19C", - "stacking": "{ hashbytes: 0x4d2bdeb7eeeb0c231f0b4a2d5225a3e3aeeed1c6, version: 0x00 }", - "btc": "mnYzsxxW271GkmyMnRfiopEkaEpeqLtDy8", - "wif": "cMh9kwaCEttgTQYkyMUYQVbdm5ZarZdBHErcq7mXUChXXCo7CFEh" -} -``` - -:::tip The stacking object with hashbytes and a version represents the bitcoin address derived from the Stacks address. Read more about the [bitcoin address format](stacking#bitcoin-address). ::: - -Full documentation available at [stacks-gen](https://github.com/psq/stacks-gen). - -## Querying - -### Get Stacks (STX) balance and nonce - -STX balance and nonce can be obtained through the [`GET /v2/accounts/`](https://docs.hiro.so/api#operation/get_account_info) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/accounts/' -``` - -Sample response: - -```js -{ - "balance": "0x0000000000000000002386f26f3f40ec", - "nonce": 17 -} -``` - -:::tip -The balance string represents an unsigned 128-bit integer (big-endian) in hex encoding -::: - -### Get all token balances - -All token balances can be obtained through the [`GET /extended/v1/address//balances`](https://docs.hiro.so/api#operation/get_account_balance) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/address//balances' -``` - -Sample response: - -```js -{ - "stx": { - "balance": "0", - "total_sent": "0", - "total_received": "0" - }, - "fungible_tokens": {}, - "non_fungible_tokens": {} -} -``` - -:::tip Stacks accounts cannot hold bitcoins. The best way to obtain corresponding BTC balances is to derive the BTC address from the Stacks address (using [`c32check`](https://github.com/stacks-network/c32check#c32tob58-b58toc32)) and query the Bitcoin network. ::: - -### Get all asset events - -All asset events associated with the account can be obtained through the [`GET /extended/v1/address//assets`](https://docs.hiro.so/api#operation/get_account_balance) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/address//assets' -``` - -Sample response: - -```js -{ - "limit": 20, - "offset": 0, - "total": 0, - "results": [ - { - "event_index": 5, - "event_type": "non_fungible_token_asset", - "asset": { - "asset_event_type": "transfer", - "asset_id": "ST2W14YX9SFVDB1ZGHSH40CX1YQAP9XKRAYSSVYAG.hello_world::hello-nft", - "sender": "SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR", - "recipient": "SM2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQVX8X0G", - "value": { - "hex": "0x0100000000000000000000000000000001", - "repr": "u1" - } - } - }, - { - "event_index": 3, - "event_type": "fungible_token_asset", - "asset": { - "asset_event_type": "mint", - "asset_id": "ST2W14YX9SFVDB1ZGHSH40CX1YQAP9XKRAYSSVYAG.hello_world::novel-token-19", - "sender": "", - "recipient": "SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR", - "amount": "12" - } - } - ] -} -``` diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/index.md b/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/index.md deleted file mode 100644 index 1533219df9..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/index.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Understand Stacks -description: Learn more about the Stacks 2.0 blockchain -sidebar_position: 1 ---- - -![](/img/SBC-L-2x-10.png) -## Introduction - -Stacks 2.0 is a layer-1 blockchain that connects to Bitcoin and brings smart contracts and decentralized apps to it. Smart contracts and apps developed on the Stacks platform are natively integrated with the security, stability, and economic power of Bitcoin. - -## Capabilities - -Read more about the features provided by the Stacks 2.0 blockchain. - - - -:::tip Check out the [technical specifications](technical-specs) for a brief overview ::: - - - - -A detailed [comparison of the Stacks blockchain to other blockchain technologies][] is available at the Stacks Foundation blog. -### Consensus mechanism -![](/img/pages/stacking.svg) Stacks 2.0 implements a new mining mechanism called Proof of Transfer ("PoX"). PoX is a consensus algorithm between two blockchains. It uses an established blockchain (in this case Bitcoin) to secure a new blockchain (Stacks). - -PoX connects to Bitcoin with a 1:1 block ratio, meaning anything that happens on the Stacks blockchain can be verified on the Bitcoin Blockchain. - -Instead of burning electricity on proof of work, PoX reuses already minted bitcoins as "proof of computation" and miners represent their cost of mining in bitcoins directly. - - -[Read more about Proof of Transfer](proof-of-transfer) -### Mining - -![](/img/pages/testnet-sm.svg) Mining is required to make the network usable, trustworthy, and secure. Miners verify incoming transactions, participate in the consensus mechanism, and write new blocks to the blockchain. - -To incentivize mining, miners receive freshly minted Stacks (STX) tokens if they win the bid for becoming the leader of the next round. - -[Read more about Mining](mining) - -### Stacking - -Bitcoins used for miner bids are sent to a set of specific addresses corresponding to Stacks (STX) tokens holders that are actively participating in consensus ("Stackers"). Thus, rather than being destroyed, the bitcoins consumed in the mining process go to productive Stacks holders as a reward based on their holdings of Stacks and participation in the Stacking algorithm. - -Stackers have to lock up their Stacks (STX) tokens for a certain period of time. - -[Read more about Stacking](stacking) - -### Smart contracts - -![](/img/pages/write-smart-contracts-sm.svg) Clarity is a new language for smart contracts on the Stacks 2.0 blockchain. The Clarity smart contract language optimizes for predictability and security. - -Stacks 2.0 anchors clarity smart contracts to Bitcoin making it possible for smart contracts to operate based on actions seen on the bitcoin blockchain. - -:::note The [Clarity open-source project](https://clarity-lang.org/) is supported by Stacks and [Algorand](https://www.algorand.com/) ::: - - -Clarity is distinct from other languages designed for writing smart contracts in a few ways: - -- **Predictability**: The Clarity language uses precise and unambiguous syntax that allows developers to predict exactly how their contracts will be executed. -- **Security**: The Clarity language allows users to supply their own conditions for transactions that ensure that a contract may never unexpectedly transfer a token owned by a user. -- **No compiler**: Contracts written in Clarity are broadcasted on the Stacks blockchain exactly as they are written by developers. This ensures that the code developers wrote, analyzed, and tested, is exactly what gets executed. - -[Read more about Clarity](../write-smart-contracts/clarity-language/) - -## Guides - -Read one of our guides to understand the ins and outs of the Stacks 2.0 blockchain. - -* [Account](../understand-stacks/accounts) -* [Transactions](../understand-stacks/transactions) -* [Network](../understand-stacks/network) -* [Microblocks](../understand-stacks/microblocks) - -[comparison of the Stacks blockchain to other blockchain technologies]: https://stacks.org/stacks-blockchain diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md b/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md deleted file mode 100644 index de64c617f4..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: Microblocks -description: Guide to Stacks Microblocks -sidebar_position: 8 ---- - -## Introduction - -Microblocks are a protocol-level feature of the Stacks blockchain that solve the technical challenge of transaction latency. Because each Stacks block is anchored to a Bitcoin block through the [Proof-of-Transfer consensus mechanism](../understand-stacks/proof-of-transfer), Stacks is necessarily limited to the same block times as the Bitcoin network. Microblocks allow the Stacks blockchain to perform state transitions between anchor blocks. - -Microblocks are a powerful mechanism for developers to create performant, high quality applications on Stacks, while still inheriting the security of Bitcoin. - -## Transaction states - -The [Stacks block production model](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.) is described in SIP-001. The standard outlines the mechanism by which elected block leaders can produce blocks on the Stacks blockchain either by batching transactions or by streaming them. Microblocks are the product of the streaming model. - -If a block leader has elected to mine microblocks, the leader selects transactions from the mempool and package them into microblocks during the current epoch. Microblocks are blocks of transactions included by a miner after the previous anchor block has been mined, but before the next block is selected. Transactions included in microblocks are processed by the network: their results are known. - -Consider a transaction from the perspective of the number of block confirmations it has. A transaction included in a microblock might have the following example lifecycle: - -``` -Transaction 1 is broadcast to the mempool. It has 0 confirmations. -Transaction 1 is included in a microblock. It still has 0 confirmations, but the results of the transaction are known -Transaction 1 is included in the next anchor block. It has 1 confirmation. -The next Stacks block confirms the previous block. Transaction 1 has 2 confirmations. -The next Stacks block confirms the previous block. Transaction 1 has 3 confirmations. -... -``` - -Consider a similar transaction that is not included in a microblock: - -``` -Transaction 2 is broadcast to the mempool. It has 0 confirmations. -Transaction 2 is included in the next anchor block. It has 1 confirmation. -The next Stacks block confirms the previous block. Transaction 2 has 2 confirmations. -The next Stacks block confirms the previous block. Transaction 2 has 3 confirmations. -``` - -The lifecycles of the two transactions are similar, but the difference is pending state. Many Bitcoin wallets display 0-confirmation balances: your wallet balance with any mempool transactions already applied. This is useful because it tells you when you've sent a transaction or received one. With smart contracts, displaying pending state is not as straightforward, because smart contracts do not just transfer inputs to outputs, they may call other contracts, emit events, or perform other computations. A transaction processed in a microblock generates all that information. - -:::tip -If a transaction is dependent on a chain state that could by altered by previous transactions with serious -implications, you should carefully consider whether it should be performed using microblocks. -::: - -## Enabling microblocks - -Miners can choose to enable or disable microblocks in their mining configuration. As a best practice, miners should enable microblock mining. When an application or user submits a transaction, the transaction can include an argument that requires the transaction to be in a microblock, an anchor block, or in either. - -### Transactions - -Transactions include an option that controls if a miner should include them in microblocks or in anchor blocks. The anchor mode transaction option is an optional argument that controls whether a transaction must be included in an anchor block or a microblock, or is eligible for either. - -### Mining - -Stacks miners must enable microblocks in their miner configuration to implement the block streaming model. For more information, see [mining microblocks](../understand-stacks/mining#microblocks). - -## Developing with microblocks - -In most cases, information from transactions included in microblocks should be treated like information from any other block. Wallets and explorers should display the consequences of microblock transactions as the current state of the network. This state should be acknowledged as tentative. - -A microblock transaction can end up being reorganized in the next block rather than just being confirmed as-is. Because of this, your UI should communicate to users if the outputs of a transaction changed, or if the transaction's associated block changed. This is the same outcome as if a 1-block fork occurred. - -### Stacks.js libraries - -Stacks.js provides the [AnchorMode][] argument on transaction objects so that your application can set the microblocks preference for transactions. - -### API - -:::danger API support for microblocks is a work-in-progress. Review the [API documentation][microblocks_api] carefully to ensure that you are up-to-date on the latest implementation details for microblocks. ::: - -The Stacks Blockchain API exposes microblocks through several endpoints. Please review the [Stacks Blockchain API guide][] for more details. - -## Best practices - -Working with microblocks is a design decision that you must make for your own application. When working with microblocks, the following best practices are recommended. - -### Handling nonce - -Nonce handling with microblocks is challenging because the next account nonce must take into account any nonce values included in microblocks, which may not yet be included in an anchor block. The Stacks Blockchain API [provides an endpoint][] to retrieve the next nonce for a given principal. - -### Application design - -The state of microblock transactions should be carefully communicated to users. No transaction is final until it's included in an anchor block, and your application design should reflect this. - -The following guidelines are provided as an initial set of best practices for UI design when incorporating microblocks into your application. - -#### Explorers - -Display pending state, but warn that a transaction is still pending. Indicate visually that displayed balances depend on pending state. - -#### Wallets - -Display pending state, but warn that a transaction is still pending. Indicate visually that displayed balances depend on pending state. - -#### Exchanges - -Continue to count confirmations, microblocks should be considered pending. - -#### Applications - -Microblock communication is highly app-dependent. For some applications, displaying a pending or 0-confirmation transaction as confirmed may be fine. For example, storing data on the chain, or querying the BNS contract. For other applications, such as the transfer of real value, waiting for 3-confirmations would be prudent before displaying the state as confirmed. - -[AnchorMode]: https://stacks.js.org/enums/transactions.AnchorMode.html -[Stacks Blockchain API guide]: https://docs.hiro.so/get-started/stacks-blockchain-api#microblocks-support -[provides an endpoint]: https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling -[microblocks_api]: https://docs.hiro.so/api#tag/Microblocks diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/mining.md b/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/mining.md deleted file mode 100644 index fa1f56ed3f..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/mining.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Mining -description: A guide to mining on Stacks 2.0 -sidebar_position: 4 ---- - -## Introduction - -This guide highlights some technical details related to mining on the Stacks 2.0 network. - -For steps on how to setup your own miner please refer to [miner on tesnet](nodes-and-miners/miner-testnet.md) and [miner on mainnet](nodes-and-miners/miner-testnet.md). - -## Mining frequency - -A new Stacks block may be mined once per Bitcoin block. To be considered for mining a block, a miner must have a block commit included in a Bitcoin block. If a miner wishes to update their commitment after submission, they may use Bitcoin Replace-By-Fee. - -## Coinbase rewards - -Miners receive coinbase rewards for blocks they win. - -The reward amounts are: - -- 1000 STX per block are released in the first 4 years of mining -- 500 STX per block are released during the following 4 years -- 250 STX per block are released during the following 4 years -- 125 STX per block are released from then on indefinitely. - -These "halvings" are synchronized with Bitcoin halvings. - -![coinbase rewards](/img/pages/coinbase-rewards.png) - -## Transaction fees - -Miners receive Stacks fees for transactions mined in any block they produce. - -For transactions mined in microblocks, the miner that produces the microblock receives 40% of the fees, while the miner that confirms the microblock receives 60% of the fees. - -## Reward maturity - -Block rewards and transaction fees take 100 blocks on the Bitcoin blockchain to mature. After successfully mining a block your rewards appear in your Stacks account after ~24 hours. - -## Mining with proof-of-transfer - -Miners commit Bitcoin to **two** addresses in every leader block commit. The amount committed to each address must be the same. The addresses are chosen from the current reward set of stacking participants. Addresses are chosen using a verifiable-random-function, and determining the correct two addresses for a given block requires monitoring the Stacks chain. - -![mining with pox](/img/pages/mining-with-pox.png) - -## 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, 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. - -While there is no minimum BTC commitment enforced by the protocol, in practice, there's a floor constrained by [dust](https://unchained-capital.com/blog/dust-thermodynamics/)": basically, if the fees for a transaction exceed the value of the spent output, it's considered dust. How dust is [calculated](https://github.com/bitcoin/bitcoin/blob/master/src/policy/policy.cpp#L14) depends on a number of factors, we've found 5,500 satoshis to be good lower bound per [output](https://learnmeabitcoin.com/technical/output). Bitcoin transactions from Stacks miners contain two outputs (for Proof-of-Transfer), so a commitment of at least 11,000 satoshis / block is recommended. - -To calculate the amount of BTC to send miners should: - -- Guess the price BTC/STX for the next day (100 blocks later) -- Guess the total amount of BTCs committed by all miners - -## Microblocks - -The Stacks blockchain produces blocks at the same rate as the Bitcoin blockchain. In order to provide lower latency transactions, miners can opt to enable microblocks. Microblocks allow the current block leader to stream transactions and include their state transitions in the current epoch. - -If a block leader opts to produce microblocks, the next leader builds the chain tip off the last microblock that the current leader produces. - -The block streaming model is described in [SIP-001][]. - -[SIP-001]: https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md#operation-as-a-leader diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/network.md b/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/network.md deleted file mode 100644 index 6efcc385ec..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/network.md +++ /dev/null @@ -1,148 +0,0 @@ ---- -title: Network -description: Guide to the Stacks 2.0 network -sidebar_position: 7 ---- - -## Tokens - -Stacks (STX) tokens are the native tokens on the Stacks 2.0 blockchain. The smallest fraction is one micro-STX. 1,000,000 micro-STX make one Stacks (STX). - -STX amounts should be stored as integers (8 bytes long), and represent the amount of micro-STX. For display purposes, micro-STX are divided by 1,000,000 (decimal precision of 6). - -## 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 in bytes. The fee rate is a market determined variable. For the [testnet](testnet), it is set to 1 micro-STX. - -Fee estimates can obtained through the [`GET /v2/fees/transfer`](https://docs.hiro.so/api#operation/get_fee_transfer) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/fees/transfer' -``` - -The API will respond with the fee rate (as integer): - -```json -1 -``` - -[The Stacks Transactions JS library](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) supports fee estimation for: - -- token transfers (`estimateTransfer`) -- contract deploys (`estimateContractDeploy`) -- non read-only contract calls (`estimateContractFunctionCall`) - -:::tip For an implementation using a different language than JavaScript, please review [this reference implementation](https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/src/builders.ts#L97). ::: - -## Nonces - -Every account carries a [nonce property](https://en.wikipedia.org/wiki/Cryptographic_nonce) that indicates the number of transactions processed for the given account. Nonces are one-time codes, starting at `0` for new accounts, and incremented by 1 on every transaction. - -Nonces are added to all transactions and help identify them in order to ensure transactions are processed in order and to avoid duplicated processing. - -:::tip -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 is constructed, the most recent nonce of the account needs to fetched and set. - -:::tip The API provides an endpoint to [simplify nonce handling](https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling). ::: - -## Confirmations - -The Stacks 2.0 network is anchored onto the bitcoin network. This allows transactions on Stacks to inherit the same finality and security of the Bitcoin blockchain. - -The time to mine a block, to confirm transactions, will eventually match the expected "block time" of the bitcoin network: 10 minutes. - -:::tip Transactions can also be mined in [microblocks](microblocks), reducing the latency significantly. ::: - -The block time is hardcoded and will change throughout the implementation phases of the [testnet](testnet). The current block time can be obtained through the [`GET /extended/v1/info/network_block_times`](https://docs.hiro.so/api#operation/get_network_block_times) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/info/network_block_times' -``` - -The API will respond with the block time (in seconds): - -```js -{ - "testnet": { - "target_block_time": 120 - }, - "mainnet": { - "target_block_time": 600 - } -} -``` - -## Read-only function calls - -Smart contracts can expose public function calls. For functions that make state modifications to the blockchain, transactions need to be generated and broadcasted. - -However, for read-only function calls, transactions are **not** required. Instead, these calls can be done using the [Stacks Blockchain API](https://docs.hiro.so/get-started/stacks-blockchain-api). - -:::tip -Read-only function calls do not require transaction fees -::: - -A read-only contract call can be done using the [`POST /v2/contracts/call-read///`](https://docs.hiro.so/api#operation/call_read_only_function) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl --location --request POST 'https://stacks-node-api.testnet.stacks.co/v2/contracts/call-read///' \ ---header 'Content-Type: application/json' \ ---data-raw '{ - "sender": ".", - "arguments": [, ...] -}' -``` - -Sample response for a successful call: - -```js -{ - "okay": true, - "result": "" -} -``` - -:::tip To set the function call arguments and read the result, [Clarity values](../write-smart-contracts/values) need to be serialized into a hexadecimal string. The [Stacks Transactions JS](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library supports these operations ::: - -## Querying - -Stacks 2.0 network details can be queried using the [Stacks Blockchain API](https://docs.hiro.so/get-started/stacks-blockchain-api). - -### Health check - -The [status checker](https://stacks-status.com/) is a service that provides a user interface to quickly review the health of the Stacks 2.0 blockchain. - -### Network info - -The network information can be obtained using the [`GET /v2/info`](https://docs.hiro.so/api#operation/get_core_api_info) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/info' -``` - -Sample response: - -```js -{ - "peer_version": 385875968, - "burn_consensus": "826401d65cf3671210a3fb135d827d549c0b4d37", - "burn_block_height": 1972, - "stable_burn_consensus": "e27ea23f199076bc41a729d76a813e125b725f64", - "stable_burn_block_height": 1971, - "server_version": "blockstack-core 0.0.1 => 23.0.0.0 (master:bdd042242+, release build, linux [x86_64]", - "network_id": 2147483648, - "parent_network_id": 3669344250, - "stacks_tip_height": 933, - "stacks_tip": "1f601823fbcc5b6b2215b2ff59d2818fba61ee4a3cea426d8bc3dbb268005d8f", - "stacks_tip_burn_block": "54c56a9685545c45accf42b5dcb2787c97eda8185a1c794daf9b5a59d4807abc", - "unanchored_tip": "71948ee211dac3b241eb65d881637f649d0d49ac08ee4a41c29217d3026d7aae", - "exit_at_block_height": 28160 -} -``` diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md b/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md deleted file mode 100644 index 4264616742..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Proof of Transfer -description: Understand the proof-of-transfer consensus mechanism -sidebar_position: 3 ---- - -## Overview - -Consensus algorithms for blockchains require compute or financial resources to secure the blockchain. The general practice of decentralized consensus is to make it practically infeasible for any single malicious actor to have enough computing power or ownership stake to attack the network. - -Popular consensus mechanisms in modern blockchains include proof-of-work, in which nodes dedicate computing resources, and proof-of-stake, in which nodes dedicate financial resources to secure the network. - -Proof-of-burn is a novel consensus mechanism where miners compete by ‘burning’ (destroying) a proof-of-work cryptocurrency as a proxy for computing resources. - -Proof-of-transfer (PoX) is an extension of the proof-of-burn mechanism. 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. - -![PoX mechanism](/img/pox-mechanism.png) - -This allows network participants to secure the PoX cryptocurrency network and earn a reward in the base cryptocurrency. Thus, proof-of-transfer blockchains are anchored on their chosen proof-of-work chain. Stacks uses [Bitcoin](#why-bitcoin) as its anchor chain. - -![PoX participants](/img/pox-participants.png) - -## Why Bitcoin? - -There are a number of reasons that Stacks chose Bitcoin as the blockchain to power consensus. It's the oldest blockchain protocol, having launched in 2009, and has become a recognized asset outside of the cryptocurrency community. BTC has held the highest market capitalization of any cryptocurrency for the past decade. - -Bitcoin champions simplicity and stability, and has stood the test of time. Influencing or attacking the network is infeasible or impractical for any potential hackers. It's one of the only cryptocurrencies to capture public attention. Bitcoin is a household name, and is recognized as an asset by governments, large corporations, and legacy banking institutions. Lastly, Bitcoin is largely considered a reliable store of value, and provides extensive infrastructure to support the proof-of-transfer consensus mechanism. - -SIP-001 provides a full [list of reasons why Bitcoin was chosen to secure Stacks](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md). - -![btc-stacks](/img/pox-why-bitcoin.png) - -## Blocks and microblocks - -The Stacks blockchain allows for increased transaction throughput using a mechanism called microblocks. Bitcoin and Stacks progress in lockstep, and their blocks are confirmed simultaneously. On Stacks, this is referred to as an ‘anchor block’. An entire block of Stacks transactions corresponds to a single Bitcoin transaction. This significantly improves cost/byte ratio for processing Stacks transactions. Because of simultaneous block production, Bitcoin acts as a rate-limiter for creating Stacks blocks, thereby preventing denial-of-service attacks on its peer network. - -However, in between Stacks anchor blocks settling on the Bitcoin blockchain, there are also a varying number of microblocks that allow rapid settlement of Stacks transactions with a high degree of confidence. This allows Stacks transaction throughput to scale independently of Bitcoin, while still periodically establishing finality with the Bitcoin chain. The Stacks blockchain adopts a block streaming model whereby each leader can adaptively select and package transactions into their block as they arrive in the mempool. Therefore when an anchor block is confirmed, all of the transactions in the parent microblock stream are packaged and processed. This is an unprecedented method for achieving scalability without creating a totally separate protocol from Bitcoin. - -![stx-microblock](/img/stx-microblocks.png) - -## Unlocking Bitcoin capital - -Stacks also unlocks the hundreds of billions in capital in Bitcoin, and gives Bitcoiners new opportunities to use and earn BTC. Stacks is a accompaniment to the Bitcoin ecosystem, and the two networks working in tandem enables totally novel ways of using BTC. The Stacks ecosystem makes interactive cryptocurrency applications available to Bitcoin holders. Additionally, by stacking STX tokens and participating in the PoX consensus mechanism, users have the opportunity to earn BTC while securing the Stacks chain. - -![Unlocking Bitcoin](/img/pox-unlocking-btc.png) - -## Clarity and the Bitcoin state - -Clarity smart contracts also have unique visibility into the state of the Bitcoin blockchain. This means that contract logic in a Clarity file has the ability to trigger when specific Bitcoin transactions are confirmed. Clarity smart contracts have a built in Simple Payment Verification (SPV) proofs for Bitcoin that make interacting with Bitcoin’s state much simpler for developers. Additionally, Clarity contracts can fork with the original Bitcoin chain. Therefore, in an edge case where Bitcoin forks, developers wouldn’t have to worry about adjusting the deployment of their smart contracts. - -## See also - -- [Read the full PoX whitepaper](https://community.stacks.org/pox) -- [Watch Executive Chair of Hiro Muneeb Ali and Evangelist Joe Bender give an overview of Stack's breakthrough PoX mining mechanism](https://www.youtube.com/watch?v=NY_eUrIcWOY) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md b/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md deleted file mode 100644 index 5f3863e8dd..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: Stacking -description: Introduction to the reward mechanism of Proof-of-Transfer -sidebar_position: 9 ---- - -## Introduction - -Stacking rewards Stacks (STX) token holders with bitcoin for providing a valuable service to the network by locking up their tokens for a certain time. - -![](/img/stacking.png) - -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. - -:::info The Stacking consensus algorithm is implemented as a smart contract, using [Clarity](../write-smart-contracts/). [Read more about the contract](../noteworthy-contracts/stacking-contract). ::: - -## Stacking flow - -The Stacking mechanism can be presented as a flow of actions: - -![Stacking flow](/img/stacking-illustration.png) - -1. Make API calls to get details about the upcoming reward cycle -2. For a specific Stacks account, confirm eligibility -3. Confirm the BTC reward address and the lockup duration -4. The transaction is broadcasted and the STX tokens are locked. This needs to happen before the prepare phase of the next reward cycle, the last 100 Bitcoin blocks of the ongoing reward phase -5. The Stacking mechanism executes reward cycles and sends out rewards to the set BTC reward address -6. During the lockup period, details about unlocking timing, rewards and more can be obtained -7. Once the lockup period is passed, the tokens are released and accessible again -8. Display reward history, including details like earnings for previous reward cycles - -:::info Keep in mind that the target duration for a reward cycles is ~2 weeks. This duration is based on the target block time of the network (10 minutes) and can be higher at times due to [confirmation time variances](https://www.blockchain.com/charts/median-confirmation-time) of the bitcoin network. ::: - -## Stacking delegation flow - -The Stacking flow is different for delegation use cases: - -![Delegated tacking flow](/img/stacking-delegation-illustration.png) - -- Before Stacking can be initiated for a token holder, the delegator needs to be granted permission to Stack on behalf of the account owner. The permission is restricted to the maximum amount the delegator is allowed to Stack. The maximum amount is not limited by the available funds and can be set much higher. An account can only be associated with one single delegator -- The account has to define the delegation relationship. They can optionally restrict the Bitcoin reward address that must be used for payouts, and the expiration burn block height for the permission, thus limiting the time a delegator has permission to Stack -- Delegators have to lock Stacks from different accounts ("pooling phase") until they reach the minimum amount of Stacks required to participate in Stacking -- Once a delegator locks enough STX tokens, they can finalize and commit their participation in the next reward cycle -- Certain delegation relationships may allow the STX holder to receive the payout directly from the miner (step 5/6) -- The termination of the delegation relationship can either happen automatically based on set expiration rules or by actively revoking delegation rights - -## PoX mining - -PoX mining is a modification of Proof-of-Burn (PoB) mining, where instead of sending the committed Bitcoin to a burn address, it's transferred to eligible STX holders that participate in the stacking protocol. - -:::note -A PoX miner can only receive newly minted STX tokens when they transfer Bitcoin to eligible owners of STX tokens -::: - -![Mining flow](/img/pox-mining-flow.png) - -Miners run Stacks nodes with mining enabled to participate in the PoX mechanism. The node implements the PoX mechanism, which ensures proper handling and incentives through four key phases: - -- Registration: miners register for a future election by sending consensus data to the network -- Commitment: registered miners transfer Bitcoin to participate in the election. Committed BTC are sent to a set participating STX token holders -- Election: a verifiable random function chooses one miner to write a new block on the Stacks blockchain -- Assembly: the elected miner writes the new block and collects rewards in form of new STX tokens - -## Token holder eligibility - -Stacks (STX) token holders don't automatically receive stacking rewards. Instead, they must: - -- Commit to participation before a reward cycle begins -- Commit the minimum amount of STX tokens to secure a reward slot, or pool with others to reach the minimum -- Lock up STX tokens for a specified period -- Provide a supported Bitcoin address to receive rewards (native segwit is not supported) - -The following diagram describes how the minimum STX tokens per slot is determined. More information on [dynamic minimums for stacking](https://stacking.club) is available at stacking.club. - -![Dynamic minimum for individual eligibility](/img/stacking-dynamic-minimum.png) - -Token holders have a variety of providers and tools to support their participation in Stacking. The Stacks website contains a [list of stacking providers and pools](https://stacks.org/stacking#earn). - -## Stacking in the PoX consensus algorithm - -Stacking is a built-in capability of PoX and occurs through a set of actions on the Stacks blockchain. The [full proof-of-transfer implementation details](https://github.com/stacks-network/stacks-blockchain/blob/develop/sip/sip-007-stacking-consensus.md) are in SIP-007. Below is a summary of the most relevant actions of the algorithm. - -![PoX cycles](/img/pox-cycles.png) - -- Stacking happens over reward cycles with a fixed length. In each reward cycle, a set of Bitcoin addresses associated with stacking participants receive BTC rewards -- A reward cycle consists of two phases: prepare and reward -- During the prepare phase, miners decide on an anchor block and a reward set. Mining any descendant forks of the anchor block requires transferring mining funds to the appropriate reward addresses. The reward set is the set of Bitcoin addresses which are eligible to receive funds in the reward cycle -- Miners register as leader candidates for a future election by sending a key transaction that burns cryptocurrency. The transaction also registers the leader's preferred chain tip (must be a descendant of the anchor block) and commitment of funds to 2 addresses from the reward set -- Token holders register for the next rewards cycle by broadcasting a signed message that locks up associated STX tokens for a protocol-specified lockup period, specifies a Bitcoin address to receive the funds, and votes on a Stacks chain tip -- Multiple leaders can commit to the same chain tip. The leader that wins the election and the peers who also burn for that leader collectively share the reward, proportional to how much each one burned -- Token holders' locked up tokens automatically unlock as soon as the lockup period finishes - -## Bitcoin address - -:::danger You must provide a BTC address in one of two formats: - -* [Legacy (P2PKH)](https://en.bitcoin.it/wiki/Transaction#Pay-to-PubkeyHash), which starts with `1`. - -* [Segregated Witness / Segwit (P2SH)](https://en.bitcoin.it/wiki/Pay_to_script_hash), which starts with `3`. The "Native Segwit" format (which starts with `bc1`), for example, is not supported. ::: - -The Stacking contract needs a special format for the Bitcoin address (the reward address). This is required to ensure that miners are able to correctly construct the Bitcoin transaction containing the reward address. - -The address must be specified in the following format using the Clarity language: - -```clar -;; a tuple of a version and hashbytes buffer -(pox-addr (tuple (version (buff 1)) (hashbytes (buff 20)))) -``` - -The `version` buffer must represent what kind of bitcoin address is being submitted. It can be one of the following: - -```js -SerializeP2PKH = 0x00, // hash160(public-key), same as bitcoin's p2pkh -SerializeP2SH = 0x01, // hash160(multisig-redeem-script), same as bitcoin's multisig p2sh -SerializeP2WPKH = 0x02, // hash160(segwit-program-00(p2pkh)), same as bitcoin's p2sh-p2wpkh -SerializeP2WSH = 0x03, // hash160(segwit-program-00(public-keys)), same as bitcoin's p2sh-p2wsh -``` - -The `hashbytes` are the 20 hash bytes of the bitcoin address. You can obtain that from a bitcoin library, for instance using [`bitcoinjs-lib`](https://github.com/bitcoinjs/bitcoinjs-lib): - -```js -const btc = require('bitcoinjs-lib'); -console.log( - '0x' + btc.address.fromBase58Check('1C56LYirKa3PFXFsvhSESgDy2acEHVAEt6').hash.toString('hex') -); -``` - -## Choosing the right Stacking strategy - -[Here](https://blog.stacks.co/stacking-strategy) is an interesting article that may help you choose the right Stacking stategy. - - -## Where to Stacks? - -You can Stack on your own, on a pool or on an exchange: -### Stacking on your own - -Stacking on your own is non-custodial. - -Stacking on your own requires a protocol minimum (amount changes but about 100,000 STX). - -[Hiro Wallet](https://www.hiro.so/wallet) allows stacking on your own. - -### Stacking on a pool - -Stacking on a pool allows Stacking without the requirement of the protocol minumum. - -Some available pools are: - -| Pool | Type | Pays rewards in | Fee | Minimum amount | -| --------------------------------------------------- | ------------- |:---------------:| --- |:--------------:| -| [Friedger's Pool](https://pool.friedger.de/) | Non custodial | STX or xBTC | No | 40 STX | -| [Planbetter](https://planbetter.org/) | Non custodial | BTC | 5% | 200 STX | -| [Stacked](https://staking.staked.us/stacks-staking) | Non custodial | BTC | | 100,000 STX | -| [Xverse](https://www.xverse.app/) | Non custodial | BTC | No | 100 STX | - -### Stacking on an exchange - -Stacking on an exchange is custodial, meaning you are trusting the exchange with your Stacks. - -Several exchanges allow Stacking directly on their sites. Examples are [Okcoin](https://www.okcoin.com) and [Binance](https://www.binance.com/en/staking) - -## Stacking statistics - -You can view all sorts of Stacking data and statistics on [Stacking Club](https://stacking.club) \ No newline at end of file diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md b/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md deleted file mode 100644 index d942d6af8f..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Stacks Blockchain API -description: Interacting with the Stacks 2.0 Blockchain via API ---- - -## Temporal page because of a Crowdin bug \ No newline at end of file diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md b/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md deleted file mode 100644 index e370129d1d..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Technical Specifications -description: Summary of technical specifications of Stacks 2.0 -sidebar_position: 10 ---- - -## Consensus - -- Proof of Transfer (PoX) as described in [SIP-007](https://github.com/stacksgov/sips/blob/main/sips/sip-007/sip-007-stacking-consensus.md) -- Network will transition to Proof of Burn (PoB) as described in [SIP-001](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md) after 10 years. [Learn more about Proof-of-Burn in SIP-001](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md). -- Threat model - - 51% of malicious Stacks mining power can perform a double-spend attack - - 51% of malicious Bitcoin mining power can reorg the Stacks chain -- Different actors and their roles - - Stacks Miners package transactions into blocks, mine them through a Bitcoin transaction, propagate them, and if they win the block race, append microblocks to their winning block until the next block is mined. The next block confirms the microblock stream. - - Stacks Holders may alter the calculation of block limits (subject to a miner veto) and may vote to disable Proof-of-Transfer rewards for a reward cycle. -- Transactions are considered final when the corresponding "block commit" transaction on Bitcoin is finalized. Typically this can by 3-6 confirmations. -- For more details, see [Proof of Transfer](proof-of-transfer). - -## Proof of Transfer Mining - -- Coinbase reward schedule: - - 1000 STX/block for first 4 years - - 500 STX/block for following 4 years - - 250 STX/block for subsequent 4 years - - 125 STX/block in perpetuity after that -- Coinbase rewards accumulate for "missed sortitions": If a Bitcoin block has no sortition (at height N), then any Stacks block mined in a subsequent sortition that builds off of any Stacks chain tip that existed at the penultimate sortition (at height N-1) may claim its coinbase. This encourages miners to keep mining even if Bitcoin fees are high. -- Initial mining bonus: This is a special case of the above to incentivize early miners. Coinbase for all burnchain blocks between the first burn block height (to be chosen by independent miners as part of the Stacks 2.0 launch) and the first sortition winner accumulate and are distributed to miners over a fixed window (to be determined). For instance, say burn block height is 10,000 and first sortition is at block 10500 and distribution window is 100 blocks, then coinbase for the first 500 blocks (10,500 - 10,000) will be distributed evenly to miners who win sortition over the subsequent 100 blocks. -- 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 at least 11,000 satoshis (5,500 sats / [UTXO output](https://learnmeabitcoin.com/technical/utxo)); 2 outputs / block) to avoid "dust." -- For more details, see [Mining](mining). - -## Stacking - -- Stacking works in 2 phases - 1. Prepare phase: In this phase an "anchor block" is chosen. The qualifying set of addresses ("reward set") is determined based on the snapshot of the chain at the anchor block. Length of prepare phase is 100 blocks. Stacking commitments need to be confirmed before this phase starts - 2. Reward phase: In this phase miner BTC commitments are distributed amongst the reward set. Reward cycle length is 2000 BTC blocks (~2 weeks). -- 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/stacksgov/sips/blob/main/sips/sip-007/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.stacks.co/references/stacking-contract#delegate-stx). -- Only two types of BTC reward addresses are supported: [Legacy (P2PKH)](https://en.bitcoin.it/wiki/Transaction#Pay-to-PubkeyHash) or [Segregated Witness / Segwit (P2SH)](https://en.bitcoin.it/wiki/Pay_to_script_hash). Native Segwit is not supported. -- Further reading: [Stacking](stacking) - -## Accounts and Addresses - -- Transactions in the Stacks blockchain originate from, are paid for by, and execute under the authority of accounts -- An account is fully specified by its address + nonce + assets -- 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 (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](accounts) - -## Transactions - -- Transaction 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 - 2. _paying account_ is the account that is billed by the leader for the cost of validating and executing the transaction - 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 -- Transactions can be batched or streamed into blocks. The behavior can be controlled by the anchor mode of a transaction. With streaming ([microblocks](microblocks)), a faster confirmation time is possible. -- 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. -- Mempool limit for concurrent pending transactions is 25 per account -- Pending mempool transactions will be garbage-collected [256 blocks after receipt](https://github.com/stacks-network/stacks-blockchain/blob/master/src/core/mempool.rs#L62). With 10 minutes target block time, this would equal ~42 hours -- [Learn more about transaction encoding in SIP-005](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md#transaction-encoding) -- [Transaction signing and verification are described in SIP-005](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md#transaction-signing-and-verifying) -- All transactions impacting account balance are atomic, a transfer operation can not increment one account’s balance without decrementing another’s. However, transactions that perform multiple account actions (for example, transferring from multiple accounts) may partially complete. -- Transactions can include a memo string (max 34 bytes) - -## See also - -- [Read the full Stacks 2.0: Apps and Smart Contracts for Bitcoin whitepaper](https://cloudflare-ipfs.com/ipfs/QmaGgiVHymeDjAc3aF1AwyhiFFwN97pme5m536cHT4FsAW). - -- [Watch Aaron Blankstein video on Stacks whitepater v2](https://www.youtube.com/watch?v=Wd-Bfe8Sn-Y). \ No newline at end of file diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md b/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md deleted file mode 100644 index 59934a5bde..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Testnet -description: Test your smart contracts and apps -sidebar_position: 2 ---- - -## About testnet - -The testnet is a separate blockchain from the Stacks mainnet analogous to a staging environment. It's a network used by developers to test their apps, smart contracts, or changes to the protocol in a production-like environment. It produces blocks at roughly the same rate as mainnet; about 1 block every 10 minutes on average. The Stacks testnet is rarely reset. - -### Faucet - -The testnet faucet provides you with free Stacks Token (STX) to test with. These are not the same as STX on mainnet and have no value. You can get STX from the faucet on the [Stacks Explorer Sandbox](https://explorer.stacks.co/sandbox/faucet?chain=testnet), or using the [API](https://docs.hiro.so/api#tag/Faucets). - -To get STX tokens from within the Explorer Sandbox, navigate to the "Faucet" tab on the left and click "Request STX" button. - -![](/img/stx_faucet.png) - -You can also try out [Stacking](stacking) by clicking on `I want to stack`. - -:::note -The Explorer Sandbox requires you to login with a Stacks wallet -::: - -### Testnet API - -The hosted Stacks Blockchain API for the testnet is available at this base URL: - -```shell -https://stacks-node-api.testnet.stacks.co/ -``` - -![](/img/api_testnet_status.png) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md b/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md deleted file mode 100644 index 2ff6072384..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Transactions -description: Guide to Stacks 2.0 transactions -sidebar_position: 6 ---- - -## Introduction - -Transactions are the fundamental unit of execution in the Stacks blockchain. Each transaction is originated from a [Stacks 2.0 account](accounts), and is retained in the Stacks blockchain history for eternity. This guide helps you understand Stacks 2.0 transactions. - -## Lifecycle - -Transactions go through phases before being finally confirmed, and available for all, on the Stacks 2.0 network. - -![Transaction lifecycle](/img/tx-lifecycle.png) - -- **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/en/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. - -:::note A transaction can have one of three states once it is registered: `pending`, `success`, or `failed`. ::: - -## Types - -The Stacks 2.0 supports a set of different transaction types: - -| **Type** | **Value** | **Description** | -| ----------------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Coinbase | `coinbase` | The first transaction in a new block (an entity holding several transactions). Used to register for block rewards. These are not manually generated and broadcasted like other types of transactions. | -| Token transfer | `token_transfer` | Asset transfer from a sender to a recipient | -| Contract deploy | `smart_contract` | Contract instantiation | -| Contract call | `contract_call` | Contract call for a public, non read-only function | -| Poison Microblock | `poison_microblock` | Punish leaders who intentionally equivocate about the microblocks they package | - -A sample of each transaction type can be found in the [Stacks Blockchain API response definition for transactions](https://docs.hiro.so/api#operation/get_transaction_by_id). - -:::caution Read-only contract call calls do **not** require transactions. Read more about it in the [network guide](network#read-only-function-calls). ::: diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md b/i18n/vi/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md deleted file mode 100644 index fd45c80583..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: Clarity Language -description: Overview of the Clarity language constructs -sidebar_label: Clarity Language -tags: - - clarity ---- - -## Clarity Type System - -The Clarity language uses a strong static type system. Function arguments and database schemas require specified types, and use of types is checked during contract launch. The type system does _not_ have a universal super type. - -## Public Functions - -Functions specified via `define-public` statements are _public_ functions and these are the only types of functions which may be called directly through signed blockchain transactions. In addition to being callable directly from a transaction (see the Stacks wire formats for more details on Stacks transactions), public functions may be called by other smart contracts. - -Public functions _must_ return a `(response ...)` type. This is used by Clarity to determine whether or not to materialize any changes from the execution of the function. If a function returns an `(err ...)` type, any mutations on the blockchain state from executing the function (and any function that it called during execution) will be aborted. - -In addition to functions defined via `define-public`, contracts may expose read-only functions. These functions, defined via `define-read-only`, are callable by other smart contracts, and may be queryable via public blockchain explorers. These functions _may not_ mutate any blockchain state. Unlike normal public functions, read-only functions may return any type. - -## Contract Calls - -A smart contract may call functions from other smart contracts using a `(contract-call?)` function. - -This function returns a response type result -- the return value of the called smart contract function. - -We distinguish 2 different types of `contract-call?`: - -### Static dispatch - -The callee is a known, invariant contract available on-chain when the caller contract is deployed. In this case, the callee's principal is provided as the first argument, followed by the name of the method and its arguments: - -```clarity -(contract-call? - .registrar - register-name - name-to-register) -``` - -### Dynamic dispatch - -The callee is passed as an argument, and typed as a trait reference (``). - -```clarity -(define-public (swap (token-a ) - (amount-a uint) - (owner-a principal) - (token-b ) - (amount-b uint) - (owner-b principal))) - (begin - (unwrap! (contract-call? token-a transfer-from? owner-a owner-b amount-a)) - (unwrap! (contract-call? token-b transfer-from? owner-b owner-a amount-b)))) -``` - -Traits can either be locally defined: - -```clarity -(define-trait can-transfer-tokens ( - (transfer-from? (principal principal uint) (response uint))) -``` - -Or imported from an existing contract: - -```clarity -(use-trait can-transfer-tokens - .contract-defining-trait.can-transfer-tokens) -``` - -Looking at trait conformance, callee contracts have two different paths. They can either be "compatible" with a trait by defining methods matching some of the methods defined in a trait, or explicitly declare conformance using the `impl-trait` statement: - -```clarity -(impl-trait .contract-defining-trait.can-transfer-tokens) -``` - -Explicit conformance should be prefered when adequate. It acts as a safeguard by helping the static analysis system to detect deviations in method signatures before contract deployment. - -The following limitations are imposed on contract calls: - -1. On static dispatches, callee smart contracts _must_ exist at the time of creation. -2. No cycles may exist in the call graph of a smart contract. This prevents recursion (and re-entrancy bugs). Such structures can be detected with static analysis of the call graph, and will be rejected by the network. -3. `contract-call?` are for inter-contract calls only. Attempts to execute when the caller is also the callee will abort the transaction. diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md b/i18n/vi/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md deleted file mode 100644 index 4605b2f4c9..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md +++ /dev/null @@ -1,1385 +0,0 @@ ---- -title: Functions -description: See a detailed list of all functions for the Clarity language. -tags: - - clarity ---- - -## Functions - -Detailed list of all functions for the Clarity language. - -### + (add) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(+ i1 i2...)` -#### description: -Adds a variable number of integer inputs and returns the result. In the event of an _overflow_, throws a runtime error. -#### example: -```clarity -(+ 1 2 3) ;; Returns 6 -(+ 2 3) ;; Returns 5 -(+ 1 2 3 4) ;; Returns 10 -(+ 9 -3) ;; Returns 6 -(+ -3 -2) ;; Returns -5 -``` - -### - (subtract) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(- i1 i2...)` -#### description: -Subtracts a variable number of integer inputs and returns the result. In the event of an _underflow_, throws a runtime error. -#### example: -```clarity -(- 2 1 1) ;; Returns 0 -(- 0 3) ;; Returns -3 -(- 5 -3) ;; Returns 8 -(- -4 -5) ;; Returns 1 -``` - -### * (multiply) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(* i1 i2...)` -#### description: -Multiplies a variable number of integer inputs and returns the result. In the event of an _overflow_, throws a runtime error. -#### example: -```clarity -(* 2 3) ;; Returns 6 -(* 5 2) ;; Returns 10 -(* 2 2 2) ;; Returns 8 -(* 3 -2) ;; Returns -6 -(* -1 -2) ;; Returns 2 -``` - -### / (divide) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(/ i1 i2...)` -#### description: -Divides a variable number of integer inputs and returns the _integer part_ of the result. In the event of _division by zero_, throws a runtime error. - -#### example: -```clarity -(/ 2 3) ;; Returns 0 -(/ 5 2) ;; Returns 2 -(/ 4 2 2) ;; Returns 1 -(/ -10 2) ;; Returns -5 -(/ -8 -2) ;; Returns 4 -(/ -9 4) ;; Returns -2 -``` - -### >= (greater than or equal) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(>= i1 i2)` -#### description: -Compares two integers, returning `true` if `i1` is greater than or equal to `i2` and `false` otherwise. -#### example: -```clarity -(>= 1 1) ;; Returns true -(>= 5 2) ;; Returns true -``` - -### <= (less than or equal) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(<= i1 i2)` -#### description: -Compares two integers, returning true if `i1` is less than or equal to `i2` and `false` otherwise. -#### example: -```clarity -(<= 1 1) ;; Returns true -(<= 5 2) ;; Returns false -``` - -### < (less than) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(< i1 i2)` -#### description: -Compares two integers, returning `true` if `i1` is less than `i2` and `false` otherwise. -#### example: -```clarity -(< 1 2) ;; Returns true -(< 5 2) ;; Returns false -``` - -### > (greater than) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(> i1 i2)` -#### description: -Compares two integers, returning `true` if `i1` is greater than `i2` and false otherwise. -#### example: -```clarity -(> 1 2) ;; Returns false -(> 5 2) ;; Returns true -``` - -### to-int -#### input: `uint` -#### output: `int` -#### signature: `(to-int u)` -#### description: -Tries to convert the `uint` argument to an `int`. Will cause a runtime error and abort if the supplied argument is >= `pow(2, 127)`` -#### example: -```clarity -(to-int u238) ;; Returns 238 -``` - -### to-uint -#### input: `int` -#### output: `uint` -#### signature: `(to-uint i)` -#### description: -Tries to convert the `int` argument to a `uint`. Will cause a runtime error and abort if the supplied argument is negative. -#### example: -```clarity -(to-uint 238) ;; Returns u238 -``` - -### mod -#### input: `int, int | uint, uint` -#### output: `int | uint` -#### signature: `(mod i1 i2)` -#### description: -Returns the integer remainder from integer dividing `i1` by `i2`. In the event of a division by zero, throws a runtime error. -#### example: -```clarity -(mod 2 3) ;; Returns 2 -(mod 5 2) ;; Returns 1 -(mod 7 1) ;; Returns 0 -``` - -### pow -#### input: `int, int | uint, uint` -#### output: `int | uint` -#### signature: `(pow i1 i2)` -#### description: -Returns the result of raising `i1` to the power of `i2`. In the event of an _overflow_, throws a runtime error. -#### example: -```clarity -(pow 2 3) ;; Returns 8 -(pow 2 2) ;; Returns 4 -(pow 7 1) ;; Returns 7 -``` - -### sqrti -#### input: `int | uint` -#### output: `int | uint` -#### signature: `(sqrti n)` -#### description: -Returns the largest integer that is less than or equal to the square root of `n`. Fails on a negative numbers. -#### example: -```clarity -(sqrti u11) ;; Returns u3 -(sqrti 1000000) ;; Returns 1000 -(sqrti u1) ;; Returns u1 -(sqrti 0) ;; Returns 0 -``` - -### log2 -#### input: `int | uint` -#### output: `int | uint` -#### signature: `(log2 n)` -#### description: -Returns the _integer part_ of the power to which the number 2 must be raised to obtain the value `n`. Fails on zero or a negative number. -#### example: -```clarity -(log2 u8) ;; Returns u3 -(log2 8) ;; Returns 3 -(log2 u1) ;; Returns u0 -(log2 1000) ;; Returns 9 -``` - -### xor -#### input: `int, int | uint, uint` -#### output: `int | uint` -#### signature: `(xor i1 i2)` -#### description: -Returns the result of bitwise exclusive or'ing `i1` with `i2`. -#### example: -```clarity -(xor 1 2) ;; Returns 3 -(xor 120 280) ;; Returns 352 -``` - -### and -#### input: `bool, ...` -#### output: `bool` -#### signature: `(and b1 b2 ...)` -#### description: -Returns `true` if all boolean inputs are `true`. Importantly, the supplied arguments are evaluated in-order and lazily. Lazy evaluation means that if one of the arguments returns `false`, the function short-circuits, and no subsequent arguments are evaluated. -#### example: -```clarity -(and true false) ;; Returns false -(and (is-eq (+ 1 2) 1) (is-eq 4 4)) ;; Returns false -(and (is-eq (+ 1 2) 3) (is-eq 4 4)) ;; Returns true -``` - -### or -#### input: `bool, ...` -#### output: `bool` -#### signature: `(or b1 b2 ...)` -#### description: -Returns `true` if any boolean inputs are `true`. Importantly, the supplied arguments are evaluated in-order and lazily. Lazy evaluation means that if one of the arguments returns `true`, the function short-circuits, and no subsequent arguments are evaluated. -#### example: -```clarity -(or true false) ;; Returns true -(or (is-eq (+ 1 2) 1) (is-eq 4 4)) ;; Returns true -(or (is-eq (+ 1 2) 1) (is-eq 3 4)) ;; Returns false -(or (is-eq (+ 1 2) 3) (is-eq 4 4)) ;; Returns true -``` - -### not -#### input: `bool` -#### output: `bool` -#### signature: `(not b1)` -#### description: -Returns the inverse of the boolean input. -#### example: -```clarity -(not true) ;; Returns false -(not (is-eq 1 2)) ;; Returns true -``` - -### is-eq -#### input: `A, A, ...` -#### output: `bool` -#### signature: `(is-eq v1 v2...)` -#### description: -Compares the inputted values, returning `true` if they are all equal. Note that _unlike_ the `(and ...)` function, `(is-eq ...)` will _not_ short-circuit. All values supplied to is-eq _must_ be the same type. -#### example: -```clarity -(is-eq 1 1) ;; Returns true -(is-eq true false) ;; Returns false -(is-eq \"abc\" 234 234) ;; Throws type error -``` - -### if -#### input: `bool, A, A` -#### output: `A` -#### signature: `(if bool1 expr1 expr2)` -#### description: -The `if` function admits a boolean argument and two expressions which must return the same type. In the case that the boolean input is `true`, the `if` function evaluates and returns `expr1`. If the boolean input is `false`, the `if` function evaluates and returns `expr2`. -#### example: -```clarity -(if true 1 2) ;; Returns 1 -(if (> 1 2) 1 2) ;; Returns 2 -``` - -### let -#### input: `((name1 AnyType) (name2 AnyType) ...), AnyType, ... A` -#### output: `A` -#### signature: `(let ((name1 expr1) (name2 expr2) ...) expr-body1 expr-body2 ... expr-body-last)` -#### description: -The `let` function accepts a list of `variable name` and `expression` pairs, evaluating each expression and _binding_ it to the corresponding variable name. `let` bindings are sequential: when a `let` binding is evaluated, it may refer to prior binding. The _context_ created by this set of bindings is used for evaluating its body expressions. The let expression returns the value of the last such body expression. Note: intermediary statements returning a response type must be checked` -#### example: -```clarity -(let ((a 2) (b (+ 5 6 7))) (print a) (print b) (+ a b)) ;; Returns 20 -(let ((a 5) (c (+ a 1)) (d (+ c 1)) (b (+ a c d))) (print a) (print b) (+ a b)) ;; Returns 23 -``` - -### map -#### input: `Function(A, B, ..., N) -> X, sequence_A, sequence_B, ..., sequence_N` -#### output: `(list X)` -#### signature: `(map func sequence_A sequence_B ... sequence_N)` -#### description: -The `map` function applies the function `func` to each corresponding element of the input sequences, and outputs a _list_ of the same type containing the outputs from those function applications. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. Also, note that, no matter what kind of sequences the inputs are, the output is always a list. -#### example: -```clarity -(map not (list true false true false)) ;; Returns (false true false true) -(map + (list 1 2 3) (list 1 2 3) (list 1 2 3)) ;; Returns (3 6 9) -(define-private (a-or-b (char (string-utf8 1))) (if (is-eq char u\"a\") u\"a\" u\"b\")) -(map a-or-b u\"aca\") ;; Returns (u\"a\" u\"b\" u\"a\") -(define-private (zero-or-one (char (buff 1))) (if (is-eq char 0x00) 0x00 0x01)) -(map zero-or-one 0x000102) ;; Returns (0x00 0x01 0x01) -``` - -### fold -#### input: `Function(A, B) -> B, sequence_A, B` -#### output: `B` -#### signature: `(fold func sequence_A initial_B)` -#### description: -The `fold` function condenses `sequence_A` into a value of type `B` by recursively applies the function `func` to each element of the input sequence _and_ the output of a previous application of `func`. - -`fold` uses `initial_B` in the initial application of `func`, along with the first element of `sequence_A`. The resulting value of type `B` is used for the next application of `func`, along with the next element of `sequence_A` and so on. `fold` returns the last value of type `B` returned by these successive applications `func`. - -Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. - -#### example: -```clarity -(fold * (list 2 2 2) 1) ;; Returns 8 -(fold * (list 2 2 2) 0) ;; Returns 0 -;; calculates (- 11 (- 7 (- 3 2))) -(fold - (list 3 7 11) 2) ;; Returns 5 -(define-private (concat-string (a (string-ascii 20)) (b (string-ascii 20))) (unwrap-panic (as-max-len? (concat a b) u20))) -(fold concat-string \"cdef\" \"ab\") ;; Returns \"fedcab\" -(fold concat-string (list \"cd\" \"ef\") \"ab\") ;; Returns \"efcdab\" -(define-private (concat-buff (a (buff 20)) (b (buff 20))) (unwrap-panic (as-max-len? (concat a b) u20))) -(fold concat-buff 0x03040506 0x0102) ;; Returns 0x060504030102 -``` - -### append -#### input: `list A, A` -#### output: `list` -#### signature: `(append (list 1 2 3 4) 5)` -#### description: -The `append` function takes a list and another value with the same entry type, and outputs a list of the same type with max_len += 1. -#### example: -```clarity -(append (list 1 2 3 4) 5) ;; Returns (1 2 3 4 5) -``` - -### concat -#### input: `sequence_A, sequence_A` -#### output: `sequence_A` -#### signature: `(concat sequence1 sequence2)` -#### description: -The `concat` function takes two sequences of the same type, and returns a concatenated sequence of the same type, with the resulting sequence_len = sequence1_len + sequence2_len. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`. - -#### example: -```clarity -(concat (list 1 2) (list 3 4)) ;; Returns (1 2 3 4) -(concat \"hello \" \"world\") ;; Returns \"hello world\" -(concat 0x0102 0x0304) ;; Returns 0x01020304 -``` - -### as-max-len? -#### input: `sequence_A, uint` -#### output: `sequence_A` -#### signature: `(as-max-len? sequence max_length)` -#### description: -The `as-max-len?` function takes a sequence argument and a uint-valued, literal length argument. The function returns an optional type. If the input sequence length is less than or equal to the supplied max_length, this returns `(some sequence)`, otherwise it returns `none`. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`. ` -#### example: -```clarity -(as-max-len? (list 2 2 2) u3) ;; Returns (some (2 2 2)) -(as-max-len? (list 1 2 3) u2) ;; Returns none -(as-max-len? \"hello\" u10) ;; Returns (some \"hello\") -(as-max-len? 0x010203 u10) ;; Returns (some 0x010203) -``` - -### len -#### input: `sequence_A` -#### output: `uint` -#### signature: `(len sequence)` -#### description: -The `len` function returns the length of a given sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`. ` -#### example: -```clarity -(len \"blockstack\") ;; Returns u10 -(len (list 1 2 3 4 5)) ;; Returns u5 -(len 0x010203) ;; Returns u3 -``` - -### element-at -#### input: `sequence_A, uint` -#### output: `(optional A)` -#### signature: `(element-at sequence index)` -#### description: -The `element-at` function returns the element at `index` in the provided sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. ` -#### example: -```clarity -(element-at \"blockstack\" u5) ;; Returns (some \"s\") -(element-at (list 1 2 3 4 5) u5) ;; Returns none -(element-at (list 1 2 3 4 5) (+ u1 u2)) ;; Returns (some 4) -(element-at \"abcd\" u1) ;; Returns (some \"b\") -(element-at 0xfb01 u1) ;; Returns (some 0x01) -``` - -### index-of -#### input: `sequence_A, A` -#### output: `(optional uint)` -#### signature: `(index-of sequence item)` -#### description: -The `index-of` function returns the first index at which `item` can be found, using `is-eq` checks, in the provided sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. If the target item is not found in the sequence (or if an empty string or buffer is supplied), this function returns `none`. -#### example: -```clarity -(index-of \"blockstack\" \"b\") ;; Returns (some u0) -(index-of \"blockstack\" \"k\") ;; Returns (some u4) -(index-of \"blockstack\" \"\") ;; Returns none -(index-of (list 1 2 3 4 5) 6) ;; Returns none -(index-of 0xfb01 0x01) ;; Returns (some u1) -``` - -### list -#### input: `A, ...` -#### output: `(list A)` -#### signature: `(list expr1 expr2 expr3 ...)` -#### description: -The `list` function constructs a list composed of the inputted values. Each supplied value must be of the same type. -#### example: -```clarity -(list (+ 1 2) 4 5) ;; Returns (3 4 5) -``` - -### var-get -#### input: `VarName` -#### output: `A` -#### signature: `(var-get var-name)` -#### description: -The `var-get` function looks up and returns an entry from a contract's data map. The value is looked up using `var-name`. -#### example: -```clarity -(define-data-var cursor int 6) -(var-get cursor) ;; Returns 6 -``` - -### var-set -#### input: `VarName, AnyType` -#### output: `bool` -#### signature: `(var-set var-name expr1)` -#### description: -The `var-set` function sets the value associated with the input variable to the inputted value. The function always returns `true`. -#### example: -```clarity -(define-data-var cursor int 6) -(var-get cursor) ;; Returns 6 -(var-set cursor (+ (var-get cursor) 1)) ;; Returns true -(var-get cursor) ;; Returns 7 -``` - -### map-get? -#### input: `MapName, tuple` -#### output: `(optional (tuple))` -#### signature: `(map-get? map-name key-tuple)` -#### description: -The `map-get?` function looks up and returns an entry from a contract's data map. The value is looked up using `key-tuple`. If there is no value associated with that key in the data map, the function returns a `none` option. Otherwise, it returns `(some value)`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(map-get? names-map (tuple (name \"blockstack\"))) ;; Returns (some (tuple (id 1337))) -(map-get? names-map { name: \"blockstack\" }) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-set -#### input: `MapName, tuple_A, tuple_B` -#### output: `bool` -#### signature: `(map-set map-name key-tuple value-tuple)` -#### description: -The `map-set` function sets the value associated with the input key to the inputted value. This function performs a _blind_ update; whether or not a value is already associated with the key, the function overwrites that existing association. - -Note: the `value-tuple` requires 1 additional byte for storage in the materialized blockchain state, and therefore the maximum size of a value that may be inserted into a map is MAX_CLARITY_VALUE - 1. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-set names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-insert -#### input: `MapName, tuple_A, tuple_B` -#### output: `bool` -#### signature: `(map-insert map-name key-tuple value-tuple)` -#### description: -The `map-insert` function sets the value associated with the input key to the inputted value if and only if there is not already a value associated with the key in the map. If an insert occurs, the function returns `true`. If a value already existed for this key in the data map, the function returns `false`. - -Note: the `value-tuple` requires 1 additional byte for storage in the materialized blockchain state, and therefore the maximum size of a value that may be inserted into a map is MAX_CLARITY_VALUE - 1. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns false -(map-insert names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-delete -#### input: `MapName, tuple` -#### output: `bool` -#### signature: `(map-delete map-name key-tuple)` -#### description: -The `map-delete` function removes the value associated with the input key for the given map. If an item exists and is removed, the function returns `true`. If a value did not exist for this key in the data map, the function returns `false`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-delete names-map { name: \"blockstack\" }) ;; Returns true -(map-delete names-map { name: \"blockstack\" }) ;; Returns false -(map-delete names-map (tuple (name \"blockstack\"))) ;; Same command, using a shorthand for constructing the tuple -``` - -### tuple -#### input: `(key-name A), (key-name-2 B), ...` -#### output: `(tuple (key-name A) (key-name-2 B) ...)` -#### signature: `(tuple (key0 expr0) (key1 expr1) ...)` -#### description: -The `tuple` special form constructs a typed tuple from the supplied key and expression pairs. A `get` function can use typed tuples as input to select specific values from a given tuple. Key names may not appear multiple times in the same tuple definition. Supplied expressions are evaluated and associated with the expressions' paired key name. - -There is a shorthand using curly brackets of the form {key0: expr0, key1: expr, ...}` -#### example: -```clarity -(tuple (name \"blockstack\") (id 1337)) ;; using tuple -{name: \"blockstack\", id: 1337} ;; using curly brackets -``` - -### get -#### input: `KeyName, (tuple) | (optional (tuple))` -#### output: `A` -#### signature: `(get key-name tuple)` -#### description: -The `get` function fetches the value associated with a given key from the supplied typed tuple. If an `Optional` value is supplied as the inputted tuple, `get` returns an `Optional` type of the specified key in the tuple. If the supplied option is a `(none)` option, get returns `(none)`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(get id (tuple (name \"blockstack\") (id 1337))) ;; Returns 1337 -(get id (map-get? names-map (tuple (name \"blockstack\")))) ;; Returns (some 1337) -(get id (map-get? names-map (tuple (name \"non-existent\")))) ;; Returns none -``` - -### merge -#### input: `tuple, tuple` -#### output: `tuple` -#### signature: `(merge tuple { key1: val1 })` -#### description: -The `merge` function returns a new tuple with the combined fields, without mutating the supplied tuples. -#### example: -```clarity -(define-map users { id: int } { name: (string-ascii 12), address: (optional principal) }) -(map-insert users { id: 1337 } { name: \"john\", address: none }) ;; Returns true -(let ((user (unwrap-panic (map-get? users { id: 1337 })))) -(merge user { address: (some 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) })) ;; Returns (tuple (address (some SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF)) (name \"john\")) -``` - -### begin -#### input: `AnyType, ... A` -#### output: `A` -#### signature: `(begin expr1 expr2 expr3 ... expr-last)` -#### description: -The `begin` function evaluates each of its input expressions, returning the return value of the last such expression. Note: intermediary statements returning a response type must be checked. -#### example: -```clarity -(begin (+ 1 2) 4 5) ;; Returns 5 -``` - -### hash160 -#### input: `buff|uint|int` -#### output: `(buff 20)` -#### signature: `(hash160 value)` -#### description: -The `hash160` function computes `RIPEMD160(SHA256(x))` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(hash160 0) ;; Returns 0xe4352f72356db555721651aa612e00379167b30f -``` - -### sha256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(sha256 value)` -#### description: -The `sha256` function computes `SHA256(x)` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(sha256 0) ;; Returns 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb -``` - -### sha512 -#### input: `buff|uint|int` -#### output: `(buff 64)` -#### signature: `(sha512 value)` -#### description: -The `sha512` function computes `SHA512(x)` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(sha512 1) ;; Returns 0x6fcee9a7b7a7b821d241c03c82377928bc6882e7a08c78a4221199bfa220cdc55212273018ee613317c8293bb8d1ce08d1e017508e94e06ab85a734c99c7cc34 -``` - -### sha512/256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(sha512/256 value)` -#### description: -The `sha512/256` function computes `SHA512/256(x)` (the SHA512 algorithm with the 512/256 initialization vector, truncated to 256 bits) of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(sha512/256 1) ;; Returns 0x515a7e92e7c60522db968d81ff70b80818fc17aeabbec36baf0dda2812e94a86 -``` - -### keccak256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(keccak256 value)` -#### description: -The `keccak256` function computes `KECCAK256(value)` of the inputted value. Note that this differs from the `NIST SHA-3` (that is, FIPS 202) standard. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(keccak256 0) ;; Returns 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4 -``` - -### secp256k1-recover? -#### input: `(buff 32), (buff 65)` -#### output: `(response (buff 33) uint)` -#### signature: `(secp256k1-recover? message-hash signature)` -#### description: -The `secp256k1-recover?` function recovers the public key used to sign the message which sha256 is `message-hash` with the provided `signature`. If the signature does not match, it will return the error code `(err u1).`. If the signature is invalid, it will return the error code `(err u2).`. The signature includes 64 bytes plus an additional recovery id (00..03) for a total of 65 bytes. -#### example: -```clarity -(secp256k1-recover? 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a1301) - ;; Returns (ok 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) - ``` - -### secp256k1-verify -#### input: `(buff 32), (buff 64) | (buff 65), (buff 33)` -#### output: `bool` -#### signature: `(secp256k1-verify message-hash signature public-key)` -#### description: -The `secp256k1-verify` function verifies that the provided signature of the message-hash was signed with the private key that generated the public key. The `message-hash` is the `sha256` of the message. The signature includes 64 bytes plus an optional additional recovery id (00..03) for a total of 64 or 65 bytes. -#### example: -```clarity -(secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a1301 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns true -(secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a13 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns true -(secp256k1-verify 0x0000000000000000000000000000000000000000000000000000000000000000 - 0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns false - ``` - -### print -#### input: `A` -#### output: `A` -#### signature: `(print expr)` -#### description: -The `print` function evaluates and returns its input expression. On Stacks Core nodes configured for development (as opposed to production mining nodes), this function prints the resulting value to `STDOUT` (standard output). -#### example: -```clarity -(print (+ 1 2 3)) ;; Returns 6 -``` - -### contract-call? -#### input: `ContractName, PublicFunctionName, Arg0, ...` -#### output: `(response A B)` -#### signature: `(contract-call? .contract-name function-name arg0 arg1 ...)` -#### description: -The `contract-call?` function executes the given public function of the given contract. You _may not_ use this function to call a public function defined in the current contract. If the public function returns _err_, any database changes resulting from calling `contract-call?` are aborted. If the function returns _ok_, database changes occurred. -#### example: -```clarity - -;; instantiate the sample-contracts/tokens.clar contract first! -(as-contract (contract-call? .tokens mint! u19)) ;; Returns (ok u19) -``` - -### as-contract -#### input: `A` -#### output: `A` -#### signature: `(as-contract expr)` -#### description: -The `as-contract` function switches the current context's `tx-sender` value to the _contract's_ principal and executes `expr` with that context. It returns the resulting value of `expr`. -#### example: -```clarity -(as-contract tx-sender) ;; Returns S1G2081040G2081040G2081040G208105NK8PE5.docs-test -``` - -### contract-of -#### input: `Trait` -#### output: `principal` -#### signature: `(contract-of .contract-name)` -#### description: -The `contract-of` function returns the principal of the contract implementing the trait. -#### example: -```clarity -(use-trait token-a-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) -(define-public (forward-get-balance (user principal) (contract )) - (begin - (ok (contract-of contract)))) ;; returns the principal of the contract implementing -``` - -### principal-of? -#### input: `(buff 33)` -#### output: `(response principal uint)` -#### signature: `(principal-of? public-key)` -#### description: -The `principal-of?` function returns the principal derived from the provided public key. If the `public-key` is invalid, it will return the error code `(err u1).`. ` -#### example: -```clarity -(principal-of? 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns (ok ST1AW6EKPGT61SQ9FNVDS17RKNWT8ZP582VF9HSCP) -``` - -### at-block -#### input: `(buff 32), A` -#### output: `A` -#### signature: `(at-block id-block-hash expr)` -#### description: -The `at-block` function evaluates the expression `expr` _as if_ it were evaluated at the end of the block indicated by the _block-hash_ argument. The `expr` closure must be read-only. - -Note: The block identifying hash must be a hash returned by the `id-header-hash` block information property. This hash uniquely identifies Stacks blocks and is unique across Stacks forks. While the hash returned by `header-hash` is unique within the context of a single fork, it is not unique across Stacks forks. - -The function returns the result of evaluating `expr`. - -#### example: -```clarity -(define-data-var data int 1) -(at-block 0x0000000000000000000000000000000000000000000000000000000000000000 block-height) ;; Returns u0 -(at-block (get-block-info? id-header-hash 0) (var-get data)) ;; Throws NoSuchDataVariable because `data` wasn't initialized at block height 0 -``` - -### get-block-info? -#### input: `BlockInfoPropertyName, BlockHeightInt` -#### output: `(optional buff) | (optional uint)` -#### signature: `(get-block-info? prop-name block-height-expr)` -#### description: -The `get-block-info?` function fetches data for a block of the given block height. The value and type returned are determined by the specified `BlockInfoPropertyName`. If the provided `BlockHeightInt` does not correspond to an existing block prior to the current block, the function returns `none`. The currently available property names are `time`, `header-hash`, `burnchain-header-hash`, `id-header-hash`, `miner-address`, and `vrf-seed`. - -The `time` property returns an integer value of the block header time field. This is a Unix epoch timestamp in seconds which roughly corresponds to when the block was mined. **Warning**: this does not increase monotonically with each block and block times are accurate only to within two hours. See [BIP113](https://github.com/bitcoin/bips/blob/master/bip-0113.mediawiki) for more information. - -The `header-hash`, `burnchain-header-hash`, `id-header-hash`, and `vrf-seed` properties return a 32-byte buffer. - -The `miner-address` property returns a `principal` corresponding to the miner of the given block. - -The `id-header-hash` is the block identifier value that must be used as input to the `at-block` function. - -#### example: -```clarity -(get-block-info? time u0) ;; Returns (some u1557860301) -(get-block-info? header-hash u0) ;; Returns (some 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb) -(get-block-info? vrf-seed u0) ;; Returns (some 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4) -``` - -### err -#### input: `A` -#### output: `(response A B)` -#### signature: `(err value)` -#### description: -The `err` function constructs a response type from the input value. Use `err` for creating return values in public functions. An _err_ value indicates that any database changes during the processing of the function should be rolled back. -#### example: -```clarity -(err true) ;; Returns (err true) -``` - -### ok -#### input: `A` -#### output: `(response A B)` -#### signature: `(ok value)` -#### description: -The `ok` function constructs a response type from the input value. Use `ok` for creating return values in public functions. An _ok_ value indicates that any database changes during the processing of the function should materialize. -#### example: -```clarity -(ok 1) ;; Returns (ok 1) -``` - -### some -#### input: `A` -#### output: `(optional A)` -#### signature: `(some value)` -#### description: -The `some` function constructs a `optional` type from the input value. -#### example: -```clarity -(some 1) ;; Returns (some 1) -(is-none (some 2)) ;; Returns false -``` - -### default-to -#### input: `A, (optional A)` -#### output: `A` -#### signature: `(default-to default-value option-value)` -#### description: -The `default-to` function attempts to 'unpack' the second argument: if the argument is a `(some ...)` option, it returns the inner value of the option. If the second argument is a `(none)` value, `default-to` it returns the value of `default-value`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(default-to 0 (get id (map-get? names-map (tuple (name \"blockstack\"))))) ;; Returns 1337 -(default-to 0 (get id (map-get? names-map (tuple (name \"non-existant\"))))) ;; Returns 0 -``` - -### asserts! -#### input: `bool, C` -#### output: `bool` -#### signature: `(asserts! bool-expr thrown-value)` -#### description: -The `asserts!` function admits a boolean argument and asserts its evaluation: if bool-expr is `true`, `asserts!` returns `true` and proceeds in the program execution. If the supplied argument is returning a false value, `asserts!` _returns_ `thrown-value` and exits the current control-flow. -#### example: -```clarity -(asserts! (is-eq 1 1) (err 1)) ;; Returns true -``` - -### unwrap! -#### input: `(optional A) | (response A B), C` -#### output: `A` -#### signature: `(unwrap! option-input thrown-value)` -#### description: -The `unwrap!` function attempts to 'unpack' the first argument: if the argument is an option type, and the argument is a `(some ...)` option, `unwrap!` returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, `unwrap!` returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `(none)` value, `unwrap!` _returns_ `thrown-value` from the current function and exits the current control-flow. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(define-private (get-name-or-err (name (string-ascii 12))) - (let ((raw-name (unwrap! (map-get? names-map { name: name }) (err 1)))) - (ok raw-name))) - -(get-name-or-err \"blockstack\") ;; Returns (ok (tuple (id 1337))) -(get-name-or-err \"non-existant\") ;; Returns (err 1) -``` - -### unwrap-err! -#### input: `(response A B), C` -#### output: `B` -#### signature: `(unwrap-err! response-input thrown-value)` -#### description: -The `unwrap-err!` function attempts to 'unpack' the first argument: if the argument is an `(err ...)` response, `unwrap-err!` returns the inner value of the `err`. If the supplied argument is an `(ok ...)` value, `unwrap-err!` _returns_ `thrown-value` from the current function and exits the current control-flow. -#### example: -```clarity -(unwrap-err! (err 1) false) ;; Returns 1 -``` - -### unwrap-panic -#### input: `(optional A) | (response A B)` -#### output: `A` -#### signature: `(unwrap-panic option-input)` -#### description: -The `unwrap` function attempts to 'unpack' its argument: if the argument is an option type, and the argument is a `(some ...)` option, this function returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, it returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `(none)` value, `unwrap` throws a runtime error, aborting any further processing of the current transaction. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(unwrap-panic (map-get? names-map { name: \"blockstack\" })) ;; Returns (tuple (id 1337)) -(unwrap-panic (map-get? names-map { name: \"non-existant\" })) ;; Throws a runtime exception -``` - -### unwrap-err-panic -#### input: `(response A B)` -#### output: `B` -#### signature: `(unwrap-err-panic response-input)` -#### description: -The `unwrap-err` function attempts to 'unpack' the first argument: if the argument is an `(err ...)` response, `unwrap` returns the inner value of the `err`. If the supplied argument is an `(ok ...)` value, `unwrap-err` throws a runtime error, aborting any further processing of the current transaction. -#### example: -```clarity -(unwrap-err-panic (err 1)) ;; Returns 1 -(unwrap-err-panic (ok 1)) ;; Throws a runtime exception -``` - -### match -#### input: `(optional A) name expression expression | (response A B) name expression name expression` -#### output: `C` -#### signature: `(match opt-input some-binding-name some-branch none-branch) | -(match-resp input ok-binding-name ok-branch err-binding-name err-branch)` -#### description: -The `match` function is used to test and destructure optional and response types. - -If the `input` is an optional, it tests whether the provided `input` is a `some` or `none` option, and evaluates `some-branch` or `none-branch` in each respective case. - -Within the `some-branch`, the _contained value_ of the `input` argument is bound to the provided `some-binding-name` name. - -Only _one_ of the branches will be evaluated (similar to `if` statements). - -If the `input` is a response, it tests whether the provided `input` is an `ok` or `err` response type, and evaluates `ok-branch` or `err-branch` in each respective case. - -Within the `ok-branch`, the _contained ok value_ of the `input` argument is bound to the provided `ok-binding-name` name. - -Within the `err-branch`, the _contained err value_ of the `input` argument is bound to the provided `err-binding-name` name. - -Only _one_ of the branches will be evaluated (similar to `if` statements). - -Note: Type checking requires that the type of both the ok and err parts of the response object be determinable. For situations in which one of the parts of a response is untyped, you should use `unwrap-panic` or `unwrap-err-panic` instead of `match`. -#### example: -```clarity - -(define-private (add-10 (x (optional int))) - (match x - value (+ 10 value) - 10)) -(add-10 (some 5)) ;; Returns 15 -(add-10 none) ;; Returns 10 - -(define-private (add-or-pass-err (x (response int (string-ascii 10))) (to-add int)) - (match x - value (ok (+ to-add value)) - err-value (err err-value))) -(add-or-pass-err (ok 5) 20) ;; Returns (ok 25) -(add-or-pass-err (err \"ERROR\") 20) ;; Returns (err \"ERROR\") -``` - -### try! -#### input: `(optional A) | (response A B)` -#### output: `A` -#### signature: `(try! option-input)` -#### description: -The `try!` function attempts to 'unpack' the first argument: if the argument is an option type, and the argument is a `(some ...)` option, `try!` returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, `try!` returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `none` value, `try!` _returns_ either `none` or the `(err ...)` value from the current function and exits the current control-flow. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(try! (map-get? names-map { name: \"blockstack\" })) ;; Returns (tuple (id 1337)) -(define-private (checked-even (x int)) - (if (is-eq (mod x 2) 0) - (ok x) - (err false))) -(define-private (double-if-even (x int)) - (ok (* 2 (try! (checked-even x))))) -(double-if-even 10) ;; Returns (ok 20) -(double-if-even 3) ;; Returns (err false) -``` - -### is-ok -#### input: `(response A B)` -#### output: `bool` -#### signature: `(is-ok value)` -#### description: -`is-ok` tests a supplied response value, returning `true` if the response was `ok`, and `false` if it was an `err`. -#### example: -```clarity -(is-ok (ok 1)) ;; Returns true -(is-ok (err 1)) ;; Returns false -``` - -### is-none -#### input: `(optional A)` -#### output: `bool` -#### signature: `(is-none value)` -#### description: -`is-none` tests a supplied option value, returning `true` if the option value is `(none)`, and `false` if it is a `(some ...)`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(is-none (get id (map-get? names-map { name: \"blockstack\" }))) ;; Returns false -(is-none (get id (map-get? names-map { name: \"non-existant\" }))) ;; Returns true -``` - -### is-err -#### input: `(response A B)` -#### output: `bool` -#### signature: `(is-err value)` -#### description: -`is-err` tests a supplied response value, returning `true` if the response was an `err`, and `false` if it was an `ok`. -#### example: -```clarity -(is-err (ok 1)) ;; Returns false -(is-err (err 1)) ;; Returns true -``` - -### is-some -#### input: `(optional A)` -#### output: `bool` -#### signature: `(is-some value)` -#### description: -`is-some` tests a supplied option value, returning `true` if the option value is `(some ...)`, and `false` if it is a `none`. -#### example: -```clarity - -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(is-some (get id (map-get? names-map { name: \"blockstack\" }))) ;; Returns true -(is-some (get id (map-get? names-map { name: \"non-existant\" }))) ;; Returns false -``` - -### filter -#### input: `Function(A) -> bool, sequence_A` -#### output: `sequence_A` -#### signature: `(filter func sequence)` -#### description: -The `filter` function applies the input function `func` to each element of the input sequence, and returns the same sequence with any elements removed for which `func` returned `false`. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. ` -#### example: -```clarity - -(filter not (list true false true false)) ;; Returns (false false) -(define-private (is-a (char (string-utf8 1))) (is-eq char u\"a\")) -(filter is-a u\"acabd\") ;; Returns u\"aa\" -(define-private (is-zero (char (buff 1))) (is-eq char 0x00)) -(filter is-zero 0x00010002) ;; Returns 0x0000 -``` - -### ft-get-balance -#### input: `TokenName, principal` -#### output: `uint` -#### signature: `(ft-get-balance token-name principal)` -#### description: -`ft-get-balance` returns `token-name` balance of the principal `principal`. The token type must have been defined using `define-fungible-token`. -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-get-balance stackaroo 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns u100 -``` - -### nft-get-owner? -#### input: `AssetName, A` -#### output: `(optional principal)` -#### signature: `(nft-get-owner? asset-class asset-identifier)` -#### description: -`nft-get-owner?` returns the owner of an asset, identified by `asset-identifier`, or `none` if the asset does not exist. The asset type must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) -(nft-get-owner? stackaroo \"Roo\") ;; Returns (some SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) -(nft-get-owner? stackaroo \"Too\") ;; Returns none -``` - -### ft-transfer? -#### input: `TokenName, uint, principal, principal` -#### output: `(response bool uint)` -#### signature: `(ft-transfer? token-name amount sender recipient)` -#### description: -`ft-transfer?` is used to increase the token balance for the `recipient` principal for a token type defined using `define-fungible-token` by debiting the `sender` principal. In contrast to `stx-transfer?`, any user can transfer the assets. When used, relevant guards need to be added. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- amount to send is non-positive ` -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-transfer? stackaroo u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(ft-transfer? stackaroo u60 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u1) -``` - -### nft-transfer? -#### input: `AssetName, A, principal, principal` -#### output: `(response bool uint)` -#### signature: `(nft-transfer? asset-class asset-identifier sender recipient)` -#### description: -`nft-transfer?` is used to change the owner of an asset identified by `asset-identifier` from `sender` to `recipient`. The `asset-class` must have been defined by `define-non-fungible-token` and `asset-identifier` must be of the type specified in that definition. In contrast to `stx-transfer?`, any user can transfer the asset. When used, relevant guards need to be added. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not own the asset `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- asset identified by asset-identifier does not exist ` -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(nft-transfer? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(nft-transfer? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u1) -(nft-transfer? stackaroo \"Stacka\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u3) -``` - -### nft-mint? -#### input: `AssetName, A, principal` -#### output: `(response bool uint)` -#### signature: `(nft-mint? asset-class asset-identifier recipient)` -#### description: -`nft-mint?` is used to instantiate an asset and set that asset's owner to the `recipient` principal. The asset must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. - -If an asset identified by `asset-identifier` _already exists_, this function will return an error with the following error code: - -`(err u1)` - -Otherwise, on successfuly mint, it returns `(ok true)`. ` -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### ft-mint? -#### input: `TokenName, uint, principal` -#### output: `(response bool uint)` -#### signature: `(ft-mint? token-name amount recipient)` -#### description: -`ft-mint?` is used to increase the token balance for the `recipient` principal for a token type defined using `define-fungible-token`. The increased token balance is _not_ transfered from another principal, but rather minted. - -If a non-positive amount is provided to mint, this function returns `(err 1)`. Otherwise, on successfuly mint, it returns `(ok true)`. ` -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### ft-get-supply -#### input: `TokenName` -#### output: `uint` -#### signature: `(ft-get-supply token-name)` -#### description: -`ft-get-balance` returns `token-name` circulating supply. The token type must have been defined using `define-fungible-token`. -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-get-supply stackaroo) ;; Returns u100 -``` - -### ft-burn? -#### input: `TokenName, uint, principal` -#### output: `(response bool uint)` -#### signature: `(ft-burn? token-name amount sender)` -#### description: -`ft-burn?` is used to decrease the token balance for the `sender` principal for a token type defined using `define-fungible-token`. The decreased token balance is _not_ transfered to another principal, but rather destroyed, reducing the circulating supply. - -If a non-positive amount is provided to burn, this function returns `(err 1)`. Otherwise, on successfuly burn, it returns `(ok true)`. - -#### example: -```clarity - -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(ft-burn? stackaroo u50 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### nft-burn? -#### input: `AssetName, A, principal` -#### output: `(response bool uint)` -#### signature: `(nft-burn? asset-class asset-identifier recipient)` -#### description: -`nft-burn?` is used to burn an asset and remove that asset's owner from the `recipient` principal. The asset must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. - -If an asset identified by `asset-identifier` _doesn't exist_, this function will return an error with the following error code: - -`(err u1)` - -Otherwise, on successfuly burn, it returns `(ok true)`. ` -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(nft-burn? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### stx-get-balance -#### input: `principal` -#### output: `uint` -#### signature: `(stx-get-balance owner)` -#### description: -`stx-get-balance` is used to query the STX balance of the `owner` principal. - -This function returns the STX balance of the `owner` principal. In the event that the `owner` principal isn't materialized, it returns 0. - -#### example: -```clarity -(stx-get-balance 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns u0 -(stx-get-balance (as-contract tx-sender)) ;; Returns u1000 -``` - -### stx-transfer? -#### input: `uint, principal, principal` -#### output: `(response bool uint)` -#### signature: `(stx-transfer? amount sender recipient)` -#### description: -`stx-transfer?` is used to increase the STX balance for the `recipient` principal by debiting the `sender` principal. The `sender` principal _must_ be equal to the current context's `tx-sender`. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- amount to send is non-positive `(err u4)` -- the `sender` principal is not the current `tx-sender` - -#### example: -```clarity - -(as-contract - (stx-transfer? u60 tx-sender 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (ok true) -(as-contract - (stx-transfer? u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR tx-sender)) ;; Returns (err u4) -``` - -### stx-burn? -#### input: `uint, principal` -#### output: `(response bool uint)` -#### signature: `(stx-burn? amount sender)` -#### description: -`stx-burn?` debits the `sender` principal's STX holdings by `amount`, destroying the STX. The `sender` principal _must_ be equal to the current context's `tx-sender`. - -This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u3)` -- amount to send is non-positive `(err u4)` -- the `sender` principal is not the current `tx-sender` - -#### example: -```clarity -(as-contract - (stx-burn? u60 tx-sender)) ;; Returns (ok true) -(as-contract - (stx-burn? u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (err u4) -``` - -### define-constant -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-constant name expression)` -#### description: -`define-constant` is used to define a private constant value in a smart contract. The expression passed into the definition is evaluated at contract launch, in the order that it is supplied in the contract. This can lead to undefined function or undefined variable errors in the event that a function or variable used in the expression has not been defined before the constant. - -Like other kinds of definition statements, `define-constant` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -#### example: -```clarity - -(define-constant four (+ 2 2)) -(+ 4 four) ;; Returns 8 -``` - -### define-private -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-private (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### description: -`define-private` is used to define _private_ functions for a smart contract. Private functions may not be called from other smart contracts, nor may they be invoked directly by users. Instead, these functions may only be invoked by other functions defined in the same smart contract. - -Like other kinds of definition statements, `define-private` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Private functions may return any type. -#### example: -```clarity -(define-private (max-of (i1 int) (i2 int)) - (if (> i1 i2) - i1 - i2)) -(max-of 4 6) ;; Returns 6 -``` - -### define-public -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-public (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### description: -`define-public` is used to define a _public_ function and transaction for a smart contract. Public functions are callable from other smart contracts and may be invoked directly by users by submitting a transaction to the Stacks blockchain. - -Like other kinds of definition statements, `define-public` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Public functions _must_ return a ResponseType (using either `ok` or `err`). Any datamap modifications performed by a public function is aborted if the function returns an `err` type. Public functions may be invoked by other contracts via `contract-call?`. -#### example: -```clarity -(define-public (hello-world (input int)) - (begin (print (+ 2 input)) - (ok input))) -``` - -### define-read-only -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-read-only (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### description: -`define-read-only` is used to define a _public read-only_ function for a smart contract. Such functions are callable from other smart contracts. - -Like other kinds of definition statements, `define-read-only` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Read-only functions may return any type. However, read-only functions may not perform any datamap modifications, or call any functions which perform such modifications. This is enforced both during type checks and during the execution of the function. Public read-only functions may be invoked by other contracts via `contract-call?`. -#### example: -```clarity -(define-read-only (just-return-one-hundred) - (* 10 10)) - ``` - -### define-map -#### input: `MapName, TypeDefinition, TypeDefinition` -#### output: `Not Applicable` -#### signature: `(define-map map-name key-type value-type)` -#### description: -`define-map` is used to define a new datamap for use in a smart contract. Such maps are only modifiable by the current smart contract. - -Maps are defined with a key type and value type, often these types are tuple types. - -Like other kinds of definition statements, `define-map` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). -#### example: -```clarity -(define-map squares { x: int } { square: int }) -(define-private (add-entry (x int)) - (map-insert squares { x: 2 } { square: (* x x) })) -(add-entry 1) -(add-entry 2) -(add-entry 3) -(add-entry 4) -(add-entry 5) -``` - -### define-data-var -#### input: `VarName, TypeDefinition, Value` -#### output: `Not Applicable` -#### signature: `(define-data-var var-name type value)` -#### description: -`define-data-var` is used to define a new persisted variable for use in a smart contract. Such variable are only modifiable by the current smart contract. - -Persisted variable are defined with a type and a value. - -Like other kinds of definition statements, `define-data-var` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). -#### example: -```clarity -(define-data-var size int 0) -(define-private (set-size (value int)) - (var-set size value)) -(set-size 1) -(set-size 2) -``` - -### define-fungible-token -#### input: `TokenName, ` -#### output: `Not Applicable` -#### signature: `(define-fungible-token token-name )` -#### description: -`define-fungible-token` is used to define a new fungible token class for use in the current contract. - -The second argument, if supplied, defines the total supply of the fungible token. This ensures that all calls to the `ft-mint?` function will never be able to create more than `total-supply` tokens. If any such call were to increase the total supply of tokens passed that amount, that invocation of `ft-mint?` will result in a runtime error and abort. - -Like other kinds of definition statements, `define-fungible-token` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Tokens defined using `define-fungible-token` may be used in `ft-transfer?`, `ft-mint?`, and `ft-get-balance` functions` -#### example: -```clarity -(define-fungible-token stacks) -(define-fungible-token limited-supply-stacks u100) -``` - -### define-non-fungible-token -#### input: `AssetName, TypeSignature` -#### output: `Not Applicable` -#### signature: `(define-non-fungible-token asset-name asset-identifier-type)` -#### description: -`define-non-fungible-token` is used to define a new non-fungible token class for use in the current contract. Individual assets are identified by their asset identifier, which must be of the type `asset-identifier-type`. Asset identifiers are _unique_ identifiers. - -Like other kinds of definition statements, `define-non-fungible-token` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Assets defined using `define-non-fungible-token` may be used in `nft-transfer?`, `nft-mint?`, and `nft-get-owner?` functions` -#### example: -```clarity -(define-non-fungible-token names (buff 50)) -``` - -### define-trait -#### input: `VarName, [MethodSignature]` -#### output: `Not Applicable` -#### signature: `(define-trait trait-name ((func1-name (arg1-type arg2-type ...) (return-type))))` -#### description: -`define-trait` is used to define a new trait definition for use in a smart contract. Other contracts can implement a given trait and then have their contract identifier being passed as function arguments in order to be called dynamically with `contract-call?`. - -Traits are defined with a name, and a list functions defined with a name, a list of argument types, and return type. - -Like other kinds of definition statements, `define-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -#### example: -```clarity -(define-trait token-trait - ((transfer? (principal principal uint) (response uint uint)) - (get-balance (principal) (response uint uint)))) -``` - -### use-trait -#### input: `VarName, TraitIdentifier` -#### output: `Not Applicable` -#### signature: `(use-trait trait-alias trait-identifier)` -#### description: -`use-trait` is used to bring a trait, defined in another contract, to the current contract. Subsequent references to an imported trait are signaled with the syntax ``. - -Traits import are defined with a name, used as an alias, and a trait identifier. Trait identifiers can either be using the sugared syntax (.token-a.token-trait), or be fully qualified ('SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait). - -Like other kinds of definition statements, `use-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put such a statement in the middle of a function body). -#### example: -```clarity -(use-trait token-a-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) -(define-public (forward-get-balance (user principal) (contract )) - (begin - (ok 1))) -``` - -### impl-trait -#### input: `TraitIdentifier` -#### output: `Not Applicable` -#### signature: `(impl-trait trait-identifier)` -#### description: -`impl-trait` can be use for asserting that a contract is fully implementing a given trait. Additional checks are being performed when the contract is being published, rejecting the deployment if the contract is violating the trait specification. - -Trait identifiers can either be using the sugared syntax (.token-a.token-trait), or be fully qualified ('SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait). - -Like other kinds of definition statements, `impl-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put such a statement in the middle of a function body). - -#### example: -```clarity -(impl-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) -(define-public (get-balance (account principal)) - (ok u0)) -(define-public (transfer? (from principal) (to principal) (amount uint)) - (ok u0)) -``` \ No newline at end of file diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md b/i18n/vi/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md deleted file mode 100644 index fd62451198..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Keywords -description: See a detailed list of all keywords for the Clarity language. -tags: - - clarity ---- - -![](/img/keywords.jpg) -## Keyword reference - -Detailed list of all keywords for the Clarity language. - - -### contract-caller -#### output: `principal` -#### description: -Returns the caller of the current contract context. If this contract is the first one called by a signed transaction, the caller will be equal to the signing principal. If `contract-call?` was used to invoke a function from a new contract, `contract-caller` changes to the _calling_ contract's principal. If `as-contract` is used to change the `tx-sender` context, `contract-caller` _also_ changes to the same contract principal. -#### example: -```clarity -(print contract-caller) ;; Will print out a Stacks address of the transaction sender -``` - -### tx-sender -#### output: `principal` -#### description: -Returns the original sender of the current transaction, or if `as-contract` was called to modify the sending context, it returns that contract principal. -#### example: -```clarity -(print tx-sender) ;; Will print out a Stacks address of the transaction sender -``` - -### block-height -#### output: `uint` -#### description: -Returns the current block height of the Stacks blockchain as an uint -#### example: -```clarity -(> block-height 1000) ;; returns true if the current block-height has passed 1000 blocks. -``` - -### burn-block-height -#### output: `uint` -#### description: -Returns the current block height of the underlying burn blockchain as a uint -#### example: -```clarity -(> burn-block-height 1000) ;; returns true if the current height of the underlying burn blockchain has passed 1000 blocks. -``` - -### none -#### output: `(optional ?)` -#### description: -Represents the _none_ option indicating no value for a given optional (analogous to a null value). -#### example: -```clarity -(define-public (only-if-positive (a int)) - (if (> a 0) - (some a) - none)) -(only-if-positive 4) ;; Returns (some 4) -(only-if-positive (- 3)) ;; Returns none -``` - -### true -#### output: `bool` -#### description: -Boolean true constant. -#### example: -```clarity -(and true false) ;; Evaluates to false -(or false true) ;; Evaluates to true -``` - -### false -#### output: `bool` -#### description: -Boolean false constant. -#### example: -```clarity -(and true false) ;; Evaluates to false -(or false true) ;; Evaluates to true -``` - -### stx-liquid-supply -#### output: `uint` -#### description: -Returns the total number of micro-STX (uSTX) that are liquid in the system as of this block. -#### example: -```clarity -(print stx-liquid-supply) ;; Will print out the total number of liquid uSTX -``` - -### is-in-regtest -#### output: `bool` -#### description: -Returns whether or not the code is running in a regression test -#### example: -```clarity -(print is-in-regtest) ;; Will print 'true' if the code is running in a regression test -``` - diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md b/i18n/vi/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md deleted file mode 100644 index d22f991413..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Types -description: See a detailed list of all types for the Clarity language. -tags: - - clarity ---- - -## Clarity Type System - -The type system contains the following types: - -| Types | Notes | -| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `int` | signed 128-bit integer | -| `uint` | unsigned 128-bit integer | -| `bool` | boolean value (`true` or `false`) | -| `principal` | object representing a principal (whether a contract principal or standard principal) | -| `(buff max-len)` | byte buffer of 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` (u"A smiley face emoji \u{1F600} as a utf8 string") | -| `(list max-len entry-type)` | list of maximum length `max-len`, with entries of type `entry-type` | -| `{label-0: value-type-0, label-1: value-type-1, ...}` | tuple, group of data values with named fields | -| `(optional some-type)` | an option type for objects that can either be `(some value)` or `none` | -| `(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. | diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md b/i18n/vi/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md deleted file mode 100644 index c518c7bbae..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Clarity overview -description: Overview and guides for getting started with Clarity -sidebar_label: Write smart contracts -sidebar_position: 2 ---- - -## Introduction - -Clarity is a **decidable** smart contract language that optimizes for predictability and security, designed for the Stacks blockchain. Smart contracts allow developers to encode essential business logic on a blockchain. - -## Smart contracts - -Smart contracts encode and enforce rules for modifying a particular set of data that is shared among people and entities who don't necessarily trust each other. For example, a smart contract can hold funds in escrow until multiple parties agree to release them, create its own ledger and keep track of its own novel tokens (fungible or non-fungible), and even help make supply chains more transparent. - -Because smart contracts are programs that exist in a blockchain, anyone can query them, and anyone can submit transactions to execute them. A smart contract execution can result in new transactions being written to the blockchain. - -Apps can take advantage of smart contracts to manage a global state that is visible to the public. Anyone can audit the blockchain to independently verify that an app's global shared state has been managed correctly according to the smart contract's rules. - -There is a [Clarity Visual Studio Code plugin][] available for syntax assistance and debugging. - -## Use cases - -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 (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 - -## Language design - -Clarity differs from most other smart contract languages in two essential ways: - -- The language is interpreted and broadcast on the blockchain as is (not compiled) -- The language is decidable (not Turing complete) - -Using an interpreted language ensures that the executed code is human-readable and auditable. A decidable language like Clarity makes it possible to determine precisely which code is executed, for any function. - -A Clarity smart contract consists of two parts, a data space and a set of functions. Only the associated smart contract may modify its corresponding data space on the blockchain. Functions may be private and thus callable only from within the smart contract, or public and thus callable from other contracts. Users call smart contracts' public functions by broadcasting a transaction on the blockchain which invokes the public function. Contracts can also call public functions from other smart contracts. - -Note some of the key Clarity language rules and limitations. - -- The only primitive types are booleans, integers, buffers, and principals. -- Recursion is illegal and there are no anonymous functions. -- Looping is only performed via `map`, `filter`, or `fold`. -- There is support for lists, however, the only variable length lists in the language appear as function inputs; there is no support for list operations like append or join. -- Variables are immutable. - -## Explore more - -For language details and references, see the following: - -- [Clarity language overview](./clarity-language/) -- [Understating Principals](principals) -- [Clarity Values](values) - -[Clarity Visual Studio Code plugin]: https://marketplace.visualstudio.com/items?itemName=HiroSystems.clarity-lsp diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md b/i18n/vi/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md deleted file mode 100644 index 9cc4fe60aa..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md +++ /dev/null @@ -1,236 +0,0 @@ ---- -title: Principals -description: 'Clarity: Understanding Principals' -sidebar_position: 1 ---- - -## Introduction - -_Principals_ are a Clarity native type that represents an entity that can have a token balance. This section discusses principals and how they are used in the Clarity. - -## Principals and tx-sender - -Assets in the smart contracting language and blockchain are "owned" by objects of the principal type, meaning that any object of the principal type may own an asset. For the case of public-key hash and multi-signature Stacks addresses, a given principal can operate on their assets by issuing a signed transaction on the blockchain. _Smart contracts_ may also be principals (represented by the smart contract's identifier), however, there is no private key associated with the smart contract, and it cannot broadcast a signed transaction on the blockchain. - -A Clarity contract can use a globally defined `tx-sender` variable to obtain the current principal. The following example defines a transaction type that transfers `amount` microSTX from the sender to a recipient if amount is a multiple of 10, otherwise returning a 400 error code. - -```clarity -(define-public (transfer-to-recipient! (recipient principal) (amount uint)) - (if (is-eq (mod amount 10) 0) - (stx-transfer? amount tx-sender recipient) - (err u400))) -``` - -Clarity provides an additional variable to help smart contracts authenticate a transaction sender. The keyword `contract-caller` returns the principal that _called_ the current contract. If an inter-contract call occurred, `contract-caller` returns the last contract in the stack of callers. For example, suppose there are three contracts A, B, and C, each with an `invoke` function such that `A::invoke` calls `B::invoke` and `B::invoke` calls `C::invoke`. - -When a user Bob issues a transaction that calls `A::invoke`, the value of `contract-caller` in each successive invoke function's body would change: - -```clarity -in A::invoke, contract-caller = Bob -in B::invoke, contract-caller = A -in C::invoke, contract-caller = B -``` - -This allows contracts to make assertions and perform authorization checks using not only the `tx-sender` (which in this example, would always be "Bob"), but also using the `contract-caller`. This could be used to ensure that a particular function is only ever called directly and never called via an inter-contract call (by asserting that `tx-sender` and `contract-caller` are equal). We provide an example of a two different types of authorization checks in the rocket ship example below. - -## Smart contracts as principals - -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, for example: - -```clarity -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-name -``` - -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 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 qualified identifier for the contracts would be: - -```clarity -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-A -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-B -``` - -But, in the contract source code, if the developer wishes to call a function from `contract-A` in `contract-B`, they can write - -```clarity -(contract-call? .contract-A public-function-foo) -``` - -This allows the smart contract developer to modularize their applications across multiple smart contracts _without_ knowing the publishing key a priori. - -In order for a smart contract to operate on assets it owns, smart contracts may use the special `(as-contract ...)` function. This function executes the expression (passed as an argument) with the `tx-sender` set to the contract's principal, rather than the current sender. The `as-contract` function returns the value of the provided expression. - -For example, a smart contract that implements something like a "token faucet" could be implemented as so: - -```clarity -(define-map claimed-before - ((sender principal)) - ((claimed bool))) - -(define-constant err-already-claimed u1) -(define-constant err-faucet-empty u2) -(define-constant stx-amount u1) - -(define-public (claim-from-faucet) - (let ((requester tx-sender)) ;; set a local variable requester = tx-sender - (asserts! (is-none (map-get? claimed-before {sender: requester})) (err err-already-claimed)) - (unwrap! (as-contract (stx-transfer? stx-amount tx-sender requester)) (err err-faucet-empty)) - (map-set claimed-before {sender: requester} {claimed: true}) - (ok stx-amount))) -``` - -In this example, the public function `claim-from-faucet`: - -- Checks if the sender has claimed from the faucet before. -- Assigns the tx sender to a `requester` variable. -- Adds an entry to the tracking map. -- Uses `as-contract` to send 1 microstack - -Unlike other principals, there is no private key associated with a smart contract. As it lacks a private key, a Clarity smart contract cannot broadcast a signed transaction on the blockchain. - -## Example: Authorization checks - -The interactions between `tx-sender`, `contract-caller` and `as-contract` are subtle, but are important when performing authorization checks in a contract. In this example contract, we'll show two different kinds of authorization checks a contract may wish to perform, and then walk through how different ways in which contract functions may be called will pass or fail those checks. - -This contract defines a "rocket-ship" non-fungible-token that a principal may own and manage the authorized pilots. Pilots are principals that are allowed to "fly" the rocket ship. - -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. -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 be called _directly_ by the ship's owner, rather than through a inter-contract-call. - -The second type of check is more restrictive than the first check, and is helpful for guarding very sensitive routines --- it protects users from unknowingly calling a function on a malicious contract that subsequently tries to call sensitive functions on another contract. - -```clarity -;; -;; rockets-base.clar -;; - -(define-non-fungible-token rocket-ship uint) - -;; a map from rocket ships to their allowed -;; pilots -(define-map allowed-pilots - ((rocket-ship uint)) ((pilots (list 10 principal)))) - -;; implementing a contains function via fold -(define-private (contains-check - (y principal) - (to-check { p: principal, result: bool })) - (if (get result to-check) - to-check - { p: (get p to-check), - result: (is-eq (get p to-check) y) })) - -(define-private (contains (x principal) (find-in (list 10 principal))) - (get result (fold contains-check find-in - { p: x, result: false }))) - -(define-read-only (is-my-ship (ship uint)) - (is-eq (some tx-sender) (nft-get-owner? rocket-ship ship))) - -;; this function will print a message -;; (and emit an event) if the tx-sender was -;; an authorized flyer. -;; -;; here we use tx-sender, because we want -;; to allow the user to let other contracts -;; fly the ship on behalf of users - -(define-public (fly-ship (ship uint)) - (let ((pilots (default-to - (list) - (get pilots (map-get? allowed-pilots { rocket-ship: ship }))))) - (if (contains tx-sender pilots) - (begin (print "Flew the rocket-ship!") - (ok true)) - (begin (print "Tried to fly without permission!") - (ok false))))) -;; -;; Authorize a new pilot. -;; -;; here we want to ensure that this function -;; was called _directly_ by the user by -;; checking that tx-sender and contract-caller are equal. -;; if any other contract is in the call stack, contract-caller -;; would be updated to a different principal. -;; -(define-public (authorize-pilot (ship uint) (pilot principal)) - (begin - ;; sender must equal caller: an intermediate contract is - ;; not issuing this call. - (asserts! (is-eq tx-sender contract-caller) (err u1)) - ;; sender must own the rocket ship - (asserts! (is-eq (some tx-sender) - (nft-get-owner? rocket-ship ship)) (err u2)) - (let ((prev-pilots (default-to - (list) - (get pilots (map-get? allowed-pilots { rocket-ship: ship }))))) - ;; don't add a pilot already in the list - (asserts! (not (contains pilot prev-pilots)) (err u3)) - ;; append to the list, and check that it is less than - ;; the allowed maximum - (match (as-max-len? (append prev-pilots pilot) u10) - next-pilots - (ok (map-set allowed-pilots {rocket-ship: ship} {pilots: next-pilots})) - ;; too many pilots already - (err u4))))) -``` - -### Extending functionality: Multi-flyer contract - -The authorization scheme for `fly-ship` allows pilots to fly rocket-ships from other contracts. This allows other contracts to provide new functionality built around calling that function. - -For example, we can create a contract that calls `fly-ship` for multiple rocket-ships in a single transaction: - -```clarity -;; -;; rockets-multi.clar -;; - -(define-private (call-fly (ship uint)) - (unwrap! (contract-call? .rockets-base fly-ship ship) false)) -;; try to fly all the ships, returning a list of whether -;; or not we were able to fly the supplied ships -(define-public (fly-all (ships (list 10 uint))) - (ok (map call-fly ships))) -``` - -### Authorization for Contract-Owned Assets - -The check in `authorize-pilot` protects users from malicious contracts, but how would such a scheme support contract-owned assets? This is what the `as-contract` function is used for. The `as-contract` function executes the supplied closure as if the sender of the transaction was the current contract, rather than the user -- it does this by updating `tx-sender` to the current contract principal. We can use this to, for example, create a smart contract rocket-ship-line: - -```clarity -;; -;; rockets-ship-line.clar -;; - -(define-constant line-ceo 'SP19Y6GRV9X778VFS1V8WT2H502WFK33XZXADJWZ) - -(define-data-var employed-pilots (list 10 principal) (list)) - -;; This function will: -;; * check that it is called by the line-ceo -;; * check that the rocket is owned by the contract -;; * authorize each employed pilot to the ship -(define-public (add-managed-rocket (ship uint)) - (begin - ;; 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 - (asserts! (contract-call? .rockets-base is-my-ship ship) (err u2)) - ;; register all of our pilots on the ship - (add-pilots-to ship))))) - -;; add all the pilots to a ship using fold -- -;; the fold checks the return type of previous calls, -;; skipping subsequent contract-calls if one fails. -(define-private (add-pilot-via-fold (pilot principal) (prior-result (response uint uint))) - (let ((ship (try! prior-result))) - (try! (contract-call? .rockets-base authorize-pilot ship pilot)) - (ok ship))) -(define-private (add-pilots-to (ship uint)) - (fold add-pilot-via-fold (var-get employed-pilots) (ok ship))) -``` - -In order for the contract to add each pilot to a new ship, the contract must call `authorize-pilot`. However, the contract wants to perform this action on behalf of a ship the _contract_ owns, not the transaction sender. To do this, the contract uses `as-contract`. diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md b/i18n/vi/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md deleted file mode 100644 index a01e37bc04..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Resources -description: 'Resources' -sidebar_position: 8 ---- - -# External resources - - -[Clarity book](https://book.clarity-lang.org/) - -[Clarity Universe](https://stacks.org/clarity-universe) - -[Hiro Clarity tutorials](https://docs.hiro.so/tutorials) diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md b/i18n/vi/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md deleted file mode 100644 index ed65829518..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Clarity development software -description: The following tools are useful when developing Clarity smart contracts -sidebar_position: 4 ---- - -## Language Server Protocol for Clarity (including Visual Studio Code extension) - -The Language Server Protocol (LSP) defines the protocol used between an editor or IDE and a language server that provides language features like auto complete, go to definition, find all references etc. - -This makes programming in Clarity easier and much more intuitive. - -![Clarity LSP Screenshot](https://raw.githubusercontent.com/hirosystems/clarity-lsp/21b64298ca117dc41358eb9dce4605cc4a448a4c/images/screenshot.png?raw=true) - - -Clarity LSP repository is available [here](https://github.com/hirosystems/clarity-lsp). The extension for Visual Studio Code can be downloaded directly from [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=HiroSystems.clarity-lsp), but can be and older version. For a more up to date version you can also download it from [open-vsx](https://open-vsx.org/extension/hirosystems/clarity-lsp). - -## Clarity REPL - -A read—eval—print loop (REPL), also termed an interactive toplevel or language shell, is a simple, interactive computer programming environment that takes single user inputs (that is, single expressions), evaluates (executes) them, and returns the result to the user; a program written in a REPL environment is executed piecewise. - -![Clarity-repl](https://github.com/hirosystems/clarity-repl/blob/develop/docs/images/screenshot.png?raw=true) - -Instructions on how to install Clarity REPL can be found [here](https://github.com/hirosystems/clarity-repl). - -## Clarinet - -Clarinet is a Clarity runtime packaged as a command line tool, designed to facilitate smart contract understanding, development, testing and deployment. Clarinet consists of a Clarity REPL and a testing harness, which, when used together allow you to rapidly develop and test a Clarity smart contract, with the need to deploy the contract to a local devnet or testnet. - -![Clarinet](https://github.com/hirosystems/clarinet/blob/develop/docs/images/demo.gif?raw=true) - -Installation instructions, including build from source instructions can be found [here](https://github.com/hirosystems/clarinet). If you prefer you can directly download the latest compiled realease for Windows, Mac and Linux [here](https://github.com/hirosystems/clarinet/releases). - -[Clarinet 101](https://www.youtube.com/playlist?list=PL5Ujm489LoJaAz9kUJm8lYUWdGJ2AnQTb) contains multiple Clarinet video tutorials - -### Getting started with Clarinet - -You can verify you have Clarinet installed by checking its version: - -```bash -$ clarinet --version -clarinet 0.70 -``` - -More detailed information on using Clarinet is available [here](https://book.clarity-lang.org/ch07-00-using-clarinet.html). However to get you started, the following commands are important to know. - -Create a new project and enter its directory: - -```bash -clarinet new my-project && cd my-project -``` - -Create a new contract inside `my-project`: - -```bash -clarinet contract new mycoolcontract -``` - -Check the syntax of Clarity: - -```bash -clarity check -``` - -To test your contract: - -```bash -clarinet test -``` - -Enter Clarinet's console: - -```bash -clarinet console -``` diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md b/i18n/vi/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md deleted file mode 100644 index c3bc8944d7..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: Tokens -description: Learn about token support within Clarity -sidebar_position: 3 ---- - -## Introduction - -A fundamental use of blockchain technology is the representation, store, and transfer of value between users of a blockchain. Cryptocurrency is a very common use of blockchain technology, and remains one of the primary drivers of adoption of blockchain technology. Cryptocurrencies are represented by blockchain tokens: individual units of value within a given blockchain ecosystem. Blockchain tokens can extend beyond just digital currency, however, and recent developments throughout the cryptocurrency community have demonstrated potential for the use of blockchain to tokenize and represent not just money but other tangible assets. - -A blockchain token is a digital asset that can be verifiably owned by a user of a blockchain. Blockchain tokens are governed by a set of rules that are defined by either the blockchain itself (in the case of native tokens) or by a smart contract on a blockchain. Rules can vary depending on the nature and the use of the token. - -Tokens on a blockchain fall into two general categories, depending on their properties: [fungible][] or [non-fungible][]. The following sections discuss the properties of both types of tokens, and provide information about implementation of the two types of tokens on Stacks. - -## Fungible tokens - -A core property of any token on a blockchain is fungibility. A fungible token is a token that's mutually interchangable or capable of mutual substitution. In other words, one quantity or part of a fungible token can be replaced by an equal quantity or part of the same fungible token. Fungible tokens are often used to represent real-world fungible assets like currency. The STX token is an example of a fungible token. Other examples include stablecoins, tokens that represent voting rights in a DAO, or tokens that algorithmically track the price of stocks. - -Fungible tokens form one of the most important value propositions for blockchain technology, the ability to store value and exchange that value through both internal and external transactions. Because fungible tokens can be divided into smaller parts and recombined into the same value representation, they serve a great utility for transferring value between blockchain users. - -The primary fungible token on the Stacks blockchain is the native token, STX. Because the Stacks blockchain allows for the creation of \[smart contracts\]\[\], other fungible tokens can be created on the Stacks blockchain as well. [SIP-010][] specifies the standard for fungible tokens on the Stacks blockchain. This specification defines the functions and traits that a fungible token on Stacks _must_ have. By complying with this standard, fungible tokens on Stacks can be easily represented by wallets that support Stacks. - -### Understanding the fungible token standard - -The [SIP-010][] standard is an interface definition that allows Stacks applications and wallets to interact with fungible tokens in a standard way. Supporting the standard reduces complexity for token creators to get their tokens into the ecosystem. Under the [SIP-010][] standard, fungible tokens must have the following characteristics: - -- Ability to transfer a specified amount of the token to a recipient (`transfer`). The recipient is required to be a Stacks principal. -- Ability to obtain the human-readable name of the token (`get-name`). -- Ability to obtain a short name (ticker symbol) for the token (`get-symbol`). -- Ability to get the number of decimals in the token representation (`get-decimals`). This is used to construct a representation of the token that humans would be familiar dealing with. For example, the US dollar has 2 decimals, if the base unit is cents. -- Ability to get the balance of the token for a particular Stacks principal (`get-balance-of`). -- Ability to get the total supply of the token (`get-total-supply`). -- A URI to metadata associated with the token (`get-token-uri`). This can resolve to off-chain metadata about the token or contract, such as an image icon for the token or a description. - -## Non-fungible tokens (NFTs) - -Non-fungible tokens (NFTs) are a type of token that are not interchangeable. NFTs have unique traits (usually in the form of attached metadata) that restrict the abillity to replace them with identical tokens. An NFT is a token that is unique, such as a piece of art, or ownership rights to a real-world asset such as a house. - -NFTs alone don't have an inherent value, like a currency. The value of an NFT is derived from the assets that the NFT represents. The use of NFTs are myriad, including digital art, collectibles, domain names, and representation of ownership of content rights. NFTs can be used as digital certificates that track the authenticty of real world items, or digitize the ownership rights to property. - -As with fungible tokens, NFTs on the Stacks blockchain are created with smart contracts. [SIP-009][] specifies the standard for NFTs on the Stacks blockchain. This specification defines the functions and traits that an NFT _must_ have, but most NFTs have more functions or traits attached than those solely described by the specification. By complying with this standard, non-fungible tokens on Stacks can be easily represented by wallets that support Stacks. - -### Understanding the non-fungible token standard - -The [SIP-009][] standard is an interface definition that the Stacks ecosystem aligned on. With support for this standard across wallets and tools, it becomes easy to interact with NFTs. Under the [SIP-009][] standard, NFT contract must have the following characteristics: - -- Ability to obtain the last token identifier (`get-last-token-id`). This id represents the upper limit of NFTs issued by the contract. -- A URI to metadata associated with a specific token identifier. (`get-token-uri`). This URI could resolve to a JSON file with information about the creator, associated media files, descriptions, signatures, and more. -- Ability to verify the owner for a given token identifier (`get-owner`). The owner resolves to a [Stacks principal](principals). -- Ability to transfer an NFT to a recipient (`transfer`). The recipient is required to be a Stacks principal. - -## Further reading - -- [The Difference Between Fungible and Non-Fungible Tokens](https://101blockchains.com/fungible-vs-non-fungible-tokens/) -- [Explain It Like I Am 5: NFTs](https://messari.io/article/explain-it-like-i-am-5-nfts) - -[fungible]: #fungible-tokens -[non-fungible]: #non-fungible-tokens-nfts -[SIP-010]: https://github.com/stacksgov/sips/blob/main/sips/sip-010/sip-010-fungible-token-standard.md -[SIP-009]: https://github.com/stacksgov/sips/blob/main/sips/sip-009/sip-009-nft-standard.md diff --git a/i18n/vi/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md b/i18n/vi/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md deleted file mode 100644 index fc4765aa0c..0000000000 --- a/i18n/vi/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md +++ /dev/null @@ -1,301 +0,0 @@ ---- -title: Clarity Values -description: Learn how to deal with Clarity Values in JavaScript -sidebar_position: 2 ---- - -## Introduction - -The Clarity language makes use of a strong static 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/hirosystems/stacks.js/tree/master/packages/transactions) library makes this easy, as we will demonstrate below. - -## Clarity Types - -Please see the following page for information on [Clarity Types](../write-smart-contracts/clarity-language/language-types). - -## Constructing Clarity Values and accessing their data - -Clarity values can be constructed with functions provided by the [@stacks/transactions](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library. These functions simply output javascript objects that contain a value and a numerical representation of the Clarity type information. The Clarity types are encoded as follows: - -```typescript -export enum ClarityType { - Int = 0, - UInt = 1, - Buffer = 2, - BoolTrue = 3, - BoolFalse = 4, - PrincipalStandard = 5, - PrincipalContract = 6, - ResponseOk = 7, - ResponseErr = 8, - OptionalNone = 9, - OptionalSome = 10, - List = 11, - Tuple = 12, - StringASCII = 13, - StringUTF8 = 14, -} -``` - -`ClarityValue` objects can be serialized and included in transactions that interact with published Clarity contracts. - -Here are examples of how to construct each type of Clarity value, and how to access its data if it has any: - -### Booleans - -```typescript -const t = trueCV(); -// { type: ClarityType.BoolTrue } - -const f = falseCV(); -// { type: ClarityType.BoolFalse } -``` - -Boolean Clarity Values don't contain any underlying data. They are simply objects with `type` information. - -### Optional Values - -```typescript -const nothing: NoneCV = noneCV(); -// { type: ClarityType.OptionalNone } - -const something: SomeCV = someCV(trueCV()); -// { type: ClarityType.OptionalSome, value: { type: 4 } } -``` - -Optional Clarity Values can either be nothing (an empty type that has no data), or something (a wrapped value). - -If you are dealing with a function or contract function that returns an `OptionalCV`, you should always check what type it is before trying to access its value. - -```typescript -const maybeVal: OptionalCV = await callReadOnlyFunction(...); - -if (maybeVal.type === ClarityType.OptionalSome) { - console.log(maybeVal.value); -} else if (maybeVal.type === ClarityType.OptionalNone) { - // deal with `none` value -} -``` - -### Buffers - -```typescript -const buffer = Buffer.from('foo'); -const bufCV: BufferCV = bufferCV(buffer); -// { type: ClarityType.Buffer, buffer: } -``` - -### Integers - -Clarity supports both integers and unsigned integers. - -```typescript -const i: IntCV = intCV(-10); -// { type: ClarityType.Int, value: BN { ... } } - -const u: UIntCV = uintCV(10); -// { type: ClarityType.UInt, value: BN { ... } } -``` - -Clarity value ints store their underlying data as `BigNum` values from the [bn.js](https://github.com/indutny/bn.js/) library. - -In order to display/print Clarity (u)int values, use the `cvToString(val)` method. - -If you wish to perform arithmetic operations using Clarity (u)int values, you must use methods from the `BigNum` api on their underlying `BigNum` values, and the construct a new Clarity value out of the result. For example: - -```typescript -const x = intCV(1); -const y = intCV(2); - -x.value.add(y.value); -// 3 -``` - -### Strings - -```typescript -const ascii: StringAsciiCV = stringAsciiCV('hello world'); -// { type: ClarityType.StringASCII, data: 'hello world' } - -const utf8: StringUtf8CV = stringUtf8CV('hello 🌾'); -// { type: ClarityType.StringUTF8, data: 'hello 🌾' } -``` - -Clarity supports both ascii and utf8 strings. - -### Principals - -```typescript -const address = 'SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B'; -const contractName = 'contract-name'; - -const spCV = standardPrincipalCV(address); -// { -// type: ClarityType.PrincipalStandard -// address: { -// type: StacksMessageType.Address, -// version: AddressVersion.MainnetSingleSig, -// hash160: "SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B" -// } -// } - -const cpCV = contractPrincipalCV(address, contractName); -// { -// type: ClarityType.PrincipalContract, -// contractName: { -// type: StacksMessageType.LengthPrefixedString, -// content: 'contract-name', -// lengthPrefixBytes: 1, -// maxLengthBytes: 128, -// }, -// address: { -// type: StacksMessageType.Address, -// version: AddressVersion.MainnetSingleSig, -// hash160: "SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B" -// } -// } -``` - -Both kinds of Clarity principal values contain `type` information and an `address` object. Contract principals also contain a `contractName`. - -### Response Values - -```typescript -const errCV = responseErrorCV(trueCV()); -// { type: ResponseErr, value: { type: ClarityType.BoolTrue } } - -const okCV = responseOkCV(falseCV()); -// { type: ResponseOk, value: { type: ClarityType.BoolFalse } } -``` - -Response Clarity Values will either have the type `ClarityType.ResponseOk` or `ClarityType.ResponseErr`. They both contain a Clarity Value. Often this value will be an integer error code if the response is an `Error`. - -### Tuples - -```typescript -const tupCV = tupleCV({ - a: intCV(1), - b: trueCV(), - c: falseCV(), -}); -// { -// type: ClarityType.Tuple, -// data: { -// a: { type: ClarityType.Int, value: BN { ... } }, -// b: { type: ClarityType.BoolTrue }, -// c: { type: ClarityType.BoolFalse }, -// } -// } - -console.log(tupCV.data['b']); -// { type: ClarityType.BoolTrue } -``` - -Tuples in Clarity are typed and contain named fields. The tuple above, for example, contains three fields with the names **a**, **b** and **c**, and the types of their values are `Int`, `Boolean` and `Boolean`, respectively. - -Clarity tuples are represented in JavaScript as objects and a tuple's data can be accessed by its `data` field, where the underlying JS object is stored. - -### Lists - -```typescript -const l = listCV([trueCV(), falseCV()]); -// { type: ClarityType.List, list: [{ type: ClarityType.BoolTrue }] } - -console.log(l.list[0]); -// { type: ClarityType.BoolTrue } -``` - -Lists, in Clarity, are homogeneous, meaning they can only contain elements of a singular (Clarity) type. Make sure to avoid constructing lists that have elements of multiple types. - -A Clarity lists underlying data can be accessed via its `list` field. - -## Using Clarity Values - -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](../understand-stacks/transactions#construction). - -## Utilizing Clarity Values from Transaction Responses - -`Read-only` Clarity functions can return Clarity values as a response. These `read-only` functions can be accessed easily in JavaScript via the [`callReadOnlyFunction()`](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions#calling-read-only-contract-function) function included in `@stacks/transactions`, which returns a `ClarityValue`. - -As mentioned above, `ClarityValues` are simply javascript objects containing a value and its associated Clarity type information. These object types are defined [here](https://github.com/hirosystems/stacks.js/tree/1f2b5fd8bdf1c2b5866e8171163594d7708a8c7a/packages/transactions/src/clarity/types). - -When you are calling a `read-only` contract function, you will always know what type the function will return, since functions in Clarity are strongly typed. - -It is common for Clarity functions to return values wrapped in a `Response`, in order to indicate if there was success or an error. - -Since every `ClarityValue` has a `type` field, the type of the result of a `read-only` function call can be checked and acted upon like so: - -```typescript -const contractAddress = 'ST3KC0MTNW34S1ZXD36JYKFD3JJMWA01M55DSJ4JE'; -const contractName = 'kv-store'; -const functionName = 'get-value'; -const buffer = bufferCVFromString('foo'); -const network = new StacksTestnet(); // for mainnet, use `StacksMainnet()` -const senderAddress = 'ST2F4BK4GZH6YFBNHYDDGN4T1RKBA7DA1BJZPJEJJ'; - -const options = { - contractAddress, - contractName, - functionName, - functionArgs: [buffer], - network, - senderAddress, -}; - -// make a read-only call to a contract function that -// returns a Response -const result: ResponseCV = await callReadOnlyFunction(options); - -if (result.type === ClarityType.ResponseOk) { - console.log(cvToString(result.value)); -} else if (result.type === ClarityType.ResponseErr) { - throw new Error(`kv-store contract error: ${result.value.data}`); -} -``` - -### ClarityValues to/from Hex - -If you receive a response from a transaction in the form of a `hex` string, you can deserialize it into a Clarity value like so: - -```javascript -import { hexToCV } from '@stacks/transactions'; - -let cv = hexToCV('hex_string'); -``` - -Similarly, you can convert a Clarity value to `hex` string like so: - -```javascript -import { cvToHex, trueCV } from '@stacks/transactions'; - -let trueHex = cvToHex(trueCV()); -``` - -## Debugging Clarity Values - -Sometimes you might receive a Clarity value that you were not expecting. Logging the value to your console won't always prove to be useful, unless you have memorized the Clarity value type enum values. - -In order to figure out what kind of value you are dealing with, you can use the `cvToString()` function to convert the Clarity value to a more easily readable string. - -For example, calling `cvToString()` on a large `tuple` might yield something like: - -``` -(tuple - (a -1) - (b u1) - (c 0x74657374) - (d true) - (e (some true)) - (f none) - (g SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B) - (h SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B.test) - (i (ok true)) - (j (err false)) - (k (list true false)) - (l (tuple (a true) (b false))) - (m "hello world") - (n u"hello \u{1234}"))` -``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/blockchain/index.md b/i18n/zh/docusaurus-plugin-content-docs/current/blockchain/index.md deleted file mode 100644 index 87406c32b5..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/blockchain/index.md +++ /dev/null @@ -1,178 +0,0 @@ ---- -title: Blockchain -description: Stacks Blockchain -sidebar_position: 6 ---- - -Below is a guide to start working locally with the Stacks Blockchain. - -Code repository is [here](https://github.com/stacks-network/stacks-blockchain). - -## Getting started with the Stacks Blockchain - -### Download and build stacks-blockchain - -The first step is to ensure that you have Rust and the support software installed. - -```bash -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -``` - -:::info -For building on Windows, follow the rustup installer instructions at https://rustup.rs/ -::: - -From there, you can clone the Stacks Blockchain repository: - -```bash -git clone --depth=1 https://github.com/stacks-network/stacks-blockchain.git - -cd stacks-blockchain -``` - -Then build the project: - -```bash -cargo build -``` - -Run the tests: - -```bash -cargo test testnet -- --test-threads=1 -``` - -### Encode and sign transactions - -在这里,我们产生了一个将用于签署即将进行的交易的关键词: - -```bash -cargo run --bin blockstack-cli generate-sk --testnet - -# Output -# { -# secretKey: "b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001", -# publicKey: "02781d2d3a545afdb7f6013a8241b9e400475397516a0d0f76863c6742210539b5", -# stacksAddress: "ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH" -# } -``` - -This keypair is already registered in the `testnet-follower-conf.toml` file, so it can be used as presented here. - -We will interact with the following simple contract `kv-store`. In our examples, we will assume this contract is saved to `./kv-store.clar`: - -```scheme -(define-map store { key: (string-ascii 32) } { value: (string-ascii 32) }) - -(define-public (get-value (key (string-ascii 32))) - (match (map-get? store { key: key }) - entry (ok (get value entry)) - (err 0))) - -(define-public (set-value (key (string-ascii 32)) (value (string-ascii 32))) - (begin - (map-set store { key: key } { value: value }) - (ok true))) -``` - -We want to publish this contract on chain, then issue some transactions that interact with it by setting some keys and getting some values, so we can observe read and writes. - -Our first step is to generate and sign, using your private key, the transaction that will publish the contract `kv-store`. To do that, we will use the subcommand `blockstack-cli` that has the following usage: - -```bash -blockstack-cli (options) publish [publisher-secret-key-hex] [fee-rate] [nonce] [contract-name] [file-name.clar] -``` - -With the following arguments: - -```bash -cargo run --bin blockstack-cli publish b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 515 0 kv-store ./kv-store.clar --testnet -``` - -The `515` is the transaction fee, denominated in microSTX. Right now, the testnet requires one microSTX per byte minimum, and this transaction should be less than 515 bytes. The third argument `0` is a nonce, that must be increased monotonically with each new transaction. - -This command will output the **binary format** of the transaction. In our case, we want to pipe this output and dump it to a file that will be used later in this tutorial. - -```bash -cargo run --bin blockstack-cli publish b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 515 0 kv-store ./kv-store.clar --testnet | xxd -r -p > tx1.bin -``` - -### Run the testnet - -You can observe the state machine in action locally by running: - -```bash -cargo stacks-node start --config=./testnet/stacks-node/conf/testnet-follower-conf.toml -``` - -`testnet-follower-conf.toml` is a configuration file that you can use for setting genesis balances or configuring Event observers. You can grant an address an initial account balance by adding the following entries: - -``` -[[ustx_balance]] -address = "ST2VHM28V9E5QCRD6C73215KAPSBKQGPWTEE5CMQT" -amount = 100000000 -``` - -The `address` field is the Stacks testnet address, and the `amount` field is the number of microSTX to grant to it in the genesis block. The addresses of the private keys used in the tutorial below are already added. - -### Publish your contract - -Assuming that the testnet is running, we can publish our `kv-store` contract. - -In another terminal (or file explorer), you can move the `tx1.bin` generated earlier, to the mempool: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx1.bin http://localhost:20443/v2/transactions -``` - -In the terminal window running the testnet, you can observe the state machine's reactions. - -### Reading from / Writing to the contract - -Now that our contract has been published on chain, let's try to submit some read / write transactions. We will start by trying to read the value associated with the key `foo`. - -To do that, we will use the subcommand: - -```bash -cargo run --bin blockstack-cli contract-call --help -``` - -With the following arguments: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 1 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store get-value -e \"foo\" --testnet | xxd -r -p > tx2.bin -``` - -`contract-call` generates and signs a contract-call transaction. - -We can submit the transaction by moving it to the mempool path: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx2.bin http://localhost:20443/v2/transactions -``` - -Similarly, we can generate a transaction that would be setting the key `foo` to the value `bar`: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 2 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store set-value -e \"foo\" -e \"bar\" --testnet | xxd -r -p > tx3.bin -``` - -And submit it by moving it to the mempool path: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx3.bin http://localhost:20443/v2/transactions -``` - -Finally, we can issue a third transaction, reading the key `foo` again, for ensuring that the previous transaction has successfully updated the state machine: - -```bash -cargo run --bin blockstack-cli contract-call b8d99fd45da58038d630d9855d3ca2466e8e0f89d3894c4724f0efc9ff4b51f001 500 3 ST2ZRX0K27GW0SP3GJCEMHD95TQGJMKB7G9Y0X1MH kv-store get-value -e \"foo\" --testnet | xxd -r -p > tx4.bin -``` - -And submit this last transaction by moving it to the mempool path: - -```bash -curl -X POST -H "Content-Type: application/octet-stream" --data-binary @./tx4.bin http://localhost:20443/v2/transactions -``` - -Congratulations, you can now [write your own smart contracts with Clarity](write-smart-contracts/). diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/blockchain/networks.md b/i18n/zh/docusaurus-plugin-content-docs/current/blockchain/networks.md deleted file mode 100644 index fe9725352c..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/blockchain/networks.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Stacks Blockchain Networks -description: Stacks Blockchain Networks -sidebar_position: 3 ---- - -### Stacks Blockchain Networks - -- [x] **Krypton** is a Stacks 2 testnet with a fixed, two-minute block time, called `regtest`. Regtest is generally unstable for regular use, and is reset often. See the [regtest documentation](understand-stacks/testnet) for more information on using regtest. - -- [x] **Testnet** (old Xenon) is the Stacks 2 public testnet, which runs PoX against the Bitcoin testnet. It is the full implementation of the Stacks 2 blockchain, and should be considered a stable testnet for developing Clarity smart contracts. See the [testnet documentation](understand-stacks/testnet) for more information on the public testnet. - -- [x] **Mainnet** is the fully functional Stacks 2 blockchain, see the [Stacks overview](understand-stacks/) for information on running a Stacks node, mining, stacking, and writing Clarity smart contracts. diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md b/i18n/zh/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md deleted file mode 100644 index ede026fd4b..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/blockchain/stacks-blockchain-api.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Stacks Blockchain API -description: Interacting with the Stacks 2.0 Blockchain via API -sidebar_position: 4 ---- - -## Introduction - -:::tip API Documentation Official API Documentation is available [here](https://stacks-network.github.io/stacks-blockchain/). ::: - - -The Stacks 2.0 Blockchain API allows you to query the Stacks 2.0 blockchain and interact with smart contracts. It was built to maintain pageable materialized views of the Stacks 2.0 Blockchain. It was built to maintain pageable materialized views of the Stacks 2.0 Blockchain. It was built to maintain pageable materialized views of the Stacks 2.0 Blockchain. It was built to maintain pageable materialized views of the Stacks 2.0 Blockchain. - -:::caution The RESTful API is developed by Hiro. Hiro also hosts a public API node for easy onboarding. Using it requires you to trust the hosted server, but provides a faster onboarding experience. :::caution The RESTful API is developed by Hiro. Hiro also hosts a public API node for easy onboarding. Using it requires you to trust the hosted server, but provides a faster onboarding experience. You can [run your own API server](https://docs.hiro.so/get-started/running-api-node) ::: - -The RESTful JSON API can be used without any authorization. The basepath for the API is: The basepath for the API is: The basepath for the API is: The basepath for the API is: - -```bash -# for mainnet, replace `testnet` with `mainnet` -https://stacks-node-api.testnet.stacks.co/ -``` - -:::note This documentation only covers endpoints that are exposed on a Stacks node, referred to as the RPC API. For full documentation on the RESTful API, check out the [Hiro's API reference](https://docs.hiro.so/api). ::: :::note This documentation only covers endpoints that are exposed on a Stacks node, referred to as the RPC API. For full documentation on the RESTful API, check out the [Hiro's API reference](https://docs.hiro.so/api). ::: For full documentation on the RESTful API, check out the [Hiro's API reference](https://docs.hiro.so/api). ::: ::: - -### Stacks Node RPC API - -The [stacks-node implementation](https://github.com/stacks-network/stacks-blockchain/) exposes JSON RPC endpoints. - -All `/v2/` routes a proxied to a Hiro-hosted Stacks Node. For a trustless architecture, you should make these requests to a self-hosted node. All `/v2/` routes a proxied to a Hiro-hosted Stacks Node. For a trustless architecture, you should make these requests to a self-hosted node. For a trustless architecture, you should make these requests to a self-hosted node. All `/v2/` routes a proxied to a Hiro-hosted Stacks Node. For a trustless architecture, you should make these requests to a self-hosted node. For a trustless architecture, you should make these requests to a self-hosted node. - -## Proxied Stacks Node RPC API endpoints - -The Stacks 2.0 Blockchain API is centrally hosted. The Stacks 2.0 Blockchain API is centrally hosted. However, every running Stacks node exposes an RPC API, which allows you to interact with the underlying blockchain. Instead of using a centrally hosted API, you can directly access the RPC API of a locally hosted Node. The Stacks 2.0 Blockchain API is centrally hosted. The Stacks 2.0 Blockchain API is centrally hosted. However, every running Stacks node exposes an RPC API, which allows you to interact with the underlying blockchain. Instead of using a centrally hosted API, you can directly access the RPC API of a locally hosted Node. Instead of using a centrally hosted API, you can directly access the RPC API of a locally hosted Node. The Stacks 2.0 Blockchain API is centrally hosted. However, every running Stacks node exposes an RPC API, which allows you to interact with the underlying blockchain. Instead of using a centrally hosted API, you can directly access the RPC API of a locally hosted Node. The Stacks 2.0 Blockchain API is centrally hosted. The Stacks 2.0 Blockchain API is centrally hosted. However, every running Stacks node exposes an RPC API, which allows you to interact with the underlying blockchain. Instead of using a centrally hosted API, you can directly access the RPC API of a locally hosted Node. Instead of using a centrally hosted API, you can directly access the RPC API of a locally hosted Node. - -:::tip -The Stacks Blockchain API proxies to Node RPC endpoints -::: - -While the Node RPC API doesn't give the same functionality as the hosted Stacks 2.0 Blockchain API, you get similar functionality in a way that is scoped to that specific node. The RPC API includes the following endpoints: The RPC API includes the following endpoints: The RPC API includes the following endpoints: The RPC API includes the following endpoints: - -- [POST /v2/transactions](https://docs.hiro.so/api#operation/post_core_node_transactions) -- [GET /v2/contracts/interface/{contract_address}/{contract_name}](https://docs.hiro.so/api#operation/get_contract_interface) -- [POST /v2/map_entry/{contract_address}/{contract_name}/{map_name}](https://docs.hiro.so/api#operation/get_contract_data_map_entry) -- [GET /v2/contracts/source/{contract_address}/{contract_name}](https://docs.hiro.so/api#operation/get_contract_source) -- [GET /v2/accounts/{principal}](https://docs.hiro.so/api#operation/get_account_info) -- [POST /v2/contracts/call-read/{contract_address}/{contract_name}/{function_name}](https://docs.hiro.so/api#operation/call_read_only_function) -- [GET /v2/fees/transfer](https://docs.hiro.so/api#operation/get_fee_transfer) -- [GET /v2/info](https://docs.hiro.so/api#operation/get_core_api_info) - -:::caution If you run a local node, it exposes an HTTP server on port `20443`. The info endpoint would be `localhost:20443/v2/info`. ::: :::caution If you run a local node, it exposes an HTTP server on port `20443`. The info endpoint would be `localhost:20443/v2/info`. ::: The info endpoint would be `localhost:20443/v2/info`. ::: ::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md b/i18n/zh/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md deleted file mode 100644 index 71e3542302..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/blockchain/stacks-releases.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: Stacks Releases -description: Stacks Blockchain Releases -sidebar_position: 2 ---- - -:::info -This page needs contributions. Help us improve it. -::: - -### Stacks Blockchain Releases - -All releases are published [here](https://github.com/stacks-network/stacks-blockchain/releases). Most important ones are described below. - -### Stacks 2.1 - -Scheduled for release at the end of 2022. - -More information on [what to expect with Stacks 2.1](https://stacks.org/stacks-21-what-to-expect). - -#### Stacks 2.05 -Activated on [Bitcoin block 713000](https://explorer.stacks.co/txid/0xece8e369310b5ff9b92ef11181ae0d2457ac0c821376d4a96c4998763e22ad04?chain=mainnet). - -This breaking change enables storage cost for list to be based on actual length and change in number of indexed I/O operations. More info on this [blog post](https://www.stacks.org/stacks-2-05?ref=docs-website). - -#### Stacks 2.0 -Activated on January 14th 2021 - -This hard fork enables Stacking, Clarity smart contracts, scalable transactions, and also building directly on Bitcoin. More info [here](https://forum.stacks.org/t/path-to-mainnet-for-stx-holders-things-to-know-ahead-of-stacks-2-0/11529). - -#### Stacks Genesis -Released on 2018, October 30th UTC+6 at Bitcoin block height 547921 - -This hard fork addresses registration of digital assets with Stacks token and also distribution of Stacks token to the existing purchasers. More info [here](https://blog.blockstack.org/the-launch-of-the-stacks-genesis-block/?ref=docs-website). - diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md b/i18n/zh/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md deleted file mode 100644 index f7355828e5..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/build-apps/deploy-tips.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Deploy tips -description: Learn some common methods for deploying your application. ---- - -## Introduction - -Stacks applications are web applications that authenticate users with Stacks Auth and store data with Gaia. Both of these technologies can be accessed on the client side. As such, Stacks apps tend to be simple in design and operation, since in many cases, they don’t have to host anything besides the application’s assets. Both of these technologies can be accessed on the client side. As such, Stacks apps tend to be simple in design and operation, since in many cases, they don’t have to host anything besides the application’s assets. Both of these technologies can be accessed on the client side. As such, Stacks apps tend to be simple in design and operation, since in many cases, they don’t have to host anything besides the application’s assets. - -## Where to deploy your application - -Before users can interact with your application, you must deploy it on a server that is accessible over the internet. Deploying requires that you: Deploying requires that you: Deploying requires that you: - -- Configure or customize the files in the `public` directory. -- Build your application site for deployment. -- Copy your generated application files to your production server. - -If you first populated your application with the Stacks application generator, your application contains the starting blocks for configuring, building, and deploying your app. For example, the React template builds out a scaffolding with the following building blocks. For example, the React template builds out a scaffolding with the following building blocks. For example, the React template builds out a scaffolding with the following building blocks. - -| File or Directory | Description | -| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| node_modules/react-scripts | A set of scripts for that helps you kick off React projects without configuring, so you do not have to set up your project by yourself. | -| package.json | Contains a scripts section that includes a reference to the react-scripts, which are a dependency. Contains a scripts section that includes a reference to the react-scripts, which are a dependency. This script creates a build directory containing your files for deployment. Contains a scripts section that includes a reference to the react-scripts, which are a dependency. This script creates a build directory containing your files for deployment. | -| public/favicon.ico | An example shortcut icon. | -| public/index.html | An entry page for an application. | -| public/manifest.json | A JSON file that describes your web application to the browser. | -| cors | Contains example deployment files for cross-origin request configuration. | - -If you use the generator to build JavasScript or Vue scaffolding, your project configuration files will be different. - -Regardless of which scaffolding you use, you must customize and extend this basic scaffolding as needed by your application. For example, you may want to add more properties to the `manifest.json` file. Since every application is different, Stacks Auth cannot give you specific instructions on how to do this. The steps you take are specific to your application. - -## Stacks Authentication and deployment - -When your application authenticates users with Stacks, the Stacks Wallet at on URL requests a resource (the app manifest) from your DApp. A request for a resource outside of the origin (the Stacks Wallet) 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. A request for a resource outside of the origin (the Stacks Wallet) 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. A request for a resource outside of the origin (the Stacks Wallet) 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 (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) 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) 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) - -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 Stacks Browser). 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 Stacks Browser). 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 Stacks 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`: - -```html -Access-Control-Allow-Origin: * Access-Control-Allow-Headers: "X-Requested-With, Content-Type, -Origin, Authorization, Accept, Client-Security-Token, Accept-Encoding" Access-Control-Allow-Methods: -"POST, GET, OPTIONS, DELETE, PUT" -``` - -Consult the documentation for your hosting service to learn how to configure CORS on that service. - -## Deployment and Radiks - -If you are deploying a Stacks application that uses [Radiks](https://github.com/stacks-network/radiks), your deployment includes a server and a database component. You must take this into account when deploying your application. You may want to choose a service such as [Heroku](https://www.heroku.com) or [Digital Ocean](https://www.digitalocean.com) if your app uses Radiks. You must take this into account when deploying your application. You may want to choose a service such as [Heroku](https://www.heroku.com) or [Digital Ocean](https://www.digitalocean.com) if your app uses Radiks. You must take this into account when deploying your application. You may want to choose a service such as [Heroku](https://www.heroku.com) or [Digital Ocean](https://www.digitalocean.com) if your app uses Radiks. diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/build-apps/index.md b/i18n/zh/docusaurus-plugin-content-docs/current/build-apps/index.md deleted file mode 100644 index e3d2f82f33..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/build-apps/index.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Build apps with Stacks -description: Authenticate users, sign transactions and store data with the Stacks blockchain -sidebar_position: 3 -sidebar_label: Build apps ---- - -## Introduction - -Apps built with the Stacks blockchain give users control over their digital identities, assets, and data. - -Unlike most cloud-based apps, they are "decentralized" since they don't depend on any centralized platform, server, or database to function. Rather, they use the Stacks blockchain to authenticate users and facilitate read and write requests for them without any single point of failure or trust. Rather, they use the Stacks blockchain to authenticate users and facilitate read and write requests for them without any single point of failure or trust. Rather, they use the Stacks blockchain to authenticate users and facilitate read and write requests for them without any single point of failure or trust. Rather, they use the Stacks blockchain to authenticate users and facilitate read and write requests for them without any single point of failure or trust. - -Stacks provides three main functions for building apps: - - - -- **Authentication**: Register and sign users in with identities on the Stacks blockchain -- **Transaction signing**: Prompt users to sign and broadcast transactions to the Stacks blockchain -- **Data storage**: Save and retrieve data for users with [Gaia](../gaia) - - -All three of these integrations can be used together to create powerful new user experiences that rival or exceed those of traditional apps—all while protecting your users' digital rights. - -While integration is possible for any type of app, most of the resources available here are for web developers experienced with JavaScript. See [Hiro developer docs](https://docs.hiro.so) for more information on the available app development libraries for Stacks. See [Hiro developer docs](https://docs.hiro.so) for more information on the available app development libraries for Stacks. See [Hiro developer docs](https://docs.hiro.so) for more information on the available app development libraries for Stacks. See [Hiro developer docs](https://docs.hiro.so) for more information on the available app development libraries for Stacks. - -## [References](references) - -[Authentication](references/authentication) - -[BNS](references/bns) - -[Gaia](../gaia/) - diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md b/i18n/zh/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md deleted file mode 100644 index ad97a935ba..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/build-apps/nocodeclarity.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: NoCodeClarity -description: Launch apps for the Stacks blockchain through no code platforms like Bubble. ---- - -## Introduction - -![](https://d1muf25xaso8hp.cloudfront.net/https%3A%2F%2Fs3.amazonaws.com%2Fappforest_uf%2Ff1653407713550x759333524803365600%2FLogo%2520of%2520NoCodeClarity.png?w=179&h=84&auto=compress&dpr=1&fit=max) - -[NoCodeClarity](https://nocodeclarity.com) allows people to create applications for the Stacks blockchain without coding. - -## Stacks Plug-In on bubble - -The [Stacks-No-Code-Plugin](https://bubble.io/plugin/the-stacks-plug-in-1645467277638x949839693014368300) released in May 2022 and it can easily be installed on Bubble with a few clicks allowing users to deploy applications with no coding knowledge. [Bubble](https://bubble.io/blog/explaining-bubble-to-investors/) is the first No Code platform that the Stacks plugin launched on. More platforms are in the roadmap of NoCodeClarity, founded by Christopher Perceptions and Sergio Gongora. The Stacks plugin was created through the support of the Stacks Foundation via a grant in January 2022 and NoCodeClarity was awarded a $100,000 grant in June 2022 to expand the roadmap. [Bubble](https://bubble.io/blog/explaining-bubble-to-investors/) is the first No Code platform that the Stacks plugin launched on. More platforms are in the roadmap of NoCodeClarity, founded by Christopher Perceptions and Sergio Gongora. The Stacks plugin was created through the support of the Stacks Foundation via a grant in January 2022 and NoCodeClarity was awarded a $100,000 grant in June 2022 to expand the roadmap. - -Additional [instructions](https://s3.amazonaws.com/appforest_uf/f1654202471526x991633667675927800/Instructions%20v2.docx.pdf) are also available. Tutorials and step by step guides will be released soon. Tutorials and step by step guides will be released soon. Tutorials and step by step guides will be released soon. - -The Stacks-No-Code-Plugin code is [publicly available on Github](https://github.com/nocodeclarity/Stacks-No-Code-Plugin). - -![](/img/bubble-stacks-plugin.png) - -## Demo page - -A demo page is available [here](https://test-stacks-plugin.bubbleapps.io/version-test). - -## NoCodeClarity videos - -NodeCodeClarity has their own [youtube channel](https://www.youtube.com/channel/UC9Ep0VQ-GQ-yDzt-wmIElRA). - -Videos: - -* [NoCodeClarity Setup](https://www.youtube.com/watch?v=WanXlpBGl0w) -* [NoCodeClarity - Part 1 of the plugin](https://www.youtube.com/watch?v=o6d3hrzNqVI&t=248s) -* [NoCodeClarity - Part 2 of the plugin](https://www.youtube.com/watch?v=0rzMdsrRg80) -* [Sneak Peek of the No Code Stacks Wallet Template](https://www.youtube.com/watch?v=Xe6Yv0rF6XM) \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md b/i18n/zh/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md deleted file mode 100644 index 65f282bf62..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/build-apps/references/authentication.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Authentication -description: Register and sign in users with identities on the Stacks blockchain ---- - -## Introduction - -This guide explains how authentication is performed on the Stacks blockchain. - -Authentication provides a way for users to identify themselves to an app while retaining complete control over their credentials and personal details. Authentication provides a way for users to identify themselves to an app while retaining complete control over their credentials and personal details. It can be integrated alone or used in conjunction with [transaction signing](https://docs.hiro.so/get-started/transactions#signature-and-verification) and [data storage](https://docs.stacks.co/build-apps/references/gaia), for which it is a prerequisite. - -Users who register for your app can subsequently authenticate to any other app with support for the [Blockchain Naming System](bns) and vice versa. - -## How it works - -The authentication flow with Stacks is similar to the typical client-server flow used by centralized sign in services (for example, OAuth). However, with Stacks the authentication flow happens entirely client-side. However, with Stacks the authentication flow happens entirely client-side. However, with Stacks the authentication flow happens entirely client-side. However, with Stacks the authentication flow happens entirely client-side. - -An app and authenticator, such as [the Stacks Wallet](https://www.hiro.so/wallet/install-web), communicate during the authentication flow by passing back and forth two tokens. The requesting app sends the authenticator an `authRequest` token. Once a user approves authentication, the authenticator responds to the app with an `authResponse` token. The requesting app sends the authenticator an `authRequest` token. Once a user approves authentication, the authenticator responds to the app with an `authResponse` token. The requesting app sends the authenticator an `authRequest` token. Once a user approves authentication, the authenticator responds to the app with an `authResponse` token. The requesting app sends the authenticator an `authRequest` token. Once a user approves authentication, the authenticator responds to the app with an `authResponse` token. - -These tokens are are based on [a JSON Web Token (JWT) standard](https://tools.ietf.org/html/rfc7519) with additional support for the `secp256k1` curve used by Bitcoin and many other cryptocurrencies. They are passed via URL query strings. They are passed via URL query strings. They are passed via URL query strings. They are passed via URL query strings. - -When a user chooses to authenticate an app, it sends the `authRequest` token to the authenticator via a URL query string with an equally named parameter: - -`https://wallet.hiro.so/...?authRequest=j902120cn829n1jnvoa...` - -When the authenticator receives the request, it generates an `authResponse` token for the app using an _ephemeral transit key_ . The ephemeral transit key is just used for the particular instance of the app, in this case, to sign the `authRequest`. The ephemeral transit key is just used for the particular instance of the app, in this case, to sign the `authRequest`. The ephemeral transit key is just used for the particular instance of the app, in this case, to sign the `authRequest`. The ephemeral transit key is just used for the particular instance of the app, in this case, to sign the `authRequest`. - -The app stores the ephemeral transit key during request generation. The public portion of the transit key is passed in the `authRequest` token. The app stores the ephemeral transit key during request generation. The public portion of the transit key is passed in the `authRequest` token. The authenticator uses the public portion of the key to encrypt an _app private key_ which is returned via the `authResponse`. The public portion of the transit key is passed in the `authRequest` token. The app stores the ephemeral transit key during request generation. The public portion of the transit key is passed in the `authRequest` token. The authenticator uses the public portion of the key to encrypt an _app private key_ which is returned via the `authResponse`. - -The authenticator generates the app private key from the user's _identity address private key_ and the app's domain. The app private key serves three functions: The app private key serves three functions: The app private key serves three functions: The app private key serves three functions: - -1. It is used to create credentials that give the app access to a storage bucket in the user's Gaia hub -2. It is used in the end-to-end encryption of files stored for the app in the user's Gaia storage. -3. It serves as a cryptographic secret that apps can use to perform other cryptographic functions. - -Finally, the app private key is deterministic, meaning that the same private key will always be generated for a given Stacks address and domain. - -The first two of these functions are particularly relevant to [data storage with Stacks.js](https://docs.stacks.co/docs/gaia). - -## Key pairs - -Authentication with Stacks makes extensive use of public key cryptography generally and ECDSA with the `secp256k1` curve in particular. - -The following sections describe the three public-private key pairs used, including how they're generated, where they're used and to whom private keys are disclosed. - -### Transit private key - -The transit private is an ephemeral key that is used to encrypt secrets that need to be passed from the authenticator to the app during the authentication process. It is randomly generated by the app at the beginning of the authentication response. It is randomly generated by the app at the beginning of the authentication response. It is randomly generated by the app at the beginning of the authentication response. It is randomly generated by the app at the beginning of the authentication response. - -The public key that corresponds to the transit private key is stored in a single element array in the `public_keys` key of the authentication request token. The authenticator encrypts secret data such as the app private key using this public key and sends it back to the app when the user signs in to the app. The transit private key signs the app authentication request. The authenticator encrypts secret data such as the app private key using this public key and sends it back to the app when the user signs in to the app. The transit private key signs the app authentication request. The authenticator encrypts secret data such as the app private key using this public key and sends it back to the app when the user signs in to the app. The transit private key signs the app authentication request. The authenticator encrypts secret data such as the app private key using this public key and sends it back to the app when the user signs in to the app. The transit private key signs the app authentication request. - -### Identity address private key - -The identity address private key is derived from the user's keychain phrase and is the private key of the Stacks username that the user chooses to use to sign in to the app. It is a secret owned by the user and never leaves the user's instance of the authenticator. It is a secret owned by the user and never leaves the user's instance of the authenticator. It is a secret owned by the user and never leaves the user's instance of the authenticator. It is a secret owned by the user and never leaves the user's instance of the authenticator. - -This private key signs the authentication response token for an app to indicate that the user approves sign in to that app. - -### App private key - -The app private key is an app-specific private key that is generated from the user's identity address private key using the `domain_name` as input. - -The app private key is securely shared with the app on each authentication, encrypted by the authenticator with the transit public key. Because the transit key is only stored on the client side, this prevents a man-in-the-middle attack where a server or internet provider could potentially snoop on the app private key. Because the transit key is only stored on the client side, this prevents a man-in-the-middle attack where a server or internet provider could potentially snoop on the app private key. Because the transit key is only stored on the client side, this prevents a man-in-the-middle attack where a server or internet provider could potentially snoop on the app private key. Because the transit key is only stored on the client side, this prevents a man-in-the-middle attack where a server or internet provider could potentially snoop on the app private key. diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/build-apps/references/bns.md b/i18n/zh/docusaurus-plugin-content-docs/current/build-apps/references/bns.md deleted file mode 100644 index 697e3e910d..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/build-apps/references/bns.md +++ /dev/null @@ -1,275 +0,0 @@ ---- -title: Blockchain Naming System -description: Binds Stacks usernames to off-chain state ---- - -Blockchain Naming System (BNS) is a network system that binds Stacks usernames to off-chain state without relying on any central points of control. - -The Stacks V1 blockchain implemented BNS through first-order name operations. In Stacks V2, BNS is instead implemented through a smart-contract loaded during the genesis block. In Stacks V2, BNS is instead implemented through a smart-contract loaded during the genesis block. In Stacks V2, BNS is instead implemented through a smart-contract loaded during the genesis block. In Stacks V2, BNS is instead implemented through a smart-contract loaded during the genesis block. - -Names in BNS have three properties: - -- **Names are globally unique.** The protocol does not allow name collisions, and all well-behaved nodes resolve a given name to the same state. -- **Names are human-meaningful.** Each name is chosen by its creator. -- **Names are strongly owned.** Only the name's owner can change the state it resolves to. Specifically, a name is owned by one or more ECDSA private keys. Specifically, a name is owned by one or more ECDSA private keys. Specifically, a name is owned by one or more ECDSA private keys. Specifically, a name is owned by one or more ECDSA private keys. - -The Stacks blockchain insures that each node's BNS view is synchronized to all of the other nodes in the world, so queries on one node will be the same on other nodes. Stacks blockchain nodes allow a name's owner to bind up to 40Kb of off-chain state to their name, which will be replicated to all other Stacks blockchain nodes via a P2P network. The Stacks blockchain insures that each node's BNS view is synchronized to all of the other nodes in the world, so queries on one node will be the same on other nodes. Stacks blockchain nodes allow a name's owner to bind up to 40Kb of off-chain state to their name, which will be replicated to all other Stacks blockchain nodes via a P2P network. The Stacks blockchain insures that each node's BNS view is synchronized to all of the other nodes in the world, so queries on one node will be the same on other nodes. Stacks blockchain nodes allow a name's owner to bind up to 40Kb of off-chain state to their name, which will be replicated to all other Stacks blockchain nodes via a P2P network. Stacks blockchain nodes allow a name's owner to bind up to 40Kb of off-chain state to their name, which will be replicated to all other Stacks blockchain nodes via a P2P network. - -The biggest consequence for developers is that in BNS, reading name state is fast and cheap but writing name state is slow and expensive. This is because registering and modifying names requires one or more transactions to be sent to the underlying blockchain, and BNS nodes will not process them until they are sufficiently confirmed. Users and developers need to acquire and spend the requisite cryptocurrency (STX) to send BNS transactions. This is because registering and modifying names requires one or more transactions to be sent to the underlying blockchain, and BNS nodes will not process them until they are sufficiently confirmed. Users and developers need to acquire and spend the requisite cryptocurrency (STX) to send BNS transactions. This is because registering and modifying names requires one or more transactions to be sent to the underlying blockchain, and BNS nodes will not process them until they are sufficiently confirmed. Users and developers need to acquire and spend the requisite cryptocurrency (STX) to send BNS transactions. - -## Motivation behind naming systems - -We rely on naming systems in everyday life, and they play a critical role in many different applications. For example, when you look up a friend on social media, you are using the platform's naming system to resolve their name to their profile. When you look up a website, you are using the Domain Name Service to resolve the hostname to its host's IP address. We rely on naming systems in everyday life, and they play a critical role in many different applications. For example, when you look up a friend on social media, you are using the platform's naming system to resolve their name to their profile. When you look up a website, you are using the Domain Name Service to resolve the hostname to its host's IP address. When you check out a Git branch, you are using your Git client to resolve the branch name to a commit hash. When you look up someone's PGP key on a keyserver, you are resolving their key ID to their public key. When you look up someone's PGP key on a keyserver, you are resolving their key ID to their public key. - -What kinds of things do we want to be true about names? In BNS, names are globally unique, names are human-meaningful, and names are strongly owned. However, if you look at these examples, you'll see that each of them only guarantees _two_ of these properties. This limits how useful they can be. What kinds of things do we want to be true about names? In BNS, names are globally unique, names are human-meaningful, and names are strongly owned. However, if you look at these examples, you'll see that each of them only guarantees _two_ of these properties. This limits how useful they can be. In BNS, names are globally unique, names are human-meaningful, and names are strongly owned. However, if you look at these examples, you'll see that each of them only guarantees _two_ of these properties. This limits how useful they can be. However, if you look at these examples, you'll see that each of them only guarantees _two_ of these properties. This limits how useful they can be. - -- In DNS and social media, names are globally unique and human-readable, but not strongly owned. The system operator has the final say as to what each names resolves to. The system operator has the final say as to what each names resolves to. The system operator has the final say as to what each names resolves to. The system operator has the final say as to what each names resolves to. - - - **Problem**: Clients must trust the system to make the right choice in what a given name resolves to. This includes trusting that no one but the system administrators can make these changes. This includes trusting that no one but the system administrators can make these changes. This includes trusting that no one but the system administrators can make these changes. This includes trusting that no one but the system administrators can make these changes. - -- In Git, branch names are human-meaningful and strongly owned, but not globally unique. In Git, branch names are human-meaningful and strongly owned, but not globally unique. Two different Git nodes may resolve the same branch name to different unrelated repository states. In Git, branch names are human-meaningful and strongly owned, but not globally unique. Two different Git nodes may resolve the same branch name to different unrelated repository states. In Git, branch names are human-meaningful and strongly owned, but not globally unique. Two different Git nodes may resolve the same branch name to different unrelated repository states. - - - **Problem**: Since names can refer to conflicting state, developers have to figure out some other mechanism to resolve ambiguities. In Git's case, the user has to manually intervene. In Git's case, the user has to manually intervene. In Git's case, the user has to manually intervene. In Git's case, the user has to manually intervene. - -- In PGP, names are key IDs. They are are globally unique and cryptographically owned, but not human-readable. PGP key IDs are derived from the keys they reference. They are are globally unique and cryptographically owned, but not human-readable. PGP key IDs are derived from the keys they reference. They are are globally unique and cryptographically owned, but not human-readable. PGP key IDs are derived from the keys they reference. They are are globally unique and cryptographically owned, but not human-readable. PGP key IDs are derived from the keys they reference. - - **Problem**: These names are difficult for most users to remember since they do not carry semantic information relating to their use in the system. - -BNS names have all three properties, and none of these problems. This makes it a powerful tool for building all kinds of network applications. With BNS, we can do the following and more: This makes it a powerful tool for building all kinds of network applications. With BNS, we can do the following and more: This makes it a powerful tool for building all kinds of network applications. With BNS, we can do the following and more: This makes it a powerful tool for building all kinds of network applications. With BNS, we can do the following and more: - -- Build domain name services where hostnames can't be hijacked. -- Build social media platforms where user names can't be stolen by phishers. -- Build version control systems where repository branches do not conflict. -- Build public-key infrastructure where it's easy for users to discover and remember each other's keys. - -## Organization of BNS - -BNS names are organized into a global name hierarchy. There are three different layers in this hierarchy related to naming: There are three different layers in this hierarchy related to naming: There are three different layers in this hierarchy related to naming: There are three different layers in this hierarchy related to naming: - -- **Namespaces**. These are the top-level names in the hierarchy. An analogy to BNS namespaces are DNS top-level domains. Existing BNS namespaces include `.id`, `.podcast`, and `.helloworld`. All other names belong to exactly one namespace. Anyone can create a namespace, but in order for the namespace to be persisted, it must be _launched_ so that anyone can register names in it. Namespaces are not owned by their creators. These are the top-level names in the hierarchy. An analogy to BNS namespaces are DNS top-level domains. Existing BNS namespaces include `.id`, `.podcast`, and `.helloworld`. All other names belong to exactly one namespace. Anyone can create a namespace, but in order for the namespace to be persisted, it must be _launched_ so that anyone can register names in it. Namespaces are not owned by their creators. - -- **BNS names**. These are names whose records are stored directly on the blockchain. The ownership and state of these names are controlled by sending blockchain transactions. Example names include `verified.podcast` and `muneeb.id`. Anyone can create a BNS name, as long as the namespace that contains it exists already. These are names whose records are stored directly on the blockchain. The ownership and state of these names are controlled by sending blockchain transactions. Example names include `verified.podcast` and `muneeb.id`. Anyone can create a BNS name, as long as the namespace that contains it exists already. - -- **BNS subdomains**. These are names whose records are stored off-chain, but are collectively anchored to the blockchain. The ownership and state for these names lives within the P2P network data. While BNS subdomains are owned by separate private keys, a BNS name owner must broadcast their subdomain state. Example subdomains include `jude.personal.id` and `podsaveamerica.verified.podcast`. Unlike BNS namespaces and names, the state of BNS subdomains is _not_ part of the blockchain consensus rules. - -A feature comparison matrix summarizing the similarities and differences between these name objects is presented below: - -| Feature | **Namespaces** | **BNS names** | **BNS Subdomains** | -| -------------------------------------- | -------------- | ------------- | ------------------ | -| Globally unique | X | X | X | -| Human-meaningful | X | X | X | -| Owned by a private key | | X | X | -| Anyone can create | X | X | [1] | -| Owner can update | | X | [1] | -| State hosted on-chain | X | X | | -| State hosted off-chain | | X | X | -| Behavior controlled by consensus rules | X | X | | -| May have an expiration date | | X | | - -[1] Requires the cooperation of a BNS name owner to broadcast its transactions - -## Namespaces - -Namespaces are the top-level naming objects in BNS. - -They control a few properties about the names within them: - -- How expensive they are to register -- How long they last before they have to be renewed -- Who (if anyone) receives the name registration fees -- Who is allowed to seed the namespace with its initial names. - -At the time of this writing, by far the largest BNS namespace is the `.id` namespace. Names in the `.id` namespace are meant for resolving user identities. Short names in `.id` are more expensive than long names, and have to be renewed by their owners every two years. Name registration fees are not paid to anyone in particular---they are instead sent to a "black hole" where they are rendered unspendable (the intention is to discourage ID squatters). Names in the `.id` namespace are meant for resolving user identities. Short names in `.id` are more expensive than long names, and have to be renewed by their owners every two years. Name registration fees are not paid to anyone in particular---they are instead sent to a "black hole" where they are rendered unspendable (the intention is to discourage ID squatters). Names in the `.id` namespace are meant for resolving user identities. Short names in `.id` are more expensive than long names, and have to be renewed by their owners every two years. Name registration fees are not paid to anyone in particular---they are instead sent to a "black hole" where they are rendered unspendable (the intention is to discourage ID squatters). - -Unlike DNS, _anyone_ can create a namespace and set its properties. Namespaces are created on a first-come first-serve basis, and once created, they last forever. Namespaces are created on a first-come first-serve basis, and once created, they last forever. Namespaces are created on a first-come first-serve basis, and once created, they last forever. Namespaces are created on a first-come first-serve basis, and once created, they last forever. - -However, creating a namespace is not free. 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 (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`). The shorter the namespace, the more cryptocurrency 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`). - -Namespaces can be between 1 and 19 characters long, and are composed of the characters `a-z`, `0-9`, `-`, and `_`. - -## Subdomains - -BNS names are strongly owned because the owner of its private key can generate valid transactions that update its zone file hash and owner. However, this comes at the cost of requiring a name owner to pay for the underlying transaction in the blockchain. Moreover, this approach limits the rate of BNS name registrations and operations to the underlying blockchain's transaction bandwidth. However, this comes at the cost of requiring a name owner to pay for the underlying transaction in the blockchain. Moreover, this approach limits the rate of BNS name registrations and operations to the underlying blockchain's transaction bandwidth. However, this comes at the cost of requiring a name owner to pay for the underlying transaction in the blockchain. Moreover, this approach limits the rate of BNS name registrations and operations to the underlying blockchain's transaction bandwidth. However, this comes at the cost of requiring a name owner to pay for the underlying transaction in the blockchain. Moreover, this approach limits the rate of BNS name registrations and operations to the underlying blockchain's transaction bandwidth. - -BNS overcomes this with subdomains. A **BNS subdomain** is a type of BNS name whose state and owner are stored outside of the blockchain, but whose existence and operation history are anchored to the blockchain. Like their on-chain counterparts, subdomains are globally unique, strongly owned, and human-readable. BNS gives them their own name state and public keys. Unlike on-chain names, subdomains can be created and managed cheaply, because they are broadcast to the BNS network in batches. A single blockchain transaction can send up to 120 subdomain operations. **BNS subdomains**. These are names whose records are stored off-chain, but are collectively anchored to the blockchain. The ownership and state for these names lives within the P2P network data. While BNS subdomains are owned by separate private keys, a BNS name owner must broadcast their subdomain state. Example subdomains include `jude.personal.id` and `podsaveamerica.verified.podcast`. Unlike BNS namespaces and names, the state of BNS subdomains is _not_ part of the blockchain consensus rules. Like their on-chain counterparts, subdomains are globally unique, strongly owned, and human-readable. BNS gives them their own name state and public keys. Unlike on-chain names, subdomains can be created and managed cheaply, because they are broadcast to the BNS network in batches. A single blockchain transaction can send up to 120 subdomain operations. - -This is achieved by storing subdomain records in the BNS name zone files. An on-chain name owner broadcasts subdomain operations by encoding them as `TXT` records within a DNS zone file. To broadcast the zone file, the name owner sets the new zone file hash with a `NAME_UPDATE` transaction and replicates the zone file. This, in turn, replicates all subdomain operations it contains, and anchors the set of subdomain operations to an on-chain transaction. The BNS node's consensus rules ensure that only valid subdomain operations from _valid_ `NAME_UPDATE` transactions will ever be stored. An on-chain name owner broadcasts subdomain operations by encoding them as `TXT` records within a DNS zone file. To broadcast the zone file, the name owner sets the new zone file hash with a `NAME_UPDATE` transaction and replicates the zone file. This, in turn, replicates all subdomain operations it contains, and anchors the set of subdomain operations to an on-chain transaction. The BNS node's consensus rules ensure that only valid subdomain operations from _valid_ `NAME_UPDATE` transactions will ever be stored. - -For example, the name `verified.podcast` once wrote the zone file hash `247121450ca0e9af45e85a82e61cd525cd7ba023`, which is the hash of the following zone file: - -```bash -$TTL 3600 -1yeardaily TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxeWVhcmRhaWx5CiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMXllYXJkYWlseS9oZWFkLmpzb24iCg==" -2dopequeens TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAyZG9wZXF1ZWVucwokVFRMIDM2MDAKX2h0dHAuX3RjcCBVUkkgMTAgMSAiaHR0cHM6Ly9waC5kb3Rwb2RjYXN0LmNvLzJkb3BlcXVlZW5zL2hlYWQuanNvbiIK" -10happier TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxMGhhcHBpZXIKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8xMGhhcHBpZXIvaGVhZC5qc29uIgo=" -31thoughts TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzMXRob3VnaHRzCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzF0aG91Z2h0cy9oZWFkLmpzb24iCg==" -359 TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzNTkKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8zNTkvaGVhZC5qc29uIgo=" -30for30 TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzMGZvcjMwCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzBmb3IzMC9oZWFkLmpzb24iCg==" -onea TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiBvbmVhCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vb25lYS9oZWFkLmpzb24iCg==" -10minuteteacher TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAxMG1pbnV0ZXRlYWNoZXIKJFRUTCAzNjAwCl9odHRwLl90Y3AgVVJJIDEwIDEgImh0dHBzOi8vcGguZG90cG9kY2FzdC5jby8xMG1pbnV0ZXRlYWNoZXIvaGVhZC5qc29uIgo=" -36questionsthepodcastmusical TXT "owner=1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH" "seqn=0" "parts=1" "zf0=JE9SSUdJTiAzNnF1ZXN0aW9uc3RoZXBvZGNhc3RtdXNpY2FsCiRUVEwgMzYwMApfaHR0cC5fdGNwIFVSSSAxMCAxICJodHRwczovL3BoLmRvdHBvZGNhc3QuY28vMzZxdWVzdGlvbnN0aGVwb2RjYXN0bXVzaWNhbC9oZWFkLmpzb24iCg==" -_http._tcp URI 10 1 "https://dotpodcast.co/" -``` - -Each `TXT` record in this zone file encodes a subdomain-creation. For example, `1yeardaily.verified.podcast` resolves to: For example, `1yeardaily.verified.podcast` resolves to: For example, `1yeardaily.verified.podcast` resolves to: For example, `1yeardaily.verified.podcast` resolves to: - -```json -{ - "address": "1MwPD6dH4fE3gQ9mCov81L1DEQWT7E85qH", - "blockchain": "bitcoin", - "last_txid": "d87a22ebab3455b7399bfef8a41791935f94bc97aee55967edd5a87f22cce339", - "status": "registered_subdomain", - "zonefile_hash": "e7acc97fd42c48ed94fd4d41f674eddbee5557e3", - "zonefile_txt": "$ORIGIN 1yeardaily\n$TTL 3600\n_http._tcp URI 10 1 \"https://ph.dotpodcast.co/1yeardaily/head.json\"\n" -} -``` - -This information was extracted from the `1yeardaily` `TXT` resource record in the zone file for `verified.podcast`. - -### Subdomain Lifecycle - -Note that `1yeardaily.verified.podcast` has a different public key hash (address) than `verified.podcast`. A BNS node will only process a subsequent subdomain operation on `1yeardaily.verified.podcast` if it includes a signature from this address's private key. `verified.podcast` cannot generate updates; only the owner of `1yeardaily.verified.podcast can do so`. A BNS node will only process a subsequent subdomain operation on `1yeardaily.verified.podcast` if it includes a signature from this address's private key. Note that `1yeardaily.verified.podcast` has a different public key hash (address) than `verified.podcast`. A BNS node will only process a subsequent subdomain operation on `1yeardaily.verified.podcast` if it includes a signature from this address's private key. `verified.podcast` cannot generate updates; only the owner of `1yeardaily.verified.podcast can do so`. A BNS node will only process a subsequent subdomain operation on `1yeardaily.verified.podcast` if it includes a signature from this address's private key. Note that `1yeardaily.verified.podcast` has a different public key hash (address) than `verified.podcast`. A BNS node will only process a subsequent subdomain operation on `1yeardaily.verified.podcast` if it includes a signature from this address's private key. `verified.podcast` cannot generate updates; only the owner of `1yeardaily.verified.podcast can do so`. A BNS node will only process a subsequent subdomain operation on `1yeardaily.verified.podcast` if it includes a signature from this address's private key. `verified.podcast` cannot generate updates; only the owner of `1yeardaily.verified.podcast can do so`. - -The lifecycle of a subdomain and its operations is shown in Figure 2. - -``` - subdomain subdomain subdomain - creation update transfer -+----------------+ +----------------+ +----------------+ -| cicero | | cicero | | cicero | -| owner="1Et..." | signed | owner="1Et..." | signed | owner="1cJ..." | -| zf0="7e4..." |<--------| zf0="111..." |<--------| zf0="111..." |<---- ... -| seqn=0 | | seqn=1 | | seqn=2 | -| | | sig="xxxx" | | sig="xxxx" | -+----------------+ +----------------+ +----------------+ - | | | - | off-chain | | -~ ~ ~ ~ | ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~|~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ | ~ ~ ~ ~ ~ ~ ~ ... - | on-chain | | - V V (zone file hash ) V -+----------------+ +----------------+ +----------------+ -| res_publica.id | | jude.id | | res_publica.id | -| NAME_UPDATE |<--------| NAME_UPDATE |<--------| NAME_UPDATE |<---- ... -+----------------+ +----------------+ +----------------+ - blockchain blockchain blockchain - block block block - - -Figure 2: Subdomain lifetime with respect to on-chain name operations .A new -subdomain operation will only be accepted if it has a later "sequence=" number, -and a valid signature in "sig=" over the transaction body .The "sig=" field -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." -However, any on-chain name ("jude.id" in this case) can broadcast a subdomain -update for "cicero.res_publica.id." | signed | owner="1Et..." | signed | owner="1cJ..." | -| zf0="7e4..." |<--------| zf0="111..." |<--------| zf0="111..." |<---- ... -| seqn=0 | | seqn=1 | | seqn=2 | -| | | sig="xxxx" | | sig="xxxx" | -+----------------+ +----------------+ +----------------+ - | | | - | off-chain | | -~ ~ ~ ~ | ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~|~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ ~ | ~ ~ ~ ~ ~ ~ ~ ... - | on-chain | | - V V (zone file hash ) V -+----------------+ +----------------+ +----------------+ -| res_publica.id | | jude.id | | res_publica.id | -| NAME_UPDATE |<--------| NAME_UPDATE |<--------| NAME_UPDATE |<---- ... -+----------------+ +----------------+ +----------------+ - blockchain blockchain blockchain - block block block - - -Figure 2: Subdomain lifetime with respect to on-chain name operations .A new -subdomain operation will only be accepted if it has a later "sequence=" number, -and a valid signature in "sig=" over the transaction body .The "sig=" field -includes both the public key and signature, and the public key must hash to -the previous subdomain operation's "addr=" field. - -A subdomain-transfer transaction can only be broadcast by the owner of the on-chain name that created it. A subdomain-transfer transaction can only be broadcast by the owner of the on-chain name that created it. For example, the owner of cicero.res_publica.id needs the owner of res_publica.id to broadcast a subdomain-transfer transaction to change cicero.res_publica.id's public key. -needs the owner of res_publica.id to broadcast a subdomain-transfer transaction to change cicero.res_publica.id's public key. -However, any on-chain name ("jude.id" in this case) can broadcast a subdomain -update for "cicero.res_publica.id." - -``` - needs the owner of res_publica.id to broadcast a subdomain-transfer transaction to change cicero.res_publica.id's public key. -needs the owner of res_publica.id to broadcast a subdomain-transfer transaction to change cicero.res_publica.id's public key. -However, any on-chain name ("jude.id" in this case) can broadcast a subdomain -update for "cicero.res_publica.id." - - - -Subdomain operations are ordered by sequence number, starting at 0. Each new subdomain operation must include: Subdomain operations are ordered by sequence number, starting at 0. Each new subdomain operation must include: Subdomain operations are ordered by sequence number, starting at 0. Each new subdomain operation must include: Each new subdomain operation must include: - -- The next sequence number -- The public key that hashes to the previous subdomain transaction's address -- A signature from the corresponding private key over the entire subdomain operation. - -If two correctly signed but conflicting subdomain operations are discovered (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. Invalid subdomain operations are ignored. Invalid subdomain operations are ignored. - -If two correctly signed but conflicting subdomain operations are discovered (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. Invalid subdomain operations are ignored. Invalid subdomain operations are ignored. - -### Subdomain Creation and Management - -That said, to create a subdomain, the subdomain owner generates a subdomain-creation operation for their desired name and gives it to the on-chain name owner. In particular: - -- A subdomain-creation transaction can only be processed by the owner of the on-chain name that shares its suffix. A subdomain-creation transaction can only be processed by the owner of the on-chain name that shares its suffix. For example, only the owner of `res_publica.id` can broadcast subdomain-creation transactions for subdomain names ending in `.res_publica.id`. A subdomain-creation transaction can only be processed by the owner of the on-chain name that shares its suffix. For example, only the owner of `res_publica.id` can broadcast subdomain-creation transactions for subdomain names ending in `.res_publica.id`. A subdomain-creation transaction can only be processed by the owner of the on-chain name that shares its suffix. For example, only the owner of `res_publica.id` can broadcast subdomain-creation transactions for subdomain names ending in `.res_publica.id`. -- A subdomain-transfer transaction can only be broadcast by the owner of the on-chain name that created it. A subdomain-transfer transaction can only be broadcast by the owner of the on-chain name that created it. For example, the owner of `cicero.res_publica.id` needs the owner of `res_publica.id` to broadcast a subdomain-transfer transaction to change `cicero.res_publica.id`'s public key. A subdomain-transfer transaction can only be broadcast by the owner of the on-chain name that created it. For example, the owner of `cicero.res_publica.id` needs the owner of `res_publica.id` to broadcast a subdomain-transfer transaction to change `cicero.res_publica.id`'s public key. -- In order to send a subdomain-creation or subdomain-transfer, all of an on-chain name owner's zone files must be present in the Atlas network. In order to send a subdomain-creation or subdomain-transfer, all of an on-chain name owner's zone files must be present in the Atlas network. This lets the BNS node prove the _absence_ of any conflicting subdomain-creation and subdomain-transfer operations when processing new zone files. In order to send a subdomain-creation or subdomain-transfer, all of an on-chain name owner's zone files must be present in the Atlas network. This lets the BNS node prove the _absence_ of any conflicting subdomain-creation and subdomain-transfer operations when processing new zone files. In order to send a subdomain-creation or subdomain-transfer, all of an on-chain name owner's zone files must be present in the Atlas network. This lets the BNS node prove the _absence_ of any conflicting subdomain-creation and subdomain-transfer operations when processing new zone files. -- A subdomain update transaction can be broadcast by _any_ on-chain name owner, but the subdomain owner needs to find one who will cooperate. For example, the owner of `verified.podcast` can broadcast a subdomain-update transaction created by the owner of `cicero.res_publica.id`. For example, the owner of `verified.podcast` can broadcast a subdomain-update transaction created by the owner of `cicero.res_publica.id`. For example, the owner of `verified.podcast` can broadcast a subdomain-update transaction created by the owner of `cicero.res_publica.id`. For example, the owner of `verified.podcast` can broadcast a subdomain-update transaction created by the owner of `cicero.res_publica.id`. - -Unlike an on-chain name, a subdomain owner needs an on-chain name owner's help to broadcast their subdomain operations. In particular: In particular: In particular: - -Once created, a subdomain owner can use any on-chain name owner to broadcast a subdomain-update operation. To do so, they generate and sign the requisite subdomain operation and give it to an on-chain name owner, who then packages it with other subdomain operations into a DNS zone file and broadcasts it to the network. To do so, they generate and sign the requisite subdomain operation and give it to an on-chain name owner, who then packages it with other subdomain operations into a DNS zone file and broadcasts it to the network. To do so, they generate and sign the requisite subdomain operation and give it to an on-chain name owner, who then packages it with other subdomain operations into a DNS zone file and broadcasts it to the network. - -If the subdomain owner wants to change the address of their subdomain, they need to sign a subdomain-transfer operation and give it to the on-chain name owner who created the subdomain. They then package it into a zone file and broadcast it. They then package it into a zone file and broadcast it. They then package it into a zone file and broadcast it. They then package it into a zone file and broadcast it. - -### Subdomain Registrars - -Because subdomain names are cheap, developers may be inclined to run subdomain registrars on behalf of their applications. For example, the name `personal.id` is used to register usernames without requiring them to spend any Bitcoin. For example, the name `personal.id` is used to register usernames without requiring them to spend any Bitcoin. For example, the name `personal.id` is used to register usernames without requiring them to spend any Bitcoin. For example, the name `personal.id` is used to register usernames without requiring them to spend any Bitcoin. - -We supply a reference implementation of a [BNS Subdomain Registrar](https://github.com/stacks-network/subdomain-registrar) to help developers broadcast subdomain operations. Users would still own their subdomain names; the registrar simply gives developers a convenient way for them to register and manage them in the context of a particular application. Users would still own their subdomain names; the registrar simply gives developers a convenient way for them to register and manage them in the context of a particular application. Users would still own their subdomain names; the registrar simply gives developers a convenient way for them to register and manage them in the context of a particular application. - -# BNS and DID Standards - -We supply a reference implementation of a [BNS Subdomain Registrar](https://github.com/stacks-network/subdomain-registrar) to help developers broadcast subdomain operations. Users would still own their subdomain names; the registrar simply gives developers a convenient way for them to register and manage them in the context of a particular application. Users would still own their subdomain names; the registrar simply gives developers a convenient way for them to register and manage them in the context of a particular application. Users would still own their subdomain names; the registrar simply gives developers a convenient way for them to register and manage them in the context of a particular application. - -Each name in BNS has an associated DID. The DID format for BNS is: Each name in BNS has an associated DID. The DID format for BNS is: The DID format for BNS is: Each name in BNS has an associated DID. The DID format for BNS is: The DID format for BNS is: - -```bash - did:stack:v0:{address}-{index} -``` - -Where: - -- `{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 `did:stack:v0:1dARRtzHPAFRNE7Yup2Md9w18XEQAtLiV-0`, because the name `personal.id` was the first-ever name created by `1dARRtzHPAFRNE7Yup2Md9w18XEQAtLiV`. - -As another example, the DID for `jude.id` is `did:stack:v0:16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg-1`. Here, the address `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` had created one earlier name in history prior to this one (which happens to be `abcdefgh123456.id`). - -The purpose of a DID is to provide an eternal identifier for a public key. The public key may change, but the DID will not. The purpose of a DID is to provide an eternal identifier for a public key. The public key may change, but the DID will not. The public key may change, but the DID will not. The purpose of a DID is to provide an eternal identifier for a public key. The public key may change, but the DID will not. The public key may change, but the DID will not. - -Stacks Blockchain implements a DID method of its own in order to be compatible with other systems that use DIDs for public key resolution. In order for a DID to be resolvable, all of the following must be true for a name: In order for a DID to be resolvable, all of the following must be true for a name: In order for a DID to be resolvable, all of the following must be true for a name: In order for a DID to be resolvable, all of the following must be true for a name: - -- The name must exist -- The name's zone file hash must be the hash of a well-formed DNS zone file -- The DNS zone file must be present in the Stacks node's data. -- The DNS zone file must contain a `URI` resource record that points to a signed JSON Web Token -- The public key that signed the JSON Web Token (and is included with it) must hash to the address that owns the name - -Not all names will have DIDs that resolve to public keys. However, names created by standard tooling will have DIDs that do. However, names created by standard tooling will have DIDs that do. However, names created by standard tooling will have DIDs that do. However, names created by standard tooling will have DIDs that do. - -A RESTful API is under development. - -## DID Encoding for Subdomains - -Every name and subdomain in BNS has a DID. Every name and subdomain in BNS has a DID. The encoding is slightly different for subdomains, so the software can determine which code-path to take. Every name and subdomain in BNS has a DID. The encoding is slightly different for subdomains, so the software can determine which code-path to take. Every name and subdomain in BNS has a DID. The encoding is slightly different 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 (that is, addresses starting with `1` or `3`, meaning `p2pkh` and `p2sh` addresses). Currently, both version byte 0 and version byte 5 addresses are supported (that is, addresses starting with `1` or `3`, meaning `p2pkh` and `p2sh` addresses). Currently, both version byte 0 and version byte 5 addresses are supported (that is, addresses starting with `1` or `3`, meaning `p2pkh` and `p2sh` addresses). Currently, both version byte 0 and version byte 5 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 subdomains owned by a single private key, and version byte 50 for subdomains owned by a m-of-n set of private keys. That is, subdomain DID addresses start with `S` or `M`, respectively. That is, subdomain DID addresses start with `S` or `M`, respectively. That is, subdomain DID addresses start with `S` or `M`, respectively. That is, subdomain DID addresses start with `S` or `M`, respectively. - -The `{index}` field for a subdomain's DID is distinct from the `{index}` field for a BNS name's DID, even if the same created both names and subdomains. As another example, the DID for `jude.id` is `did:stack:v0:16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg-1`. Here, the address `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` had created one earlier name in history prior to this one (which happens to be `abcdefgh123456.id`). However, `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` _also_ created `jude.statism.id` as its first subdomain name. The DID for `jude.statism.id` is `did:stack:v0:SSXMcDiCZ7yFSQSUj7mWzmDcdwYhq97p2i-0`. Note that the address `SSXMcDiCZ7yFSQSUj7mWzmDcdwYhq97p2i` encodes the same public key hash as the address `16EMaNw3pkn3v6f2BgnSSs53zAKH4Q8YJg` (the only difference between these two strings is that the first is base58check-encoded with version byte 0, and the second is encoded with version byte 63). diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/build-apps/references/references.md b/i18n/zh/docusaurus-plugin-content-docs/current/build-apps/references/references.md deleted file mode 100644 index babe5e119a..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/build-apps/references/references.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: References -sidebar_label: References ---- - -[Authentication](./authentication) - -[Blockchain Naming System](./bns) - -[Hiro example apps](https://docs.hiro.so/example-apps) \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/contribute/docs.md b/i18n/zh/docusaurus-plugin-content-docs/current/contribute/docs.md deleted file mode 100644 index 38c3e19d43..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/contribute/docs.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -title: Contribute to docs -description: Learn how this site is built, and how you can contribute to it. ---- - -## Introduction - -Welcome. Thank you for your interest in contributing and helping make these docs as good as they can be. - -This docs site is built on the open source platform [Discosaurus 2](https://docusaurus.io/) and most of its content is written in Markdown files. All of the code for this site is free and open source, located at the [GitHub repository here](https://github.com/stacks-network/docs). All of the code for this site is free and open source, located at the [GitHub repository here](https://github.com/stacks-network/docs). - -:::tip Don't know what Markdown is? Want to learn? :::tip Don't know what Markdown is? Want to learn? Here is a [helpful guide](https://guides.github.com/features/mastering-markdown/). - -Don't want to learn it? No need to. Don't want to learn it? No need to. Write [in plain text an issue on Github](https://github.com/stacks-network/docs/issues/new?assignees=&labels=documentation&template=add-documentation.md&title=%5BAdd+docs%5D) ::: - -:::info You need a free [Github](https://www.github.com) account to add or edit any content. ::: ::: - -To edit any page, just click on the *Edit this page* button at the bottom of each page and submit your changes online. - -To add new content, they are two different ways to do it, the [easy way](#easy-way) and the [advanced way](#advanced-way). - -## Easy way - -[**Simply click here and enter the text of the article you wish to add.**](https://github.com/stacks-network/docs/issues/new?assignees=&labels=documentation&template=add-documentation.md&title=%5BAdd+docs%5D) - -This will open up an issue on github using our template. -## Advanced way - -For more advanced changes you can follow the next steps. - -You can also test the site locally using this method. -### Steps - -1. Fork the [docs reposiroty](https://github.com/stacks-network/docs) by clicking on the *Fork* button in the upper right of the screen. -2. Clone your fork to your local machine with this command `git clone git@github.com:/docs.git stacks_docs` -3. Enter your project folder `cd stacks_docs` -4. Create a branch `git checkout -b feat/my-feature-branch`. -5. You can optionally preview your changes in real time with: - - `npm install` (to install dependencies). - - `npx docusaurus start` to start a local copy of the site. `npx docusaurus start` to start a local copy of the site. A web browser will open at http://localhost:3000, so you can see a preview of yourhanges in real time. -6. Make the changes you wish and then commit them with this kind of message: `git commit -am "feat: some new feature or content"`. -7. Push to to GitHub with `git push --set-upstream origin feature/my-feature-branch`. -8. Visit GitHub and make your pull request. - -## Aditional information -### Running and building the site locally (optional) - -You can start the page locally with the following command. This is enough to preview your changes. This is enough to preview your changes. -```bash -npx docusaurus start -``` - -Before running this command for the first time you will need to run `npm install` to install dependencies. - -The docs site will be accessible at this url: [`http://localhost:3000`](http://localhost:3000). - - -After you finished your changes, you can also build the entire site with the following command (not usually needed): -```bash -npm run build -``` - -:::tip `npx docusaurus start` will only load the default language (english). To test all languages you can build with `npm run build` and then preview your build with `npm run serve`. ::: - -### An alternative: Working in browser - -As an alterative to working locally, you can also use the web IDE gitpod that provides an environment to contribute directly from within your browser. - -You only need to have a github account and open [this link](https://gitpod.io/#https://github.com/stacks-network/docs). - -### Folder structure of the site - -If you are interested in only adding new documentation content to the site, the files that will be important to you are located within `./docs/*`: - -```bash -docs/ - build-apps - contribute/ - faq/ - gaia/ - nodes-and-miners/ - noteworthy-contracts/ - references/ - understand-stack/ - write-smart-contracts/ -``` - -The routing for this site is file based, meaning if you created a folder within `/docs/gaia/` named `testing` and in it a file named `test1.md`, you would be able to navigate to `http://localhost:3000/gaia/testing/test1` and you would see whatever content is in that markdown file. - -All the docs in English are stored in the folder `/docs/`. - -To add new English content simply add a markdown file (.md) into any subfolder in docs, and it will be automatically displayed in the category of that folder. - -All the docs in other languages are stored under the folder `i18n`, but these files should never be edited using GitHub as they are overwritten by Crowdin every time new translations are added. **To make changes in other languages**, you must do so using Crowdin. Please refer to [translations](translations) instead. **To make changes in other languages**, you must do so using Crowdin. Please refer to [translations](translations) instead. - -### Frontmatter - -Frontmatter is the top part of any markdown document that is written in a language called [YAML](https://yaml.org/). It looks like this: It looks like this: It looks like this: - -```yaml ---- -title: This is my page title -description: A short, concise sentence describing what is on this page ---- -``` - -Frontmatter gives us the ability to define some things within a page that the site can use, such as a page title or page description. When adding any new page, please include a `title` and `description`. When adding any new page, please include a `title` and `description`. When adding any new page, please include a `title` and `description`. - - - -### Use Conventional Commits - -We use the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) as and commits naming convention. Use it while contributing, please. Use it while contributing, please. Use it while contributing, please. - -### Code blocks - -To write a code block, you need to wrap your code in ` ```language `, and end your code block with ` ``` `. Here is an example of ` ```clarity `. Here is an example of ` ```clarity `. Here is an example of ` ```clarity `. - -```clarity -(define-data-var counter int 0) - -(define-public (get-counter) - (ok (var-get counter))) -``` -### Admonitions - -You can use the following admonitions to highlight content. - -```md -:::note -Some **content** with _markdown_ `syntax`. -:::note -Some **content** with _markdown_ `syntax`. -:::note -Some **content** with _markdown_ `syntax`. Check [this `api`](#). -::: - -:::tip -Some **content** with _markdown_ `syntax`. Check [this `api`](#). -::: - -:::info -Some **content** with _markdown_ `syntax`. Check [this `api`](#). -::: - -:::caution -Some **content** with _markdown_ `syntax`. Check [this `api`](#). -::: - -:::danger -Some **content** with _markdown_ `syntax`. Check [this `api`](#). -::: -::: - -:::info -Some **content** with _markdown_ `syntax`. -::: - -:::caution -Some **content** with _markdown_ `syntax`. -::: - -:::danger -Some **content** with _markdown_ `syntax`. -::: -::: - -:::info -Some **content** with _markdown_ `syntax`. -::: - -:::caution -Some **content** with _markdown_ `syntax`. -::: - -:::danger -Some **content** with _markdown_ `syntax`. -::: - -:::tip My personalized title -Some **content** with _markdown_ `syntax`. -::: -``` - -Which renders: - -:::note - -Some **content** with _markdown_ `syntax`. Check [this `api`](#). - -::: - -:::tip - -Some **content** with _markdown_ `syntax`. Check [this `api`](#). - -::: - -:::info - -Some **content** with _markdown_ `syntax`. Check [this `api`](#). - -::: - -:::caution - -Some **content** with _markdown_ `syntax`. Check [this `api`](#). - -::: - -:::danger - -Some **content** with _markdown_ `syntax`. Check [this `api`](#). - -::: - -:::tip My personalized title - -Some **content** with _markdown_ `syntax`. Check [this `api`](#). - -::: \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/contribute/index.md b/i18n/zh/docusaurus-plugin-content-docs/current/contribute/index.md deleted file mode 100644 index f6fbcc3931..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/contribute/index.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: Contribute -description: Contribute to the Stacks ecosystem. -sidebar_position: 10 -sidebar_label: "Contribute" ---- - -You can contribute to the Stacks ecosystem in multiple ways: - - - -### Documentation - -Contribute to the Stacks Docs on this website. Contribute to the Stacks Docs on this website. More info [here](docs). Contribute to the Stacks Docs on this website. More info [here](docs). - -### Translations - -Help us reach more people with translations. Help with translations. More details [here](translations). Help with translations. More details [here](translations). - - - -### Articles - -Write an article or a blog post about Stacks. A good place to start is [Stacks Forum](https://forum.stacks.org). Write an article or a blog post about Stacks. A good place to start is [Stacks Forum](https://forum.stacks.org). A good place to start is [Stacks Forum](https://forum.stacks.org). - -### Github - -If you are familiar with Github they are multiple repositories of the Stack Ecosystem that you can contribute to. - -- https://github.com/stacks-network/ diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/contribute/translations.md b/i18n/zh/docusaurus-plugin-content-docs/current/contribute/translations.md deleted file mode 100644 index fa419be8be..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/contribute/translations.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Contribute with translations -description: Want to help tranlating these docs to your local language? ---- - -## Help with translations - -Translations are managed with Crowdin. -Anybody can colaborate and no technichal skills are required, as it's all done on the browser. - -To help with translation please go to [this page](https://crowdin.com/project/docsstacksco), click any language and start translating. - -All help is appreciated. - -:::caution -Please don't add any translations to the Github repository, as the translated pages get rewritten from Crowdin. Translations need to be added on Crodin intead. -::: Translations need to be added on Crodin intead. -::: - -### Common issues on translations - -When translating in Crowdin, please only translate the texts and not the html code. - -If you acccidently modify the html tags you will get errors like shown below (`Seems like some formating tags are missing` or `Translation contains tag that source text doesn't have`). These errors will prevent your translation getting published until the tags are left as they were in the original text. If you acccidently modify the html tags you will get errors like shown below (`Seems like some formating tags are missing` or `Translation contains tag that source text doesn't have`). These errors will prevent your translation getting published until the tags are left as they were in the original text. These errors will prevent your translation getting published until the tags are left as they were in the original text. - -![](/img/crowdin-qa-issue-formatting_tags_missing.png) ![](/img/crowdin-qa-issue-tag_source.png) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/faq/faq.md b/i18n/zh/docusaurus-plugin-content-docs/current/faq/faq.md deleted file mode 100644 index c3e600e0c2..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/faq/faq.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: General FAQs -description: Frequently Asked Questions -sidebar_label: "FAQ" -sidebar_position: 10 ---- - -![](/img/glasses.png) - -## Why is my transfer still pending? - -Commonly it's because your fee is too low or your [nonce](#what-is-nonce) is incorrect. - -More information can be found [here](https://www.hiro.so/wallet-faq/why-is-my-stacks-transaction-pending). More information can be found [here](https://www.hiro.so/wallet-faq/why-is-my-stacks-transaction-pending). There are also [best practices and known issues](https://forum.stacks.org/t/transactions-in-mempool-best-practices-and-known-issues/11659) and [diagnosing pending transactions](https://forum.stacks.org/t/diagnosing-pending-transactions/11908). More information can be found [here](https://www.hiro.so/wallet-faq/why-is-my-stacks-transaction-pending). There are also [best practices and known issues](https://forum.stacks.org/t/transactions-in-mempool-best-practices-and-known-issues/11659) and [diagnosing pending transactions](https://forum.stacks.org/t/diagnosing-pending-transactions/11908). - -There is also this [script](https://github.com/citycoins/scripts/blob/main/getnetworkstatus.js) to look at either the first 200 transactions or all the transactions in the mempool, to then return the maximum adn average fee values. We've noticed that using 1.5-2x the average fee in the mempool will generally get things processed within 6-10 blocks even during high congestion. We've noticed that using 1.5-2x the average fee in the mempool will generally get things processed within 6-10 blocks even during high congestion. We've noticed that using 1.5-2x the average fee in the mempool will generally get things processed within 6-10 blocks even during high congestion. - -There is also this [script](https://github.com/citycoins/scripts/blob/main/gettxstatus.js) to track a pending transaction until it reaches a final status. - -## What is Nonce? - -A nonce is used to make sure that every transaction goes in right order. Nonce starts at 0, so the very first transaction from an address should set to nonce=0. You can find the nonce of your wallet address by searching the address in any [Stacks blockchain explorer](https://explorer.stacks.co/). You can also user `$ stx balance
`. - -If you have a transaction nonce that is less than your account nonce, the transaction is unmineable and will (should) disappear after 256 blocks. This does not affect future transactions and therefore can be just ignored, they are in the past. This does not affect future transactions and therefore can be just ignored, they are in the past. This does not affect future transactions and therefore can be just ignored, they are in the past. - -If you have a transaction nonce that is equal to your account nonce, then that transaction is valid and should be the next in line to be processed next. - -If you have a transaction nonce that is higher than your account nonce, then there needs to be a chain of transactions starting with your account nonce in order for it to be processed. E.g. Your account nonce is 10 but the pending transaction has a nonce of 12. It will not be mineable until a transaction with nonces 10 and 11 are processed. E.g. Your account nonce is 10 but the pending transaction has a nonce of 12. It will not be mineable until a transaction with nonces 10 and 11 are processed. E.g. Your account nonce is 10 but the pending transaction has a nonce of 12. It will not be mineable until a transaction with nonces 10 and 11 are processed. - -## Whats a Replace-by-fee (RBF)? - -A replace-by-fee (RBF) transaction tells the blockchain that you would like to replace one transaction with another, while specifying a fee that is higher than the original transaction fee. A transaction can be replaced with **any other transaction**, and is not limited to the same operation. A transaction can be replaced with **any other transaction**, and is not limited to the same operation. A transaction can be replaced with **any other transaction**, and is not limited to the same operation. - -This can be used to effectively **cancel a transaction** by replacing it with something else, like a small STX transfer to another owned address. - -This can be used to **raise the fee for a pending transaction** so it is considered by miners during periods of high congestion. This can be used to **raise the fee for a pending transaction** so it is considered by miners during periods of high congestion. This can also be used to _resubmit_ a transaction, in the sense that the RBF transaction gets a new txid and gets considered again (or faster) by miners. E.g. I submit my transaction with 1 STX fee at block 54,123. By block 54,133 I see my tx hasn’t been picked up, so I RBF with 1.1 STX. Then wait 10 blocks again, and RBF again if not received. There’s a balance between doing this too often and keeping a consistent pace, but it has been seen to help get transactions through, especially when new ones are constantly flooding in. E.g. I submit my transaction with 1 STX fee at block 54,123. By block 54,133 I see my tx hasn’t been picked up, so I RBF with 1.1 STX. Then wait 10 blocks again, and RBF again if not received. There’s a balance between doing this too often and keeping a consistent pace, but it has been seen to help get transactions through, especially when new ones are constantly flooding in. - -The replacement transaction needs to use the same nonce as the original transaction with a fee increase of at least 0.000001 STX. E.g. The replacement transaction needs to use the same nonce as the original transaction with a fee increase of at least 0.000001 STX. E.g. The replacement transaction needs to use the same nonce as the original transaction with a fee increase of at least 0.000001 STX. E.g. Your original transaction has a fee of 0.03 STX, the new RBF transaction must have a fee of 0.030001 STX or above. - -RBF transactions process in one of two ways: - -- If miners pick up the original transaction before the RBF transaction is received, then the original transaction is processed and the replacement transaction goes into an unmineable state. It will eventually disappear and doesn’t affect future transactions. It will eventually disappear and doesn’t affect future transactions. It will eventually disappear and doesn’t affect future transactions. -- If miners pick up the replaced transaction then the new transaction is processed instead of the original, and the status of the original transaction is set to “droppped_replaced_by_fee”. This status is not shown on the explorer but can be seen when querying the txid. This status is not shown on the explorer but can be seen when querying the txid. This status is not shown on the explorer but can be seen when querying the txid. - -Submitting multiple transactions for the same action can slow things down in a few ways. - -- If the total spent in 2 or 3 transactions is more than can be spent in a single transaction, the transactions appear unmineable. -- If the fees for multiple transactions exceed the STX balance, the transactions will be unmineable. - -## What are .btc domains? - -[This forum post](https://forum.stacks.org/t/btc-domains-are-live/12065) explains all the benefits of .btc domains. They can currently be purchased in [btc.us](https://btc.us/) They can currently be purchased in [btc.us](https://btc.us/) They can currently be purchased in [btc.us](https://btc.us/) - -## What is the blockchain trilemma? - -## Stacks vs. Solana vs. Polygon: How Do They Compare From a Developer Perspective? - -[This blog post answers the question](https://www.hiro.so/blog/stacks-vs-solana-vs-polygon-how-do-they-compare-from-a-developer-perspective). - -## What Does Lightning’s Taro Proposal Mean for Stacks? - -[This blog post answers the question](https://www.hiro.so/blog/what-does-lightnings-taro-proposal-mean-for-stacks). - - -## Is Stacks a [PoS chain](https://en.wikipedia.org/wiki/Proof_of_stake)?[¹][] - -No. - -The act of block production requires an extrinsic expenditure — it is not tied to owning the native token, as would be required in PoS. First, the history of all Stacks blocks produced is recorded to Bitcoin. This means that the act of producing a private Stacks fork is at least as hard as reorging the Bitcoin chain. This in turn makes it so attacks on the chain that rely on creating private forks (such as selfish mining and double-spending) are much harder to carry out profitably, since all honest participants can see the attack coming before it happens and have a chance to apply countermeasures. Sidechains offer no such security benefit. Moreover, the Stacks blockchain can fork, and there exists a protocol to rank forks by quality independent of the set of miners and the tokens they hold. These two properties further distinguish it from PoS chains, which cannot fork due to the inability to identify a canonical fork without trusting a 3rd party to decree a particular fork as valid. The ability to fork allows the Stacks blockchain to survive failure modes that would crash a PoS chain. - -## Is Stacks a [sidechain](https://en.bitcoin.it/wiki/Sidechain)?[¹][] - -No. - -For two key reasons. - -First, the history of all Stacks blocks produced is recorded to Bitcoin. This means that the act of producing a private Stacks fork is at least as hard as reorging the Bitcoin chain. This in turn makes it so attacks on the chain that rely on creating private forks (such as selfish mining and double-spending) are much harder to carry out profitably, since all honest participants can see the attack coming before it happens and have a chance to apply countermeasures. Sidechains offer no such security benefit. - -Second, the Stacks blockchain has its own token; it does not represent pegged Bitcoin. Second, the Stacks blockchain has its own token; it does not represent pegged Bitcoin. This means that the safety of the canonical fork of the Stacks blockchain is underpinned by its entire token economy’s value, whereas the safety of a sidechain’s canonical fork is underpinned only by whatever system-specific measures incentivize its validators to produce blocks honestly, or the Bitcoin miners’ willingness to process peg-in requests (whichever is the weaker guarantee). - - -## Is Stacks a [layer-2 system](https://academy.binance.com/en/glossary/layer-2) for Bitcoin?[¹][] - -No. - -Stacks blockchain is a layer-1 blockchain, which uses a novel and unique mining protocol called proof-of-transfer (PoX). Stacks blockchain is a layer-1 blockchain, which uses a novel and unique mining protocol called proof-of-transfer (PoX). A PoX blockchain runs in parallel to another blockchain (Bitcoin in Stacks’ case), which it uses as a reliable broadcast medium for its block headers. It's a sovereign system in its own right. The Stacks blockchain state is distinct from Bitcoin, and is wholly maintained by and for Stacks nodes. Stacks transactions are separate from Bitcoin transactions. Layer-2 systems like Lightning are designed to help scale Bitcoin payment transactions, whereas Stacks is designed to bring new use-cases to Bitcoin through smart contracts. Stacks is not designed as a Bitcoin layer-2 scalability solution. It's a sovereign system in its own right. The Stacks blockchain state is distinct from Bitcoin, and is wholly maintained by and for Stacks nodes. Stacks transactions are separate from Bitcoin transactions. Layer-2 systems like Lightning are designed to help scale Bitcoin payment transactions, whereas Stacks is designed to bring new use-cases to Bitcoin through smart contracts. Stacks is not designed as a Bitcoin layer-2 scalability solution. - - -## Is Stacks a [merged-mined chain](https://en.bitcoin.it/wiki/Merged_mining_specification)?[¹][] - -No. - -The only block producers on the Stacks chain are Stacks miners. Bitcoin miners do not participate in Stacks block validation, and do not claim Stacks block rewards. The only block producers on the Stacks chain are Stacks miners. Bitcoin miners do not participate in Stacks block validation, and do not claim Stacks block rewards. Moreover, Stacks is not a [blind merged-mined chain](https://github.com/bitcoin/bips/blob/master/bip-0301.mediawiki), because STX block winners are public and randomly chosen (instead of highest-bid-wins), and its tokens are minted according to a schedule that is independent of the degree of miner commitment or Bitcoin transferred (instead of minted only by one-way pegs from Bitcoin). This ensures that Stacks is able to make forward progress without opt-in from Bitcoin miners, and it ensures that Stacks miners are adequately compensated for keeping the system alive regardless of transaction volume. This ensures that Stacks is able to make forward progress without opt-in from Bitcoin miners, and it ensures that Stacks miners are adequately compensated for keeping the system alive regardless of transaction volume. - -## Whats the difference between Stacks and Ethereum?[²][] -**Computation and Storage** Stacks does all computation and storage outside of the blockchain, and uses the blockchain only as a “shared source of truth” between clients. By contrast, Ethereum does all computation and most application storage in the blockchain itself. Like Ethereum, if two Stacks nodes see the same underlying blockchain, they will independently run the same computations and produce the same state. Unlike Ethereum, there is no Stacks-specific blockchain. By contrast, Ethereum does all computation and most application storage in the blockchain itself. Like Ethereum, if two Stacks nodes see the same underlying blockchain, they will independently run the same computations and produce the same state. Unlike Ethereum, there is no Stacks-specific blockchain. - -**Programming Language and Tooling** Stacks’s programming model is based on running off-chain programs. These programs can be written and debugged in any language you want. By contrast, Ethereum’s programming model is based on running on-chain “smart contracts.” These are written and debugged with a whole new set of tools, like Solidity and Serpent. These programs can be written and debugged in any language you want. By contrast, Ethereum’s programming model is based on running on-chain “smart contracts.” These are written and debugged with a whole new set of tools, like Solidity and Serpent. - -**Scalability of On-chain Computation** Stacks is designed around a “virtual chain” concept, where nodes only need to reach consensus on the shared “virtual chain” they’re interested in. Virtual chains do not interact with one another, and a single blockchain can host many virtual chains. Although Stacks’s specific virtual chain is not Turing-complete (i.e. it’s a list of instructions to build the name database), it is possible to create Turing-complete virtual chains like Ethereum. These virtual chains can live in any blockchain for which there exists a driver, and virtual chain clients only need to execute their virtual chain transactions (i.e. Stacks only processes Stacks virtual chain transactions). Virtual chains do not interact with one another, and a single blockchain can host many virtual chains. Although Stacks’s specific virtual chain is not Turing-complete (i.e. it’s a list of instructions to build the name database), it is possible to create Turing-complete virtual chains like Ethereum. These virtual chains can live in any blockchain for which there exists a driver, and virtual chain clients only need to execute their virtual chain transactions (i.e. Stacks only processes Stacks virtual chain transactions). - -By contrast, because smart contracts run on-chain and can call one another, all Ethereum nodes need to process all smart contracts’ computations in order to reach consensus. This can get expensive as the number of running smart contracts grow, which takes the form of gas fee increases. This can get expensive as the number of running smart contracts grow, which takes the form of gas fee increases. - -**Scalability of Off-chain Computation** Stacks applications are very similar to Web applications today and almost never need to interact with the blockchain. For most Stacks applications, the blockchain is only used to authenticate the application’s code and data before the user runs it. By contrast, Ethereum applications usually require an application-specific smart contract, and must interact with the blockchain to carry out its operations. For most Stacks applications, the blockchain is only used to authenticate the application’s code and data before the user runs it. By contrast, Ethereum applications usually require an application-specific smart contract, and must interact with the blockchain to carry out its operations. - - -[¹]: https://stacks.org/stacks-blockchain -[²]: https://forum.stacks.org/t/what-is-the-difference-between-blockstack-and-ethereum/781 diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/gaia/configuration.md b/i18n/zh/docusaurus-plugin-content-docs/current/gaia/configuration.md deleted file mode 100644 index 3a97cde018..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/gaia/configuration.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Configuration -description: Configuring Gaia Hub ---- - -## Configuration files - -The following configuration files exist in the folder `deploy/configs/gaia/`: - -``` -admin-config.json -hub-config.json -reader-config.json -``` - -## GAIA Admin Service - -You can also use the GAIA Admin Service to remotely administer it with an API Key. It will require you to install `npm` with a `apt install npm`. Once `npm` is installed you can continue with the steps in the [GAIA Admin Service](https://github.com/stacks-network/gaia/blob/master/admin/README.md). It will require you to install `npm` with a `apt install npm`. Once `npm` is installed you can continue with the steps in the [GAIA Admin Service](https://github.com/stacks-network/gaia/blob/master/admin/README.md). It will require you to install `npm` with a `apt install npm`. Once `npm` is installed you can continue with the steps in the [GAIA Admin Service](https://github.com/stacks-network/gaia/blob/master/admin/README.md). - -## Driver Selection - -The Gaia hub currently supports the following drivers: - -``` -'aws' == Amazon S3 -'azure' == Azure Blob Storage -'disk' == Local disk -'google-cloud' === Google Cloud Storage -``` - -Set the driver you wish to use in your [config.json](https://github.com/stacks-network/gaia/blob/master/hub/config.sample.json) file with the `driver` parameter. Many drivers additionally accept the `bucket` parameter, which controls the bucket name that files should be written to. Many drivers additionally accept the `bucket` parameter, which controls the bucket name that files should be written to. Many drivers additionally accept the `bucket` parameter, which controls the bucket name that files should be written to. - -These driver may require you to provide additional credentials for performing writes to the backends. See `config.sample.json` for fields for those credentials. These driver may require you to provide additional credentials for performing writes to the backends. See `config.sample.json` for fields for those credentials. These driver may require you to provide additional credentials for performing writes to the backends. See `config.sample.json` for fields for those credentials. In some cases, the driver can use a system configured credential for the backend (e.g., if you are logged into your AWS CLI account, and run the hub from that environment, it won't need to read credentials from your `config.json`). - -_Note:_ The disk driver requires a \*nix like filesystem interface, and will not work correctly when trying to run in a Windows environment. ::: - -## Note on SSL - -We _strongly_ recommend that you deploy your Gaia hub with SSL enabled. We _strongly_ recommend that you deploy your Gaia hub with SSL enabled. We _strongly_ recommend that you deploy your Gaia hub with SSL enabled. Otherwise, the tokens used to authenticate with the Gaia hub may be stolen by attackers, which could allow them to execute writes on your behalf. -Configuration options are available to run the hub with an `https` Node.js server. -Otherwise, a reverse proxy web server such as nginx or Apache can be used. - -## Require Correct Hub URL - -If you turn on the `requireCorrectHubUrl` option in your `config.json` file, your Gaia hub will require that authentication requests correctly include the `hubURL` they are trying to connect with. This is used to prevent a malicious gaia hub from using an authentication token for itself on other Gaia hubs. This is used to prevent a malicious gaia hub from using an authentication token for itself on other Gaia hubs. This is used to prevent a malicious gaia hub from using an authentication token for itself on other Gaia hubs. - -By default, the Gaia hub will validate that the supplied URL matches `https://${config.serverName}`, but if there are multiple valid URLs for clients to reach the hub at, you can include a list in your `config.json`: - -```javascript -{ - .... - { - .... - { - .... - serverName: "normalserver.com" - validHubUrls: [ "https://specialserver.com/", - "https://legacyurl.info" ] - .... -} -} -} -``` - -## The readURL parameter - -By default, the gaia hub drivers will return read URLs which point directly at the written content. For example, an S3 driver would return the URL directly to the S3 file. However, if you configure a CDN or domain to point at that same bucket, you can use the `readURL` parameter to tell the gaia hub that files can be read from the given URL. For example, the `hub.blockstack.org` Gaia Hub is configured to return a read URL that looks like `https://gaia.blockstack.org/hub/`. For example, an S3 driver would return the URL directly to the S3 file. However, if you configure a CDN or domain to point at that same bucket, you can use the `readURL` parameter to tell the gaia hub that files can be read from the given URL. For example, the `hub.blockstack.org` Gaia Hub is configured to return a read URL that looks like `https://gaia.blockstack.org/hub/`. - -Unset this configuration parameter if you do not intend to deploy any caching. - -## Minimum Proofs Requirement - -The gaia hub can also be configured to require a minimum number of social proofs in a user's profile to accept writes from that user. This can be used as a kind of spam-control mechanism. However, we recommend for the smoothest operation of your gaia hub, to set the `proofsConfig.proofsRequired` configuration key to `0`. This can be used as a kind of spam-control mechanism. However, we recommend for the smoothest operation of your gaia hub, to set the `proofsConfig.proofsRequired` configuration key to `0`. This can be used as a kind of spam-control mechanism. However, we recommend for the smoothest operation of your gaia hub, to set the `proofsConfig.proofsRequired` configuration key to `0`. - -## CDN & Replicated Hubs - -- https://docs.microsoft.com/en-us/azure/storage/blobs/storage-https-custom-domain-cdn - -- The hub implementation is designed to be ran from a single Node.js instance. The hub implementation is designed to be ran from a single Node.js instance. The hub implementation is designed to be ran from a single Node.js instance. If the hub instance is sharded (e.g. replicated hubs via load balancing), then any given `bucket` (identified by URI segment) must be served by the same instance, At least a couple elements of the Gaia Hub depend on this: token invalidation in-memory caching, and resource endpoint 409 contention behavior. diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md b/i18n/zh/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md deleted file mode 100644 index 558cbb14f5..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/gaia/deploy-gaia-hub.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Deploy Gaia Hub -description: Steps and tutorials ---- - -## Deploy your GAIA hub - -Tutorials to deploy your own GAIA hub are currently available for [Linux](./setup-linux), [MacOS](./setup-mac) and [Amazon EC2 / CloudFormation](./gaia-on-ec2). - -Regardless of what server the Gaia Hub runs on, the storage it uses can currently be deployed on multiple platforms: - -- Local disk (the server itself) -- Amazon S3 -- Azure Blob Storage -- Google Cloud - -:::tip -Support for IPFS is under development. -::: \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md b/i18n/zh/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md deleted file mode 100644 index 2dd4b2ca9a..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/gaia/gaia-on-ec2.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Amazon EC2 -description: Use a template to deploy a Gaia hub on Amazon EC2 -tags: - - tutorial - - gaia ---- - -## Introduction - -The template provided on this page provides an easy way to deploy a Gaia hub directly to Amazon EC2. You can use this template to deploy your own Gaia hub to your Amazon Web Services (AWS) account. Amazon EC2 is an affordable and convenient cloud computing provider. The template provides a one-click deploy for Amazon EC2 with either S3 or EBS as a storage provider. You can use this template to deploy your own Gaia hub to your Amazon Web Services (AWS) account. Amazon EC2 is an affordable and convenient cloud computing provider. The template provides a one-click deploy for Amazon EC2 with either S3 or EBS as a storage provider. You can use this template to deploy your own Gaia hub to your Amazon Web Services (AWS) account. Amazon EC2 is an affordable and convenient cloud computing provider. The template provides a one-click deploy for Amazon EC2 with either S3 or EBS as a storage provider. - -## Prerequisites - -This procedure uses Amazon CloudFormation to configure an EC2 cloud compute provider to run the Gaia hub service with an S3 or EBS provider for file storage. You should have access to an AWS account either through your personal account or through a corporate account. This account should have permissions to create resources. You should have access to an AWS account either through your personal account or through a corporate account. This account should have permissions to create resources. You should have access to an AWS account either through your personal account or through a corporate account. This account should have permissions to create resources. - -Additionally, you must also own a domain name and be able to update the DNS records associated with that domain name. - -## Setup steps - -### Step 1 - Create Stack - -Use a link in the table to launch the [CloudFormation](https://console.aws.amazon.com/cloudformation/) template in the AWS region that you wish to deploy a Gaia hub. - -![Create stack](/img/cloudformation-create-stack.png) - -### Step 2 - Setup stack using template - -You need to configure the template with the appropiate values for your hub and domain it runs on. - -Select `Template is ready` and `Amazon S3 URL` and enter the following Amazon S3 URL: -``` -https://s3-external-1.amazonaws.com/cf-templates-vzldibfi2mw8-us-east-1/2022160J6G-cloudformation.yaml -``` - -If you prefer you can instead select `Template is ready` and `Upload a template file` to upload the template file `cloudformation.yaml`. - -The latest `cloudformation.yaml` file can be downloaded [here](https://raw.githubusercontent.com/stacks-network/gaia/master/deploy/cloudformation.yaml). On most browsers you can right-click on that page and click on `Save page as` to download the file. Alternatively, you can copy/paste the text into a text file called `cloudformation.yaml`. On most browsers you can right-click on that page and click on `Save page as` to download the file. Alternatively, you can copy/paste the text into a text file called `cloudformation.yaml`. On most browsers you can right-click on that page and click on `Save page as` to download the file. Alternatively, you can copy/paste the text into a text file called `cloudformation.yaml`. - -Then click `Next`. - -![Specify template](/img/cloudformation-specify-template.png) - -### Step 3 - Specify stack details - -Specify the stack details and then click `Next`: ![Specify template](/img/cloudformation-specify-stack-details.png) - -| Field | Value | Notes | -| --------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Stack name | _a unique name in your AWS account_ | e.g.: my_gaia_hub | -| DomainName | _your-domain_ | | -| EmailAddress | _your email address_ | | -| GaiaBucketName | _S3 bucket name_ | The template combines this name with the stack name to create a unique S3 bucket. The template combines this name with the stack name to create a unique S3 bucket. The template ignores this field if GaiaStorageType is set to `disk`. The template combines this name with the stack name to create a unique S3 bucket. The template ignores this field if GaiaStorageType is set to `disk`. | -| GaiaStorageType | `s3` or `disk` | Select the GaiaStorageType of which to use as a backend for the Gaia Hub. Selecting `s3` causes the template to create an S3 bucket based on the name given in the previous field. Select the GaiaStorageType of which to use as a backend for the Gaia Hub. Selecting `s3` causes the template to create an S3 bucket based on the name given in the previous field. Selecting `disk` causes the template to attach a separate EBS volume to the EC2 instance for Hub storage. | -| InstaceType | t2.micro | Select the instance type you want. Select the instance type you want. Default value is `t2.micro`. Select the instance type you want. Default value is `t2.micro`. | -| KeyName | | In the KeyName drop-down, select an [EC2 KeyPair](https://console.aws.amazon.com/ec2/v2/home?region=us-east-1#KeyPairs:) to enable SSH access to the EC2 instance. You should download the `.pem` keyfile for this pair from the EC2 console. For more information see the [EC2 key pair documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html#prepare-key-pair) You should download the `.pem` keyfile for this pair from the EC2 console. For more information see the [EC2 key pair documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html#prepare-key-pair) You should download the `.pem` keyfile for this pair from the EC2 console. For more information see the [EC2 key pair documentation](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html#prepare-key-pair) | -| SSHLocation | 0.0.0.0/0 | Leave the SSHLocation field with the default value of `0.0.0.0/0` to enable SSH access from any IP address. If you wish to restrict SSH access to the EC2 instance to a certain IP, you can update this field. Leave the SSHLocation field with the default value of `0.0.0.0/0` to enable SSH access from any IP address. If you wish to restrict SSH access to the EC2 instance to a certain IP, you can update this field. If you wish to restrict SSH access to the EC2 instance to a certain IP, you can update this field. | -| SubnetId | _subnetid_ | Select a public subnet | -| VpcId | _vpcid_ | | - -### Step 4 - Configure stack options - -Configure any stack options that fit your desired setup and click `Next`. All these fields are optinal. All these fields are optional. All these fields are optional. - -![Specify template](/img/cloudformation-stack-options.png) - -### Step 5 - Review - -Review the configuration of your Gaia hub, select the checkbox to acknowledge that AWS may create IAM resources with custom names and click on `Create stack`. - -![Specify template](/img/cloudformation-iam-resources.png) - -### Step 6 - Retrieve the public IP of your Gaia hub - -Your stack can take several minutes to launch. You can monitor the Events tab of your hub to review the current progress of the launch. When the launch is complete, the Outputs tab displays information about the hub. Select the PublicIP and copy it to configure your domain name. - -Create an `A` DNS record pointing to the given IP in your domain. - -Wait a few minutes for the DNS record to propagate, and your should be able to access your Gaia hub with SSH. - -## Accessing your Gaia hub with SSH - -To SSH into your Gaia hub EC2 host directly, you must have the keyfile used in container creation. Access the host with the following command in your terminal: Access the host with the following command in your terminal: Access the host with the following command in your terminal: - -```bash -ssh -i admin@ -``` - -:::tip If you can only access SSH with the IP but not with the DNS name and you wish to do so, you can optionally activate it by following these steps: - - Open your [AWS Console](https://console.aws.amazon.com) - Click on `Service` -> VPC - Open Your VPCs - Select your VPC connected to your Gaia Hub - Click `Actions` -> `Edit DNS Hostnames` -> Change `DNS hostnames` to `Enable` -::: -## Graphical representation of the cloudformation template - -![](/img/cloudformation-gaia-template1-designer.png) \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/gaia/gaia.md b/i18n/zh/docusaurus-plugin-content-docs/current/gaia/gaia.md deleted file mode 100644 index 5718b504f2..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/gaia/gaia.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: Gaia -description: Decentralized storage architecture for off-chain data -sidebar_position: 5 -tags: - - gaia ---- - -## Introduction - -Apps built with the Stacks blockchain store off-chain data using a storage system called Gaia. - -Whereas public transactional metadata is best stored on the Stacks blockchain, user application data can often be stored more efficiently and privately in Gaia storage. - -Storing data off of the blockchain ensures that Stacks applications can provide users with high performance and high availability for data reads and writes without introducing central trust parties. - -:::tip Latest whitepaper of GAIA (May 2022) is available [here](https://dev1-gaia-hub.s3.amazonaws.com/GAIA_Whitepaper.pdf) ::: - -## Understand Gaia in the Stacks architecture - -The following diagram depicts the Stacks architecture and Gaia's place in it: - -![Stacks Architecture](/img/architecture.png) - -Blockchains require consensus among large numbers of people, so they can be slow. Additionally, a blockchain is not designed to hold a lot of data. This means using a blockchain for every bit of data a user might write and store is expensive. For example, imagine if an application were storing every tweet in the chain. Additionally, a blockchain is not designed to hold a lot of data. This means using a blockchain for every bit of data a user might write and store is expensive. For example, imagine if an application were storing every tweet in the chain. Additionally, a blockchain is not designed to hold a lot of data. This means using a blockchain for every bit of data a user might write and store is expensive. For example, imagine if an application were storing every tweet in the chain. - -The Stacks blockchain addresses performance problems using a layered approach. The Stacks blockchain addresses performance problems using a layered approach. The base layer consists of the Stacks blockchain and the Blockchain Naming System (BNS). The blockchain governs ownership of identities in the Stacks network. Identities can be names such as domain names, usernames, or application names. The blockchain governs ownership of identities in the Stacks network. Identities can be names such as domain names, usernames, or application names. - -When an identity is created, its creation is recorded in the Stacks blockchain. Identities make up the primary data stored into the Stacks blockchain. These identities correspond to routing data in the OSI stack. The routing data is stored in the Atlas Peer Network, the second layer. Every core node that joins the Stacks Network is able to obtain an entire copy of this routing data. Stacks uses the routing data to associate identities (domain names, user names, and application names) with a particular storage location in the final layer, the Gaia Storage System. - -A Gaia Storage System consists of a _hub service_ and storage resource on a cloud software provider. The storage provider can be any commercial provider such as Azure, DigitalOcean, Amazon EC2, and so forth. Typically the compute resource and the storage resource reside same cloud vendor, though this is not a requirement. A Gaia Storage System consists of a _hub service_ and storage resource on a cloud software provider. The storage provider can be any commercial provider such as Azure, DigitalOcean, Amazon EC2, and so forth. Typically the compute resource and the storage resource reside same cloud vendor, though this is not a requirement. Gaia currently has driver support for S3, Azure Blob Storage, Google Cloud Platform and local disk, but the driver model allows for other backend support as well. The storage provider can be any commercial provider such as Azure, DigitalOcean, Amazon EC2, and so forth. Typically the compute resource and the storage resource reside same cloud vendor, though this is not a requirement. A Gaia Storage System consists of a _hub service_ and storage resource on a cloud software provider. The storage provider can be any commercial provider such as Azure, DigitalOcean, Amazon EC2, and so forth. Typically the compute resource and the storage resource reside same cloud vendor, though this is not a requirement. Gaia currently has driver support for S3, Azure Blob Storage, Google Cloud Platform and local disk, but the driver model allows for other backend support as well. - -Gaia stores data as a simple key-value store. When an identity is created, a corresponding data store is associated with that identity on Gaia. Gaia stores data as a simple key-value store. When an identity is created, a corresponding data store is associated with that identity on Gaia. When a user logs into a dApp, the authentication process gives the application the URL of a Gaia hub, which then writes to storage on behalf of that user. When an identity is created, a corresponding data store is associated with that identity on Gaia. Gaia stores data as a simple key-value store. When an identity is created, a corresponding data store is associated with that identity on Gaia. When a user logs into a dApp, the authentication process gives the application the URL of a Gaia hub, which then writes to storage on behalf of that user. - -The Stacks blockchain stores only identity data. Data created by the actions of an identity is stored in a Gaia Storage System. Each user has profile data. When a user interacts with a decentralized dApp that application stores application data on behalf of the user. The Stacks blockchain stores only identity data. Data created by the actions of an identity is stored in a Gaia Storage System. Each user has profile data. When a user interacts with a decentralized dApp that application stores application data on behalf of the user. Because Gaia stores user and application data off the blockchain, a Stacks DApp is typically more performant than DApps created on other blockchains. Data created by the actions of an identity is stored in a Gaia Storage System. Each user has profile data. When a user interacts with a decentralized dApp that application stores application data on behalf of the user. The Stacks blockchain stores only identity data. Data created by the actions of an identity is stored in a Gaia Storage System. Each user has profile data. When a user interacts with a decentralized dApp that application stores application data on behalf of the user. Because Gaia stores user and application data off the blockchain, a Stacks DApp is typically more performant than DApps created on other blockchains. - -## User control or how is Gaia decentralized? - -A Gaia hub runs as a service which writes to data storage. The storage itself is a simple key-value store. The hub service writes to data storage by requiring a valid authentication token from a requestor. Typically, the hub service runs on a compute resource and the storage itself on separate, dedicated storage resource. Typically, both resources belong to the same cloud computing provider. The storage itself is a simple key-value store. The hub service writes to data storage by requiring a valid authentication token from a requestor. Typically, the hub service runs on a compute resource and the storage itself on separate, dedicated storage resource. Typically, both resources belong to the same cloud computing provider. The storage itself is a simple key-value store. The hub service writes to data storage by requiring a valid authentication token from a requestor. Typically, the hub service runs on a compute resource and the storage itself on separate, dedicated storage resource. Typically, both resources belong to the same cloud computing provider. - -![Gaiastorage](/img/gaia-storage.png) - -Gaia's approach to decentralization focuses on user control of data and its storage. Users can choose a Gaia hub provider. Gaia's approach to decentralization focuses on user control of data and its storage. Users can choose a Gaia hub provider. If a user can choose which Gaia hub provider to use, then that choice is all the decentralization required to enable user-controlled applications. Moreover, Gaia defines a uniform API for applications to access that data. Moreover, Gaia defines a uniform API for applications to access that data. Users can choose a Gaia hub provider. Gaia's approach to decentralization focuses on user control of data and its storage. Users can choose a Gaia hub provider. If a user can choose which Gaia hub provider to use, then that choice is all the decentralization required to enable user-controlled applications. Moreover, Gaia defines a uniform API for applications to access that data. Moreover, Gaia defines a uniform API for applications to access that data. - -The control of user data lies in the way that user data is accessed. The control of user data lies in the way that user data is accessed. The control of user data lies in the way that user data is accessed. When an application fetches a file `data.txt` for a given user `alice.id`, the lookup will follow these steps: - -1. Fetch the `zonefile` for `alice.id`. -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. Find the read-only url out of the profile's `appsMeta` section (e.g. `https://example-app.gaia.alice.org`). -6. Fetch the file from `https://example-app.gaia.alice.org/data.txt`. - -Because `alice.id` has access to her [zonefile](https://docs.stacks.co/references/bns-contract#name-update), 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. For example, she may do this if the current profile's service provider or storage is compromised. Because `alice.id` has access to her [zonefile](https://docs.stacks.co/references/bns-contract#name-update), 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. 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. 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. - -:::caution -Users with existing identities cannot yet migrate their data from one hub to another. -::: ::: -::: - -Applications writing directly on behalf of `alice.id` do not need to perform a lookup. Applications writing directly on behalf of `alice.id` do not need to perform a lookup. Instead, the [Stacks authentication flow](https://stacks.js.org) provides Alice's chosen gaia hub URL to the application. This authentication flow _is also_ within Alice's control because Alice's wallet _must_ generate the authentication response. This authentication flow _is also_ within Alice's control because Alice's wallet _must_ generate the authentication response. Applications writing directly on behalf of `alice.id` do not need to perform a lookup. Instead, the [Stacks authentication flow](https://stacks.js.org) provides Alice's chosen gaia hub URL to the application. This authentication flow _is also_ within Alice's control because Alice's wallet _must_ generate the authentication response. This authentication flow _is also_ within Alice's control because Alice's wallet _must_ generate the authentication response. - -## Understand data storage - -A Gaia hub stores the written data _exactly_ as given. It offers minimal guarantees about the data. It does not ensure that data is validly formatted, contains valid signatures, or is encrypted. Rather, the design philosophy is that these concerns are client-side concerns. It offers minimal guarantees about the data. It does not ensure that data is validly formatted, contains valid signatures, or is encrypted. Rather, the design philosophy is that these concerns are client-side concerns. It offers minimal guarantees about the data. It does not ensure that data is validly formatted, contains valid signatures, or is encrypted. Rather, the design philosophy is that these concerns are client-side concerns. - -Client libraries (such as [`Stacks.js`](https://stacks.js.org/)) are capable of providing these guarantees. A liberal definition of the [end-to-end principle](https://en.wikipedia.org/wiki/End-to-end_principle) guides this design decision. A liberal definition of the [end-to-end principle](https://en.wikipedia.org/wiki/End-to-end_principle) guides this design decision. A liberal definition of the [end-to-end principle](https://en.wikipedia.org/wiki/End-to-end_principle) guides this design decision. - -When an application writes to a Gaia hub, an authentication token, key, and the data are passed to the Gaia hub. - -![Gaia writes](/img/gaia-writes.png) - -The token ensures the app has the authorization to write to the hub on the user's behalf. - -## Gaia versus other storage systems - -Here's how Gaia stacks up against other decentralized storage systems. Features that are common to all storage systems are omitted for brevity. Features that are common to all storage systems are omitted for brevity. Features that are common to all storage systems are omitted for brevity. - -| Features | [Gaia](https://github.com/stacks-network/gaia) | [Sia](https://sia.tech/) | [Storj](https://storj.io/) | [IPFS](https://ipfs.io/) | [DAT](https://datproject.org/) | [SSB](https://www.scuttlebutt.nz/) | -| ------------------------------------------ | ---------------------------------------------- | ------------------------ | -------------------------- | ------------------------ | ------------------------------ | ---------------------------------- | -| User controls where data is hosted | X | | | | | | -| Data can be viewed in a normal Web browser | X | | | X | | | -| Data is read/write | X | | | | X | X | -| Data can be deleted | X | | | | X | X | -| Data can be listed | X | X | X | | X | X | -| Deleted data space is reclaimed | X | X | X | X | | | -| Data lookups have predictable performance | X | | X | | | | -| Writes permission can be delegated | X | | | | | | -| Listing permission can be delegated | X | | | | | | -| Supports multiple backends natively | X | | X | | | | -| Data is globally addressable | X | X | X | X | X | | -| Needs a cryptocurrency to work | | X | X | | | | -| Data is content-addressed | | X | X | X | X | X | diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/gaia/setup-linux.md b/i18n/zh/docusaurus-plugin-content-docs/current/gaia/setup-linux.md deleted file mode 100644 index dea034dd65..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/gaia/setup-linux.md +++ /dev/null @@ -1,129 +0,0 @@ ---- -title: Linux -description: Steps to setup a GAIA hub on a Linux server (fresh install). This example is using Debian, but should work on any Linux distribution. It uses docker compose in the backgroud. This example is using Debian, but should work on any Linux distribution. It uses docker compose in the backgroud. This example is using Debian, but should work on any Linux distribution. It uses docker compose in the backgroud. -tags: - - tutorial - - gaia ---- - -This configuration will setup the following 4 docker containers: - -- Nginx with certbot on TCP ports 80 and 443. -- Gaia hub on TCP port 3000. -- Gaia admin on TCP port 8009. -- Gaia reader on TCP port 8008 - -**1. 1. 1. Update the system and install the dependencies and software we will use to test:** - -```bash -apt update && apt upgrade -y && apt install -y git vim gnupg jq -``` - -**2. **2. **2. Install [docker](https://docs.docker.com/engine/install/debian/) and [docker-compose](https://docs.docker.com/compose/cli-command/#install-on-linux)** in your OS. -For our example we install _docker_ with:

- -```bash -curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg - -echo \ - "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian \ - $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null - -apt update && apt install -y docker-ce docker-ce-cli containerd.io -``` - -Install _docker-compose_ by downloading the [latest-release](https://github.com/docker/compose/releases): - -```bash -VERSION_DC=$(curl --silent https://api.github.com/repos/docker/compose/releases/latest | jq .name -r) -DESTINATION_DC=~/.docker/cli-plugins -mkdir -p ${DESTINATION_DC} -curl -SL https://github.com/docker/compose/releases/download/${VERSION_DC}/docker-compose-linux-x86_64 -o ${DESTINATION_DC}/docker-compose -chmod +x ${DESTINATION_DC}/docker-compose -``` - -**3. **3. **3. Clone the GAIA repository** and enter it's docker directory.

- -```bash -git clone https://github.com/stacks-network/gaia.git && cd gaia/deploy/docker -``` - -**4. **4. Copy and edit appropiate .env file**. -In the folder `./deploy/docker/` they are different sample files for different configurations like using aws, azure or disk among others. In this example we will store the data localy so we will copy the _disk_ file and update the domain and email fields. Please change `gaia.site.com` and `gaiarocks@mydomain.com` accordingly. Note you need both for the SSL certificate to be created correctly. In this example we will store the data localy so we will copy the _disk_ file and update the domain and email fields. Please change `gaia.site.com` and `gaiarocks@mydomain.com` accordingly. Note you need both for the SSL certificate to be created correctly.

- -```bash -export MYGAIADOMAIN=gaia.site.com -export MYGAIAEMAIL=gaiarocks@mydomain.com -cp sample-disk.env disk.env -sed -i 's/my-domain.com/'"$MYGAIADOMAIN"'/g' disk.env -sed -i 's/my-email@example.com/'"$MYGAIAEMAIL"'/g' disk.env - -``` - -**5. 5. 5. Start GAIA HUB service** - -To start GAIA HUB - -```bash -./gaiahub.sh start -``` - -To stop GAIA HUB - -```bash -./gaiahub.sh stop -``` - -To view GAIA HUB status - -```bash -./gaiahub.sh status -``` - -**6. **6. **6. Verify server works locally** with the following command:

- -```bash -curl -sk http://localhost/hub_info | jq -``` - -A correct result should look similar to this: - -```bash - { - "challenge_text": "[\"gaiahub\",\"0\",\"gaia-0\",\"blockstack_storage_please_sign\"]", - "latest_auth_version": "v1", - "max_file_upload_size_megabytes": 20, - "read_url_prefix": "https://gaia.site.com/reader/" - } -``` - -**7. **7. **7. Test your GAIA HUB** Running `gaia_test.js` will test your GAIA Hub, by trying to connect to it, uploading a file and downloading it again.

- -First install all required dependencies with: - -```bash -npm install -``` - -Then, from the root folder of the project type: - -```bash -node ./deploy/gaia_test.js https://yourgaiaurl -``` - -A correct result will be something like this: - -``` -Will run a test for the GAIA HUB: https://gaia.mydomain.com -Generating some test keys... -Private key: 5aacc60fc2a429e1f02be139f3cac82061c6a980******************** -Public key: 025691f17f2ab80dc4af363bb9c7aac59e9e1db6ae8ff668202582a3f4ec9678ff -Address: 15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS -[DEBUG] connectToGaiaHub: https://gaia.mydomain.com/hub_info -[DEBUG] uploadToGaiaHub: uploading testing.txt to https://gaia.mydomain.com -File uploaded successfully. -Upload to gaia hub thinks it can read it from: https://gaia.mydomain.com/reader/15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS/testing.txt -Hub info thinks it can read it from : https://gaia.mydomain.com/reader/15n8Xo8acRvSZghJG2dxJ8dCdzDMYicUuS/testing.txt -Let's now try to fetch the uploaded file... -File fetched successfully. Contents of file: GAIA ROCKS! -``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/gaia/setup-mac.md b/i18n/zh/docusaurus-plugin-content-docs/current/gaia/setup-mac.md deleted file mode 100644 index 86b247af5e..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/gaia/setup-mac.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: MacOS -description: MacOS for local testing/development -tags: - - tutorial ---- - -The following assumes you have [Docker Installed](https://docs.docker.com/docker-for-mac/install/) - -- Recommended to also have [MacOS Homebrew](https://docs.brew.sh/Installation) installed -- Use Homebrew to install jq with `brew install jq` - -In your working directory: - -**1. 1. 1. Clone a copy of the [gaia repo](https://github.com/stacks-network/gaia):** - -```bash -$ git clone -b master --single-branch https://github.com/stacks-network/gaia -``` - -**2. 2. 2. Change your cwd:** - -```bash -$ cd gaia/deploy/docker -``` - -**3. 3. 3. Create a copy of sample-disk.env and fill out the values:** - -``` -$ cp sample-disk.env disk.env -# Update the DOMAIN_NAME variable to `localhost` -``` - -**4. 4. 4. Start the server:** - -``` -$ docker-compose -f docker-compose-base.yaml -f docker-compose-disk.yaml --env-file disk.env up -``` - -**5. 5. 5. Verify the server is responding locally:** - -``` -$ curl -sk https://localhost/hub_info | jq - { - "challenge_text": "[\"gaiahub\",\"0\",\"gaia-0\",\"blockstack_storage_please_sign\"]", - "latest_auth_version": "v1", - "max_file_upload_size_megabytes": 20, - "read_url_prefix": "https://localhost/reader/" - } -``` - -### Modifying the configuration for your gaia-hub - -Two methods exist: - -1. Edit the `gaia/deploy/configs/gaia/hub-config.json` using `vim` or other - -- requires a restart of the containers: `docker-compose -f docker-compose-base.yaml -f docker-compose-disk.yaml --env-file disk.env restart` - -2. Use the running `admin` container to modify any config values, and also reload the hub when complete: - -- [GitHub - Gaia Admin README.md](https://github.com/stacks-network/gaia/blob/master/admin/README.md) - -``` -$ export API_KEY="hello" -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - -H 'Content-Type: application/json' \ - -X POST \ - --data-raw '{"serverName": "myserver"}' \ - http://localhost:8009/v1/admin/config - -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - -X POST \ - http://localhost:8009/v1/admin/reload - -$ curl -s \ - -H "Authorization: bearer $API_KEY" \ - http://localhost:8009/v1/admin/config | jq -``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/governance/_index.md b/i18n/zh/docusaurus-plugin-content-docs/current/governance/_index.md deleted file mode 100644 index 73c66a4ae1..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/governance/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -title: Governance -description: Governance -sidebar_position: 9 ---- - -This page needs contributions. Help us write it! Help us write it! \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/governance/index.md b/i18n/zh/docusaurus-plugin-content-docs/current/governance/index.md deleted file mode 100644 index 91b0215b5f..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/governance/index.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Governance -description: Governance -sidebar_position: 9 ---- - -![](/img/stacks-governance.png) - -This page needs contributions. Help us write it! - -Governance in web3 is driven by the community. - -How can I get involved ? - -[Governance Resources website](https://resources.stacksgov.com) - -[Github - Stack Community Governance](https://github.com/stacksgov) - -:::tip Community Calls Monthly community calls are recorded and available [here](https://www.youtube.com/playlist?list=PLg717Ri_rTnwwYjQYlc7rIP6x2FaTNn7f) ::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/governance/sips.md b/i18n/zh/docusaurus-plugin-content-docs/current/governance/sips.md deleted file mode 100644 index 29ac1ae1ed..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/governance/sips.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: SIPs -description: SIPs -sidebar_position: 9 ---- - -## Stacks Improvement Proposals (SIPs) - -Stacks improvement proposals (SIPs) are aimed at describing the implementation of the Stacks blockchain, as well as proposing improvements. - -The SIP process [(SIP-000)](https://github.com/stacksgov/sips/blob/main/sips/sip-000/sip-000-stacks-improvement-proposal-process.md) describes how to make a SIP and get it ratified. - -They should contain concise technical specifications of features or standards and the rationale behind it. SIPs are intended to be the primary medium for proposing new features, for collecting community input on a system-wide issue, and for documenting design decisions. - -The SIPs are located in the [stacksgov/sips](https://github.com/stacksgov/sips) repository as part of the [Stacks Community Governance organization](https://github.com/stacksgov). - -Anyone in the Stacks community can submit a SIP. - -:::tip Stacks Improvement Proposals Community Calls SIP Meeting calls are recorded and available [here](https://www.youtube.com/playlist?list=PLg717Ri_rTnx5kuaWqp3cUAtwQk_yzslT) - -More details of the meetings are available [here](https://github.com/stacksgov/sips/issues/79) ::: - -## Ratified SIPSs - -- [x] [SIP 001: Burn Election](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md) -- [x] [SIP 002: Clarity, a language for predictable smart contracts](https://github.com/stacksgov/sips/blob/main/sips/sip-002/sip-002-smart-contract-language.md) -- [x] [SIP 003: Peer Network](https://github.com/stacksgov/sips/blob/main/sips/sip-003/sip-003-peer-network.md) -- [x] [SIP 004: Cryptographic Committment to Materialized Views](https://github.com/stacksgov/sips/blob/main/sips/sip-004/sip-004-materialized-view.md) -- [x] [SIP 005: Blocks, Transactions, and Accounts](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md) -- [x] [SIP 006: Clarity Execution Cost Assessment](https://github.com/stacksgov/sips/blob/main/sips/sip-006/sip-006-runtime-cost-assessment.md) -- [x] [SIP 007: Stacking Consensus](https://github.com/stacksgov/sips/blob/main/sips/sip-007/sip-007-stacking-consensus.md) -- [x] [SIP 008: Clarity Parsing and Analysis Cost Assessment](https://github.com/stacksgov/sips/blob/main/sips/sip-008/sip-008-analysis-cost-assessment.md) -- [x] [SIP 009: Standard Trait Definition for Non-Fungible Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-009/sip-009-nft-standard.md) -- [x] [SIP 010: Standard Trait Definition for Fungible Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-010/sip-010-fungible-token-standard.md) -- [x] [SIP 012: Burn Height Selection for a Network Upgrade to Introduce New Cost-Limits](https://github.com/stacksgov/sips/blob/main/sips/sip-012/sip-012-cost-limits-network-upgrade.md) -- [x] [SIP-016: Metadata for Tokens](https://github.com/stacksgov/sips/blob/main/sips/sip-016/sip-016-token-metadata.md) - -## How to Get Involved - -There are several ways you can get involved with the SIP process: - -* **Join the weekly SIP Meeting call** listed [here](https://community.stacks.org/events). - -* **SIP Editor**. SIP editors help SIP authors make sure their SIPs are well-formed and follow the right process. They help get SIPs ready for deep review by advancing it them from Draft to Accepted status. If you want to become a SIP editor, open an issue with your name and email to ask to be added to the list of SIP editors. - -* **Join a CAB** (Consideration Advisory Board). SIPs fall under the purview of one or more considerations. A full list is in [this github](https://github.com/stacksgov/sips/tree/main/considerations) directory. Currently they are: Diversity, Economics, Ethics, Governance and Technical. Members of SIP consideration advisory boards use their domain expertise to give Accepted SIPs a deep read, and give the authors any/all feedback to help make the SIP workable. If you want to join a board, reach out to the board's chairperson via the listed contact information. - -* **Steering Committee**. The Steering Committee organizes the consideration advisory boards and votes to advance Recommended SIPs to Activation-in-Progress status, and then to either Ratified or Rejected status. Once they are in the process of being activated, they use a SIP's Activation section to determine whether or not the Stacks ecosystem has ratified or rejected the SIP. Joining this committee requires the consent of the Stacks Foundation board. diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/intro.md b/i18n/zh/docusaurus-plugin-content-docs/current/intro.md deleted file mode 100644 index 84f1eaa649..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/intro.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -sidebar_label: "Home" -sidebar_position: 1 ---- - -# Stacks Docs Introduction - -Welcome to the community driven official Stacks Documentation. - -Learn about Stacks mining, the STX token, and the Clarity smart contract language. - -![](/img/Bitcoinet-L_2.svg) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md b/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md deleted file mode 100644 index 99aeac842b..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/digitalocean.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: 数码海洋上的应用 -description: A guide to setup Stacks on DigitalOcean -sidebar_position: 4 -tags: - - tutorial ---- - -## Introduction - -This is a step by step guide to deploy the [Stacks Blockchain on DigitalOcean](https://marketplace.digitalocean.com/apps/stacks-blockchain). Code is hosted on this [Github repository](https://github.com/stacks-network/stacks-blockchain-docker). Code is hosted on this [Github repository](https://github.com/stacks-network/stacks-blockchain-docker). Code is hosted on this [Github repository](https://github.com/stacks-network/stacks-blockchain-docker). - -## Steps - -#### Step 1 - -Go to the [Stacks Blockchain page](https://marketplace.digitalocean.com/apps/stacks-blockchain) in DigitalOcean's marketplace. Click on `Create Stacks Blockchain Droplet`. Click on `Create Stacks Blockchain Droplet`. Click on `Create Stacks Blockchain Droplet`. - -#### Step 2 - -Choose a plan (it will only allow you to select a plan that meets the minimum requirements) and your prefered datacenter region. ![](/img/sh_digitalocean-choose-plan.png) - -#### Step 3 - -Enter a root password or enable SSH keys if your prefer. - -![](/img/sh_digitalocean-choose-authentication.png) - -#### Step 4 - -You can leave the rest of the options as they are and click on `Create Droplet` - -#### Step 5 - -You will need to wait a few seconds for the droplet to get created. Once created click on it to see more information. Once created click on it to see more information. Once created click on it to see more information. - -![](/img/sh_digitalocean-creating-droplet.png) - -![](/img/sh_digitalocean-created-droplet.png) - -### Step 6 - -Congratulations! Congratulations! You are now running the Stacks Blockchain. Congratulations! You are now running the Stacks Blockchain. You can click on `Console` for a terminal window to open or login using SSH to the public IP you've been assigned to with user `root`. Congratulations! You are now running the Stacks Blockchain. You can click on `Console` for a terminal window to open or login using SSH to the public IP you've been assigned to with user `root`. - -![](/img/sh_digitalocean-console-button.png) ![](/img/sh_digitalocean-console.png) - -## Getting started after deploying Stacks Blockchain - -Once droplet is launched, initial startup can take several minutes while BNS data is imported (this is a one time operation). - -To keep track of the progress, you can `ssh root@your_droplet_public_ipv4` to the host and run: `/opt/stacks-blockchain-docker/manage.sh -n mainnet -a logs`. - -Once the stacks blockchain starts to sync with peers, application ports will open and nginx port 80 will now start proxying requests. - -Use `http://your_droplet_public_ipv4` to access the data directly, with output being similar to: - -```json -{ - "server_version": "stacks-blockchain-api v3.0.3 (master:cd0c8aef)", - "status": "ready", - "chain_tip": { - "block_height": 16220, - "block_hash": "0x3123fba9c0de6b569573494cf83c1d5d198a66bfd5f48ef97949b6bf11ba13be", - "index_block_hash": "0xeec960fbbd6186b4ccac85ce12adba72be497d881f81e077305c90955b51a6ae" - } -} -``` - -All services are managed by a [systemd unit file](https://github.com/stacksfoundation/stacks-machine-images/blob/master/files/etc/systemd/system/stacks.service) that is set to start on boot. - -Manual control is also possible via the [manage.sh script](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/manage.sh) at `/opt/stacks-blockchain-docker/manage.sh` on the host. - -Full details on how to use the manage.sh script is [available here](https://github.com/stacks-network/stacks-blockchain-docker/blob/master/README.md#quickstart). - -## API Creation - -In addition to creating a Droplet from the Stacks Blockchain 1-Click App via the control panel, you can also use the [DigitalOcean API](https://digitalocean.com/docs/api). - -As an example, to create a 4GB Stacks Blockchain Droplet in the SFO2 region, you can use the following curl command. You’ll need to either save your [API access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/) to an environment variable or substitute it into the command below. As an example, to create a 4GB Stacks Blockchain Droplet in the SFO2 region, you can use the following curl command. You’ll need to either save your [API access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/) to an environment variable or substitute it into the command below. You’ll need to either save your [API access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/) to an environment variable or substitute it into the command below. - -```bash -curl -X POST -H 'Content-Type: application/json' \ - -H 'Authorization: Bearer '$TOKEN'' -d \ - '{"name":"choose_a_name","region":"sfo2","size":"s-2vcpu-4gb","image":"stacksfoundation-stacksblockchain"}' \ - "https://api.digitalocean.com/v2/droplets" -``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md b/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md deleted file mode 100644 index b6cbb9754a..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Nodes and Miners -description: Nodes and Miners -sidebar_position: 7 ---- - -Here are all the steps to run nodes and miners, both on mainnet and testnet. - -## What's a Stacks node? - -## What's a Stacks miner? diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md b/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md deleted file mode 100644 index 40397a51e0..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-costs-and-fees.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Miner costs and fees -description: Miner Cost and Fee Estimation -sidebar_position: 8 ---- - -## Configuring Cost and Fee Estimation - -Fee and cost estimators can be configured via the config section `[fee_estimation]`: - -``` -[fee_estimation] -cost_estimator = naive_pessimistic -fee_estimator = fuzzed_weighted_median_fee_rate -fee_rate_fuzzer_fraction = 0.1 -fee_rate_window_size = 5 -cost_metric = proportion_dot_product -log_error = true -enabled = true -``` - -Fee and cost estimators observe transactions on the network and use the observed costs of those transactions to build estimates for viable fee rates and expected execution costs for transactions. Estimators and metrics can be selected using the configuration fields above, though the default values are the only options currently. `log_error` controls whether or not the INFO logger will display information about the cost estimator accuracy as new costs are observed. Setting `enabled = false` turns off the cost estimators. Cost estimators are **not** consensus-critical components, but rather can be used by miners to rank transactions in the mempool or client to determine appropriate fee rates for transactions before broadcasting them. - -The `fuzzed_weighted_median_fee_rate` uses a median estimate from a window of the fees paid in the last `fee_rate_window_size` blocks. Estimates are then randomly "fuzzed" using uniform random fuzz of size up to `fee_rate_fuzzer_fraction` of the base estimate. diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md b/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md deleted file mode 100644 index 751a5f87b7..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-mainnet.md +++ /dev/null @@ -1,434 +0,0 @@ ---- -title: Mine mainnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 mainnet -sidebar_position: 5 -tags: - - tutorial ---- - -## Introduction - -Make sure you've followed the [run a node](run-a-node) procedure. Once completed it's only a few more steps to run a proof-of-burn miner on the mainnet. - -If you're interested in mining on the testnet, you can find instructions on how to do that [here](miner-testnet): - -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining): - -## Running bitcoind locally - -To participate as a miner on mainnet, you must have access to a mainnet bitcoin node. One way to accomplish this is to run bitcoind locally. [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements) One way to accomplish this is to run bitcoind locally. [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements) One way to accomplish this is to run bitcoind locally. [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements) - -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. - -Next, start bitcoind with the following configuration: - -```toml -server=1 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=1 -banscore=1 -bind=0.0.0.0:8333 -rpcbind=0.0.0.0:8332 -rpcport=8332 -``` - -Finally, start bitcoind as follows: - -```bash -bitcoind -conf=path/to/bitcoin.conf -``` - -It may take a few days for the node to synchronize with the Bitcoin mainnet. - -## Running a miner - -First, a keychain needs to be generated. First, a keychain needs to be generated. With this keychain, we'll purchase some BTC from a crytpocurrency exchange, and then use that BTC to start mining. First, a keychain needs to be generated. With this keychain, we'll purchase some BTC from a crytpocurrency exchange, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. We'll use the `make_keychain` command. - -```bash -npx @stacks/cli make_keychain 2>/dev/null | json_pp > keychain.txt -``` - -After this runs, you should see some JSON in the new `keychain.txt` file that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -**Don't lose this information** - we'll need to use the `privateKey` field later on. - -The above BTC address will then need to be imported into the BTC network. - -```bash -bitcoin-cli -rpcport=8332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - - - -Once imported, we need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). Once imported, we need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). We need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - - - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/mainnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... - -[burnchain] -... -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `make_keychain` command. Replace the `seed` field with your private key. Save and close this configuration file. Replace the `seed` field with your private key. Save and close this configuration file. Replace the `seed` field with your private key. Save and close this configuration file. - -To run your miner, run this in the command line: - -```bash -stacks-node start --config=./testnet/stacks-node/conf/mainnet-miner-conf.toml -``` - -Your node should start. Your node should start. Your node should start. It will take some time to sync, and then your miner will be running. - -### Creating an optimized binary - -The steps above are great for trying to run a node temporarily. The steps above are great for trying to run a node temporarily. The steps above are great for trying to run a node temporarily. If you want to host a node on a server somewhere, you might want to generate an optimized binary. To do so, use the same configuration as above, but run: To do so, use the same configuration as above, but run: To do so, use the same configuration as above, but run: - -```bash -cd testnet/stacks-node -cargo build --release --bin stacks-node -``` - -The above code will compile an optimized binary. To use it, run: To use it, run: To use it, run: - -```bash -cd ../.. -cd ../.. -cd ../.. -./target/release/stacks-node start --config=./mainnet-miner-conf.toml -``` - -To read more about the technical details of mining on the Stacks 2.0 network, have a look at [the mining guide](../understand-stacks/mining). - -### Enable debug logging - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: In the command line, run: In the command line, run: - -```bash -STACKS_LOG_DEBUG=1 stacks-node mainnet -``` - -## Running a miner in Windows - -### Prerequisites - -Make sure are [running a node](run-a-node) and [running bitcoind locally](#running-bitcoind-locally) before starting this tutorial. - -### Generate keychain and get mainnet tokens in Windows - -To setup the miner, first we need to generate a keychain. With this keychain, we'll purchase some BTC from a crytpocurrency exchange, and then use that BTC to start mining. First, a keychain needs to be generated. With this keychain, we'll purchase some BTC from a crytpocurrency exchange, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. We'll use the `make_keychain` command. To get a keychain, the simplest way is to use the `stacks-cli`. We'll use the `make_keychain` command. To get a keychain, the simplest way is to use the `stacks-cli`. We'll use the `stx make-keychain` command. - -Generate a keychain: - -```bash -npm install --global @stacks/cli -stx make_keychain > cli_keychain.json -type cli_keychain.json -``` - -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -The above BTC address will then need to be imported into the BTC network. - -```bash -bitcoin-cli -rpcport=8332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - -Once imported, we need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). We need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Update configuration file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/mainnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... - -[burnchain] -... -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. Replace the seed field with your private key. Save and close this configuration file. Replace the seed field with your private key. Save and close this configuration file. - -### Run the miner - -To start your miner, run this in the command line: - -```bash -stacks-node start --config=testnet/stacks-node/conf/mainnet-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. -::: If so, allow access to run the node. -::: If so, allow access to run the node. -::: ![Windows Defender](/img/windows-defender.png) - -Your node should start. Your node should start. It will take some time to sync, and then your miner will be running. - -### Enable debug logging in Windows - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: In the command line, run: - -```bash -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=mainnet-miner-conf.toml -``` - -## Optional: Running with Docker - -Alternatively, you can run the mainnet node with Docker. - -:::caution Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: ::: ::: - -### Generate keychain and get tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null -``` - -We need to get some BTC to that address. We need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). Once imported, we need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). We need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Update configuration file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/mainnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/mainnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... - -[burnchain] -... -[node] -... -# Enter your private key here -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on mainnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. Replace the seed field with your private key. Save and close this configuration file. - -### Start the miner - -:::info The ENV VARS `RUST_BACKTRACE` and `STACKS_LOG_DEBUG` are optional. If removed, debug logs will be disabled ::: If removed, debug logs will be disabled ::: If removed, debug logs will be disabled ::: - -```bash -docker run -d \ - --name stacks_miner \ - --rm \ - --network host \ - -e RUST_BACKTRACE="full" \ - -e STACKS_LOG_DEBUG="1" \ - -v "$(pwd)/testnet/stacks-node/conf/mainnet-miner-conf.toml:/src/stacks-node/mainnet-miner-conf.toml" \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain:latest \ -/bin/stacks-node start --config /src/stacks-node/mainnet-miner-conf.toml -``` - -You can review the node logs with this command: - -```bash -docker logs -f stacks_miner -``` - -## Optional: Running in Kubernetes with Helm - -In addition, you're also able to run a mainnet node in a Kubernetes cluster using the [stacks-blockchain Helm chart](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). - -Ensure you have the following prerequisites installed on your machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [minikube](https://minikube.sigs.k8s.io/docs/start/) (Only needed if standing up a local Kubernetes cluster) -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [helm](https://helm.sh/docs/intro/install/) - -### Generate keychain and get some tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain 2>/dev/null -``` - -We need to get some BTC to that address. We need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). Once imported, we need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). We need to get some BTC to that address. You should be able to transfer BTC to this address using a crytpocurrency exchange such as [Coinbase](https://www.coinbase.com), [Binance](https://www.binance.com), or [Kraken](https://www.kraken.com). - -### Install the chart and run the miner - -To install the chart with the release name `my-release` and run the node as a miner: - -```bash -minikube start # Only run this if standing up a local Kubernetes cluster -helm repo add blockstack https://charts.blockstack.xyz -helm install my-release blockstack/stacks-blockchain \ - --set config.node.miner=true \ - --set config.node.seed="replace-with-your-privateKey-from-generate-keychain-step" \ - --set config.burnchain.mode="mainnet" -``` - -You can review the node logs with this command: - -```bash -kubectl logs -l app.kubernetes.io/name=stacks-blockchain -``` - -For more information on the Helm chart and configuration options, please refer to the [chart's homepage](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md b/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md deleted file mode 100644 index 7dc2ac76ca..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/miner-testnet.md +++ /dev/null @@ -1,420 +0,0 @@ ---- -title: Mine testnet Stacks tokens -description: Set up and run a miner on the Stacks 2.0 testnet -sidebar_position: 4 -tags: - - tutorial ---- - -## Introduction - -Make sure you've followed the [Run a node](run-a-node) procedure. Once completed it's only a few more steps to run a proof-of-burn miner on the testnet. - -If you want to learn more about the technical details of mining, please review the [mining guide](../understand-stacks/mining). - -## Running bitcoind locally - -To participate as a miner on Testnet, you must have access to a testnet bitcoin node. One way to accomplish this is to run bitcoind locally. [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements) One way to accomplish this is to run bitcoind locally. [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements) One way to accomplish this is to run bitcoind locally. [Ensure your computer meets the minimum hardware requirements before continuing.](https://bitcoin.org/en/bitcoin-core/features/requirements) - -First, download the bitcoind software for your platform from https://bitcoin.org/en/download. - -Next, start bitcoind with the following configuration: - -```toml -server=1 -rpcuser=your-bitcoind-username -rpcpassword=your-bitcoind-password -testnet=1 -txindex=0 -listen=1 -rpcserialversion=0 -maxorphantx=1 -banscore=1 - -[test] -bind=0.0.0.0:18333 -rpcbind=0.0.0.0:18332 -rpcport=18332 -``` - -Finally, start bitcoind as follows: - -```bash -bitcoind -conf=path/to/bitcoin.conf -``` - -It may take a few hours for the node to synchronize with the Bitcoin testnet. - -## Running a miner - -First, a keychain needs to be generated. First, a keychain needs to be generated. With this keychain, we'll purchase some BTC from a crytpocurrency exchange, and then use that BTC to start mining. First, a keychain needs to be generated. With this keychain, we'll get some testnet BTC from a faucet, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. To get a keychain, the simplest way is to use the `stacks-cli`. We'll use the `make_keychain` command, and pass `-t` to indicate that we want a testnet keychain. - -```bash -npx @stacks/cli make_keychain -t 2>/dev/null | json_pp > keychain.txt -``` - -After this runs, you should see some JSON in the new `keychain.txt` file that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -**Don't lose this information** - we'll need to use the `privateKey` field later on. - -The above BTC address will then need to be imported into the BTC testnet network. - -```bash -bitcoin-cli -rpcport=18332 -rpcuser=your-user -rpcpassword=your-password importaddress -``` - -Once imported, we need to get some testnet BTC to that address. Once imported, we need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). You'll be sent `0.01` testnet BTC to that address. You'll be sent `0.01` testnet BTC to that address. We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). You'll be sent 0.01 testnet BTC to that address. Once imported, we need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). You'll be sent `0.01` testnet BTC to that address. You'll be sent 0.01 testnet BTC to that address. You'll be sent `0.01` testnet BTC to that address. - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/testnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/testnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... - -[burnchain] -... -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `make_keychain` command. Replace the `seed` field with your private key. Save and close this configuration file. Replace the `seed` field with your private key. Save and close this configuration file. - -To run your miner, run this in the command line: - -```bash -stacks-node start --config=./testnet/stacks-node/conf/testnet-miner-conf.toml -``` - -Your node should start. Your node should start. It will take some time to sync, and then your miner will be running. - -### Creating an optimized binary - -The steps above are great for trying to run a node temporarily. The steps above are great for trying to run a node temporarily. If you want to host a node on a server somewhere, you might want to generate an optimized binary. To do so, use the same configuration as above, but run: To do so, use the same configuration as above, but run: - -```bash -cd testnet/stacks-node -cargo build --release --bin stacks-node -``` - -The above code will compile an optimized binary. To use it, run: To use it, run: - -```bash -cd ../.. -cd ../.. -cd ../.. -./target/release/stacks-node start --config=./testnet/conf/testnet-follower-conf.toml -``` - -To read more about the technical details of mining on the Stacks 2.0 network, have a look at [the minig guide](../understand-stacks/mining): - -### Enable debug logging - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: In the command line, run: - -```bash -STACKS_LOG_DEBUG=1 stacks-node testnet -``` - -## Running a miner in Windows - -### Prerequisites - -Make sure are [running a testnet node](run-a-node) before starting this tutorial. - -### Generate keychain and get testnet tokens in Windows - -To setup the miner, first, we need to generate a keychain. With this keychain, we'll get some testnet BTC from a faucet, and then use that BTC to start mining. First, a keychain needs to be generated. With this keychain, we'll get some testnet BTC from a faucet, and then use that BTC to start mining. - -To get a keychain, the simplest way is to use the `stacks-cli`. To get a keychain, the simplest way is to use the `stacks-cli`. To get a keychain, the simplest way is to use the `stacks-cli`. We'll use the `stx make-keychain` command, and pass `-t` to indicate that we want a testnet keychain. - -Generate a keychain: - -```bash -npm install --global @stacks/cli -stx make_keychain -t > cli_keychain.json -type cli_keychain.json -``` - -After this runs, you'll probably see some installation logs, and at the end you should see some JSON that looks like this: - -```json -{ - "mnemonic": "exhaust spin topic distance hole december impulse gate century absent breeze ostrich armed clerk oak peace want scrap auction sniff cradle siren blur blur", - "keyInfo": { - "privateKey": "2033269b55026ff2eddaf06d2e56938f7fd8e9d697af8fe0f857bb5962894d5801", - "address": "STTX57EGWW058FZ6WG3WS2YRBQ8HDFGBKEFBNXTF", - "btcAddress": "mkRYR7KkPB1wjxNjVz3HByqAvVz8c4B6ND", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -Request BTC from faucet: - -We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). You'll be sent 0.01 testnet BTC to that address. We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). You'll be sent 0.01 testnet BTC to that address. Once imported, we need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). You'll be sent `0.01` testnet BTC to that address. You'll be sent 0.01 testnet BTC to that address. You'll be sent 0.01 testnet BTC to that address. - -### Update configuration file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/testnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/testnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... - -[burnchain] -... -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. Replace the seed field with your private key. Save and close this configuration file. - -### Run the miner - -To start your miner, run this in the command line: - -```bash -stacks-node start --config=testnet/stacks-node/conf/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. -::: If so, allow access to run the node. -::: ![Windows Defender](/img/windows-defender.png) - - - -Your node should start. Your node should start. It will take some time to sync, and then your miner will be running. - -### Enable debug logging in Windows - -In case you are running into issues or would like to see verbose logging, you can run your node with debug logging enabled. In the command line, run: In the command line, run: - -```bash -set RUST_BACKTRACE=full; -set STACKS_LOG_DEBUG=1; -stacks-node start --config=testnet-miner-conf.toml -``` - -## Optional: Running with Docker - -Alternatively, you can run the testnet node with Docker. - -:::warning Ensure you have [Docker](https://docs.docker.com/get-docker/) installed on your machine. ::: ::: ::: - -### Generate keychain and get testnet tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` - -We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). You'll be sent 0.01 testnet BTC to that address. We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). You'll be sent 0.01 testnet BTC to that address. Once imported, we need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). You'll be sent `0.01` testnet BTC to that address. You'll be sent 0.01 testnet BTC to that address. You'll be sent 0.01 testnet BTC to that address. - -### Update config file - -Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. Now, we need to configure our node to use this Bitcoin keychain. Clone the [stacks-blockchain repository](https://github.com/stacks-network/stacks-blockchain) to your local machine if you haven't already. In the `stacks-blockchain` folder, modify the file at [`testnet/stacks-node/conf/testnet-miner-conf.toml`](https://github.com/stacks-network/stacks-blockchain/blob/master/testnet/stacks-node/conf/testnet-miner-conf.toml). - -Update the following properties: - -```toml -[node] -... -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... - -[burnchain] -... -[node] -... -seed = "replace-with-your-private-key" -local_peer_seed = "replace-with-your-private-key" -... - -[burnchain] -... -# To mine on Testnet, you need to run bitcoind locally -# Details can be found in above section, 'Running bitcoind locally' -peer_host = "127.0.0.1" -username = "" -password = "" -... -``` - -Now, grab your `privateKey` from earlier, when you ran the `stx make_keychain` command. Replace the seed field with your private key. Save and close this configuration file. Replace the seed field with your private key. Save and close this configuration file. - -### Start the miner - -:::info The ENV VARS `RUST_BACKTRACE` and `STACKS_LOG_DEBUG` are optional. If removed, debug logs will be disabled ::: If removed, debug logs will be disabled ::: - -```bash -docker run -d \ - --name stacks_miner \ - --rm \ - --network host \ - -e RUST_BACKTRACE="full" \ - -e STACKS_LOG_DEBUG="1" \ - -v "$(pwd))/testnet/stacks-node/conf/testnet-miner-conf.toml:/src/stacks-node/testnet-miner-conf.toml" \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain:latest \ -/bin/stacks-node start --config /src/stacks-node/testnet-miner-conf.toml -``` - -You can review the node logs with this command: - -```bash -docker logs -f stacks_miner -``` - -## Optional: Running in Kubernetes with Helm - -In addition, you're also able to run a testnet node in a Kubernetes cluster using the [stacks-blockchain Helm chart](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). - -Ensure you have the following prerequisites installed on your machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [minikube](https://minikube.sigs.k8s.io/docs/start/) (Only needed if standing up a local Kubernetes cluster) -- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) -- [helm](https://helm.sh/docs/intro/install/) - -### Generate keychain and get some testnet tokens - -Generate a keychain: - -```bash -docker run -i node:14-alpine npx @stacks/cli make_keychain -t 2>/dev/null -``` - -We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). You'll be sent 0.01 testnet BTC to that address. We need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). You'll be sent 0.01 testnet BTC to that address. Once imported, we need to get some testnet BTC to that address. Grab the `btcAddress` field, and paste it into [this Bitcoin testnet faucet](https://tbtc.bitaps.com/). You'll be sent `0.01` testnet BTC to that address. You'll be sent 0.01 testnet BTC to that address. You'll be sent 0.01 testnet BTC to that address. - -### Install the chart and run the miner - -To install the chart with the release name `my-release` and run the node as a miner: - -```bash -minikube start # Only run this if standing up a local Kubernetes cluster -helm repo add blockstack https://charts.blockstack.xyz -helm install my-release blockstack/stacks-blockchain \ - --set config.node.miner=true \ - --set config.node.seed="replace-with-your-privateKey-from-generate-keychain-step" -``` - -You can review the node logs with this command: - -```bash -kubectl logs -l app.kubernetes.io/name=stacks-blockchain -``` - -For more information on the Helm chart and configuration options, please refer to the [chart's homepage](https://github.com/stacks-network/stacks-blockchain/tree/master/deployment/helm/stacks-blockchain). diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md b/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md deleted file mode 100644 index 94d938c5ca..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/run-a-node.md +++ /dev/null @@ -1,351 +0,0 @@ ---- -title: Run a node -description: Set up and run a Stacks node -sidebar_position: 1 -tags: - - tutorial ---- - -## Stacks Blockchain with Docker - -Run your own Stacks Blockchain node easily with just few commands. - -This tutorial describes a simple and effective [quickstart](#quickstart) to run a Stacks node using public scripts hosted in [Stacks Blockchain repository](https://github.com/stacks-network/stacks-blockchain-docker). Valid for mainnet, testnet and mocknet. - -## **Quickstart** - -1. **Clone the stacks-blockchain-docker repository locally** - -```bash -git clone https://github.com/stacks-network/stacks-blockchain-docker && cd stacks-blockchain-docker -``` - -2. **Optionally, create/copy `.env` file**. If file `.env` doesn't exist when launched it will be created from `sample.env` automatically. - -```bash -cp sample.env .env -``` - -_You may also use a symlink as an alternative to copying: `ln -s sample.env .env`_ - -3. **Optionally, ensure all images are up to date** - -```bash -./manage.sh -n -a pull -``` - -4. **Start the Services** - -```bash -./manage.sh -n -a start -``` - -- With optional proxy: - -```bash -./manage.sh -n -a start -f proxy -``` - -- With optional bitcoin node: - -```bash -./manage.sh -n -a start -f bitcoin -``` - -5. **Stop the Services** - -```bash -./manage.sh -n -a stop -``` - -6. **Retrieve Service Logs** - -```bash -./manage.sh -n -a logs -``` - -- Export docker log files to `./exported-logs`: - -This will create one log file for every running service, for example: postgres.log, stacks-blockain.log, stacks-blockchain-api.log and bitcoin-core.log. -Notice that each time you run this command the log files will be overwritten. - -```bash -./manage.sh -n -a logs export -``` - -7. **Restart all services** - -```bash -./manage.sh -n -a restart -``` - -- With optional proxy: - -```bash -./manage.sh -n -a restart -f proxy -``` - -8. **Delete** all data in `./persistent-data/` and/or data of the Bitcoin blockchain. - - This data is owned by root, so you will need to run it with sudo privileges so it can delete the data. - -```bash -$ sudo ./manage.sh -n -a reset - -Please confirm what persistent data you wish to delete: - -0. Cancel -1. Delete Persistent data for Stacks testnet only and leave Bitcoin blockchain data unaffected. -2. Delete Persistent data for Stacks testnet and Bitcoin blockchain data in ./persistent-data/blockchain-bitcoin -3. Delete Persistent data for Bitcoin blockchain data in ./persistent-data/blockchain-bitcoin only. -Please note that BNS data will never get deleted. - -Type 0, 1, 2 or 3: 2 - -Ok. Delete Stacks and Bitcoin data. -[ Success ] Persistent data deleted for Bitcoin blockchain. -[ Success ] Persistent data deleted for Stacks testnet. - -``` - -9. **Download BNS data to** `./persistent-data/bns-data` - -```bash -./manage.sh bns -``` - -10. **Export stacks-blockchain-api events** (_Not applicable for mocknet_) - -```bash -./manage.sh -n -a export -# check logs for completion -./manage.sh -n -a restart -``` - -11. **Replay stacks-blockchain-api events** (_Not applicable for mocknet_) - -```bash -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart -``` - -## **Running also a bitcoin node (Optional)** - -Stacks needs to use a Bitcoin node, and by default when you run a Stacks node you will be using a public Bitcoin node, which is configured in the `.env` file. Default values is `BITCOIN_NODE=bitcoin.mainnet.stacks.org`. - -However, you can optionaly run both nodes together and configured in a way that you Stacks node will use your own Bitcoin node instead of a public one. - -If you run the script with a bitcoin node it will download and build it directly from source for increased security. This process which only needs to happen once can take up to 20-30 minutes depending on the speed of your system. Also, once the bitcoin node is up and running it will need an additional time for sync for the first time (can be hours for testnet and days for mainnet). - -### Why run Stacks node with your own Bitcoin node? - -Because running your own Bitcoin node will give you higher security and improved perfomance. - -* **Improved perfomance**: The Bitcoin node will serve you blocks faster, as well as UTXOs for your miner (if you run one). -* **Higher security**: The Bitcoin node will also have validated all bitcoin transactions the Stacks node consumes. If you don't run your own Bitcoin node, you're relying on the SPV headers to vouch for the validity of Bitcoin blocks. - -The disadvantage of running your own Bitcoin node is that you need the extra space to store the Bitcoin blockchain (about 500GB) and the initial time it will take to download this data the first time. - -### Example - -You can run easily run your Stacks node with your own Bitcoin node by adding the flag `bitcoin`. This is available only for testnet and mainnet. - -Example: `./manage.sh -n mainnet -a start -f bitcoin` or `./manage.sh -n testnet -a start -f bitcoin` - -### Bitcoin node configuration - -In the `.env` file there is the variable `BITCOIN_BLOCKCHAIN_FOLDER`. As the bitcoin blockchain can be large (over 500GB) you optionally change this variable to any location of your choosing. If you have previously used the [bitcoin core application](https://bitcoin.org/en/bitcoin-core/) and already have the bitcoin blockchain synced, you can use the same data folder and avoid redownloading the entire bitcoin blockchain. - -## **Accessing the services** - -:::tip For networks other than `mocknet`, downloading the initial headers can take several minutes. Until the headers are downloaded, the `/v2/info` endpoints won't return any data. - -Use the command `./manage.sh -n -a logs` to check the sync progress. ::: - -**stacks-blockchain**: - -- Ports `20443-20444` are exposed to `localhost` - -```bash -curl -sL localhost:20443/v2/info | jq -``` - -**stacks-blockchain-api**: - -- Port `3999` are exposed to `localhost` - -```bash -curl -sL localhost:3999/v2/info | jq -``` - -**proxy**: - -- Port `80` is exposed to `localhost` - -```bash -curl -sL localhost/v2/info | jq -curl -sL localhost/ | jq -``` - ---- - -## Upgrades - -⚠️ For upgrades to running instances of this repo, you'll need to [run the event-replay](https://github.com/hirosystems/stacks-blockchain-api#event-replay): - -```bash -./manage.sh -n -a stop -./manage.sh -n -a export -./manage.sh -n -a import -./manage.sh -n -a restart -``` - ---- - -## **Workarounds to potential issues** - -_**Port(s) already in use**_: - -- 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. `3999` and edit your `.env` file to use the new port. - -```bash -netstat -anl | grep 3999 -``` - -``` -tcp46 0 0 *.3999 *.* LISTEN -``` - -_**Containers not starting (hanging on start)**_: - -- Occasionally, docker can get **stuck** and not allow new containers to start. If this happens, simply restart your docker daemon and try again. - -_**Database Issues**_: - -- For any of the various Postgres/sync issues, it may be easier to simply remove the persistent data dir. Note that doing so will result in a longer startup time as the data is repopulated. - -```bash -./manage.sh -n -a stop -./manage.sh -n -a reset -./manage.sh -n -a start -``` - -_**API Missing Parent Block Error**_: - -- If the Stacks blockchain is no longer syncing blocks, and the API reports an error similar to this:\ - `Error processing core node block message DB does not contain a parent block at height 1970 with index_hash 0x3367f1abe0ee35b10e77fbcaa00d3ca452355478068a0662ec492bb30ee0f13e"`,\ - The API (and by extension the DB) is out of sync with the blockchain. \ - The only known method to recover is to resync from genesis (**event-replay _may_ work, but in all likelihood will restore data to the same broken state**). - -- To attempt the event-replay - -```bash -./manage.sh -n -a stop -./manage.sh -n -a import -# check logs for completion -./manage.sh -n -a restart -``` - -- To wipe data and re-sync from genesis - -```bash -./manage.sh -n -a stop -./manage.sh -n -a reset -./manage.sh -n -a restart -``` - - -## **Requirements:** - -- [Docker](https://docs.docker.com/get-docker/) >= `17.09` -- [docker-compose](https://github.com/docker/compose/releases/) >= `1.27.4` -- [git](https://git-scm.com/downloads) -- [jq binary](https://stedolan.github.io/jq/download/) -- [sed](https://www.gnu.org/software/sed/) -- Machine with (at a minimum): - - 4GB memory - - 1 Vcpu - - 50GB storage (600GB if you optionally also run the bitcoin mainnet node) - -:::caution MacOS with an M1 processor is NOT recommended - -The way Docker for Mac on an Arm chip is designed makes the I/O incredibly slow, and blockchains are **_very_** heavy on I/O. This only seems to affect MacOS, other Arm based systems like Raspberry Pi's seem to work fine. - -::: - - -### Install/Update docker-compose - -:::note `docker-compose` executable is required, even though recent versions of Docker contain `compose` natively ::: - -- [Install Docker-compose](https://docs.docker.com/compose/install/) -- [Docker Desktop for Mac](https://docs.docker.com/docker-for-mac/install/) -- [Docker Desktop for Windows](https://docs.docker.com/docker-for-windows/install/) -- [Docker Engine for Linux](https://docs.docker.com/engine/install/#server) - -First, check if you have `docker-compose` installed locally. - -To do that, run this command in your terminal : - -```bash -docker-compose --version -``` - -Output should look something very similar to this : - -``` -docker-compose version 1.27.4, build 40524192 -``` - -If the command is not found, or the version is < `1.27.4`, run the following to install the latest to `/usr/local/bin/docker-compose`: - -```bash -#You will need to have jq installed, or this snippet won't run. -VERSION=$(curl --silent https://api.github.com/repos/docker/compose/releases/latest | jq .name -r) -DESTINATION=/usr/local/bin/docker-compose -sudo curl -L https://github.com/docker/compose/releases/download/${VERSION}/docker-compose-$(uname -s)-$(uname -m) -o $DESTINATION -sudo chmod 755 $DESTINATION -``` - -### Security note on docker - -The Docker daemon always runs as the root user so by default you will need root privileges to interact with it. - -The script `manage.sh` uses docker, so to avoid the requirement of needing to run the script with root privileges it is prefered to be able to *manage Docker as a non-root user*, following [these simple tests](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user). - -This will avoid the need of running the script with root privileges for all operations except the removal of data. - -### Configuration files you can edit - -The following files can be modified to personalize your node configuration, but generally most of them should be left as-is. All these files will be created from the sample copy if they don't exist at runtime (for example `.env` is created from `sample.env`). However these files will never be modified by the application once created and will never be pushed back to github, so your changes will be safe. - -* `.env` -* `./conf/mainnet/Config.toml` -* `./conf/mainnet/bitcoin.conf` -* `./conf/testnet/Config.toml` -* `./conf/testnet/bitcoin.conf` - -By default: - -- BNS data is **not** enabled/imported - - To enable, uncomment `# BNS_IMPORT_DIR=/bns-data` in `./env` - - Download BNS data: `./manage.sh bns` -- Fungible token metadata is **not** enabled - - To enable, uncomment `# STACKS_API_ENABLE_FT_METADATA=1` in `./env` -- Non-Fungible token metadata is **not** enabled - - To enable, uncomment `# STACKS_API_ENABLE_NFT_METADATA=1` in `./env` -- Verbose logging is **not** enabled - - To enable, uncomment `# VERBOSE=true` in `./env` -- Bitcoin blockchain folder is configured in `BITCOIN_BLOCKCHAIN_FOLDER` in `./env` - -### Local Data Dirs - -Directories will be created on first start that will store persistent data under `./persistent-data/` - -`` can be 1 of: - -- mainnet -- testnet -- mocknet diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md b/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md deleted file mode 100644 index f4dfc90a4f..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/running-mainnet-node.md +++ /dev/null @@ -1,190 +0,0 @@ ---- -title: Running a mainnet node -description: Set up and run a mainnet node with Docker -sidebar_position: 3 -tags: - - tutorial ---- - -## Introduction - -This procedure demonstrates how to run a local mainnet node using Docker images. - -:::caution -This procedure focuses on Unix-like operating systems (Linux and MacOS). This procedure has not been tested on Windows. -::: This procedure has not been tested on Windows. -::: This procedure has not been tested on Windows. -::: - -## Prerequisites - -Running a node has no specialized hardware requirements. Running a node has no specialized hardware requirements. Users have been successful in running nodes on Raspberry Pi boards and other system-on-chip architectures. In order to complete this procedure, you must have the following software installed on the node host machine: In order to complete this procedure, you must have the following software installed on the node host machine: Running a node has no specialized hardware requirements. Users have been successful in running nodes on Raspberry Pi boards and other system-on-chip architectures. In order to complete this procedure, you must have the following software installed on the node host machine: In order to complete this procedure, you must have the following software installed on the node host machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [curl](https://curl.se/download.html) -- [jq](https://stedolan.github.io/jq/download/) - -### Firewall configuration - -In order for the API node services to work correctly, you must configure any network firewall rules to allow traffic on the ports discussed in this section. The details of network and firewall configuration are highly specific to your machine and network, so a detailed example isn't provided. The details of network and firewall configuration are highly specific to your machine and network, so a detailed example isn't provided. The details of network and firewall configuration are highly specific to your machine and network, so a detailed example isn't provided. - -The following ports must open on the host machine: - -Ingress: - -- stacks-blockchain (open to `0.0.0.0/0`): - - `20443 TCP` - - `20444 TCP` - -Egress: - -- `8332` -- `8333` -- `20443-20444` - -These egress ports are for syncing stacks-blockchain and Bitcoin headers. If they're not open, the sync will fail. If they're not open, the sync will fail. - -## Step 1: initial setup - -In order to run the mainnet node, you must download the Docker images and create a directory structure to hold the persistent data from the services. Download and configure the Docker images with the following commands: Download and configure the Docker images with the following commands: Download and configure the Docker images with the following commands: - -```sh -docker pull blockstack/stacks-blockchain -``` - -Create a directory structure for the service data with the following command: - -```sh -mkdir -p ./stacks-node/{persistent-data/stacks-blockchain/mainnet,config/mainnet} && cd stacks-node -``` - -## Step 2: running Stacks blockchain - -First, create the `./config/mainnet/Config.toml` file and add the following content to the file using a text editor: - -```toml -[node] -working_dir = "/root/stacks-node/data" -rpc_bind = "0.0.0.0:20443" -p2p_bind = "0.0.0.0:20444" -bootstrap_node = "02da7a464ac770ae8337a343670778b93410f2f3fef6bea98dd1c3e9224459d36b@seed-0.mainnet.stacks.co:20444,02afeae522aab5f8c99a00ddf75fbcb4a641e052dd48836408d9cf437344b63516@seed-1.mainnet.stacks.co:20444,03652212ea76be0ed4cd83a25c06e57819993029a7b9999f7d63c36340b34a4e62@seed-2.mainnet.stacks.co:20444" -wait_time_for_microblocks = 10000 - -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "bitcoin.blockstack.com" -username = "blockstack" -password = "blockstacksystem" -rpc_port = 8332 -peer_port = 8333 - -[connection_options] -read_only_call_limit_write_length = 0 -read_only_call_limit_read_length = 100000 -read_only_call_limit_write_count = 0 -read_only_call_limit_read_count = 30 -read_only_call_limit_runtime = 1000000000 -``` - -Start the `stacks-blockchain` container with the following command: - -```sh -docker run -d --rm \ - --name stacks-blockchain \ - -v $(pwd)/persistent-data/stacks-blockchain/mainnet:/root/stacks-node/data \ - -v $(pwd)/config/mainnet:/src/stacks-node \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain \ -/bin/stacks-node start --config /src/stacks-node/Config.toml -``` - -You can verify the running `stacks-blockchain` container with the command: - -```sh -docker ps --filter name=stacks-blockchain -``` - -## Step 3: verifying the services - -:::note -The initial burnchain header sync can take several minutes, until this is done the following commands will not work -::: - -To verify the `stacks-blockchain` burnchain header sync progress: - -```sh -docker logs stacks-blockchain -``` - -The output should be similar to the following: - -``` -INFO [1626290705.886954] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.2% (8000 out of 691034) -INFO [1626290748.103291] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.4% (10000 out of 691034) -INFO [1626290776.956535] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.7% (12000 out of 691034) -``` - -To verify the `stacks-blockchain` tip height is progressing use the following command: - -```sh -curl -sL localhost:20443/v2/info | jq -``` - -If the instance is running you should recieve terminal output similar to the following: - -```json -{ - "peer_version": 402653184, - "pox_consensus": "89d752034e73ed10d3b97e6bcf3cff53367b4166", - "burn_block_height": 666143, - "stable_pox_consensus": "707f26d9d0d1b4c62881a093c99f9232bc74e744", - "stable_burn_block_height": 666136, - "server_version": "stacks-node 2.0.11.1.0-rc1 (master:67dccdf, release build, linux [x86_64])", - "network_id": 1, - "parent_network_id": 3652501241, - "stacks_tip_height": 61, - "stacks_tip": "e08b2fe3dce36fd6d015c2a839c8eb0885cbe29119c1e2a581f75bc5814bce6f", - "stacks_tip_consensus_hash": "ad9f4cb6155a5b4f5dcb719d0f6bee043038bc63", - "genesis_chainstate_hash": "74237aa39aa50a83de11a4f53e9d3bb7d43461d1de9873f402e5453ae60bc59b", - "unanchored_tip": "74d172df8f8934b468c5b0af2efdefe938e9848772d69bcaeffcfe1d6c6ef041", - "unanchored_seq": 0, - "exit_at_block_height": null -} -``` - -## Stopping the mainnet node - -Use the following commands to stop the local mainnet node: - -```sh -docker stop stacks-blockchain -``` - -## Optional. Optional. Optional. Run stacks node with own bitcoin node - -It's encouraged to use your own bitcoin node when possible. - -To do this simply update the `stacks-node/config/mainnet/Config.toml` file with the details of your bitcoin node. For example: For example: For example: - -``` -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "localhost" -username = "rpc username" -password = "rpc password" -rpc_port = 8332 -peer_port = 8333 -``` - -The rpc configuration of your bitcoin node is out of the scope of this document, but you can find more information on how to set it up [here](https://developer.bitcoin.org/examples/intro.html). - -## Additional reading - - - -- [Running a Stacks API node](https://docs.hiro.so/get-started/running-api-node) -- [Running a Stacks testnet node](running-testnet-node) - diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md b/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md deleted file mode 100644 index 1932c35831..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/running-testnet-node.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: Running a testnet node -description: Set up and run a testnet node with Docker -sidebar_position: 2 -tags: - - tutorial ---- - -## Introduction - -This procedure demonstrates how to run a local testnet node using Docker images. - -:::caution -This procedure focuses on Unix-like operating systems (Linux and MacOS). This procedure has not been tested on Windows. -::: This procedure has not been tested on Windows. -::: This procedure has not been tested on Windows. -::: - -## Prerequisites - -Running a node has no specialized hardware requirements. Running a node has no specialized hardware requirements. Users have been successful in running nodes on Raspberry Pi boards and other system-on-chip architectures. In order to complete this procedure, you must have the following software installed on the node host machine: In order to complete this procedure, you must have the following software installed on the node host machine: Running a node has no specialized hardware requirements. Users have been successful in running nodes on Raspberry Pi boards and other system-on-chip architectures. In order to complete this procedure, you must have the following software installed on the node host machine: In order to complete this procedure, you must have the following software installed on the node host machine: - -- [Docker](https://docs.docker.com/get-docker/) -- [curl](https://curl.se/download.html) -- [jq](https://stedolan.github.io/jq/download/) - -### Firewall configuration - -In order for the API node services to work correctly, you must configure any network firewall rules to allow traffic on the ports discussed in this section. The details of network and firewall configuration are highly specific to your machine and network, so a detailed example isn't provided. The details of network and firewall configuration are highly specific to your machine and network, so a detailed example isn't provided. - -The following ports must open on the host machine: - -Ingress: - -- stacks-blockchain (open to `0.0.0.0/0`): - - `20443 TCP` - - `20444 TCP` - -Egress: - -- `18332` -- `18333` -- `20443-20444` - -These egress ports are for syncing stacks-blockchain and Bitcoin headers. If they're not open, the sync will fail. If they're not open, the sync will fail. - -## Step 1: initial setup - -In order to run the testnet node, you must download the Docker images and create a directory structure to hold the persistent data from the services. Download and configure the Docker images with the following commands: Download and configure the Docker images with the following commands: Download and configure the Docker images with the following commands: - -```sh -docker pull blockstack/stacks-blockchain -``` - -Create a directory structure for the service data with the following command: - -```sh -mkdir -p ./stacks-node/persistent-data/stacks-blockchain/testnet && cd stacks-node -``` - -## Step 2: running Stacks blockchain - -Start the stacks-blockchain container with the following command: - -```sh -docker run -d --rm \ - --name stacks-blockchain \ - -v $(pwd)/persistent-data/stacks-blockchain/testnet:/root/stacks-node/data \ - -p 20443:20443 \ - -p 20444:20444 \ - blockstack/stacks-blockchain \ -/bin/stacks-node testnet -``` - -You can verify the running stacks-blockchain container with the command: - -```sh -docker ps --filter name=stacks-blockchain -``` - -## Step 3: verifying the services - -:::info -The initial burnchain header sync can take several minutes, until this is done the following commands will not work -::: - -To verify the stacks-blockchain burnchain header sync progress: - -```sh -docker logs stacks-blockchain -``` - -The output should be similar to the following: - -``` -INFO [1626290705.886954] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.2% (8000 out of 2034380) -INFO [1626290748.103291] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.4% (10000 out of 2034380) -INFO [1626290776.956535] [src/burnchains/bitcoin/spv.rs:926] [main] Syncing Bitcoin headers: 1.7% (12000 out of 2034380) -``` - -To verify the stacks-blockchain tip height is progressing use the following command: - -```sh -curl -sL localhost:20443/v2/info | jq -``` - -If the instance is running you should recieve terminal output similar to the following: - -```json -{ - "peer_version": 4207599105, - "pox_consensus": "12f7fa85e5099755a00b7eaecded1aa27af61748", - "burn_block_height": 2034380, - "stable_pox_consensus": "5cc4e0403ff6a1a4bd17dae9600c7c13d0b10bdf", - "stable_burn_block_height": 2034373, - "server_version": "stacks-node 2.0.11.2.0-rc1 (develop:7b6d3ee+, release build, linux [x86_64])", - "network_id": 2147483648, - "parent_network_id": 118034699, - "stacks_tip_height": 509, - "stacks_tip": "e0ee952e9891709d196080ca638ad07e6146d4c362e6afe4bb46f42d5fe584e8", - "stacks_tip_consensus_hash": "12f7fa85e5099755a00b7eaecded1aa27af61748", - "genesis_chainstate_hash": "74237aa39aa50a83de11a4f53e9d3bb7d43461d1de9873f402e5453ae60bc59b", - "unanchored_tip": "32bc86590f11504f17904ee7f5cb05bcf71a68a35f0bb3bc2d31aca726090842", - "unanchored_seq": 0, - "exit_at_block_height": null -} -``` - -## Stopping the testnet node - -Use the following commands to stop the local testnet node: - -```sh -docker stop stacks-blockchain -``` - -## Additional reading - - - -- [Running a Stacks API node](https://docs.hiro.so/get-started/running-api-node) -- [Running a Stacks mainnet node](running-mainnet-node) - diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md b/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md deleted file mode 100644 index ea9a1e45d3..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/stacks-node-configuration.md +++ /dev/null @@ -1,507 +0,0 @@ ---- -title: Stacks Node Configuration -description: Configuration parameters and options for the stacks-node binary -sidebar_position: 6 ---- - -## Usage - -```bash -stacks-node sub-command [--subcommand-option ] -``` - -## Subcommands - -:::caution The `stacks-node` binary may have deprecated commands that are not documented on this page. Deprecated commands may be accessible until they are fully removed from the sources. ::: - -### mocknet - -Start a node based on a fast local setup emulating a burnchain. Ideal for smart contract development. Ideal for smart contract development. Ideal for smart contract development. - -Example: - -```bash -stacks-node mocknet -``` - -### krypton - -Start a node that will join and stream blocks from the public krypton regtest, powered by Blockstack via [Proof of Transfer](../understand-stacks#consensus-mechanism). sidebar_position: 1 sidebar_position: 1 - -Example: - -```bash -stacks-node krypton -``` - -### testnet - -Start a node that will join and stream blocks from the public testnet. - -Example: - -```bash -stacks-node testnet -``` - -### mainnet - -Start a node that joins and streams blocks from the public mainnet. - -Example: - -```bash -stacks-node mainnet -``` - -### start - -Start a node with a config of your own. Start a node with a config of your own. Start a node with a config of your own. Can be used for joining a network, starting a new chain, or replacing default values used by the `mocknet` or `testnet` subcommands. - -#### Arguments - -**--config**: relative or absolute path to the TOML config file. Required. Required. Required. - -Example: - -```bash -stacks-node start --config=/path/to/config.toml -``` - -See [Configuration File Options](#configuration-file-options) for more information. - -#### version - -Displays information about the current version and the release cycle. - -Example: - -```bash -stacks-node version -``` - -#### help - -Displays a help message. - -Example: - -```bash -stacks-node help -``` - -## Configuration File Options - -The TOML configuration file has multiple sections under which an option may be placed. - -To see a list of example configurations, [please see this page](https://github.com/stacks-network/stacks-blockchain/tree/master/testnet/stacks-node/conf). - -### Section: node - -Contains various configuration options pertaining to the stacks-node. - -Example: - -```toml -[node] -rpc_bind = "0.0.0.0:20443" -p2p_bind = "0.0.0.0:20444" -# Enter your private key here -seed = "replace-with-your-private-key" -miner = true -``` - -#### working_dir (optional) - -Absolute path to the directory which the stacks-node will use for storing various data. - -Example: - -```toml -working_dir = "/root/stacks-node" -``` - -#### rpc_bind - -Address and port stacks-node should bind to for RPC connections. - -Example: - -```toml -rpc_bind = "0.0.0.0:20443" -``` - -#### p2p_bind - -Address and port stacks-node should bind to for P2P connections. - -Example: - -```toml -p2p_bind = "0.0.0.0:20444" -``` - -#### data_url (optional) - -Address and port from which the stacks-node will be receiving incoming rpc connections. - -Example: - -```toml -data_url = "1.2.3.4:20443" -``` - -#### p2p_address (optional) - -Address and port from which the stacks-node will be receiving incoming p2p connections. - -Example: - -```toml -p2p_address = "1.2.3.4:20444" -``` - -#### bootstrap_node (optional) - -Public key, address, and port stacks-node should use to pull transaction data from when starting. - -Example: - -```toml -bootstrap_node = "047435c194e9b01b3d7f7a2802d6684a3af68d05bbf4ec8f17021980d777691f1d51651f7f1d566532c804da506c117bbf79ad62eea81213ba58f8808b4d9504ad@testnet.blockstack.org:20444" -``` - -#### wait_time_for_microblocks (optional) - -The amount of time (in milliseconds) that a node will wait before trying to mine a block, after catching up to the anchored chain tip. This gives the current leader time to broadcast microblocks that will get included in that mined block. This gives the current leader time to broadcast microblocks that will get included in that mined block. This gives the current leader time to broadcast microblocks that will get included in that mined block. - -Example: - -```toml -wait_time_for_microblocks = 15000 -``` - -#### seed (optional) - -The private key to use for mining. The private key to use for mining. Only needed if `miner` is set to `true`. The private key to use for mining. Only needed if `miner` is set to `true`. - -Example: - -```toml -seed = "replace-with-your-private-key" -``` - -#### local_peer_seed (optional) - -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. It differentiates network peers and is used even by non-mining nodes. It differentiates network peers and is used even by non-mining nodes. - -Example: - -```toml -local_peer_seed = "replace-with-your-private-key" -``` - -#### miner (optional) - -Determines whether the stacks-node is running a follower (`false`) or a miner (`true`). Defaults to `false` if omitted. Defaults to `false` if omitted. Defaults to `false` if omitted. - -Example: - -```toml -miner = true -``` - -#### mine_microblocks (optional) - -Determines whether the stacks-node will mine microblocks. Determines whether the stacks-node will mine microblocks. Will only take effect if `miner` is set to `true`. Determines whether the stacks-node will mine microblocks. Will only take effect if `miner` is set to `true`. - -Example: - -```toml -mine_microblocks = true -``` - -#### prometheus_bind (optional) - -Address and port stacks-node should open for Prometheus metrics collection. - -Example: - -```toml -prometheus_bind = "0.0.0.0:9153" -``` - -### Section: events_observer (optional) - -Contains options for watching events emitted by a local [stacks-blockchain-api](https://github.com/hirosystems/stacks-blockchain-api) service. - -:::info -This section can be repeated multiple times. -::: ::: -::: - -Example: - -```toml -[[events_observer]] -endpoint = "address-to-my-local.stacks-node-api.com:3700" -retry_count = 255 -events_keys = ["*"] -``` - -#### endpoint - -Address and port to a stacks-node-api to watch for events. - -Example: - -```toml -endpoint = "address-to-my-local.stacks-node-api.com:3700" -``` - -#### retry_count - -Number of times to retry sending events to the endpoint before failing. - -Example: - -```toml -retry_count = 255 -``` - -#### events_keys - -Event keys for which to watch. Event keys for which to watch. The emitted node events can be restricted by account, function name and event type. Asterix ("\*") can be used to emit all events. Event keys for which to watch. Event keys for which to watch. The emitted node events can be restricted by account, function name and event type. Asterix ("\*") can be used to emit all events. Asterix ("\*") can be used to emit all events. - -Examples: - -```toml -events_keys = ["*"] -``` - -```toml -events_keys = [ - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.store::print", - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.contract.ft-token", - "STGT7GSMZG7EA0TS6MVSKT5JC1DCDFGZWJJZXN8A.contract.nft-token", - "stx" -] -``` - -### Section: connection_options (optional) - -Specifies configuration options for others connecting to the stacks node. - -Example: - -```toml -[connection_options] -public_ip_address = "1.2.3.4:20444" -download_interval = 60 -walk_interval = 30 -``` - -#### public_ip_address - -The advertised public IP of this stacks-node. - -Example: - -```toml -public_ip_address = "1.2.3.4:20444" -``` - -#### download_interval - -Time (in seconds) between attempts to download blocks. - -Example: - -```toml -download_interval = 60 -``` - -#### walk_interval - -Time (in seconds) between attempts to walk the neighborhood. - -Example: - -```toml -walk_interval = 30 -``` - -#### read_only_call_limit_read_length - -Total number of bytes allowed to be read by an individual read-only function call. - -Example: - -```toml -read_only_call_limit_read_length = 100000 -``` - -#### read_only_call_limit_read_count - -Total number of independent read operations permitted for an individual read-only function call. - -Example: - -```toml -read_only_call_limit_read_count = 30 -``` - -#### read_only_call_limit_runtime - -[Runtime cost](https://github.com/stacksgov/sips/blob/2d3fd9bf8da7a04f588d90ff6252173d7609d7bf/sips/sip-006/sip-006-runtime-cost-assessment.md#introduction) limit for an individual read-only function call. - -Example: - -```toml -read_only_call_limit_runtime = 1000000000 -``` - -### Section: burnchain - -This section contains configuration options pertaining to the blockchain the stacks-node binds to on the backend for proof-of-transfer (BTC). - -Example: - -```toml -[burnchain] -chain = "bitcoin" -mode = "mainnet" -peer_host = "your.bitcoind.node.org" -rpc_port = 8332 -peer_port = 8333 -``` - -#### chain - -The blockchain stacks-node binds to on the backend for proof-of-transfer. Only value supported: `"bitcoin"`. Only value supported: `"bitcoin"`. Only value supported: `"bitcoin"`. - -Example: - -```toml -chain = "bitcoin" -``` - -#### mode - -The profile or test phase of which to run stacks-node. The profile or test phase of which to run stacks-node. Valid values are `"mocknet"`, `"helium"`, `"neon"`, `"argon"`, `"krypton"`, `"xenon"`. The profile or test phase of which to run stacks-node. Valid values are `"mocknet"`, `"helium"`, `"neon"`, `"argon"`, `"krypton"`, `"xenon"`. - -Example: - -```toml -mode = "xenon" -``` - -#### peer_host - -Domain name of the host running the backend Bitcoin blockchain. It's required to either run a personal Bitcoin node locally, or to use a publicly hosted Bitcoin node. Domain name of the host running the backend Bitcoin blockchain. It's required to either run a personal Bitcoin node locally, or to use a publicly hosted Bitcoin node. It's required to either run a personal Bitcoin node locally, or to use a publicly hosted Bitcoin node. - -Example: - -```toml -peer_host = "your.bitcoind.node.org" -``` - -#### rpc_port - -peer_host's port stacks-node will connect to for RPC connections. - -Example: - -```toml -rpc_port = 8332 -``` - -#### peer_port - -peer_host's port stacks-node will connect to for P2P connections. - -Example: - -```toml -peer_port = 8333 -``` - -#### burn_fee_cap (optional) - -Maximum amount (in Satoshis) of "burn commitment" to broadcast for the next block's leader election. - -Example: - -```toml -burn_fee_cap = 30000 -``` - -#### satoshis_per_byte (optional) - -Amount (in Satoshis) per [virtual byte](https://en.bitcoin.it/wiki/Weight_units). This is used to compute the transaction fees. This is used to compute the transaction fees. This is used to compute the transaction fees. - -Example: - -```toml -satoshis_per_byte = 50 -``` - -So total transaction cost would be `(estimated_tx_size * satoshis_per_byte) + burn_fee_cap`. - -#### commit_anchor_block_within (optional) - -Sets the time period (in milliseconds) for commitments. Sets the time period (in milliseconds) for commitments. Sets the time period (in milliseconds) for commitments. Only used when `mode` is set to `"helium"`. - -Example: - -```toml -commit_anchor_block_within = 10000 -``` - -### Section: ustx_balance (testnet/regtest only) - -This section contains configuration options pertaining to the genesis block allocation for an address in micro-STX. This section contains configuration options pertaining to the genesis block allocation for an address in micro-STX. If a user changes these values, their node may be in conflict with other nodes on the network and find themselves unable to sync with other nodes. This section contains configuration options pertaining to the genesis block allocation for an address in micro-STX. If a user changes these values, their node may be in conflict with other nodes on the network and find themselves unable to sync with other nodes. - -:::info -This section can repeat multiple times, and thus is in double-brackets. Each section can define only one address. This section is ignored if running a node on mainnet. -::: - -Example: - -```toml -[[ustx_balance]] -address = "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6" -amount = 10000000000000000 - -[[ustx_balance]] -address = "ST11NJTTKGVT6D1HY4NJRVQWMQM7TVAR091EJ8P2Y" -amount = 10000000000000000 - -[[ustx_balance]] -address = "ST1HB1T8WRNBYB0Y3T7WXZS38NKKPTBR3EG9EPJKR" -amount = 10000000000000000 - -[[ustx_balance]] -address = "STRYYQQ9M8KAF4NS7WNZQYY59X93XEKR31JP64CP" -amount = 10000000000000000 -``` - -#### address - -Address which maintains a micro-STX balance. - -Example: - -```toml -address = "STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6" -``` - -#### amount - -The balance of micro-STX given to the address at the start of the node. - -Example: - -```toml -amount = 10000000000000000 -``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md b/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md deleted file mode 100644 index 094e3f03a1..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/nodes-and-miners/verify-miner.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Verify Miner -description: Verify node is operating as miner -sidebar_position: 7 ---- - -You can verify that your node is operating as a miner by checking its log output to verify that it was able to find its Bitcoin UTXOs: - -```bash -$ head -n 100 /path/to/your/node/logs | grep -i utxo -INFO [1630127492.031042] [testnet/stacks-node/src/run_loop/neon.rs:146] [main] Miner node: checking UTXOs at address: -INFO [1630127492.062652] [testnet/stacks-node/src/run_loop/neon.rs:164] [main] UTXOs found - will run as a Miner node -``` \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json b/i18n/zh/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json deleted file mode 100644 index f5de305558..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/noteworthy-contracts/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Noteworthy Contracts", - "position": 4, - "link": { - "type": "generated-index", - "description": "Specific deployed Clarity Contracts worth mentioning." - } -} \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md b/i18n/zh/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md deleted file mode 100644 index 2952930bbf..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/noteworthy-contracts/bns-contract.md +++ /dev/null @@ -1,362 +0,0 @@ ---- -title: BNS Contract -description: The Blockchain Naming System. ---- - -![](/img/satoshi-btc.png) - -## Introduction - -The Blockchain Naming System (BNS) is implemented as a smart contract using Clarity. - -Below is a list of public and read-only functions as well as error codes that can be returned by those methods: -* [Public functions](#public-functions) -* [Read-only functions](#read-only-functions) -* [Error codes](#error-codes) - -## Public functions - - -### name-import - -#### Input: `(buff 20), (buff 48), principal, (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-import namespace name beneficiary zonefile-hash)` -#### Description: -Imports name to a revealed namespace. Imports name to a revealed namespace. Each imported name is given both an owner and some off-chain state. Imports name to a revealed namespace. Each imported name is given both an owner and some off-chain state. - -### name-preorder - -#### Input: `(buff 20), uint` -#### Output: `(response uint int)` -#### Signature: `(name-preorder hashed-salted-fqn stx-to-burn)` -#### Description: -Preorders a name by telling all BNS nodes the salted hash of the BNS name. It pays the registration fee to the namespace owner's designated address. It pays the registration fee to the namespace owner's designated address. It pays the registration fee to the namespace owner's designated address. - -### name-register - -#### Input: `(buff 20), (buff 48), (buff 20), (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-register namespace name salt zonefile-hash)` -#### Description: -Reveals the salt and the name to all BNS nodes, and assigns the name an initial public key hash and zone file hash. - -### name-renewal - -#### Input: `(buff 20), (buff 48), uint, (optional principal), (optional (buff 20))` -#### Output: `(response bool int)` -#### Signature: `(name-renewal namespace name stx-to-burn new-owner zonefile-hash)` -#### Description: -Depending in the namespace rules, a name can expire. For example, names in the .id namespace expire after 2 years. You need to send a name renewal every so often to keep your name. For example, names in the .id namespace expire after 2 years. You need to send a name renewal every so often to keep your name. For example, names in the .id namespace expire after 2 years. You need to send a name renewal every so often to keep your name. - -You will pay the registration cost of your name to the namespace's designated burn address when you renew it. When a name expires, it enters a \"grace period\". The period is set to 5000 blocks (a month) but can be configured for each namespace. When a name expires, it enters a \"grace period\". The period is set to 5000 blocks (a month) but can be configured for each namespace. When a name expires, it enters a \"grace period\". The period is set to 5000 blocks (a month) but can be configured for each namespace. - -It will stop resolving in the grace period, and all of the above operations will cease to be honored by the BNS consensus rules. You may, however, send a NAME_RENEWAL during this grace period to preserve your name. After the grace period, everybody can register that name again. If your name is in a namespace where names do not expire, then you never need to use this transaction. -### name-revoke - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(name-revoke namespace name)` -#### Description: -Makes a name unresolvable. Makes a name unresolvable. Makes a name unresolvable. The BNS consensus rules stipulate that once a name is revoked, no one can change its public key hash or its zone file hash. The name's zone file hash is set to null to prevent it from resolving. You should only do this if your private key is compromised, or if you want to render your name unusable for whatever reason. The name's zone file hash is set to null to prevent it from resolving. You should only do this if your private key is compromised, or if you want to render your name unusable for whatever reason. The name's zone file hash is set to null to prevent it from resolving. You should only do this if your private key is compromised, or if you want to render your name unusable for whatever reason. - -### name-transfer - -#### Input: `(buff 20), (buff 48), principal, (optional (buff 20))` -#### Output: `(response bool int)` -#### Signature: `(name-transfer namespace name new-owner zonefile-hash)` -#### Description: -Changes the name's public key hash. Changes the name's public key hash. You would send a name transfer transaction if you wanted to: Changes the name's public key hash. You would send a name transfer transaction if you wanted to: -* Change your private key -* Send the name to someone else or -* Update your zone file - -When transferring a name, you have the option to also clear the name's zone file hash (i.e. set it to null). This is useful for when you send the name to someone else, so the recipient's name does not resolve to your zone file. This is useful for when you send the name to someone else, so the recipient's name does not resolve to your zone file. This is useful for when you send the name to someone else, so the recipient's name does not resolve to your zone file. - -### name-update - -#### Input: `(buff 20), (buff 48), (buff 20)` -#### Output: `(response bool int)` -#### Signature: `(name-update namespace name zonefile-hash)` -#### Description: -Changes the name's zone file hash. Changes the name's zone file hash. You would send a name update transaction if you wanted to change the name's zone file contents. For example, you would do this if you want to deploy your own Gaia hub and want other people to read from it. For example, you would do this if you want to deploy your own Gaia hub and want other people to read from it. Changes the name's zone file hash. You would send a name update transaction if you wanted to change the name's zone file contents. For example, you would do this if you want to deploy your own Gaia hub and want other people to read from it. For example, you would do this if you want to deploy your own Gaia hub and want other people to read from it. - -### namespace-preorder - -#### Input: `(buff 20), uint` -#### Output: `(response uint int)` -#### Signature: `(namespace-preorder hashed-salted-namespace stx-to-burn)` -#### Description: -Registers the salted hash of the namespace with BNS nodes, and burns the requisite amount of cryptocurrency. Additionally, this step proves to the BNS nodes that user has honored the BNS consensus rules by including a recent consensus hash in the transaction. Returns pre-order's expiration date (in blocks). Additionally, this step proves to the BNS nodes that user has honored the BNS consensus rules by including a recent consensus hash in the transaction. Returns pre-order's expiration date (in blocks). Additionally, this step proves to the BNS nodes that user has honored the BNS consensus rules by including a recent consensus hash in the transaction. Returns pre-order's expiration date (in blocks). - -### namespace-ready - -#### Input: `(buff 20)` -#### Output: `(response bool int)` -#### Signature: `(namespace-ready namespace)` -#### Description: -Launches the namespace and makes it available to the public. Launches the namespace and makes it available to the public. Launches the namespace and makes it available to the public. Once a namespace is launched, anyone can register a name in it if they pay the appropriate amount of cryptocurrency. - -### namespace-reveal - -#### Input: `(buff 20), (buff 20), uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, principal` -#### Output: `(response bool int)` -#### Signature: `(namespace-reveal namespace namespace-salt p-func-base p-func-coeff p-func-b1 p-func-b2 p-func-b3 p-func-b4 p-func-b5 p-func-b6 p-func-b7 p-func-b8 p-func-b9 p-func-b10 p-func-b11 p-func-b12 p-func-b13 p-func-b14 p-func-b15 p-func-b16 p-func-non-alpha-discount p-func-no-vowel-discount lifetime namespace-import)` -#### Description: -Reveals the salt and the namespace ID (after a namespace preorder). Reveals the salt and the namespace ID (after a namespace preorder). Reveals the salt and the namespace ID (after a namespace preorder). It reveals how long names last in this namespace before they expire or must be renewed, and it sets a price function for the namespace that determines how cheap or expensive names its will be.All of the parameters prefixed by `p` make up the `price function`. These parameters govern the pricing and lifetime of names in the namespace. These parameters govern the pricing and lifetime of names in the namespace. These parameters govern the pricing and lifetime of names in the namespace. - -The rules for a namespace are as follows: - -* a name can fall into one of 16 buckets, measured by length. a name can fall into one of 16 buckets, measured by length. Bucket 16 incorporates all names at least 16 characters long. a name can fall into one of 16 buckets, measured by length. Bucket 16 incorporates all names at least 16 characters long. - -* the pricing structure applies a multiplicative penalty for having numeric characters, or punctuation characters. - -* the price of a name in a bucket is `((coeff) * (base) ^ (bucket exponent)) / ((numeric discount multiplier) * (punctuation discount multiplier))` - -Example: - -* base = 10 -* coeff = 2 -* nonalpha discount: 10 -* no-vowel discount: 10 -* buckets 1, 2: 9 -* buckets 3, 4, 5, 6: 8 -* buckets 7, 8, 9, 10, 11, 12, 13, 14: 7 -* buckets 15, 16+: - - -## Read-only functions - -### can-name-be-registered - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(can-name-be-registered namespace name)` -#### Description: -Returns true if the provided name can be registered. - -### can-namespace-be-registered - -#### Input: `(buff 20)` -#### Output: `(response bool UnknownType)` -#### Signature: `(can-namespace-be-registered namespace)` -#### Description: -Returns true if the provided namespace is available. - -### can-receive-name - -#### Input: `principal` -#### Output: `(response bool int)` -#### Signature: `(can-receive-name owner)` -#### Description: -Returns true if the provided name can be received. Returns true if the provided name can be received. That is, if it is not curretly owned, a previous lease is expired, and the name wasn't revoked. Returns true if the provided name can be received. That is, if it is not curretly owned, a previous lease is expired, and the name wasn't revoked. - -### get-name-price - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response uint int)` -#### Signature: `(get-name-price namespace name)` -#### Description: -Gets the price for a name. - -### get-namespace-price - -#### Input: `(buff 20)` -#### Output: `(response uint int)` -#### Signature: `(get-namespace-price namespace)` -#### Description: -Gets the price for a namespace. - -### get-namespace-properties - -#### Input: `(buff 20)` -#### Output: `(response (tuple (namespace (buff 20)) (properties (tuple (can-update-price-function bool) (launched-at (optional uint)) (lifetime uint) (namespace-import principal) (price-function (tuple (base uint) (buckets (list 16 uint)) (coeff uint) (no-vowel-discount uint) (nonalpha-discount uint))) (revealed-at uint)))) int)` -#### Signature: `(get-namespace-properties namespace)` -#### Description: -Get namespace properties. - -### is-name-lease-expired - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response bool int)` -#### Signature: `(is-name-lease-expired namespace name)` -#### Description: -Return true if the provided name lease is expired. - -### name-resolve - -#### Input: `(buff 20), (buff 48)` -#### Output: `(response (tuple (lease-ending-at (optional uint)) (lease-started-at uint) (owner principal) (zonefile-hash (buff 20))) int)` -#### Signature: `(name-resolve namespace name)` -#### Description: -Get name registration details. - -### resolve-principal - -#### Input: `principal` -#### Output: `(response (tuple (name (buff 48)) (namespace (buff 20))) (tuple (code int) (name (optional (tuple (name (buff 48)) (namespace (buff 20)))))))` -#### Signature: `(resolve-principal owner)` -#### Description: -Returns the registered name that a principal owns if there is one. A principal can only own one name at a time. Returns the registered name that a principal owns if there is one. A principal can only own one name at a time. A principal can only own one name at a time. - -## Error codes - -### ERR_INSUFFICIENT_FUNDS -#### type: `int` -#### value: `4001` - -### ERR_NAMESPACE_ALREADY_EXISTS -#### type: `int` -#### value: `1006` - -### ERR_NAMESPACE_ALREADY_LAUNCHED -#### type: `int` -#### value: `1014` - -### ERR_NAMESPACE_BLANK -#### type: `int` -#### value: `1013` - -### ERR_NAMESPACE_CHARSET_INVALID -#### type: `int` -#### value: `1016` - -### ERR_NAMESPACE_HASH_MALFORMED -#### type: `int` -#### value: `1015` - -### ERR_NAMESPACE_NOT_FOUND -#### type: `int` -#### value: `1005` - -### ERR_NAMESPACE_NOT_LAUNCHED -#### type: `int` -#### value: `1007` - -### ERR_NAMESPACE_OPERATION_UNAUTHORIZED -#### type: `int` -#### value: `1011` - -### ERR_NAMESPACE_PREORDER_ALREADY_EXISTS -#### type: `int` -#### value: `1003` - -### ERR_NAMESPACE_PREORDER_CLAIMABILITY_EXPIRED -#### type: `int` -#### value: `1009` - -### ERR_NAMESPACE_PREORDER_EXPIRED -#### type: `int` -#### value: `1002` - -### ERR_NAMESPACE_PREORDER_LAUNCHABILITY_EXPIRED -#### type: `int` -#### value: `1010` - -### ERR_NAMESPACE_PREORDER_NOT_FOUND -#### type: `int` -#### value: `1001` - -### ERR_NAMESPACE_PRICE_FUNCTION_INVALID -#### type: `int` -#### value: `1008` - -### ERR_NAMESPACE_STX_BURNT_INSUFFICIENT -#### type: `int` -#### value: `1012` - -### ERR_NAMESPACE_UNAVAILABLE -#### type: `int` -#### value: `1004` - -### ERR_NAME_ALREADY_CLAIMED -#### type: `int` -#### value: `2011` - -### ERR_NAME_BLANK -#### type: `int` -#### value: `2010` - -### ERR_NAME_CHARSET_INVALID -#### type: `int` -#### value: `2022` - -### ERR_NAME_CLAIMABILITY_EXPIRED -#### type: `int` -#### value: `2012` - -### ERR_NAME_COULD_NOT_BE_MINTED -#### type: `int` -#### value: `2020` - -### ERR_NAME_COULD_NOT_BE_TRANSFERED -#### type: `int` -#### value: `2021` - -### ERR_NAME_EXPIRED -#### type: `int` -#### value: `2008` - -### ERR_NAME_GRACE_PERIOD -#### type: `int` -#### value: `2009` - -### ERR_NAME_HASH_MALFORMED -#### type: `int` -#### value: `2017` - -### ERR_NAME_NOT_FOUND -#### type: `int` -#### value: `2013` - -### ERR_NAME_NOT_RESOLVABLE -#### type: `int` -#### value: `2019` - -### ERR_NAME_OPERATION_UNAUTHORIZED -#### type: `int` -#### value: `2006` - -### ERR_NAME_PREORDERED_BEFORE_NAMESPACE_LAUNCH -#### type: `int` -#### value: `2018` - -### ERR_NAME_PREORDER_ALREADY_EXISTS -#### type: `int` -#### value: `2016` - -### ERR_NAME_PREORDER_EXPIRED -#### type: `int` -#### value: `2002` - -### ERR_NAME_PREORDER_FUNDS_INSUFFICIENT -#### type: `int` -#### value: `2003` - -### ERR_NAME_PREORDER_NOT_FOUND -#### type: `int` -#### value: `2001` - -### ERR_NAME_REVOKED -#### type: `int` -#### value: `2014` - -### ERR_NAME_STX_BURNT_INSUFFICIENT -#### type: `int` -#### value: `2007` - -### ERR_NAME_TRANSFER_FAILED -#### type: `int` -#### value: `2015` - -### ERR_NAME_UNAVAILABLE -#### type: `int` -#### value: `2004` - -### ERR_PANIC -#### type: `int` -#### value: `0` - -### ERR_PRINCIPAL_ALREADY_ASSOCIATED -#### type: `int` -#### value: `3001` diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md b/i18n/zh/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md deleted file mode 100644 index 349826f5f4..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/noteworthy-contracts/stacking-contract.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -title: Stacking Contract -description: See a detailed list of all functions and error codes of the Stacking contract. ---- - -## Introduction - -Stacking is implemented as a smart contract using Clarity. Stacking is implemented as a smart contract using Clarity. Stacking is implemented as a smart contract using Clarity. You can always find the Stacking contract identifier using the Stacks Blockchain API [`v2/pox` endpoint](https://docs.hiro.so/api#operation/get_pox_info). - -Below is a list of public and read-only functions as well as error codes that can be returned by those methods: - -* [Public functions](#public-functions) -* [Read-only functions](#read-only-functions) -* [Error codes](#error-codes) - -## Public functions - -### allow-contract-caller -#### input: `principal, (optional uint)` -#### output: `(response bool int)` -#### signature: `(allow-contract-caller caller until-burn-ht)` -#### description: -Give a contract-caller authorization to call stacking methods. Give a contract-caller authorization to call stacking methods. Give a contract-caller authorization to call stacking methods. Normally, stacking methods may only be invoked by _direct_ transactions (i.e., the `tx-sender` issues a direct `contract-call` to the stacking methods). - -By issuing an allowance, the tx-sender may call through the allowed contract. - -### delegate-stack-stx -#### input: `principal, uint, (tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint` -#### output: `(response (tuple (lock-amount uint) (stacker principal) (unlock-burn-height uint)) int)` -#### signature: `(delegate-stack-stx stacker amount-ustx pox-addr start-burn-ht lock-period)` -#### description: -As a delegate, stack the given principal's STX using `partial-stacked-by-cycle`. - -Once the delegate has stacked > minimum, the delegate should call `stack-aggregation-commit`. - -### delegate-stx -#### input: `uint, principal, (optional uint), (optional (tuple (hashbytes (buff 20)) (version (buff 1))))` -#### output: `(response bool int)` -#### signature: `(delegate-stx amount-ustx delegate-to until-burn-ht pox-addr)` -#### description: -Delegate to `delegate-to` the ability to stack from a given address. - -This method _does not_ lock the funds, rather, it allows the delegate to issue the stacking lock. - -The caller specifies: - -* amount-ustx: the total amount of ustx the delegate may be allowed to lock -* until-burn-ht: an optional burn height at which this delegation expiration -* pox-addr: an optional p2pkh or p2sh address to which any rewards *must* be sent - -### disallow-contract-caller -#### input: `principal` -#### output: `(response bool int)` -#### signature: `(disallow-contract-caller caller)` -#### description: -Revokes authorization from a contract to invoke stacking methods through contract-calls - -### reject-pox -#### input: -#### output: `(response bool int)` -#### signature: `(reject-pox)` -#### description: -Reject Stacking for this reward cycle. - -`tx-sender` votes all its uSTX for rejection. - -Note that unlike Stacking, rejecting PoX does not lock the tx-sender's tokens: PoX rejection acts like a coin vote. - -### revoke-delegate-stx -#### input: -#### output: `(response bool int)` -#### signature: `(revoke-delegate-stx)` -#### description: -Revoke a Stacking delegate relationship. Revoke a Stacking delegate relationship. Revoke a Stacking delegate relationship. A particular Stacker may only have one delegate, so this method does not take any parameters, and just revokes the Stacker's current delegate (if one exists). - -### stack-aggregation-commit -#### input: `(tuple (hashbytes (buff 20)) (version (buff 1))), uint` -#### output: `(response bool int)` -#### signature: `(stack-aggregation-commit pox-addr reward-cycle)` -#### description: -Commit partially stacked STX. - -This allows a stacker/delegate to lock fewer STX than the minimal threshold in multiple transactions, - -so long as: - -1. The pox-addr is the same. -2. This \"commit\" transaction is called _before_ the PoX anchor block. - -This ensures that each entry in the reward set returned to the stacks-node is greater than the threshold, - - but does not require it be all locked up within a single transaction - -### stack-stx -#### input: `uint, (tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint` -#### output: `(response (tuple (lock-amount uint) (stacker principal) (unlock-burn-height uint)) int)` -#### signature: `(stack-stx amount-ustx pox-addr start-burn-ht lock-period)` -#### description: -Lock up some uSTX for stacking! Note that the given amount here is in micro-STX (uSTX). Lock up some uSTX for stacking! Note that the given amount here is in micro-STX (uSTX). Note that the given amount here is in micro-STX (uSTX). - -The STX will be locked for the given number of reward cycles (lock-period). - -This is the self-service interface. tx-sender will be the Stacker. This is the self-service interface. tx-sender will be the Stacker. tx-sender will be the Stacker. - -* The given stacker cannot currently be stacking. -* You will need the minimum uSTX threshold. You will need the minimum uSTX threshold. You will need the minimum uSTX threshold. This isn't determined until the reward cycle begins, but this method still requires stacking over the _absolute minimum_ amount, which can be obtained by calling `get-stacking-minimum`. -* The pox-addr argument must represent a valid reward address. Right now, this must be a Bitcoin p2pkh or p2sh address. The pox-addr argument must represent a valid reward address. Right now, this must be a Bitcoin p2pkh or p2sh address. It cannot be a native Segwit address, but it may be a p2wpkh-p2sh or p2wsh-p2sh address. Right now, this must be a Bitcoin p2pkh or p2sh address. The pox-addr argument must represent a valid reward address. Right now, this must be a Bitcoin p2pkh or p2sh address. It cannot be a native Segwit address, but it may be a p2wpkh-p2sh or p2wsh-p2sh address. - -The tokens will unlock and be returned to the Stacker (tx-sender) automatically. - -## Read-only functions - -### can-stack-stx -#### input: `(tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint, uint` -#### output: `(response bool int)` -#### signature: `(can-stack-stx pox-addr amount-ustx first-reward-cycle num-cycles)` -#### description: -Evaluate if a participant can stack an amount of STX for a given period. - -### get-pox-info -#### input: -#### output: `(response (tuple (current-rejection-votes uint) (first-burnchain-block-height uint) (min-amount-ustx uint) (prepare-cycle-length uint) (rejection-fraction uint) (reward-cycle-id uint) (reward-cycle-length uint) (total-liquid-supply-ustx uint)) UnknownType)` -#### signature: `(get-pox-info)` -#### description: -Returns information about PoX status. - -### get-pox-rejection -#### input: `principal, uint` -#### output: `(optional (tuple (amount uint)))` -#### signature: `(get-pox-rejection stacker reward-cycle)` -#### description: -Returns the amount of uSTX that a given principal used to reject a PoX cycle. - -### get-stacker-info -#### input: `principal` -#### output: `(optional (tuple (amount-ustx uint) (first-reward-cycle uint) (lock-period uint) (pox-addr (tuple (hashbytes (buff 20)) (version (buff 1))))))` -#### signature: `(get-stacker-info stacker)` -#### description: -Returns the _current_ stacking information for `stacker. If the information is expired, or if there's never been such a stacker, then returns none. If the information is expired, or if there's never been such a stacker, then returns none. If the information is expired, or if there's never been such a stacker, then returns none. - -### get-stacking-minimum -#### input: -#### output: `uint` -#### signature: `(get-stacking-minimum)` -#### description: -Returns the absolute minimum amount that could be validly Stacked (the threshold to Stack in a given reward cycle may be higher than this - -### get-total-ustx-stacked -#### input: `uint` -#### output: `uint` -#### signature: `(get-total-ustx-stacked reward-cycle)` -#### description: -Returns the amount of currently participating uSTX in the given cycle. - -### is-pox-active -#### input: `uint` -#### output: `bool` -#### signature: `(is-pox-active reward-cycle)` -#### description: -Returns whether or not PoX has been rejected at a given PoX cycle. -## Error codes - -### ERR_DELEGATION_EXPIRES_DURING_LOCK -#### type: `int` -#### value: `21` - -### ERR_DELEGATION_POX_ADDR_REQUIRED -#### type: `int` -#### value: `23` - -### ERR_DELEGATION_TOO_MUCH_LOCKED -#### type: `int` -#### value: `22` - -### ERR_INVALID_START_BURN_HEIGHT -#### type: `int` -#### value: `24` - -### ERR_NOT_ALLOWED -#### type: `int` -#### value: `19` - -### ERR_STACKING_ALREADY_DELEGATED -#### type: `int` -#### value: `20` - -### ERR_STACKING_ALREADY_REJECTED -#### type: `int` -#### value: `17` - -### ERR_STACKING_ALREADY_STACKED -#### type: `int` -#### value: `3` - -### ERR_STACKING_EXPIRED -#### type: `int` -#### value: `5` - -### ERR_STACKING_INSUFFICIENT_FUNDS -#### type: `int` -#### value: `1` - -### ERR_STACKING_INVALID_AMOUNT -#### type: `int` -#### value: `18` - -### ERR_STACKING_INVALID_LOCK_PERIOD -#### type: `int` -#### value: `2` - -### ERR_STACKING_INVALID_POX_ADDRESS -#### type: `int` -#### value: `13` - -### ERR_STACKING_NO_SUCH_PRINCIPAL -#### type: `int` -#### value: `4` - -### ERR_STACKING_PERMISSION_DENIED -#### type: `int` -#### value: `9` - -### ERR_STACKING_POX_ADDRESS_IN_USE -#### type: `int` -#### value: `12` - -### ERR_STACKING_STX_LOCKED -#### type: `int` -#### value: `6` - -### ERR_STACKING_THRESHOLD_NOT_MET -#### type: `int` -#### value: `11` - -### ERR_STACKING_UNREACHABLE -#### type: `int` -#### value: `255` \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md b/i18n/zh/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md deleted file mode 100644 index 5f38edfb57..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/noteworthy-contracts/xbtc.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: xBTC -description: Wrapped BTC on Stacks ---- - -![](/img/xbtc-icon.webp) - -## Introduction - -[Wrapped.com](https://www.wrapped.com) has brought Bitcoin (xBTC) to the Stacks ecosystem. - -xBTC is backed 1:1 by Bitcoin and empowers developers to expand the Bitcoin DeFi ecosystem. - -The reserves are publicly visible [here](https://open.wrapped.com/reserves/). - -## Contract - -[SP3DX3H4FEYZJZ586MFBS25ZW3HZDMEW92260R2PR.Wrapped-Bitcoin](https://explorer.stacks.co/txid/SP3DX3H4FEYZJZ586MFBS25ZW3HZDMEW92260R2PR.Wrapped-Bitcoin?chain=mainnet) - -## Examples of uses - -[Friedger Mining Pool](https://pool.friedger.de/) currrently supports Stacking rewards payments in xBTC (optional). - - -## More information - -* [Blog post announcement](https://www.stacks.co/blog/tokensoft-wrapped-fundamental-bitcoin-defi-building-blocks-xbtc) by Muneeb Ali - -* Video: [Why xBTC is Important For Bitcoin to Grow](https://www.youtube.com/watch?v=xIoadrfSdi4) \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/references/_category_.json b/i18n/zh/docusaurus-plugin-content-docs/current/references/_category_.json deleted file mode 100644 index 3805ab0783..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/references/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "References", - "position": 9, - "link": { - "type": "generated-index", - "description": "Stacks references." - } -} \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/references/glossary.md b/i18n/zh/docusaurus-plugin-content-docs/current/references/glossary.md deleted file mode 100644 index b315c60d84..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/references/glossary.md +++ /dev/null @@ -1,215 +0,0 @@ ---- -title: Glossary -description: A comprehensive list of terms used within the ecosystem. ---- - -A comprehensive list of terms used within the ecosystem. - -#### App Review -An incentive mechanism for application developers in the early stage (first four years) of the ecosystem and helps with bootstrapping the two-sided market. - -#### Atlas -A peer network provide a global index for discovery. - -#### Bitcoin (BTC) address -A string of letters and numbers. A string of letters and numbers. A string of letters and numbers. `3E53XjqK4Cxt71BGeP2VhpcotM8LZ853C8` Sharing this address allows anyone to send Bitcoin to the address. - -#### block -A discrete group of records written to a blockchain that can effectively be identified and referenced by the use of headers that contain a digital fingerprint of the records each block contains. - -#### blockchain -A database created and shared by the members of a peer-to-peer computer network which each member of that network can independently trust due to the rules governing the database’s creation. A blockchain can therefore be used to replace centralized databases. A database created and shared by the members of a peer-to-peer computer network which each member of that network can independently trust due to the rules governing the database’s creation. A blockchain can therefore be used to replace centralized databases. A blockchain can therefore be used to replace centralized databases. - -#### Blockchain Name System (BNS) -Replacement for DNS. Replacement for DNS. More info [here](../noteworthy-contracts/bns-contract). - -#### Blockstack Browser -A deprecated application for accessing identity and storage. - -#### Blockstack Owner Address - -Looks like a bitcoin address but starts with `ID` for example: `ID-1J3PUxY5uDShUnHRrMyU6yKtoHEUPhKULs` - -#### Burning -Burning a token means that the token is transferred to an address that is a black hole—one that is not owned by any entity and for which guessing the applicable private key is effectively impossible based on known mathematical principles. This effectively destroys the token by making it unavailable for future use and decreases the total number of tokens available from that point forward. This effectively destroys the token by making it unavailable for future use and decreases the total number of tokens available from that point forward. This effectively destroys the token by making it unavailable for future use and decreases the total number of tokens available from that point forward. - -#### consensus hash -A consensus hash is a cryptographic hash that each node calculates at each block. It is derived from the accepted state transitions in the last-processed block and a geometric series of prior-calculated consensus hashes. It is derived from the accepted state transitions in the last-processed block and a geometric series of prior-calculated consensus hashes. It is derived from the accepted state transitions in the last-processed block and a geometric series of prior-calculated consensus hashes. - -#### Consensus rules -"The rules governing the creation of new valid records in a blockchain database and the mining algorithms used for this purpose. - -#### control plane -The part of a network that carries signaling traffic and is responsible for routing. Control packets originate from or are destined for a router. Functions of the control plane include system configuration and management. The part of a network that carries signaling traffic and is responsible for routing. Control packets originate from or are destined for a router. Functions of the control plane include system configuration and management. Control packets originate from or are destined for a router. Functions of the control plane include system configuration and management. Functions of the control plane include system configuration and management. - -#### core node -A server that runs Stacks Blockchain services. - -#### crypto-asset -A digital asset which utilises cryptography, peer-to-peer networking and a public ledger to regulate the creation of new units, verify transactions and secure the transactions without the intervention of any middleman. - -#### cryptography -The practise and study of encryption and decryption - encoding data so that it can only be decoded by specific individuals. A system for encrypting and decrypting data is a cryptosystem. The practise and study of encryption and decryption - encoding data so that it can only be decoded by specific individuals. A system for encrypting and decrypting data is a cryptosystem. A system for encrypting and decrypting data is a cryptosystem. - -#### DAO -See Decentralized Autonomous Organization. - -#### decentralized application (DApp) -A DApp is a service that enables direct interaction between end users and providers (e.g. connecting buyers and sellers in some marketplace, owners and stores in file storage). A term coined by Ethereum. See their glossary: http://ethdocs.org/en/latest/glossary.html#dapp" A term coined by Ethereum. See their glossary: http://ethdocs.org/en/latest/glossary.html#dapp" A term coined by Ethereum. See their glossary: http://ethdocs.org/en/latest/glossary.html#dapp" - -#### Decentralized Autonomous Organization -A type of contract or suite of contracts on the blockchain that is intented to codify, enforce or automate the processes of an organization. - -#### digital asset -Also referred to as a crypto-asset. Also referred to as a crypto-asset. Any set of unique digital information—including, for example, programs, decentralized programs, isolated chunks of programming code, collections of data, e-mail or web addresses or cryptocurrency tokens—that is capable of being stored and uniquely tracked on a computer network such as the Stacks network and over which a user can maintain control through that network. Also referred to as a crypto-asset. Any set of unique digital information—including, for example, programs, decentralized programs, isolated chunks of programming code, collections of data, e-mail or web addresses or cryptocurrency tokens—that is capable of being stored and uniquely tracked on a computer network such as the Stacks network and over which a user can maintain control through that network. - -#### digital fingerprint -A digital fingerprint is a unique number of a fixed length that can be produced by running any set of digital information through something called a cryptographic hash function. Each set of digital information (including a digital asset, and the digital record of any network operation on that digital asset) should (as a practical matter) have a unique digital fingerprint, which allows that set of digital information to be identified. However, it is almost impossible to recreate a digital asset from its digital fingerprint. The Blockstack network uses industry-standard algorithms such as SHA-256 to create digital fingerprints. Each set of digital information (including a digital asset, and the digital record of any network operation on that digital asset) should (as a practical matter) have a unique digital fingerprint, which allows that set of digital information to be identified. However, it is almost impossible to recreate a digital asset from its digital fingerprint. The Blockstack network uses industry-standard algorithms such as SHA-256 to create digital fingerprints. Each set of digital information (including a digital asset, and the digital record of any network operation on that digital asset) should (as a practical matter) have a unique digital fingerprint, which allows that set of digital information to be identified. However, it is almost impossible to recreate a digital asset from its digital fingerprint. The Blockstack network uses industry-standard algorithms such as SHA-256 to create digital fingerprints. - -#### digital signature -A digital signature is a sequence of digital information combining a user’s private key and any digital information that the user wishes to sign. A digital signature is a sequence of digital information combining a user’s private key and any digital information that the user wishes to sign. Any other party can use the user’s paired public key to verify that the digital signature is authentic, i.e. that the public key was generated from a particular piece of digital information and the user’s private key. A digital signature is a sequence of digital information combining a user’s private key and any digital information that the user wishes to sign. Any other party can use the user’s paired public key to verify that the digital signature is authentic, i.e. that the public key was generated from a particular piece of digital information and the user’s private key. - -#### distributed hash tables (DHT) -A form of network used to store some content in the form of key/value pairs. ... A form of network used to store some content in the form of key/value pairs. ... This experimental project try to avoid keeping all the blockchain, but instead prefers to store it in a DHT. ... A form of network used to store some content in the form of key/value pairs. ... This experimental project try to avoid keeping all the blockchain, but instead prefers to store it in a DHT. - -#### ephemeral key -A cryptographic key is called ephemeral if it is generated for each execution of a key establishment process. - -#### fork -The term fork is used to refer both to any situation where there are two or more competing versions of a blockchain on a network (a situation that may arise and resolve itself in the ordinary course of network operations due to lags in communication between core nodes) and any software update that is proposed for adoption by the core nodes of a blockchain network that may result in a persistent fork on the network, with core nodes that adopt the update recognizing one version of the blockchain and those which do not recognizing another. - -#### Gaia -Decentralized storage architecture for off-chain data. More info [here](../gaia). More info [here](../gaia). More info [here](../gaia). - -#### genesis block -The genesis block is the first block of the Stacks blockchain, which will create the initial 1.32 billion Stacks Tokens. - -#### id.blockstack -An identifier in the Blockstack, for example meepers.id.blockstack. This is your name & identity that is registered in the .id namespace on Blockstack. Your personal data and storage are built around this ID. Apps that want to access your data use your permission and identity to find it. An id is usually a shorthand for a longer, hash ID string, for example ID-1Fj9kkw15P51Fj9kkw15P5xJmyefWhLKrQMKNPREfaqsJ" This is your name & identity that is registered in the .id namespace on Blockstack. Your personal data and storage are built around this ID. Apps that want to access your data use your permission and identity to find it. An id is usually a shorthand for a longer, hash ID string, for example ID-1Fj9kkw15P51Fj9kkw15P5xJmyefWhLKrQMKNPREfaqsJ" This is your name & identity that is registered in the .id namespace on Blockstack. Your personal data and storage are built around this ID. Apps that want to access your data use your permission and identity to find it. An id is usually a shorthand for a longer, hash ID string, for example ID-1Fj9kkw15P51Fj9kkw15P5xJmyefWhLKrQMKNPREfaqsJ" - -#### identity - -A way to identify a person or an organization on the Stacks network. A way to identify a person or an organization on the Stacks network. An identity is unique, both `meepers.id.blockstack` or `chad.id` are examples of IDs. A way to identify a person or an organization on the Stacks network. An identity is unique, both `meepers.id.blockstack` or `chad.id` are examples of IDs. - -#### identity management (IDM) -Identity management, also known as identity and access management is, in computer security, the security and business discipline that enables the right individuals to access the right resources at the right times and for the right reason". - -#### know your customer (KYC) -Or KYC, is a popular term used in the banking or financial field. Or KYC, is a popular term used in the banking or financial field. KYC is a process where financial institutions, insurers and other companies obtain information about the identity and address of the customers as part of risk management. Or KYC, is a popular term used in the banking or financial field. KYC is a process where financial institutions, insurers and other companies obtain information about the identity and address of the customers as part of risk management. - -#### light clients -Clients that can independently validate the existence of transactions by downloading only block headers and not the entire blockchain. - -#### magic recovery code - -A long encrypted string, for example: `36mWivFdy0YPH2z31EflpQz/Y0UMrOrJ++lH=0EI7c3mop2JuRBm5WXxSTazJsUjOA...` Do not share the QR code that accompanied your recovery code either. This is a QR code: - -![](/img/qr-code.png) - -#### mesh network -A local network topology in which the infrastructure nodes (i.e. bridges, switches, and other infrastructure devices) connect directly, dynamically and non-hierarchically to as many other nodes as possible and cooperate with one another to efficiently route data from/to clients. - -#### mining -Mining generally refers to the process of performing certain functions for a network such as adding new records to a blockchain in exchange for mining rewards; it may also refer to other mechanisms whereby rewards (usually in the form of cryptocurrency) are provided for performing other tasks helpful to the network. - -#### mining power -A miner’s (or group of miners’) mining power is equal to the probability it will be selected to write a new block to the blockchain. Depending on the mechanism for mining, this is usually related to the overall share of computing power or cryptoassets the miner or miners possess relative to all miners for that blockchain. Depending on the mechanism for mining, this is usually related to the overall share of computing power or cryptoassets the miner or miners possess relative to all miners for that blockchain. Depending on the mechanism for mining, this is usually related to the overall share of computing power or cryptoassets the miner or miners possess relative to all miners for that blockchain. - -#### mining rewards -Mining rewards are newly issued tokens received by miners in exchange for adding new records to the blockchain or other activities beneficial to the network. - -#### name -An identifier or name. Names are a type of digital asset in the Stacks network. An identifier or name. Names are a type of digital asset in the Stacks network. If you have signed into the Stacks Wallet, you might have created a name. If an application developer registered an application within Stacks, then they registered a name. Public Stacking pools can also have a name. If an application developer registered an application within Stacks, then they registered a name. Public Stacking pools can also have a name. - -#### network operation -A network operation is any change to the information about a digital asset (or smart contract) stored on a blockchain, including, for example, a change in the digital asset’s owner, or a change in the location at which it is stored on the network. How and when these network operations are performed for each digital asset is governed, on the Blockstack network, either by the Stacks Node software or a smart contract. How and when these network operations are performed for each digital asset is governed, on the Blockstack network, either by the Stacks Node software or a smart contract. How and when these network operations are performed for each digital asset is governed, on the Blockstack network, either by the Stacks Node software or a smart contract. - -#### NFT -Non fungible token. - -#### private key - -Private keys matches a corresponding public key. Private keys matches a corresponding public key. Private keys matches a corresponding public key. A public key also looks like a string of letters and numbers: - -![](/img/private.png) - -The exact format of the public and private key depend on the software you use to create them. - -#### proof-of-burn mining -The consensus algorithm used in the Stacks blockchain where miners destroy a proof-of-work-based cryptocurrency (currently Bitcoin) to get tokens; this enables the functionality where nodes can select between conflicting blockchain forks, as the blockchain fork with the most amount of cryptocurrency burned is considered to be the correct fork. - -#### proof-of-work -A proof-of-work system or proof-of-work mining is a mining mechanism where miners must expend computing power to solve complicated cryptographic puzzles, and prove that they have done so by writing the solution to the blockchain, in order to be allowed to add blocks to a blockchain. This is the mining system used, for example, by Bitcoin. This is the mining system used, for example, by Bitcoin. This is the mining system used, for example, by Bitcoin. - -#### public key -Public and private key pair comprise of two uniquely related cryptographic keys. Public and private key pair comprise of two uniquely related cryptographic keys. Public and private key pair comprise of two uniquely related cryptographic keys. It looks like a long random string of letters and numbers: `3048 0241 00C9 18FA CF8D EB2D EFD5 FD37 89B9 E069 EA97 FC20 …` The exact format of the public and private key depend on the software you use to create them. - -#### Public Key Infrastructure (PKI) -A system which returns a cryptographic public key associated with a name. - -#### replicated state machines (RSMs) -This is a model for reasoning about distributed computer programs -- any program (plus it's input) can be represented as a state machine, and when trying to get a distributed set of servers to agree on the output of an algorithm, you can model that process as N different state machines" - -#### Secret recovery Key, -Used to access an identity on the Stacks blockchain. Used to access an identity on the Stacks blockchain. A 24-word sequence of words for example: `applied binge crisp pictorial fiery` `dancing agreeable frogs light finish ping apple` Used to access an identity on the Stacks blockchain. A 24-word sequence of words for example: `applied binge crisp pictorial fiery` `dancing agreeable frogs light finish ping apple` - -#### seed phrase - -Used to access Stacks Wallet software. The seed phrase consists of 24 words in a sequence. Both the word *and its position the sequence* are important. Write down your seed phrase and store it in a secure location such as a safe deposit box. When you write the seed phrase down, include its position, for example,`1-frog, 2-horse, 3-building` and so on until you reach a final position `24-ocean`. -#### smart contract -A smart contract is a computer program written to a blockchain such as the Stacks blockchain by developers. This computer program defines the various network operations that can be performed on the digital assets on the blockchain, the computations that can be performed using the smart contract, along with defining various important properties of the respective digital assets like ownership rights and the cost in fuel required to register the digital assets. This computer program defines the various network operations that can be performed on the digital assets on the blockchain, the computations that can be performed using the smart contract, along with defining various important properties of the respective digital assets like ownership rights and the cost in fuel required to register the digital assets. This computer program defines the various network operations that can be performed on the digital assets on the blockchain, the computations that can be performed using the smart contract, along with defining various important properties of the respective digital assets like ownership rights and the cost in fuel required to register the digital assets. - -#### soft fork -A soft fork is a proposed update to the software governing the network that results in a post-update network that is compatible with the network as it existed prior to the update, because it restricts the network operations that can be performed after the update. - -#### Stacks (STX) address - - A STX address is a string of letters and numbers starting with an `SP` or `SM`, for example: `SM3KJBA4RZ7Z20KD2HBXNSXVPCR1D3CRAV6Q05MKT` If you created a software-only wallet with the Stacks Wallet software, the wallet has a single STX address which is also sometimes called the *wallet address*. You access a software wallet with a *seed phrase*. " You access a software wallet with a *seed phrase*. " You access a software wallet with a *seed phrase*. " - -#### Stacks blockchain -The Stacks blockchain is the custom blockchain being developed for use by the Stacks network that will use the Stacks token as its native currency and which will include the genesis block and subsequent blocks created by the mining activities described in the Stacks Network—Development of the Stacks network. - -#### Stacks Explorer -An application that allow you to view and search transactions in the blockchain. For example, https://explorer.stacks.co. For example, https://explorer.stacks.co. For example, https://explorer.stacks.co. - -#### Stacks node -A complete version of our open-source software available on Github at https://github.com/stacks-network/stacks-blockchain/ that governs the creation of the blockchain, the smart contracts that may be written to our blockchain, and other systems that make up the Stacks network, when run on the systems and devices of our users and developers. - -#### Stacks wallet -An application for accessing assets, identity and storage. More information and example [here](../services-using-stacks/wallets). An application for accessing assets, identity and storage. Examples are the [Hiro Wallet](https://www.hiro.so/wallet), [xverse](https://www.xverse.app/) and [dcent](https://dcentwallet.com/). - -#### storage hub -A Gaia instance run by a hub provider or software. A Gaia hub stores data in a separate, addressed location. - -#### storage provider -A third-party company cloud or software provider that hosts one or more Gaia storage hubs. - -#### transaction -A transaction is a unit of work within a block. - -#### transaction fee -Fees paid by participants in a transaction to miners. - -#### two-sided market problem -Economic platforms having two distinct user groups that provide each other with network benefits. The Stacks platform is a classic two-sided market. Economic platforms having two distinct user groups that provide each other with network benefits. The Stacks platform is a classic two-sided market. The Stacks platform is a classic two-sided market. - -#### username -A shorthand name for your id.blockstack. - -#### virtual blockchain -A layer that sits on top of a blockchain that introduces new functionality and operations without requiring changes to the underlying blockchain. - -#### wallet address -A wallet address is the form in which a public key can be presented and recorded on a blockchain. Wallet addresses are therefore used to assign the ownership of digital assets on the Blockstack network. A wallet address is the form in which a public key can be presented and recorded on a blockchain. Wallet addresses are therefore used to assign the ownership of digital assets on the Blockstack network. Wallet addresses are therefore used to assign the ownership of digital assets on the Blockstack network. - -#### watch-only wallet -A wallet without send and receive ability. A wallet without send and receive ability. You can view only balances and transaction history. - -#### web of trust mining -Web-of-trust mining provides incentive mechanisms for users where an initial trusted-set of unique users is curated in the genesis block and, in the future, the initial set of users can expand the web-of-trust after the network goes live. - -#### web3 -The exact definition is still under discussion, but it general refers to the 3rd generation of the web that is based on blockchain technology and incorporates decentralized and token-based economics. - -#### zone file -A Domain Name System (DNS) zone file is a text file that describes a DNS zone. A Domain Name System (DNS) zone file is a text file that describes a DNS zone. A DNS zone is a subset, often a single domain, of the hierarchical domain name structure of the DNS. A Domain Name System (DNS) zone file is a text file that describes a DNS zone. A DNS zone is a subset, often a single domain, of the hierarchical domain name structure of the DNS. diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/references/nft.md b/i18n/zh/docusaurus-plugin-content-docs/current/references/nft.md deleted file mode 100644 index 033ee0a71a..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/references/nft.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: NFTs on Stacks -description: A list of sites that operate NFTs on Stacks ---- - -List of sites that operate NFTS on Stacks on alphabetical order. - -### [Byzantion](https://byzantion.xyz/) - -![website-screenshot](/img/sh_nft_byzantion.png) - -### [Gamma](https://gamma.io/) -![website-screenshot](/img/sh_nft_gamma.png) - -### [Megapont](https://www.megapont.com/) - -![website-screenshot](/img/sh_nft_megapont.png) - -### [StacksArt](https://www.stacksart.com/) - -![website-screenshot](/img/sh_nft_stacksart.png) - diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md b/i18n/zh/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md deleted file mode 100644 index dc6e507d5e..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/references/stacks-info-sites.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Stacks info sites -description: A list of sites on alphabetical order that display status and stats of the Stacks network. ---- - -### [Haystack](https://haystack.tools/mempool) - -![website-screenshot](/img/sh_haystacks.png) - -### [Stacksdata](https://stacksdata.info/) - -![website-screenshot](/img/sh_stacksdata.png) - -### [Stacksonchain](https://stacksonchain.com) - -![website-screenshot](/img/sh_stacksonchain.png) - -### [Status Hiro](https://status.hiro.so/) - -![website-screenshot](/img/sh_statushiro.png) - -### [Stxstats](https://www.stxstats.co/) - -![website-screenshot](/img/sh_stxstats.png) - -### [Novuminsights](https://stacks.novuminsights.com/health) - -![website-screenshot](/img/sh_novuminsights.png) - -### [Onstacks](https://app.onstacks.com/) - -![website-screenshot](/img/sh_onstacks.png) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json b/i18n/zh/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json deleted file mode 100644 index ebd63f366c..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/services-using-stacks/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "Services using Stacks", - "position": 8, - "link": { - "type": "generated-index", - "description": "An 'always incomplete' list of services that use Stacks." - } -} \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md b/i18n/zh/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md deleted file mode 100644 index c3fc0556bf..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/services-using-stacks/defi.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: DeFi -description: De-Fi sites on Stacks -sidebar_position: 2 ---- - -They are multiple De-Fi sites that operate on the Stacks blockchain. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: Please edit this page to add any relevant new site that we are missing. ::: - -## Alex - -[Alex](https://app.alexlab.co) ![](/img/sh_alex.png) - -## Arkadiko - -[Arkadiko](https://arkadiko.finance/) ![](/img/sh_arkadiko.png) - -## Catamaran Swaps - -[Catamaran Swaps](https://www.catamaranswaps.org/) allows trustless exchange of digital assets. - -![](/img/sh_catamaran.png) - -## Lnswap - -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange Non custiodial crypto currency exchange - -![](/img/sh_lnswap.png) - -## Neoswap - -[Neoswap](https://neoswap.party) - -![](/img/sh_neoswap.png) - -## Stackswap - -[Stackswap](https://app.stackswap.org/v2) - -![](/img/sh_stackswap.png) - diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/services-using-stacks/more.md b/i18n/zh/docusaurus-plugin-content-docs/current/services-using-stacks/more.md deleted file mode 100644 index a7b57f922c..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/services-using-stacks/more.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: More -description: More services built on Stacks. -sidebar_position: 5 ---- - -List of sites on alphabetical order added by the community. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: Please edit this page to add any relevant new site that we are missing. ::: - -## Citycoins - -[Citycoins](https://citycoins.co) - -![](/img/sh_citycoins.png) - -## Sigle - -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. - -![](/img/sh_sigle.png) \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md b/i18n/zh/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md deleted file mode 100644 index 6f1f8ecfa0..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/services-using-stacks/nft.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: NFTs -description: NFTs on Stacks -sidebar_position: 3 ---- - -List of sites that operate NFTS on Stacks on alphabetical order. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: Please edit this page to add any relevant new site that we are missing. ::: - -### [Byzantion](https://byzantion.xyz/) - -![website-screenshot](/img/sh_nft_byzantion.png) - -### [Gamma](https://gamma.io/) -![website-screenshot](/img/sh_nft_gamma.png) - -### [Megapont](https://www.megapont.com/) - -![website-screenshot](/img/sh_nft_megapont.png) - -### [StacksArt](https://www.stacksart.com/) - -![website-screenshot](/img/sh_nft_stacksart.png) - -### [Superfandom](https://superfandom.io/) - -![website-screenshot](/img/sh_superfandom.png) \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/services-using-stacks/other.md b/i18n/zh/docusaurus-plugin-content-docs/current/services-using-stacks/other.md deleted file mode 100644 index 199fc41da5..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/services-using-stacks/other.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -title: Other Stacks sites -description: A list of sites on alphabetical order built on Stacks. -sidebar_position: 4 ---- - -List of sites on alphabetical order added by the community. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Alex -[Alex](https://app.alexlab.co) - -## Sigle - -[Sigle](https://www.sigle.io/) is a decentralised and open source web 3 writing platform. \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md b/i18n/zh/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md deleted file mode 100644 index 9618006777..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/services-using-stacks/stacks-info-sites.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Stacks info sites -description: Status and stats of the Stacks network. -sidebar_position: 1 ---- - -A list of sites on alphabetical order that display status and stats of the Stacks network. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: Please edit this page to add any relevant new site that we are missing. ::: - -### [Haystack](https://haystack.tools/mempool) - -![website-screenshot](/img/sh_haystacks.png) - -### [Stacksdata](https://stacksdata.info/) - -![website-screenshot](/img/sh_stacksdata.png) - -### [Stacksonchain](https://stacksonchain.com) - -![website-screenshot](/img/sh_stacksonchain.png) - -### [Status Hiro](https://status.hiro.so/) - -![website-screenshot](/img/sh_statushiro.png) - -### [Stxstats](https://www.stxstats.co/) - -![website-screenshot](/img/sh_stxstats.png) - -### [Novuminsights](https://stacks.novuminsights.com/health) - -![website-screenshot](/img/sh_novuminsights.png) - -### [Onstacks](https://app.onstacks.com/) - -![website-screenshot](/img/sh_onstacks.png) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md b/i18n/zh/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md deleted file mode 100644 index d4b4cbf18c..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/services-using-stacks/swaps.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: Swaps -description: A list of sites that allow Swaps -sidebar_position: 2 ---- - -They are multiple sites that allow you to make swaps using the Stacks blockchain. - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: - -## Catamaran Swaps - -[Catamaran Swaps](https://www.catamaranswaps.org/) allows trustless exchange of digital assets. - -![](/img/sh_catamaran.png) - -## Lnswap - -[LNSWAP](https://www.lnswap.org). Non custiodial crypto currency exchange - -![](/img/sh_lnswap.png) - -## Neoswap - -[Neoswap](https://neoswap.party) - -![](/img/sh_neoswap.png) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md b/i18n/zh/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md deleted file mode 100644 index fb1bf958be..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/services-using-stacks/wallets.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Wallets -description: Wallets for Stacks -sidebar_position: 4 ---- - -A list of hardware and software wallets for Stacks - -:::tip Are we missing one? -Please edit this page to add any relevant new site that we are missing. -::: Please edit this page to add any relevant new site that we are missing. ::: - -## Blockchain.com - -[Blockchain.com](https://www.blockchain.com/wallet) - -![](/img/sh_blockchain.png) -## Boom - -[Boom](https://boom.money) - -![](/img/sh_boom.png) - -## Dcent wallet - -[D'CENT](https://dcentwallet.com) - -![](/img/sh_dcent.png) -## Hiro Wallet - -[Hiro Wallet](https://www.hiro.so/wallet) - -![](/img/sh_hirowallet.png) - -## Neptune - -[Neptune](https://neptunewallet.io) - -![](/img/sh_neptunewallet.png) - -## Xverse - -[Xverse](https://www.xverse.app/) - -![](/img/sh_xverse.png) - -## Wise - -[Wise](https://wiseapp.id) - -![](/img/sh_wiseapp.png) \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md b/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md deleted file mode 100644 index 1e82e1ca58..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/accounts.md +++ /dev/null @@ -1,216 +0,0 @@ ---- -title: Accounts -description: Guide to Stacks 2.0 accounts -sidebar_position: 5 ---- - -## Introduction - -Stacks 2.0 accounts are entities that own assets, like Stacks (STX) tokens. An account has an address, private key, nonce, and one or more asset balances. An account has an address, private key, nonce, and one or more asset balances. An account has an address, private key, nonce, and one or more asset balances. An account has an address, private key, nonce, and one or more asset balances. - -:::tip The encryption algorithm used in Stacks 2.0 is **[secp256k1](https://en.bitcoinwiki.org/wiki/Secp256k1)**. - -Additionally, [Ed25519](https://ed25519.cr.yp.to/) is also used just for the VRF (Verifiable Random Function). ::: - -Assets cannot leave an account without an action from the account owner. 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. 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. 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. - -:::tip -The transaction type doesn't need to be a token transfer - contract deploy and contract call transactions can change the balances of an account -::: - -## Creation - -An account is generated from a 24-word mnemonic phrase. This is often referred to as the **seed phrase**. The seed phrase provides access to Stacks 2.0 accounts. This is often referred to as the **seed phrase**. The seed phrase provides access to Stacks 2.0 accounts. - -:::danger -If the seed phrase is lost, access to the associated account cannot be restored. No person or organization, including Blockstack, can recover a lost seed phrase. -::: No person or organization, including Blockstack, can recover a lost seed phrase. -::: No person or organization, including Blockstack, can recover a lost seed phrase. -::: - -The easiest way to generate a new Stacks 2.0 account is to use the [Stacks CLI](https://github.com/hirosystems/stacks.js/tree/master/packages/cli): - -```bash -# install CLI globally -npm install --global @stacks/cli - -# generate a new account and store details in a new file -# '-t' option makes this a testnet account -stx make_keychain -t > cli_keychain.json -``` - -`make_keychain` creates the following file: - -```js -{ - "mnemonic": "aaa bbb ccc ddd ...", - "keyInfo": { - "privateKey": "5a3f1f15245bb3fb...", - "address": "STJRM2AMVF90ER6G3RW1QTF85E3HZH37006D5ER1", - "btcAddress": "biwSd6KTEvJcyX2R8oyfgj5REuLzczMYC1", - "wif": "L4HXn7PLmzoNW...", - "index": 0 - } -} -``` - -:::tip Check out the [Stacks CLI reference](https://docs.hiro.so/references/stacks-cli) for more details ::: - -| Field | Description | -| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `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.privateKey` | Private key for the account. Private key for the account. Private key for the account. Private key for the account. Required for token transfers and often referred to as `senderKey` | -| `keyInfo.address` | Stacks address for the account | -| `keyInfo.btcAddress` | Corresponding BTC address for the account. | -| `keyInfo.wif` | Private key of the btcAddress in compressed format. | -| `keyInfo.index` | Nonce for the account, starting at 0 | - -Note that a new account automatically exists for each new private key. Note that a new account automatically exists for each new private key. There is no need to manually instantiate an account on the Stacks 2.0 blockchain. Note that a new account automatically exists for each new private key. Note that a new account automatically exists for each new private key. There is no need to manually instantiate an account on the Stacks 2.0 blockchain. Note that a new account automatically exists for each new private key. There is no need to manually instantiate an account on the Stacks 2.0 blockchain. - -:::tip Addresses are created by generating the [RIPEMD-160 hash](https://en.wikipedia.org/wiki/RIPEMD#RIPEMD-160_hashes) of the [SHA256](https://en.bitcoinwiki.org/wiki/SHA-256) of the public key. BTC addresses are encoded with [Base58Check](https://en.bitcoin.it/wiki/Base58Check_encoding). For Stacks addresses, [c32check](https://github.com/stacks-network/c32check) is used. Deriving an address from a public key can be done without internet access, for instance using the c32check `c32addressDecode` method. ::: BTC addresses are encoded with [Base58Check](https://en.bitcoin.it/wiki/Base58Check_encoding). For Stacks addresses, [c32check](https://github.com/stacks-network/c32check) is used. Deriving an address from a public key can be done without internet access, for instance using the c32check `c32addressDecode` method. ::: BTC addresses are encoded with [Base58Check](https://en.bitcoin.it/wiki/Base58Check_encoding). For Stacks addresses, [c32check](https://github.com/stacks-network/c32check) is used. Deriving an address from a public key can be done without internet access, for instance using the c32check `c32addressDecode` method. ::: - -Alternatively to the CLI creation, the [Stacks Transactions JS](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library can be used: - -```js -import { - makeRandomPrivKey, - privateKeyToString, - getAddressFromPrivateKey, - TransactionVersion, -} from '@stacks/transactions'; - -const privateKey = makeRandomPrivKey(); - -// Get public key from private -const publicKey = getPublicKey(privateKey); - -const stacksAddress = getAddressFromPrivateKey( - privateKeyToString(privateKey), - TransactionVersion.Testnet // remove for Mainnet addresses -); -``` - -A second alternative would be to use [stacks-gen](https://github.com/psq/stacks-gen). A second alternative would be to use [stacks-gen](https://github.com/psq/stacks-gen). This tool will generate all the keys you need in one place, including the values needed for calling the stacking contract, and also a WIF key for use with `bitcoind`. A second alternative would be to use [stacks-gen](https://github.com/psq/stacks-gen). This tool will generate all the keys you need in one place, including the values needed for calling the stacking contract, and also a WIF key for use with `bitcoind`. - -#### stacks-gen prerequisite - -Install [npx](https://github.com/npm/npx) if not already installed. (npx will check whether `` exists in \$PATH, or in the local project binaries, and execute that. If `` is not found, it will be installed prior to execution). (npx will check whether `` exists in \$PATH, or in the local project binaries, and execute that. If `` is not found, it will be installed prior to execution). Install [npx](https://github.com/npm/npx) if not already installed. (npx will check whether `` exists in \$PATH, or in the local project binaries, and execute that. If `` is not found, it will be installed prior to execution). (npx will check whether `` exists in \$PATH, or in the local project binaries, and execute that. If `` is not found, it will be installed prior to execution). (npx will check whether `` exists in \$PATH, or in the local project binaries, and execute that. If `` is not found, it will be installed prior to execution). If `` is not found, it will be installed prior to execution). - -``` -npm install -g npx -``` - -#### stacks-gen usage - -``` -npx -q stacks-gen sk --testnet - -{ - "phrase": "guide air pet hat friend anchor harvest dog depart matter deny awkward sign almost speak short dragon rare private fame depart elevator snake chef", - "private": "0351764dc07ee1ad038ff49c0e020799f0a350dd0769017ea09460e150a6401901", - "public": "022d82baea2d041ac281bebafab11571f45db4f163a9e3f8640b1c804a4ac6f662", - "stacks": "ST16JQQNQXVNGR8RZ1D52TMH5MFHTXVPHRV6YE19C", - "stacking": "{ hashbytes: 0x4d2bdeb7eeeb0c231f0b4a2d5225a3e3aeeed1c6, version: 0x00 }", - "btc": "mnYzsxxW271GkmyMnRfiopEkaEpeqLtDy8", - "wif": "cMh9kwaCEttgTQYkyMUYQVbdm5ZarZdBHErcq7mXUChXXCo7CFEh" -} -``` - -:::tip The stacking object with hashbytes and a version represents the bitcoin address derived from the Stacks address. Read more about the [bitcoin address format](stacking#bitcoin-address). ::: Read more about the [bitcoin address format](stacking#bitcoin-address). ::: Read more about the [bitcoin address format](stacking#bitcoin-address). ::: - -Full documentation available at [stacks-gen](https://github.com/psq/stacks-gen). - -## Querying - -### Get Stacks (STX) balance and nonce - -STX balance and nonce can be obtained through the [`GET /v2/accounts/`](https://docs.hiro.so/api#operation/get_account_info) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/accounts/' -``` - -Sample response: - -```js -{ - "balance": "0x0000000000000000002386f26f3f40ec", - "nonce": 17 -} -``` - -:::tip -The balance string represents an unsigned 128-bit integer (big-endian) in hex encoding -::: - -### Get all token balances - -All token balances can be obtained through the [`GET /extended/v1/address//balances`](https://docs.hiro.so/api#operation/get_account_balance) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/address//balances' -``` - -Sample response: - -```js -{ - "stx": { - "balance": "0", - "total_sent": "0", - "total_received": "0" - }, - "fungible_tokens": {}, - "non_fungible_tokens": {} -} -``` - -:::tip Stacks accounts cannot hold bitcoins. -> Stacks accounts cannot hold bitcoins. The best way to obtain corresponding BTC balances is to derive the BTC address from the Stacks address (using [`c32check`](https://github.com/stacks-network/c32check#c32tob58-b58toc32)) and query the Bitcoin network. ::: -> Stacks accounts cannot hold bitcoins. The best way to obtain corresponding BTC balances is to derive the BTC address from the Stacks address (using [`c32check`](https://github.com/stacks-network/c32check#c32tob58-b58toc32)) and query the Bitcoin network. ::: -> Stacks accounts cannot hold bitcoins. The best way to obtain corresponding BTC balances is to derive the BTC address from the Stacks address (using [`c32check`](https://github.com/stacks-network/c32check#c32tob58-b58toc32)) and query the Bitcoin network. ::: - -### Get all asset events - -All asset events associated with the account can be obtained through the [`GET /extended/v1/address//assets`](https://docs.hiro.so/api#operation/get_account_balance) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/address//assets' -``` - -Sample response: - -```js -{ - "limit": 20, - "offset": 0, - "total": 0, - "results": [ - { - "event_index": 5, - "event_type": "non_fungible_token_asset", - "asset": { - "asset_event_type": "transfer", - "asset_id": "ST2W14YX9SFVDB1ZGHSH40CX1YQAP9XKRAYSSVYAG.hello_world::hello-nft", - "sender": "SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR", - "recipient": "SM2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQVX8X0G", - "value": { - "hex": "0x0100000000000000000000000000000001", - "repr": "u1" - } - } - }, - { - "event_index": 3, - "event_type": "fungible_token_asset", - "asset": { - "asset_event_type": "mint", - "asset_id": "ST2W14YX9SFVDB1ZGHSH40CX1YQAP9XKRAYSSVYAG.hello_world::novel-token-19", - "sender": "", - "recipient": "SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR", - "amount": "12" - } - } - ] -} -``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/index.md b/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/index.md deleted file mode 100644 index bc8283ae8d..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/index.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Understand Stacks -description: Learn more about the Stacks 2.0 blockchain -sidebar_position: 1 ---- - -![](/img/SBC-L-2x-10.png) -## Introduction - -Stacks 2.0 is a layer-1 blockchain that connects to Bitcoin and brings smart contracts and decentralized apps to it. Smart contracts and apps developed on the Stacks platform are natively integrated with the security, stability, and economic power of Bitcoin. Smart contracts and apps developed on the Stacks platform are natively integrated with the security, stability, and economic power of Bitcoin. Smart contracts and apps developed on the Stacks platform are natively integrated with the security, stability, and economic power of Bitcoin. Smart contracts and apps developed on the Stacks platform are natively integrated with the security, stability, and economic power of Bitcoin. - -## Capabilities - -Read more about the features provided by the Stacks 2.0 blockchain. - - - -:::tip Check out the [technical specifications](technical-specs) for a brief overview ::: - - - - -A detailed [comparison of the Stacks blockchain to other blockchain technologies][] is available at the Stacks Foundation blog. -### Consensus mechanism -![](/img/pages/stacking.svg) Stacks 2.0 implements a new mining mechanism called Proof of Transfer ("PoX"). Stacks 2.0 implements a new mining mechanism called Proof of Transfer ("PoX"). PoX is a consensus algorithm between two blockchains. It uses an established blockchain (in this case Bitcoin) to secure a new blockchain (Stacks). It uses an established blockchain (in this case Bitcoin) to secure a new blockchain (Stacks). Stacks 2.0 implements a new mining mechanism called Proof of Transfer ("PoX"). PoX is a consensus algorithm between two blockchains. It uses an established blockchain (in this case Bitcoin) to secure a new blockchain (Stacks). It uses an established blockchain (in this case Bitcoin) to secure a new blockchain (Stacks). Stacks 2.0 implements a new mining mechanism called Proof of Transfer ("PoX"). PoX is a consensus algorithm between two blockchains. It uses an established blockchain (in this case Bitcoin) to secure a new blockchain (Stacks). It uses an established blockchain (in this case Bitcoin) to secure a new blockchain (Stacks). - -PoX connects to Bitcoin with a 1:1 block ratio, meaning anything that happens on the Stacks blockchain can be verified on the Bitcoin Blockchain. - -Instead of burning electricity on proof of work, PoX reuses already minted bitcoins as "proof of computation" and miners represent their cost of mining in bitcoins directly. - - -[Read more about Proof of Transfer](proof-of-transfer) -### Mining - -![](/img/pages/testnet-sm.svg) Mining is required to make the network usable, trustworthy, and secure. Mining is required to make the network usable, trustworthy, and secure. Miners verify incoming transactions, participate in the consensus mechanism, and write new blocks to the blockchain. Mining is required to make the network usable, trustworthy, and secure. Miners verify incoming transactions, participate in the consensus mechanism, and write new blocks to the blockchain. Mining is required to make the network usable, trustworthy, and secure. Miners verify incoming transactions, participate in the consensus mechanism, and write new blocks to the blockchain. - -To incentivize mining, miners receive freshly minted Stacks (STX) tokens if they win the bid for becoming the leader of the next round. - -[Read more about Mining](mining) - -### Stacking - -Bitcoins used for miner bids are sent to a set of specific addresses corresponding to Stacks (STX) tokens holders that are actively participating in consensus ("Stackers"). Thus, rather than being destroyed, the bitcoins consumed in the mining process go to productive Stacks holders as a reward based on their holdings of Stacks and participation in the Stacking algorithm. Thus, rather than being destroyed, the bitcoins consumed in the mining process go to productive Stacks holders as a reward based on their holdings of Stacks and participation in the Stacking algorithm. Thus, rather than being destroyed, the bitcoins consumed in the mining process go to productive Stacks holders as a reward based on their holdings of Stacks and participation in the Stacking algorithm. Thus, rather than being destroyed, the bitcoins consumed in the mining process go to productive Stacks holders as a reward based on their holdings of Stacks and participation in the Stacking algorithm. - -Stackers have to lock up their Stacks (STX) tokens for a certain period of time. - -[Read more about Stacking](stacking) - -### Smart contracts - -![](/img/pages/write-smart-contracts-sm.svg) Clarity is a new language for smart contracts on the Stacks 2.0 blockchain. The Clarity smart contract language optimizes for predictability and security. The Clarity smart contract language optimizes for predictability and security. The Clarity smart contract language optimizes for predictability and security. The Clarity smart contract language optimizes for predictability and security. - -Stacks 2.0 anchors clarity smart contracts to Bitcoin making it possible for smart contracts to operate based on actions seen on the bitcoin blockchain. - -:::note The [Clarity open-source project](https://clarity-lang.org/) is supported by Stacks and [Algorand](https://www.algorand.com/) ::: - - -Clarity is distinct from other languages designed for writing smart contracts in a few ways: - -- **Predictability**: The Clarity language uses precise and unambiguous syntax that allows developers to predict exactly how their contracts will be executed. -- **Security**: The Clarity language allows users to supply their own conditions for transactions that ensure that a contract may never unexpectedly transfer a token owned by a user. -- **No compiler**: Contracts written in Clarity are broadcasted on the Stacks blockchain exactly as they are written by developers. This ensures that the code developers wrote, analyzed, and tested, is exactly what gets executed. This ensures that the code developers wrote, analyzed, and tested, is exactly what gets executed. This ensures that the code developers wrote, analyzed, and tested, is exactly what gets executed. This ensures that the code developers wrote, analyzed, and tested, is exactly what gets executed. - -[Read more about Clarity](../write-smart-contracts/clarity-language/) - -## Guides - -Read one of our guides to understand the ins and outs of the Stacks 2.0 blockchain. - -* [Account](../understand-stacks/accounts) -* [Transactions](../understand-stacks/transactions) -* [Network](../understand-stacks/network) -* [Microblocks](../understand-stacks/microblocks) - -[comparison of the Stacks blockchain to other blockchain technologies]: https://stacks.org/stacks-blockchain diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md b/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md deleted file mode 100644 index bebabd304f..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/microblocks.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: Microblocks -description: Guide to Stacks Microblocks -sidebar_position: 8 ---- - -## Introduction - -Microblocks are a protocol-level feature of the Stacks blockchain that solve the technical challenge of transaction latency. Microblocks are a protocol-level feature of the Stacks blockchain that solve the technical challenge of transaction latency. Because each Stacks block is anchored to a Bitcoin block through the [Proof-of-Transfer consensus mechanism](../understand-stacks/proof-of-transfer), Stacks is necessarily limited to the same block times as the Bitcoin network. Microblocks allow the Stacks blockchain to perform state transitions between anchor blocks. Microblocks allow the Stacks blockchain to perform state transitions between anchor blocks. Microblocks are a protocol-level feature of the Stacks blockchain that solve the technical challenge of transaction latency. Because each Stacks block is anchored to a Bitcoin block through the [Proof-of-Transfer consensus mechanism](../understand-stacks/proof-of-transfer), Stacks is necessarily limited to the same block times as the Bitcoin network. Microblocks allow the Stacks blockchain to perform state transitions between anchor blocks. Microblocks allow the Stacks blockchain to perform state transitions between anchor blocks. - -Microblocks are a powerful mechanism for developers to create performant, high quality applications on Stacks, while still inheriting the security of Bitcoin. - -## Transaction states - -The [Stacks block production model](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.) is described in SIP-001. The standard outlines the mechanism by which elected block leaders can produce blocks on the Stacks blockchain either by batching transactions or by streaming them. Microblocks are the product of the streaming model. The standard outlines the mechanism by which elected block leaders can produce blocks on the Stacks blockchain either by batching transactions or by streaming them. Microblocks are the product of the streaming model. The standard outlines the mechanism by which elected block leaders can produce blocks on the Stacks blockchain either by batching transactions or by streaming them. Microblocks are the product of the streaming model. - -If a block leader has elected to mine microblocks, the leader selects transactions from the mempool and package them into microblocks during the current epoch. Microblocks are blocks of transactions included by a miner after the previous anchor block has been mined, but before the next block is selected. Transactions included in microblocks are processed by the network: their results are known. Microblocks are blocks of transactions included by a miner after the previous anchor block has been mined, but before the next block is selected. Transactions included in microblocks are processed by the network: their results are known. Microblocks are blocks of transactions included by a miner after the previous anchor block has been mined, but before the next block is selected. Transactions included in microblocks are processed by the network: their results are known. Microblocks are blocks of transactions included by a miner after the previous anchor block has been mined, but before the next block is selected. Transactions included in microblocks are processed by the network: their results are known. - -Consider a transaction from the perspective of the number of block confirmations it has. Consider a transaction from the perspective of the number of block confirmations it has. A transaction included in a microblock might have the following example lifecycle: Consider a transaction from the perspective of the number of block confirmations it has. A transaction included in a microblock might have the following example lifecycle: Consider a transaction from the perspective of the number of block confirmations it has. A transaction included in a microblock might have the following example lifecycle: - -``` -Transaction 1 is broadcast to the mempool. It has 0 confirmations. -Transaction 1 is included in a microblock. It still has 0 confirmations, but the results of the transaction are known -Transaction 1 is included in the next anchor block. It has 1 confirmation. -The next Stacks block confirms the previous block. Transaction 1 has 2 confirmations. -The next Stacks block confirms the previous block. Transaction 1 has 3 confirmations. -... -``` - -Consider a similar transaction that is not included in a microblock: - -``` -Transaction 2 is broadcast to the mempool. It has 0 confirmations. -Transaction 2 is included in the next anchor block. It has 1 confirmation. -The next Stacks block confirms the previous block. Transaction 2 has 2 confirmations. -The next Stacks block confirms the previous block. Transaction 2 has 3 confirmations. -``` - -The lifecycles of the two transactions are similar, but the difference is pending state. Many Bitcoin wallets display 0-confirmation balances: your wallet balance with any mempool transactions already applied. This is useful because it tells you when you've sent a transaction or received one. With smart contracts, displaying pending state is not as straightforward, because smart contracts do not just transfer inputs to outputs, they may call other contracts, emit events, or perform other computations. A transaction processed in a microblock generates all that information. - -:::tip -If a transaction is dependent on a chain state that could by altered by previous transactions with serious -implications, you should carefully consider whether it should be performed using microblocks. -::: ::: -::: - -## Enabling microblocks - -Miners can choose to enable or disable microblocks in their mining configuration. As a best practice, miners should enable microblock mining. When an application or user submits a transaction, the transaction can include an argument that requires the transaction to be in a microblock, an anchor block, or in either. As a best practice, miners should enable microblock mining. When an application or user submits a transaction, the transaction can include an argument that requires the transaction to be in a microblock, an anchor block, or in either. As a best practice, miners should enable microblock mining. When an application or user submits a transaction, the transaction can include an argument that requires the transaction to be in a microblock, an anchor block, or in either. As a best practice, miners should enable microblock mining. When an application or user submits a transaction, the transaction can include an argument that requires the transaction to be in a microblock, an anchor block, or in either. - -### Transactions - -Transactions include an option that controls if a miner should include them in microblocks or in anchor blocks. Transactions include an option that controls if a miner should include them in microblocks or in anchor blocks. The anchor mode transaction option is an optional argument that controls whether a transaction must be included in an anchor block or a microblock, or is eligible for either. Transactions include an option that controls if a miner should include them in microblocks or in anchor blocks. The anchor mode transaction option is an optional argument that controls whether a transaction must be included in an anchor block or a microblock, or is eligible for either. Transactions include an option that controls if a miner should include them in microblocks or in anchor blocks. The anchor mode transaction option is an optional argument that controls whether a transaction must be included in an anchor block or a microblock, or is eligible for either. - -### Mining - -Stacks miners must enable microblocks in their miner configuration to implement the block streaming model. For more information, see [mining microblocks][]. For more information, see [mining microblocks](../understand-stacks/mining#microblocks). For more information, see [mining microblocks](../understand-stacks/mining#microblocks). For more information, see [mining microblocks](../understand-stacks/mining#microblocks). - -## Developing with microblocks - -In most cases, information from transactions included in microblocks should be treated like information from any other block. Wallets and explorers should display the consequences of microblock transactions as the current state of the network. This state should be acknowledged as tentative. In most cases, information from transactions included in microblocks should be treated like information from any other block. Wallets and explorers should display the consequences of microblock transactions as the current state of the network. This state should be acknowledged as tentative. In most cases, information from transactions included in microblocks should be treated like information from any other block. Wallets and explorers should display the consequences of microblock transactions as the current state of the network. This state should be acknowledged as tentative. Wallets and explorers should display the consequences of microblock transactions as the current state of the network. This state should be acknowledged as tentative. This state should be acknowledged as tentative. This state should be acknowledged as tentative. - -A microblock transaction can end up being reorganized in the next block rather than just being confirmed as-is. Because of this, your UI should communicate to users if the outputs of a transaction changed, or if the transaction's associated block changed. This is the same outcome as if a 1-block fork occurred. Because of this, your UI should communicate to users if the outputs of a transaction changed, or if the transaction's associated block changed. This is the same outcome as if a 1-block fork occurred. Because of this, your UI should communicate to users if the outputs of a transaction changed, or if the transaction's associated block changed. This is the same outcome as if a 1-block fork occurred. Because of this, your UI should communicate to users if the outputs of a transaction changed, or if the transaction's associated block changed. This is the same outcome as if a 1-block fork occurred. - -### Stacks.js libraries - -Stacks.js provides the [AnchorMode][] argument on transaction objects so that your application can set the microblocks preference for transactions. - -### API - -:::danger API support for microblocks is a work-in-progress. :::danger API support for microblocks is a work-in-progress. Review the [API documentation][microblocks_api] carefully to ensure that you are up-to-date on the latest implementation details for microblocks. ::: ::: :::danger API support for microblocks is a work-in-progress. Review the [API documentation][microblocks_api] carefully to ensure that you are up-to-date on the latest implementation details for microblocks. ::: ::: - -The Stacks Blockchain API exposes microblocks through several endpoints. The Stacks Blockchain API exposes microblocks through several endpoints. Please review the [Stacks Blockchain API guide][] for more details. The Stacks Blockchain API exposes microblocks through several endpoints. Please review the [Stacks Blockchain API guide][] for more details. - -## Best practices - -Working with microblocks is a design decision that you must make for your own application. When working with microblocks, the following best practices are recommended. Working with microblocks is a design decision that you must make for your own application. When working with microblocks, the following best practices are recommended. When working with microblocks, the following best practices are recommended. Working with microblocks is a design decision that you must make for your own application. When working with microblocks, the following best practices are recommended. When working with microblocks, the following best practices are recommended. - -### Handling nonce - -Nonce handling with microblocks is challenging because the next account nonce must take into account any nonce values included in microblocks, which may not yet be included in an anchor block. The Stacks Blockchain API [provides an endpoint][] to retrieve the next nonce for a given principal. The Stacks Blockchain API [provides an endpoint][] to retrieve the next nonce for a given principal. The Stacks Blockchain API [provides an endpoint][] to retrieve the next nonce for a given principal. - -### Application design - -The state of microblock transactions should be carefully communicated to users. The state of microblock transactions should be carefully communicated to users. No transaction is final until it's included in an anchor block, and your application design should reflect this. The state of microblock transactions should be carefully communicated to users. No transaction is final until it's included in an anchor block, and your application design should reflect this. The state of microblock transactions should be carefully communicated to users. No transaction is final until it's included in an anchor block, and your application design should reflect this. - -The following guidelines are provided as an initial set of best practices for UI design when incorporating microblocks into your application. - -#### Explorers - -Display pending state, but warn that a transaction is still pending. Indicate visually that displayed balances depend on pending state. Indicate visually that displayed balances depend on pending state. Display pending state, but warn that a transaction is still pending. Indicate visually that displayed balances depend on pending state. Indicate visually that displayed balances depend on pending state. Indicate visually that displayed balances depend on pending state. - -#### Wallets - -Display pending state, but warn that a transaction is still pending. Indicate visually that displayed balances depend on pending state. Indicate visually that displayed balances depend on pending state. Display pending state, but warn that a transaction is still pending. Indicate visually that displayed balances depend on pending state. Indicate visually that displayed balances depend on pending state. Indicate visually that displayed balances depend on pending state. - -#### Exchanges - -Continue to count confirmations, microblocks should be considered pending. - -#### Applications - -Microblock communication is highly app-dependent. For some applications, displaying a pending or 0-confirmation transaction as confirmed may be fine. For example, storing data on the chain, or querying the BNS contract. For other applications, such as the transfer of real value, waiting for 3-confirmations would be prudent before displaying the state as confirmed. - -[AnchorMode]: https://stacks.js.org/enums/transactions.AnchorMode.html -[Stacks Blockchain API guide]: https://docs.hiro.so/get-started/stacks-blockchain-api#microblocks-support -[mining microblocks]: /understand-stacks/mining#microblocks -[microblocks_api]: https://docs.hiro.so/api#tag/Microblocks -[provides an endpoint]: https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/mining.md b/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/mining.md deleted file mode 100644 index a039ecb015..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/mining.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: Mining -description: A guide to mining on Stacks 2.0 -sidebar_position: 4 ---- - -## Introduction - -This guide highlights some technical details related to mining on the Stacks 2.0 network. - -For steps on how to setup your own miner please refer to [miner on tesnet](nodes-and-miners/miner-testnet.md) and [miner on mainnet](nodes-and-miners/miner-testnet.md). - -## Mining frequency - -A new Stacks block may be mined once per Bitcoin block. To be considered for mining a block, a miner must have a block commit included in a Bitcoin block. If a miner wishes to update their commitment after submission, they may use Bitcoin Replace-By-Fee. To be considered for mining a block, a miner must have a block commit included in a Bitcoin block. If a miner wishes to update their commitment after submission, they may use Bitcoin Replace-By-Fee. To be considered for mining a block, a miner must have a block commit included in a Bitcoin block. If a miner wishes to update their commitment after submission, they may use Bitcoin Replace-By-Fee. To be considered for mining a block, a miner must have a block commit included in a Bitcoin block. If a miner wishes to update their commitment after submission, they may use Bitcoin Replace-By-Fee. - -## Coinbase rewards - -Miners receive coinbase rewards for blocks they win. - -The reward amounts are: - -- 1000 STX per block are released in the first 4 years of mining -- 500 STX per block are released during the following 4 years -- 250 STX per block are released during the following 4 years -- 125 STX per block are released from then on indefinitely. - -These "halvings" are synchronized with Bitcoin halvings. - -![coinbase rewards](/img/pages/coinbase-rewards.png) - -## Transaction fees - -Miners receive Stacks fees for transactions mined in any block they produce. - -For transactions mined in microblocks, the miner that produces the microblock receives 40% of the fees, while the miner that confirms the microblock receives 60% of the fees. - -## Reward maturity - -Block rewards and transaction fees take 100 blocks on the Bitcoin blockchain to mature. Block rewards and transaction fees take 100 blocks on the Bitcoin blockchain to mature. After successfully mining a block your rewards appear in your Stacks account after ~24 hours. Block rewards and transaction fees take 100 blocks on the Bitcoin blockchain to mature. After successfully mining a block your rewards appear in your Stacks account after ~24 hours. Block rewards and transaction fees take 100 blocks on the Bitcoin blockchain to mature. After successfully mining a block your rewards appear in your Stacks account after ~24 hours. - -## Mining with proof-of-transfer - -Miners commit Bitcoin to **two** addresses in every leader block commit. The amount committed to each address must be the same. The addresses are chosen from the current reward set of stacking participants. Addresses are chosen using a verifiable-random-function, and determining the correct two addresses for a given block requires monitoring the Stacks chain. The amount committed to each address must be the same. The addresses are chosen from the current reward set of stacking participants. Addresses are chosen using a verifiable-random-function, and determining the correct two addresses for a given block requires monitoring the Stacks chain. The amount committed to each address must be the same. The addresses are chosen from the current reward set of stacking participants. Addresses are chosen using a verifiable-random-function, and determining the correct two addresses for a given block requires monitoring the Stacks chain. The amount committed to each address must be the same. The addresses are chosen from the current reward set of stacking participants. Addresses are chosen using a verifiable-random-function, and determining the correct two addresses for a given block requires monitoring the Stacks chain. - -![mining with pox](/img/pages/mining-with-pox.png) - -## 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, 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. - -While there is no minimum BTC commitment enforced by the protocol, in practice, there's a floor constrained by [dust](https://unchained-capital.com/blog/dust-thermodynamics/)": basically, if the fees for a transaction exceed the value of the spent output, it's considered dust. How dust is [calculated](https://github.com/bitcoin/bitcoin/blob/master/src/policy/policy.cpp#L14) depends on a number of factors, we've found 5,500 satoshis to be good lower bound per [output](https://learnmeabitcoin.com/technical/output). Bitcoin transactions from Stacks miners contain two outputs (for Proof-of-Transfer), so a commitment of at least 11,000 satoshis / block is recommended. While there is no minimum BTC commitment enforced by the protocol, in practice, there's a floor constrained by [dust](https://unchained-capital.com/blog/dust-thermodynamics/)": basically, if the fees for a transaction exceed the value of the spent output, it's considered dust. How dust is [calculated](https://github.com/bitcoin/bitcoin/blob/master/src/policy/policy.cpp#L14) depends on a number of factors, we've found 5,500 satoshis to be good lower bound per [output](https://learnmeabitcoin.com/technical/output). Bitcoin transactions from Stacks miners contain two outputs (for Proof-of-Transfer), so a commitment of at least 11,000 satoshis / block is recommended. While there is no minimum BTC commitment enforced by the protocol, in practice, there's a floor constrained by [dust](https://unchained-capital.com/blog/dust-thermodynamics/)": basically, if the fees for a transaction exceed the value of the spent output, it's considered dust. How dust is [calculated](https://github.com/bitcoin/bitcoin/blob/master/src/policy/policy.cpp#L14) depends on a number of factors, we've found 5,500 satoshis to be good lower bound per [output](https://learnmeabitcoin.com/technical/output). Bitcoin transactions from Stacks miners contain two outputs (for Proof-of-Transfer), so a commitment of at least 11,000 satoshis / block is recommended. How dust is [calculated](https://github.com/bitcoin/bitcoin/blob/master/src/policy/policy.cpp#L14) depends on a number of factors, we've found 5,500 satoshis to be good lower bound per [output](https://learnmeabitcoin.com/technical/output). Bitcoin transactions from Stacks miners contain two outputs (for Proof-of-Transfer), so a commitment of at least 11,000 satoshis / block is recommended. Bitcoin transactions from Stacks miners contain two outputs (for Proof-of-Transfer), so a commitment of at least 11,000 satoshis / block is recommended. Bitcoin transactions from Stacks miners contain two outputs (for Proof-of-Transfer), so a commitment of at least 11,000 satoshis / block is recommended. - -To calculate the amount of BTC to send miners should: - -- Guess the price BTC/STX for the next day (100 blocks later) -- Guess the total amount of BTCs committed by all miners - -## Microblocks - -The Stacks blockchain produces blocks at the same rate as the Bitcoin blockchain. In order to provide lower latency transactions, miners can opt to enable microblocks. Microblocks allow the current block leader to stream transactions and include their state transitions in the current epoch. In order to provide lower latency transactions, miners can opt to enable microblocks. Microblocks allow the current block leader to stream transactions and include their state transitions in the current epoch. In order to provide lower latency transactions, miners can opt to enable microblocks. Microblocks allow the current block leader to stream transactions and include their state transitions in the current epoch. In order to provide lower latency transactions, miners can opt to enable microblocks. Microblocks allow the current block leader to stream transactions and include their state transitions in the current epoch. - -If a block leader opts to produce microblocks, the next leader builds the chain tip off the last microblock that the current leader produces. - -The block streaming model is described in [SIP-001][]. - -[SIP-001]: https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md#operation-as-a-leader diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/network.md b/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/network.md deleted file mode 100644 index 4b104de061..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/network.md +++ /dev/null @@ -1,152 +0,0 @@ ---- -title: Network -description: Guide to the Stacks 2.0 network -sidebar_position: 7 ---- - -## Tokens - -Stacks (STX) tokens are the native tokens on the Stacks 2.0 blockchain. The smallest fraction is one micro-STX. 1,000,000 micro-STX make one Stacks (STX). The smallest fraction is one micro-STX. 1,000,000 micro-STX make one Stacks (STX). The smallest fraction is one micro-STX. 1,000,000 micro-STX make one Stacks (STX). The smallest fraction is one micro-STX. 1,000,000 micro-STX make one Stacks (STX). - -STX amounts should be stored as integers (8 bytes long), and represent the amount of micro-STX. For display purposes, micro-STX are divided by 1,000,000 (decimal precision of 6). For display purposes, micro-STX are divided by 1,000,000 (decimal precision of 6). For display purposes, micro-STX are divided by 1,000,000 (decimal precision of 6). For display purposes, micro-STX are divided by 1,000,000 (decimal precision of 6). - -## 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 in bytes. The fee rate is a market determined variable. For the [testnet](/understand-stacks/testnet), it is set to 1 micro-STX. The fee is calculated based on the estimate fee rate and the size of the raw transaction in bytes. The fee rate is a market determined variable. For the [testnet](testnet), it is set to 1 micro-STX. - -Fee estimates can obtained through the [`GET /v2/fees/transfer`](https://docs.hiro.so/api#operation/get_fee_transfer) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/fees/transfer' -``` - -The API will respond with the fee rate (as integer): - -```json -1 -``` - -[The Stacks Transactions JS library](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) supports fee estimation for: - -- token transfers (`estimateTransfer`) -- contract deploys (`estimateContractDeploy`) -- non read-only contract calls (`estimateContractFunctionCall`) - -:::tip For an implementation using a different language than JavaScript, please review [this reference implementation](https://github.com/hirosystems/stacks.js/blob/master/packages/transactions/src/builders.ts#L97). ::: ::: ::: - -## Nonces - -Every account carries a [nonce property](https://en.wikipedia.org/wiki/Cryptographic_nonce) that indicates the number of transactions processed for the given account. Nonces are one-time codes, starting at `0` for new accounts, and incremented by 1 on every transaction. Nonces are one-time codes, starting at `0` for new accounts, and incremented by 1 on every transaction. Nonces are one-time codes, starting at `0` for new accounts, and incremented by 1 on every transaction. Nonces are one-time codes, starting at `0` for new accounts, and incremented by 1 on every transaction. - -Nonces are added to all transactions and help identify them in order to ensure transactions are processed in order and to avoid duplicated processing. - -:::tip -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. -::: 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 is constructed, the most recent nonce of the account needs to fetched and set. - -:::tip The API provides an endpoint to [simplify nonce handling](https://docs.hiro.so/get-started/stacks-blockchain-api#nonce-handling). ::: ::: ::: - -## Confirmations - -The Stacks 2.0 network is anchored onto the bitcoin network. This allows transactions on Stacks to inherit the same finality and security of the Bitcoin blockchain. This allows transactions on Stacks to inherit the same finality and security of the Bitcoin blockchain. This allows transactions on Stacks to inherit the same finality and security of the Bitcoin blockchain. This allows transactions on Stacks to inherit the same finality and security of the Bitcoin blockchain. - -The time to mine a block, to confirm transactions, will eventually match the expected "block time" of the bitcoin network: 10 minutes. - -:::tip Transactions can also be mined in [microblocks](microblocks), reducing the latency significantly. ::: ::: ::: - -The block time is hardcoded and will change throughout the implementation phases of the [testnet](testnet). The block time is hardcoded and will change throughout the implementation phases of the [testnet](testnet). 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://docs.hiro.so/api#operation/get_network_block_times) endpoint: The block time is hardcoded and will change throughout the implementation phases of the [testnet](testnet). 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://docs.hiro.so/api#operation/get_network_block_times) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/extended/v1/info/network_block_times' -``` - -The API will respond with the block time (in seconds): - -```js -{ - "testnet": { - "target_block_time": 120 - }, - "mainnet": { - "target_block_time": 600 - } -} -``` - -## Read-only function calls - -Smart contracts can expose public function calls. Smart contracts can expose public function calls. For functions that make state modifications to the blockchain, transactions need to be generated and broadcasted. Smart contracts can expose public function calls. For functions that make state modifications to the blockchain, transactions need to be generated and broadcasted. Smart contracts can expose public function calls. For functions that make state modifications to the blockchain, transactions need to be generated and broadcasted. - -However, for read-only function calls, transactions are **not** required. Instead, these calls can be done using the [Stacks Blockchain API](https://docs.hiro.so/get-started/stacks-blockchain-api). However, for read-only function calls, transactions are **not** required. Instead, these calls can be done using the [Stacks Blockchain API](https://docs.hiro.so/get-started/stacks-blockchain-api). Instead, these calls can be done using the [Stacks Blockchain API](https://docs.hiro.so/get-started/stacks-blockchain-api). However, for read-only function calls, transactions are **not** required. Instead, these calls can be done using the [Stacks Blockchain API](https://docs.hiro.so/get-started/stacks-blockchain-api). Instead, these calls can be done using the [Stacks Blockchain API](https://docs.hiro.so/get-started/stacks-blockchain-api). - -:::tip -Read-only function calls do not require transaction fees -::: - -A read-only contract call can be done using the [`POST /v2/contracts/call-read///`](https://docs.hiro.so/api#operation/call_read_only_function) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl --location --request POST 'https://stacks-node-api.testnet.stacks.co/v2/contracts/call-read///' \ ---header 'Content-Type: application/json' \ ---data-raw '{ - "sender": ".", - "arguments": [, ...] -}' -}' -}' -}' -``` - -Sample response for a successful call: - -```js -{ - "okay": true, - "result": "" -} -``` - -:::tip To set the function call arguments and read the result, [Clarity values](../write-smart-contracts/values) need to be serialized into a hexadecimal string. The [Stacks Transactions JS](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library supports these operations ::: The [Stacks Transactions JS](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library supports these operations ::: The [Stacks Transactions JS](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library supports these operations ::: - -## Querying - -Stacks 2.0 network details can be queried using the [Stacks Blockchain API](https://docs.hiro.so/get-started/stacks-blockchain-api). - -### Health check - -The [status checker](https://stacks-status.com/) is a service that provides a user interface to quickly review the health of the Stacks 2.0 blockchain. - -### Network info - -The network information can be obtained using the [`GET /v2/info`](https://docs.hiro.so/api#operation/get_core_api_info) endpoint: - -```bash -# for mainnet, replace `testnet` with `mainnet` -curl 'https://stacks-node-api.testnet.stacks.co/v2/info' -``` - -Sample response: - -```js -{ - "peer_version": 385875968, - "burn_consensus": "826401d65cf3671210a3fb135d827d549c0b4d37", - "burn_block_height": 1972, - "stable_burn_consensus": "e27ea23f199076bc41a729d76a813e125b725f64", - "stable_burn_block_height": 1971, - "server_version": "blockstack-core 0.0.1 => 23.0.0.0 (master:bdd042242+, release build, linux [x86_64]", - "network_id": 2147483648, - "parent_network_id": 3669344250, - "stacks_tip_height": 933, - "stacks_tip": "1f601823fbcc5b6b2215b2ff59d2818fba61ee4a3cea426d8bc3dbb268005d8f", - "stacks_tip_burn_block": "54c56a9685545c45accf42b5dcb2787c97eda8185a1c794daf9b5a59d4807abc", - "unanchored_tip": "71948ee211dac3b241eb65d881637f649d0d49ac08ee4a41c29217d3026d7aae", - "exit_at_block_height": 28160 -} -``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md b/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md deleted file mode 100644 index 11a2a2e0fc..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/proof-of-transfer.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Proof of Transfer -description: Understand the proof-of-transfer consensus mechanism -sidebar_position: 3 ---- - -## Overview - -Consensus algorithms for blockchains require compute or financial resources to secure the blockchain. The general practice of decentralized consensus is to make it practically infeasible for any single malicious actor to have enough computing power or ownership stake to attack the network. The general practice of decentralized consensus is to make it practically infeasible for any single malicious actor to have enough computing power or ownership stake to attack the network. The general practice of decentralized consensus is to make it practically infeasible for any single malicious actor to have enough computing power or ownership stake to attack the network. The general practice of decentralized consensus is to make it practically infeasible for any single malicious actor to have enough computing power or ownership stake to attack the network. - -Popular consensus mechanisms in modern blockchains include proof-of-work, in which nodes dedicate computing resources, and proof-of-stake, in which nodes dedicate financial resources to secure the network. - -Proof-of-burn is a novel consensus mechanism where miners compete by ‘burning’ (destroying) a proof-of-work cryptocurrency as a proxy for computing resources. - -Proof-of-transfer (PoX) is an extension of the proof-of-burn mechanism. Proof-of-transfer (PoX) is an extension of the proof-of-burn mechanism. 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. 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 to secure the PoX cryptocurrency network and earn a reward in the base cryptocurrency. Thus, proof-of-transfer blockchains are anchored on their chosen proof-of-work chain. Stacks uses [Bitcoin](#why-bitcoin) as its anchor chain. Thus, proof-of-transfer blockchains are anchored on their chosen proof-of-work chain. Stacks uses [Bitcoin](#why-bitcoin) as its anchor chain. However, unlike proof-of-burn, rather than burning the cryptocurrency, miners transfer the committed cryptocurrency to some other participants in the network. - -![PoX mechanism](/img/pox-mechanism.png) - -This allows network participants to secure the PoX cryptocurrency network and earn a reward in the base cryptocurrency. Thus, proof-of-transfer blockchains are anchored on their chosen proof-of-work chain. Stacks uses [Bitcoin](#why-bitcoin) as its anchor chain. Thus, proof-of-transfer blockchains are anchored on their chosen proof-of-work chain. Stacks uses [Bitcoin](#why-bitcoin) as its anchor chain. - -![PoX participants](/img/pox-participants.png) - -## Why Bitcoin? - -There are a number of reasons that Stacks chose Bitcoin as the blockchain to power consensus. It's the oldest blockchain protocol, having launched in 2009, and has become a recognized asset outside of the cryptocurrency community. BTC has held the highest market capitalization of any cryptocurrency for the past decade. It's the oldest blockchain protocol, having launched in 2009, and has become a recognized asset outside of the cryptocurrency community. BTC has held the highest market capitalization of any cryptocurrency for the past decade. It's the oldest blockchain protocol, having launched in 2009, and has become a recognized asset outside of the cryptocurrency community. BTC has held the highest market capitalization of any cryptocurrency for the past decade. It's the oldest blockchain protocol, having launched in 2009, and has become a recognized asset outside of the cryptocurrency community. BTC has held the highest market capitalization of any cryptocurrency for the past decade. - -Bitcoin champions simplicity and stability, and has stood the test of time. Influencing or attacking the network is infeasible or impractical for any potential hackers. It's one of the only cryptocurrencies to capture public attention. Bitcoin is a household name, and is recognized as an asset by governments, large corporations, and legacy banking institutions. Lastly, Bitcoin is largely considered a reliable store of value, and provides extensive infrastructure to support the proof-of-transfer consensus mechanism. Influencing or attacking the network is infeasible or impractical for any potential hackers. It's one of the only cryptocurrencies to capture public attention. Bitcoin is a household name, and is recognized as an asset by governments, large corporations, and legacy banking institutions. Lastly, Bitcoin is largely considered a reliable store of value, and provides extensive infrastructure to support the proof-of-transfer consensus mechanism. - -SIP-001 provides a full [list of reasons why Bitcoin was chosen to secure Stacks](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md). - -![btc-stacks](/img/pox-why-bitcoin.png) - -## Blocks and microblocks - -The Stacks blockchain allows for increased transaction throughput using a mechanism called microblocks. The Stacks blockchain allows for increased transaction throughput using a mechanism called microblocks. Bitcoin and Stacks progress in lockstep, and their blocks are confirmed simultaneously. On Stacks, this is referred to as an ‘anchor block’. An entire block of Stacks transactions corresponds to a single Bitcoin transaction. This significantly improves cost/byte ratio for processing Stacks transactions. Because of simultaneous block production, Bitcoin acts as a rate-limiter for creating Stacks blocks, thereby preventing denial-of-service attacks on its peer network. On Stacks, this is referred to as an ‘anchor block’. An entire block of Stacks transactions corresponds to a single Bitcoin transaction. This significantly improves cost/byte ratio for processing Stacks transactions. Because of simultaneous block production, Bitcoin acts as a rate-limiter for creating Stacks blocks, thereby preventing denial-of-service attacks on its peer network. - -However, in between Stacks anchor blocks settling on the Bitcoin blockchain, there are also a varying number of microblocks that allow rapid settlement of Stacks transactions with a high degree of confidence. This allows Stacks transaction throughput to scale independently of Bitcoin, while still periodically establishing finality with the Bitcoin chain. The Stacks blockchain adopts a block streaming model whereby each leader can adaptively select and package transactions into their block as they arrive in the mempool. Therefore when an anchor block is confirmed, all of the transactions in the parent microblock stream are packaged and processed. This is an unprecedented method for achieving scalability without creating a totally separate protocol from Bitcoin. This allows Stacks transaction throughput to scale independently of Bitcoin, while still periodically establishing finality with the Bitcoin chain. The Stacks blockchain adopts a block streaming model whereby each leader can adaptively select and package transactions into their block as they arrive in the mempool. Therefore when an anchor block is confirmed, all of the transactions in the parent microblock stream are packaged and processed. This is an unprecedented method for achieving scalability without creating a totally separate protocol from Bitcoin. - -![stx-microblock](/img/stx-microblocks.png) - -## Unlocking Bitcoin capital - -Stacks also unlocks the hundreds of billions in capital in Bitcoin, and gives Bitcoiners new opportunities to use and earn BTC. Stacks is a accompaniment to the Bitcoin ecosystem, and the two networks working in tandem enables totally novel ways of using BTC. The Stacks ecosystem makes interactive cryptocurrency applications available to Bitcoin holders. Additionally, By stacking STX tokens and participating in the PoX consensus mechanism, users have the opportunity to earn BTC while securing the Stacks chain. Stacks is a accompaniment to the Bitcoin ecosystem, and the two networks working in tandem enables totally novel ways of using BTC. The Stacks ecosystem makes interactive cryptocurrency applications available to Bitcoin holders. Additionally, by stacking STX tokens and participating in the PoX consensus mechanism, users have the opportunity to earn BTC while securing the Stacks chain. Stacks is a accompaniment to the Bitcoin ecosystem, and the two networks working in tandem enables totally novel ways of using BTC. The Stacks ecosystem makes interactive cryptocurrency applications available to Bitcoin holders. Additionally, by stacking STX tokens and participating in the PoX consensus mechanism, users have the opportunity to earn BTC while securing the Stacks chain. Stacks is a accompaniment to the Bitcoin ecosystem, and the two networks working in tandem enables totally novel ways of using BTC. The Stacks ecosystem makes interactive cryptocurrency applications available to Bitcoin holders. Additionally, by stacking STX tokens and participating in the PoX consensus mechanism, users have the opportunity to earn BTC while securing the Stacks chain. - -![Unlocking Bitcoin](/img/pox-unlocking-btc.png) - -## Clarity and the Bitcoin state - -Clarity smart contracts also have unique visibility into the state of the Bitcoin blockchain. This means that contract logic in a Clarity file has the ability to trigger when specific Bitcoin transactions are confirmed. Clarity smart contracts also have unique visibility into the state of the Bitcoin blockchain. This means that contract logic in a Clarity file has the ability to trigger when specific Bitcoin transactions are confirmed. Clarity smart contracts also have unique visibility into the state of the Bitcoin blockchain. This means that contract logic in a Clarity file has the ability to trigger when specific Bitcoin transactions are confirmed. Clarity smart contracts have a built in Simple Payment Verification (SPV) proofs for Bitcoin that make interacting with Bitcoin’s state much simpler for developers. Additionally, Clarity contracts can fork with the original Bitcoin chain. Therefore, in an edge case where Bitcoin forks, developers wouldn’t have to worry about adjusting the deployment of their smart contracts. Additionally, Clarity contracts can fork with the original Bitcoin chain. Therefore, in an edge case where Bitcoin forks, developers wouldn’t have to worry about adjusting the deployment of their smart contracts. Additionally, Clarity contracts can fork with the original Bitcoin chain. Therefore, in an edge case where Bitcoin forks, developers wouldn’t have to worry about adjusting the deployment of their smart contracts. This means that contract logic in a Clarity file has the ability to trigger when specific Bitcoin transactions are confirmed. Clarity smart contracts also have unique visibility into the state of the Bitcoin blockchain. This means that contract logic in a Clarity file has the ability to trigger when specific Bitcoin transactions are confirmed. Clarity smart contracts also have unique visibility into the state of the Bitcoin blockchain. This means that contract logic in a Clarity file has the ability to trigger when specific Bitcoin transactions are confirmed. Clarity smart contracts have a built in Simple Payment Verification (SPV) proofs for Bitcoin that make interacting with Bitcoin’s state much simpler for developers. Additionally, Clarity contracts can fork with the original Bitcoin chain. Therefore, in an edge case where Bitcoin forks, developers wouldn’t have to worry about adjusting the deployment of their smart contracts. Additionally, Clarity contracts can fork with the original Bitcoin chain. Therefore, in an edge case where Bitcoin forks, developers wouldn’t have to worry about adjusting the deployment of their smart contracts. Additionally, Clarity contracts can fork with the original Bitcoin chain. Therefore, in an edge case where Bitcoin forks, developers wouldn’t have to worry about adjusting the deployment of their smart contracts. - -## See also - -- [Read the full PoX whitepaper](https://community.stacks.org/pox) -- [Watch Executive Chair of Hiro Muneeb Ali and Evangelist Joe Bender give an overview of Stack's breakthrough PoX mining mechanism](https://www.youtube.com/watch?v=NY_eUrIcWOY) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md b/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md deleted file mode 100644 index 50a05c578b..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/stacking.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: Stacking -description: Introduction to the reward mechanism of Proof-of-Transfer -sidebar_position: 9 ---- - -## Introduction - -Stacking rewards Stacks (STX) token holders with bitcoin for providing a valuable service to the network by locking up their tokens for a certain time. - -![](/img/stacking.png) - -Stacking is a built-in action, required by the "proof-of-transfer" (PoX) mechanism. Stacking is a built-in action, required by the "proof-of-transfer" (PoX) mechanism. 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. - -:::info The Stacking consensus algorithm is implemented as a smart contract, using [Clarity](../write-smart-contracts/). [Read more about the contract](../noteworthy-contracts/stacking-contract). ::: [Read more about the contract](../noteworthy-contracts/stacking-contract). ::: [Read more about the contract](../noteworthy-contracts/stacking-contract). ::: - -## Stacking flow - -The Stacking mechanism can be presented as a flow of actions: - -![Stacking flow](/img/stacking-illustration.png) - -1. Make API calls to get details about the upcoming reward cycle -2. For a specific Stacks account, confirm eligibility -3. Confirm the BTC reward address and the lockup duration -4. The transaction is broadcasted and the STX tokens are locked. This needs to happen before the prepare phase of the next reward cycle, the last 100 Bitcoin blocks of the ongoing reward phase The transaction is broadcasted and the STX tokens are locked. This needs to happen before the prepare phase of the next reward cycle, the last 100 Bitcoin blocks of the ongoing reward phase This needs to happen before the prepare phase of the next reward cycle, the last 100 Bitcoin blocks of the ongoing reward phase The transaction is broadcasted and the STX tokens are locked. This needs to happen before the prepare phase of the next reward cycle, the last 100 Bitcoin blocks of the ongoing reward phase This needs to happen before the prepare phase of the next reward cycle, the last 100 Bitcoin blocks of the ongoing reward phase -5. The Stacking mechanism executes reward cycles and sends out rewards to the set BTC reward address -6. During the lockup period, details about unlocking timing, rewards and more can be obtained -7. Once the lockup period is passed, the tokens are released and accessible again -8. Display reward history, including details like earnings for previous reward cycles - -:::info Keep in mind that the target duration for a reward cycles is ~2 weeks. -> Keep in mind that the target duration for a reward cycles is ~2 weeks. This duration is based on the target block time of the network (10 minutes) and can be higher at times due to [confirmation time variances](https://www.blockchain.com/charts/median-confirmation-time) of the bitcoin network. ::: -> Keep in mind that the target duration for a reward cycles is ~2 weeks. This duration is based on the target block time of the network (10 minutes) and can be higher at times due to [confirmation time variances](https://www.blockchain.com/charts/median-confirmation-time) of the bitcoin network. ::: - -## Stacking delegation flow - -The Stacking flow is different for delegation use cases: - -![Delegated tacking flow](/img/stacking-delegation-illustration.png) - -- Before Stacking can be initiated for a token holder, the delegator needs to be granted permission to Stack on behalf of the account owner. The permission is restricted to the maximum amount the delegator is allowed to Stack. The maximum amount is not limited by the available funds and can be set much higher. An account can only be associated with one single delegator The permission is restricted to the maximum amount the delegator is allowed to Stack. The maximum amount is not limited by the available funds and can be set much higher. An account can only be associated with one single delegator The permission is restricted to the maximum amount the delegator is allowed to Stack. The maximum amount is not limited by the available funds and can be set much higher. An account can only be associated with one single delegator -- The account has to define the delegation relationship. The account has to define the delegation relationship. The account has to define the delegation relationship. The account has to define the delegation relationship. They can optionally restrict the Bitcoin reward address that must be used for payouts, and the expiration burn block height for the permission, thus limiting the time a delegator has permission to Stack -- Delegators have to lock Stacks from different accounts ("pooling phase") until they reach the minimum amount of Stacks required to participate in Stacking -- Once a delegator locks enough STX tokens, they can finalize and commit their participation in the next reward cycle -- Certain delegation relationships may allow the STX holder to receive the payout directly from the miner (step 5/6) -- The termination of the delegation relationship can either happen automatically based on set expiration rules or by actively revoking delegation rights - -## PoX mining - -PoX mining is a modification of Proof-of-Burn (PoB) mining, where instead of sending the committed Bitcoin to a burn address, it's transferred to eligible STX holders that participate in the stacking protocol. - -:::note -A PoX miner can only receive newly minted STX tokens when they transfer Bitcoin to eligible owners of STX tokens -::: - -![Mining flow](/img/pox-mining-flow.png) - -Miners run Stacks nodes with mining enabled to participate in the PoX mechanism. Miners run Stacks nodes with mining enabled to participate in the PoX mechanism. The node implements the PoX mechanism, which ensures proper handling and incentives through four key phases: Miners run Stacks nodes with mining enabled to participate in the PoX mechanism. The node implements the PoX mechanism, which ensures proper handling and incentives through four key phases: Miners run Stacks nodes with mining enabled to participate in the PoX mechanism. The node implements the PoX mechanism, which ensures proper handling and incentives through four key phases: - -- Registration: miners register for a future election by sending consensus data to the network -- Commitment: registered miners transfer Bitcoin to participate in the election. Committed BTC are sent to a set participating STX token holders Commitment: registered miners transfer Bitcoin to participate in the election. Committed BTC are sent to a set participating STX token holders Commitment: registered miners transfer Bitcoin to participate in the election. Committed BTC are sent to a set participating STX token holders Committed BTC are sent to a set participating STX token holders -- Election: a verifiable random function chooses one miner to write a new block on the Stacks blockchain -- Assembly: the elected miner writes the new block and collects rewards in form of new STX tokens - -## Token holder eligibility - -Stacks (STX) token holders don't automatically receive stacking rewards. Instead, they must: Instead, they must: Instead, they must: Instead, they must: - -- Commit to participation before a reward cycle begins -- Commit the minimum amount of STX tokens to secure a reward slot, or pool with others to reach the minimum -- Lock up STX tokens for a specified period -- Provide a supported Bitcoin address to receive rewards (native segwit is not supported) - -The following diagram describes how the minimum STX tokens per slot is determined. More information on [dynamic minimums for stacking](https://stacking.club) is available at stacking.club. More information on [dynamic minimums for stacking](https://stacking.club) is available at stacking.club. More information on [dynamic minimums for stacking](https://stacking.club) is available at stacking.club. More information on [dynamic minimums for stacking](https://stacking.club) is available at stacking.club. - -![Dynamic minimum for individual eligibility](/img/stacking-dynamic-minimum.png) - -Token holders have a variety of providers and tools to support their participation in Stacking. Token holders have a variety of providers and tools to support their participation in Stacking. Token holders have a variety of providers and tools to support their participation in Stacking. The Stacks website contains a [list of stacking providers and pools](https://stacks.org/stacking#earn). - -## Stacking in the PoX consensus algorithm - -Stacking is a built-in capability of PoX and occurs through a set of actions on the Stacks blockchain. The [full proof-of-transfer implementation details](https://github.com/stacks-network/stacks-blockchain/blob/develop/sip/sip-007-stacking-consensus.md) are in SIP-007. Below is a summary of the most relevant actions of the algorithm. Stacking is a built-in capability of PoX and occurs through a set of actions on the Stacks blockchain. The [full proof-of-transfer implementation details](https://github.com/stacks-network/stacks-blockchain/blob/develop/sip/sip-007-stacking-consensus.md) are in SIP-007. Below is a summary of the most relevant actions of the algorithm. Stacking is a built-in capability of PoX and occurs through a set of actions on the Stacks blockchain. The [full proof-of-transfer implementation details](https://github.com/stacks-network/stacks-blockchain/blob/develop/sip/sip-007-stacking-consensus.md) are in SIP-007. Below is a summary of the most relevant actions of the algorithm. The [full proof-of-transfer implementation details](https://github.com/stacks-network/stacks-blockchain/blob/develop/sip/sip-007-stacking-consensus.md) are in SIP-007. Below is a summary of the most relevant actions of the algorithm. Below is a summary of the most relevant actions of the algorithm. Below is a summary of the most relevant actions of the algorithm. - -![PoX cycles](/img/pox-cycles.png) - -- Stacking happens over reward cycles with a fixed length. Stacking happens over reward cycles with a fixed length. Stacking happens over reward cycles with a fixed length. Stacking happens over reward cycles with a fixed length. In each reward cycle, a set of Bitcoin addresses associated with stacking participants receive BTC rewards -- A reward cycle consists of two phases: prepare and reward -- During the prepare phase, miners decide on an anchor block and a reward set. During the prepare phase, miners decide on an anchor block and a reward set. Mining any descendant forks of the anchor block requires transferring mining funds to the appropriate reward addresses. During the prepare phase, miners decide on an anchor block and a reward set. Mining any descendant forks of the anchor block requires transferring mining funds to the appropriate reward addresses. The reward set is the set of Bitcoin addresses which are eligible to receive funds in the reward cycle During the prepare phase, miners decide on an anchor block and a reward set. Mining any descendant forks of the anchor block requires transferring mining funds to the appropriate reward addresses. The reward set is the set of Bitcoin addresses which are eligible to receive funds in the reward cycle -- Miners register as leader candidates for a future election by sending a key transaction that burns cryptocurrency. The transaction also registers the leader's preferred chain tip (must be a descendant of the anchor block) and commitment of funds to 2 addresses from the reward set The transaction also registers the leader's preferred chain tip (must be a descendant of the anchor block) and commitment of funds to 2 addresses from the reward set The transaction also registers the leader's preferred chain tip (must be a descendant of the anchor block) and commitment of funds to 2 addresses from the reward set The transaction also registers the leader's preferred chain tip (must be a descendant of the anchor block) and commitment of funds to 2 addresses from the reward set -- Token holders register for the next rewards cycle by broadcasting a signed message that locks up associated STX tokens for a protocol-specified lockup period, specifies a Bitcoin address to receive the funds, and votes on a Stacks chain tip -- Multiple leaders can commit to the same chain tip. Multiple leaders can commit to the same chain tip. Multiple leaders can commit to the same chain tip. Multiple leaders can commit to the same chain tip. The leader that wins the election and the peers who also burn for that leader collectively share the reward, proportional to how much each one burned -- Token holders' locked up tokens automatically unlock as soon as the lockup period finishes - -## Bitcoin address - -:::danger You must provide a BTC address in one of two formats: - -* [Legacy (P2PKH)](https://en.bitcoin.it/wiki/Transaction#Pay-to-PubkeyHash), which starts with `1`. - -* [Segregated Witness / Segwit (P2SH)](https://en.bitcoin.it/wiki/Pay_to_script_hash), which starts with `3`. The "Native Segwit" format (which starts with `bc1`), for example, is not supported. ::: The "Native Segwit" format (which starts with `bc1`), for example, is not supported. ::: - -The Stacking contract needs a special format for the Bitcoin address (the reward address). This is required to ensure that miners are able to correctly construct the Bitcoin transaction containing the reward address. This is required to ensure that miners are able to correctly construct the Bitcoin transaction containing the reward address. This is required to ensure that miners are able to correctly construct the Bitcoin transaction containing the reward address. This is required to ensure that miners are able to correctly construct the Bitcoin transaction containing the reward address. - -The address must be specified in the following format using the Clarity language: - -```clar -;; a tuple of a version and hashbytes buffer -(pox-addr (tuple (version (buff 1)) (hashbytes (buff 20)))) -``` - -The `version` buffer must represent what kind of bitcoin address is being submitted. It can be one of the following: It can be one of the following: It can be one of the following: It can be one of the following: - -```js -SerializeP2PKH = 0x00, // hash160(public-key), same as bitcoin's p2pkh -SerializeP2SH = 0x01, // hash160(multisig-redeem-script), same as bitcoin's multisig p2sh -SerializeP2WPKH = 0x02, // hash160(segwit-program-00(p2pkh)), same as bitcoin's p2sh-p2wpkh -SerializeP2WSH = 0x03, // hash160(segwit-program-00(public-keys)), same as bitcoin's p2sh-p2wsh -``` - -The `hashbytes` are the 20 hash bytes of the bitcoin address. You can obtain that from a bitcoin library, for instance using [`bitcoinjs-lib`](https://github.com/bitcoinjs/bitcoinjs-lib): You can obtain that from a bitcoin library, for instance using [`bitcoinjs-lib`](https://github.com/bitcoinjs/bitcoinjs-lib): The `hashbytes` are the 20 hash bytes of the bitcoin address. You can obtain that from a bitcoin library, for instance using [`bitcoinjs-lib`](https://github.com/bitcoinjs/bitcoinjs-lib): You can obtain that from a bitcoin library, for instance using [`bitcoinjs-lib`](https://github.com/bitcoinjs/bitcoinjs-lib): You can obtain that from a bitcoin library, for instance using [`bitcoinjs-lib`](https://github.com/bitcoinjs/bitcoinjs-lib): - -```js -const btc = require('bitcoinjs-lib'); -console.log( - '0x' + btc.address.fromBase58Check('1C56LYirKa3PFXFsvhSESgDy2acEHVAEt6').hash.toString('hex') -); -``` - -## Choosing the right Stacking strategy - -[Here](https://blog.stacks.co/stacking-strategy) is an interesting article that may help you choose the right Stacking stategy. - - -## Where to Stacks? - -You can Stack on your own, on a pool or on an exchange: -### Stacking on your own - -Stacking on your own is non-custodial. - -Stacking on your own requires a protocol minimum (amount changes but about 100,000 STX). - -[Hiro Wallet](https://www.hiro.so/wallet) allows stacking on your own. - -### Stacking on a pool - -Stacking on a pool allows Stacking without the requirement of the protocol minumum. - -Some available pools are: - -| Pool | Type | Pays rewards in | Fee | Minimum amount | -| --------------------------------------------------- | ------------- |:---------------:| --- |:--------------:| -| [Friedger's Pool](https://pool.friedger.de/) | Non custodial | STX or xBTC | No | 40 STX | -| [Planbetter](https://planbetter.org/) | Non custodial | BTC | 5% | 200 STX | -| [Stacked](https://staking.staked.us/stacks-staking) | Non custodial | BTC | | 100,000 STX | -| [Xverse](https://www.xverse.app/) | Non custodial | BTC | No | 100 STX | - -### Stacking on an exchange - -Stacking on an exchange is custodial, meaning you are trusting the exchange with your Stacks. - -Several exchanges allow Stacking directly on their sites. Several exchanges allow Stacking directly on their sites. Examples are [Okcoin](https://www.okcoin.com) and [Binance](https://www.binance.com/en/staking) - -## Stacking statistics - -You can view all sorts of Stacking data and statistics on [Stacking Club](https://stacking.club) \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md b/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md deleted file mode 100644 index d942d6af8f..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/stacks-blockchain-api.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Stacks Blockchain API -description: Interacting with the Stacks 2.0 Blockchain via API ---- - -## Temporal page because of a Crowdin bug \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md b/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md deleted file mode 100644 index 9f7dc7a2ce..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/technical-specs.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: Technical Specifications -description: Summary of technical specifications of Stacks 2.0 -sidebar_position: 10 ---- - -## Consensus - -- Proof of Transfer (PoX) as described in [SIP-007](https://github.com/stacksgov/sips/blob/main/sips/sip-007/sip-007-stacking-consensus.md) -- Network will transition to Proof of Burn (PoB) as described in [SIP-001](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md) after 10 years. [Learn more about Proof-of-Burn in SIP-001](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md). [Learn more about Proof-of-Burn in SIP-001](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md). [Learn more about Proof-of-Burn in SIP-001](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md). [Learn more about Proof-of-Burn in SIP-001](https://github.com/stacksgov/sips/blob/main/sips/sip-001/sip-001-burn-election.md). -- Threat model - - 51% of malicious Stacks mining power can perform a double-spend attack - - 51% of malicious Bitcoin mining power can reorg the Stacks chain -- Different actors and their roles - - Stacks Miners package transactions into blocks, mine them through a Bitcoin transaction, propagate them, and if they win the block race, append microblocks to their winning block until the next block is mined. The next block confirms the microblock stream. The next block confirms the microblock stream. The next block confirms the microblock stream. The next block confirms the microblock stream. - - Stacks Holders may alter the calculation of block limits (subject to a miner veto) and may vote to disable Proof-of-Transfer rewards for a reward cycle. -- Transactions are considered final when the corresponding "block commit" transaction on Bitcoin is finalized. Typically this can by 3-6 confirmations. Typically this can by 3-6 confirmations. Typically this can by 3-6 confirmations. Typically this can by 3-6 confirmations. -- For more details, see [Proof of Transfer](proof-of-transfer). - -## Proof of Transfer Mining - -- Coinbase reward schedule: - - 1000 STX/block for first 4 years - - 500 STX/block for following 4 years - - 250 STX/block for subsequent 4 years - - 125 STX/block in perpetuity after that -- Coinbase rewards accumulate for "missed sortitions": If a Bitcoin block has no sortition (at height N), then any Stacks block mined in a subsequent sortition that builds off of any Stacks chain tip that existed at the penultimate sortition (at height N-1) may claim its coinbase. This encourages miners to keep mining even if Bitcoin fees are high. This encourages miners to keep mining even if Bitcoin fees are high. This encourages miners to keep mining even if Bitcoin fees are high. This encourages miners to keep mining even if Bitcoin fees are high. -- Initial mining bonus: This is a special case of the above to incentivize early miners. Initial mining bonus: This is a special case of the above to incentivize early miners. Coinbase for all burnchain blocks between the first burn block height (to be chosen by independent miners as part of the Stacks 2.0 launch) and the first sortition winner accumulate and are distributed to miners over a fixed window (to be determined). For instance, say burn block height is 10,000 and first sortition is at block 10500 and distribution window is 100 blocks, then coinbase for the first 500 blocks (10,500 - 10,000) will be distributed evenly to miners who win sortition over the subsequent 100 blocks. For instance, say burn block height is 10,000 and first sortition is at block 10500 and distribution window is 100 blocks, then coinbase for the first 500 blocks (10,500 - 10,000) will be distributed evenly to miners who win sortition over the subsequent 100 blocks. -- 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. For Bitcoin, this is approximately every 10 minutes. For Bitcoin, this is approximately every 10 minutes. For Bitcoin, this is approximately every 10 minutes. -- BTC commitment: Miners must commit at least 11,000 satoshis (5,500 sats / [UTXO output](https://learnmeabitcoin.com/technical/utxo)); 2 outputs / block) to avoid "dust." -- For more details, see [Mining](mining). - -## Stacking - -- Stacking works in 2 phases - 1. Prepare phase: In this phase an "anchor block" is chosen. The qualifying set of addresses ("reward set") is determined based on the snapshot of the chain at the anchor block. Length of prepare phase is 100 blocks. Stacking commitments need to be confirmed before this phase starts - 2. Reward phase: In this phase miner BTC commitments are distributed amongst the reward set. Reward phase: In this phase miner BTC commitments are distributed amongst the reward set. Reward cycle length is 2000 BTC blocks (~2 weeks). Reward phase: In this phase miner BTC commitments are distributed amongst the reward set. Reward cycle length is 2000 BTC blocks (~2 weeks). Reward phase: In this phase miner BTC commitments are distributed amongst the reward set. Reward cycle length is 2000 BTC blocks (~2 weeks). -- Two reward addresses / block, for a total of 4000 addresses every reward cycle. 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. 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. 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/stacksgov/sips/blob/main/sips/sip-007/sip-007-stacking-consensus.md#stacker-delegation). [Relevant section in SIP-007](https://github.com/stacksgov/sips/blob/main/sips/sip-007/sip-007-stacking-consensus.md#stacker-delegation). [Relevant section in SIP-007](https://github.com/stacksgov/sips/blob/main/sips/sip-007/sip-007-stacking-consensus.md#stacker-delegation). [Relevant section in SIP-007](https://github.com/stacksgov/sips/blob/main/sips/sip-007/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.stacks.co/references/stacking-contract#delegate-stx). To do this, STX holders must set the (optional) reward address to the "delegate address." For more details, see [this reference](https://docs.stacks.co/references/stacking-contract#delegate-stx). To do this, STX holders must set the (optional) reward address to the "delegate address." For more details, see [this reference](https://docs.stacks.co/references/stacking-contract#delegate-stx). -- Only two types of BTC reward addresses are supported: [Legacy (P2PKH)](https://en.bitcoin.it/wiki/Transaction#Pay-to-PubkeyHash) or [Segregated Witness / Segwit (P2SH)](https://en.bitcoin.it/wiki/Pay_to_script_hash). Native Segwit is not supported. Native Segwit is not supported. Native Segwit is not supported. Native Segwit is not supported. -- Further reading: [Stacking](stacking) - -## Accounts and Addresses - -- Transactions in the Stacks blockchain originate from, are paid for by, and execute under the authority of accounts -- An account is fully specified by its address + nonce + assets -- 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. Nonce counts number of times an account has authorized a transaction. Nonce counts number of times an account has authorized a transaction. Starts at 0, valid authorization must include the _next_ nonce value. Nonce counts number of times an account has authorized a transaction. 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 (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](accounts) - -## Transactions - -- Transaction 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 - 2. _paying account_ is the account that is billed by the leader for the cost of validating and executing the transaction - 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 -- Transactions can be batched or streamed into blocks. The behavior can be controlled by the anchor mode of a transaction. Transactions can be batched or streamed into blocks. The behavior can be controlled by the anchor mode of a transaction. Transactions can be batched or streamed into blocks. The behavior can be controlled by the anchor mode of a transaction. With streaming ([microblocks](microblocks)), a faster confirmation time is possible. -- Two types of authorizations: standard authorization is where originating account is the same as paying account. 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 instance, developers or service providers could pay for users to call their smart-contracts. 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 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. -- Mempool limit for concurrent pending transactions is 25 per account -- Pending mempool transactions will be garbage-collected [256 blocks after receipt](https://github.com/stacks-network/stacks-blockchain/blob/master/src/core/mempool.rs#L62). With 10 minutes target block time, this would equal ~42 hours With 10 minutes target block time, this would equal ~42 hours With 10 minutes target block time, this would equal ~42 hours With 10 minutes target block time, this would equal ~42 hours -- [Learn more about transaction encoding in SIP-005](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md#transaction-encoding) -- [Transaction signing and verification are described in SIP-005](https://github.com/stacksgov/sips/blob/main/sips/sip-005/sip-005-blocks-and-transactions.md#transaction-signing-and-verifying) -- All transactions impacting account balance are atomic, a transfer operation can not increment one account’s balance without decrementing another’s. However, transactions that perform multiple account actions (for example, transferring from multiple accounts) may partially complete. However, transactions that perform multiple account actions (for example, transferring from multiple accounts) may partially complete. However, transactions that perform multiple account actions (for example, transferring from multiple accounts) may partially complete. However, transactions that perform multiple account actions (for example, transferring from multiple accounts) may partially complete. -- Transactions can include a memo string (max 34 bytes) - -## See also - -- [Read the full Stacks 2.0: Apps and Smart Contracts for Bitcoin whitepaper](https://cloudflare-ipfs.com/ipfs/QmaGgiVHymeDjAc3aF1AwyhiFFwN97pme5m536cHT4FsAW). - -- [Watch Aaron Blankstein video on Stacks whitepater v2](https://www.youtube.com/watch?v=Wd-Bfe8Sn-Y). \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md b/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md deleted file mode 100644 index 35a30f9673..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/testnet.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Testnet -description: Test your smart contracts and apps -sidebar_position: 2 ---- - -## About testnet - -The testnet is a separate blockchain from the Stacks mainnet analogous to a staging environment. It's a network used by developers to test their apps, smart contracts, or changes to the protocol in a production-like environment. It produces blocks at roughly the same rate as mainnet; about 1 block every 10 minutes on average. The Stacks testnet is rarely reset. - -### Faucet - -The testnet faucet provides you with free Stacks Token (STX) to test with. These are not the same as STX on mainnet and have no value. The testnet faucet provides you with free Stacks Token (STX) to test with. These are not the same as STX on mainnet and have no value. You can get STX from the faucet on the [Stacks Explorer Sandbox](https://explorer.stacks.co/sandbox/faucet?chain=testnet), or using the [API](https://docs.hiro.so/api#tag/Faucets). These are not the same as STX on mainnet and have no value. The testnet faucet provides you with free Stacks Token (STX) to test with. These are not the same as STX on mainnet and have no value. The testnet faucet provides you with free Stacks Token (STX) to test with. These are not the same as STX on mainnet and have no value. You can get STX from the faucet on the [Stacks Explorer Sandbox](https://explorer.stacks.co/sandbox/faucet?chain=testnet), or using the [API](https://docs.hiro.so/api#tag/Faucets). These are not the same as STX on mainnet and have no value. The testnet faucet provides you with free Stacks Token (STX) to test with. These are not the same as STX on mainnet and have no value. You can get STX from the faucet on the [Stacks Explorer Sandbox](https://explorer.stacks.co/sandbox/faucet?chain=testnet), or using the [API](https://docs.hiro.so/api#tag/Faucets). - -To get STX tokens from within the Explorer Sandbox, navigate to the "Faucet" tab on the left and click "Request STX" button. - -![](/img/stx_faucet.png) - -You can also try out [Stacking](stacking) by clicking on `I want to stack`. - -:::note -The Explorer Sandbox requires you to login with a Stacks wallet -::: - -### Testnet API - -The hosted Stacks Blockchain API for the testnet is available at this base URL: - -```shell -https://stacks-node-api.testnet.stacks.co/ -``` - -![](/img/api_testnet_status.png) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md b/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md deleted file mode 100644 index 403e5c176c..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/understand-stacks/transactions.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Transactions -description: Guide to Stacks 2.0 transactions -sidebar_position: 6 ---- - -## Introduction - -Transactions are the fundamental unit of execution in the Stacks blockchain. Transactions are the fundamental unit of execution in the Stacks blockchain. Transactions are the fundamental unit of execution in the Stacks blockchain. Each transaction is originated from a [Stacks 2.0 account](accounts), and is retained in the Stacks blockchain history for eternity. This guide helps you understand Stacks 2.0 transactions. This guide helps you understand Stacks 2.0 transactions. This guide helps you understand Stacks 2.0 transactions. - -## Lifecycle - -Transactions go through phases before being finally confirmed, and available for all, on the Stacks 2.0 network. - -![Transaction lifecycle](/img/tx-lifecycle.png) - -- **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. Required signatures are filled in. Required signatures are filled in. 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/en/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. 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. The transactions inside are successfully propagated to the network. The transactions inside are successfully propagated to the network. The transactions inside are successfully propagated to the network. - -:::note A transaction can have one of three states once it is registered: `pending`, `success`, or `failed`. ::: ::: ::: - -## Types - -The Stacks 2.0 supports a set of different transaction types: - -| **Type** | **Value** | **Description** | -| ----------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Coinbase | `coinbase` | The first transaction in a new block (an entity holding several transactions). Used to register for block rewards. These are not manually generated and broadcasted like other types of transactions. Used to register for block rewards. These are not manually generated and broadcasted like other types of transactions. Used to register for block rewards. These are not manually generated and broadcasted like other types of transactions. | -| Token transfer | `token_transfer` | Asset transfer from a sender to a recipient | -| Contract deploy | `smart_contract` | Contract instantiation | -| Contract call | `contract_call` | Contract call for a public, non read-only function | -| Poison Microblock | `poison_microblock` | Punish leaders who intentionally equivocate about the microblocks they package | - -A sample of each transaction type can be found in the [Stacks Blockchain API response definition for transactions](https://docs.hiro.so/api#operation/get_transaction_by_id). - -:::caution Read-only contract call calls do **not** require transactions. Read more about it in the [network guide](network#read-only-function-calls). ::: Read more about it in the [network guide](network#read-only-function-calls). ::: Read more about it in the [network guide](network#read-only-function-calls). ::: diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md b/i18n/zh/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md deleted file mode 100644 index 339872ef23..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/clarity-language.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: Clarity Language -description: Overview of the Clarity language constructs -sidebar_label: Clarity Language -tags: - - clarity ---- - -## Clarity Type System - -The Clarity language uses a strong static type system. The Clarity language uses a strong static type system. Function arguments and database schemas require specified types, and use of types is checked during contract launch. The type system does _not_ have a universal super type. The type system does _not_ have a universal super type. The Clarity language uses a strong static type system. Function arguments and database schemas require specified types, and use of types is checked during contract launch. The type system does _not_ have a universal super type. The type system does _not_ have a universal super type. - -## Public Functions - -Functions specified via `define-public` statements are _public_ functions and these are the only types of functions which may be called directly through signed blockchain transactions. In addition to being callable directly from a transaction (see the Stacks wire formats for more details on Stacks transactions), public functions may be called by other smart contracts. In addition to being callable directly from a transaction (see the Stacks wire formats for more details on Stacks transactions), public functions may be called by other smart contracts. In addition to being callable directly from a transaction (see the Stacks wire formats for more details on Stacks transactions), public functions may be called by other smart contracts. - -Public functions _must_ return a `(response ...)` type. This is used by Clarity to determine whether or not to materialize any changes from the execution of the function. If a function returns an `(err ...)` type, any mutations on the blockchain state from executing the function (and any function that it called during execution) will be aborted. This is used by Clarity to determine whether or not to materialize any changes from the execution of the function. If a function returns an `(err ...)` type, any mutations on the blockchain state from executing the function (and any function that it called during execution) will be aborted. This is used by Clarity to determine whether or not to materialize any changes from the execution of the function. If a function returns an `(err ...)` type, any mutations on the blockchain state from executing the function (and any function that it called during execution) will be aborted. - -In addition to functions defined via `define-public`, contracts may expose read-only functions. In addition to functions defined via `define-public`, contracts may expose read-only functions. In addition to functions defined via `define-public`, contracts may expose read-only functions. These functions, defined via `define-read-only`, are callable by other smart contracts, and may be queryable via public blockchain explorers. These functions _may not_ mutate any blockchain state. Unlike normal public functions, read-only functions may return any type. These functions _may not_ mutate any blockchain state. Unlike normal public functions, read-only functions may return any type. These functions _may not_ mutate any blockchain state. Unlike normal public functions, read-only functions may return any type. - -## Contract Calls - -A smart contract may call functions from other smart contracts using a `(contract-call?)` function. - -This function returns a response type result -- the return value of the called smart contract function. - -We distinguish 2 different types of `contract-call?`: - -### Static dispatch - -The callee is a known, invariant contract available on-chain when the caller contract is deployed. The callee is a known, invariant contract available on-chain when the caller contract is deployed. In this case, the callee's principal is provided as the first argument, followed by the name of the method and its arguments: The callee is a known, invariant contract available on-chain when the caller contract is deployed. In this case, the callee's principal is provided as the first argument, followed by the name of the method and its arguments: - -```clarity -(contract-call? - (contract-call? - (contract-call? - .registrar - register-name - name-to-register) -``` - -### Dynamic dispatch - -The callee is passed as an argument, and typed as a trait reference (`
`). - -```clarity -(define-public (swap (token-a ) - (amount-a uint) - (owner-a principal) - (token-b ) - (amount-b uint) - (owner-b principal))) - (begin - (unwrap! (contract-call? token-a transfer-from? owner-a owner-b amount-a)) - (unwrap! (contract-call? token-b transfer-from? owner-b owner-a amount-b)))) (contract-call? token-a transfer-from? owner-a owner-b amount-a)) - (unwrap! (contract-call? token-b transfer-from? owner-b owner-a amount-b)))) (contract-call? token-a transfer-from? owner-a owner-b amount-a)) - (unwrap! (contract-call? token-b transfer-from? owner-b owner-a amount-b)))) -``` - -Traits can either be locally defined: - -```clarity -(define-trait can-transfer-tokens ( - (transfer-from? (principal principal uint) (response uint))) (define-trait can-transfer-tokens ( - (transfer-from? (principal principal uint) (response uint))) (principal principal uint) (response uint))) -``` - -Or imported from an existing contract: - -```clarity -(use-trait can-transfer-tokens - .contract-defining-trait.can-transfer-tokens) -``` - -Looking at trait conformance, callee contracts have two different paths. Looking at trait conformance, callee contracts have two different paths. Looking at trait conformance, callee contracts have two different paths. They can either be "compatible" with a trait by defining methods matching some of the methods defined in a trait, or explicitly declare conformance using the `impl-trait` statement: - -```clarity -(impl-trait .contract-defining-trait.can-transfer-tokens) -``` - -Explicit conformance should be prefered when adequate. Explicit conformance should be prefered when adequate. Explicit conformance should be prefered when adequate. It acts as a safeguard by helping the static analysis system to detect deviations in method signatures before contract deployment. - -The following limitations are imposed on contract calls: - -1. On static dispatches, callee smart contracts _must_ exist at the time of creation. -2. No cycles may exist in the call graph of a smart contract. This prevents recursion (and re-entrancy bugs). No cycles may exist in the call graph of a smart contract. This prevents recursion (and re-entrancy bugs). Such structures can be detected with static analysis of the call graph, and will be rejected by the network. This prevents recursion (and re-entrancy bugs). No cycles may exist in the call graph of a smart contract. This prevents recursion (and re-entrancy bugs). Such structures can be detected with static analysis of the call graph, and will be rejected by the network. -3. `contract-call?` are for inter-contract calls only. `contract-call?` are for inter-contract calls only. Attempts to execute when the caller is also the callee will abort the transaction. `contract-call?` are for inter-contract calls only. Attempts to execute when the caller is also the callee will abort the transaction. diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md b/i18n/zh/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md deleted file mode 100644 index c01d4a2618..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-functions.md +++ /dev/null @@ -1,1393 +0,0 @@ ---- -title: Functions -description: See a detailed list of all functions for the Clarity language. -tags: - - clarity ---- - -## Functions - -Detailed list of all functions for the Clarity language. - -### + (add) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(+ i1 i2...)` -#### description: -Adds a variable number of integer inputs and returns the result. Returns the result of raising `i1` to the power of `i2`. In the event of an _overflow_, throws a runtime error. -#### example: -```clarity -(+ 1 2 3) ;; Returns 6 -(+ 2 3) ;; Returns 5 -(+ 1 2 3 4) ;; Returns 10 -(+ 9 -3) ;; Returns 6 -(+ -3 -2) ;; Returns -5 -``` - -### - (subtract) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(- i1 i2...)` -#### description: -Subtracts a variable number of integer inputs and returns the result. Subtracts a variable number of integer inputs and returns the result. In the event of an _underflow_, throws a runtime error. -#### example: -```clarity -(- 2 1 1) ;; Returns 0 -(- 0 3) ;; Returns -3 -(- 5 -3) ;; Returns 8 -(- -4 -5) ;; Returns 1 -``` - -### * (multiply) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(* i1 i2...)` -#### description: -Multiplies a variable number of integer inputs and returns the result. Returns the result of raising `i1` to the power of `i2`. In the event of an _overflow_, throws a runtime error. -#### example: -```clarity -(* 2 3) ;; Returns 6 -(* 5 2) ;; Returns 10 -(* 2 2 2) ;; Returns 8 -(* 3 -2) ;; Returns -6 -(* -1 -2) ;; Returns 2 -``` - -### / (divide) -#### input: `int, ... | uint, ...` -#### output: `int | uint` -#### signature: `(/ i1 i2...)` -#### description: -Divides a variable number of integer inputs and returns the _integer part_ of the result. In the event of _division by zero_, throws a runtime error. - -#### example: -```clarity -(/ 2 3) ;; Returns 0 -(/ 5 2) ;; Returns 2 -(/ 4 2 2) ;; Returns 1 -(/ -10 2) ;; Returns -5 -(/ -8 -2) ;; Returns 4 -(/ -9 4) ;; Returns -2 -``` - -### >= (greater than or equal) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(>= i1 i2)` -#### description: -Compares two integers, returning `true` if `i1` is greater than or equal to `i2` and `false` otherwise. -#### example: -```clarity -(>= 1 1) ;; Returns true -(>= 5 2) ;; Returns true -``` - -### <= (less than or equal) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(<= i1 i2)` -#### description: -Compares two integers, returning true if `i1` is less than or equal to `i2` and `false` otherwise. -#### example: -```clarity -(<= 1 1) ;; Returns true -(<= 5 2) ;; Returns false -``` - -### < (less than) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(< i1 i2)` -#### description: -Compares two integers, returning `true` if `i1` is less than `i2` and `false` otherwise. -#### example: -```clarity -(< 1 2) ;; Returns true -(< 5 2) ;; Returns false -``` - -### > (greater than) -#### input: `int, int | uint, uint` -#### output: `bool` -#### signature: `(> i1 i2)` -#### description: -Compares two integers, returning `true` if `i1` is greater than `i2` and false otherwise. -#### example: -```clarity -(> 1 2) ;; Returns false -(> 5 2) ;; Returns true -``` - -### to-int -#### input: `uint` -#### output: `int` -#### signature: `(to-int u)` -#### description: -Tries to convert the `uint` argument to an `int`. Tries to convert the `uint` argument to an `int`. Will cause a runtime error and abort if the supplied argument is >= `pow(2, 127)`` -#### example: -```clarity -(to-int u238) ;; Returns 238 -``` - -### to-uint -#### input: `int` -#### output: `uint` -#### signature: `(to-uint i)` -#### description: -Tries to convert the `int` argument to a `uint`. Will cause a runtime error and abort if the supplied argument is negative. -#### example: -```clarity -(to-uint 238) ;; Returns u238 -``` - -### mod -#### input: `int, int | uint, uint` -#### output: `int | uint` -#### signature: `(mod i1 i2)` -#### description: -Returns the integer remainder from integer dividing `i1` by `i2`. In the event of a division by zero, throws a runtime error. -#### example: -```clarity -(mod 2 3) ;; Returns 2 -(mod 5 2) ;; Returns 1 -(mod 7 1) ;; Returns 0 -``` - -### pow -#### input: `int, int | uint, uint` -#### output: `int | uint` -#### signature: `(pow i1 i2)` -#### description: -Returns the result of raising `i1` to the power of `i2`. Returns the result of raising `i1` to the power of `i2`. In the event of an _overflow_, throws a runtime error. -#### example: -```clarity -(pow 2 3) ;; Returns 8 -(pow 2 2) ;; Returns 4 -(pow 7 1) ;; Returns 7 -``` - -### sqrti -#### input: `int | uint` -#### output: `int | uint` -#### signature: `(sqrti n)` -#### description: -Returns the largest integer that is less than or equal to the square root of `n`. Fails on a negative numbers. Fails on a negative numbers. -#### example: -```clarity -(sqrti u11) ;; Returns u3 -(sqrti 1000000) ;; Returns 1000 -(sqrti u1) ;; Returns u1 -(sqrti 0) ;; Returns 0 -``` - -### log2 -#### input: `int | uint` -#### output: `int | uint` -#### signature: `(log2 n)` -#### description: -Returns the _integer part_ of the power to which the number 2 must be raised to obtain the value `n`. Fails on zero or a negative number. -#### example: -```clarity -(log2 u8) ;; Returns u3 -(log2 8) ;; Returns 3 -(log2 u1) ;; Returns u0 -(log2 1000) ;; Returns 9 -``` - -### xor -#### input: `int, int | uint, uint` -#### output: `int | uint` -#### signature: `(xor i1 i2)` -#### description: -Returns the result of bitwise exclusive or'ing `i1` with `i2`. -#### example: -```clarity -(xor 1 2) ;; Returns 3 -(xor 120 280) ;; Returns 352 -``` - -### and -#### input: `bool, ...` -#### output: `bool` -#### signature: `(and b1 b2 ...)` -#### description: -Returns `true` if all boolean inputs are `true`. Importantly, the supplied arguments are evaluated in-order and lazily. Lazy evaluation means that if one of the arguments returns `false`, the function short-circuits, and no subsequent arguments are evaluated. Importantly, the supplied arguments are evaluated in-order and lazily. Lazy evaluation means that if one of the arguments returns `false`, the function short-circuits, and no subsequent arguments are evaluated. -#### example: -```clarity -(and true false) ;; Returns false -(and (is-eq (+ 1 2) 1) (is-eq 4 4)) ;; Returns false -(and (is-eq (+ 1 2) 3) (is-eq 4 4)) ;; Returns true -``` - -### or -#### input: `bool, ...` -#### output: `bool` -#### signature: `(or b1 b2 ...)` -#### description: -Returns `true` if any boolean inputs are `true`. Importantly, the supplied arguments are evaluated in-order and lazily. Returns `true` if any boolean inputs are `true`. Importantly, the supplied arguments are evaluated in-order and lazily. Lazy evaluation means that if one of the arguments returns `true`, the function short-circuits, and no subsequent arguments are evaluated. -#### example: -```clarity -(or true false) ;; Returns true -(or (is-eq (+ 1 2) 1) (is-eq 4 4)) ;; Returns true -(or (is-eq (+ 1 2) 1) (is-eq 3 4)) ;; Returns false -(or (is-eq (+ 1 2) 3) (is-eq 4 4)) ;; Returns true -``` - -### not -#### input: `bool` -#### output: `bool` -#### signature: `(not b1)` -#### description: -Returns the inverse of the boolean input. -#### example: -```clarity -(not true) ;; Returns false -(not (is-eq 1 2)) ;; Returns true -``` - -### is-eq -#### input: `A, A, ...` -#### output: `bool` -#### signature: `(is-eq v1 v2...)` -#### description: -Compares the inputted values, returning `true` if they are all equal. Note that _unlike_ the `(and ...)` function, `(is-eq ...)` will _not_ short-circuit. All values supplied to is-eq _must_ be the same type. Note that _unlike_ the `(and ...)` function, `(is-eq ...)` will _not_ short-circuit. All values supplied to is-eq _must_ be the same type. -#### example: -```clarity -(is-eq 1 1) ;; Returns true -(is-eq true false) ;; Returns false -(is-eq \"abc\" 234 234) ;; Throws type error -``` - -### if -#### input: `bool, A, A` -#### output: `A` -#### signature: `(if bool1 expr1 expr2)` -#### description: -The `if` function admits a boolean argument and two expressions which must return the same type. In the case that the boolean input is `true`, the `if` function evaluates and returns `expr1`. The `if` function admits a boolean argument and two expressions which must return the same type. In the case that the boolean input is `true`, the `if` function evaluates and returns `expr1`. If the boolean input is `false`, the `if` function evaluates and returns `expr2`. -#### example: -```clarity -(if true 1 2) ;; Returns 1 -(if (> 1 2) 1 2) ;; Returns 2 -``` - -### let -#### input: `((name1 AnyType) (name2 AnyType) ...), AnyType, ... A` -#### output: `A` -#### signature: `(let ((name1 expr1) (name2 expr2) ...) expr-body1 expr-body2 ... expr-body-last)` -#### description: -The `let` function accepts a list of `variable name` and `expression` pairs, evaluating each expression and _binding_ it to the corresponding variable name. `let` bindings are sequential: when a `let` binding is evaluated, it may refer to prior binding. The _context_ created by this set of bindings is used for evaluating its body expressions. The let expression returns the value of the last such body expression. Note: intermediary statements returning a response type must be checked` -#### example: -```clarity -(let ((a 2) (b (+ 5 6 7))) (print a) (print b) (+ a b)) ;; Returns 20 -(let ((a 5) (c (+ a 1)) (d (+ c 1)) (b (+ a c d))) (print a) (print b) (+ a b)) ;; Returns 23 -``` - -### map -#### input: `Function(A, B, ..., N) -> X, sequence_A, sequence_B, ..., sequence_N` -#### output: `(list X)` -#### signature: `(map func sequence_A sequence_B ... sequence_N)` -#### description: -The `map` function applies the function `func` to each corresponding element of the input sequences, and outputs a _list_ of the same type containing the outputs from those function applications. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. Also, note that, no matter what kind of sequences the inputs are, the output is always a list. -#### example: -```clarity -(map not (list true false true false)) ;; Returns (false true false true) -(map + (list 1 2 3) (list 1 2 3) (list 1 2 3)) ;; Returns (3 6 9) -(define-private (a-or-b (char (string-utf8 1))) (if (is-eq char u\"a\") u\"a\" u\"b\")) -(map a-or-b u\"aca\") ;; Returns (u\"a\" u\"b\" u\"a\") -(define-private (zero-or-one (char (buff 1))) (if (is-eq char 0x00) 0x00 0x01)) -(map zero-or-one 0x000102) ;; Returns (0x00 0x01 0x01) -``` - -### fold -#### input: `Function(A, B) -> B, sequence_A, B` -#### output: `B` -#### signature: `(fold func sequence_A initial_B)` -#### description: -The `fold` function condenses `sequence_A` into a value of type `B` by recursively applies the function `func` to each element of the input sequence _and_ the output of a previous application of `func`. - -`fold` uses `initial_B` in the initial application of `func`, along with the first element of `sequence_A`. The resulting value of type `B` is used for the next application of `func`, along with the next element of `sequence_A` and so on. `fold` returns the last value of type `B` returned by these successive applications `func`. The resulting value of type `B` is used for the next application of `func`, along with the next element of `sequence_A` and so on. `fold` returns the last value of type `B` returned by these successive applications `func`. - -Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. - -#### example: -```clarity -(fold * (list 2 2 2) 1) ;; Returns 8 -(fold * (list 2 2 2) 0) ;; Returns 0 -;; calculates (- 11 (- 7 (- 3 2))) -(fold - (list 3 7 11) 2) ;; Returns 5 -(define-private (concat-string (a (string-ascii 20)) (b (string-ascii 20))) (unwrap-panic (as-max-len? (concat a b) u20))) -(fold concat-string \"cdef\" \"ab\") ;; Returns \"fedcab\" -(fold concat-string (list \"cd\" \"ef\") \"ab\") ;; Returns \"efcdab\" -(define-private (concat-buff (a (buff 20)) (b (buff 20))) (unwrap-panic (as-max-len? (concat a b) u20))) -(fold concat-buff 0x03040506 0x0102) ;; Returns 0x060504030102 (concat a b) u20))) -(fold concat-string \"cdef\" \"ab\") ;; Returns \"fedcab\" -(fold concat-string (list \"cd\" \"ef\") \"ab\") ;; Returns \"efcdab\" -(define-private (concat-buff (a (buff 20)) (b (buff 20))) (unwrap-panic (as-max-len? (concat a b) u20))) -(fold concat-buff 0x03040506 0x0102) ;; Returns 0x060504030102 -``` - -### append -#### input: `list A, A` -#### output: `list` -#### signature: `(append (list 1 2 3 4) 5)` -#### description: -The `append` function takes a list and another value with the same entry type, and outputs a list of the same type with max_len += 1. -#### example: -```clarity -(append (list 1 2 3 4) 5) ;; Returns (1 2 3 4 5) -``` - -### concat -#### input: `sequence_A, sequence_A` -#### output: `sequence_A` -#### signature: `(concat sequence1 sequence2)` -#### description: -The `concat` function takes two sequences of the same type, and returns a concatenated sequence of the same type, with the resulting sequence_len = sequence1_len + sequence2_len. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`. - -#### example: -```clarity -(concat (list 1 2) (list 3 4)) ;; Returns (1 2 3 4) -(concat \"hello \" \"world\") ;; Returns \"hello world\" -(concat 0x0102 0x0304) ;; Returns 0x01020304 -``` - -### as-max-len? -#### input: `sequence_A, uint` -#### output: `sequence_A` -#### signature: `(as-max-len? sequence max_length)` sequence max_length) -#### description: -The `as-max-len?` function takes a sequence argument and a uint-valued, literal length argument. The function returns an optional type. If the input sequence length is less than or equal to the supplied max_length, this returns `(some sequence)`, otherwise it returns `none`. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`. ` The function returns an optional type. If the input sequence length is less than or equal to the supplied max_length, this returns `(some sequence)`, otherwise it returns `none`. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`. ` -#### example: -```clarity -(as-max-len? (as-max-len? (list 2 2 2) u3) ;; Returns (some (2 2 2)) -(as-max-len? (list 1 2 3) u2) ;; Returns none -(as-max-len? \"hello\" u10) ;; Returns (some \"hello\") -(as-max-len? 0x010203 u10) ;; Returns (some 0x010203) (list 1 2 3) u2) ;; Returns none -(as-max-len? \"hello\" u10) ;; Returns (some \"hello\") -(as-max-len? 0x010203 u10) ;; Returns (some 0x010203) -``` - -### len -#### input: `sequence_A` -#### output: `uint` -#### signature: `(len sequence)` -#### description: -The `len` function returns the length of a given sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`. ` Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`. ` -#### example: -```clarity -(len \"blockstack\") ;; Returns u10 -(len (list 1 2 3 4 5)) ;; Returns u5 -(len 0x010203) ;; Returns u3 -``` - -### element-at -#### input: `sequence_A, uint` -#### output: `(optional A)` -#### signature: `(element-at sequence index)` -#### description: -The `element-at` function returns the element at `index` in the provided sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. ` Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. ` ` -#### example: -```clarity -(element-at \"blockstack\" u5) ;; Returns (some \"s\") -(element-at (list 1 2 3 4 5) u5) ;; Returns none -(element-at (list 1 2 3 4 5) (+ u1 u2)) ;; Returns (some 4) -(element-at \"abcd\" u1) ;; Returns (some \"b\") -(element-at 0xfb01 u1) ;; Returns (some 0x01) -``` - -### index-of -#### input: `sequence_A, A` -#### output: `(optional uint)` -#### signature: `(index-of sequence item)` -#### description: -The `index-of` function returns the first index at which `item` can be found, using `is-eq` checks, in the provided sequence. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. If the target item is not found in the sequence (or if an empty string or buffer is supplied), this function returns `none`. ` Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. If the target item is not found in the sequence (or if an empty string or buffer is supplied), this function returns `none`. -#### example: -```clarity -(index-of \"blockstack\" \"b\") ;; Returns (some u0) -(index-of \"blockstack\" \"k\") ;; Returns (some u4) -(index-of \"blockstack\" \"\") ;; Returns none -(index-of (list 1 2 3 4 5) 6) ;; Returns none -(index-of 0xfb01 0x01) ;; Returns (some u1) -``` - -### list -#### input: `A, ...` -#### output: `(list A)` -#### signature: `(list expr1 expr2 expr3 ...)` -#### description: -The `list` function constructs a list composed of the inputted values. Each supplied value must be of the same type. Each supplied value must be of the same type. -#### example: -```clarity -(list (+ 1 2) 4 5) ;; Returns (3 4 5) -``` - -### var-get -#### input: `VarName` -#### output: `A` -#### signature: `(var-get var-name)` -#### description: -The `var-get` function looks up and returns an entry from a contract's data map. The value is looked up using `var-name`. -#### example: -```clarity -(define-data-var cursor int 6) -(var-get cursor) ;; Returns 6 -``` - -### var-set -#### input: `VarName, AnyType` -#### output: `bool` -#### signature: `(var-set var-name expr1)` -#### description: -The `var-set` function sets the value associated with the input variable to the inputted value. The function always returns `true`. -#### example: -```clarity -(define-data-var cursor int 6) -(var-get cursor) ;; Returns 6 -(var-set cursor (+ (var-get cursor) 1)) ;; Returns true -(var-get cursor) ;; Returns 7 -``` - -### map-get? -#### input: `MapName, tuple` -#### output: `(optional (tuple))` -#### signature: `(map-get? map-name key-tuple)` -#### description: -The `map-get?` function looks up and returns an entry from a contract's data map. The value is looked up using `key-tuple`. If there is no value associated with that key in the data map, the function returns a `none` option. Otherwise, it returns `(some value)`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(map-get? names-map (tuple (name \"blockstack\"))) ;; Returns (some (tuple (id 1337))) -(map-get? names-map { name: \"blockstack\" }) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-set -#### input: `MapName, tuple_A, tuple_B` -#### output: `bool` -#### signature: `(map-set map-name key-tuple value-tuple)` -#### description: -The `map-set` function sets the value associated with the input key to the inputted value. The `map-set` function sets the value associated with the input key to the inputted value. This function performs a _blind_ update; whether or not a value is already associated with the key, the function overwrites that existing association. - -Note: the `value-tuple` requires 1 additional byte for storage in the materialized blockchain state, and therefore the maximum size of a value that may be inserted into a map is MAX_CLARITY_VALUE - 1. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-set names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-insert -#### input: `MapName, tuple_A, tuple_B` -#### output: `bool` -#### signature: `(map-insert map-name key-tuple value-tuple)` -#### description: -The `map-insert` function sets the value associated with the input key to the inputted value if and only if there is not already a value associated with the key in the map. If an insert occurs, the function returns `true`. If a value already existed for this key in the data map, the function returns `false`. If an insert occurs, the function returns `true`. If a value already existed for this key in the data map, the function returns `false`. - -Note: the `value-tuple` requires 1 additional byte for storage in the materialized blockchain state, and therefore the maximum size of a value that may be inserted into a map is MAX_CLARITY_VALUE - 1. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns false -(map-insert names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Same command, using a shorthand for constructing the tuple -``` - -### map-delete -#### input: `MapName, tuple` -#### output: `bool` -#### signature: `(map-delete map-name key-tuple)` -#### description: -The `map-delete` function removes the value associated with the input key for the given map. If an item exists and is removed, the function returns `true`. The `map-delete` function removes the value associated with the input key for the given map. If an item exists and is removed, the function returns `true`. If a value did not exist for this key in the data map, the function returns `false`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 10) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(map-delete names-map { name: \"blockstack\" }) ;; Returns true -(map-delete names-map { name: \"blockstack\" }) ;; Returns false -(map-delete names-map (tuple (name \"blockstack\"))) ;; Same command, using a shorthand for constructing the tuple -``` - -### tuple -#### input: `(key-name A), (key-name-2 B), ...` -#### output: `(tuple (key-name A) (key-name-2 B) ...)` -#### signature: `(tuple (key0 expr0) (key1 expr1) ...)` -#### description: -The `tuple` special form constructs a typed tuple from the supplied key and expression pairs. A `get` function can use typed tuples as input to select specific values from a given tuple. Key names may not appear multiple times in the same tuple definition. Supplied expressions are evaluated and associated with the expressions' paired key name. A `get` function can use typed tuples as input to select specific values from a given tuple. Key names may not appear multiple times in the same tuple definition. Supplied expressions are evaluated and associated with the expressions' paired key name. - -There is a shorthand using curly brackets of the form {key0: expr0, key1: expr, ...}` -#### example: -```clarity -(tuple (name \"blockstack\") (id 1337)) ;; using tuple -{name: \"blockstack\", id: 1337} ;; using curly brackets -``` - -### get -#### input: `KeyName, (tuple) | (optional (tuple))` -#### output: `A` -#### signature: `(get key-name tuple)` -#### description: -The `get` function fetches the value associated with a given key from the supplied typed tuple. If an `Optional` value is supplied as the inputted tuple, `get` returns an `Optional` type of the specified key in the tuple. If the supplied option is a `(none)` option, get returns `(none)`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true -(get id (tuple (name \"blockstack\") (id 1337))) ;; Returns 1337 -(get id (map-get? names-map (tuple (name \"blockstack\")))) ;; Returns (some 1337) -(get id (map-get? names-map (tuple (name \"non-existent\")))) ;; Returns none -``` - -### merge -#### input: `tuple, tuple` -#### output: `tuple` -#### signature: `(merge tuple { key1: val1 })` -#### description: -The `merge` function returns a new tuple with the combined fields, without mutating the supplied tuples. -#### example: -```clarity -(define-map users { id: int } { name: (string-ascii 12), address: (optional principal) }) -(map-insert users { id: 1337 } { name: \"john\", address: none }) ;; Returns true -(let ((user (unwrap-panic (map-get? users { id: 1337 })))) -(merge user { address: (some 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) })) ;; Returns (tuple (address (some SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF)) (name \"john\")) -``` - -### begin -#### input: `AnyType, ... A` -#### output: `A` -#### signature: `(begin expr1 expr2 expr3 ... expr-last)` -#### description: -The `begin` function evaluates each of its input expressions, returning the return value of the last such expression. Note: intermediary statements returning a response type must be checked. -#### example: -```clarity -(begin (+ 1 2) 4 5) ;; Returns 5 -``` - -### hash160 -#### input: `buff|uint|int` -#### output: `(buff 20)` -#### signature: `(hash160 value)` -#### description: -The `hash160` function computes `RIPEMD160(SHA256(x))` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(hash160 0) ;; Returns 0xe4352f72356db555721651aa612e00379167b30f -``` - -### sha256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(sha256 value)` -#### description: -The `sha256` function computes `SHA256(x)` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(sha256 0) ;; Returns 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb -``` - -### sha512 -#### input: `buff|uint|int` -#### output: `(buff 64)` -#### signature: `(sha512 value)` -#### description: -The `sha512` function computes `SHA512(x)` of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(sha512 1) ;; Returns 0x6fcee9a7b7a7b821d241c03c82377928bc6882e7a08c78a4221199bfa220cdc55212273018ee613317c8293bb8d1ce08d1e017508e94e06ab85a734c99c7cc34 -``` - -### sha512/256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(sha512/256 value)` -#### description: -The `sha512/256` function computes `SHA512/256(x)` (the SHA512 algorithm with the 512/256 initialization vector, truncated to 256 bits) of the inputted value. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(sha512/256 1) ;; Returns 0x515a7e92e7c60522db968d81ff70b80818fc17aeabbec36baf0dda2812e94a86 -``` - -### keccak256 -#### input: `buff|uint|int` -#### output: `(buff 32)` -#### signature: `(keccak256 value)` -#### description: -The `keccak256` function computes `KECCAK256(value)` of the inputted value. Note that this differs from the `NIST SHA-3` (that is, FIPS 202) standard. If an integer (128 bit) is supplied the hash is computed over the little-endian representation of the integer. -#### example: -```clarity -(keccak256 0) ;; Returns 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4 -``` - -### secp256k1-recover? -#### input: `(buff 32), (buff 65)` -#### output: `(response (buff 33) uint)` -#### signature: `(secp256k1-recover? message-hash signature)` -#### description: -The `secp256k1-recover?` function recovers the public key used to sign the message which sha256 is `message-hash` with the provided `signature`. If the signature does not match, it will return the error code `(err u1).`. If the signature is invalid, it will return the error code `(err u2).`. The signature includes 64 bytes plus an additional recovery id (00..03) for a total of 65 bytes. -#### example: -```clarity -(secp256k1-recover? 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a1301) - ;; Returns (ok 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) - ``` - -### secp256k1-verify -#### input: `(buff 32), (buff 64) | (buff 65), (buff 33)` -#### output: `bool` -#### signature: `(secp256k1-verify message-hash signature public-key)` -#### description: -The `secp256k1-verify` function verifies that the provided signature of the message-hash was signed with the private key that generated the public key. The `message-hash` is the `sha256` of the message. The signature includes 64 bytes plus an optional additional recovery id (00..03) for a total of 64 or 65 bytes. -#### example: -```clarity -(secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a1301 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns true -(secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04 - 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a13 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns true -(secp256k1-verify 0x0000000000000000000000000000000000000000000000000000000000000000 - 0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000 - 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns false - ``` - -### print -#### input: `A` -#### output: `A` -#### signature: `(print expr)` -#### description: -The `print` function evaluates and returns its input expression. On Stacks Core nodes configured for development (as opposed to production mining nodes), this function prints the resulting value to `STDOUT` (standard output). -#### example: -```clarity -(print (+ 1 2 3)) ;; Returns 6 -``` - -### contract-call? -#### input: `ContractName, PublicFunctionName, Arg0, ...` -#### output: `(response A B)` -#### signature: `(contract-call? .contract-name function-name arg0 arg1 ...)` -#### description: -The `contract-call?` function executes the given public function of the given contract. You _may not_ use this function to call a public function defined in the current contract. If the public function returns _err_, any database changes resulting from calling `contract-call?` are aborted. If the function returns _ok_, database changes occurred. -#### example: -```clarity - -;; instantiate the sample-contracts/tokens.clar contract first! -(as-contract (contract-call? .tokens mint! u19)) ;; Returns (ok u19) -``` - -### as-contract -#### input: `A` -#### output: `A` -#### signature: `(as-contract expr)` -#### description: -The `as-contract` function switches the current context's `tx-sender` value to the _contract's_ principal and executes `expr` with that context. It returns the resulting value of `expr`. -#### example: -```clarity -(as-contract tx-sender) ;; Returns S1G2081040G2081040G2081040G208105NK8PE5.docs-test -``` - -### contract-of -#### input: `Trait` -#### output: `principal` -#### signature: `(contract-of .contract-name)` -#### description: -The `contract-of` function returns the principal of the contract implementing the trait. -#### example: -```clarity -(use-trait token-a-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) -(define-public (forward-get-balance (user principal) (contract )) - (begin - (ok (contract-of contract)))) ;; returns the principal of the contract implementing -``` - -### principal-of? -#### input: `(buff 33)` -#### output: `(response principal uint)` -#### signature: `(principal-of? public-key)` public-key) -#### description: -The `principal-of?` function returns the principal derived from the provided public key. The `principal-of?` function returns the principal derived from the provided public key. If the `public-key` is invalid, it will return the error code `(err u1).`. ` ` -#### example: -```clarity -(principal-of? 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns (ok ST1AW6EKPGT61SQ9FNVDS17RKNWT8ZP582VF9HSCP) -``` - -### at-block -#### input: `(buff 32), A` -#### output: `A` -#### signature: `(at-block id-block-hash expr)` -#### description: -The `at-block` function evaluates the expression `expr` _as if_ it were evaluated at the end of the block indicated by the _block-hash_ argument. The `expr` closure must be read-only. - -Note: The block identifying hash must be a hash returned by the `id-header-hash` block information property. This hash uniquely identifies Stacks blocks and is unique across Stacks forks. While the hash returned by `header-hash` is unique within the context of a single fork, it is not unique across Stacks forks. - -The function returns the result of evaluating `expr`. - -#### example: -```clarity -(define-data-var data int 1) -(at-block 0x0000000000000000000000000000000000000000000000000000000000000000 block-height) ;; Returns u0 -(at-block (get-block-info? id-header-hash 0) (var-get data)) ;; Throws NoSuchDataVariable because `data` wasn't initialized at block height 0 -``` - -### get-block-info? -#### input: `BlockInfoPropertyName, BlockHeightInt` -#### output: `(optional buff) | (optional uint)` -#### signature: `(get-block-info? prop-name block-height-expr)` -#### description: -The `get-block-info?` function fetches data for a block of the given block height. The value and type returned are determined by the specified `BlockInfoPropertyName`. If the provided `BlockHeightInt` does not correspond to an existing block prior to the current block, the function returns `none`. The currently available property names are `time`, `header-hash`, `burnchain-header-hash`, `id-header-hash`, `miner-address`, and `vrf-seed`. - -The `time` property returns an integer value of the block header time field. This is a Unix epoch timestamp in seconds which roughly corresponds to when the block was mined. **Warning**: this does not increase monotonically with each block and block times are accurate only to within two hours. See [BIP113](https://github.com/bitcoin/bips/blob/master/bip-0113.mediawiki) for more information. - -The `header-hash`, `burnchain-header-hash`, `id-header-hash`, and `vrf-seed` properties return a 32-byte buffer. - -The `miner-address` property returns a `principal` corresponding to the miner of the given block. - -The `id-header-hash` is the block identifier value that must be used as input to the `at-block` function. - -#### example: -```clarity -(get-block-info? time u0) ;; Returns (some u1557860301) -(get-block-info? header-hash u0) ;; Returns (some 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb) -(get-block-info? vrf-seed u0) ;; Returns (some 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4) -``` - -### err -#### input: `A` -#### output: `(response A B)` -#### signature: `(err value)` -#### description: -The `err` function constructs a response type from the input value. Use `err` for creating return values in public functions. The `err` function constructs a response type from the input value. Use `err` for creating return values in public functions. An _err_ value indicates that any database changes during the processing of the function should be rolled back. -#### example: -```clarity -(err true) ;; Returns (err true) -``` - -### ok -#### input: `A` -#### output: `(response A B)` -#### signature: `(ok value)` -#### description: -The `ok` function constructs a response type from the input value. Use `ok` for creating return values in public functions. An _ok_ value indicates that any database changes during the processing of the function should materialize. -#### example: -```clarity -(ok 1) ;; Returns (ok 1) -``` - -### some -#### input: `A` -#### output: `(optional A)` -#### signature: `(some value)` -#### description: -The `some` function constructs a `optional` type from the input value. -#### example: -```clarity -(some 1) ;; Returns (some 1) -(is-none (some 2)) ;; Returns false -``` - -### default-to -#### input: `A, (optional A)` -#### output: `A` -#### signature: `(default-to default-value option-value)` -#### description: -The `default-to` function attempts to 'unpack' the second argument: if the argument is a `(some ...)` option, it returns the inner value of the option. If the second argument is a `(none)` value, `default-to` it returns the value of `default-value`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(default-to 0 (get id (map-get? names-map (tuple (name \"blockstack\"))))) ;; Returns 1337 -(default-to 0 (get id (map-get? names-map (tuple (name \"non-existant\"))))) ;; Returns 0 -``` - -### asserts! -#### input: `bool, C` -#### output: `bool` -#### signature: `(asserts! signature: (asserts! bool-expr thrown-value)` -#### description: -The `asserts!` function admits a boolean argument and asserts its evaluation: if bool-expr is `true`, `asserts!` returns `true` and proceeds in the program execution. If the supplied argument is returning a false value, `asserts!` _returns_ `thrown-value` and exits the current control-flow. If the supplied argument is returning a false value, `asserts!` _returns_ `thrown-value` and exits the current control-flow. -#### example: -```clarity -(asserts! (is-eq 1 1) (err 1)) ;; Returns true -``` - -### unwrap! -#### input: `(optional A) | (response A B), C` -#### output: `A` -#### signature: `(unwrap! option-input thrown-value)` -#### description: -The `unwrap!` function attempts to 'unpack' the first argument: if the argument is an option type, and the argument is a `(some ...)` option, `unwrap!` returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, `unwrap!` returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `(none)` value, `unwrap!` _returns_ `thrown-value` from the current function and exits the current control-flow. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(define-private (get-name-or-err (name (string-ascii 12))) - (let ((raw-name (unwrap! (map-get? names-map { name: name }) (err 1)))) - (ok raw-name))) - -(get-name-or-err \"blockstack\") ;; Returns (ok (tuple (id 1337))) -(get-name-or-err \"non-existant\") ;; Returns (err 1) -``` - -### unwrap-err! -#### input: `(response A B), C` -#### output: `B` -#### signature: `(unwrap-err! response-input thrown-value)` -#### description: -The `unwrap-err!` function attempts to 'unpack' the first argument: if the argument is an `(err ...)` response, `unwrap-err!` returns the inner value of the `err`. If the supplied argument is an `(ok ...)` value, `unwrap-err!` _returns_ `thrown-value` from the current function and exits the current control-flow. -#### example: -```clarity -(unwrap-err! (err 1) false) ;; Returns 1 -``` - -### unwrap-panic -#### input: `(optional A) | (response A B)` -#### output: `A` -#### signature: `(unwrap-panic option-input)` -#### description: -The `unwrap` function attempts to 'unpack' its argument: if the argument is an option type, and the argument is a `(some ...)` option, this function returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, it returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `(none)` value, `unwrap` throws a runtime error, aborting any further processing of the current transaction. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(unwrap-panic (map-get? names-map { name: \"blockstack\" })) ;; Returns (tuple (id 1337)) -(unwrap-panic (map-get? names-map { name: \"non-existant\" })) ;; Throws a runtime exception -``` - -### unwrap-err-panic -#### input: `(response A B)` -#### output: `B` -#### signature: `(unwrap-err-panic response-input)` -#### description: -The `unwrap-err` function attempts to 'unpack' the first argument: if the argument is an `(err ...)` response, `unwrap` returns the inner value of the `err`. If the supplied argument is an `(ok ...)` value, `unwrap-err` throws a runtime error, aborting any further processing of the current transaction. If the supplied argument is an `(ok ...)` value, `unwrap-err` throws a runtime error, aborting any further processing of the current transaction. -#### example: -```clarity -(unwrap-err-panic (err 1)) ;; Returns 1 -(unwrap-err-panic (ok 1)) ;; Throws a runtime exception -``` - -### match -#### input: `(optional A) name expression expression | (response A B) name expression name expression` -#### output: `C` -#### signature: `(match opt-input some-binding-name some-branch none-branch) | -(match-resp input ok-binding-name ok-branch err-binding-name err-branch)` -#### description: -The `match` function is used to test and destructure optional and response types. - -If the `input` is an optional, it tests whether the provided `input` is a `some` or `none` option, and evaluates `some-branch` or `none-branch` in each respective case. - -Within the `some-branch`, the _contained value_ of the `input` argument is bound to the provided `some-binding-name` name. - -Only _one_ of the branches will be evaluated (similar to `if` statements). - -If the `input` is a response, it tests whether the provided `input` is an `ok` or `err` response type, and evaluates `ok-branch` or `err-branch` in each respective case. - -Within the `ok-branch`, the _contained ok value_ of the `input` argument is bound to the provided `ok-binding-name` name. - -Within the `err-branch`, the _contained err value_ of the `input` argument is bound to the provided `err-binding-name` name. - -Only _one_ of the branches will be evaluated (similar to `if` statements). - -Note: Type checking requires that the type of both the ok and err parts of the response object be determinable. For situations in which one of the parts of a response is untyped, you should use `unwrap-panic` or `unwrap-err-panic` instead of `match`. -#### example: -```clarity - -(define-private (add-10 (x (optional int))) - (match x - value (+ 10 value) - 10)) -(add-10 (some 5)) ;; Returns 15 -(add-10 none) ;; Returns 10 - -(define-private (add-or-pass-err (x (response int (string-ascii 10))) (to-add int)) - (match x - value (ok (+ to-add value)) - err-value (err err-value))) -(add-or-pass-err (ok 5) 20) ;; Returns (ok 25) -(add-or-pass-err (err \"ERROR\") 20) ;; Returns (err \"ERROR\") -``` - -### try! -#### input: `(optional A) | (response A B)` -#### output: `A` -#### signature: `(try! signature: (try! option-input)` -#### description: -The `try!` function attempts to 'unpack' the first argument: if the argument is an option type, and the argument is a `(some ...)` option, `try!` returns the inner value of the option. If the argument is a response type, and the argument is an `(ok ...)` response, `try!` returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `none` value, `try!` _returns_ either `none` or the `(err ...)` value from the current function and exits the current control-flow. If the argument is a response type, and the argument is an `(ok ...)` response, `try!` returns the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `none` value, `try!` _returns_ either `none` or the `(err ...)` value from the current function and exits the current control-flow. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(try! (map-get? names-map { name: \"blockstack\" })) ;; Returns (tuple (id 1337)) -(define-private (checked-even (x int)) - (if (is-eq (mod x 2) 0) - (ok x) - (err false))) -(define-private (double-if-even (x int)) - (ok (* 2 (try! (checked-even x))))) -(double-if-even 10) ;; Returns (ok 20) -(double-if-even 3) ;; Returns (err false) -``` - -### is-ok -#### input: `(response A B)` -#### output: `bool` -#### signature: `(is-ok value)` -#### description: -`is-ok` tests a supplied response value, returning `true` if the response was `ok`, and `false` if it was an `err`. -#### example: -```clarity -(is-ok (ok 1)) ;; Returns true -(is-ok (err 1)) ;; Returns false -``` - -### is-none -#### input: `(optional A)` -#### output: `bool` -#### signature: `(is-none value)` -#### description: -`is-none` tests a supplied option value, returning `true` if the option value is `(none)`, and `false` if it is a `(some ...)`. -#### example: -```clarity -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(is-none (get id (map-get? names-map { name: \"blockstack\" }))) ;; Returns false -(is-none (get id (map-get? names-map { name: \"non-existant\" }))) ;; Returns true -``` - -### is-err -#### input: `(response A B)` -#### output: `bool` -#### signature: `(is-err value)` -#### description: -`is-err` tests a supplied response value, returning `true` if the response was an `err`, and `false` if it was an `ok`. -#### example: -```clarity -(is-err (ok 1)) ;; Returns false -(is-err (err 1)) ;; Returns true -``` - -### is-some -#### input: `(optional A)` -#### output: `bool` -#### signature: `(is-some value)` -#### description: -`is-some` tests a supplied option value, returning `true` if the option value is `(some ...)`, and `false` if it is a `none`. -#### example: -```clarity - -(define-map names-map { name: (string-ascii 12) } { id: int }) -(map-set names-map { name: \"blockstack\" } { id: 1337 }) -(is-some (get id (map-get? names-map { name: \"blockstack\" }))) ;; Returns true -(is-some (get id (map-get? names-map { name: \"non-existant\" }))) ;; Returns false -``` - -### filter -#### input: `Function(A) -> bool, sequence_A` -#### output: `sequence_A` -#### signature: `(filter func sequence)` -#### description: -The `filter` function applies the input function `func` to each element of the input sequence, and returns the same sequence with any elements removed for which `func` returned `false`. Applicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`, for which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`. The `func` argument must be a literal function name. ` -#### example: -```clarity - -(filter not (list true false true false)) ;; Returns (false false) -(define-private (is-a (char (string-utf8 1))) (is-eq char u\"a\")) -(filter is-a u\"acabd\") ;; Returns u\"aa\" -(define-private (is-zero (char (buff 1))) (is-eq char 0x00)) -(filter is-zero 0x00010002) ;; Returns 0x0000 -``` - -### ft-get-balance -#### input: `TokenName, principal` -#### output: `uint` -#### signature: `(ft-get-balance token-name principal)` -#### description: -`ft-get-balance` returns `token-name` balance of the principal `principal`. The token type must have been defined using `define-fungible-token`. The token type must have been defined using `define-fungible-token`. -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-get-balance stackaroo 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns u100 -``` - -### nft-get-owner? -#### input: `AssetName, A` -#### output: `(optional principal)` -#### signature: `(nft-get-owner? asset-class asset-identifier)` asset-class asset-identifier) -#### description: -`nft-get-owner?` returns the owner of an asset, identified by `asset-identifier`, or `none` if the asset does not exist. The asset type must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. The asset type must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) -(nft-get-owner? stackaroo \"Roo\") ;; Returns (some SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) -(nft-get-owner? stackaroo \"Too\") ;; Returns none -``` - -### ft-transfer? -#### input: `TokenName, uint, principal, principal` -#### output: `(response bool uint)` -#### signature: `(ft-transfer? signature: (ft-transfer? token-name amount sender recipient)` -#### description: -`ft-transfer?` is used to increase the token balance for the `recipient` principal for a token type defined using `define-fungible-token` by debiting the `sender` principal. In contrast to `stx-transfer?`, any user can transfer the assets. When used, relevant guards need to be added. In contrast to `stx-transfer?`, any user can transfer the assets. When used, relevant guards need to be added. - -This function returns (ok true) if the transfer is successful. This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- amount to send is non-positive ` -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-transfer? stackaroo u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(ft-transfer? stackaroo u60 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u1) -``` - -### nft-transfer? -#### input: `AssetName, A, principal, principal` -#### output: `(response bool uint)` -#### signature: `(nft-transfer? signature: (nft-transfer? asset-class asset-identifier sender recipient)` -#### description: -`nft-transfer?` is used to change the owner of an asset identified by `asset-identifier` from `sender` to `recipient`. The `asset-class` must have been defined by `define-non-fungible-token` and `asset-identifier` must be of the type specified in that definition. In contrast to `stx-transfer?`, any user can transfer the asset. When used, relevant guards need to be added. The `asset-class` must have been defined by `define-non-fungible-token` and `asset-identifier` must be of the type specified in that definition. In contrast to `stx-transfer?`, any user can transfer the asset. When used, relevant guards need to be added. - -This function returns (ok true) if the transfer is successful. This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not own the asset `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- asset identified by asset-identifier does not exist ` -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(nft-transfer? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(nft-transfer? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u1) -(nft-transfer? stackaroo \"Stacka\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u3) -``` - -### nft-mint? -#### input: `AssetName, A, principal` -#### output: `(response bool uint)` -#### signature: `(nft-mint? asset-class asset-identifier recipient)` -#### description: -`nft-mint?` is used to instantiate an asset and set that asset's owner to the `recipient` principal. The asset must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. - -If an asset identified by `asset-identifier` _already exists_, this function will return an error with the following error code: - -`(err u1)` - -Otherwise, on successfuly mint, it returns `(ok true)`. ` -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### ft-mint? -#### input: `TokenName, uint, principal` -#### output: `(response bool uint)` -#### signature: `(ft-mint? token-name amount recipient)` token-name amount recipient) -#### description: -`ft-mint?` is used to increase the token balance for the `recipient` principal for a token type defined using `define-fungible-token`. The increased token balance is _not_ transfered from another principal, but rather minted. The increased token balance is _not_ transfered from another principal, but rather minted. - -If a non-positive amount is provided to mint, this function returns `(err 1)`. Otherwise, on successfuly mint, it returns `(ok true)`. ` Otherwise, on successfuly mint, it returns `(ok true)`. ` ` -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) stackaroo u100 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### ft-get-supply -#### input: `TokenName` -#### output: `uint` -#### signature: `(ft-get-supply token-name)` -#### description: -`ft-get-balance` returns `token-name` circulating supply. `ft-get-balance` returns `token-name` circulating supply. The token type must have been defined using `define-fungible-token`. -#### example: -```clarity -(define-fungible-token stackaroo) -(ft-mint? (define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) -(ft-get-supply stackaroo) ;; Returns u100 -``` - -### ft-burn? -#### input: `TokenName, uint, principal` -#### output: `(response bool uint)` -#### signature: `(ft-burn? token-name amount sender)` token-name amount sender) -#### description: -`ft-burn?` is used to decrease the token balance for the `sender` principal for a token type defined using `define-fungible-token`. The decreased token balance is _not_ transfered to another principal, but rather destroyed, reducing the circulating supply. The decreased token balance is _not_ transfered to another principal, but rather destroyed, reducing the circulating supply. - -If a non-positive amount is provided to burn, this function returns `(err 1)`. Otherwise, on successfuly burn, it returns `(ok true)`. ` Otherwise, on successfuly burn, it returns `(ok true)`. - -#### example: -```clarity - -(define-fungible-token stackaroo) -(ft-mint? (define-fungible-token stackaroo) -(ft-mint? stackaroo u100 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(ft-burn? stackaroo u50 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) stackaroo u50 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### nft-burn? -#### input: `AssetName, A, principal` -#### output: `(response bool uint)` -#### signature: `(nft-burn? signature: (nft-burn? asset-class asset-identifier recipient)` -#### description: -`nft-burn?` is used to burn an asset and remove that asset's owner from the `recipient` principal. The asset must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. `nft-mint?` is used to instantiate an asset and set that asset's owner to the `recipient` principal. The asset must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in that definition. - -If an asset identified by `asset-identifier` _doesn't exist_, this function will return an error with the following error code: - -`(err u1)` - -Otherwise, on successfuly burn, it returns `(ok true)`. ` ` -#### example: -```clarity -(define-non-fungible-token stackaroo (string-ascii 40)) -(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -(nft-burn? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true) -``` - -### stx-get-balance -#### input: `principal` -#### output: `uint` -#### signature: `(stx-get-balance owner)` -#### description: -`stx-get-balance` is used to query the STX balance of the `owner` principal. - -This function returns the STX balance of the `owner` principal. In the event that the `owner` principal isn't materialized, it returns 0. ` In the event that the `owner` principal isn't materialized, it returns 0. - -#### example: -```clarity -(stx-get-balance 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns u0 -(stx-get-balance (as-contract tx-sender)) ;; Returns u1000 -``` - -### stx-transfer? -#### input: `uint, principal, principal` -#### output: `(response bool uint)` -#### signature: `(stx-transfer? amount sender recipient)` amount sender recipient) -#### description: -`stx-transfer?` is used to increase the STX balance for the `recipient` principal by debiting the `sender` principal. The `sender` principal _must_ be equal to the current context's `tx-sender`. The `sender` principal _must_ be equal to the current context's `tx-sender`. - -This function returns (ok true) if the transfer is successful. This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u2)` -- `sender` and `recipient` are the same principal `(err u3)` -- amount to send is non-positive `(err u4)` -- the `sender` principal is not the current `tx-sender` - -#### example: -```clarity - -(as-contract - (stx-transfer? (as-contract - (stx-transfer? u60 tx-sender 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (ok true) -(as-contract - (stx-transfer? u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR tx-sender)) ;; Returns (err u4) u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR tx-sender)) ;; Returns (err u4) -``` - -### stx-burn? -#### input: `uint, principal` -#### output: `(response bool uint)` -#### signature: `(stx-burn? amount sender)` amount sender) -#### description: -`stx-burn?` debits the `sender` principal's STX holdings by `amount`, destroying the STX. The `sender` principal _must_ be equal to the current context's `tx-sender`. The `sender` principal _must_ be equal to the current context's `tx-sender`. - -This function returns (ok true) if the transfer is successful. This function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns one of the following error codes: - -`(err u1)` -- `sender` does not have enough balance to transfer `(err u3)` -- amount to send is non-positive `(err u4)` -- the `sender` principal is not the current `tx-sender` - -#### example: -```clarity -(as-contract - (stx-burn? (as-contract - (stx-burn? u60 tx-sender)) ;; Returns (ok true) -(as-contract - (stx-burn? u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (err u4) u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (err u4) -``` - -### define-constant -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-constant name expression)` -#### description: -`define-constant` is used to define a private constant value in a smart contract. The expression passed into the definition is evaluated at contract launch, in the order that it is supplied in the contract. This can lead to undefined function or undefined variable errors in the event that a function or variable used in the expression has not been defined before the constant. The expression passed into the definition is evaluated at contract launch, in the order that it is supplied in the contract. This can lead to undefined function or undefined variable errors in the event that a function or variable used in the expression has not been defined before the constant. - -Like other kinds of definition statements, `define-constant` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -#### example: -```clarity - -(define-constant four (+ 2 2)) -(+ 4 four) ;; Returns 8 -``` - -### define-private -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-private (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### description: -`define-private` is used to define _private_ functions for a smart contract. `define-private` is used to define _private_ functions for a smart contract. Private functions may not be called from other smart contracts, nor may they be invoked directly by users. Instead, these functions may only be invoked by other functions defined in the same smart contract. Instead, these functions may only be invoked by other functions defined in the same smart contract. - -Like other kinds of definition statements, `define-private` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Private functions may return any type. -#### example: -```clarity -(define-private (max-of (i1 int) (i2 int)) - (if (> i1 i2) - i1 - i2)) -(max-of 4 6) ;; Returns 6 -``` - -### define-public -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-public (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### description: -`define-public` is used to define a _public_ function and transaction for a smart contract. Public functions are callable from other smart contracts and may be invoked directly by users by submitting a transaction to the Stacks blockchain. Public functions are callable from other smart contracts and may be invoked directly by users by submitting a transaction to the Stacks blockchain. - -Like other kinds of definition statements, `define-public` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Public functions _must_ return a ResponseType (using either `ok` or `err`). Any datamap modifications performed by a public function is aborted if the function returns an `err` type. Public functions may be invoked by other contracts via `contract-call?`. Any datamap modifications performed by a public function is aborted if the function returns an `err` type. Public functions may be invoked by other contracts via `contract-call?`. -#### example: -```clarity -(define-public (hello-world (input int)) - (begin (print (+ 2 input)) - (ok input))) -``` - -### define-read-only -#### input: `MethodSignature, MethodBody` -#### output: `Not Applicable` -#### signature: `(define-read-only (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)` -#### description: -`define-read-only` is used to define a _public read-only_ function for a smart contract. Such functions are callable from other smart contracts. Such functions are callable from other smart contracts. - -Like other kinds of definition statements, `define-read-only` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Read-only functions may return any type. Read-only functions may return any type. However, read-only functions may not perform any datamap modifications, or call any functions which perform such modifications. This is enforced both during type checks and during the execution of the function. Public read-only functions may be invoked by other contracts via `contract-call?`. This is enforced both during type checks and during the execution of the function. Public read-only functions may be invoked by other contracts via `contract-call?`. -#### example: -```clarity -(define-read-only (just-return-one-hundred) - (* 10 10)) - ``` - -### define-map -#### input: `MapName, TypeDefinition, TypeDefinition` -#### output: `Not Applicable` -#### signature: `(define-map map-name key-type value-type)` -#### description: -`define-map` is used to define a new datamap for use in a smart contract. Such maps are only modifiable by the current smart contract. - -Maps are defined with a key type and value type, often these types are tuple types. - -Like other kinds of definition statements, `define-map` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). -#### example: -```clarity -(define-map squares { x: int } { square: int }) -(define-private (add-entry (x int)) - (map-insert squares { x: 2 } { square: (* x x) })) -(add-entry 1) -(add-entry 2) -(add-entry 3) -(add-entry 4) -(add-entry 5) -``` - -### define-data-var -#### input: `VarName, TypeDefinition, Value` -#### output: `Not Applicable` -#### signature: `(define-data-var var-name type value)` -#### description: -`define-data-var` is used to define a new persisted variable for use in a smart contract. Such variable are only modifiable by the current smart contract. Such variable are only modifiable by the current smart contract. - -Persisted variable are defined with a type and a value. - -Like other kinds of definition statements, `define-data-var` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). -#### example: -```clarity -(define-data-var size int 0) -(define-private (set-size (value int)) - (var-set size value)) -(set-size 1) -(set-size 2) -``` - -### define-fungible-token -#### input: `TokenName, ` -#### output: `Not Applicable` -#### signature: `(define-fungible-token token-name )` -#### description: -`define-fungible-token` is used to define a new fungible token class for use in the current contract. - -The second argument, if supplied, defines the total supply of the fungible token. This ensures that all calls to the `ft-mint?` function will never be able to create more than `total-supply` tokens. The second argument, if supplied, defines the total supply of the fungible token. This ensures that all calls to the `ft-mint?` function will never be able to create more than `total-supply` tokens. If any such call were to increase the total supply of tokens passed that amount, that invocation of `ft-mint?` will result in a runtime error and abort. - -Like other kinds of definition statements, `define-fungible-token` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Tokens defined using `define-fungible-token` may be used in `ft-transfer?`, `ft-mint?`, and `ft-get-balance` functions` -#### example: -```clarity -(define-fungible-token stacks) -(define-fungible-token limited-supply-stacks u100) -``` - -### define-non-fungible-token -#### input: `AssetName, TypeSignature` -#### output: `Not Applicable` -#### signature: `(define-non-fungible-token asset-name asset-identifier-type)` -#### description: -`define-non-fungible-token` is used to define a new non-fungible token class for use in the current contract. Individual assets are identified by their asset identifier, which must be of the type `asset-identifier-type`. Asset identifiers are _unique_ identifiers. Individual assets are identified by their asset identifier, which must be of the type `asset-identifier-type`. Asset identifiers are _unique_ identifiers. - -Like other kinds of definition statements, `define-non-fungible-token` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). - -Assets defined using `define-non-fungible-token` may be used in `nft-transfer?`, `nft-mint?`, and `nft-get-owner?` functions` -#### example: -```clarity -(define-non-fungible-token names (buff 50)) -``` - -### define-trait -#### input: `VarName, [MethodSignature]` -#### output: `Not Applicable` -#### signature: `(define-trait trait-name ((func1-name (arg1-type arg2-type ...) (return-type))))` -#### description: -`define-trait` is used to define a new trait definition for use in a smart contract. `define-trait` is used to define a new trait definition for use in a smart contract. Other contracts can implement a given trait and then have their contract identifier being passed as function arguments in order to be called dynamically with `contract-call?`. - -Traits are defined with a name, and a list functions defined with a name, a list of argument types, and return type. - -Like other kinds of definition statements, `define-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put a define statement in the middle of a function body). ` - -#### example: -```clarity -(define-trait token-trait - ((transfer? (define-trait token-trait - ((transfer? (principal principal uint) (response uint uint)) - (get-balance (principal) (response uint uint)))) -``` - -### use-trait -#### input: `VarName, TraitIdentifier` -#### output: `Not Applicable` -#### signature: `(use-trait trait-alias trait-identifier)` -#### description: -`use-trait` is used to bring a trait, defined in another contract, to the current contract. Subsequent references to an imported trait are signaled with the syntax ``. Subsequent references to an imported trait are signaled with the syntax ``. - -Traits import are defined with a name, used as an alias, and a trait identifier. Traits import are defined with a name, used as an alias, and a trait identifier. Trait identifiers can either be using the sugared syntax (.token-a.token-trait), or be fully qualified ('SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait). - -Like other kinds of definition statements, `use-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put such a statement in the middle of a function body). ` -#### example: -```clarity -(use-trait token-a-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) -(define-public (forward-get-balance (user principal) (contract )) - (begin - (ok 1))) -``` - -### impl-trait -#### input: `TraitIdentifier` -#### output: `Not Applicable` -#### signature: `(impl-trait trait-identifier)` -#### description: -`impl-trait` can be use for asserting that a contract is fully implementing a given trait. `impl-trait` can be use for asserting that a contract is fully implementing a given trait. Additional checks are being performed when the contract is being published, rejecting the deployment if the contract is violating the trait specification. - -Trait identifiers can either be using the sugared syntax (.token-a.token-trait), or be fully qualified ('SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait). - -Like other kinds of definition statements, `impl-trait` may only be used at the top level of a smart contract definition (i.e., you cannot put such a statement in the middle of a function body). ` - -#### example: -```clarity -(impl-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait) (define-public (get-balance (account principal)) (ok u0)) (define-public (transfer? (from principal) (to principal) (amount uint)) (ok u0)) " } (from principal) (to principal) (amount uint)) - (ok u0)) -``` \ No newline at end of file diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md b/i18n/zh/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md deleted file mode 100644 index 01740cb012..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-keywords.md +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: Keywords -description: See a detailed list of all keywords for the Clarity language. -tags: - - clarity ---- - -![](/img/keywords.jpg) -## Keyword reference - -Detailed list of all keywords for the Clarity language. - - -### contract-caller -#### output: `principal` -#### description: -Returns the caller of the current contract context. If this contract is the first one called by a signed transaction, the caller will be equal to the signing principal. Returns the caller of the current contract context. If this contract is the first one called by a signed transaction, the caller will be equal to the signing principal. If `contract-call?` was used to invoke a function from a new contract, `contract-caller` changes to the _calling_ contract's principal. If `as-contract` is used to change the `tx-sender` context, `contract-caller` _also_ changes to the same contract principal. If `as-contract` is used to change the `tx-sender` context, `contract-caller` _also_ changes to the same contract principal. -#### example: -```clarity -(print contract-caller) ;; Will print out a Stacks address of the transaction sender -``` - -### tx-sender -#### output: `principal` -#### description: -Returns the original sender of the current transaction, or if `as-contract` was called to modify the sending context, it returns that contract principal. -#### example: -```clarity -(print tx-sender) ;; Will print out a Stacks address of the transaction sender -``` - -### block-height -#### output: `uint` -#### description: -Returns the current block height of the Stacks blockchain as an uint -#### example: -```clarity -(> block-height 1000) ;; returns true if the current block-height has passed 1000 blocks. -``` - -### burn-block-height -#### output: `uint` -#### description: -Returns the current block height of the underlying burn blockchain as a uint -#### example: -```clarity -(> burn-block-height 1000) ;; returns true if the current height of the underlying burn blockchain has passed 1000 blocks. -``` - -### none -#### output: `(optional ?)` -#### description: -Represents the _none_ option indicating no value for a given optional (analogous to a null value). -#### example: -```clarity -(define-public (only-if-positive (a int)) - (if (> a 0) - (some a) - none)) -(only-if-positive 4) ;; Returns (some 4) -(only-if-positive (- 3)) ;; Returns none -``` - -### true -#### output: `bool` -#### description: -Boolean true constant. -#### example: -```clarity -(and true false) ;; Evaluates to false -(or false true) ;; Evaluates to true -``` - -### false -#### output: `bool` -#### description: -Boolean false constant. -#### example: -```clarity -(and true false) ;; Evaluates to false -(or false true) ;; Evaluates to true -``` - -### stx-liquid-supply -#### output: `uint` -#### description: -Returns the total number of micro-STX (uSTX) that are liquid in the system as of this block. -#### example: -```clarity -(print stx-liquid-supply) ;; Will print out the total number of liquid uSTX -``` - -### is-in-regtest -#### output: `bool` -#### description: -Returns whether or not the code is running in a regression test -#### example: -```clarity -(print is-in-regtest) ;; Will print 'true' if the code is running in a regression test -``` - diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md b/i18n/zh/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md deleted file mode 100644 index 360e201a22..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/write-smart-contracts/clarity-language/language-types.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Types -description: See a detailed list of all types for the Clarity language. -tags: - - clarity ---- - -## Clarity Type System - -The type system contains the following types: - -| Types | Notes | -| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `int` | signed 128-bit integer | -| `uint` | unsigned 128-bit integer | -| `bool` | boolean value (`true` or `false`) | -| `principal` | object representing a principal (whether a contract principal or standard principal) | -| `(buff max-len)` | byte buffer of 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` (u"A smiley face emoji \u{1F600} as a utf8 string") | -| `(list max-len entry-type)` | list of maximum length `max-len`, with entries of type `entry-type` | -| `{label-0: value-type-0, label-1: value-type-1, ...}` | tuple, group of data values with named fields | -| `(optional some-type)` | an option type for objects that can either be `(some value)` or `none` | -| `(response ok-type err-type)` | object used by public functions to commit their changes or abort. 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. | diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md b/i18n/zh/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md deleted file mode 100644 index 29c02cef41..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/write-smart-contracts/index.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: Clarity overview -description: Overview and guides for getting started with Clarity -sidebar_label: Write smart contracts -sidebar_position: 2 ---- - -## Introduction - -Clarity is a **decidable** smart contract language that optimizes for predictability and security, designed for the Stacks blockchain. Smart contracts allow developers to encode essential business logic on a blockchain. Smart contracts allow developers to encode essential business logic on a blockchain. - -## Smart contracts - -Smart contracts encode and enforce rules for modifying a particular set of data that is shared among people and entities who don't necessarily trust each other. For example, a smart contract can hold funds in escrow until multiple parties agree to release them, create its own ledger and keep track of its own novel tokens (fungible or non-fungible), and even help make supply chains more transparent. For example, a smart contract can hold funds in escrow until multiple parties agree to release them, create its own ledger and keep track of its own novel tokens (fungible or non-fungible), and even help make supply chains more transparent. - -Because smart contracts are programs that exist in a blockchain, anyone can query them, and anyone can submit transactions to execute them. A smart contract execution can result in new transactions being written to the blockchain. A smart contract execution can result in new transactions being written to the blockchain. A smart contract execution can result in new transactions being written to the blockchain. - -Apps can take advantage of smart contracts to manage a global state that is visible to the public. Apps can take advantage of smart contracts to manage a global state that is visible to the public. Apps can take advantage of smart contracts to manage a global state that is visible to the public. Anyone can audit the blockchain to independently verify that an app's global shared state has been managed correctly according to the smart contract's rules. - -There is a [Clarity Visual Studio Code plugin][] available for syntax assistance and debugging. - -## Use cases - -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: Examples of use cases include, but are not limited to: Examples of use cases include, but are not limited to: - -- 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 - -## Language design - -Clarity differs from most other smart contract languages in two essential ways: - -- The language is interpreted and broadcast on the blockchain as is (not compiled) -- The language is decidable (not Turing complete) - -Using an interpreted language ensures that the executed code is human-readable and auditable. Using an interpreted language ensures that the executed code is human-readable and auditable. A decidable language like Clarity makes it possible to determine precisely which code is executed, for any function. Using an interpreted language ensures that the executed code is human-readable and auditable. A decidable language like Clarity makes it possible to determine precisely which code is executed, for any function. - -A Clarity smart contract consists of two parts, a data space and a set of functions. Only the associated smart contract may modify its corresponding data space on the blockchain. Functions may be private and thus callable only from within the smart contract, or public and thus callable from other contracts. A Clarity smart contract consists of two parts, a data space and a set of functions. Only the associated smart contract may modify its corresponding data space on the blockchain. Functions may be private and thus callable only from within the smart contract, or public and thus callable from other contracts. A Clarity smart contract consists of two parts, a data space and a set of functions. Only the associated smart contract may modify its corresponding data space on the blockchain. Functions may be private and thus callable only from within the smart contract, or public and thus callable from other contracts. Users call smart contracts' public functions by broadcasting a transaction on the blockchain which invokes the public function. Contracts can also call public functions from other smart contracts. Contracts can also call public functions from other smart contracts. Contracts can also call public functions from other smart contracts. - -Note some of the key Clarity language rules and limitations. - -- The only primitive types are booleans, integers, buffers, and principals. -- Recursion is illegal and there are no anonymous functions. -- Looping is only performed via `map`, `filter`, or `fold`. -- There is support for lists, however, the only variable length lists in the language appear as function inputs; there is no support for list operations like append or join. -- Variables are immutable. - -## Explore more - -For language details and references, see the following: - -- [Clarity language overview](./clarity-language/) -- [Understating Principals](principals) -- [Clarity Values](values) - -[Clarity Visual Studio Code plugin]: https://marketplace.visualstudio.com/items?itemName=HiroSystems.clarity-lsp diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md b/i18n/zh/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md deleted file mode 100644 index fdb65420e8..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/write-smart-contracts/principals.md +++ /dev/null @@ -1,383 +0,0 @@ ---- -title: Principals -description: 'Clarity: Understanding Principals' -sidebar_position: 1 ---- - -## Introduction - -_Principals_ are a Clarity native type that represents an entity that can have a token balance. This section discusses principals and how they are used in the Clarity. This section discusses principals and how they are used in the Clarity. This section discusses principals and how they are used in the Clarity. - -## Principals and tx-sender - -Assets in the smart contracting language and blockchain are "owned" by objects of the principal type, meaning that any object of the principal type may own an asset. For the case of public-key hash and multi-signature Stacks addresses, a given principal can operate on their assets by issuing a signed transaction on the blockchain. _Smart contracts_ may also be principals (represented by the smart contract's identifier), however, there is no private key associated with the smart contract, and it cannot broadcast a signed transaction on the blockchain. For the case of public-key hash and multi-signature Stacks addresses, a given principal can operate on their assets by issuing a signed transaction on the blockchain. _Smart contracts_ may also be principals (represented by the smart contract's identifier), however, there is no private key associated with the smart contract, and it cannot broadcast a signed transaction on the blockchain. For the case of public-key hash and multi-signature Stacks addresses, a given principal can operate on their assets by issuing a signed transaction on the blockchain. _Smart contracts_ may also be principals (represented by the smart contract's identifier), however, there is no private key associated with the smart contract, and it cannot broadcast a signed transaction on the blockchain. - -A Clarity contract can use a globally defined `tx-sender` variable to obtain the current principal. A Clarity contract can use a globally defined `tx-sender` variable to obtain the current principal. The following example defines a transaction type that transfers `amount` microSTX from the sender to a recipient if amount is a multiple of 10, otherwise returning a 400 error code. A Clarity contract can use a globally defined `tx-sender` variable to obtain the current principal. The following example defines a transaction type that transfers `amount` microSTX from the sender to a recipient if amount is a multiple of 10, otherwise returning a 400 error code. - -```clarity -(define-public (transfer-to-recipient! (define-public (transfer-to-recipient! (define-public (transfer-to-recipient! (recipient principal) (amount uint)) - (if (is-eq (mod amount 10) 0) - (stx-transfer? amount tx-sender recipient) - (err u400))) amount tx-sender recipient) - (err u400))) amount tx-sender recipient) - (err u400))) -``` - -Clarity provides an additional variable to help smart contracts authenticate a transaction sender. The keyword `contract-caller` returns the principal that _called_ the current contract. If an inter-contract call occurred, `contract-caller` returns the last contract in the stack of callers. For example, suppose there are three contracts A, B, and C, each with an `invoke` function such that `A::invoke` calls `B::invoke` and `B::invoke` calls `C::invoke`. The keyword `contract-caller` returns the principal that _called_ the current contract. If an inter-contract call occurred, `contract-caller` returns the last contract in the stack of callers. For example, suppose there are three contracts A, B, and C, each with an `invoke` function such that `A::invoke` calls `B::invoke` and `B::invoke` calls `C::invoke`. - -When a user Bob issues a transaction that calls `A::invoke`, the value of `contract-caller` in each successive invoke function's body would change: - -```clarity -in A::invoke, contract-caller = Bob -in B::invoke, contract-caller = A -in C::invoke, contract-caller = B -``` - -This allows contracts to make assertions and perform authorization checks using not only the `tx-sender` (which in this example, would always be "Bob"), but also using the `contract-caller`. This could be used to ensure that a particular function is only ever called directly and never called via an inter-contract call (by asserting that `tx-sender` and `contract-caller` are equal). We provide an example of a two different types of authorization checks in the rocket ship example below. This could be used to ensure that a particular function is only ever called directly and never called via an inter-contract call (by asserting that `tx-sender` and `contract-caller` are equal). We provide an example of a two different types of authorization checks in the rocket ship example below. This could be used to ensure that a particular function is only ever called directly and never called via an inter-contract call (by asserting that `tx-sender` and `contract-caller` are equal). We provide an example of a two different types of authorization checks in the rocket ship example below. - -## Smart contracts as principals - -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, for example: - -```clarity -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-name -``` - -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 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 qualified identifier for the contracts would be: This will be expanded by the Clarity interpreter into 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 qualified identifier for the contracts would be: This will be expanded by the Clarity interpreter into 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 qualified identifier for the contracts would be: - -```clarity -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-A -'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR.contract-B -``` - -But, in the contract source code, if the developer wishes to call a function from `contract-A` in `contract-B`, they can write - -```clarity -(contract-call? (contract-call? (contract-call? .contract-A public-function-foo) -``` - -This allows the smart contract developer to modularize their applications across multiple smart contracts _without_ knowing the publishing key a priori. - -In order for a smart contract to operate on assets it owns, smart contracts may use the special `(as-contract ...)` function. This function executes the expression (passed as an argument) with the `tx-sender` set to the contract's principal, rather than the current sender. The `as-contract` function returns the value of the provided expression. This function executes the expression (passed as an argument) with the `tx-sender` set to the contract's principal, rather than the current sender. The `as-contract` function returns the value of the provided expression. This function executes the expression (passed as an argument) with the `tx-sender` set to the contract's principal, rather than the current sender. The `as-contract` function returns the value of the provided expression. - -For example, a smart contract that implements something like a "token faucet" could be implemented as so: - -```clarity -(define-map claimed-before - ((sender principal)) - ((claimed bool))) - -(define-constant err-already-claimed u1) -(define-constant err-faucet-empty u2) -(define-constant stx-amount u1) - -(define-public (claim-from-faucet) - (let ((requester tx-sender)) ;; set a local variable requester = tx-sender - (asserts! (is-none (map-get? claimed-before {sender: requester})) (err err-already-claimed)) - (unwrap! (as-contract (stx-transfer? stx-amount tx-sender requester)) (err err-faucet-empty)) - (map-set claimed-before {sender: requester} {claimed: true}) - (ok stx-amount))) (is-none (map-get? claimed-before {sender: requester})) (err err-already-claimed)) - (unwrap! (as-contract (stx-transfer? stx-amount tx-sender requester)) (err err-faucet-empty)) - (map-set claimed-before {sender: requester} {claimed: true}) - (ok stx-amount))) (is-none (map-get? claimed-before {sender: requester})) (err err-already-claimed)) - (unwrap! (as-contract (stx-transfer? stx-amount tx-sender requester)) (err err-faucet-empty)) - (map-set claimed-before {sender: requester} {claimed: true}) - (ok stx-amount))) -``` - -In this example, the public function `claim-from-faucet`: - -- Checks if the sender has claimed from the faucet before. -- Assigns the tx sender to a `requester` variable. -- Adds an entry to the tracking map. -- Uses `as-contract` to send 1 microstack - -Unlike other principals, there is no private key associated with a smart contract. Unlike other principals, there is no private key associated with a smart contract. Unlike other principals, there is no private key associated with a smart contract. As it lacks a private key, a Clarity smart contract cannot broadcast a signed transaction on the blockchain. - -## Example: Authorization checks - -The interactions between `tx-sender`, `contract-caller` and `as-contract` are subtle, but are important when performing authorization checks in a contract. In this example contract, we'll show two different kinds of authorization checks a contract may wish to perform, and then walk through how different ways in which contract functions may be called will pass or fail those checks. In this example contract, we'll show two different kinds of authorization checks a contract may wish to perform, and then walk through how different ways in which contract functions may be called will pass or fail those checks. In this example contract, we'll show two different kinds of authorization checks a contract may wish to perform, and then walk through how different ways in which contract functions may be called will pass or fail those checks. - -This contract defines a "rocket-ship" non-fungible-token that a principal may own and manage the authorized pilots. Pilots are principals that are allowed to "fly" the rocket ship. Pilots are principals that are allowed to "fly" the rocket ship. Pilots are principals that are allowed to "fly" the rocket ship. - -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. 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. A pilot could, for example, call another contract, which then calls 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. 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 be called _directly_ by the ship's owner, rather than through a inter-contract-call. 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 be called _directly_ by the ship's owner, rather than through a inter-contract-call. - -The second type of check is more restrictive than the first check, and is helpful for guarding very sensitive routines --- it protects users from unknowingly calling a function on a malicious contract that subsequently tries to call sensitive functions on another contract. - -```clarity -;; -;; rockets-base.clar -;; - -(define-non-fungible-token rocket-ship uint) - -;; a map from rocket ships to their allowed -;; pilots -(define-map allowed-pilots - ((rocket-ship uint)) ((pilots (list 10 principal)))) - -;; implementing a contains function via fold -(define-private (contains-check - (y principal) - (to-check { p: principal, result: bool })) - (if (get result to-check) - to-check - { p: (get p to-check), - result: (is-eq (get p to-check) y) })) - -(define-private (contains (x principal) (find-in (list 10 principal))) - (get result (fold contains-check find-in - { p: x, result: false }))) - -(define-read-only (is-my-ship (ship uint)) - (is-eq (some tx-sender) (nft-get-owner? rocket-ship ship))) - -;; this function will print a message -;; (and emit an event) if the tx-sender was -;; an authorized flyer. -;; -;; here we use tx-sender, because we want -;; to allow the user to let other contracts -;; fly the ship on behalf of users - -(define-public (fly-ship (ship uint)) - (let ((pilots (default-to - (list) - (get pilots (map-get? allowed-pilots { rocket-ship: ship }))))) - (if (contains tx-sender pilots) - (begin (print "Flew the rocket-ship!") - (ok true)) - (begin (print "Tried to fly without permission!") - (ok false))))) -;; -;; Authorize a new pilot. -;; -;; here we want to ensure that this function -;; was called _directly_ by the user by -;; checking that tx-sender and contract-caller are equal. -;; if any other contract is in the call stack, contract-caller -;; would be updated to a different principal. -;; -(define-public (authorize-pilot (ship uint) (pilot principal)) - (begin - ;; sender must equal caller: an intermediate contract is - ;; not issuing this call. - (asserts! (is-eq tx-sender contract-caller) (err u1)) - ;; sender must own the rocket ship - (asserts! (is-eq (some tx-sender) - (nft-get-owner? rocket-ship ship)) (err u2)) - (let ((prev-pilots (default-to - (list) - (get pilots (map-get? allowed-pilots { rocket-ship: ship }))))) - ;; don't add a pilot already in the list - (asserts! (not (contains pilot prev-pilots)) (err u3)) - ;; append to the list, and check that it is less than - ;; the allowed maximum - (match (as-max-len? (append prev-pilots pilot) u10) - next-pilots - (ok (map-set allowed-pilots {rocket-ship: ship} {pilots: next-pilots})) - ;; too many pilots already - (err u4))))) rocket-ship ship))) - -;; this function will print a message -;; (and emit an event) if the tx-sender was -;; an authorized flyer. -;; -;; here we use tx-sender, because we want -;; to allow the user to let other contracts -;; fly the ship on behalf of users - -(define-public (fly-ship (ship uint)) - (let ((pilots (default-to - (list) - (get pilots (map-get? allowed-pilots { rocket-ship: ship }))))) - (if (contains tx-sender pilots) - (begin (print "Flew the rocket-ship!") - (ok true)) - (begin (print "Tried to fly without permission!") - (ok false))))) -;; -;; Authorize a new pilot. -;; -;; here we want to ensure that this function -;; was called _directly_ by the user by -;; checking that tx-sender and contract-caller are equal. -;; if any other contract is in the call stack, contract-caller -;; would be updated to a different principal. -;; -(define-public (authorize-pilot (ship uint) (pilot principal)) - (begin - ;; sender must equal caller: an intermediate contract is - ;; not issuing this call. - (asserts! (is-eq tx-sender contract-caller) (err u1)) - ;; sender must own the rocket ship - (asserts! (is-eq (some tx-sender) - (nft-get-owner? rocket-ship ship)) (err u2)) - (let ((prev-pilots (default-to - (list) - (get pilots (map-get? allowed-pilots { rocket-ship: ship }))))) - ;; don't add a pilot already in the list - (asserts! (not (contains pilot prev-pilots)) (err u3)) - ;; append to the list, and check that it is less than - ;; the allowed maximum - (match (as-max-len? (append prev-pilots pilot) u10) - next-pilots - (ok (map-set allowed-pilots {rocket-ship: ship} {pilots: next-pilots})) - ;; too many pilots already - (err u4))))) rocket-ship ship))) - -;; this function will print a message -;; (and emit an event) if the tx-sender was -;; an authorized flyer. -;; -;; here we use tx-sender, because we want -;; to allow the user to let other contracts -;; fly the ship on behalf of users - -(define-public (fly-ship (ship uint)) - (let ((pilots (default-to - (list) - (get pilots (map-get? allowed-pilots { rocket-ship: ship }))))) - (if (contains tx-sender pilots) - (begin (print "Flew the rocket-ship!") - (ok true)) - (begin (print "Tried to fly without permission!") - (ok false))))) -;; -;; Authorize a new pilot. -;; -;; here we want to ensure that this function -;; was called _directly_ by the user by -;; checking that tx-sender and contract-caller are equal. -;; if any other contract is in the call stack, contract-caller -;; would be updated to a different principal. -;; -(define-public (authorize-pilot (ship uint) (pilot principal)) - (begin - ;; sender must equal caller: an intermediate contract is - ;; not issuing this call. - (asserts! (is-eq tx-sender contract-caller) (err u1)) - ;; sender must own the rocket ship - (asserts! (is-eq (some tx-sender) - (nft-get-owner? rocket-ship ship)) (err u2)) - (let ((prev-pilots (default-to - (list) - (get pilots (map-get? allowed-pilots { rocket-ship: ship }))))) - ;; don't add a pilot already in the list - (asserts! (not (contains pilot prev-pilots)) (err u3)) - ;; append to the list, and check that it is less than - ;; the allowed maximum - (match (as-max-len? (append prev-pilots pilot) u10) - next-pilots - (ok (map-set allowed-pilots {rocket-ship: ship} {pilots: next-pilots})) - ;; too many pilots already - (err u4))))) -``` - -### Extending functionality: Multi-flyer contract - -The authorization scheme for `fly-ship` allows pilots to fly rocket-ships from other contracts. This allows other contracts to provide new functionality built around calling that function. This allows other contracts to provide new functionality built around calling that function. This allows other contracts to provide new functionality built around calling that function. - -For example, we can create a contract that calls `fly-ship` for multiple rocket-ships in a single transaction: - -```clarity -;; -;; rockets-multi.clar -;; - -(define-private (call-fly (ship uint)) - (unwrap! (contract-call? .rockets-base fly-ship ship) false)) -;; try to fly all the ships, returning a list of whether -;; or not we were able to fly the supplied ships -(define-public (fly-all (ships (list 10 uint))) - (ok (map call-fly ships))) (contract-call? ;; -;; rockets-multi.clar -;; - -(define-private (call-fly (ship uint)) - (unwrap! (contract-call? .rockets-base fly-ship ship) false)) -;; try to fly all the ships, returning a list of whether -;; or not we were able to fly the supplied ships -(define-public (fly-all (ships (list 10 uint))) - (ok (map call-fly ships))) (contract-call? .rockets-base fly-ship ship) false)) -;; try to fly all the ships, returning a list of whether -;; or not we were able to fly the supplied ships -(define-public (fly-all (ships (list 10 uint))) - (ok (map call-fly ships))) -``` - -### Authorization for Contract-Owned Assets - -The check in `authorize-pilot` protects users from malicious contracts, but how would such a scheme support contract-owned assets? This is what the `as-contract` function is used for. The `as-contract` function executes the supplied closure as if the sender of the transaction was the current contract, rather than the user -- it does this by updating `tx-sender` to the current contract principal. We can use this to, for example, create a smart contract rocket-ship-line: This is what the `as-contract` function is used for. The `as-contract` function executes the supplied closure as if the sender of the transaction was the current contract, rather than the user -- it does this by updating `tx-sender` to the current contract principal. We can use this to, for example, create a smart contract rocket-ship-line: This is what the `as-contract` function is used for. The `as-contract` function executes the supplied closure as if the sender of the transaction was the current contract, rather than the user -- it does this by updating `tx-sender` to the current contract principal. We can use this to, for example, create a smart contract rocket-ship-line: - -```clarity -;; -;; rockets-ship-line.clar -;; - -(define-constant line-ceo 'SP19Y6GRV9X778VFS1V8WT2H502WFK33XZXADJWZ) - -(define-data-var employed-pilots (list 10 principal) (list)) - -;; This function will: -;; * check that it is called by the line-ceo -;; * check that the rocket is owned by the contract -;; * authorize each employed pilot to the ship -(define-public (add-managed-rocket (ship uint)) - (begin - ;; 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 - (asserts! (contract-call? .rockets-base is-my-ship ship) (err u2)) - ;; register all of our pilots on the ship - (add-pilots-to ship))))) - -;; add all the pilots to a ship using fold -- -;; the fold checks the return type of previous calls, -;; skipping subsequent contract-calls if one fails. -(define-private (add-pilot-via-fold (pilot principal) (prior-result (response uint uint))) - (let ((ship (try! prior-result))) - (try! (contract-call? .rockets-base authorize-pilot ship pilot)) - (ok ship))) -(define-private (add-pilots-to (ship uint)) - (fold add-pilot-via-fold (var-get employed-pilots) (ok ship))) (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 - (asserts! (contract-call? .rockets-base is-my-ship ship) (err u2)) - ;; register all of our pilots on the ship - (add-pilots-to ship))))) - -;; add all the pilots to a ship using fold -- -;; the fold checks the return type of previous calls, -;; skipping subsequent contract-calls if one fails. -(define-private (add-pilot-via-fold (pilot principal) (prior-result (response uint uint))) - (let ((ship (try! prior-result))) - (try! (contract-call? .rockets-base authorize-pilot ship pilot)) - (ok ship))) -(define-private (add-pilots-to (ship uint)) - (fold add-pilot-via-fold (var-get employed-pilots) (ok ship))) (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 - (asserts! (contract-call? .rockets-base is-my-ship ship) (err u2)) - ;; register all of our pilots on the ship - (add-pilots-to ship))))) - -;; add all the pilots to a ship using fold -- -;; the fold checks the return type of previous calls, -;; skipping subsequent contract-calls if one fails. -(define-private (add-pilot-via-fold (pilot principal) (prior-result (response uint uint))) - (let ((ship (try! prior-result))) - (try! (contract-call? .rockets-base authorize-pilot ship pilot)) - (ok ship))) -(define-private (add-pilots-to (ship uint)) - (fold add-pilot-via-fold (var-get employed-pilots) (ok ship))) -``` - -In order for the contract to add each pilot to a new ship, the contract must call `authorize-pilot`. However, the contract wants to perform this action on behalf of a ship the _contract_ owns, not the transaction sender. To do this, the contract uses `as-contract`. However, the contract wants to perform this action on behalf of a ship the _contract_ owns, not the transaction sender. To do this, the contract uses `as-contract`. However, the contract wants to perform this action on behalf of a ship the _contract_ owns, not the transaction sender. To do this, the contract uses `as-contract`. diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md b/i18n/zh/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md deleted file mode 100644 index a01e37bc04..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/write-smart-contracts/resources.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Resources -description: 'Resources' -sidebar_position: 8 ---- - -# External resources - - -[Clarity book](https://book.clarity-lang.org/) - -[Clarity Universe](https://stacks.org/clarity-universe) - -[Hiro Clarity tutorials](https://docs.hiro.so/tutorials) diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md b/i18n/zh/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md deleted file mode 100644 index c034ec20e4..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/write-smart-contracts/software.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Clarity development software -description: The following tools are useful when developing Clarity smart contracts -sidebar_position: 4 ---- - -## Language Server Protocol for Clarity (including Visual Studio Code extension) - -The Language Server Protocol (LSP) defines the protocol used between an editor or IDE and a language server that provides language features like auto complete, go to definition, find all references etc. - -This makes programming in Clarity easier and much more intuitive. - -![Clarity LSP Screenshot](https://raw.githubusercontent.com/hirosystems/clarity-lsp/21b64298ca117dc41358eb9dce4605cc4a448a4c/images/screenshot.png?raw=true) - - -Clarity LSP repository is available [here](https://github.com/hirosystems/clarity-lsp). The extension for Visual Studio Code can be downloaded directly from [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=HiroSystems.clarity-lsp), but can be and older version. For a more up to date version you can also download it from [open-vsx](https://open-vsx.org/extension/hirosystems/clarity-lsp). The extension for Visual Studio Code can be downloaded directly from [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=HiroSystems.clarity-lsp), but can be and older version. For a more up to date version you can also download it from [open-vsx](https://open-vsx.org/extension/hirosystems/clarity-lsp). - -## Clarity REPL - -A read—eval—print loop (REPL), also termed an interactive toplevel or language shell, is a simple, interactive computer programming environment that takes single user inputs (that is, single expressions), evaluates (executes) them, and returns the result to the user; a program written in a REPL environment is executed piecewise. - -![Clarity-repl](https://github.com/hirosystems/clarity-repl/blob/develop/docs/images/screenshot.png?raw=true) - -Instructions on how to install Clarity REPL can be found [here](https://github.com/hirosystems/clarity-repl). - -## Clarinet - -Clarinet is a Clarity runtime packaged as a command line tool, designed to facilitate smart contract understanding, development, testing and deployment. Clarinet is a Clarity runtime packaged as a command line tool, designed to facilitate smart contract understanding, development, testing and deployment. Clarinet consists of a Clarity REPL and a testing harness, which, when used together allow you to rapidly develop and test a Clarity smart contract, with the need to deploy the contract to a local devnet or testnet. - -![Clarinet](https://github.com/hirosystems/clarinet/blob/develop/docs/images/demo.gif?raw=true) - -Installation instructions, including build from source instructions can be found [here](https://github.com/hirosystems/clarinet). If you prefer you can directly download the latest compiled realease for Windows, Mac and Linux [here](https://github.com/hirosystems/clarinet/releases). If you prefer you can directly download the latest compiled realease for Windows, Mac and Linux [here](https://github.com/hirosystems/clarinet/releases). - -[Clarinet 101](https://www.youtube.com/playlist?list=PL5Ujm489LoJaAz9kUJm8lYUWdGJ2AnQTb) contains multiple Clarinet video tutorials - -### Getting started with Clarinet - -You can verify you have Clarinet installed by checking its version: - -```bash -$ clarinet --version -clarinet 0.70 -``` - -More detailed information on using Clarinet is available [here](https://book.clarity-lang.org/ch07-00-using-clarinet.html). However to get you started, the following commands are important to know. However to get you started, the following commands are important to know. - -Create a new project and enter its directory: - -```bash -clarinet new my-project && cd my-project -``` - -Create a new contract inside `my-project`: - -```bash -clarinet contract new mycoolcontract -``` - -Check the syntax of Clarity: - -```bash -clarity check -``` - -To test your contract: - -```bash -clarinet test -``` - -Enter Clarinet's console: - -```bash -clarinet console -``` diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md b/i18n/zh/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md deleted file mode 100644 index 028eed578f..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/write-smart-contracts/tokens.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Tokens -description: Learn about token support within Clarity -sidebar_position: 3 ---- - -## Introduction - -A fundamental use of blockchain technology is the representation, store, and transfer of value between users of a blockchain. A fundamental use of blockchain technology is the representation, store, and transfer of value between users of a blockchain. A fundamental use of blockchain technology is the representation, store, and transfer of value between users of a blockchain. Cryptocurrency is a very common use of blockchain technology, and remains one of the primary drivers of adoption of blockchain technology. Cryptocurrencies are represented by blockchain tokens: individual units of value within a given blockchain ecosystem. Blockchain tokens can extend beyond just digital currency, however, and recent developments throughout the cryptocurrency community have demonstrated potential for the use of blockchain to tokenize and represent not just money but other tangible assets. Cryptocurrencies are represented by blockchain tokens: individual units of value within a given blockchain ecosystem. Blockchain tokens can extend beyond just digital currency, however, and recent developments throughout the cryptocurrency community have demonstrated potential for the use of blockchain to tokenize and represent not just money but other tangible assets. Cryptocurrencies are represented by blockchain tokens: individual units of value within a given blockchain ecosystem. Blockchain tokens can extend beyond just digital currency, however, and recent developments throughout the cryptocurrency community have demonstrated potential for the use of blockchain to tokenize and represent not just money but other tangible assets. - -A blockchain token is a digital asset that can be verifiably owned by a user of a blockchain. Blockchain tokens are governed by a set of rules that are defined by either the blockchain itself (in the case of native tokens) or by a smart contract on a blockchain. Rules can vary depending on the nature and the use of the token. Blockchain tokens are governed by a set of rules that are defined by either the blockchain itself (in the case of native tokens) or by a smart contract on a blockchain. Rules can vary depending on the nature and the use of the token. Blockchain tokens are governed by a set of rules that are defined by either the blockchain itself (in the case of native tokens) or by a smart contract on a blockchain. Rules can vary depending on the nature and the use of the token. - -Tokens on a blockchain fall into two general categories, depending on their properties: [fungible][] or [non-fungible][]. The following sections discuss the properties of both types of tokens, and provide information about implementation of the two types of tokens on Stacks. The following sections discuss the properties of both types of tokens, and provide information about implementation of the two types of tokens on Stacks. The following sections discuss the properties of both types of tokens, and provide information about implementation of the two types of tokens on Stacks. - -## Fungible tokens - -A core property of any token on a blockchain is fungibility. A fungible token is a token that's mutually interchangable or capable of mutual substitution. In other words, one quantity or part of a fungible token can be replaced by an equal quantity or part of the same fungible token. Fungible tokens are often used to represent real-world fungible assets like currency. The STX token is an example of a fungible token. Other examples include stablecoins, tokens that represent voting rights in a DAO, or tokens that algorithmically track the price of stocks. A fungible token is a token that's mutually interchangable or capable of mutual substitution. In other words, one quantity or part of a fungible token can be replaced by an equal quantity or part of the same fungible token. Fungible tokens are often used to represent real-world fungible assets like currency. The STX token is an example of a fungible token. Other examples include stablecoins, tokens that represent voting rights in a DAO, or tokens that algorithmically track the price of stocks. - -Fungible tokens form one of the most important value propositions for blockchain technology, the ability to store value and exchange that value through both internal and external transactions. Because fungible tokens can be divided into smaller parts and recombined into the same value representation, they serve a great utility for transferring value between blockchain users. Fungible tokens form one of the most important value propositions for blockchain technology, the ability to store value and exchange that value through both internal and external transactions. Because fungible tokens can be divided into smaller parts and recombined into the same value representation, they serve a great utility for transferring value between blockchain users. Because fungible tokens can be divided into smaller parts and recombined into the same value representation, they serve a great utility for transferring value between blockchain users. - -The primary fungible token on the Stacks blockchain is the native token, STX. Because the Stacks blockchain allows for the creation of [smart contracts][], other fungible tokens can be created on the Stacks blockchain as well. [SIP-010][] specifies the standard for fungible tokens on the Stacks blockchain. This specification defines the functions and traits that a fungible token on Stacks _must_ have. By complying with this standard, fungible tokens on Stacks can be easily represented by wallets that support Stacks. Because the Stacks blockchain allows for the creation of \[smart contracts\]\[\], other fungible tokens can be created on the Stacks blockchain as well. The [SIP-010][] standard is an interface definition that allows Stacks applications and wallets to interact with fungible tokens in a standard way. Supporting the standard reduces complexity for token creators to get their tokens into the ecosystem. Under the [SIP-010][] standard, fungible tokens must have the following characteristics: This specification defines the functions and traits that a fungible token on Stacks _must_ have. By complying with this standard, fungible tokens on Stacks can be easily represented by wallets that support Stacks. - -### Understanding the fungible token standard - -The [SIP-009][] standard is an interface definition that the Stacks ecosystem aligned on. With support for this standard across wallets and tools, it becomes easy to interact with NFTs. Under the [SIP-009][] standard, NFT contract must have the following characteristics: Supporting the standard reduces complexity for token creators to get their tokens into the ecosystem. Under the [SIP-010][] standard, fungible tokens must have the following characteristics: - -- Ability to transfer a specified amount of the token to a recipient (`transfer`). The recipient is required to be a Stacks principal. The recipient is required to be a Stacks principal. The recipient is required to be a Stacks principal. -- Ability to obtain the human-readable name of the token (`get-name`). -- Ability to obtain a short name (ticker symbol) for the token (`get-symbol`). -- Ability to get the number of decimals in the token representation (`get-decimals`). This is used to construct a representation of the token that humans would be familiar dealing with. For example, the US dollar has 2 decimals, if the base unit is cents. This is used to construct a representation of the token that humans would be familiar dealing with. For example, the US dollar has 2 decimals, if the base unit is cents. This is used to construct a representation of the token that humans would be familiar dealing with. For example, the US dollar has 2 decimals, if the base unit is cents. -- Ability to get the balance of the token for a particular Stacks principal (`get-balance-of`). -- Ability to get the total supply of the token (`get-total-supply`). -- A URI to metadata associated with the token (`get-token-uri`). A URI to metadata associated with the token (`get-token-uri`). A URI to metadata associated with the token (`get-token-uri`). This can resolve to off-chain metadata about the token or contract, such as an image icon for the token or a description. - -## Non-fungible tokens (NFTs) - -Non-fungible tokens (NFTs) are a type of token that are not interchangeable. NFTs have unique traits (usually in the form of attached metadata) that restrict the abillity to replace them with identical tokens. An NFT is a token that is unique, such as a piece of art, or ownership rights to a real-world asset such as a house. NFTs have unique traits (usually in the form of attached metadata) that restrict the abillity to replace them with identical tokens. An NFT is a token that is unique, such as a piece of art, or ownership rights to a real-world asset such as a house. NFTs have unique traits (usually in the form of attached metadata) that restrict the abillity to replace them with identical tokens. An NFT is a token that is unique, such as a piece of art, or ownership rights to a real-world asset such as a house. - -NFTs alone don't have an inherent value, like a currency. The value of an NFT is derived from the assets that the NFT represents. The use of NFTs are myriad, including digital art, collectibles, domain names, and representation of ownership of content rights. NFTs can be used as digital certificates that track the authenticty of real world items, or digitize the ownership rights to property. The value of an NFT is derived from the assets that the NFT represents. The use of NFTs are myriad, including digital art, collectibles, domain names, and representation of ownership of content rights. NFTs can be used as digital certificates that track the authenticty of real world items, or digitize the ownership rights to property. The value of an NFT is derived from the assets that the NFT represents. The use of NFTs are myriad, including digital art, collectibles, domain names, and representation of ownership of content rights. NFTs can be used as digital certificates that track the authenticty of real world items, or digitize the ownership rights to property. - -As with fungible tokens, NFTs on the Stacks blockchain are created with smart contracts. As with fungible tokens, NFTs on the Stacks blockchain are created with smart contracts. [SIP-009][] specifies the standard for NFTs on the Stacks blockchain. This specification defines the functions and traits that an NFT _must_ have, but most NFTs have more functions or traits attached than those solely described by the specification. By complying with this standard, non-fungible tokens on Stacks can be easily represented by wallets that support Stacks. This specification defines the functions and traits that an NFT _must_ have, but most NFTs have more functions or traits attached than those solely described by the specification. By complying with this standard, non-fungible tokens on Stacks can be easily represented by wallets that support Stacks. - -### Understanding the non-fungible token standard - -The [SIP-009][] standard is an interface definition that the Stacks ecosystem aligned on. With support for this standard across wallets and tools, it becomes easy to interact with NFTs. Under the [SIP-009][] standard, NFT contract must have the following characteristics: - -- Ability to obtain the last token identifier (`get-last-token-id`). Ability to obtain the last token identifier (`get-last-token-id`). This id represents the upper limit of NFTs issued by the contract. Ability to obtain the last token identifier (`get-last-token-id`). This id represents the upper limit of NFTs issued by the contract. -- A URI to metadata associated with a specific token identifier. (`get-token-uri`). A URI to metadata associated with a specific token identifier. (`get-token-uri`). A URI to metadata associated with a specific token identifier. (`get-token-uri`). This URI could resolve to a JSON file with information about the creator, associated media files, descriptions, signatures, and more. -- Ability to verify the owner for a given token identifier (`get-owner`). The owner resolves to a [Stacks principal](/write-smart-contracts/principals). The owner resolves to a [Stacks principal](principals). The owner resolves to a [Stacks principal](principals). -- Ability to transfer an NFT to a recipient (`transfer`). The recipient is required to be a Stacks principal. The recipient is required to be a Stacks principal. The recipient is required to be a Stacks principal. - -## Further reading - -- [The Difference Between Fungible and Non-Fungible Tokens](https://101blockchains.com/fungible-vs-non-fungible-tokens/) -- [Explain It Like I Am 5: NFTs](https://messari.io/article/explain-it-like-i-am-5-nfts) - -[fungible]: #fungible-tokens -[non-fungible]: #non-fungible-tokens-nfts -[smart contracts]: /write-smart-contracts/overview -[SIP-010]: https://github.com/stacksgov/sips/blob/main/sips/sip-010/sip-010-fungible-token-standard.md -[SIP-010]: https://github.com/hstove/sips/blob/feat/sip-10-ft/sips/sip-010/sip-010-fungible-token-standard.md -[SIP-009]: https://github.com/stacksgov/sips/blob/main/sips/sip-009/sip-009-nft-standard.md diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md b/i18n/zh/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md deleted file mode 100644 index debefc8d65..0000000000 --- a/i18n/zh/docusaurus-plugin-content-docs/current/write-smart-contracts/values.md +++ /dev/null @@ -1,301 +0,0 @@ ---- -title: Clarity Values -description: Learn how to deal with Clarity Values in JavaScript -sidebar_position: 2 ---- - -## Introduction - -The Clarity language makes use of a strong static type system. The Clarity language makes use of a strong static 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/hirosystems/stacks.js/tree/master/packages/transactions) library makes this easy, as we will demonstrate below. The [@stacks/transactions](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library makes this easy, as we will demonstrate below. The [@stacks/transactions](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library makes this easy, as we will demonstrate below. - -## Clarity Types - -Please see the following page for information on [Clarity Types](../write-smart-contracts/clarity-language/language-types). - -## Constructing Clarity Values and accessing their data - -Clarity values can be constructed with functions provided by the [@stacks/transactions](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions) library. These functions simply output javascript objects that contain a value and a numerical representation of the Clarity type information. The Clarity types are encoded as follows: These functions simply output javascript objects that contain a value and a numerical representation of the Clarity type information. The Clarity types are encoded as follows: These functions simply output javascript objects that contain a value and a numerical representation of the Clarity type information. The Clarity types are encoded as follows: - -```typescript -export enum ClarityType { - Int = 0, - UInt = 1, - Buffer = 2, - BoolTrue = 3, - BoolFalse = 4, - PrincipalStandard = 5, - PrincipalContract = 6, - ResponseOk = 7, - ResponseErr = 8, - OptionalNone = 9, - OptionalSome = 10, - List = 11, - Tuple = 12, - StringASCII = 13, - StringUTF8 = 14, -} -``` - -`ClarityValue` objects can be serialized and included in transactions that interact with published Clarity contracts. - -Here are examples of how to construct each type of Clarity value, and how to access its data if it has any: - -### Booleans - -```typescript -const t = trueCV(); -// { type: ClarityType.BoolTrue } - -const f = falseCV(); -// { type: ClarityType.BoolFalse } -``` - -Boolean Clarity Values don't contain any underlying data. They are simply objects with `type` information. They are simply objects with `type` information. They are simply objects with `type` information. - -### Optional Values - -```typescript -const nothing: NoneCV = noneCV(); -// { type: ClarityType.OptionalNone } - -const something: SomeCV = someCV(trueCV()); -// { type: ClarityType.OptionalSome, value: { type: 4 } } -``` - -Optional Clarity Values can either be nothing (an empty type that has no data), or something (a wrapped value). - -If you are dealing with a function or contract function that returns an `OptionalCV`, you should always check what type it is before trying to access its value. - -```typescript -const maybeVal: OptionalCV = await callReadOnlyFunction(...); - -if (maybeVal.type === ClarityType.OptionalSome) { - console.log(maybeVal.value); -} else if (maybeVal.type === ClarityType.OptionalNone) { - // deal with `none` value -} -``` - -### Buffers - -```typescript -const buffer = Buffer.from('foo'); -const bufCV: BufferCV = bufferCV(buffer); -// { type: ClarityType.Buffer, buffer: } -``` - -### Integers - -Clarity supports both integers and unsigned integers. - -```typescript -const i: IntCV = intCV(-10); -// { type: ClarityType.Int, value: BN { ... } } - -const u: UIntCV = uintCV(10); -// { type: ClarityType.UInt, value: BN { ... } } -``` - -Clarity value ints store their underlying data as `BigNum` values from the [bn.js](https://github.com/indutny/bn.js/) library. - -In order to display/print Clarity (u)int values, use the `cvToString(val)` method. - -If you wish to perform arithmetic operations using Clarity (u)int values, you must use methods from the `BigNum` api on their underlying `BigNum` values, and the construct a new Clarity value out of the result. For example: For example: For example: - -```typescript -const x = intCV(1); -const y = intCV(2); - -x.value.add(y.value); -// 3 -``` - -### Strings - -```typescript -const ascii: StringAsciiCV = stringAsciiCV('hello world'); -// { type: ClarityType.StringASCII, data: 'hello world' } - -const utf8: StringUtf8CV = stringUtf8CV('hello 🌾'); -// { type: ClarityType.StringUTF8, data: 'hello 🌾' } -``` - -Clarity supports both ascii and utf8 strings. - -### Principals - -```typescript -const address = 'SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B'; -const contractName = 'contract-name'; - -const spCV = standardPrincipalCV(address); -// { -// type: ClarityType.PrincipalStandard -// address: { -// type: StacksMessageType.Address, -// version: AddressVersion.MainnetSingleSig, -// hash160: "SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B" -// } -// } - -const cpCV = contractPrincipalCV(address, contractName); -// { -// type: ClarityType.PrincipalContract, -// contractName: { -// type: StacksMessageType.LengthPrefixedString, -// content: 'contract-name', -// lengthPrefixBytes: 1, -// maxLengthBytes: 128, -// }, -// address: { -// type: StacksMessageType.Address, -// version: AddressVersion.MainnetSingleSig, -// hash160: "SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B" -// } -// } -``` - -Both kinds of Clarity principal values contain `type` information and an `address` object. Contract principals also contain a `contractName`. Contract principals also contain a `contractName`. Contract principals also contain a `contractName`. - -### Response Values - -```typescript -const errCV = responseErrorCV(trueCV()); -// { type: ResponseErr, value: { type: ClarityType.BoolTrue } } - -const okCV = responseOkCV(falseCV()); -// { type: ResponseOk, value: { type: ClarityType.BoolFalse } } -``` - -Response Clarity Values will either have the type `ClarityType.ResponseOk` or `ClarityType.ResponseErr`. They both contain a Clarity Value. Often this value will be an integer error code if the response is an `Error`. They both contain a Clarity Value. Often this value will be an integer error code if the response is an `Error`. They both contain a Clarity Value. Often this value will be an integer error code if the response is an `Error`. - -### Tuples - -```typescript -const tupCV = tupleCV({ - a: intCV(1), - b: trueCV(), - c: falseCV(), -}); -// { -// type: ClarityType.Tuple, -// data: { -// a: { type: ClarityType.Int, value: BN { ... } }, -// b: { type: ClarityType.BoolTrue }, -// c: { type: ClarityType.BoolFalse }, -// } -// } - -console.log(tupCV.data['b']); -// { type: ClarityType.BoolTrue } -``` - -Tuples in Clarity are typed and contain named fields. Tuples in Clarity are typed and contain named fields. The tuple above, for example, contains three fields with the names **a**, **b** and **c**, and the types of their values are `Int`, `Boolean` and `Boolean`, respectively. Tuples in Clarity are typed and contain named fields. The tuple above, for example, contains three fields with the names **a**, **b** and **c**, and the types of their values are `Int`, `Boolean` and `Boolean`, respectively. - -Clarity tuples are represented in JavaScript as objects and a tuple's data can be accessed by its `data` field, where the underlying JS object is stored. - -### Lists - -```typescript -const l = listCV([trueCV(), falseCV()]); -// { type: ClarityType.List, list: [{ type: ClarityType.BoolTrue }] } - -console.log(l.list[0]); -// { type: ClarityType.BoolTrue } -``` - -Lists, in Clarity, are homogeneous, meaning they can only contain elements of a singular (Clarity) type. Make sure to avoid constructing lists that have elements of multiple types. Make sure to avoid constructing lists that have elements of multiple types. Make sure to avoid constructing lists that have elements of multiple types. - -A Clarity lists underlying data can be accessed via its `list` field. - -## Using Clarity Values - -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](../understand-stacks/transactions#construction). - -## Utilizing Clarity Values from Transaction Responses - -`Read-only` Clarity functions can return Clarity values as a response. `Read-only` Clarity functions can return Clarity values as a response. `Read-only` Clarity functions can return Clarity values as a response. These `read-only` functions can be accessed easily in JavaScript via the [`callReadOnlyFunction()`](https://github.com/hirosystems/stacks.js/tree/master/packages/transactions#calling-read-only-contract-function) function included in `@stacks/transactions`, which returns a `ClarityValue`. - -As mentioned above, `ClarityValues` are simply javascript objects containing a value and its associated Clarity type information. These object types are defined [here](https://github.com/hirosystems/stacks.js/tree/1f2b5fd8bdf1c2b5866e8171163594d7708a8c7a/packages/transactions/src/clarity/types). As mentioned above, `ClarityValues` are simply javascript objects containing a value and its associated Clarity type information. These object types are defined [here](https://github.com/hirosystems/stacks.js/tree/1f2b5fd8bdf1c2b5866e8171163594d7708a8c7a/packages/transactions/src/clarity/types). These object types are defined [here](https://github.com/hirosystems/stacks.js/tree/1f2b5fd8bdf1c2b5866e8171163594d7708a8c7a/packages/transactions/src/clarity/types). - -When you are calling a `read-only` contract function, you will always know what type the function will return, since functions in Clarity are strongly typed. - -It is common for Clarity functions to return values wrapped in a `Response`, in order to indicate if there was success or an error. - -Since every `ClarityValue` has a `type` field, the type of the result of a `read-only` function call can be checked and acted upon like so: - -```typescript -const contractAddress = 'ST3KC0MTNW34S1ZXD36JYKFD3JJMWA01M55DSJ4JE'; -const contractName = 'kv-store'; -const functionName = 'get-value'; -const buffer = bufferCVFromString('foo'); -const network = new StacksTestnet(); // for mainnet, use `StacksMainnet()` -const senderAddress = 'ST2F4BK4GZH6YFBNHYDDGN4T1RKBA7DA1BJZPJEJJ'; - -const options = { - contractAddress, - contractName, - functionName, - functionArgs: [buffer], - network, - senderAddress, -}; - -// make a read-only call to a contract function that -// returns a Response -const result: ResponseCV = await callReadOnlyFunction(options); - -if (result.type === ClarityType.ResponseOk) { - console.log(cvToString(result.value)); -} else if (result.type === ClarityType.ResponseErr) { - throw new Error(`kv-store contract error: ${result.value.data}`); -} -``` - -### ClarityValues to/from Hex - -If you receive a response from a transaction in the form of a `hex` string, you can deserialize it into a Clarity value like so: - -```javascript -import { hexToCV } from '@stacks/transactions'; - -let cv = hexToCV('hex_string'); -``` - -Similarly, you can convert a Clarity value to `hex` string like so: - -```javascript -import { cvToHex, trueCV } from '@stacks/transactions'; - -let trueHex = cvToHex(trueCV()); -``` - -## Debugging Clarity Values - -Sometimes you might receive a Clarity value that you were not expecting. Sometimes you might receive a Clarity value that you were not expecting. Sometimes you might receive a Clarity value that you were not expecting. Logging the value to your console won't always prove to be useful, unless you have memorized the Clarity value type enum values. - -In order to figure out what kind of value you are dealing with, you can use the `cvToString()` function to convert the Clarity value to a more easily readable string. - -For example, calling `cvToString()` on a large `tuple` might yield something like: - -``` -(tuple - (a -1) - (b u1) - (c 0x74657374) - (d true) - (e (some true)) - (f none) - (g SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B) - (h SP2JXKMSH007NPYAQHKJPQMAQYAD90NQGTVJVQ02B.test) - (i (ok true)) - (j (err false)) - (k (list true false)) - (l (tuple (a true) (b false))) - (m "hello world") - (n u"hello \u{1234}"))` -``` diff --git a/src/_data/boot-contracts-reference.json b/src/_data/boot-contracts-reference.json deleted file mode 100644 index 26cfa7e035..0000000000 --- a/src/_data/boot-contracts-reference.json +++ /dev/null @@ -1,551 +0,0 @@ -{ - "bns": { - "public_functions": [ - { - "name": "name-import", - "input_type": "(buff 20), (buff 48), principal, (buff 20)", - "output_type": "(response bool int)", - "signature": "(name-import namespace name beneficiary zonefile-hash)", - "description": "Imports name to a revealed namespace. Each imported name is given both an owner and some off-chain state." - }, - { - "name": "name-preorder", - "input_type": "(buff 20), uint", - "output_type": "(response uint int)", - "signature": "(name-preorder hashed-salted-fqn stx-to-burn)", - "description": "Preorders a name by telling all BNS nodes the salted hash of the BNS name. It pays the registration fee to the namespace owner's designated address." - }, - { - "name": "name-register", - "input_type": "(buff 20), (buff 48), (buff 20), (buff 20)", - "output_type": "(response bool int)", - "signature": "(name-register namespace name salt zonefile-hash)", - "description": "Reveals the salt and the name to all BNS nodes, and assigns the name an initial public key hash and zone file hash." - }, - { - "name": "name-renewal", - "input_type": "(buff 20), (buff 48), uint, (optional principal), (optional (buff 20))", - "output_type": "(response bool int)", - "signature": "(name-renewal namespace name stx-to-burn new-owner zonefile-hash)", - "description": "Depending in the namespace rules, a name can expire. For example, names in the .id namespace expire after 2 years. You need to send a name renewal every so often to keep your name.\n\nYou will pay the registration cost of your name to the namespace's designated burn address when you renew it.\nWhen a name expires, it enters a \"grace period\". The period is set to 5000 blocks (a month) but can be configured for each namespace. \n\nIt will stop resolving in the grace period, and all of the above operations will cease to be honored by the BNS consensus rules.\nYou may, however, send a NAME_RENEWAL during this grace period to preserve your name. After the grace period, everybody can register that name again.\nIf your name is in a namespace where names do not expire, then you never need to use this transaction." - }, - { - "name": "name-revoke", - "input_type": "(buff 20), (buff 48)", - "output_type": "(response bool int)", - "signature": "(name-revoke namespace name)", - "description": "Makes a name unresolvable. The BNS consensus rules stipulate that once a name is revoked, no one can change its public key hash or its zone file hash. The name's zone file hash is set to null to prevent it from resolving. You should only do this if your private key is compromised, or if you want to render your name unusable for whatever reason." - }, - { - "name": "name-transfer", - "input_type": "(buff 20), (buff 48), principal, (optional (buff 20))", - "output_type": "(response bool int)", - "signature": "(name-transfer namespace name new-owner zonefile-hash)", - "description": "Changes the name's public key hash. You would send a name transfer transaction if you wanted to:\n* Change your private key\n* Send the name to someone else or\n* Update your zone file\n\nWhen transferring a name, you have the option to also clear the name's zone file hash (i.e. set it to null). This is useful for when you send the name to someone else, so the recipient's name does not resolve to your zone file." - }, - { - "name": "name-update", - "input_type": "(buff 20), (buff 48), (buff 20)", - "output_type": "(response bool int)", - "signature": "(name-update namespace name zonefile-hash)", - "description": "Changes the name's zone file hash. You would send a name update transaction if you wanted to change the name's zone file contents. For example, you would do this if you want to deploy your own Gaia hub and want other people to read from it." - }, - { - "name": "namespace-preorder", - "input_type": "(buff 20), uint", - "output_type": "(response uint int)", - "signature": "(namespace-preorder hashed-salted-namespace stx-to-burn)", - "description": "Registers the salted hash of the namespace with BNS nodes, and burns the requisite amount of cryptocurrency. Additionally, this step proves to the BNS nodes that user has honored the BNS consensus rules by including a recent consensus hash in the transaction. Returns pre-order's expiration date (in blocks)." - }, - { - "name": "namespace-ready", - "input_type": "(buff 20)", - "output_type": "(response bool int)", - "signature": "(namespace-ready namespace)", - "description": "Launches the namespace and makes it available to the public. Once a namespace is launched, anyone can register a name in it if they pay the appropriate amount of cryptocurrency." - }, - { - "name": "namespace-reveal", - "input_type": "(buff 20), (buff 20), uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, uint, principal", - "output_type": "(response bool int)", - "signature": "(namespace-reveal namespace namespace-salt p-func-base p-func-coeff p-func-b1 p-func-b2 p-func-b3 p-func-b4 p-func-b5 p-func-b6 p-func-b7 p-func-b8 p-func-b9 p-func-b10 p-func-b11 p-func-b12 p-func-b13 p-func-b14 p-func-b15 p-func-b16 p-func-non-alpha-discount p-func-no-vowel-discount lifetime namespace-import)", - "description": "Reveals the salt and the namespace ID (after a namespace preorder). It reveals how long names last in this namespace before they expire or must be renewed, and it sets a price function for the namespace that determines how cheap or expensive names its will be.All of the parameters prefixed by `p` make up the `price function`. These parameters govern the pricing and lifetime of names in the namespace.\n\nThe rules for a namespace are as follows:\n* a name can fall into one of 16 buckets, measured by length. Bucket 16 incorporates all names at least 16 characters long.\n* the pricing structure applies a multiplicative penalty for having numeric characters, or punctuation characters.\n* the price of a name in a bucket is `((coeff) * (base) ^ (bucket exponent)) / ((numeric discount multiplier) * (punctuation discount multiplier))`\n\nExample:\n\n* base = 10\n* coeff = 2\n* nonalpha discount: 10\n* no-vowel discount: 10\n* buckets 1, 2: 9\n* buckets 3, 4, 5, 6: 8\n* buckets 7, 8, 9, 10, 11, 12, 13, 14: 7\n* buckets 15, 16+:" - } - ], - "read_only_functions": [ - { - "name": "can-name-be-registered", - "input_type": "(buff 20), (buff 48)", - "output_type": "(response bool int)", - "signature": "(can-name-be-registered namespace name)", - "description": "Returns true if the provided name can be registered." - }, - { - "name": "can-namespace-be-registered", - "input_type": "(buff 20)", - "output_type": "(response bool UnknownType)", - "signature": "(can-namespace-be-registered namespace)", - "description": "Returns true if the provided namespace is available." - }, - { - "name": "can-receive-name", - "input_type": "principal", - "output_type": "(response bool int)", - "signature": "(can-receive-name owner)", - "description": "Returns true if the provided name can be received. That is, if it is not curretly owned, a previous lease is expired, and the name wasn't revoked." - }, - { - "name": "get-name-price", - "input_type": "(buff 20), (buff 48)", - "output_type": "(response uint int)", - "signature": "(get-name-price namespace name)", - "description": "Gets the price for a name." - }, - { - "name": "get-namespace-price", - "input_type": "(buff 20)", - "output_type": "(response uint int)", - "signature": "(get-namespace-price namespace)", - "description": "Gets the price for a namespace." - }, - { - "name": "get-namespace-properties", - "input_type": "(buff 20)", - "output_type": "(response (tuple (namespace (buff 20)) (properties (tuple (can-update-price-function bool) (launched-at (optional uint)) (lifetime uint) (namespace-import principal) (price-function (tuple (base uint) (buckets (list 16 uint)) (coeff uint) (no-vowel-discount uint) (nonalpha-discount uint))) (revealed-at uint)))) int)", - "signature": "(get-namespace-properties namespace)", - "description": "Get namespace properties." - }, - { - "name": "is-name-lease-expired", - "input_type": "(buff 20), (buff 48)", - "output_type": "(response bool int)", - "signature": "(is-name-lease-expired namespace name)", - "description": "Return true if the provided name lease is expired." - }, - { - "name": "name-resolve", - "input_type": "(buff 20), (buff 48)", - "output_type": "(response (tuple (lease-ending-at (optional uint)) (lease-started-at uint) (owner principal) (zonefile-hash (buff 20))) int)", - "signature": "(name-resolve namespace name)", - "description": "Get name registration details." - }, - { - "name": "resolve-principal", - "input_type": "principal", - "output_type": "(response (tuple (name (buff 48)) (namespace (buff 20))) (tuple (code int) (name (optional (tuple (name (buff 48)) (namespace (buff 20)))))))", - "signature": "(resolve-principal owner)", - "description": "Returns the registered name that a principal owns if there is one. A principal can only own one name at a time." - } - ], - "error_codes": [ - { - "name": "ERR_INSUFFICIENT_FUNDS", - "type": "int", - "value": "4001" - }, - { - "name": "ERR_NAMESPACE_ALREADY_EXISTS", - "type": "int", - "value": "1006" - }, - { - "name": "ERR_NAMESPACE_ALREADY_LAUNCHED", - "type": "int", - "value": "1014" - }, - { - "name": "ERR_NAMESPACE_BLANK", - "type": "int", - "value": "1013" - }, - { - "name": "ERR_NAMESPACE_CHARSET_INVALID", - "type": "int", - "value": "1016" - }, - { - "name": "ERR_NAMESPACE_HASH_MALFORMED", - "type": "int", - "value": "1015" - }, - { - "name": "ERR_NAMESPACE_NOT_FOUND", - "type": "int", - "value": "1005" - }, - { - "name": "ERR_NAMESPACE_NOT_LAUNCHED", - "type": "int", - "value": "1007" - }, - { - "name": "ERR_NAMESPACE_OPERATION_UNAUTHORIZED", - "type": "int", - "value": "1011" - }, - { - "name": "ERR_NAMESPACE_PREORDER_ALREADY_EXISTS", - "type": "int", - "value": "1003" - }, - { - "name": "ERR_NAMESPACE_PREORDER_CLAIMABILITY_EXPIRED", - "type": "int", - "value": "1009" - }, - { - "name": "ERR_NAMESPACE_PREORDER_EXPIRED", - "type": "int", - "value": "1002" - }, - { - "name": "ERR_NAMESPACE_PREORDER_LAUNCHABILITY_EXPIRED", - "type": "int", - "value": "1010" - }, - { - "name": "ERR_NAMESPACE_PREORDER_NOT_FOUND", - "type": "int", - "value": "1001" - }, - { - "name": "ERR_NAMESPACE_PRICE_FUNCTION_INVALID", - "type": "int", - "value": "1008" - }, - { - "name": "ERR_NAMESPACE_STX_BURNT_INSUFFICIENT", - "type": "int", - "value": "1012" - }, - { - "name": "ERR_NAMESPACE_UNAVAILABLE", - "type": "int", - "value": "1004" - }, - { - "name": "ERR_NAME_ALREADY_CLAIMED", - "type": "int", - "value": "2011" - }, - { - "name": "ERR_NAME_BLANK", - "type": "int", - "value": "2010" - }, - { - "name": "ERR_NAME_CHARSET_INVALID", - "type": "int", - "value": "2022" - }, - { - "name": "ERR_NAME_CLAIMABILITY_EXPIRED", - "type": "int", - "value": "2012" - }, - { - "name": "ERR_NAME_COULD_NOT_BE_MINTED", - "type": "int", - "value": "2020" - }, - { - "name": "ERR_NAME_COULD_NOT_BE_TRANSFERED", - "type": "int", - "value": "2021" - }, - { - "name": "ERR_NAME_EXPIRED", - "type": "int", - "value": "2008" - }, - { - "name": "ERR_NAME_GRACE_PERIOD", - "type": "int", - "value": "2009" - }, - { - "name": "ERR_NAME_HASH_MALFORMED", - "type": "int", - "value": "2017" - }, - { - "name": "ERR_NAME_NOT_FOUND", - "type": "int", - "value": "2013" - }, - { - "name": "ERR_NAME_NOT_RESOLVABLE", - "type": "int", - "value": "2019" - }, - { - "name": "ERR_NAME_OPERATION_UNAUTHORIZED", - "type": "int", - "value": "2006" - }, - { - "name": "ERR_NAME_PREORDERED_BEFORE_NAMESPACE_LAUNCH", - "type": "int", - "value": "2018" - }, - { - "name": "ERR_NAME_PREORDER_ALREADY_EXISTS", - "type": "int", - "value": "2016" - }, - { - "name": "ERR_NAME_PREORDER_EXPIRED", - "type": "int", - "value": "2002" - }, - { - "name": "ERR_NAME_PREORDER_FUNDS_INSUFFICIENT", - "type": "int", - "value": "2003" - }, - { - "name": "ERR_NAME_PREORDER_NOT_FOUND", - "type": "int", - "value": "2001" - }, - { - "name": "ERR_NAME_REVOKED", - "type": "int", - "value": "2014" - }, - { - "name": "ERR_NAME_STX_BURNT_INSUFFICIENT", - "type": "int", - "value": "2007" - }, - { - "name": "ERR_NAME_TRANSFER_FAILED", - "type": "int", - "value": "2015" - }, - { - "name": "ERR_NAME_UNAVAILABLE", - "type": "int", - "value": "2004" - }, - { - "name": "ERR_PANIC", - "type": "int", - "value": "0" - }, - { - "name": "ERR_PRINCIPAL_ALREADY_ASSOCIATED", - "type": "int", - "value": "3001" - } - ] - }, - "pox": { - "public_functions": [ - { - "name": "allow-contract-caller", - "input_type": "principal, (optional uint)", - "output_type": "(response bool int)", - "signature": "(allow-contract-caller caller until-burn-ht)", - "description": "Give a contract-caller authorization to call stacking methods. Normally, stacking methods may\nonly be invoked by _direct_ transactions (i.e., the `tx-sender` issues a direct `contract-call` to the stacking methods).\nBy issuing an allowance, the tx-sender may call through the allowed contract." - }, - { - "name": "delegate-stack-stx", - "input_type": "principal, uint, (tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint", - "output_type": "(response (tuple (lock-amount uint) (stacker principal) (unlock-burn-height uint)) int)", - "signature": "(delegate-stack-stx stacker amount-ustx pox-addr start-burn-ht lock-period)", - "description": "As a delegate, stack the given principal's STX using `partial-stacked-by-cycle`.\nOnce the delegate has stacked > minimum, the delegate should call `stack-aggregation-commit`." - }, - { - "name": "delegate-stx", - "input_type": "uint, principal, (optional uint), (optional (tuple (hashbytes (buff 20)) (version (buff 1))))", - "output_type": "(response bool int)", - "signature": "(delegate-stx amount-ustx delegate-to until-burn-ht pox-addr)", - "description": "Delegate to `delegate-to` the ability to stack from a given address.\nThis method _does not_ lock the funds, rather, it allows the delegate to issue the stacking lock.\n\nThe caller specifies:\n * amount-ustx: the total amount of ustx the delegate may be allowed to lock\n * until-burn-ht: an optional burn height at which this delegation expiration\n * pox-addr: an optional p2pkh or p2sh address to which any rewards *must* be sent" - }, - { - "name": "disallow-contract-caller", - "input_type": "principal", - "output_type": "(response bool int)", - "signature": "(disallow-contract-caller caller)", - "description": "Revokes authorization from a contract to invoke stacking methods through contract-calls" - }, - { - "name": "reject-pox", - "input_type": "", - "output_type": "(response bool int)", - "signature": "(reject-pox)", - "description": "Reject Stacking for this reward cycle.\n`tx-sender` votes all its uSTX for rejection.\nNote that unlike Stacking, rejecting PoX does not lock the tx-sender's tokens: PoX rejection acts like a coin vote." - }, - { - "name": "revoke-delegate-stx", - "input_type": "", - "output_type": "(response bool int)", - "signature": "(revoke-delegate-stx)", - "description": "Revoke a Stacking delegate relationship. A particular Stacker may only have one delegate,\nso this method does not take any parameters, and just revokes the Stacker's current delegate (if one exists)." - }, - { - "name": "stack-aggregation-commit", - "input_type": "(tuple (hashbytes (buff 20)) (version (buff 1))), uint", - "output_type": "(response bool int)", - "signature": "(stack-aggregation-commit pox-addr reward-cycle)", - "description": "Commit partially stacked STX.\n\nThis allows a stacker/delegate to lock fewer STX than the minimal threshold in multiple transactions,\nso long as:\n 1. The pox-addr is the same.\n 2. This \"commit\" transaction is called _before_ the PoX anchor block.\nThis ensures that each entry in the reward set returned to the stacks-node is greater than the threshold,\n but does not require it be all locked up within a single transaction" - }, - { - "name": "stack-stx", - "input_type": "uint, (tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint", - "output_type": "(response (tuple (lock-amount uint) (stacker principal) (unlock-burn-height uint)) int)", - "signature": "(stack-stx amount-ustx pox-addr start-burn-ht lock-period)", - "description": "Lock up some uSTX for stacking! Note that the given amount here is in micro-STX (uSTX).\nThe STX will be locked for the given number of reward cycles (lock-period).\nThis is the self-service interface. tx-sender will be the Stacker.\n\n* The given stacker cannot currently be stacking.\n* You will need the minimum uSTX threshold. This isn't determined until the reward cycle begins, but this\n method still requires stacking over the _absolute minimum_ amount, which can be obtained by calling `get-stacking-minimum`.\n* The pox-addr argument must represent a valid reward address. Right now, this must be a Bitcoin\np2pkh or p2sh address. It cannot be a native Segwit address, but it may be a p2wpkh-p2sh or p2wsh-p2sh address.\n\nThe tokens will unlock and be returned to the Stacker (tx-sender) automatically." - } - ], - "read_only_functions": [ - { - "name": "can-stack-stx", - "input_type": "(tuple (hashbytes (buff 20)) (version (buff 1))), uint, uint, uint", - "output_type": "(response bool int)", - "signature": "(can-stack-stx pox-addr amount-ustx first-reward-cycle num-cycles)", - "description": "Evaluate if a participant can stack an amount of STX for a given period." - }, - { - "name": "get-pox-info", - "input_type": "", - "output_type": "(response (tuple (current-rejection-votes uint) (first-burnchain-block-height uint) (min-amount-ustx uint) (prepare-cycle-length uint) (rejection-fraction uint) (reward-cycle-id uint) (reward-cycle-length uint) (total-liquid-supply-ustx uint)) UnknownType)", - "signature": "(get-pox-info)", - "description": "Returns information about PoX status." - }, - { - "name": "get-pox-rejection", - "input_type": "principal, uint", - "output_type": "(optional (tuple (amount uint)))", - "signature": "(get-pox-rejection stacker reward-cycle)", - "description": "Returns the amount of uSTX that a given principal used to reject a PoX cycle." - }, - { - "name": "get-stacker-info", - "input_type": "principal", - "output_type": "(optional (tuple (amount-ustx uint) (first-reward-cycle uint) (lock-period uint) (pox-addr (tuple (hashbytes (buff 20)) (version (buff 1))))))", - "signature": "(get-stacker-info stacker)", - "description": "Returns the _current_ stacking information for `stacker. If the information\nis expired, or if there's never been such a stacker, then returns none." - }, - { - "name": "get-stacking-minimum", - "input_type": "", - "output_type": "uint", - "signature": "(get-stacking-minimum)", - "description": "Returns the absolute minimum amount that could be validly Stacked (the threshold to Stack in\na given reward cycle may be higher than this" - }, - { - "name": "get-total-ustx-stacked", - "input_type": "uint", - "output_type": "uint", - "signature": "(get-total-ustx-stacked reward-cycle)", - "description": "Returns the amount of currently participating uSTX in the given cycle." - }, - { - "name": "is-pox-active", - "input_type": "uint", - "output_type": "bool", - "signature": "(is-pox-active reward-cycle)", - "description": "Returns whether or not PoX has been rejected at a given PoX cycle." - } - ], - "error_codes": [ - { - "name": "ERR_DELEGATION_EXPIRES_DURING_LOCK", - "type": "int", - "value": "21" - }, - { - "name": "ERR_DELEGATION_POX_ADDR_REQUIRED", - "type": "int", - "value": "23" - }, - { - "name": "ERR_DELEGATION_TOO_MUCH_LOCKED", - "type": "int", - "value": "22" - }, - { - "name": "ERR_INVALID_START_BURN_HEIGHT", - "type": "int", - "value": "24" - }, - { - "name": "ERR_NOT_ALLOWED", - "type": "int", - "value": "19" - }, - { - "name": "ERR_STACKING_ALREADY_DELEGATED", - "type": "int", - "value": "20" - }, - { - "name": "ERR_STACKING_ALREADY_REJECTED", - "type": "int", - "value": "17" - }, - { - "name": "ERR_STACKING_ALREADY_STACKED", - "type": "int", - "value": "3" - }, - { - "name": "ERR_STACKING_EXPIRED", - "type": "int", - "value": "5" - }, - { - "name": "ERR_STACKING_INSUFFICIENT_FUNDS", - "type": "int", - "value": "1" - }, - { - "name": "ERR_STACKING_INVALID_AMOUNT", - "type": "int", - "value": "18" - }, - { - "name": "ERR_STACKING_INVALID_LOCK_PERIOD", - "type": "int", - "value": "2" - }, - { - "name": "ERR_STACKING_INVALID_POX_ADDRESS", - "type": "int", - "value": "13" - }, - { - "name": "ERR_STACKING_NO_SUCH_PRINCIPAL", - "type": "int", - "value": "4" - }, - { - "name": "ERR_STACKING_PERMISSION_DENIED", - "type": "int", - "value": "9" - }, - { - "name": "ERR_STACKING_POX_ADDRESS_IN_USE", - "type": "int", - "value": "12" - }, - { - "name": "ERR_STACKING_STX_LOCKED", - "type": "int", - "value": "6" - }, - { - "name": "ERR_STACKING_THRESHOLD_NOT_MET", - "type": "int", - "value": "11" - }, - { - "name": "ERR_STACKING_UNREACHABLE", - "type": "int", - "value": "255" - } - ] - } -} diff --git a/src/_data/clarity-reference.json b/src/_data/clarity-reference.json deleted file mode 100644 index cf34a63804..0000000000 --- a/src/_data/clarity-reference.json +++ /dev/null @@ -1,1292 +0,0 @@ -{ - "functions": [ - { - "name": "* (multiply)", - "snippet": "* ${1:expr-1} ${2:expr-2}", - "input_type": "int, ... | uint, ...", - "output_type": "int | uint", - "signature": "(* i1 i2...)", - "description": "Multiplies a variable number of integer inputs and returns the result. In the event of an _overflow_, throws a runtime error.", - "example": "(* 2 3) ;; Returns 6\n(* 5 2) ;; Returns 10\n(* 2 2 2) ;; Returns 8\n", - "version": "Clarity1" - }, - { - "name": "+ (add)", - "snippet": "+ ${1:expr-1} ${2:expr-2}", - "input_type": "int, ... | uint, ...", - "output_type": "int | uint", - "signature": "(+ i1 i2...)", - "description": "Adds a variable number of integer inputs and returns the result. In the event of an _overflow_, throws a runtime error.", - "example": "(+ 1 2 3) ;; Returns 6", - "version": "Clarity1" - }, - { - "name": "- (subtract)", - "snippet": "- ${1:expr-1} ${2:expr-2}", - "input_type": "int, ... | uint, ...", - "output_type": "int | uint", - "signature": "(- i1 i2...)", - "description": "Subtracts a variable number of integer inputs and returns the result. In the event of an _underflow_, throws a runtime error.", - "example": "(- 2 1 1) ;; Returns 0\n(- 0 3) ;; Returns -3\n", - "version": "Clarity1" - }, - { - "name": "/ (divide)", - "snippet": "/ ${1:expr-1} ${2:expr-2}", - "input_type": "int, ... | uint, ...", - "output_type": "int | uint", - "signature": "(/ i1 i2...)", - "description": "Integer divides a variable number of integer inputs and returns the result. In the event of division by zero, throws a runtime error.", - "example": "(/ 2 3) ;; Returns 0\n(/ 5 2) ;; Returns 2\n(/ 4 2 2) ;; Returns 1\n", - "version": "Clarity1" - }, - { - "name": "< (less than)", - "snippet": "< ${1:expr-1} ${2:expr-2}", - "input_type": "int, int | uint, uint | string-ascii, string-ascii | string-utf8, string-utf8 | buff, buff", - "output_type": "bool", - "signature": "(< i1 i2)", - "description": "Compares two integers, returning `true` if `i1` is less than `i2` and `false` otherwise.\ni1 and i2 must be of the same type. Starting with Stacks 1.0, the `<`-comparable types are `int` and `uint`. Starting with Stacks 2.1,\nthe `<`-comparable types are expanded to include `string-ascii`, `string-utf8` and `buff`.", - "example": "(< 1 2) ;; Returns true\n(< 5 2) ;; Returns false\n(< \"aaa\" \"baa\") ;; Returns true\n(< \"aa\" \"aaa\") ;; Returns true\n(< 0x01 0x02) ;; Returns true\n(< 5 u2) ;; Throws type error\n", - "version": "Clarity1" - }, - { - "name": "<= (less than or equal)", - "snippet": "<= ${1:expr-1} ${2:expr-2}", - "input_type": "int, int | uint, uint | string-ascii, string-ascii | string-utf8, string-utf8 | buff, buff", - "output_type": "bool", - "signature": "(<= i1 i2)", - "description": "Compares two integers, returning true if `i1` is less than or equal to `i2` and `false` otherwise.\ni1 and i2 must be of the same type. Starting with Stacks 1.0, the `<=`-comparable types are `int` and `uint`. Starting with Stacks 2.1,\nthe `<=`-comparable types are expanded to include `string-ascii`, `string-utf8` and `buff`.", - "example": "(<= 1 1) ;; Returns true\n(<= 5 2) ;; Returns false\n(<= \"aaa\" \"baa\") ;; Returns true\n(<= \"aa\" \"aaa\") ;; Returns true\n(<= 0x01 0x02) ;; Returns true\n(<= 5 u2) ;; Throws type error\n", - "version": "Clarity1" - }, - { - "name": "> (greater than)", - "snippet": "> ${1:expr-1} ${2:expr-2}", - "input_type": "int, int | uint, uint | string-ascii, string-ascii | string-utf8, string-utf8 | buff, buff", - "output_type": "bool", - "signature": "(> i1 i2)", - "description": "Compares two integers, returning `true` if `i1` is greater than `i2` and false otherwise.\ni1 and i2 must be of the same type. Starting with Stacks 1.0, the `>`-comparable types are `int` and `uint`. Starting with Stacks 2.1,\nthe `>`-comparable types are expanded to include `string-ascii`, `string-utf8` and `buff`.", - "example": "(> 1 2) ;; Returns false\n(> 5 2) ;; Returns true\n(> \"baa\" \"aaa\") ;; Returns true\n(> \"aaa\" \"aa\") ;; Returns true\n(> 0x02 0x01) ;; Returns true\n(> 5 u2) ;; Throws type error\n", - "version": "Clarity1" - }, - { - "name": ">= (greater than or equal)", - "snippet": ">= ${1:expr-1} ${2:expr-2}", - "input_type": "int, int | uint, uint | string-ascii, string-ascii | string-utf8, string-utf8 | buff, buff", - "output_type": "bool", - "signature": "(>= i1 i2)", - "description": "Compares two integers, returning `true` if `i1` is greater than or equal to `i2` and `false` otherwise.\ni1 and i2 must be of the same type. Starting with Stacks 1.0, the `>=`-comparable types are `int` and `uint`. Starting with Stacks 2.1,\nthe `>=`-comparable types are expanded to include `string-ascii`, `string-utf8` and `buff`.\n ", - "example": "(>= 1 1) ;; Returns true\n(>= 5 2) ;; Returns true\n(>= \"baa\" \"aaa\") ;; Returns true\n(>= \"aaa\" \"aa\") ;; Returns true\n(>= 0x02 0x01) ;; Returns true\n(>= 5 u2) ;; Throws type error\n", - "version": "Clarity1" - }, - { - "name": "and", - "snippet": "and ${1:expr-1} ${2:expr-2}", - "input_type": "bool, ...", - "output_type": "bool", - "signature": "(and b1 b2 ...)", - "description": "Returns `true` if all boolean inputs are `true`. Importantly, the supplied arguments are \nevaluated in-order and lazily. Lazy evaluation means that if one of the arguments returns `false`, the function \nshort-circuits, and no subsequent arguments are evaluated.\n", - "example": "(and true false) ;; Returns false\n(and (is-eq (+ 1 2) 1) (is-eq 4 4)) ;; Returns false\n(and (is-eq (+ 1 2) 3) (is-eq 4 4)) ;; Returns true\n", - "version": "Clarity1" - }, - { - "name": "append", - "snippet": "append ${1:list} ${2:element}", - "input_type": "list A, A", - "output_type": "list", - "signature": "(append (list 1 2 3 4) 5)", - "description": "The `append` function takes a list and another value with the same entry type,\nand outputs a list of the same type with max_len += 1.", - "example": "(append (list 1 2 3 4) 5) ;; Returns (1 2 3 4 5)", - "version": "Clarity1" - }, - { - "name": "as-contract", - "snippet": "as-contract ${1:expr}", - "input_type": "A", - "output_type": "A", - "signature": "(as-contract expr)", - "description": "The `as-contract` function switches the current context's `tx-sender` value to the _contract's_\nprincipal and executes `expr` with that context. It returns the resulting value of `expr`.", - "example": "(as-contract tx-sender) ;; Returns S1G2081040G2081040G2081040G208105NK8PE5.docs-test", - "version": "Clarity1" - }, - { - "name": "as-max-len?", - "snippet": "as-max-len? ${1:sequence} ${2:max-len}", - "input_type": "sequence_A, uint", - "output_type": "(optional sequence_A)", - "signature": "(as-max-len? sequence max_length)", - "description": "The `as-max-len?` function takes a sequence argument and a uint-valued, literal length argument.\nThe function returns an optional type. If the input sequence length is less than\nor equal to the supplied max_length, this returns `(some sequence)`, otherwise it returns `none`.\nApplicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`.\n", - "example": "\n(as-max-len? (list 2 2 2) u3) ;; Returns (some (2 2 2))\n(as-max-len? (list 1 2 3) u2) ;; Returns none\n(as-max-len? \"hello\" u10) ;; Returns (some \"hello\")\n(as-max-len? 0x010203 u10) ;; Returns (some 0x010203)\n", - "version": "Clarity1" - }, - { - "name": "asserts!", - "snippet": "asserts! ${1:boolean-expr} (err ${2:thrown})", - "input_type": "bool, C", - "output_type": "bool", - "signature": "(asserts! bool-expr thrown-value)", - "description": "The `asserts!` function admits a boolean argument and asserts its evaluation:\nif bool-expr is `true`, `asserts!` returns `true` and proceeds in the program execution.\nIf the supplied argument is returning a false value, `asserts!` _returns_ `thrown-value` and exits the current\ncontrol-flow.", - "example": "(asserts! (is-eq 1 1) (err 1)) ;; Returns true", - "version": "Clarity1" - }, - { - "name": "at-block", - "snippet": "at-block ${1:id-header-hash} ${2:expr}", - "input_type": "(buff 32), A", - "output_type": "A", - "signature": "(at-block id-block-hash expr)", - "description": "The `at-block` function evaluates the expression `expr` _as if_ it were evaluated at the end of the\nblock indicated by the _block-hash_ argument. The `expr` closure must be read-only.\n\nNote: The block identifying hash must be a hash returned by the `id-header-hash` block information\nproperty. This hash uniquely identifies Stacks blocks and is unique across Stacks forks. While the hash returned by\n`header-hash` is unique within the context of a single fork, it is not unique across Stacks forks.\n\nThe function returns the result of evaluating `expr`.\n", - "example": "\n(define-data-var data int 1)\n(at-block 0x0000000000000000000000000000000000000000000000000000000000000000 block-height) ;; Returns u0\n(at-block (get-block-info? id-header-hash 0) (var-get data)) ;; Throws NoSuchDataVariable because `data` wasn't initialized at block height 0", - "version": "Clarity1" - }, - { - "name": "begin", - "snippet": "begin ${1:expr-1} ${2:expr-2}", - "input_type": "AnyType, ... A", - "output_type": "A", - "signature": "(begin expr1 expr2 expr3 ... expr-last)", - "description": "The `begin` function evaluates each of its input expressions, returning the\nreturn value of the last such expression.\nNote: intermediary statements returning a response type must be checked.", - "example": "(begin (+ 1 2) 4 5) ;; Returns 5", - "version": "Clarity1" - }, - { - "name": "bit-and", - "snippet": "bit-and ${1:expr-1} ${2:expr-2}", - "input_type": "int, ... | uint, ...", - "output_type": "int | uint", - "signature": "(bit-and i1 i2...)", - "description": "Returns the result of bitwise and'ing a variable number of integer inputs.", - "example": "(bit-and 24 16) ;; Returns 16\n(bit-and 28 24 -1) ;; Returns 24\n(bit-and u24 u16) ;; Returns u16\n(bit-and -128 -64) ;; Returns -128\n(bit-and 28 24 -1) ;; Returns 24\n", - "version": "Clarity2" - }, - { - "name": "bit-not", - "snippet": "bit-not ${1:expr-1}", - "input_type": "int | uint", - "output_type": "int | uint", - "signature": "(bit-not i1)", - "description": "Returns the one's compliement (sometimes also called the bitwise compliment or not operator) of `i1`, effectively reversing the bits in `i1`.\nIn other words, every bit that is `1` in ì1` will be `0` in the result. Conversely, every bit that is `0` in `i1` will be `1` in the result.\n", - "example": "(bit-not 3) ;; Returns -4\n(bit-not u128) ;; Returns u340282366920938463463374607431768211327\n(bit-not 128) ;; Returns -129\n(bit-not -128) ;; Returns 127\n", - "version": "Clarity2" - }, - { - "name": "bit-or", - "snippet": "bit-or ${1:expr-1} ${2:expr-2}", - "input_type": "int, ... | uint, ...", - "output_type": "int | uint", - "signature": "(bit-or i1 i2...)", - "description": "Returns the result of bitwise inclusive or'ing a variable number of integer inputs.", - "example": "(bit-or 4 8) ;; Returns 12\n(bit-or 1 2 4) ;; Returns 7\n(bit-or 64 -32 -16) ;; Returns -16\n(bit-or u2 u4 u32) ;; Returns u38\n", - "version": "Clarity2" - }, - { - "name": "bit-shift-left", - "snippet": "bit-shift-left ${1:expr-1} ${2:expr-2}", - "input_type": "int, uint | uint, uint", - "output_type": "int | uint", - "signature": "(bit-shift-left i1 shamt)", - "description": "Shifts all the bits in `i1` to the left by the number of places specified in `shamt` modulo 128 (the bit width of Clarity integers). \n\nNote that there is a deliberate choice made to ignore arithmetic overflow for this operation. In use cases where overflow should be detected, developers\nshould use `*`, `/`, and `pow` instead of the shift operators.\n", - "example": "(bit-shift-left 2 u1) ;; Returns 4\n(bit-shift-left 16 u2) ;; Returns 64\n(bit-shift-left -64 u1) ;; Returns -128\n(bit-shift-left u4 u2) ;; Returns u16\n(bit-shift-left 123 u9999999999) ;; Returns -170141183460469231731687303715884105728\n(bit-shift-left u123 u9999999999) ;; Returns u170141183460469231731687303715884105728\n(bit-shift-left -1 u7) ;; Returns -128\n(bit-shift-left -1 u128) ;; Returns -1\n", - "version": "Clarity2" - }, - { - "name": "bit-shift-right", - "snippet": "bit-shift-right ${1:expr-1} ${2:expr-2}", - "input_type": "int, uint | uint, uint", - "output_type": "int | uint", - "signature": "(bit-shift-right i1 shamt)", - "description": "Shifts all the bits in `i1` to the right by the number of places specified in `shamt` modulo 128 (the bit width of Clarity integers). \nWhen `i1` is a `uint` (unsigned), new bits are filled with zeros. When `i1` is an `int` (signed), the sign is preserved, meaning that new bits are filled with the value of the previous sign-bit.\n\nNote that there is a deliberate choice made to ignore arithmetic overflow for this operation. In use cases where overflow should be detected, developers should use `*`, `/`, and `pow` instead of the shift operators.\n", - "example": "(bit-shift-right 2 u1) ;; Returns 1\n(bit-shift-right 128 u2) ;; Returns 32\n(bit-shift-right -64 u1) ;; Returns -32\n(bit-shift-right u128 u2) ;; Returns u32\n(bit-shift-right 123 u9999999999) ;; Returns 0\n(bit-shift-right u123 u9999999999) ;; Returns u0\n(bit-shift-right -128 u7) ;; Returns -1\n(bit-shift-right -256 u1) ;; Returns -128\n(bit-shift-right 5 u2) ;; Returns 1\n(bit-shift-right -5 u2) ;; Returns -2\n", - "version": "Clarity2" - }, - { - "name": "bit-xor", - "snippet": "bit-xor ${1:expr-1} ${2:expr-2}", - "input_type": "int, ... | uint, ...", - "output_type": "int | uint", - "signature": "(bit-xor i1 i2...)", - "description": "Returns the result of bitwise exclusive or'ing a variable number of integer inputs.", - "example": "(bit-xor 1 2) ;; Returns 3\n(bit-xor 120 280) ;; Returns 352\n(bit-xor -128 64) ;; Returns -64\n(bit-xor u24 u4) ;; Returns u28\n(bit-xor 1 2 4 -1) ;; Returns -8\n", - "version": "Clarity2" - }, - { - "name": "buff-to-int-be", - "snippet": "buff-to-int-be ${1:buff}", - "input_type": "(buff 16)", - "output_type": "int", - "signature": "(buff-to-int-be (buff 16))", - "description": "Converts a byte buffer to a signed integer use a big-endian encoding.\nThe byte buffer can be up to 16 bytes in length. If there are fewer than 16 bytes, as\nthis function uses a big-endian encoding, the input behaves as if it is\nzero-padded on the _left_.\n\nNote: This function is only available starting with Stacks 2.1.", - "example": "\n(buff-to-int-be 0x01) ;; Returns 1\n(buff-to-int-be 0x00000000000000000000000000000001) ;; Returns 1\n(buff-to-int-be 0xffffffffffffffffffffffffffffffff) ;; Returns -1\n(buff-to-int-be 0x) ;; Returns 0\n", - "version": "Clarity2" - }, - { - "name": "buff-to-int-le", - "snippet": "buff-to-int-le ${1:buff}", - "input_type": "(buff 16)", - "output_type": "int", - "signature": "(buff-to-int-le (buff 16))", - "description": "Converts a byte buffer to a signed integer use a little-endian encoding.\nThe byte buffer can be up to 16 bytes in length. If there are fewer than 16 bytes, as\nthis function uses a little-endian encoding, the input behaves as if it is\nzero-padded on the _right_.\n\nNote: This function is only available starting with Stacks 2.1.", - "example": "\n(buff-to-int-le 0x01) ;; Returns 1\n(buff-to-int-le 0x01000000000000000000000000000000) ;; Returns 1\n(buff-to-int-le 0xffffffffffffffffffffffffffffffff) ;; Returns -1\n(buff-to-int-le 0x) ;; Returns 0\n", - "version": "Clarity2" - }, - { - "name": "buff-to-uint-be", - "snippet": "buff-to-uint-be ${1:buff}", - "input_type": "(buff 16)", - "output_type": "uint", - "signature": "(buff-to-uint-be (buff 16))", - "description": "Converts a byte buffer to an unsigned integer use a big-endian encoding.\nThe byte buffer can be up to 16 bytes in length. If there are fewer than 16 bytes, as\nthis function uses a big-endian encoding, the input behaves as if it is\nzero-padded on the _left_.\n\nNote: This function is only available starting with Stacks 2.1.", - "example": "\n(buff-to-uint-be 0x01) ;; Returns u1\n(buff-to-uint-be 0x00000000000000000000000000000001) ;; Returns u1\n(buff-to-uint-be 0xffffffffffffffffffffffffffffffff) ;; Returns u340282366920938463463374607431768211455\n(buff-to-uint-be 0x) ;; Returns u0\n", - "version": "Clarity2" - }, - { - "name": "buff-to-uint-le", - "snippet": "buff-to-uint-le ${1:buff}", - "input_type": "(buff 16)", - "output_type": "uint", - "signature": "(buff-to-uint-le (buff 16))", - "description": "Converts a byte buffer to an unsigned integer use a little-endian encoding..\nThe byte buffer can be up to 16 bytes in length. If there are fewer than 16 bytes, as\nthis function uses a little-endian encoding, the input behaves as if it is\nzero-padded on the _right_.\n\nNote: This function is only available starting with Stacks 2.1.", - "example": "\n(buff-to-uint-le 0x01) ;; Returns u1\n(buff-to-uint-le 0x01000000000000000000000000000000) ;; Returns u1\n(buff-to-uint-le 0xffffffffffffffffffffffffffffffff) ;; Returns u340282366920938463463374607431768211455\n(buff-to-uint-le 0x) ;; Returns u0\n", - "version": "Clarity2" - }, - { - "name": "concat", - "snippet": "concat ${1:sequence-1} ${2:sequence-2}", - "input_type": "sequence_A, sequence_A", - "output_type": "sequence_A", - "signature": "(concat sequence1 sequence2)", - "description": "The `concat` function takes two sequences of the same type,\nand returns a concatenated sequence of the same type, with the resulting\nsequence_len = sequence1_len + sequence2_len.\nApplicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`.\n", - "example": "\n(concat (list 1 2) (list 3 4)) ;; Returns (1 2 3 4)\n(concat \"hello \" \"world\") ;; Returns \"hello world\"\n(concat 0x0102 0x0304) ;; Returns 0x01020304\n", - "version": "Clarity1" - }, - { - "name": "contract-call?", - "snippet": "contract-call? ${1:contract-principal} ${2:func} ${3:arg1}", - "input_type": "ContractName, PublicFunctionName, Arg0, ...", - "output_type": "(response A B)", - "signature": "(contract-call? .contract-name function-name arg0 arg1 ...)", - "description": "The `contract-call?` function executes the given public function of the given contract.\nYou _may not_ use this function to call a public function defined in the current contract. If the public\nfunction returns _err_, any database changes resulting from calling `contract-call?` are aborted.\nIf the function returns _ok_, database changes occurred.", - "example": "\n;; instantiate the sample-contracts/tokens.clar contract first!\n(as-contract (contract-call? .tokens mint! u19)) ;; Returns (ok u19)", - "version": "Clarity1" - }, - { - "name": "contract-of", - "snippet": "contract-of ${1:contract-name}", - "input_type": "Trait", - "output_type": "principal", - "signature": "(contract-of .contract-name)", - "description": "The `contract-of` function returns the principal of the contract implementing the trait.", - "example": "\n(use-trait token-a-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait)\n(define-public (forward-get-balance (user principal) (contract ))\n (begin\n (ok (contract-of contract)))) ;; returns the principal of the contract implementing \n", - "version": "Clarity1" - }, - { - "name": "default-to", - "snippet": "default-to ${1:default-value} ${2:option-value}", - "input_type": "A, (optional A)", - "output_type": "A", - "signature": "(default-to default-value option-value)", - "description": "The `default-to` function attempts to 'unpack' the second argument: if the argument is\na `(some ...)` option, it returns the inner value of the option. If the second argument is a `(none)` value,\n`default-to` it returns the value of `default-value`.", - "example": "\n(define-map names-map { name: (string-ascii 12) } { id: int })\n(map-set names-map { name: \"blockstack\" } { id: 1337 })\n(default-to 0 (get id (map-get? names-map (tuple (name \"blockstack\"))))) ;; Returns 1337\n(default-to 0 (get id (map-get? names-map (tuple (name \"non-existant\"))))) ;; Returns 0\n", - "version": "Clarity1" - }, - { - "name": "define-constant", - "snippet": "define-constant ${1:name} ${2:exprs}", - "input_type": "MethodSignature, MethodBody", - "output_type": "Not Applicable", - "signature": "(define-constant name expression)", - "description": "`define-constant` is used to define a private constant value in a smart contract.\nThe expression passed into the definition is evaluated at contract launch, in the order that it is\nsupplied in the contract. This can lead to undefined function or undefined variable errors in the\nevent that a function or variable used in the expression has not been defined before the constant.\n\nLike other kinds of definition statements, `define-constant` may only be used at the top level of a smart contract\ndefinition (i.e., you cannot put a define statement in the middle of a function body).\n", - "example": "\n(define-constant four (+ 2 2))\n(+ 4 four) ;; Returns 8\n", - "version": "Clarity1" - }, - { - "name": "define-data-var", - "snippet": "define-data-var ${1:name} ${2:type} ${3:value}", - "input_type": "VarName, TypeDefinition, Value", - "output_type": "Not Applicable", - "signature": "(define-data-var var-name type value)", - "description": "`define-data-var` is used to define a new persisted variable for use in a smart contract. Such\nvariable are only modifiable by the current smart contract.\n\nPersisted variable are defined with a type and a value.\n\nLike other kinds of definition statements, `define-data-var` may only be used at the top level of a smart contract\ndefinition (i.e., you cannot put a define statement in the middle of a function body).", - "example": "\n(define-data-var size int 0)\n(define-private (set-size (value int))\n (var-set size value))\n(set-size 1)\n(set-size 2)\n", - "version": "Clarity1" - }, - { - "name": "define-fungible-token", - "snippet": "define-fungible-token ${1:token-name} ${2:total-supply}", - "input_type": "TokenName, ", - "output_type": "Not Applicable", - "signature": "(define-fungible-token token-name )", - "description": "`define-fungible-token` is used to define a new fungible token class for use in the current contract.\n\nThe second argument, if supplied, defines the total supply of the fungible token. This ensures that all calls to the `ft-mint?`\nfunction will never be able to create more than `total-supply` tokens. If any such call were to increase the total supply\nof tokens passed that amount, that invocation of `ft-mint?` will result in a runtime error and abort.\n\nLike other kinds of definition statements, `define-fungible-token` may only be used at the top level of a smart contract\ndefinition (i.e., you cannot put a define statement in the middle of a function body).\n\nTokens defined using `define-fungible-token` may be used in `ft-transfer?`, `ft-mint?`, and `ft-get-balance` functions", - "example": "\n(define-fungible-token stacks)\n(define-fungible-token limited-supply-stacks u100)\n", - "version": "Clarity1" - }, - { - "name": "define-map", - "snippet": "define-map ${1:map-name} { ${2:key-name-1}: ${3:key-type-1} } { ${4:val-name-1}: ${5:vals-type-1} }", - "input_type": "MapName, TypeDefinition, TypeDefinition", - "output_type": "Not Applicable", - "signature": "(define-map map-name key-type value-type)", - "description": "`define-map` is used to define a new datamap for use in a smart contract. Such\nmaps are only modifiable by the current smart contract.\n\nMaps are defined with a key type and value type, often these types are tuple types.\n\nLike other kinds of definition statements, `define-map` may only be used at the top level of a smart contract\ndefinition (i.e., you cannot put a define statement in the middle of a function body).", - "example": "\n(define-map squares { x: int } { square: int })\n(define-private (add-entry (x int))\n (map-insert squares { x: 2 } { square: (* x x) }))\n(add-entry 1)\n(add-entry 2)\n(add-entry 3)\n(add-entry 4)\n(add-entry 5)\n", - "version": "Clarity1" - }, - { - "name": "define-non-fungible-token", - "snippet": "define-non-fungible-token ${1:nft-name} ${2:nft-identifier-type}", - "input_type": "AssetName, TypeSignature", - "output_type": "Not Applicable", - "signature": "(define-non-fungible-token asset-name asset-identifier-type)", - "description": "`define-non-fungible-token` is used to define a new non-fungible token class for use in the current contract.\nIndividual assets are identified by their asset identifier, which must be of the type `asset-identifier-type`. Asset\nidentifiers are _unique_ identifiers.\n\nLike other kinds of definition statements, `define-non-fungible-token` may only be used at the top level of a smart contract\ndefinition (i.e., you cannot put a define statement in the middle of a function body).\n\nAssets defined using `define-non-fungible-token` may be used in `nft-transfer?`, `nft-mint?`, and `nft-get-owner?` functions", - "example": "\n(define-non-fungible-token names (buff 50))\n", - "version": "Clarity1" - }, - { - "name": "define-private", - "snippet": "define-private (${1:func-name}) ${2:body}", - "input_type": "MethodSignature, MethodBody", - "output_type": "Not Applicable", - "signature": "(define-private (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)", - "description": "`define-private` is used to define _private_ functions for a smart contract. Private\nfunctions may not be called from other smart contracts, nor may they be invoked directly by users.\nInstead, these functions may only be invoked by other functions defined in the same smart contract.\n\nLike other kinds of definition statements, `define-private` may only be used at the top level of a smart contract\ndefinition (i.e., you cannot put a define statement in the middle of a function body).\n\nPrivate functions may return any type.", - "example": "\n(define-private (max-of (i1 int) (i2 int))\n (if (> i1 i2)\n i1\n i2))\n(max-of 4 6) ;; Returns 6\n", - "version": "Clarity1" - }, - { - "name": "define-public", - "snippet": "define-public (${1:func-name}) ${2:body}", - "input_type": "MethodSignature, MethodBody", - "output_type": "Not Applicable", - "signature": "(define-public (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)", - "description": "`define-public` is used to define a _public_ function and transaction for a smart contract. Public\nfunctions are callable from other smart contracts and may be invoked directly by users by submitting a transaction\nto the Stacks blockchain.\n\nLike other kinds of definition statements, `define-public` may only be used at the top level of a smart contract\ndefinition (i.e., you cannot put a define statement in the middle of a function body).\n\nPublic functions _must_ return a ResponseType (using either `ok` or `err`). Any datamap modifications performed by\na public function is aborted if the function returns an `err` type. Public functions may be invoked by other\ncontracts via `contract-call?`.", - "example": "\n(define-public (hello-world (input int))\n (begin (print (+ 2 input))\n (ok input)))\n", - "version": "Clarity1" - }, - { - "name": "define-read-only", - "snippet": "define-read-only (${1:func-name}) ${2:body}", - "input_type": "MethodSignature, MethodBody", - "output_type": "Not Applicable", - "signature": "(define-read-only (function-name (arg-name-0 arg-type-0) (arg-name-1 arg-type-1) ...) function-body)", - "description": "`define-read-only` is used to define a _public read-only_ function for a smart contract. Such\nfunctions are callable from other smart contracts.\n\nLike other kinds of definition statements, `define-read-only` may only be used at the top level of a smart contract\ndefinition (i.e., you cannot put a define statement in the middle of a function body).\n\nRead-only functions may return any type. However, read-only functions\nmay not perform any datamap modifications, or call any functions which\nperform such modifications. This is enforced both during type checks and during\nthe execution of the function. Public read-only functions may\nbe invoked by other contracts via `contract-call?`.", - "example": "\n(define-read-only (just-return-one-hundred)\n (* 10 10))", - "version": "Clarity1" - }, - { - "name": "define-trait", - "snippet": "define-trait ${1:trait-name} ((${2:func-name} (${3:func-param-types}) (response ${4:ok-type} ${5:err-type})))", - "input_type": "VarName, [MethodSignature]", - "output_type": "Not Applicable", - "signature": "(define-trait trait-name ((func1-name (arg1-type arg2-type ...) (return-type))))", - "description": "`define-trait` is used to define a new trait definition for use in a smart contract. Other contracts\ncan implement a given trait and then have their contract identifier being passed as a function argument in order to be called\ndynamically with `contract-call?`.\n\nTraits are defined with a name, and a list functions, defined with a name, a list of argument types, and return type.\n\nIn Clarity 1, a trait type can be used to specify the type of a function parameter. A parameter with a trait type can\nbe used as the target of a dynamic `contract-call?`. A principal literal (e.g. `ST1PQHQKV0RJXZFY1DGX8MNSNYVE3VGZJSRTPGZGM.foo`)\nmay be passed as a trait parameter if the specified contract implements all of the functions specified by the trait.\nA trait value (originating from a parameter with trait type) may also be passed as a trait parameter if the types are the same.\n\nBeginning in Clarity 2, a trait can be used in all of the same ways that a built-in type can be used,\nexcept that it cannot be stored in a data var or map, since this would inhibit static analysis.\nThis means that a trait type can be embedded in a compound type (e.g. `(optional )` or `(list 4 )`)\nand a trait value can be bound to a variable in a `let` or `match` expression. In addition to the principal literal\nand trait value with matching type allowed in Clarity 1, Clarity 2 also supports implicit casting from a\ncompatible trait, meaning that a value of type `trait-a` may be passed to a parameter with type `trait-b` if `trait-a`\nincludes all of the requirements of `trait-b` (and optionally additional functions).\n\nLike other kinds of definition statements, `define-trait` may only be used at the top level of a smart contract\ndefinition (i.e., you cannot put a define statement in the middle of a function body).\n", - "example": "\n(define-trait token-trait\n ((transfer? (principal principal uint) (response uint uint))\n (get-balance (principal) (response uint uint))))\n", - "version": "Clarity1" - }, - { - "name": "element-at", - "snippet": "element-at? ${1:sequence} ${2:index}", - "input_type": "sequence_A, uint", - "output_type": "(optional A)", - "signature": "(element-at? sequence index)", - "description": "The `element-at?` function returns the element at `index` in the provided sequence.\nApplicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`,\nfor which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`.\nIn Clarity1, `element-at` must be used (without the `?`). The `?` is added in Clarity2 for consistency -- built-ins that return responses or optionals end in `?`. The Clarity1 spelling is left as an alias in Clarity2 for backwards compatibility.\n", - "example": "\n(element-at? \"blockstack\" u5) ;; Returns (some \"s\")\n(element-at? (list 1 2 3 4 5) u5) ;; Returns none\n(element-at? (list 1 2 3 4 5) (+ u1 u2)) ;; Returns (some 4)\n(element-at? \"abcd\" u1) ;; Returns (some \"b\")\n(element-at? 0xfb01 u1) ;; Returns (some 0x01)\n", - "version": "Clarity1" - }, - { - "name": "element-at?", - "snippet": "element-at? ${1:sequence} ${2:index}", - "input_type": "sequence_A, uint", - "output_type": "(optional A)", - "signature": "(element-at? sequence index)", - "description": "The `element-at?` function returns the element at `index` in the provided sequence.\nApplicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`,\nfor which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`.\nIn Clarity1, `element-at` must be used (without the `?`). The `?` is added in Clarity2 for consistency -- built-ins that return responses or optionals end in `?`. The Clarity1 spelling is left as an alias in Clarity2 for backwards compatibility.\n", - "example": "\n(element-at? \"blockstack\" u5) ;; Returns (some \"s\")\n(element-at? (list 1 2 3 4 5) u5) ;; Returns none\n(element-at? (list 1 2 3 4 5) (+ u1 u2)) ;; Returns (some 4)\n(element-at? \"abcd\" u1) ;; Returns (some \"b\")\n(element-at? 0xfb01 u1) ;; Returns (some 0x01)\n", - "version": "Clarity2" - }, - { - "name": "err", - "snippet": "err ${1:value}", - "input_type": "A", - "output_type": "(response A B)", - "signature": "(err value)", - "description": "The `err` function constructs a response type from the input value. Use `err` for\ncreating return values in public functions. An _err_ value indicates that any database changes during\nthe processing of the function should be rolled back.", - "example": "(err true) ;; Returns (err true)", - "version": "Clarity1" - }, - { - "name": "filter", - "snippet": "filter ${1:func} ${2:sequence}", - "input_type": "Function(A) -> bool, sequence_A", - "output_type": "sequence_A", - "signature": "(filter func sequence)", - "description": "The `filter` function applies the input function `func` to each element of the\ninput sequence, and returns the same sequence with any elements removed for which `func` returned `false`.\nApplicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`,\nfor which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`.\nThe `func` argument must be a literal function name.\n", - "example": "\n(filter not (list true false true false)) ;; Returns (false false)\n(define-private (is-a (char (string-utf8 1))) (is-eq char u\"a\"))\n(filter is-a u\"acabd\") ;; Returns u\"aa\"\n(define-private (is-zero (char (buff 1))) (is-eq char 0x00))\n(filter is-zero 0x00010002) ;; Returns 0x0000\n", - "version": "Clarity1" - }, - { - "name": "fold", - "snippet": "fold ${1:func} ${2:sequence} ${3:initial-value}", - "input_type": "Function(A, B) -> B, sequence_A, B", - "output_type": "B", - "signature": "(fold func sequence_A initial_B)", - "description": "The `fold` function condenses `sequence_A` into a value of type\n`B` by recursively applies the function `func` to each element of the\ninput sequence _and_ the output of a previous application of `func`.\n\n`fold` uses `initial_B` in the initial application of `func`, along with the\nfirst element of `sequence_A`. The resulting value of type `B` is used for the\nnext application of `func`, along with the next element of `sequence_A` and so\non. `fold` returns the last value of type `B` returned by these successive\napplications `func`.\n\nApplicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`,\nfor which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`.\nThe `func` argument must be a literal function name.\n", - "example": "\n(fold * (list 2 2 2) 1) ;; Returns 8\n(fold * (list 2 2 2) 0) ;; Returns 0\n;; calculates (- 11 (- 7 (- 3 2)))\n(fold - (list 3 7 11) 2) ;; Returns 5 \n(define-private (concat-string (a (string-ascii 20)) (b (string-ascii 20))) (unwrap-panic (as-max-len? (concat a b) u20)))\n(fold concat-string \"cdef\" \"ab\") ;; Returns \"fedcab\"\n(fold concat-string (list \"cd\" \"ef\") \"ab\") ;; Returns \"efcdab\"\n(define-private (concat-buff (a (buff 20)) (b (buff 20))) (unwrap-panic (as-max-len? (concat a b) u20)))\n(fold concat-buff 0x03040506 0x0102) ;; Returns 0x060504030102\n", - "version": "Clarity1" - }, - { - "name": "from-consensus-buff?", - "snippet": "from-consensus-buff? ${1:type-signature} ${2:buffer}", - "input_type": "type-signature(t), buff", - "output_type": "(optional t)", - "signature": "(from-consensus-buff? type-signature buffer)", - "description": "`from-consensus-buff?` is a special function that will deserialize a\nbuffer into a Clarity value, using the SIP-005 serialization of the\nClarity value. The type that `from-consensus-buff?` tries to deserialize\ninto is provided by the first parameter to the function. If it fails\nto deserialize the type, the method returns `none`.\n", - "example": "\n(from-consensus-buff? int 0x0000000000000000000000000000000001) ;; Returns (some 1)\n(from-consensus-buff? uint 0x0000000000000000000000000000000001) ;; Returns none\n(from-consensus-buff? uint 0x0100000000000000000000000000000001) ;; Returns (some u1)\n(from-consensus-buff? bool 0x0000000000000000000000000000000001) ;; Returns none\n(from-consensus-buff? bool 0x03) ;; Returns (some true)\n(from-consensus-buff? bool 0x04) ;; Returns (some false)\n(from-consensus-buff? principal 0x051fa46ff88886c2ef9762d970b4d2c63678835bd39d) ;; Returns (some SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)\n(from-consensus-buff? { abc: int, def: int } 0x0c00000002036162630000000000000000000000000000000003036465660000000000000000000000000000000004) ;; Returns (some (tuple (abc 3) (def 4)))\n", - "version": "Clarity2" - }, - { - "name": "ft-burn?", - "snippet": "ft-burn? ${1:asset-name} ${2:amount} ${3:sender}", - "input_type": "TokenName, uint, principal", - "output_type": "(response bool uint)", - "signature": "(ft-burn? token-name amount sender)", - "description": "`ft-burn?` is used to decrease the token balance for the `sender` principal for a token\ntype defined using `define-fungible-token`. The decreased token balance is _not_ transfered to another principal, but\nrather destroyed, reducing the circulating supply. \n\nOn a successful burn, it returns `(ok true)`. In the event of an unsuccessful burn it\nreturns one of the following error codes:\n\n`(err u1)` -- `sender` does not have enough balance to burn this amount or the amount specified is not positive\n", - "example": "\n(define-fungible-token stackaroo)\n(ft-mint? stackaroo u100 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true)\n(ft-burn? stackaroo u50 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true)\n", - "version": "Clarity1" - }, - { - "name": "ft-get-balance", - "snippet": "ft-get-balance ${1:token-name} ${2:principal}", - "input_type": "TokenName, principal", - "output_type": "uint", - "signature": "(ft-get-balance token-name principal)", - "description": "`ft-get-balance` returns `token-name` balance of the principal `principal`.\nThe token type must have been defined using `define-fungible-token`.", - "example": "\n(define-fungible-token stackaroo)\n(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)\n(ft-get-balance stackaroo 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns u100\n", - "version": "Clarity1" - }, - { - "name": "ft-get-supply", - "snippet": "ft-get-supply ${1:token-name}", - "input_type": "TokenName", - "output_type": "uint", - "signature": "(ft-get-supply token-name)", - "description": "`ft-get-balance` returns `token-name` circulating supply.\nThe token type must have been defined using `define-fungible-token`.", - "example": "\n(define-fungible-token stackaroo)\n(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)\n(ft-get-supply stackaroo) ;; Returns u100\n", - "version": "Clarity1" - }, - { - "name": "ft-mint?", - "snippet": "ft-mint? ${1:token-name} ${2:amount} ${3:recipient}", - "input_type": "TokenName, uint, principal", - "output_type": "(response bool uint)", - "signature": "(ft-mint? token-name amount recipient)", - "description": "`ft-mint?` is used to increase the token balance for the `recipient` principal for a token\ntype defined using `define-fungible-token`. The increased token balance is _not_ transfered from another principal, but\nrather minted. \n\nIf a non-positive amount is provided to mint, this function returns `(err 1)`. Otherwise, on successfuly mint, it\nreturns `(ok true)`.\n", - "example": "\n(define-fungible-token stackaroo)\n(ft-mint? stackaroo u100 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true)\n", - "version": "Clarity1" - }, - { - "name": "ft-transfer?", - "snippet": "ft-transfer? ${1:token-name} ${2:amount} ${3:sender} ${4:recipient}", - "input_type": "TokenName, uint, principal, principal", - "output_type": "(response bool uint)", - "signature": "(ft-transfer? token-name amount sender recipient)", - "description": "`ft-transfer?` is used to increase the token balance for the `recipient` principal for a token\ntype defined using `define-fungible-token` by debiting the `sender` principal. In contrast to `stx-transfer?`, \nany user can transfer the assets. When used, relevant guards need to be added.\n\nThis function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns\none of the following error codes:\n\n`(err u1)` -- `sender` does not have enough balance to transfer\n`(err u2)` -- `sender` and `recipient` are the same principal\n`(err u3)` -- amount to send is non-positive\n", - "example": "\n(define-fungible-token stackaroo)\n(ft-mint? stackaroo u100 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)\n(ft-transfer? stackaroo u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true)\n(ft-transfer? stackaroo u60 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u1)\n", - "version": "Clarity1" - }, - { - "name": "get", - "snippet": "get ${1:key-name} ${2:tuple}", - "input_type": "KeyName, (tuple) | (optional (tuple))", - "output_type": "A", - "signature": "(get key-name tuple)", - "description": "The `get` function fetches the value associated with a given key from the supplied typed tuple.\nIf an `Optional` value is supplied as the inputted tuple, `get` returns an `Optional` type of the specified key in\nthe tuple. If the supplied option is a `(none)` option, get returns `(none)`.", - "example": "(define-map names-map { name: (string-ascii 12) } { id: int })\n(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true\n(get id (tuple (name \"blockstack\") (id 1337))) ;; Returns 1337\n(get id (map-get? names-map (tuple (name \"blockstack\")))) ;; Returns (some 1337)\n(get id (map-get? names-map (tuple (name \"non-existent\")))) ;; Returns none\n", - "version": "Clarity1" - }, - { - "name": "get-block-info?", - "snippet": "get-block-info? ${1:prop} ${2:block-height}", - "input_type": "BlockInfoPropertyName, uint", - "output_type": "(optional buff) | (optional uint)", - "signature": "(get-block-info? prop-name block-height)", - "description": "The `get-block-info?` function fetches data for a block of the given *Stacks* block height. The\nvalue and type returned are determined by the specified `BlockInfoPropertyName`. If the provided `block-height` does\nnot correspond to an existing block prior to the current block, the function returns `none`. The currently available property names\nare as follows:\n\n`burnchain-header-hash`: This property returns a `(buff 32)` value containing the header hash of the burnchain (Bitcoin) block that selected the \nStacks block at the given Stacks chain height.\n\n`id-header-hash`: This property returns a `(buff 32)` value containing the _index block hash_ of a Stacks block. This hash is globally unique, and is derived\nfrom the block hash and the history of accepted PoX operations. This is also the block hash value you would pass into `(at-block)`.\n\n`header-hash`: This property returns a `(buff 32)` value containing the header hash of a Stacks block, given a Stacks chain height. **WARNING* this hash is\nnot guaranteed to be globally unique, since the same Stacks block can be mined in different PoX forks. If you need global uniqueness, you should use `id-header-hash`.\n\n`miner-address`: This property returns a `principal` value corresponding to the miner of the given block. **WARNING** In Stacks 2.1, this is not guaranteed to \nbe the same `principal` that received the block reward, since Stacks 2.1 supports coinbase transactions that pay the reward to a contract address. This is merely\nthe address of the `principal` that produced the block.\n\n`time`: This property returns a `uint` value of the block header time field. This is a Unix epoch timestamp in seconds\nwhich roughly corresponds to when the block was mined. **Note**: this does not increase monotonically with each block\nand block times are accurate only to within two hours. See [BIP113](https://github.com/bitcoin/bips/blob/master/bip-0113.mediawiki) for more information.\n\nNew in Stacks 2.1:\n\n`block-reward`: This property returns a `uint` value for the total block reward of the indicated Stacks block. This value is only available once the reward for \nthe block matures. That is, the latest `block-reward` value available is at least 101 Stacks blocks in the past (on mainnet). The reward includes the coinbase,\nthe anchored block's transaction fees, and the shares of the confirmed and produced microblock transaction fees earned by this block's miner. Note that this value may \nbe smaller than the Stacks coinbase at this height, because the miner may have been punished with a valid `PoisonMicroblock` transaction in the event that the miner\npublished two or more microblock stream forks.\n\n`miner-spend-total`: This property returns a `uint` value for the total number of burnchain tokens (i.e. satoshis) spent by all miners trying to win this block.\n\n`miner-spend-winner`: This property returns a `uint` value for the number of burnchain tokens (i.e. satoshis) spent by the winning miner for this Stacks block. Note that\nthis value is less than or equal to the value for `miner-spend-total` at the same block height.\n", - "example": "(get-block-info? time u0) ;; Returns (some u1557860301)\n(get-block-info? header-hash u0) ;; Returns (some 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb)\n(get-block-info? vrf-seed u0) ;; Returns (some 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4)\n", - "version": "Clarity1" - }, - { - "name": "get-burn-block-info?", - "snippet": "get-burn-block-info? ${1:prop} ${2:block-height}", - "input_type": "BurnBlockInfoPropertyName, uint", - "output_type": "(optional buff) | (optional (tuple (addrs (list 2 (tuple (hashbytes (buff 32)) (version (buff 1))))) (payout uint)))", - "signature": "(get-burn-block-info? prop-name block-height)", - "description": "The `get-burn-block-info?` function fetches data for a block of the given *burnchain* block height. The\nvalue and type returned are determined by the specified `BlockInfoPropertyName`. Valid values for `block-height` only\ninclude heights between the burnchain height at the time the Stacks chain was launched, and the last-processed burnchain\nblock. If the `block-height` argument falls outside of this range, then `none` shall be returned.\n\nThe following `BlockInfoPropertyName` values are defined:\n\n* The `header-hash` property returns a 32-byte buffer representing the header hash of the burnchain block at\nburnchain height `block-height`.\n\n* The `pox-addrs` property returns a tuple with two items: a list of up to two PoX addresses that received a PoX payout at that block height, and the amount of burnchain\ntokens paid to each address (note that per the blockchain consensus rules, each PoX payout will be the same for each address in the block-commit transaction).\nThe list will include burn addresses -- that is, the unspendable addresses that miners pay to when there are no PoX addresses left to be paid. During the prepare phase,\nthere will be exactly one burn address reported. During the reward phase, up to two burn addresses may be reported in the event that some PoX reward slots are not claimed.\n\nThe `addrs` list contains the same PoX address values passed into the PoX smart contract:\n * They each have type signature `(tuple (hashbytes (buff 32)) (version (buff 1)))`\n * The `version` field can be any of the following:\n * `0x00` means this is a p2pkh address, and `hashbytes` is the 20-byte hash160 of a single public key\n * `0x01` means this is a p2sh address, and `hashbytes` is the 20-byte hash160 of a redeemScript script\n * `0x02` means this is a p2wpkh-p2sh address, and `hashbytes` is the 20-byte hash160 of a p2wpkh witness script\n * `0x03` means this is a p2wsh-p2sh address, and `hashbytes` is the 20-byte hash160 of a p2wsh witness script\n * `0x04` means this is a p2wpkh address, and `hashbytes` is the 20-byte hash160 of the witness script\n * `0x05` means this is a p2wsh address, and `hashbytes` is the 32-byte sha256 of the witness script\n * `0x06` means this is a p2tr address, and `hashbytes` is the 32-byte sha256 of the witness script\n", - "example": "\n(get-burn-block-info? header-hash u677050) ;; Returns (some 0xe67141016c88a7f1203eca0b4312f2ed141531f59303a1c267d7d83ab6b977d8)\n(get-burn-block-info? pox-addrs u677050) ;; Returns (some (tuple (addrs ((tuple (hashbytes 0x395f3643cea07ec4eec73b4d9a973dcce56b9bf1) (version 0x00)) (tuple (hashbytes 0x7c6775e20e3e938d2d7e9d79ac310108ba501ddb) (version 0x01)))) (payout u123)))\n", - "version": "Clarity2" - }, - { - "name": "hash160", - "snippet": "hash160 ${1:buff}", - "input_type": "buff|uint|int", - "output_type": "(buff 20)", - "signature": "(hash160 value)", - "description": "The `hash160` function computes `RIPEMD160(SHA256(x))` of the inputted value.\nIf an integer (128 bit) is supplied the hash is computed over the little-endian representation of the\ninteger.", - "example": "(hash160 0) ;; Returns 0xe4352f72356db555721651aa612e00379167b30f", - "version": "Clarity1" - }, - { - "name": "if", - "snippet": "if ${1:condition} ${2:expr-if-true} ${3:expr-if-false}", - "input_type": "bool, A, A", - "output_type": "A", - "signature": "(if bool1 expr1 expr2)", - "description": "The `if` function admits a boolean argument and two expressions\nwhich must return the same type. In the case that the boolean input is `true`, the\n`if` function evaluates and returns `expr1`. If the boolean input is `false`, the\n`if` function evaluates and returns `expr2`.", - "example": "(if true 1 2) ;; Returns 1\n(if (> 1 2) 1 2) ;; Returns 2", - "version": "Clarity1" - }, - { - "name": "impl-trait", - "snippet": "impl-trait ${1:trait-identifier}", - "input_type": "TraitIdentifier", - "output_type": "Not Applicable", - "signature": "(impl-trait trait-identifier)", - "description": "`impl-trait` can be use for asserting that a contract is fully implementing a given trait.\nAdditional checks are being performed when the contract is being published, rejecting the deployment if the\ncontract is violating the trait specification.\n\nTrait identifiers can either be using the sugared syntax (.token-a.token-trait), or be fully qualified\n('SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait).\n\nLike other kinds of definition statements, `impl-trait` may only be used at the top level of a smart contract\ndefinition (i.e., you cannot put such a statement in the middle of a function body).\n", - "example": "\n(impl-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait)\n(define-public (get-balance (account principal))\n (ok u0))\n(define-public (transfer? (from principal) (to principal) (amount uint))\n (ok u0))\n", - "version": "Clarity1" - }, - { - "name": "index-of", - "snippet": "index-of? ${1:sequence} ${2:item}", - "input_type": "sequence_A, A", - "output_type": "(optional uint)", - "signature": "(index-of? sequence item)", - "description": "The `index-of?` function returns the first index at which `item` can be\nfound, using `is-eq` checks, in the provided sequence.\nApplicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`,\nfor which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`.\nIf the target item is not found in the sequence (or if an empty string or buffer is\nsupplied), this function returns `none`.\nIn Clarity1, `index-of` must be used (without the `?`). The `?` is added in Clarity2 for consistency -- built-ins that return responses or optionals end in `?`. The Clarity1 spelling is left as an alias in Clarity2 for backwards compatibility.\n", - "example": "\n(index-of? \"blockstack\" \"b\") ;; Returns (some u0)\n(index-of? \"blockstack\" \"k\") ;; Returns (some u4)\n(index-of? \"blockstack\" \"\") ;; Returns none\n(index-of? (list 1 2 3 4 5) 6) ;; Returns none\n(index-of? 0xfb01 0x01) ;; Returns (some u1)\n", - "version": "Clarity1" - }, - { - "name": "index-of?", - "snippet": "index-of? ${1:sequence} ${2:item}", - "input_type": "sequence_A, A", - "output_type": "(optional uint)", - "signature": "(index-of? sequence item)", - "description": "The `index-of?` function returns the first index at which `item` can be\nfound, using `is-eq` checks, in the provided sequence.\nApplicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`,\nfor which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`.\nIf the target item is not found in the sequence (or if an empty string or buffer is\nsupplied), this function returns `none`.\nIn Clarity1, `index-of` must be used (without the `?`). The `?` is added in Clarity2 for consistency -- built-ins that return responses or optionals end in `?`. The Clarity1 spelling is left as an alias in Clarity2 for backwards compatibility.\n", - "example": "\n(index-of? \"blockstack\" \"b\") ;; Returns (some u0)\n(index-of? \"blockstack\" \"k\") ;; Returns (some u4)\n(index-of? \"blockstack\" \"\") ;; Returns none\n(index-of? (list 1 2 3 4 5) 6) ;; Returns none\n(index-of? 0xfb01 0x01) ;; Returns (some u1)\n", - "version": "Clarity2" - }, - { - "name": "int-to-ascii", - "snippet": "int-to-ascii ${1:num}", - "input_type": "int | uint", - "output_type": "(string-ascii 40)", - "signature": "(int-to-ascii (int|uint))", - "description": "Converts an integer, either `int` or `uint`, to a `string-ascii` string-value representation.\n\nNote: This function is only available starting with Stacks 2.1.", - "example": "\n(int-to-ascii 1) ;; Returns \"1\"\n(int-to-ascii u1) ;; Returns \"1\"\n(int-to-ascii -1) ;; Returns \"-1\"\n", - "version": "Clarity2" - }, - { - "name": "int-to-utf8", - "snippet": "int-to-utf8 ${1:num}", - "input_type": "int | uint", - "output_type": "(string-utf8 40)", - "signature": "(int-to-utf8 (int|uint))", - "description": "Converts an integer, either `int` or `uint`, to a `string-utf8` string-value representation.\n\nNote: This function is only available starting with Stacks 2.1.", - "example": "\n(int-to-utf8 1) ;; Returns u\"1\"\n(int-to-utf8 u1) ;; Returns u\"1\"\n(int-to-utf8 -1) ;; Returns u\"-1\"\n", - "version": "Clarity2" - }, - { - "name": "is-eq", - "snippet": "is-eq ${1:expr-1} ${2:expr-2}", - "input_type": "A, A, ...", - "output_type": "bool", - "signature": "(is-eq v1 v2...)", - "description": "Compares the inputted values, returning `true` if they are all equal. Note that \n_unlike_ the `(and ...)` function, `(is-eq ...)` will _not_ short-circuit. All values supplied to\nis-eq _must_ be the same type.", - "example": "(is-eq 1 1) ;; Returns true\n(is-eq true false) ;; Returns false\n(is-eq \"abc\" 234 234) ;; Throws type error\n(is-eq \"abc\" \"abc\") ;; Returns true\n(is-eq 0x0102 0x0102) ;; Returns true\n", - "version": "Clarity1" - }, - { - "name": "is-err", - "snippet": "is-err ${1:expr}", - "input_type": "(response A B)", - "output_type": "bool", - "signature": "(is-err value)", - "description": "`is-err` tests a supplied response value, returning `true` if the response was an `err`,\nand `false` if it was an `ok`.", - "example": "(is-err (ok 1)) ;; Returns false\n(is-err (err 1)) ;; Returns true", - "version": "Clarity1" - }, - { - "name": "is-none", - "snippet": "is-none ${1:expr}", - "input_type": "(optional A)", - "output_type": "bool", - "signature": "(is-none value)", - "description": "`is-none` tests a supplied option value, returning `true` if the option value is `(none)`,\nand `false` if it is a `(some ...)`.", - "example": "\n(define-map names-map { name: (string-ascii 12) } { id: int })\n(map-set names-map { name: \"blockstack\" } { id: 1337 })\n(is-none (get id (map-get? names-map { name: \"blockstack\" }))) ;; Returns false\n(is-none (get id (map-get? names-map { name: \"non-existant\" }))) ;; Returns true", - "version": "Clarity1" - }, - { - "name": "is-ok", - "snippet": "is-ok ${1:expr}", - "input_type": "(response A B)", - "output_type": "bool", - "signature": "(is-ok value)", - "description": "`is-ok` tests a supplied response value, returning `true` if the response was `ok`,\nand `false` if it was an `err`.", - "example": "(is-ok (ok 1)) ;; Returns true\n(is-ok (err 1)) ;; Returns false", - "version": "Clarity1" - }, - { - "name": "is-some", - "snippet": "is-some ${1:expr}", - "input_type": "(optional A)", - "output_type": "bool", - "signature": "(is-some value)", - "description": "`is-some` tests a supplied option value, returning `true` if the option value is `(some ...)`,\nand `false` if it is a `none`.", - "example": "\n(define-map names-map { name: (string-ascii 12) } { id: int })\n(map-set names-map { name: \"blockstack\" } { id: 1337 })\n(is-some (get id (map-get? names-map { name: \"blockstack\" }))) ;; Returns true\n(is-some (get id (map-get? names-map { name: \"non-existant\" }))) ;; Returns false", - "version": "Clarity1" - }, - { - "name": "is-standard", - "snippet": "is-standard ${1:principal}", - "input_type": "principal", - "output_type": "bool", - "signature": "(is-standard standard-or-contract-principal)", - "description": "Tests whether `standard-or-contract-principal` _matches_ the current network\ntype, and therefore represents a principal that can spend tokens on the current\nnetwork type. That is, the network is either of type `mainnet`, or `testnet`.\nOnly `SPxxxx` and `SMxxxx` _c32check form_ addresses can spend tokens on\na mainnet, whereas only `STxxxx` and `SNxxxx` _c32check forms_ addresses can spend\ntokens on a testnet. All addresses can _receive_ tokens, but only principal\n_c32check form_ addresses that match the network type can _spend_ tokens on the\nnetwork. This method will return `true` if and only if the principal matches\nthe network type, and false otherwise.\n\nNote: This function is only available starting with Stacks 2.1.", - "example": "\n(is-standard 'STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6) ;; returns true on testnet and false on mainnet\n(is-standard 'STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6.foo) ;; returns true on testnet and false on mainnet\n(is-standard 'SP3X6QWWETNBZWGBK6DRGTR1KX50S74D3433WDGJY) ;; returns true on mainnet and false on testnet\n(is-standard 'SP3X6QWWETNBZWGBK6DRGTR1KX50S74D3433WDGJY.foo) ;; returns true on mainnet and false on testnet\n(is-standard 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; returns false on both mainnet and testnet\n", - "version": "Clarity2" - }, - { - "name": "keccak256", - "snippet": "keccak256 ${1:buff}", - "input_type": "buff|uint|int", - "output_type": "(buff 32)", - "signature": "(keccak256 value)", - "description": "The `keccak256` function computes `KECCAK256(value)` of the inputted value.\nNote that this differs from the `NIST SHA-3` (that is, FIPS 202) standard. If an integer (128 bit)\nis supplied the hash is computed over the little-endian representation of the integer.", - "example": "(keccak256 0) ;; Returns 0xf490de2920c8a35fabeb13208852aa28c76f9be9b03a4dd2b3c075f7a26923b4", - "version": "Clarity1" - }, - { - "name": "len", - "snippet": "len ${1:sequence}", - "input_type": "sequence_A", - "output_type": "uint", - "signature": "(len sequence)", - "description": "The `len` function returns the length of a given sequence.\nApplicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`.\n ", - "example": "\n(len \"blockstack\") ;; Returns u10\n(len (list 1 2 3 4 5)) ;; Returns u5\n(len 0x010203) ;; Returns u3\n", - "version": "Clarity1" - }, - { - "name": "let", - "snippet": "let ((${1:name-1} ${2:val-1})) ${3:expr-1}", - "input_type": "((name1 AnyType) (name2 AnyType) ...), AnyType, ... A", - "output_type": "A", - "signature": "(let ((name1 expr1) (name2 expr2) ...) expr-body1 expr-body2 ... expr-body-last)", - "description": "The `let` function accepts a list of `variable name` and `expression` pairs,\nevaluating each expression and _binding_ it to the corresponding variable name.\n`let` bindings are sequential: when a `let` binding is evaluated, it may refer to prior binding.\nThe _context_ created by this set of bindings is used for evaluating its body expressions.\n The let expression returns the value of the last such body expression.\nNote: intermediary statements returning a response type must be checked", - "example": "(let ((a 2) (b (+ 5 6 7))) (print a) (print b) (+ a b)) ;; Returns 20\n(let ((a 5) (c (+ a 1)) (d (+ c 1)) (b (+ a c d))) (print a) (print b) (+ a b)) ;; Returns 23", - "version": "Clarity1" - }, - { - "name": "list", - "snippet": "list ${1:expr-1} ${2:expr-2}", - "input_type": "A, ...", - "output_type": "(list A)", - "signature": "(list expr1 expr2 expr3 ...)", - "description": "The `list` function constructs a list composed of the inputted values. Each\nsupplied value must be of the same type.", - "example": "(list (+ 1 2) 4 5) ;; Returns (3 4 5)", - "version": "Clarity1" - }, - { - "name": "log2", - "snippet": "log2 ${1:expr-1}", - "input_type": "int | uint", - "output_type": "int | uint", - "signature": "(log2 n)", - "description": "Returns the power to which the number 2 must be raised to to obtain the value `n`, rounded \ndown to the nearest integer. Fails on a negative numbers.\n", - "example": "(log2 u8) ;; Returns u3\n(log2 8) ;; Returns 3\n(log2 u1) ;; Returns u0\n(log2 1000) ;; Returns 9\n", - "version": "Clarity1" - }, - { - "name": "map", - "snippet": "map ${1:func} ${2:sequence}", - "input_type": "Function(A, B, ..., N) -> X, sequence_A, sequence_B, ..., sequence_N", - "output_type": "(list X)", - "signature": "(map func sequence_A sequence_B ... sequence_N)", - "description": "The `map` function applies the function `func` to each corresponding element of the input sequences,\nand outputs a _list_ of the same type containing the outputs from those function applications.\nApplicable sequence types are `(list A)`, `buff`, `string-ascii` and `string-utf8`,\nfor which the corresponding element types are, respectively, `A`, `(buff 1)`, `(string-ascii 1)` and `(string-utf8 1)`.\nThe `func` argument must be a literal function name.\nAlso, note that, no matter what kind of sequences the inputs are, the output is always a list.", - "example": "\n(map not (list true false true false)) ;; Returns (false true false true)\n(map + (list 1 2 3) (list 1 2 3) (list 1 2 3)) ;; Returns (3 6 9)\n(define-private (a-or-b (char (string-utf8 1))) (if (is-eq char u\"a\") u\"a\" u\"b\"))\n(map a-or-b u\"aca\") ;; Returns (u\"a\" u\"b\" u\"a\")\n(define-private (zero-or-one (char (buff 1))) (if (is-eq char 0x00) 0x00 0x01))\n(map zero-or-one 0x000102) ;; Returns (0x00 0x01 0x01)\n", - "version": "Clarity1" - }, - { - "name": "map-delete", - "snippet": "map-delete ${1:map-name} ${2:key-tuple}", - "input_type": "MapName, tuple", - "output_type": "bool", - "signature": "(map-delete map-name key-tuple)", - "description": "The `map-delete` function removes the value associated with the input key for\nthe given map. If an item exists and is removed, the function returns `true`.\nIf a value did not exist for this key in the data map, the function returns `false`.", - "example": "(define-map names-map { name: (string-ascii 10) } { id: int })\n(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true\n(map-delete names-map { name: \"blockstack\" }) ;; Returns true\n(map-delete names-map { name: \"blockstack\" }) ;; Returns false\n(map-delete names-map (tuple (name \"blockstack\"))) ;; Same command, using a shorthand for constructing the tuple\n", - "version": "Clarity1" - }, - { - "name": "map-get?", - "snippet": "map-get? ${1:map-name} ${2:key-tuple}", - "input_type": "MapName, tuple", - "output_type": "(optional (tuple))", - "signature": "(map-get? map-name key-tuple)", - "description": "The `map-get?` function looks up and returns an entry from a contract's data map.\nThe value is looked up using `key-tuple`.\nIf there is no value associated with that key in the data map, the function returns a `none` option. Otherwise,\nit returns `(some value)`.", - "example": "(define-map names-map { name: (string-ascii 10) } { id: int })\n(map-set names-map { name: \"blockstack\" } { id: 1337 })\n(map-get? names-map (tuple (name \"blockstack\"))) ;; Returns (some (tuple (id 1337)))\n(map-get? names-map { name: \"blockstack\" }) ;; Same command, using a shorthand for constructing the tuple\n", - "version": "Clarity1" - }, - { - "name": "map-insert", - "snippet": "map-insert ${1:map-name} ${2:key-tuple} ${3:value-tuple}", - "input_type": "MapName, tuple_A, tuple_B", - "output_type": "bool", - "signature": "(map-insert map-name key-tuple value-tuple)", - "description": "The `map-insert` function sets the value associated with the input key to the\ninputted value if and only if there is not already a value associated with the key in the map.\nIf an insert occurs, the function returns `true`. If a value already existed for\nthis key in the data map, the function returns `false`.\n\nNote: the `value-tuple` requires 1 additional byte for storage in the materialized blockchain state,\nand therefore the maximum size of a value that may be inserted into a map is MAX_CLARITY_VALUE - 1.", - "example": "(define-map names-map { name: (string-ascii 10) } { id: int })\n(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true\n(map-insert names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns false\n(map-insert names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Same command, using a shorthand for constructing the tuple\n", - "version": "Clarity1" - }, - { - "name": "map-set", - "snippet": "map-set ${1:map-name} ${2:key-tuple} ${3:value-tuple}", - "input_type": "MapName, tuple_A, tuple_B", - "output_type": "bool", - "signature": "(map-set map-name key-tuple value-tuple)", - "description": "The `map-set` function sets the value associated with the input key to the\ninputted value. This function performs a _blind_ update; whether or not a value is already associated\nwith the key, the function overwrites that existing association.\n\nNote: the `value-tuple` requires 1 additional byte for storage in the materialized blockchain state,\nand therefore the maximum size of a value that may be inserted into a map is MAX_CLARITY_VALUE - 1.", - "example": "(define-map names-map { name: (string-ascii 10) } { id: int })\n(map-set names-map { name: \"blockstack\" } { id: 1337 }) ;; Returns true\n(map-set names-map (tuple (name \"blockstack\")) (tuple (id 1337))) ;; Same command, using a shorthand for constructing the tuple\n", - "version": "Clarity1" - }, - { - "name": "match", - "snippet": "match ${1:algebraic-expr} ${2:some-binding-name} ${3:some-branch} ${4:none-branch}", - "input_type": "(optional A) name expression expression | (response A B) name expression name expression", - "output_type": "C", - "signature": "(match opt-input some-binding-name some-branch none-branch) |\n(match-resp input ok-binding-name ok-branch err-binding-name err-branch)", - "description": "The `match` function is used to test and destructure optional and response types.\n\nIf the `input` is an optional, it tests whether the provided\n`input` is a `some` or `none` option, and evaluates `some-branch` or\n`none-branch` in each respective case.\n\nWithin the `some-branch`, the _contained value_ of the `input`\nargument is bound to the provided `some-binding-name` name.\n\nOnly _one_ of the branches will be evaluated (similar to `if` statements).\n\nIf the `input` is a response, it tests whether the provided `input` is\nan `ok` or `err` response type, and evaluates `ok-branch` or\n`err-branch` in each respective case.\n\nWithin the `ok-branch`, the _contained ok value_ of the `input`\nargument is bound to the provided `ok-binding-name` name.\n\nWithin the `err-branch`, the _contained err value_ of the `input`\nargument is bound to the provided `err-binding-name` name.\n\nOnly _one_ of the branches will be evaluated (similar to `if` statements).\n\nNote: Type checking requires that the type of both the ok and err parts of the\nresponse object be determinable. For situations in which one of the parts of a response\nis untyped, you should use `unwrap-panic` or `unwrap-err-panic` instead of `match`.", - "example": "\n(define-private (add-10 (x (optional int)))\n (match x\n value (+ 10 value)\n 10))\n(add-10 (some 5)) ;; Returns 15\n(add-10 none) ;; Returns 10\n\n(define-private (add-or-pass-err (x (response int (string-ascii 10))) (to-add int))\n (match x\n value (ok (+ to-add value))\n err-value (err err-value)))\n(add-or-pass-err (ok 5) 20) ;; Returns (ok 25)\n(add-or-pass-err (err \"ERROR\") 20) ;; Returns (err \"ERROR\")\n", - "version": "Clarity1" - }, - { - "name": "merge", - "snippet": "merge ${1:tuple-1} ${2:tuple-2}", - "input_type": "tuple, tuple", - "output_type": "tuple", - "signature": "(merge tuple { key1: val1 })", - "description": "The `merge` function returns a new tuple with the combined fields, without mutating the supplied tuples.", - "example": "(define-map users { id: int } { name: (string-ascii 12), address: (optional principal) })\n(map-insert users { id: 1337 } { name: \"john\", address: none }) ;; Returns true\n(let ((user (unwrap-panic (map-get? users { id: 1337 }))))\n (merge user { address: (some 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) })) ;; Returns (tuple (address (some SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF)) (name \"john\"))", - "version": "Clarity1" - }, - { - "name": "mod", - "snippet": "mod ${1:expr-1} ${2:expr-2}", - "input_type": "int, int | uint, uint | string-ascii, string-ascii | string-utf8, string-utf8 | buff, buff", - "output_type": "int | uint", - "signature": "(mod i1 i2)", - "description": "Returns the integer remainder from integer dividing `i1` by `i2`. In the event of a division by zero, throws a runtime error.", - "example": "(mod 2 3) ;; Returns 2\n(mod 5 2) ;; Returns 1\n(mod 7 1) ;; Returns 0\n", - "version": "Clarity1" - }, - { - "name": "nft-burn?", - "snippet": "nft-burn? ${1:asset-name} ${2:asset-identifier} ${3:sender}", - "input_type": "AssetName, A, principal", - "output_type": "(response bool uint)", - "signature": "(nft-burn? asset-class asset-identifier sender)", - "description": "`nft-burn?` is used to burn an asset that the `sender` principal owns.\nThe asset must have been defined using `define-non-fungible-token`, and the supplied \n`asset-identifier` must be of the same type specified in that definition.\n\nOn a successful burn, it returns `(ok true)`. In the event of an unsuccessful burn it\nreturns one of the following error codes:\n\n`(err u1)` -- `sender` does not own the specified asset\n`(err u3)` -- the asset specified by `asset-identifier` does not exist\n", - "example": "\n(define-non-fungible-token stackaroo (string-ascii 40))\n(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true)\n(nft-burn? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true)\n", - "version": "Clarity1" - }, - { - "name": "nft-get-owner?", - "snippet": "nft-get-owner? ${1:asset-name} ${2:asset-identifier}", - "input_type": "AssetName, A", - "output_type": "(optional principal)", - "signature": "(nft-get-owner? asset-class asset-identifier)", - "description": "`nft-get-owner?` returns the owner of an asset, identified by `asset-identifier`, or `none` if the asset does not exist.\nThe asset type must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in\nthat definition.", - "example": "\n(define-non-fungible-token stackaroo (string-ascii 40))\n(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF)\n(nft-get-owner? stackaroo \"Roo\") ;; Returns (some SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF)\n(nft-get-owner? stackaroo \"Too\") ;; Returns none\n", - "version": "Clarity1" - }, - { - "name": "nft-mint?", - "snippet": "nft-mint? ${1:asset-name} ${2:asset-identifier} ${3:recipient}", - "input_type": "AssetName, A, principal", - "output_type": "(response bool uint)", - "signature": "(nft-mint? asset-class asset-identifier recipient)", - "description": "`nft-mint?` is used to instantiate an asset and set that asset's owner to the `recipient` principal.\nThe asset must have been defined using `define-non-fungible-token`, and the supplied `asset-identifier` must be of the same type specified in\nthat definition.\n\nIf an asset identified by `asset-identifier` _already exists_, this function will return an error with the following error code:\n\n`(err u1)`\n\nOtherwise, on successfuly mint, it returns `(ok true)`.\n", - "example": "\n(define-non-fungible-token stackaroo (string-ascii 40))\n(nft-mint? stackaroo \"Roo\" 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true)\n", - "version": "Clarity1" - }, - { - "name": "nft-transfer?", - "snippet": "nft-transfer? ${1:asset-name} ${2:asset-identifier} ${3:sender} ${4:recipient}", - "input_type": "AssetName, A, principal, principal", - "output_type": "(response bool uint)", - "signature": "(nft-transfer? asset-class asset-identifier sender recipient)", - "description": "`nft-transfer?` is used to change the owner of an asset identified by `asset-identifier`\nfrom `sender` to `recipient`. The `asset-class` must have been defined by `define-non-fungible-token` and `asset-identifier`\nmust be of the type specified in that definition. In contrast to `stx-transfer?`, any user can transfer the asset. \nWhen used, relevant guards need to be added.\n\nThis function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns\none of the following error codes:\n\n`(err u1)` -- `sender` does not own the asset\n`(err u2)` -- `sender` and `recipient` are the same principal\n`(err u3)` -- asset identified by asset-identifier does not exist\n", - "example": "\n(define-non-fungible-token stackaroo (string-ascii 40))\n(nft-mint? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)\n(nft-transfer? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (ok true)\n(nft-transfer? stackaroo \"Roo\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u1)\n(nft-transfer? stackaroo \"Stacka\" 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF) ;; Returns (err u3)\n", - "version": "Clarity1" - }, - { - "name": "not", - "snippet": "not ${1:expr-1}", - "input_type": "bool", - "output_type": "bool", - "signature": "(not b1)", - "description": "Returns the inverse of the boolean input.", - "example": "(not true) ;; Returns false\n(not (is-eq 1 2)) ;; Returns true\n", - "version": "Clarity1" - }, - { - "name": "ok", - "snippet": "ok ${1:value}", - "input_type": "A", - "output_type": "(response A B)", - "signature": "(ok value)", - "description": "The `ok` function constructs a response type from the input value. Use `ok` for\ncreating return values in public functions. An _ok_ value indicates that any database changes during\nthe processing of the function should materialize.", - "example": "(ok 1) ;; Returns (ok 1)", - "version": "Clarity1" - }, - { - "name": "or", - "snippet": "or ${1:expr-1} ${2:expr-2}", - "input_type": "bool, ...", - "output_type": "bool", - "signature": "(or b1 b2 ...)", - "description": "Returns `true` if any boolean inputs are `true`. Importantly, the supplied arguments are \nevaluated in-order and lazily. Lazy evaluation means that if one of the arguments returns `true`, the function \nshort-circuits, and no subsequent arguments are evaluated.", - "example": "(or true false) ;; Returns true\n(or (is-eq (+ 1 2) 1) (is-eq 4 4)) ;; Returns true\n(or (is-eq (+ 1 2) 1) (is-eq 3 4)) ;; Returns false\n(or (is-eq (+ 1 2) 3) (is-eq 4 4)) ;; Returns true\n", - "version": "Clarity1" - }, - { - "name": "pow", - "snippet": "pow ${1:expr-1} ${2:expr-2}", - "input_type": "int, int | uint, uint | string-ascii, string-ascii | string-utf8, string-utf8 | buff, buff", - "output_type": "int | uint", - "signature": "(pow i1 i2)", - "description": "Returns the result of raising `i1` to the power of `i2`. In the event of an _overflow_, throws a runtime error.\nNote: Corner cases are handled with the following rules:\n * if both `i1` and `i2` are `0`, return `1`\n * if `i1` is `1`, return `1`\n * if `i1` is `0`, return `0`\n * if `i2` is `1`, return `i1`\n * if `i2` is negative or greater than `u32::MAX`, throw a runtime error", - "example": "(pow 2 3) ;; Returns 8\n(pow 2 2) ;; Returns 4\n(pow 7 1) ;; Returns 7\n", - "version": "Clarity1" - }, - { - "name": "principal-construct?", - "snippet": "principal-construct? ${1:version} ${2:pub-key-hash}", - "input_type": "(buff 1), (buff 20), [(string-ascii 40)]", - "output_type": "(response principal { error_code: uint, principal: (option principal) })", - "signature": "(principal-construct? (buff 1) (buff 20) [(string-ascii 40)])", - "description": "A principal value represents either a set of keys, or a smart contract.\nThe former, called a _standard principal_,\nis encoded as a `(buff 1)` *version byte*, indicating the type of account\nand the type of network that this principal can spend tokens on,\nand a `(buff 20)` *public key hash*, characterizing the principal's unique identity.\nThe latter, a _contract principal_, is encoded as a standard principal concatenated with\na `(string-ascii 40)` *contract name* that identifies the code body.\n\nThe `principal-construct?` function allows users to create either standard or contract principals,\ndepending on which form is used. To create a standard principal, \n`principal-construct?` would be called with two arguments: it\ntakes as input a `(buff 1)` which encodes the principal address's\n`version-byte`, a `(buff 20)` which encodes the principal address's `hash-bytes`.\nTo create a contract principal, `principal-construct?` would be called with\nthree arguments: the `(buff 1)` and `(buff 20)` to represent the standard principal\nthat created the contract, and a `(string-ascii 40)` which encodes the contract's name.\nOn success, this function returns either a standard principal or contract principal, \ndepending on whether or not the third `(string-ascii 40)` argument is given.\n\nThis function returns a `Response`. On success, the `ok` value is a `Principal`.\nThe `err` value is a value tuple with the form `{ error_code: uint, value: (optional principal) }`.\n\nIf the single-byte `version-byte` is in the valid range `0x00` to `0x1f`, but is not an appropriate\nversion byte for the current network, then the error will be `u0`, and `value` will contain\n`(some principal)`, where the wrapped value is the principal. If the `version-byte` is not in this range, \nhowever, then the `value` will be `none`.\n\nIf the `version-byte` is a `buff` of length 0, if the single-byte `version-byte` is a\nvalue greater than `0x1f`, or the `hash-bytes` is a `buff` of length not equal to 20, then `error_code`\nwill be `u1` and `value` will be `None`.\n\nIf a name is given, and the name is either an empty string or contains ASCII characters\nthat are not allowed in contract names, then `error_code` will be `u2`.\n\nNote: This function is only available starting with Stacks 2.1.", - "example": "\n(principal-construct? 0x1a 0xfa6bf38ed557fe417333710d6033e9419391a320) ;; Returns (ok ST3X6QWWETNBZWGBK6DRGTR1KX50S74D3425Q1TPK)\n(principal-construct? 0x1a 0xfa6bf38ed557fe417333710d6033e9419391a320 \"foo\") ;; Returns (ok ST3X6QWWETNBZWGBK6DRGTR1KX50S74D3425Q1TPK.foo)\n(principal-construct? 0x16 0xfa6bf38ed557fe417333710d6033e9419391a320) ;; Returns (err (tuple (error_code u0) (value (some SP3X6QWWETNBZWGBK6DRGTR1KX50S74D3433WDGJY))))\n(principal-construct? 0x16 0xfa6bf38ed557fe417333710d6033e9419391a320 \"foo\") ;; Returns (err (tuple (error_code u0) (value (some SP3X6QWWETNBZWGBK6DRGTR1KX50S74D3433WDGJY.foo))))\n(principal-construct? 0x 0xfa6bf38ed557fe417333710d6033e9419391a320) ;; Returns (err (tuple (error_code u1) (value none)))\n(principal-construct? 0x16 0xfa6bf38ed557fe417333710d6033e9419391a3) ;; Returns (err (tuple (error_code u1) (value none)))\n(principal-construct? 0x20 0xfa6bf38ed557fe417333710d6033e9419391a320) ;; Returns (err (tuple (error_code u1) (value none)))\n(principal-construct? 0x1a 0xfa6bf38ed557fe417333710d6033e9419391a320 \"\") ;; Returns (err (tuple (error_code u2) (value none)))\n(principal-construct? 0x1a 0xfa6bf38ed557fe417333710d6033e9419391a320 \"foo[\") ;; Returns (err (tuple (error_code u2) (value none)))\n", - "version": "Clarity2" - }, - { - "name": "principal-destruct?", - "snippet": "principal-destruct? ${1:principal-address}", - "input_type": "principal", - "output_type": "(response (tuple (hash-bytes (buff 20)) (name (optional (string-ascii 40))) (version (buff 1))) (tuple (hash-bytes (buff 20)) (name (optional (string-ascii 40))) (version (buff 1))))", - "signature": "(principal-destruct? principal-address)", - "description": "A principal value represents either a set of keys, or a smart contract.\nThe former, called a _standard principal_,\nis encoded as a `(buff 1)` *version byte*, indicating the type of account\nand the type of network that this principal can spend tokens on,\nand a `(buff 20)` *public key hash*, characterizing the principal's unique identity.\nThe latter, a _contract principal_, is encoded as a standard principal concatenated with\na `(string-ascii 40)` *contract name* that identifies the code body.\n\n`principal-destruct?` will decompose a principal into its component parts: either`{version-byte, hash-bytes}`\nfor standard principals, or `{version-byte, hash-bytes, name}` for contract principals.\n\nThis method returns a `Response` that wraps this data as a tuple.\n\nIf the version byte of `principal-address` matches the network (see `is-standard`), then this method\nreturns the pair as its `ok` value.\n\nIf the version byte of `principal-address` does not match the network, then this method\nreturns the pair as its `err` value.\n\nIn both cases, the value itself is a tuple containing three fields: a `version` value as a `(buff 1)`,\na `hash-bytes` value as a `(buff 20)`, and a `name` value as an `(optional (string-ascii 40))`. The `name`\nfield will only be `(some ..)` if the principal is a contract principal.\n\nNote: This function is only available starting with Stacks 2.1.", - "example": "\n(principal-destruct? 'STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6) ;; Returns (ok (tuple (hash-bytes 0x164247d6f2b425ac5771423ae6c80c754f7172b0) (name none) (version 0x1a)))\n(principal-destruct? 'STB44HYPYAT2BB2QE513NSP81HTMYWBJP02HPGK6.foo) ;; Returns (ok (tuple (hash-bytes 0x164247d6f2b425ac5771423ae6c80c754f7172b0) (name (some \"foo\")) (version 0x1a)))\n(principal-destruct? 'SP3X6QWWETNBZWGBK6DRGTR1KX50S74D3433WDGJY) ;; Returns (err (tuple (hash-bytes 0xfa6bf38ed557fe417333710d6033e9419391a320) (name none) (version 0x16)))\n(principal-destruct? 'SP3X6QWWETNBZWGBK6DRGTR1KX50S74D3433WDGJY.foo) ;; Returns (err (tuple (hash-bytes 0xfa6bf38ed557fe417333710d6033e9419391a320) (name (some \"foo\")) (version 0x16)))\n", - "version": "Clarity2" - }, - { - "name": "principal-of?", - "snippet": "principal-of? ${1:public-key}", - "input_type": "(buff 33)", - "output_type": "(response principal uint)", - "signature": "(principal-of? public-key)", - "description": "The `principal-of?` function returns the principal derived from the provided public key.\n If the `public-key` is invalid, it will return the error code `(err u1).`.\n\nNote: Before Stacks 2.1, this function has a bug, in that the principal returned would always\nbe a testnet single-signature principal, even if the function were run on the mainnet. Starting\nwith Stacks 2.1, this bug is fixed, so that this function will return a principal suited to\nthe network it is called on. In particular, if this is called on the mainnet, it will\nreturn a single-signature mainnet principal.\n ", - "example": "(principal-of? 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns (ok ST1AW6EKPGT61SQ9FNVDS17RKNWT8ZP582VF9HSCP)", - "version": "Clarity1" - }, - { - "name": "print", - "snippet": "print ${1:expr}", - "input_type": "A", - "output_type": "A", - "signature": "(print expr)", - "description": "The `print` function evaluates and returns its input expression. On Stacks Core\nnodes configured for development (as opposed to production mining nodes), this function prints the resulting value to `STDOUT` (standard output).", - "example": "(print (+ 1 2 3)) ;; Returns 6", - "version": "Clarity1" - }, - { - "name": "replace-at?", - "snippet": "replace-at? ${1:sequence} ${2:index} ${3:element}", - "input_type": "sequence_A, uint, A", - "output_type": "(optional sequence_A)", - "signature": "(replace-at? sequence index element)", - "description": "The `replace-at?` function takes in a sequence, an index, and an element,\nand returns a new sequence with the data at the index position replaced with the given element. \nThe given element's type must match the type of the sequence, and must correspond to a single \nindex of the input sequence. The return type on success is the same type as the input sequence.\n\nIf the provided index is out of bounds, this functions returns `none`.\n", - "example": "\n(replace-at? u\"ab\" u1 u\"c\") ;; Returns (some u\"ac\")\n(replace-at? 0x00112233 u2 0x44) ;; Returns (some 0x00114433)\n(replace-at? \"abcd\" u3 \"e\") ;; Returns (some \"abce\")\n(replace-at? (list 1) u0 10) ;; Returns (some (10))\n(replace-at? (list (list 1) (list 2)) u0 (list 33)) ;; Returns (some ((33) (2)))\n(replace-at? (list 1 2) u3 4) ;; Returns none\n", - "version": "Clarity2" - }, - { - "name": "secp256k1-recover?", - "snippet": "secp256k1-recover? ${1:message-hash} ${2:signature}", - "input_type": "(buff 32), (buff 65)", - "output_type": "(response (buff 33) uint)", - "signature": "(secp256k1-recover? message-hash signature)", - "description": "The `secp256k1-recover?` function recovers the public key used to sign the message which sha256 is `message-hash`\n with the provided `signature`.\n If the signature does not match, it will return the error code `(err u1).`.\n If the signature is invalid, it will return the error code `(err u2).`.\n The signature includes 64 bytes plus an additional recovery id (00..03) for a total of 65 bytes.", - "example": "(secp256k1-recover? 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04\n 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a1301)\n ;; Returns (ok 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110)", - "version": "Clarity1" - }, - { - "name": "secp256k1-verify", - "snippet": "secp256k1-verify ${1:message-hash} ${2:signature} ${3:public-key})", - "input_type": "(buff 32), (buff 64) | (buff 65), (buff 33)", - "output_type": "bool", - "signature": "(secp256k1-verify message-hash signature public-key)", - "description": "The `secp256k1-verify` function verifies that the provided signature of the message-hash\nwas signed with the private key that generated the public key.\nThe `message-hash` is the `sha256` of the message.\nThe signature includes 64 bytes plus an optional additional recovery id (00..03) for a total of 64 or 65 bytes.", - "example": "(secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04\n 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a1301\n 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns true\n(secp256k1-verify 0xde5b9eb9e7c5592930eb2e30a01369c36586d872082ed8181ee83d2a0ec20f04\n 0x8738487ebe69b93d8e51583be8eee50bb4213fc49c767d329632730cc193b873554428fc936ca3569afc15f1c9365f6591d6251a89fee9c9ac661116824d3a13\n 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns true\n(secp256k1-verify 0x0000000000000000000000000000000000000000000000000000000000000000\n 0x0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000\n 0x03adb8de4bfb65db2cfd6120d55c6526ae9c52e675db7e47308636534ba7786110) ;; Returns false", - "version": "Clarity1" - }, - { - "name": "sha256", - "snippet": "sha256 ${1:buff}", - "input_type": "buff|uint|int", - "output_type": "(buff 32)", - "signature": "(sha256 value)", - "description": "The `sha256` function computes `SHA256(x)` of the inputted value.\nIf an integer (128 bit) is supplied the hash is computed over the little-endian representation of the\ninteger.", - "example": "(sha256 0) ;; Returns 0x374708fff7719dd5979ec875d56cd2286f6d3cf7ec317a3b25632aab28ec37bb", - "version": "Clarity1" - }, - { - "name": "sha512", - "snippet": "sha512 ${1:buff}", - "input_type": "buff|uint|int", - "output_type": "(buff 64)", - "signature": "(sha512 value)", - "description": "The `sha512` function computes `SHA512(x)` of the inputted value.\nIf an integer (128 bit) is supplied the hash is computed over the little-endian representation of the\ninteger.", - "example": "(sha512 1) ;; Returns 0x6fcee9a7b7a7b821d241c03c82377928bc6882e7a08c78a4221199bfa220cdc55212273018ee613317c8293bb8d1ce08d1e017508e94e06ab85a734c99c7cc34", - "version": "Clarity1" - }, - { - "name": "sha512/256", - "snippet": "sha512/256 ${1:buff}", - "input_type": "buff|uint|int", - "output_type": "(buff 32)", - "signature": "(sha512/256 value)", - "description": "The `sha512/256` function computes `SHA512/256(x)` (the SHA512 algorithm with the 512/256 initialization vector, truncated\nto 256 bits) of the inputted value.\nIf an integer (128 bit) is supplied the hash is computed over the little-endian representation of the\ninteger.", - "example": "(sha512/256 1) ;; Returns 0x515a7e92e7c60522db968d81ff70b80818fc17aeabbec36baf0dda2812e94a86", - "version": "Clarity1" - }, - { - "name": "slice?", - "snippet": "slice? ${1:sequence} ${2:left-pos} ${3:right-pos}", - "input_type": "sequence_A, uint, uint", - "output_type": "(optional sequence_A)", - "signature": "(slice? sequence left-position right-position)", - "description": "The `slice?` function attempts to return a sub-sequence of that starts at `left-position` (inclusive), and\nends at `right-position` (non-inclusive).\nIf `left_position`==`right_position`, the function returns an empty sequence.\nIf either `left_position` or `right_position` are out of bounds OR if `right_position` is less than\n`left_position`, the function returns `none`.", - "example": "(slice? \"blockstack\" u5 u10) ;; Returns (some \"stack\")\n(slice? (list 1 2 3 4 5) u5 u9) ;; Returns none\n(slice? (list 1 2 3 4 5) u3 u4) ;; Returns (some (4))\n(slice? \"abcd\" u1 u3) ;; Returns (some \"bc\")\n(slice? \"abcd\" u2 u2) ;; Returns (some \"\")\n(slice? \"abcd\" u3 u1) ;; Returns none\n", - "version": "Clarity2" - }, - { - "name": "some", - "snippet": "some ${1:value}", - "input_type": "A", - "output_type": "(optional A)", - "signature": "(some value)", - "description": "The `some` function constructs a `optional` type from the input value.", - "example": "(some 1) ;; Returns (some 1)\n(is-none (some 2)) ;; Returns false", - "version": "Clarity1" - }, - { - "name": "sqrti", - "snippet": "sqrti ${1:expr-1}", - "input_type": "int | uint", - "output_type": "int | uint", - "signature": "(sqrti n)", - "description": "Returns the largest integer that is less than or equal to the square root of `n`. \nFails on a negative numbers.\n", - "example": "(sqrti u11) ;; Returns u3\n(sqrti 1000000) ;; Returns 1000\n(sqrti u1) ;; Returns u1\n(sqrti 0) ;; Returns 0\n", - "version": "Clarity1" - }, - { - "name": "string-to-int?", - "snippet": "string-to-int? ${1:string}", - "input_type": "(string-ascii 1048576) | (string-utf8 262144)", - "output_type": "(optional int)", - "signature": "(string-to-int? (string-ascii|string-utf8))", - "description": "Converts a string, either `string-ascii` or `string-utf8`, to an optional-wrapped signed integer.\nIf the input string does not represent a valid integer, then the function returns `none`. Otherwise it returns\nan integer wrapped in `some`.\n\nNote: This function is only available starting with Stacks 2.1.", - "example": "\n(string-to-int? \"1\") ;; Returns (some 1)\n(string-to-int? u\"-1\") ;; Returns (some -1)\n(string-to-int? \"a\") ;; Returns none\n", - "version": "Clarity2" - }, - { - "name": "string-to-uint?", - "snippet": "string-to-uint? ${1:string}", - "input_type": "(string-ascii 1048576) | (string-utf8 262144)", - "output_type": "(optional uint)", - "signature": "(string-to-uint? (string-ascii|string-utf8))", - "description": "Converts a string, either `string-ascii` or `string-utf8`, to an optional-wrapped unsigned integer.\nIf the input string does not represent a valid integer, then the function returns `none`. Otherwise it returns\nan unsigned integer wrapped in `some`.\n\nNote: This function is only available starting with Stacks 2.1.", - "example": "\n(string-to-uint? \"1\") ;; Returns (some u1)\n(string-to-uint? u\"1\") ;; Returns (some u1)\n(string-to-uint? \"a\") ;; Returns none\n", - "version": "Clarity2" - }, - { - "name": "stx-account", - "snippet": "stx-account ${1:owner}", - "input_type": "principal", - "output_type": "(tuple (locked uint) (unlock-height uint) (unlocked uint))", - "signature": "(stx-account owner)", - "description": "`stx-account` is used to query the STX account of the `owner` principal.\n\nThis function returns a tuple with the canonical account representation for an STX account.\nThis includes the current amount of unlocked STX, the current amount of locked STX, and the\nunlock height for any locked STX, all denominated in microstacks.\n", - "example": "\n(stx-account 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns (tuple (locked u0) (unlock-height u0) (unlocked u0))\n(stx-account (as-contract tx-sender)) ;; Returns (tuple (locked u0) (unlock-height u0) (unlocked u1000))\n", - "version": "Clarity2" - }, - { - "name": "stx-burn?", - "snippet": "stx-burn? ${1:amount} ${2:sender}", - "input_type": "uint, principal", - "output_type": "(response bool uint)", - "signature": "(stx-burn? amount sender)", - "description": "`stx-burn?` decreases the `sender` principal's STX holdings by `amount`,\nspecified in microstacks, by destroying the STX. The `sender` principal _must_ be equal to the current\ncontext's `tx-sender`.\n\nThis function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns\none of the following error codes:\n\n`(err u1)` -- `sender` does not have enough balance to transfer\n`(err u3)` -- amount to send is non-positive\n`(err u4)` -- the `sender` principal is not the current `tx-sender`\n", - "example": "\n(as-contract\n (stx-burn? u60 tx-sender)) ;; Returns (ok true)\n(as-contract\n (stx-burn? u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (err u4)\n", - "version": "Clarity1" - }, - { - "name": "stx-get-balance", - "snippet": "stx-get-balance ${1:owner}", - "input_type": "principal", - "output_type": "uint", - "signature": "(stx-get-balance owner)", - "description": "`stx-get-balance` is used to query the STX balance of the `owner` principal.\n\nThis function returns the STX balance, in microstacks (1 STX = 1,000,000 microstacks), of the\n`owner` principal. In the event that the `owner` principal isn't materialized, it returns 0.\n", - "example": "\n(stx-get-balance 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns u0\n(stx-get-balance (as-contract tx-sender)) ;; Returns u1000\n", - "version": "Clarity1" - }, - { - "name": "stx-transfer-memo?", - "snippet": "stx-transfer-memo? ${1:amount} ${2:sender} ${3:recipient} ${4:memo}", - "input_type": "uint, principal, principal, buff", - "output_type": "(response bool uint)", - "signature": "(stx-transfer-memo? amount sender recipient memo)", - "description": "`stx-transfer-memo?` is similar to `stx-transfer?`, except that it adds a `memo` field. \n\nThis function returns (ok true) if the transfer is successful, or, on an error, returns the same codes as `stx-transfer?`.\n", - "example": "\n(as-contract\n (stx-transfer-memo? u60 tx-sender 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR 0x010203)) ;; Returns (ok true)\n", - "version": "Clarity2" - }, - { - "name": "stx-transfer?", - "snippet": "stx-transfer? ${1:amount} ${2:sender} ${3:recipient}", - "input_type": "uint, principal, principal, buff", - "output_type": "(response bool uint)", - "signature": "(stx-transfer? amount sender recipient)", - "description": "`stx-transfer?` is used to increase the STX balance for the `recipient` principal\nby debiting the `sender` principal by `amount`, specified in microstacks. The `sender` principal\n _must_ be equal to the current context's `tx-sender`.\n\nThis function returns (ok true) if the transfer is successful. In the event of an unsuccessful transfer it returns\none of the following error codes:\n\n`(err u1)` -- `sender` does not have enough balance to transfer\n`(err u2)` -- `sender` and `recipient` are the same principal\n`(err u3)` -- amount to send is non-positive\n`(err u4)` -- the `sender` principal is not the current `tx-sender`\n", - "example": "\n(as-contract\n (stx-transfer? u60 tx-sender 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (ok true)\n(as-contract\n (stx-transfer? u60 tx-sender 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR)) ;; Returns (ok true)\n(as-contract\n (stx-transfer? u50 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR tx-sender)) ;; Returns (err u4)\n", - "version": "Clarity1" - }, - { - "name": "to-consensus-buff?", - "snippet": "to-consensus-buff? ${1:value}", - "input_type": "any", - "output_type": "(optional buff)", - "signature": "(to-consensus-buff? value)", - "description": "`to-consensus-buff?` is a special function that will serialize any\nClarity value into a buffer, using the SIP-005 serialization of the\nClarity value. Not all values can be serialized: some value's\nconsensus serialization is too large to fit in a Clarity buffer (this\nis because of the type prefix in the consensus serialization).\n\nIf the value cannot fit as serialized into the maximum buffer size,\nthis returns `none`, otherwise, it will be\n`(some consensus-serialized-buffer)`. During type checking, the\nanalyzed type of the result of this method will be the maximum possible\nconsensus buffer length based on the inferred type of the supplied value.\n", - "example": "\n(to-consensus-buff? 1) ;; Returns (some 0x0000000000000000000000000000000001)\n(to-consensus-buff? u1) ;; Returns (some 0x0100000000000000000000000000000001)\n(to-consensus-buff? true) ;; Returns (some 0x03)\n(to-consensus-buff? false) ;; Returns (some 0x04)\n(to-consensus-buff? none) ;; Returns (some 0x09)\n(to-consensus-buff? 'SZ2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKQ9H6DPR) ;; Returns (some 0x051fa46ff88886c2ef9762d970b4d2c63678835bd39d)\n(to-consensus-buff? { abc: 3, def: 4 }) ;; Returns (some 0x0c00000002036162630000000000000000000000000000000003036465660000000000000000000000000000000004)\n", - "version": "Clarity2" - }, - { - "name": "to-int", - "snippet": "to-int ${1:uint}", - "input_type": "uint", - "output_type": "int", - "signature": "(to-int u)", - "description": "Tries to convert the `uint` argument to an `int`. Will cause a runtime error and abort if the supplied argument is >= `pow(2, 127)`", - "example": "(to-int u238) ;; Returns 238", - "version": "Clarity1" - }, - { - "name": "to-uint", - "snippet": "to-uint ${1:int}", - "input_type": "int", - "output_type": "uint", - "signature": "(to-uint i)", - "description": "Tries to convert the `int` argument to a `uint`. Will cause a runtime error and abort if the supplied argument is negative.", - "example": "(to-uint 238) ;; Returns u238", - "version": "Clarity1" - }, - { - "name": "try!", - "snippet": "try! ${1:algebraic-expr}", - "input_type": "(optional A) | (response A B)", - "output_type": "A", - "signature": "(try! option-input)", - "description": "The `try!` function attempts to 'unpack' the first argument: if the argument is\nan option type, and the argument is a `(some ...)` option, `try!` returns the inner value of the\noption. If the argument is a response type, and the argument is an `(ok ...)` response, `try!` returns\n the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `none` value,\n`try!` _returns_ either `none` or the `(err ...)` value from the current function and exits the current control-flow.", - "example": "\n(define-map names-map { name: (string-ascii 12) } { id: int })\n(map-set names-map { name: \"blockstack\" } { id: 1337 })\n(try! (map-get? names-map { name: \"blockstack\" })) ;; Returns (tuple (id 1337))\n(define-private (checked-even (x int))\n (if (is-eq (mod x 2) 0)\n (ok x)\n (err false)))\n(define-private (double-if-even (x int))\n (ok (* 2 (try! (checked-even x)))))\n(double-if-even 10) ;; Returns (ok 20)\n(double-if-even 3) ;; Returns (err false)\n", - "version": "Clarity1" - }, - { - "name": "tuple", - "snippet": "tuple (${1:key-1} ${2:val-1})", - "input_type": "(key-name A), (key-name-2 B), ...", - "output_type": "(tuple (key-name A) (key-name-2 B) ...)", - "signature": "(tuple (key0 expr0) (key1 expr1) ...)", - "description": "The `tuple` special form constructs a typed tuple from the supplied key and expression pairs.\nA `get` function can use typed tuples as input to select specific values from a given tuple.\nKey names may not appear multiple times in the same tuple definition. Supplied expressions are evaluated and\nassociated with the expressions' paired key name.\n\nThere is a shorthand using curly brackets of the form {key0: expr0, key1: expr, ...}", - "example": "(tuple (name \"blockstack\") (id 1337)) ;; using tuple\n {name: \"blockstack\", id: 1337} ;; using curly brackets", - "version": "Clarity1" - }, - { - "name": "unwrap!", - "snippet": "unwrap! ${1:algebraic-expr} (err ${2:thrown})", - "input_type": "(optional A) | (response A B), C", - "output_type": "A", - "signature": "(unwrap! option-input thrown-value)", - "description": "The `unwrap!` function attempts to 'unpack' the first argument: if the argument is\nan option type, and the argument is a `(some ...)` option, `unwrap!` returns the inner value of the\noption. If the argument is a response type, and the argument is an `(ok ...)` response, `unwrap!` returns\n the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `(none)` value,\n`unwrap!` _returns_ `thrown-value` from the current function and exits the current control-flow.", - "example": "\n(define-map names-map { name: (string-ascii 12) } { id: int })\n(map-set names-map { name: \"blockstack\" } { id: 1337 })\n(define-private (get-name-or-err (name (string-ascii 12)))\n (let ((raw-name (unwrap! (map-get? names-map { name: name }) (err 1))))\n (ok raw-name)))\n\n(get-name-or-err \"blockstack\") ;; Returns (ok (tuple (id 1337)))\n(get-name-or-err \"non-existant\") ;; Returns (err 1)", - "version": "Clarity1" - }, - { - "name": "unwrap-err!", - "snippet": "unwrap-err! ${1:algebraic-expr} (err ${2:thrown})", - "input_type": "(response A B), C", - "output_type": "B", - "signature": "(unwrap-err! response-input thrown-value)", - "description": "The `unwrap-err!` function attempts to 'unpack' the first argument: if the argument\nis an `(err ...)` response, `unwrap-err!` returns the inner value of the `err`.\nIf the supplied argument is an `(ok ...)` value,\n`unwrap-err!` _returns_ `thrown-value` from the current function and exits the current control-flow.", - "example": "(unwrap-err! (err 1) false) ;; Returns 1", - "version": "Clarity1" - }, - { - "name": "unwrap-err-panic", - "snippet": "unwrap-err-panic ${1:algebraic-expr}", - "input_type": "(response A B)", - "output_type": "B", - "signature": "(unwrap-err-panic response-input)", - "description": "The `unwrap-err` function attempts to 'unpack' the first argument: if the argument\nis an `(err ...)` response, `unwrap` returns the inner value of the `err`.\nIf the supplied argument is an `(ok ...)` value,\n`unwrap-err` throws a runtime error, aborting any further processing of the current transaction.", - "example": "(unwrap-err-panic (err 1)) ;; Returns 1\n(unwrap-err-panic (ok 1)) ;; Throws a runtime exception", - "version": "Clarity1" - }, - { - "name": "unwrap-panic", - "snippet": "unwrap-panic ${1:algebraic-expr}", - "input_type": "(optional A) | (response A B)", - "output_type": "A", - "signature": "(unwrap-panic option-input)", - "description": "The `unwrap` function attempts to 'unpack' its argument: if the argument is\nan option type, and the argument is a `(some ...)` option, this function returns the inner value of the\noption. If the argument is a response type, and the argument is an `(ok ...)` response, it returns\n the inner value of the `ok`. If the supplied argument is either an `(err ...)` or a `(none)` value,\n`unwrap` throws a runtime error, aborting any further processing of the current transaction.", - "example": "\n(define-map names-map { name: (string-ascii 12) } { id: int })\n(map-set names-map { name: \"blockstack\" } { id: 1337 })\n(unwrap-panic (map-get? names-map { name: \"blockstack\" })) ;; Returns (tuple (id 1337))\n(unwrap-panic (map-get? names-map { name: \"non-existant\" })) ;; Throws a runtime exception\n", - "version": "Clarity1" - }, - { - "name": "use-trait", - "snippet": "use-trait ${1:trait-alias} ${2:trait-identifier}", - "input_type": "VarName, TraitIdentifier", - "output_type": "Not Applicable", - "signature": "(use-trait trait-alias trait-identifier)", - "description": "`use-trait` is used to bring a trait, defined in another contract, to the current contract. Subsequent\nreferences to an imported trait are signaled with the syntax ``.\n\nTraits import are defined with a name, used as an alias, and a trait identifier. Trait identifiers can either be\nusing the sugared syntax (.token-a.token-trait), or be fully qualified ('SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait).\n\nLike other kinds of definition statements, `use-trait` may only be used at the top level of a smart contract\ndefinition (i.e., you cannot put such a statement in the middle of a function body).\n ", - "example": "\n(use-trait token-a-trait 'SPAXYA5XS51713FDTQ8H94EJ4V579CXMTRNBZKSF.token-a.token-trait)\n(define-public (forward-get-balance (user principal) (contract ))\n (begin\n (ok 1)))\n", - "version": "Clarity1" - }, - { - "name": "var-get", - "snippet": "var-get ${1:var}", - "input_type": "VarName", - "output_type": "A", - "signature": "(var-get var-name)", - "description": "The `var-get` function looks up and returns an entry from a contract's data map.\nThe value is looked up using `var-name`.", - "example": "(define-data-var cursor int 6)\n(var-get cursor) ;; Returns 6", - "version": "Clarity1" - }, - { - "name": "var-set", - "snippet": "var-set ${1:var} ${2:value}", - "input_type": "VarName, AnyType", - "output_type": "bool", - "signature": "(var-set var-name expr1)", - "description": "The `var-set` function sets the value associated with the input variable to the\ninputted value. The function always returns `true`.", - "example": "\n(define-data-var cursor int 6)\n(var-get cursor) ;; Returns 6\n(var-set cursor (+ (var-get cursor) 1)) ;; Returns true\n(var-get cursor) ;; Returns 7", - "version": "Clarity1" - }, - { - "name": "xor", - "snippet": "xor ${1:expr-1} ${2:expr-2}", - "input_type": "int, int | uint, uint | string-ascii, string-ascii | string-utf8, string-utf8 | buff, buff", - "output_type": "int | uint", - "signature": "(xor i1 i2)", - "description": "Returns the result of bitwise exclusive or'ing `i1` with `i2`.", - "example": "(xor 1 2) ;; Returns 3\n(xor 120 280) ;; Returns 352\n", - "version": "Clarity1" - } - ], - "keywords": [ - { - "name": "block-height", - "snippet": "block-height", - "output_type": "uint", - "description": "Returns the current block height of the Stacks blockchain as an uint", - "example": "(> block-height 1000) ;; returns true if the current block-height has passed 1000 blocks.", - "version": "Clarity1" - }, - { - "name": "burn-block-height", - "snippet": "burn-block-height", - "output_type": "uint", - "description": "Returns the current block height of the underlying burn blockchain as a uint", - "example": "(> burn-block-height 1000) ;; returns true if the current height of the underlying burn blockchain has passed 1000 blocks.", - "version": "Clarity1" - }, - { - "name": "chain-id", - "snippet": "chain-id", - "output_type": "uint", - "description": "Returns the 32-bit chain ID of the blockchain running this transaction", - "example": "(print chain-id) ;; Will print 'u1' if the code is running on mainnet, and 'u2147483648' on testnet, and other values on different chains.", - "version": "Clarity2" - }, - { - "name": "contract-caller", - "snippet": "contract-caller", - "output_type": "principal", - "description": "Returns the caller of the current contract context. If this contract is the first one called by a signed transaction,\nthe caller will be equal to the signing principal. If `contract-call?` was used to invoke a function from a new contract, `contract-caller`\nchanges to the _calling_ contract's principal. If `as-contract` is used to change the `tx-sender` context, `contract-caller` _also_ changes\nto the same contract principal.", - "example": "(print contract-caller) ;; Will print out a Stacks address of the transaction sender", - "version": "Clarity1" - }, - { - "name": "false", - "snippet": "false", - "output_type": "bool", - "description": "Boolean false constant.", - "example": "\n(and true false) ;; Evaluates to false\n(or false true) ;; Evaluates to true\n", - "version": "Clarity1" - }, - { - "name": "is-in-mainnet", - "snippet": "is-in-mainnet", - "output_type": "bool", - "description": "Returns a boolean indicating whether or not the code is running on the mainnet", - "example": "(print is-in-mainnet) ;; Will print 'true' if the code is running on the mainnet", - "version": "Clarity2" - }, - { - "name": "is-in-regtest", - "snippet": "is-in-regtest", - "output_type": "bool", - "description": "Returns whether or not the code is running in a regression test", - "example": "(print is-in-regtest) ;; Will print 'true' if the code is running in a regression test", - "version": "Clarity1" - }, - { - "name": "none", - "snippet": "none", - "output_type": "(optional ?)", - "description": "Represents the _none_ option indicating no value for a given optional (analogous to a null value).", - "example": "\n(define-public (only-if-positive (a int))\n (if (> a 0)\n (some a)\n none))\n(only-if-positive 4) ;; Returns (some 4)\n(only-if-positive (- 3)) ;; Returns none\n", - "version": "Clarity1" - }, - { - "name": "stx-liquid-supply", - "snippet": "stx-liquid-supply", - "output_type": "uint", - "description": "Returns the total number of micro-STX (uSTX) that are liquid in the system as of this block.", - "example": "(print stx-liquid-supply) ;; Will print out the total number of liquid uSTX", - "version": "Clarity1" - }, - { - "name": "true", - "snippet": "true", - "output_type": "bool", - "description": "Boolean true constant.", - "example": "\n(and true false) ;; Evaluates to false\n(or false true) ;; Evaluates to true\n", - "version": "Clarity1" - }, - { - "name": "tx-sender", - "snippet": "tx-sender", - "output_type": "principal", - "description": "Returns the original sender of the current transaction, or if `as-contract` was called to modify the sending context, it returns that\ncontract principal.", - "example": "(print tx-sender) ;; Will print out a Stacks address of the transaction sender", - "version": "Clarity1" - }, - { - "name": "tx-sponsor?", - "snippet": "tx-sponsor?", - "output_type": "optional principal", - "description": "Returns the sponsor of the current transaction if there is a sponsor, otherwise returns None.", - "example": "(print tx-sponsor?) ;; Will print out an optional value containing the Stacks address of the transaction sponsor", - "version": "Clarity2" - } - ] -} diff --git a/src/components/ApiReferences/FunctionsReferences.jsx b/src/components/ApiReferences/FunctionsReferences.jsx deleted file mode 100644 index ff0c8d9e59..0000000000 --- a/src/components/ApiReferences/FunctionsReferences.jsx +++ /dev/null @@ -1,51 +0,0 @@ -import React from "react"; -import { ReactMarkdown } from "react-markdown/lib/react-markdown"; -import CodeBlock from "@theme/CodeBlock"; -import MDXContent from "@theme/MDXContent"; -import MDXHeading from "@theme/MDXComponents/Heading"; - -import { nameToId } from "./_helpers"; -import { functions } from "../../_data/clarity-reference.json"; - -export const FunctionsReferences = ({ toc }) => { - return functions.sort().map((func) => { - const id = nameToId(func.name, func.version); - // ugly hack to customize table of content from non-markdown content - // https://github.com/facebook/docusaurus/issues/6201 - const value = func.name.replace(">", ">").replace("<", "<"); - if (!toc.find((t) => t.id === id)) toc.push({ id, level: 3, value }); - return ; - }); -}; - -const FunctionReference = ({ id, func }) => { - return ( - - - {func.name} - - -

- Introduced in: {func.version.replace("Clarity", "Clarity ")} -

- -

- input: {func.input_type} -

- -

- output: {func.output_type} -

- -

- signature: {func.signature} -

- -

description:

- {func.description} - -

example:

- {func.example.trim()} -
- ); -}; diff --git a/src/components/ApiReferences/KeywordsReferences.jsx b/src/components/ApiReferences/KeywordsReferences.jsx deleted file mode 100644 index 971d20ad2a..0000000000 --- a/src/components/ApiReferences/KeywordsReferences.jsx +++ /dev/null @@ -1,45 +0,0 @@ -import React from "react"; -import { ReactMarkdown } from "react-markdown/lib/react-markdown"; -import CodeBlock from "@theme/CodeBlock"; -import MDXContent from "@theme/MDXContent"; -import MDXHeading from "@theme/MDXComponents/Heading"; - -import { nameToId } from "./_helpers"; -import { keywords } from "../../_data/clarity-reference.json"; - -export const KeywordsReferences = ({ toc }) => { - return keywords.map((keyword) => { - const id = nameToId(keyword.name, keyword.version); - // ugly hack to customize table of content from non-markdown content - // https://github.com/facebook/docusaurus/issues/6201 - if (!toc.find((t) => t.id === id)) - toc.push({ id, level: 3, value: keyword.name }); - return ; - }); -}; - -const KeywordReference = ({ id, keyword }) => { - return ( - - - {keyword.name} - - -

- Introduced in: {keyword.version.replace("Clarity", "Clarity ")} -

- -

- output: {keyword.output_type} -

- -

description:

- {keyword.description} - -

example:

- - {keyword.example.trim()} - -
- ); -}; diff --git a/src/components/ApiReferences/_helpers.js b/src/components/ApiReferences/_helpers.js deleted file mode 100644 index 25c5e3b945..0000000000 --- a/src/components/ApiReferences/_helpers.js +++ /dev/null @@ -1,6 +0,0 @@ -const idPattern = /[^A-Za-z0-9\-]/g; -export const nameToId = (name, version) => { - let slug = name.trim().replaceAll(" ", "-").replace(idPattern, ""); - let suffix = version === "Clarity1" ? "" : `-${version}`.toLowerCase(); - return `${slug}${suffix}`; -}; diff --git a/src/components/HomepageFeatures/reportWebVitals.js b/src/components/HomepageFeatures/reportWebVitals.js deleted file mode 100644 index ca5bbcf25d..0000000000 --- a/src/components/HomepageFeatures/reportWebVitals.js +++ /dev/null @@ -1,60 +0,0 @@ -import { getCLS, getFCP, getFID, getLCP, getTTFB } from 'web-vitals'; - -const vitalsUrl = 'https://vitals.vercel-analytics.com/v1/vitals'; - -function getConnectionSpeed() { - return 'connection' in navigator && - navigator['connection'] && - 'effectiveType' in navigator['connection'] - ? navigator['connection']['effectiveType'] - : ''; -} - -function sendToAnalytics(metric, options) { - const page = Object.entries(options.params).reduce( - (acc, [key, value]) => acc.replace(value, `[${key}]`), - options.path, - ); - - const body = { - dsn: options.analyticsId, // qPgJqYH9LQX5o31Ormk8iWhCxZO - id: metric.id, // v2-1653884975443-1839479248192 - page, // /blog/[slug] - href: location.href, // https://my-app.vercel.app/blog/my-test - event_name: metric.name, // TTFB - value: metric.value.toString(), // 60.20000000298023 - speed: getConnectionSpeed(), // 4g - }; - - if (options.debug) { - console.log('[Analytics]', metric.name, JSON.stringify(body, null, 2)); - } - - const blob = new Blob([new URLSearchParams(body).toString()], { - // This content type is necessary for `sendBeacon` - type: 'application/x-www-form-urlencoded', - }); - if (navigator.sendBeacon) { - navigator.sendBeacon(vitalsUrl, blob); - } else - fetch(vitalsUrl, { - body: blob, - method: 'POST', - credentials: 'omit', - keepalive: true, - }); -} - -export function webVitals(options) { - console.log('[I WAS CALLED (webVitals)]'); - try { - getFID((metric) => sendToAnalytics(metric, options)); - getTTFB((metric) => sendToAnalytics(metric, options)); - getLCP((metric) => sendToAnalytics(metric, options)); - getCLS((metric) => sendToAnalytics(metric, options)); - getFCP((metric) => sendToAnalytics(metric, options)); - console.error('[Success?]'); - } catch (err) { - console.error('[Analytics]', err); - } -} diff --git a/src/css/custom.css b/src/css/custom.css deleted file mode 100644 index 2bc6a4cfde..0000000000 --- a/src/css/custom.css +++ /dev/null @@ -1,30 +0,0 @@ -/** - * Any CSS included here will be global. The classic template - * bundles Infima by default. Infima is a CSS framework designed to - * work well for content-centric websites. - */ - -/* You can override the default Infima variables here. */ -:root { - --ifm-color-primary: #2e8555; - --ifm-color-primary-dark: #29784c; - --ifm-color-primary-darker: #277148; - --ifm-color-primary-darkest: #205d3b; - --ifm-color-primary-light: #33925d; - --ifm-color-primary-lighter: #359962; - --ifm-color-primary-lightest: #3cad6e; - --ifm-code-font-size: 95%; - --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1); -} - -/* For readability concerns, you should choose a lighter palette in dark mode. */ -[data-theme='dark'] { - --ifm-color-primary: #25c2a0; - --ifm-color-primary-dark: #21af90; - --ifm-color-primary-darker: #1fa588; - --ifm-color-primary-darkest: #1a8870; - --ifm-color-primary-light: #29d5b0; - --ifm-color-primary-lighter: #32d8b4; - --ifm-color-primary-lightest: #4fddbf; - --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3); -} diff --git a/src/pages/index.js b/src/pages/index.js deleted file mode 100644 index 7a6e639b23..0000000000 --- a/src/pages/index.js +++ /dev/null @@ -1,14 +0,0 @@ -import React, { useEffect } from "react"; - -import { webVitals } from "@site/src/components/HomepageFeatures/reportWebVitals"; - -//Added to redirect the main page to the docs -import { Redirect } from "@docusaurus/router"; - -export default function Home() { - useEffect(() => { - webVitals(); - }, []); - - return ; -} diff --git a/src/pages/index.module.css b/src/pages/index.module.css deleted file mode 100644 index 9f71a5da77..0000000000 --- a/src/pages/index.module.css +++ /dev/null @@ -1,23 +0,0 @@ -/** - * CSS files with the .module.css suffix will be treated as CSS modules - * and scoped locally. - */ - -.heroBanner { - padding: 4rem 0; - text-align: center; - position: relative; - overflow: hidden; -} - -@media screen and (max-width: 996px) { - .heroBanner { - padding: 2rem; - } -} - -.buttons { - display: flex; - align-items: center; - justify-content: center; -} diff --git a/src/theme/clarity-prism.js b/src/theme/clarity-prism.js deleted file mode 100644 index 404a5e1ea6..0000000000 --- a/src/theme/clarity-prism.js +++ /dev/null @@ -1,109 +0,0 @@ -// Clarity language definition to add clarity support to prismjs -// from -// https://github.com/hirosystems/stacks-wallet-web/blob/dev/src/app/common/clarity-prism.ts - -function clarity(Prism) { - function primitive(pattern) { - return RegExp(`([\\s([])${pattern}(?=[\\s)])`); - } - - const par = "(\\()"; - const space = "(?=\\s)"; - - Prism.languages.clarity = { - // Three or four semicolons are considered a heading. - heading: { - pattern: /;;;.*/, - alias: ["comment", "title"], - }, - comment: /;;.*/, - string: [ - { - pattern: /"(?:[^"\\]|\\.)*"/, - greedy: true, - }, - { - pattern: /0x[0-9a-fA-F]*/, - greedy: true, - }, - ], - symbol: { - pattern: /'[^()#'\s]+/, - greedy: true, - }, - keyword: [ - { - pattern: RegExp( - `${par}(?:\\+|\\-|/|\\*|>|<|<=|>=|pow|log2|mod|sqrti)${space}` - ), - lookbehind: true, - }, - { - pattern: RegExp( - `${par}(?:default-to|or|and|xor|not|begin|let|if|ok|err|unwrap\!|unwrap-err\!|unwrap-panic|unwrap-err-panic|match|merge|try\!|asserts\!|map-get\\?|var-get|contract-map-get\\?|get|tuple|print|replace-at\\?|secp256k1-recover\\?|secp256k1-verify|slice\\?|some|buff-to-int-be|buff-to-int-le|buff-to-uint-be|buff-to-uint-le|int-to-ascii|int-to-utf8|string-to-int\\?|string-to-uint\\?|element-at|element-at\\?|index-of|index-of\\?|from-consensus-buff\\?|to-consensus-buff\\?|principal-construct\\?|principal-destruct\\?|principal-of\\?|use-trait|impl-trait)${space}` - ), - lookbehind: true, - }, - { - pattern: RegExp( - `${par}(?:define-trait|define-public|define-private|define-constant|define-map|define-data-var|define-fungible-token|define-non-fungible-token|define-read-only)${space}` - ), - lookbehind: true, - }, - { - pattern: RegExp( - `${par}(?:bit-and|bit-not|bit-or|bit-shift-left|bit-shift-right|bit-xor)${space}` - ), - lookbehind: true, - }, - { - pattern: RegExp( - `${par}(?:var-set|map-set|map-delete|map-insert|stx-account|stx-burn\\?|stx-get-balance|stx-transfer-memo\\?|stx-transfer\\?|ft-get-balance|ft-get-supply|ft-transfer\\?|nft-transfer\\?|nft-mint\\?|nft-burn\\?|ft-mint\\?|ft-burn\\?|nft-get-owner\\?|ft-get-balance\\?|contract-call\\?)${space}` - ), - lookbehind: true, - }, - { - pattern: RegExp( - `${par}(?:list|map|filter|fold|len|concat|append|as-max-len\\?|to-int|to-uint|buff|hash160|sha256|sha512|sha512/256|keccak256|none)${space}` - ), - lookbehind: true, - }, - { - pattern: RegExp( - `${par}(?:as-contract|contract-caller|tx-sender|tx-sponsor\\?|block-height|burn-block-height|get-burn-block-info\\?|at-block|get-block-info\\?|stx-liquid-supply|chain-id|is-in-mainnet|is-in-regtest)${space}` - ), - lookbehind: true, - }, - { - pattern: RegExp( - `${par}(?:is-eq|is-some|is-none|is-ok|is-err|is-standard)${space}` - ), - lookbehind: true, - }, - ], - boolean: /(?:false|true)/, - number: { - pattern: primitive("[-]?u?\\d+"), - lookbehind: true, - }, - address: { - pattern: - /([\s()])(?:'[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41})(?=[()\s]|$)/, - lookbehind: true, - }, - operator: { - pattern: /(\()(?:[-+*/]|[<>]=?|=>?)(?=[()\s]|$)/, - lookbehind: true, - }, - function: { - pattern: /(\()[^()'\s]+(?=[()\s]|$)/, - lookbehind: true, - }, - punctuation: /[()']/, - }; -} - -clarity.displayName = "clarity"; -clarity.aliases = ["clar"]; - -export default clarity; diff --git a/src/theme/prism-include-languages.js b/src/theme/prism-include-languages.js deleted file mode 100644 index 81f9893e46..0000000000 --- a/src/theme/prism-include-languages.js +++ /dev/null @@ -1,18 +0,0 @@ -import siteConfig from "@generated/docusaurus.config"; -import clarity from "./clarity-prism"; - -export default function prismIncludeLanguages(PrismObject) { - const { - themeConfig: { prism }, - } = siteConfig; - const { additionalLanguages } = prism; - - globalThis.Prism = PrismObject; - additionalLanguages.forEach((lang) => { - // eslint-disable-next-line global-require, import/no-dynamic-require - require(`prismjs/components/prism-${lang}`); - }); - - clarity(Prism); - delete globalThis.Prism; -} diff --git a/static/.nojekyll b/static/.nojekyll deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/static/img/Bitcoinet-L_2.svg b/static/img/Bitcoinet-L_2.svg deleted file mode 100755 index 7ff242c089..0000000000 --- a/static/img/Bitcoinet-L_2.svg +++ /dev/null @@ -1,9 +0,0 @@ - - - - - - - - - diff --git a/static/img/C++BuildTools.png b/static/img/C++BuildTools.png deleted file mode 100644 index a3f341458f..0000000000 Binary files a/static/img/C++BuildTools.png and /dev/null differ diff --git a/static/img/SBC-L-2x-10.png b/static/img/SBC-L-2x-10.png deleted file mode 100644 index 4472ba8b22..0000000000 Binary files a/static/img/SBC-L-2x-10.png and /dev/null differ diff --git a/static/img/SBC-L-2x-20.png b/static/img/SBC-L-2x-20.png deleted file mode 100644 index 01365fab1e..0000000000 Binary files a/static/img/SBC-L-2x-20.png and /dev/null differ diff --git a/static/img/SBC-L-2x.png b/static/img/SBC-L-2x.png deleted file mode 100755 index ab32a5d2e3..0000000000 Binary files a/static/img/SBC-L-2x.png and /dev/null differ diff --git a/static/img/add-storage.png b/static/img/add-storage.png deleted file mode 100644 index 7553878d03..0000000000 Binary files a/static/img/add-storage.png and /dev/null differ diff --git a/static/img/added-contact.png b/static/img/added-contact.png deleted file mode 100644 index 3b00bb6a38..0000000000 Binary files a/static/img/added-contact.png and /dev/null differ diff --git a/static/img/api_testnet_status.png b/static/img/api_testnet_status.png deleted file mode 100644 index c0f7cb1365..0000000000 Binary files a/static/img/api_testnet_status.png and /dev/null differ diff --git a/static/img/architecture.png b/static/img/architecture.png deleted file mode 100644 index e87b751f04..0000000000 Binary files a/static/img/architecture.png and /dev/null differ diff --git a/static/img/aws-console.png b/static/img/aws-console.png deleted file mode 100644 index dcabda91a5..0000000000 Binary files a/static/img/aws-console.png and /dev/null differ diff --git a/static/img/aws-dns-fields.png b/static/img/aws-dns-fields.png deleted file mode 100644 index aaa31bee58..0000000000 Binary files a/static/img/aws-dns-fields.png and /dev/null differ diff --git a/static/img/aws-hub.png b/static/img/aws-hub.png deleted file mode 100644 index 1b77d6d0c2..0000000000 Binary files a/static/img/aws-hub.png and /dev/null differ diff --git a/static/img/aws-launch-status.png b/static/img/aws-launch-status.png deleted file mode 100644 index ba9f0f33d1..0000000000 Binary files a/static/img/aws-launch-status.png and /dev/null differ diff --git a/static/img/bad-connection.png b/static/img/bad-connection.png deleted file mode 100644 index 16f1706c3f..0000000000 Binary files a/static/img/bad-connection.png and /dev/null differ diff --git a/static/img/btc-stacks.png b/static/img/btc-stacks.png deleted file mode 100644 index cb47827fbd..0000000000 Binary files a/static/img/btc-stacks.png and /dev/null differ diff --git a/static/img/bubble-stacks-plugin.png b/static/img/bubble-stacks-plugin.png deleted file mode 100644 index 323fd5b18b..0000000000 Binary files a/static/img/bubble-stacks-plugin.png and /dev/null differ diff --git a/static/img/cert-check.png b/static/img/cert-check.png deleted file mode 100644 index feb6589e1b..0000000000 Binary files a/static/img/cert-check.png and /dev/null differ diff --git a/static/img/choose-hardware.png b/static/img/choose-hardware.png deleted file mode 100644 index 22d9734b2d..0000000000 Binary files a/static/img/choose-hardware.png and /dev/null differ diff --git a/static/img/cli.svg b/static/img/cli.svg deleted file mode 100644 index 3557bce81c..0000000000 --- a/static/img/cli.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - - - - - - - - - - - diff --git a/static/img/cloudformation-bucket.png b/static/img/cloudformation-bucket.png deleted file mode 100644 index d90821da05..0000000000 Binary files a/static/img/cloudformation-bucket.png and /dev/null differ diff --git a/static/img/cloudformation-create-stack.png b/static/img/cloudformation-create-stack.png deleted file mode 100644 index 2ce5caa644..0000000000 Binary files a/static/img/cloudformation-create-stack.png and /dev/null differ diff --git a/static/img/cloudformation-delete.png b/static/img/cloudformation-delete.png deleted file mode 100644 index 394e90e372..0000000000 Binary files a/static/img/cloudformation-delete.png and /dev/null differ diff --git a/static/img/cloudformation-details.png b/static/img/cloudformation-details.png deleted file mode 100644 index 1fe5f871dd..0000000000 Binary files a/static/img/cloudformation-details.png and /dev/null differ diff --git a/static/img/cloudformation-domain-name.png b/static/img/cloudformation-domain-name.png deleted file mode 100644 index 7fe479cf2f..0000000000 Binary files a/static/img/cloudformation-domain-name.png and /dev/null differ diff --git a/static/img/cloudformation-email.png b/static/img/cloudformation-email.png deleted file mode 100644 index d07e8fbc04..0000000000 Binary files a/static/img/cloudformation-email.png and /dev/null differ diff --git a/static/img/cloudformation-gaia-template1-designer.png b/static/img/cloudformation-gaia-template1-designer.png deleted file mode 100644 index 74ecb16892..0000000000 Binary files a/static/img/cloudformation-gaia-template1-designer.png and /dev/null differ diff --git a/static/img/cloudformation-iam-resources.png b/static/img/cloudformation-iam-resources.png deleted file mode 100644 index 3c1c970a2f..0000000000 Binary files a/static/img/cloudformation-iam-resources.png and /dev/null differ diff --git a/static/img/cloudformation-keyname.png b/static/img/cloudformation-keyname.png deleted file mode 100644 index 5fa44af47e..0000000000 Binary files a/static/img/cloudformation-keyname.png and /dev/null differ diff --git a/static/img/cloudformation-launch-stack-button.png b/static/img/cloudformation-launch-stack-button.png deleted file mode 100644 index 175c2f7b2f..0000000000 Binary files a/static/img/cloudformation-launch-stack-button.png and /dev/null differ diff --git a/static/img/cloudformation-specify-stack-details.png b/static/img/cloudformation-specify-stack-details.png deleted file mode 100644 index 3d8ef2f0f0..0000000000 Binary files a/static/img/cloudformation-specify-stack-details.png and /dev/null differ diff --git a/static/img/cloudformation-specify-template.png b/static/img/cloudformation-specify-template.png deleted file mode 100644 index a39eef1aee..0000000000 Binary files a/static/img/cloudformation-specify-template.png and /dev/null differ diff --git a/static/img/cloudformation-stack-name.png b/static/img/cloudformation-stack-name.png deleted file mode 100644 index 409b7c3ba9..0000000000 Binary files a/static/img/cloudformation-stack-name.png and /dev/null differ diff --git a/static/img/cloudformation-stack-options.png b/static/img/cloudformation-stack-options.png deleted file mode 100644 index 769d60fd59..0000000000 Binary files a/static/img/cloudformation-stack-options.png and /dev/null differ diff --git a/static/img/cloudformation-storage-type.png b/static/img/cloudformation-storage-type.png deleted file mode 100644 index 6d4eb5107a..0000000000 Binary files a/static/img/cloudformation-storage-type.png and /dev/null differ diff --git a/static/img/cloudformation-subnet.png b/static/img/cloudformation-subnet.png deleted file mode 100644 index 988cf9b1d2..0000000000 Binary files a/static/img/cloudformation-subnet.png and /dev/null differ diff --git a/static/img/confirm-send.png b/static/img/confirm-send.png deleted file mode 100644 index 8dcac6d44a..0000000000 Binary files a/static/img/confirm-send.png and /dev/null differ diff --git a/static/img/connect-call-to-action-branding.png b/static/img/connect-call-to-action-branding.png deleted file mode 100644 index e43b54e838..0000000000 Binary files a/static/img/connect-call-to-action-branding.png and /dev/null differ diff --git a/static/img/contacts-manager.png b/static/img/contacts-manager.png deleted file mode 100644 index 8dfc7ea0c2..0000000000 Binary files a/static/img/contacts-manager.png and /dev/null differ diff --git a/static/img/contract-deploy.png b/static/img/contract-deploy.png deleted file mode 100644 index d42a880083..0000000000 Binary files a/static/img/contract-deploy.png and /dev/null differ diff --git a/static/img/contract.svg b/static/img/contract.svg deleted file mode 100644 index eb7a9e71b9..0000000000 --- a/static/img/contract.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - - - - - - - - - - - - - - - - - diff --git a/static/img/copy-authRequest.png b/static/img/copy-authRequest.png deleted file mode 100644 index fe6f4f2ddf..0000000000 Binary files a/static/img/copy-authRequest.png and /dev/null differ diff --git a/static/img/counter-testnet-sandbox.png b/static/img/counter-testnet-sandbox.png deleted file mode 100644 index 3237c9b5c2..0000000000 Binary files a/static/img/counter-testnet-sandbox.png and /dev/null differ diff --git a/static/img/create-space.png b/static/img/create-space.png deleted file mode 100644 index 2094afeb1a..0000000000 Binary files a/static/img/create-space.png and /dev/null differ diff --git a/static/img/crowdin-qa-issue-formatting_tags_missing.png b/static/img/crowdin-qa-issue-formatting_tags_missing.png deleted file mode 100644 index 0cfa2fab25..0000000000 Binary files a/static/img/crowdin-qa-issue-formatting_tags_missing.png and /dev/null differ diff --git a/static/img/crowdin-qa-issue-tag_source.png b/static/img/crowdin-qa-issue-tag_source.png deleted file mode 100644 index f2dd0a4977..0000000000 Binary files a/static/img/crowdin-qa-issue-tag_source.png and /dev/null differ diff --git a/static/img/device-check.png b/static/img/device-check.png deleted file mode 100644 index 9c06d93ac6..0000000000 Binary files a/static/img/device-check.png and /dev/null differ diff --git a/static/img/devnet-interface.png b/static/img/devnet-interface.png deleted file mode 100644 index aaa3853034..0000000000 Binary files a/static/img/devnet-interface.png and /dev/null differ diff --git a/static/img/different-provider.png b/static/img/different-provider.png deleted file mode 100644 index 128f16958c..0000000000 Binary files a/static/img/different-provider.png and /dev/null differ diff --git a/static/img/digital-droplet.png b/static/img/digital-droplet.png deleted file mode 100644 index 090d112f0d..0000000000 Binary files a/static/img/digital-droplet.png and /dev/null differ diff --git a/static/img/digital-one-click.png b/static/img/digital-one-click.png deleted file mode 100644 index 2d69ed3a9d..0000000000 Binary files a/static/img/digital-one-click.png and /dev/null differ diff --git a/static/img/digital-welcome.png b/static/img/digital-welcome.png deleted file mode 100644 index 9c7e90c759..0000000000 Binary files a/static/img/digital-welcome.png and /dev/null differ diff --git a/static/img/dns-fields.png b/static/img/dns-fields.png deleted file mode 100644 index 6f1c42c4bc..0000000000 Binary files a/static/img/dns-fields.png and /dev/null differ diff --git a/static/img/docs-homepage.png b/static/img/docs-homepage.png deleted file mode 100644 index 0f3f69fc20..0000000000 Binary files a/static/img/docs-homepage.png and /dev/null differ diff --git a/static/img/docusaurus.png b/static/img/docusaurus.png deleted file mode 100644 index f458149e3c..0000000000 Binary files a/static/img/docusaurus.png and /dev/null differ diff --git a/static/img/domain-test.png b/static/img/domain-test.png deleted file mode 100644 index 8b3f4d2b42..0000000000 Binary files a/static/img/domain-test.png and /dev/null differ diff --git a/static/img/droplet-control.png b/static/img/droplet-control.png deleted file mode 100644 index 9a672663d5..0000000000 Binary files a/static/img/droplet-control.png and /dev/null differ diff --git a/static/img/ec2-dashboard.png b/static/img/ec2-dashboard.png deleted file mode 100644 index e93bcfc8b3..0000000000 Binary files a/static/img/ec2-dashboard.png and /dev/null differ diff --git a/static/img/ec2-instance.png b/static/img/ec2-instance.png deleted file mode 100644 index eda346aafd..0000000000 Binary files a/static/img/ec2-instance.png and /dev/null differ diff --git a/static/img/ec2-instances.png b/static/img/ec2-instances.png deleted file mode 100644 index 09ee579f1f..0000000000 Binary files a/static/img/ec2-instances.png and /dev/null differ diff --git a/static/img/faucet-transfer.png b/static/img/faucet-transfer.png deleted file mode 100644 index a7348bef72..0000000000 Binary files a/static/img/faucet-transfer.png and /dev/null differ diff --git a/static/img/faucet.png b/static/img/faucet.png deleted file mode 100644 index 4a9e6f8791..0000000000 Binary files a/static/img/faucet.png and /dev/null differ diff --git a/static/img/favicon-dark.svg b/static/img/favicon-dark.svg deleted file mode 100755 index 8c9cce7be2..0000000000 --- a/static/img/favicon-dark.svg +++ /dev/null @@ -1,5 +0,0 @@ - - - \ No newline at end of file diff --git a/static/img/favicon-light.svg b/static/img/favicon-light.svg deleted file mode 100755 index 77955e5440..0000000000 --- a/static/img/favicon-light.svg +++ /dev/null @@ -1,5 +0,0 @@ - - - \ No newline at end of file diff --git a/static/img/favicon.ico b/static/img/favicon.ico deleted file mode 100644 index c01d54bcd3..0000000000 Binary files a/static/img/favicon.ico and /dev/null differ diff --git a/static/img/freenom-my-domains.png b/static/img/freenom-my-domains.png deleted file mode 100644 index c5fd2acff0..0000000000 Binary files a/static/img/freenom-my-domains.png and /dev/null differ diff --git a/static/img/gaia-community.png b/static/img/gaia-community.png deleted file mode 100644 index a2566675bb..0000000000 Binary files a/static/img/gaia-community.png and /dev/null differ diff --git a/static/img/gaia-storage.png b/static/img/gaia-storage.png deleted file mode 100644 index b7154424ee..0000000000 Binary files a/static/img/gaia-storage.png and /dev/null differ diff --git a/static/img/gaia-writes.png b/static/img/gaia-writes.png deleted file mode 100644 index 6cd92ac9e6..0000000000 Binary files a/static/img/gaia-writes.png and /dev/null differ diff --git a/static/img/gas-up-cb.gif b/static/img/gas-up-cb.gif deleted file mode 100644 index 1711d3c72f..0000000000 Binary files a/static/img/gas-up-cb.gif and /dev/null differ diff --git a/static/img/gears.svg b/static/img/gears.svg deleted file mode 100644 index 702fe6103f..0000000000 --- a/static/img/gears.svg +++ /dev/null @@ -1,17 +0,0 @@ - - - - - - - - - - - - - - - - - diff --git a/static/img/glasses.png b/static/img/glasses.png deleted file mode 100755 index 0c2c21f676..0000000000 Binary files a/static/img/glasses.png and /dev/null differ diff --git a/static/img/hardware-balance.png b/static/img/hardware-balance.png deleted file mode 100644 index 32d0985460..0000000000 Binary files a/static/img/hardware-balance.png and /dev/null differ diff --git a/static/img/hello-world-confirmed.png b/static/img/hello-world-confirmed.png deleted file mode 100644 index e9ac07d6b8..0000000000 Binary files a/static/img/hello-world-confirmed.png and /dev/null differ diff --git a/static/img/hello-world-sandbox-contract.png b/static/img/hello-world-sandbox-contract.png deleted file mode 100644 index 361b34f45b..0000000000 Binary files a/static/img/hello-world-sandbox-contract.png and /dev/null differ diff --git a/static/img/hello-world-testnet-sandbox.png b/static/img/hello-world-testnet-sandbox.png deleted file mode 100644 index 597458d63f..0000000000 Binary files a/static/img/hello-world-testnet-sandbox.png and /dev/null differ diff --git a/static/img/hello-world-transaction-summary.png b/static/img/hello-world-transaction-summary.png deleted file mode 100644 index bbbdc9a49c..0000000000 Binary files a/static/img/hello-world-transaction-summary.png and /dev/null differ diff --git a/static/img/hub-running.png b/static/img/hub-running.png deleted file mode 100644 index c2fef22de1..0000000000 Binary files a/static/img/hub-running.png and /dev/null differ diff --git a/static/img/icon_xverse.png b/static/img/icon_xverse.png deleted file mode 100644 index 605730be6a..0000000000 Binary files a/static/img/icon_xverse.png and /dev/null differ diff --git a/static/img/instance-initialize.png b/static/img/instance-initialize.png deleted file mode 100644 index 96522c3141..0000000000 Binary files a/static/img/instance-initialize.png and /dev/null differ diff --git a/static/img/key.png b/static/img/key.png deleted file mode 100644 index b467e0c7c5..0000000000 Binary files a/static/img/key.png and /dev/null differ diff --git a/static/img/keywords.jpg b/static/img/keywords.jpg deleted file mode 100755 index 18f50cc53b..0000000000 Binary files a/static/img/keywords.jpg and /dev/null differ diff --git a/static/img/logo.svg b/static/img/logo.svg deleted file mode 100644 index 9db6d0d066..0000000000 --- a/static/img/logo.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/static/img/mac-shasum.png b/static/img/mac-shasum.png deleted file mode 100644 index 1a5d1cf89b..0000000000 Binary files a/static/img/mac-shasum.png and /dev/null differ diff --git a/static/img/mac-terminal.png b/static/img/mac-terminal.png deleted file mode 100644 index a6dcff266f..0000000000 Binary files a/static/img/mac-terminal.png and /dev/null differ diff --git a/static/img/microblock-states.png b/static/img/microblock-states.png deleted file mode 100644 index f8a3b7af27..0000000000 Binary files a/static/img/microblock-states.png and /dev/null differ diff --git a/static/img/mining-windows-popup.png b/static/img/mining-windows-popup.png deleted file mode 100644 index 5452ca3ef7..0000000000 Binary files a/static/img/mining-windows-popup.png and /dev/null differ diff --git a/static/img/mining-windows.png b/static/img/mining-windows.png deleted file mode 100644 index ea2c6ec4b0..0000000000 Binary files a/static/img/mining-windows.png and /dev/null differ diff --git a/static/img/nocodeclarity.jpeg b/static/img/nocodeclarity.jpeg deleted file mode 100644 index 6b25282af1..0000000000 Binary files a/static/img/nocodeclarity.jpeg and /dev/null differ diff --git a/static/img/nodes.svg b/static/img/nodes.svg deleted file mode 100644 index 9990c138d5..0000000000 --- a/static/img/nodes.svg +++ /dev/null @@ -1,37 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/static/img/not-authenticated.png b/static/img/not-authenticated.png deleted file mode 100644 index 5e12535684..0000000000 Binary files a/static/img/not-authenticated.png and /dev/null differ diff --git a/static/img/not-enough.png b/static/img/not-enough.png deleted file mode 100644 index 9ce9fdf869..0000000000 Binary files a/static/img/not-enough.png and /dev/null differ diff --git a/static/img/og_image.png b/static/img/og_image.png deleted file mode 100644 index d83d1ad160..0000000000 Binary files a/static/img/og_image.png and /dev/null differ diff --git a/static/img/pages/angular-app-sm.svg b/static/img/pages/angular-app-sm.svg deleted file mode 100644 index 5b415a7b15..0000000000 --- a/static/img/pages/angular-app-sm.svg +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - - - - - - - - - - diff --git a/static/img/pages/authentication-sm.svg b/static/img/pages/authentication-sm.svg deleted file mode 100644 index d6cf77bacc..0000000000 --- a/static/img/pages/authentication-sm.svg +++ /dev/null @@ -1,10 +0,0 @@ - - - - - - - - - - diff --git a/static/img/pages/authentication.svg b/static/img/pages/authentication.svg deleted file mode 100644 index 116f820e21..0000000000 --- a/static/img/pages/authentication.svg +++ /dev/null @@ -1,5 +0,0 @@ - - - - - diff --git a/static/img/pages/billboard.svg b/static/img/pages/billboard.svg deleted file mode 100644 index f1d4e4a91c..0000000000 --- a/static/img/pages/billboard.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/static/img/pages/build-apps-sm.svg b/static/img/pages/build-apps-sm.svg deleted file mode 100644 index 9ad2c8c1ba..0000000000 --- a/static/img/pages/build-apps-sm.svg +++ /dev/null @@ -1,9 +0,0 @@ - - - - - - - - - diff --git a/static/img/pages/build-apps.svg b/static/img/pages/build-apps.svg deleted file mode 100644 index fcd62d1e72..0000000000 --- a/static/img/pages/build-apps.svg +++ /dev/null @@ -1,8 +0,0 @@ - - - - - - - - diff --git a/static/img/pages/coinbase-rewards.png b/static/img/pages/coinbase-rewards.png deleted file mode 100644 index 219f0577bf..0000000000 Binary files a/static/img/pages/coinbase-rewards.png and /dev/null differ diff --git a/static/img/pages/connect-sm.svg b/static/img/pages/connect-sm.svg deleted file mode 100644 index df65f00db4..0000000000 --- a/static/img/pages/connect-sm.svg +++ /dev/null @@ -1,7 +0,0 @@ - - - - - - - diff --git a/static/img/pages/connect.svg b/static/img/pages/connect.svg deleted file mode 100644 index a99463fdca..0000000000 --- a/static/img/pages/connect.svg +++ /dev/null @@ -1,12 +0,0 @@ - - - - - - - - - - - - diff --git a/static/img/pages/counter-tutorial-sm.svg b/static/img/pages/counter-tutorial-sm.svg deleted file mode 100644 index f80ed4f489..0000000000 --- a/static/img/pages/counter-tutorial-sm.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - - - - - - - - - - - diff --git a/static/img/pages/counter-tutorial.svg b/static/img/pages/counter-tutorial.svg deleted file mode 100644 index 4ee93e7c65..0000000000 --- a/static/img/pages/counter-tutorial.svg +++ /dev/null @@ -1,16 +0,0 @@ - - - - - - - - - - - - - - - - diff --git a/static/img/pages/data-storage-sm.svg b/static/img/pages/data-storage-sm.svg deleted file mode 100644 index 24f4f4a78b..0000000000 --- a/static/img/pages/data-storage-sm.svg +++ /dev/null @@ -1,12 +0,0 @@ - - - - - - - - - - - - diff --git a/static/img/pages/data-storage.svg b/static/img/pages/data-storage.svg deleted file mode 100644 index 320deaca9d..0000000000 --- a/static/img/pages/data-storage.svg +++ /dev/null @@ -1,6 +0,0 @@ - - - - - - diff --git a/static/img/pages/hello-world-sm.svg b/static/img/pages/hello-world-sm.svg deleted file mode 100644 index 315cea812b..0000000000 --- a/static/img/pages/hello-world-sm.svg +++ /dev/null @@ -1,13 +0,0 @@ - - - - - - - - - - - - - diff --git a/static/img/pages/hello-world.svg b/static/img/pages/hello-world.svg deleted file mode 100644 index b4e0691f63..0000000000 --- a/static/img/pages/hello-world.svg +++ /dev/null @@ -1,8 +0,0 @@ - - - - - - - - diff --git a/static/img/pages/heystack-app.svg b/static/img/pages/heystack-app.svg deleted file mode 100644 index 6b114f4a1f..0000000000 --- a/static/img/pages/heystack-app.svg +++ /dev/null @@ -1 +0,0 @@ - \ No newline at end of file diff --git a/static/img/pages/mainnet-sm.svg b/static/img/pages/mainnet-sm.svg deleted file mode 100644 index c8da860387..0000000000 --- a/static/img/pages/mainnet-sm.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - - - - background - - - - Layer 1 - - - - - - - \ No newline at end of file diff --git a/static/img/pages/mainnet.svg b/static/img/pages/mainnet.svg deleted file mode 100644 index 842f6e7514..0000000000 --- a/static/img/pages/mainnet.svg +++ /dev/null @@ -1,13 +0,0 @@ - - - - background - - - - Layer 1 - - - - - \ No newline at end of file diff --git a/static/img/pages/mining-with-pox.png b/static/img/pages/mining-with-pox.png deleted file mode 100644 index f5ff2f11ec..0000000000 Binary files a/static/img/pages/mining-with-pox.png and /dev/null differ diff --git a/static/img/pages/nft/btc-stx.png b/static/img/pages/nft/btc-stx.png deleted file mode 100644 index 3a38788d53..0000000000 Binary files a/static/img/pages/nft/btc-stx.png and /dev/null differ diff --git a/static/img/pages/nft/contract-interaction.png b/static/img/pages/nft/contract-interaction.png deleted file mode 100644 index f86ea32656..0000000000 Binary files a/static/img/pages/nft/contract-interaction.png and /dev/null differ diff --git a/static/img/pages/nft/contract-name.png b/static/img/pages/nft/contract-name.png deleted file mode 100644 index 9f72e9b6eb..0000000000 Binary files a/static/img/pages/nft/contract-name.png and /dev/null differ diff --git a/static/img/pages/nft/faucet.png b/static/img/pages/nft/faucet.png deleted file mode 100644 index c7e3d2f948..0000000000 Binary files a/static/img/pages/nft/faucet.png and /dev/null differ diff --git a/static/img/pages/nft/nft-claimed.png b/static/img/pages/nft/nft-claimed.png deleted file mode 100644 index 10a9741c9d..0000000000 Binary files a/static/img/pages/nft/nft-claimed.png and /dev/null differ diff --git a/static/img/pages/nft/nft-preview.png b/static/img/pages/nft/nft-preview.png deleted file mode 100644 index 310a7d654b..0000000000 Binary files a/static/img/pages/nft/nft-preview.png and /dev/null differ diff --git a/static/img/pages/nft/nft.png b/static/img/pages/nft/nft.png deleted file mode 100644 index 0116fc1dc4..0000000000 Binary files a/static/img/pages/nft/nft.png and /dev/null differ diff --git a/static/img/pages/nft/open-tab.png b/static/img/pages/nft/open-tab.png deleted file mode 100644 index 82fcd75076..0000000000 Binary files a/static/img/pages/nft/open-tab.png and /dev/null differ diff --git a/static/img/pages/nft/token.png b/static/img/pages/nft/token.png deleted file mode 100644 index 4e1c305de3..0000000000 Binary files a/static/img/pages/nft/token.png and /dev/null differ diff --git a/static/img/pages/nft/wallet.png b/static/img/pages/nft/wallet.png deleted file mode 100644 index 7a8d08129b..0000000000 Binary files a/static/img/pages/nft/wallet.png and /dev/null differ diff --git a/static/img/pages/radiks-sm.svg b/static/img/pages/radiks-sm.svg deleted file mode 100644 index 8dc6ec7e14..0000000000 --- a/static/img/pages/radiks-sm.svg +++ /dev/null @@ -1,13 +0,0 @@ - - - - - - - - - - - - - diff --git a/static/img/pages/radiks.svg b/static/img/pages/radiks.svg deleted file mode 100644 index 97c035cef8..0000000000 --- a/static/img/pages/radiks.svg +++ /dev/null @@ -1,8 +0,0 @@ - - - - - - - - diff --git a/static/img/pages/regtest-sm.svg b/static/img/pages/regtest-sm.svg deleted file mode 100644 index 3ad8d2be79..0000000000 --- a/static/img/pages/regtest-sm.svg +++ /dev/null @@ -1,10 +0,0 @@ - - - - - - - - - - diff --git a/static/img/pages/regtest.svg b/static/img/pages/regtest.svg deleted file mode 100644 index f19961f98e..0000000000 --- a/static/img/pages/regtest.svg +++ /dev/null @@ -1,5 +0,0 @@ - - - - - diff --git a/static/img/pages/stacking-rounded.svg b/static/img/pages/stacking-rounded.svg deleted file mode 100644 index 26f51420fa..0000000000 --- a/static/img/pages/stacking-rounded.svg +++ /dev/null @@ -1,23 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - diff --git a/static/img/pages/stacking.svg b/static/img/pages/stacking.svg deleted file mode 100644 index aeca8c4c50..0000000000 --- a/static/img/pages/stacking.svg +++ /dev/null @@ -1,23 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - diff --git a/static/img/pages/start-mining-sm.svg b/static/img/pages/start-mining-sm.svg deleted file mode 100644 index 0e714e724f..0000000000 --- a/static/img/pages/start-mining-sm.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - - - - - - - - - - - diff --git a/static/img/pages/start-mining.svg b/static/img/pages/start-mining.svg deleted file mode 100644 index 519e494ef5..0000000000 --- a/static/img/pages/start-mining.svg +++ /dev/null @@ -1,8 +0,0 @@ - - - - - - - - diff --git a/static/img/pages/testnet-sm.svg b/static/img/pages/testnet-sm.svg deleted file mode 100644 index 3ad8d2be79..0000000000 --- a/static/img/pages/testnet-sm.svg +++ /dev/null @@ -1,10 +0,0 @@ - - - - - - - - - - diff --git a/static/img/pages/testnet.svg b/static/img/pages/testnet.svg deleted file mode 100644 index f19961f98e..0000000000 --- a/static/img/pages/testnet.svg +++ /dev/null @@ -1,5 +0,0 @@ - - - - - diff --git a/static/img/pages/todo-app-sm.svg b/static/img/pages/todo-app-sm.svg deleted file mode 100644 index 566d6cd2ad..0000000000 --- a/static/img/pages/todo-app-sm.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - - - - - - - - - - - - - - - diff --git a/static/img/pages/todo-app.svg b/static/img/pages/todo-app.svg deleted file mode 100644 index 0a2d57c7ff..0000000000 --- a/static/img/pages/todo-app.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - - - - - - - - - - - - - - - diff --git a/static/img/pages/write-smart-contracts-sm.svg b/static/img/pages/write-smart-contracts-sm.svg deleted file mode 100644 index 3b91790305..0000000000 --- a/static/img/pages/write-smart-contracts-sm.svg +++ /dev/null @@ -1,24 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/static/img/pages/write-smart-contracts.svg b/static/img/pages/write-smart-contracts.svg deleted file mode 100644 index 7ef603e036..0000000000 --- a/static/img/pages/write-smart-contracts.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - - - - - - - - - - - diff --git a/static/img/pending.png b/static/img/pending.png deleted file mode 100644 index cb8a730ad6..0000000000 Binary files a/static/img/pending.png and /dev/null differ diff --git a/static/img/pox-cycles.png b/static/img/pox-cycles.png deleted file mode 100755 index 91763541aa..0000000000 Binary files a/static/img/pox-cycles.png and /dev/null differ diff --git a/static/img/pox-mechanism.png b/static/img/pox-mechanism.png deleted file mode 100755 index d3be7028d2..0000000000 Binary files a/static/img/pox-mechanism.png and /dev/null differ diff --git a/static/img/pox-mining-flow.png b/static/img/pox-mining-flow.png deleted file mode 100755 index 7991e909de..0000000000 Binary files a/static/img/pox-mining-flow.png and /dev/null differ diff --git a/static/img/pox-participants.png b/static/img/pox-participants.png deleted file mode 100755 index 3ca6a2e569..0000000000 Binary files a/static/img/pox-participants.png and /dev/null differ diff --git a/static/img/pox-unlocking-btc.png b/static/img/pox-unlocking-btc.png deleted file mode 100755 index f580db4c40..0000000000 Binary files a/static/img/pox-unlocking-btc.png and /dev/null differ diff --git a/static/img/pox-why-bitcoin.png b/static/img/pox-why-bitcoin.png deleted file mode 100755 index c84c99f3f3..0000000000 Binary files a/static/img/pox-why-bitcoin.png and /dev/null differ diff --git a/static/img/private-connection.png b/static/img/private-connection.png deleted file mode 100644 index b99dcbf2ed..0000000000 Binary files a/static/img/private-connection.png and /dev/null differ diff --git a/static/img/private.png b/static/img/private.png deleted file mode 100644 index 8131b4f596..0000000000 Binary files a/static/img/private.png and /dev/null differ diff --git a/static/img/proof-of-transfer.png b/static/img/proof-of-transfer.png deleted file mode 100644 index 5ed46a7d2c..0000000000 Binary files a/static/img/proof-of-transfer.png and /dev/null differ diff --git a/static/img/provider-prompt.png b/static/img/provider-prompt.png deleted file mode 100644 index 8556febfcf..0000000000 Binary files a/static/img/provider-prompt.png and /dev/null differ diff --git a/static/img/qr-code.png b/static/img/qr-code.png deleted file mode 100644 index 751971b0a2..0000000000 Binary files a/static/img/qr-code.png and /dev/null differ diff --git a/static/img/receive-button.png b/static/img/receive-button.png deleted file mode 100644 index bd32e5d5e8..0000000000 Binary files a/static/img/receive-button.png and /dev/null differ diff --git a/static/img/receive-details.png b/static/img/receive-details.png deleted file mode 100644 index 1777c6db24..0000000000 Binary files a/static/img/receive-details.png and /dev/null differ diff --git a/static/img/recommended-provider.png b/static/img/recommended-provider.png deleted file mode 100644 index 78bd4a529c..0000000000 Binary files a/static/img/recommended-provider.png and /dev/null differ diff --git a/static/img/registry.svg b/static/img/registry.svg deleted file mode 100644 index 9a2150c215..0000000000 --- a/static/img/registry.svg +++ /dev/null @@ -1,20 +0,0 @@ - - - - - - - - - - - - - - - - - - - - diff --git a/static/img/rust-install.png b/static/img/rust-install.png deleted file mode 100644 index 20fdafca12..0000000000 Binary files a/static/img/rust-install.png and /dev/null differ diff --git a/static/img/sandbox-call.png b/static/img/sandbox-call.png deleted file mode 100644 index 27dcc0c910..0000000000 Binary files a/static/img/sandbox-call.png and /dev/null differ diff --git a/static/img/sandbox-calltx.png b/static/img/sandbox-calltx.png deleted file mode 100644 index f00e41e2d7..0000000000 Binary files a/static/img/sandbox-calltx.png and /dev/null differ diff --git a/static/img/satoshi-btc.png b/static/img/satoshi-btc.png deleted file mode 100755 index a19fc8d428..0000000000 Binary files a/static/img/satoshi-btc.png and /dev/null differ diff --git a/static/img/sent.png b/static/img/sent.png deleted file mode 100644 index 3959d82153..0000000000 Binary files a/static/img/sent.png and /dev/null differ diff --git a/static/img/settings.png b/static/img/settings.png deleted file mode 100644 index 5f5c4171aa..0000000000 Binary files a/static/img/settings.png and /dev/null differ diff --git a/static/img/sh_alex.png b/static/img/sh_alex.png deleted file mode 100644 index 8ca99ef92d..0000000000 Binary files a/static/img/sh_alex.png and /dev/null differ diff --git a/static/img/sh_arkadiko.png b/static/img/sh_arkadiko.png deleted file mode 100644 index 7ec8dd2144..0000000000 Binary files a/static/img/sh_arkadiko.png and /dev/null differ diff --git a/static/img/sh_blockchain.png b/static/img/sh_blockchain.png deleted file mode 100644 index dce6671f3c..0000000000 Binary files a/static/img/sh_blockchain.png and /dev/null differ diff --git a/static/img/sh_boom.png b/static/img/sh_boom.png deleted file mode 100644 index 64dbe740fb..0000000000 Binary files a/static/img/sh_boom.png and /dev/null differ diff --git a/static/img/sh_catamaran.png b/static/img/sh_catamaran.png deleted file mode 100644 index 6a7be37f39..0000000000 Binary files a/static/img/sh_catamaran.png and /dev/null differ diff --git a/static/img/sh_citycoins.png b/static/img/sh_citycoins.png deleted file mode 100644 index b7343e7547..0000000000 Binary files a/static/img/sh_citycoins.png and /dev/null differ diff --git a/static/img/sh_dcent.png b/static/img/sh_dcent.png deleted file mode 100644 index 0b88509dd8..0000000000 Binary files a/static/img/sh_dcent.png and /dev/null differ diff --git a/static/img/sh_digitalocean-choose-authentication.png b/static/img/sh_digitalocean-choose-authentication.png deleted file mode 100644 index 433ef64486..0000000000 Binary files a/static/img/sh_digitalocean-choose-authentication.png and /dev/null differ diff --git a/static/img/sh_digitalocean-choose-plan.png b/static/img/sh_digitalocean-choose-plan.png deleted file mode 100644 index e2f2a337ed..0000000000 Binary files a/static/img/sh_digitalocean-choose-plan.png and /dev/null differ diff --git a/static/img/sh_digitalocean-console-button.png b/static/img/sh_digitalocean-console-button.png deleted file mode 100644 index 7cdd07576f..0000000000 Binary files a/static/img/sh_digitalocean-console-button.png and /dev/null differ diff --git a/static/img/sh_digitalocean-console.png b/static/img/sh_digitalocean-console.png deleted file mode 100644 index 6fd2821fcd..0000000000 Binary files a/static/img/sh_digitalocean-console.png and /dev/null differ diff --git a/static/img/sh_digitalocean-created-droplet.png b/static/img/sh_digitalocean-created-droplet.png deleted file mode 100644 index 83e0f30b4d..0000000000 Binary files a/static/img/sh_digitalocean-created-droplet.png and /dev/null differ diff --git a/static/img/sh_digitalocean-creating-droplet.png b/static/img/sh_digitalocean-creating-droplet.png deleted file mode 100644 index 963a23b3e2..0000000000 Binary files a/static/img/sh_digitalocean-creating-droplet.png and /dev/null differ diff --git a/static/img/sh_digitalocean-marketplace.png b/static/img/sh_digitalocean-marketplace.png deleted file mode 100644 index 4406f97d17..0000000000 Binary files a/static/img/sh_digitalocean-marketplace.png and /dev/null differ diff --git a/static/img/sh_haystacks.png b/static/img/sh_haystacks.png deleted file mode 100644 index c930cbdbad..0000000000 Binary files a/static/img/sh_haystacks.png and /dev/null differ diff --git a/static/img/sh_hirowallet.png b/static/img/sh_hirowallet.png deleted file mode 100644 index 3863bccca2..0000000000 Binary files a/static/img/sh_hirowallet.png and /dev/null differ diff --git a/static/img/sh_lnswap.png b/static/img/sh_lnswap.png deleted file mode 100644 index d8e1a997f4..0000000000 Binary files a/static/img/sh_lnswap.png and /dev/null differ diff --git a/static/img/sh_neoswap.png b/static/img/sh_neoswap.png deleted file mode 100644 index 334d590845..0000000000 Binary files a/static/img/sh_neoswap.png and /dev/null differ diff --git a/static/img/sh_neptunewallet.png b/static/img/sh_neptunewallet.png deleted file mode 100644 index fb92d19467..0000000000 Binary files a/static/img/sh_neptunewallet.png and /dev/null differ diff --git a/static/img/sh_nft_byzantion.png b/static/img/sh_nft_byzantion.png deleted file mode 100644 index 44c0b577a7..0000000000 Binary files a/static/img/sh_nft_byzantion.png and /dev/null differ diff --git a/static/img/sh_nft_gamma.png b/static/img/sh_nft_gamma.png deleted file mode 100644 index d7ae25e5ba..0000000000 Binary files a/static/img/sh_nft_gamma.png and /dev/null differ diff --git a/static/img/sh_nft_megapont.png b/static/img/sh_nft_megapont.png deleted file mode 100644 index e6be30f552..0000000000 Binary files a/static/img/sh_nft_megapont.png and /dev/null differ diff --git a/static/img/sh_nft_satoshibles.png b/static/img/sh_nft_satoshibles.png deleted file mode 100644 index b887152627..0000000000 Binary files a/static/img/sh_nft_satoshibles.png and /dev/null differ diff --git a/static/img/sh_nft_stacksart.png b/static/img/sh_nft_stacksart.png deleted file mode 100644 index 6674c3de68..0000000000 Binary files a/static/img/sh_nft_stacksart.png and /dev/null differ diff --git a/static/img/sh_nft_stacksbridge.png b/static/img/sh_nft_stacksbridge.png deleted file mode 100644 index dc819c6514..0000000000 Binary files a/static/img/sh_nft_stacksbridge.png and /dev/null differ diff --git a/static/img/sh_novuminsights.png b/static/img/sh_novuminsights.png deleted file mode 100644 index b1c0aae7cc..0000000000 Binary files a/static/img/sh_novuminsights.png and /dev/null differ diff --git a/static/img/sh_onstacks.png b/static/img/sh_onstacks.png deleted file mode 100644 index 0966564453..0000000000 Binary files a/static/img/sh_onstacks.png and /dev/null differ diff --git a/static/img/sh_sigle.png b/static/img/sh_sigle.png deleted file mode 100644 index 86440da93e..0000000000 Binary files a/static/img/sh_sigle.png and /dev/null differ diff --git a/static/img/sh_stacksdata.png b/static/img/sh_stacksdata.png deleted file mode 100644 index 1b40b32114..0000000000 Binary files a/static/img/sh_stacksdata.png and /dev/null differ diff --git a/static/img/sh_stacksonchain.png b/static/img/sh_stacksonchain.png deleted file mode 100644 index 2760d43892..0000000000 Binary files a/static/img/sh_stacksonchain.png and /dev/null differ diff --git a/static/img/sh_stackswap.png b/static/img/sh_stackswap.png deleted file mode 100644 index f01d939983..0000000000 Binary files a/static/img/sh_stackswap.png and /dev/null differ diff --git a/static/img/sh_statushiro.png b/static/img/sh_statushiro.png deleted file mode 100644 index ade2e3dda5..0000000000 Binary files a/static/img/sh_statushiro.png and /dev/null differ diff --git a/static/img/sh_stxstats.png b/static/img/sh_stxstats.png deleted file mode 100644 index 3500ba0021..0000000000 Binary files a/static/img/sh_stxstats.png and /dev/null differ diff --git a/static/img/sh_superfandom.png b/static/img/sh_superfandom.png deleted file mode 100644 index b2d7a41dc3..0000000000 Binary files a/static/img/sh_superfandom.png and /dev/null differ diff --git a/static/img/sh_wiseapp.png b/static/img/sh_wiseapp.png deleted file mode 100644 index 829d2375b5..0000000000 Binary files a/static/img/sh_wiseapp.png and /dev/null differ diff --git a/static/img/sh_xverse.png b/static/img/sh_xverse.png deleted file mode 100644 index cef9e77e81..0000000000 Binary files a/static/img/sh_xverse.png and /dev/null differ diff --git a/static/img/sign-in.png b/static/img/sign-in.png deleted file mode 100644 index 7d4f5a6018..0000000000 Binary files a/static/img/sign-in.png and /dev/null differ diff --git a/static/img/space-access-key.png b/static/img/space-access-key.png deleted file mode 100644 index 5dc57c9e81..0000000000 Binary files a/static/img/space-access-key.png and /dev/null differ diff --git a/static/img/space-endpoint.png b/static/img/space-endpoint.png deleted file mode 100644 index 7fb0b03041..0000000000 Binary files a/static/img/space-endpoint.png and /dev/null differ diff --git a/static/img/stacking-delegation-illustration.png b/static/img/stacking-delegation-illustration.png deleted file mode 100755 index 54f2055b2e..0000000000 Binary files a/static/img/stacking-delegation-illustration.png and /dev/null differ diff --git a/static/img/stacking-dynamic-minimum.png b/static/img/stacking-dynamic-minimum.png deleted file mode 100755 index 46f866fb95..0000000000 Binary files a/static/img/stacking-dynamic-minimum.png and /dev/null differ diff --git a/static/img/stacking-illustration.png b/static/img/stacking-illustration.png deleted file mode 100755 index 058f4fbc04..0000000000 Binary files a/static/img/stacking-illustration.png and /dev/null differ diff --git a/static/img/stacking.png b/static/img/stacking.png deleted file mode 100644 index 2515e23ade..0000000000 Binary files a/static/img/stacking.png and /dev/null differ diff --git a/static/img/stacking.svg b/static/img/stacking.svg deleted file mode 100644 index 97c8c8b18d..0000000000 --- a/static/img/stacking.svg +++ /dev/null @@ -1,18 +0,0 @@ - - - - - - - - - - - - - - - - - - diff --git a/static/img/stacks-governance.png b/static/img/stacks-governance.png deleted file mode 100644 index d12f093fd8..0000000000 Binary files a/static/img/stacks-governance.png and /dev/null differ diff --git a/static/img/stacks_with_interior_white_exterior_transparent.png b/static/img/stacks_with_interior_white_exterior_transparent.png deleted file mode 100644 index dc714937c3..0000000000 Binary files a/static/img/stacks_with_interior_white_exterior_transparent.png and /dev/null differ diff --git a/static/img/stx-microblocks.png b/static/img/stx-microblocks.png deleted file mode 100644 index a152742605..0000000000 Binary files a/static/img/stx-microblocks.png and /dev/null differ diff --git a/static/img/stx_faucet.png b/static/img/stx_faucet.png deleted file mode 100644 index 37a546dec0..0000000000 Binary files a/static/img/stx_faucet.png and /dev/null differ diff --git a/static/img/tag-add.png b/static/img/tag-add.png deleted file mode 100644 index c27ff77949..0000000000 Binary files a/static/img/tag-add.png and /dev/null differ diff --git a/static/img/test-contact.png b/static/img/test-contact.png deleted file mode 100644 index 75cb01f197..0000000000 Binary files a/static/img/test-contact.png and /dev/null differ diff --git a/static/img/tier-2-image.png b/static/img/tier-2-image.png deleted file mode 100644 index 162e03e078..0000000000 Binary files a/static/img/tier-2-image.png and /dev/null differ diff --git a/static/img/todos-public-registry.png b/static/img/todos-public-registry.png deleted file mode 100644 index a65dc4c9d0..0000000000 Binary files a/static/img/todos-public-registry.png and /dev/null differ diff --git a/static/img/todos-recent-activities-json.png b/static/img/todos-recent-activities-json.png deleted file mode 100644 index 6c12fc7148..0000000000 Binary files a/static/img/todos-recent-activities-json.png and /dev/null differ diff --git a/static/img/todos-recent-activities.png b/static/img/todos-recent-activities.png deleted file mode 100644 index ba748fc674..0000000000 Binary files a/static/img/todos-recent-activities.png and /dev/null differ diff --git a/static/img/todos-register-on-chain.png b/static/img/todos-register-on-chain.png deleted file mode 100644 index c2dfda9392..0000000000 Binary files a/static/img/todos-register-on-chain.png and /dev/null differ diff --git a/static/img/todos/choose-account.png b/static/img/todos/choose-account.png deleted file mode 100644 index 64b1ec18b5..0000000000 Binary files a/static/img/todos/choose-account.png and /dev/null differ diff --git a/static/img/todos/choose-username.png b/static/img/todos/choose-username.png deleted file mode 100644 index d84c686d33..0000000000 Binary files a/static/img/todos/choose-username.png and /dev/null differ diff --git a/static/img/todos/copy-secret-key.png b/static/img/todos/copy-secret-key.png deleted file mode 100644 index ae89e6292d..0000000000 Binary files a/static/img/todos/copy-secret-key.png and /dev/null differ diff --git a/static/img/todos/get-started.png b/static/img/todos/get-started.png deleted file mode 100644 index 93dee35513..0000000000 Binary files a/static/img/todos/get-started.png and /dev/null differ diff --git a/static/img/todos/home-public.png b/static/img/todos/home-public.png deleted file mode 100644 index 9fbdd2a438..0000000000 Binary files a/static/img/todos/home-public.png and /dev/null differ diff --git a/static/img/todos/home.png b/static/img/todos/home.png deleted file mode 100644 index 3002201485..0000000000 Binary files a/static/img/todos/home.png and /dev/null differ diff --git a/static/img/todos/landing.png b/static/img/todos/landing.png deleted file mode 100644 index 24cb0f39c5..0000000000 Binary files a/static/img/todos/landing.png and /dev/null differ diff --git a/static/img/todos/saved-secret-key.png b/static/img/todos/saved-secret-key.png deleted file mode 100644 index 1beefe6b2a..0000000000 Binary files a/static/img/todos/saved-secret-key.png and /dev/null differ diff --git a/static/img/todos/secret-key-generation.png b/static/img/todos/secret-key-generation.png deleted file mode 100644 index ba5f529c39..0000000000 Binary files a/static/img/todos/secret-key-generation.png and /dev/null differ diff --git a/static/img/todos/sign-in.png b/static/img/todos/sign-in.png deleted file mode 100644 index fb40fdaa0d..0000000000 Binary files a/static/img/todos/sign-in.png and /dev/null differ diff --git a/static/img/token-holder-balance.png b/static/img/token-holder-balance.png deleted file mode 100644 index 4ec88db91e..0000000000 Binary files a/static/img/token-holder-balance.png and /dev/null differ diff --git a/static/img/top-up.png b/static/img/top-up.png deleted file mode 100644 index a7b3102607..0000000000 Binary files a/static/img/top-up.png and /dev/null differ diff --git a/static/img/transaction-signing.svg b/static/img/transaction-signing.svg deleted file mode 100644 index 4b80ed0e91..0000000000 --- a/static/img/transaction-signing.svg +++ /dev/null @@ -1,22 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - diff --git a/static/img/trezor-export.png b/static/img/trezor-export.png deleted file mode 100644 index 307675b47b..0000000000 Binary files a/static/img/trezor-export.png and /dev/null differ diff --git a/static/img/tx-lifecycle.png b/static/img/tx-lifecycle.png deleted file mode 100644 index 977c684143..0000000000 Binary files a/static/img/tx-lifecycle.png and /dev/null differ diff --git a/static/img/undraw_docusaurus_mountain.svg b/static/img/undraw_docusaurus_mountain.svg deleted file mode 100644 index af961c49a8..0000000000 --- a/static/img/undraw_docusaurus_mountain.svg +++ /dev/null @@ -1,171 +0,0 @@ - - Easy to Use - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/static/img/undraw_docusaurus_react.svg b/static/img/undraw_docusaurus_react.svg deleted file mode 100644 index 94b5cf08f8..0000000000 --- a/static/img/undraw_docusaurus_react.svg +++ /dev/null @@ -1,170 +0,0 @@ - - Powered by React - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/static/img/undraw_docusaurus_tree.svg b/static/img/undraw_docusaurus_tree.svg deleted file mode 100644 index d9161d3392..0000000000 --- a/static/img/undraw_docusaurus_tree.svg +++ /dev/null @@ -1,40 +0,0 @@ - - Focus on What Matters - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/static/img/unlocking-address.png b/static/img/unlocking-address.png deleted file mode 100644 index bb50e01228..0000000000 Binary files a/static/img/unlocking-address.png and /dev/null differ diff --git a/static/img/unlocking.png b/static/img/unlocking.png deleted file mode 100644 index 718e838538..0000000000 Binary files a/static/img/unlocking.png and /dev/null differ diff --git a/static/img/us-west-2.png b/static/img/us-west-2.png deleted file mode 100644 index 205f1e971e..0000000000 Binary files a/static/img/us-west-2.png and /dev/null differ diff --git a/static/img/windows-certutil.png b/static/img/windows-certutil.png deleted file mode 100644 index f0140d2cef..0000000000 Binary files a/static/img/windows-certutil.png and /dev/null differ diff --git a/static/img/windows-cmd.png b/static/img/windows-cmd.png deleted file mode 100644 index 8352b94db5..0000000000 Binary files a/static/img/windows-cmd.png and /dev/null differ diff --git a/static/img/windows-defender.png b/static/img/windows-defender.png deleted file mode 100644 index fd7acc724a..0000000000 Binary files a/static/img/windows-defender.png and /dev/null differ diff --git a/static/img/xbtc-icon.webp b/static/img/xbtc-icon.webp deleted file mode 100644 index 65691ed358..0000000000 Binary files a/static/img/xbtc-icon.webp and /dev/null differ